iptvnator/docs/architecture/workspace-shell.md

Workspace Shell

This document records the current workspace-first shell contract. It is the stable replacement for the older UI refactor summary.

Related:

• Workspace Dashboard

Summary

• /workspace is the primary app surface.
• WorkspaceShellComponent owns the persistent frame: rail, header, optional context panel, content outlet, and external playback footer.
• Descendant workspace pages inherit layout = 'workspace' from the /workspace root route.
• Provider route trees now bootstrap through route-scoped session providers instead of nested provider shell components.

Core implementation:

1. apps/web/src/app/app.routes.ts
2. libs/workspace/shell/feature/src/lib/workspace-shell/workspace-shell.component.ts
3. libs/workspace/shell/feature/src/lib/workspace-shell/workspace-shell.component.html
4. libs/workspace/shell/feature/src/lib/workspace-shell/services/workspace-shell.facade.ts
5. libs/workspace/shell/feature/src/lib/workspace-shell/services/workspace-shell-route-state.service.ts
6. libs/workspace/shell/feature/src/lib/workspace-shell/services/workspace-shell-search.service.ts
7. libs/workspace/shell/feature/src/lib/workspace-shell/services/workspace-shell-search-sync.service.ts
8. libs/workspace/shell/feature/src/lib/workspace-shell/services/workspace-shell-header.service.ts
9. libs/workspace/shell/feature/src/lib/workspace-shell/services/workspace-shell-command-palette.service.ts
10. libs/workspace/shell/feature/src/lib/workspace-shell/services/workspace-shell-xtream-import.service.ts
11. libs/portal/shared/util/src/lib/navigation/portal-route.utils.ts
12. libs/portal/shared/util/src/lib/navigation/portal-rail-links.ts
13. libs/portal/shared/ui/src/lib/navigation/portal-rail-links.component.ts

Route Contract

Current workspace routes:

1. / -> /workspace
2. /workspace -> functional redirect workspaceEntryRedirect (WorkspaceStartupPreferencesService.resolveInitialWorkspacePath(); /workspace/dashboard by default, /workspace/sources when the dashboard is disabled, or the last restorable route under StartupBehavior.RestoreLastView — dashboard itself is guarded by dashboardAccessGuard)
3. /workspace/dashboard
4. /workspace/sources
5. /workspace/playlists/:id/:view (plus favorites and recent siblings)
6. /workspace/global-favorites
7. /workspace/global-recent
8. /workspace/search
9. /workspace/downloads
10. /workspace/settings/:section (/workspace/settings redirects to general; the settings context panel links each section page)
11. /workspace/xtreams/:id/...
12. /workspace/stalker/:id/...

Compatibility redirect:

1. /settings -> /workspace/settings

Provider route integration:

1. apps/web/src/app/app.routes.ts marks the /workspace root route with data.layout = 'workspace'.
2. isWorkspaceLayoutRoute(...) treats that layout marker as inherited route state for all descendants.
3. Xtream and Stalker parent routes attach route-scoped session providers that bootstrap the active playlist, sync provider section state, and clean up provider-local state when the route is destroyed.
4. Xtream route bootstrap is DB-first for already imported Electron playlists: if the requested section has persisted categories and content, the route hydrates from SQLite even when the portal status probe reports unavailable, expired, or inactive. Fresh/no-cache Xtream routes still use the status probe to block remote imports before the loading overlay starts.
5. Workspace routes no longer rely on nested provider shell components for hidden local chrome.

Shell Structure

The shell is intentionally split into four persistent regions:

1. Left rail:
   1. Static workspace links for dashboard, sources, global favorites, and recently viewed. The routed global-search rail link is Electron-only because its data source is the SQLite worker bridge.
   2. Provider-aware context links derived from the active or current playlist.
   3. Settings remains a persistent footer shortcut in the rail.
2. Top header:
   1. Playlist switcher.
   2. Route-aware search input and command palette trigger.
   3. Add source action.
   4. Optional playlist refresh and route-specific shortcut actions.
   5. Downloads shortcut in Electron.
3. Main body:
   1. Optional left context panel.
   2. Main router outlet content.
4. Optional footer:
   1. External playback session bar when a docked session is visible.

WorkspaceShellComponent binds only to WorkspaceShellFacade. The facade is kept as a thin template-facing API and delegates ownership to component-scoped services:

1. WorkspaceShellRouteStateService owns current route parsing, rail links, context-panel state, dashboard startup preference, and playlist source signals.
2. WorkspaceShellSearchService owns the route-aware header search capability and public search actions.
3. WorkspaceShellSearchSyncService owns the search query signals, debounced application, provider-store synchronization, and query-param sync.
4. WorkspaceShellHeaderService owns playlist title/subtitle, account/info actions, refresh action state, and recent-items bulk cleanup.
5. WorkspaceShellCommandPaletteService owns command-palette dialog lifecycle and recent-command recording.
6. WorkspaceShellXtreamImportService owns Xtream import/refresh overlay state and labels.

When adding shell behavior, prefer placing it in the service that owns the nearest existing state. Keep WorkspaceShellFacade as a stable re-export layer for the template unless the template contract itself intentionally changes.

Context Panel Rules

The shell decides which secondary panel to show from the current route:

1. /workspace/sources
   1. WorkspaceSourcesFiltersPanelComponent
2. Xtream category sections (live, vod, series)
   1. WorkspaceContextPanelComponent
3. Stalker category sections (itv, radio, vod, series)
   1. WorkspaceContextPanelComponent
4. /workspace/settings/:section
   1. WorkspaceSettingsContextPanelComponent
5. Downloads sections
   1. WorkspaceCollectionContextPanelComponent

The context panel is part of the shell contract. New workspace-level routes should explicitly decide whether they need one rather than adding local sidebars inside feature pages.

Xtream and Stalker category panels preserve provider/server category order by default. The panel header exposes a sort menu next to category search with Server sorting, A-Z, and Z-A; when alphabetical sorting is active, synthetic "all categories" entries stay pinned before sorted provider categories.

On live sections the category panel can be folded away independently of the channels list; the folded panel is reachable as a popover from the channels header through the LIVE_CATEGORIES_POPOVER token the shell provides. The three nested levels, their affordances and persistence are specified in iptvnator-ui-guidelines.md ("Collapsible Live Sidebar").

A category click in a LIVE section (Xtream live, Stalker itv and radio) changes only the selected category: the live layouts gate their player on the store's selected item, so the handler must not clear it — the channel the user is watching keeps playing while the sidebar re-filters (Xtream: #936; Stalker: onStalkerCategoryClicked returns before clearSelectedItem()). VOD and series category clicks do drop the open detail (setSelectedItem(null) / clearSelectedItem()) because they navigate to a list route.

The channel header offers Show playing channel when browsing excludes the active channel. It returns to that category and focuses the row without restarting playback; remote commands retain captured playback order. See the queue and reveal contract.

Search And Navigation Rules

Search is shell-owned and route-aware:

1. Disabled on settings routes.
2. Enabled on sources routes.
3. Enabled for /workspace/search, which is the Electron-only routed global-search view. Ctrl/Cmd+F in Electron opens this route and focuses/selects the header search input instead of opening a fullscreen dialog.
4. Enabled for supported Xtream and Stalker content/search views.
5. Placeholder text and search handling vary by provider and section.
6. Input changes are debounced before route/store updates are applied.
7. Global search uses the header input as its primary input and writes the search phrase to the q query parameter, so history/back-forward behavior matches the rest of the workspace.
8. The URL is authoritative for the search box only when it carries search intent. WorkspaceShellSearchSyncService re-reads q on every NavigationEnd, but an app-initiated navigation that stays on the same page and carries the term already applied is always ignored — whether or not a debounce is still pending. Otherwise a page writing an unrelated query param (a downloads filter chip, a refresh bump) or the router echoing back our own trimmed q would reset the box to the applied term, eating everything typed since: the whole word while the first keystroke is still debouncing, or a just-typed trailing space once the debounce has fired ("Bein " would snap to "Bein" and typing on would yield "BeinSports"). Applied terms are always stored trimmed (applySearchQuery and setSearchState both trim), so the echoed q compares directly; the box keeps exactly what the user typed. Pages are free to write their own query params while the user types; they must not assume the shell will re-apply the search afterwards.
9. Browser history overrides that guard. The exemption is keyed on Navigation.trigger === 'imperative', so back/forward always re-applies what the history entry carries, even mid-typing.
10. Applying a term explicitly supersedes a queued one. applySearchQuery() cancels any pending debounce, so the Enter key committing a trimmed term cannot be overwritten a moment later by the untrimmed keystroke still waiting behind it.

Rail navigation is also shell-owned:

1. Workspace-global entries are static.
2. Provider entries come from buildPortalRailLinks(...).
3. On dashboard, sources, settings, global search, global favorites, and global recent, the shell falls back to the currently selected playlist so provider navigation remains available even outside a provider route.

Command palette behavior is shell-owned but view-extensible:

1. The shell resolves commands into three groups in fixed order: current view, this playlist, then global.
2. Shell-owned commands are derived from route context and current playlist state; empty groups are omitted instead of rendering disabled placeholders.
3. Workspace features contribute current-view commands through WorkspaceViewCommandService.
4. Header shortcut actions can opt into palette exposure by attaching palette metadata through WorkspaceHeaderContextService.
5. Filtering matches command labels, descriptions, and keywords, and keyboard selection always lands on the first enabled command.
6. A "Recently used" section is rendered above the standard groups when the query is empty and at least one stored id resolves to a visible+enabled command; ids are persisted via RecentCommandsService (capped at 5, stored at STORE_KEY.RecentCommands). Storage is not pruned by route visibility — a navigation command like Open sources is invisible while the user is on /workspace/sources but the id stays in storage so it reappears in the recent section after navigating away.
7. Six "Switch player to X" commands are registered globally by WorkspacePlayerCommandsContributor (VideoJS, HTML5, ArtPlayer, Embedded MPV, MPV, VLC). Each command carries a requires flag gating its visibility: the MPV/VLC ("managed-external") entries are visible only when RuntimeCapabilitiesService.supportsManagedExternalPlayers is true, and the Embedded MPV ("embedded-mpv") entry is visible only after the command palette lazily preloads an async window.electron.getEmbeddedMpvSupport() check and it resolves to supported (mirroring the Settings dropdown gate). Do not run this Embedded MPV support check from workspace shell bootstrap: supported desktop builds may load the native addon while resolving capabilities. The entry matching the current SettingsStore.player() value is disabled. The new player setting applies to the next playback session; an existing stream is not re-mounted.

Keyboard shortcut help is shell-owned:

1. WorkspaceKeyboardShortcutsService is provided by WorkspaceShellComponent. It owns the workspace-scoped document:keydown listener for ? / Shift+/.
2. The listener ignores events from inputs, textareas, selects, and content-editable elements via isTypingInInput(...).
3. libs/portal/shared/util/src/lib/keyboard-shortcut-definitions.ts is the metadata registry for shortcuts shown in the help dialog and documented in README. keyboard-shortcuts.ts owns the display transformation and help trigger detection. Shortcuts that only work through the Electron bridge, such as embedded MPV controls, must set electronOnly: true so the PWA dialog does not advertise unavailable commands.
4. New custom shortcuts should be added to that registry when the handler is added. Do not include native browser/editor behavior such as Tab or platform text editing shortcuts.

Window Chrome And Custom Title Bar

The Electron window hides the native title bar on all desktop platforms (titleBarStyle: 'hidden' in apps/electron-backend/src/app/app.ts):

1. macOS keeps the native traffic lights (titleBarOverlay: true, trafficLightPosition); the renderer draws no window buttons.
2. Windows and Linux use renderer-drawn window controls (app-window-controls, libs/ui/components/src/lib/window-controls/). frame is intentionally left untouched so native resize borders and window snapping keep working.

The controls are mounted once in app-root (not inside the workspace header) as a position: fixed top-right overlay so they stay clickable above full-window content such as Material dialog backdrops — the same behavior as the macOS traffic lights. Because CDK overlays render as popovers in the browser top layer (above any z-index), the component host is itself a popover="manual" element: it enters the top layer on init and re-enters it (hide + show) whenever another popover opens, so the controls always paint last. The z-index: 10000 remains only as a fallback when the popover API is unavailable. They render only when RuntimeCapabilitiesService.usesCustomWindowControls is true (Windows/Linux Electron with the window-control bridge methods available); the PWA and macOS never mount them.

IPC contract (constants in libs/shared/interfaces/src/lib/ipc-commands.ts, handlers in apps/electron-backend/src/app/events/window.events.ts):

1. WINDOW:MINIMIZE, WINDOW:TOGGLE_MAXIMIZE, WINDOW:CLOSE, WINDOW:GET_STATE are ipcMain.handle channels resolved from the sender WebContents. Close goes through win.close() so the existing window-bounds persistence in app.ts still runs.

2. WINDOW:STATE_CHANGED is pushed main → renderer on maximize/unmaximize and on the fullscreen events — enter/leave-full-screen plus the enter/leave-html-full-screen variants emitted for HTML-element fullscreen (video player fullscreen) — so the maximize/restore glyph stays correct for externally triggered changes (double-click on a drag region, OS snap, F11). The controls hide themselves while the window is fullscreen.

   Window state is never re-read at event time. attachWindowStateEvents seeds { isMaximized, isFullScreen } once at window creation and each event patches only the flag it names; every push carries a copy of that tracked state. On Windows both getters can still report the pre-transition value while the matching event fires — isFullScreen() stays true during an HTML fullscreen exit, and isMaximized() reads false while the window is fullscreen. Because the renderer replaces both flags on every push and no later event corrects a stale one, polling left the controls hidden forever after leaving fullscreen and stuck the maximize/restore glyph on the wrong icon. Regression coverage: app-window-state.spec.ts and window-controls.e2e.ts.

   The pushed isFullScreen is the OR of two flags tracked apart: native (OS-level, fed by enter/leave-full-screen) and HTML-element (fed by the *-html-* pair). Electron remembers when the window was already natively fullscreen before the player entered HTML fullscreen and then leaves ONLY the HTML state on exit — no leave-full-screen fires and the window stays fullscreen — so a single flag cleared by leave-html-full-screen would un-hide the controls over a window that is still fullscreen. A fullscreen launch (below) or F11 followed by the player's F → Esc makes that path routine on Windows/Linux.

3. WINDOW:TOGGLE_FULLSCREEN toggles OS-level fullscreen (setFullScreen) and, like the maximize toggle, reports the requested state and leaves the WINDOW:STATE_CHANGED push authoritative. Because the transition is asynchronous — isFullScreen() reports the old value until it lands, and on Windows even while the matching event fires — a toggle must never be decided against the getter. Every native fullscreen request goes through the tracker in apps/electron-backend/src/app/services/native-fullscreen-transitions.ts (the F11 toggle AND the startup fallback below). Like the state pushes above it keeps its own per-window fullscreen state, seeded from the getter once at window creation (trackNativeFullScreen in initMainWindow, while no transition can be in flight) and fed afterwards only by the enter/leave-full-screen events, which also cover transitions the app did not request. A toggle is decided against the pending target while a transition is in flight, else against that tracked state: two quick presses are an enter-then-exit, not two enters, and F11 during the startup animation leaves fullscreen instead of asking for it again. The tracker observes and never issues a request on its own. The pending record is the LATEST requested target: an event landing on it clears it, an event landing on the other state (an earlier request of a burst landed first; ours is still queued) leaves it in place so the next press still follows the user's latest intent, and a record older than FULLSCREEN_TRANSITION_TIMEOUT_MS (2 s) is ignored. Events cannot say which request they belong to, so any automatic "repeat the target" on a mismatch is indistinguishable from reversing the user's own green-button/Ctrl+Cmd+F action and is deliberately not done: should a platform ever drop a queued request (Electron queues them on macOS and applies them synchronously elsewhere), the record expires, the event-fed state takes over and the next press corrects the window. The renderer binds it to F11 in WorkspaceKeyboardShortcutsService (deliberately not gated by isTypingInInput — it must work from any focus, because it is the only exit from a fullscreen launch on Windows/Linux, where the title bar is hidden and the controls hide themselves) and skips the key while document.fullscreenElement is set, since the player's own F / Esc own HTML fullscreen and F11 must not yank OS fullscreen out from under it. Without a bridge (PWA) F11 is left to the browser.

Startup window mode (Settings.startupWindowMode, issue #1455):

1. normal (default) / maximized / fullscreen, chosen in Settings → General ("Window on startup"). Electron only — the select renders only when RuntimeCapabilitiesService.supportsStartupWindowMode sees both updateSettings and toggleFullScreenWindow on the bridge, so the mode is never offered without its F11 exit.
2. Settings live in the renderer's IndexedDB, which the main process cannot read at window creation, so the SETTINGS_UPDATE handler mirrors the value into electron-conf (STARTUP_WINDOW_MODE, the same pattern as the frame-copy flag) and initMainWindow reads it synchronously. A change therefore applies on the next launch. Both sides normalize through normalizeStartupWindowMode, so junk never reaches the config file or the window options.
3. fullscreen is the BrowserWindow constructor option: on Windows/Linux the window is created hidden and enters fullscreen before its first paint. macOS ignores the option while the window is hidden (an NSWindow only toggles fullscreen once it is on screen), so ready-to-show repeats the request with setFullScreen(true) right after show() wherever isFullScreen() is still false — never unconditionally, or the platforms that honoured the option would animate a second toggle. The saved bounds stay spread into the options — they are the normal bounds the window returns to, and the close handler keeps persisting getNormalBounds(). maximized calls maximize() inside ready-to-show right before show(), never earlier: maximize() on a hidden window shows it, and a blank window would flash.
4. iptvnator --fullscreen (read via app.commandLine.hasSwitch, so it can sit anywhere in argv; the playlist-path extractor already skips every --prefixed argument) forces fullscreen for that launch only and is never persisted. Resolution lives in apps/electron-backend/src/app/services/startup-window-mode.ts. The switch is consumed by the first window (launchFullscreenSwitchConsumed in App): on macOS the process outlives its last window and the Dock re-creates it through the same initMainWindow, which must then follow the stored setting only. A second-instance launch carrying the switch is ignored — the window already exists.
5. Deliberately not offered: kiosk mode (removes the exit path) and "remember last state" (bounds persistence stores normal bounds only; an explicit choice is clearer). Regression coverage: app.spec.ts ("startup window mode"), settings.events.spec.ts, window.events.spec.ts, and the startup-window-mode cases in settings.e2e.ts.

Layout integration:

1. document.body gets a frameless-platform class (set in AppComponent, same mechanism as dark-theme) — body-level so rules also reach cdk-overlay content rendered outside app-root.
2. apps/web/src/styles.scss reserves padding-right: 150px in the top-aligned drag region (.workspace-header) for the 3 × 46px button strip.
3. Button colors follow the theme via CSS variables (--app-on-surface, --app-hover-overlay); the close button uses the Windows-style red hover (#e81123). No theme IPC is involved.

Window decorations on Linux (shadows, corners):

1. Hiding the title bar removes the window manager's decorations, so the shadow/rounded corners must come from client-side decorations (CSD). Electron 43 enables rounded corners by default when the Linux desktop environment supports CSD. GTK drop shadows and extended resize boundaries remain environment-dependent; Electron selects native Wayland automatically on Wayland sessions.
2. Linux environments without CSD support can still show a square, undecorated window. Windows 11 keeps its DWM rounded corners and shadow because the standard frame is retained.

Toolchain notes for the Electron 43 baseline:

1. better-sqlite3 remains pinned exactly so native dependency updates happen deliberately with database-worker, packaging, and Electron E2E validation. Version 13 uses Node-API and ships its supported platform binaries in the package. It must not be listed in pnpm's onlyBuiltDependencies: forcing an implicit node-gyp rebuild bypasses those binaries and makes installation depend on the host compiler toolchain. The old node-abi override belonged to v12's removed prebuild-install path and is no longer required.
2. Local development supports Node 22.13–22.x or Node >= 24, declared in engines as ^22.13.0 || >=24.0.0. The direct @faker-js/faker dependency and current lint tooling require that floor. electron-builder 26.15.7 also pulls @electron/rebuild 4, which requires Node 22.12 or newer, and the root postinstall runs install-app-deps on every pnpm install. The 26.15.7 minimum also carries the v26 backport that fully extracts the Snap template's .tar.7z payload; 26.15.0–26.15.6 can produce a Snap that is missing desktop-init.sh. CI already runs Node 22.
3. Dependabot keeps Electron, native database, packaging, EPG parser, and version-locked Shaka/mpegts updates out of the shared npm minor/patch group. Those dependencies require standalone PRs so their dedicated package, worker, playback, and diagnostic-contract validation cannot be hidden by an unrelated grouped update.
4. Electron 42 and newer download their development binary on the first Electron command instead of during package postinstall, so electron must not remain in pnpm's onlyBuiltDependencies allowlist. The first local pnpm run serve:backend can include a one-time download; use pnpm exec electron --version to prewarm it before an offline run.

Known caveats:

1. DIY buttons cannot show the Windows 11 Snap Layouts flyout (only native caption buttons or the Window Controls Overlay get that).
2. Double-click-to-maximize on drag regions is handled natively by Electron/Chromium; on Linux the exact behavior depends on the window manager.

Maintenance Guidance

Use this document as the source of truth when changing workspace shell behavior.

1. New top-level user destinations should default to child routes under /workspace.
2. Shared provider navigation logic belongs in portal-shared util/UI libraries, not duplicated inside the shell.
3. If a provider route changes how playlist/session bootstrap works, update the route-session provider and shell-facing route contract together.
4. When adding a non-native keyboard shortcut, update the shared shortcuts registry, the help dialog tests, README, and the closest behavior test.
5. Historical migration notes, cleanup lists, and one-off refactor steps should stay out of this file; track them in issues or PR notes instead.