> ## Documentation Index > Fetch the complete documentation index at: https://help.stralos.app/llms.txt > Use this file to discover all available pages before exploring further. # Frontend architecture > Stralos shell and feature-package architecture The frontend is composed by `stralos-shell` and separate feature packages. ## Shell responsibilities * Regional login redirect to the central login application. * Hand-off receiver (`/auth/handoff`) for a single-use session ticket issued by the central login service. * Browser session persistence. * Route guard and login redirects. * Global navigation (grouped Resources navigation surface — navigation-migration M1). * Organisation switcher (org-users-directory M3). * Workspace chrome slots and validation of the workspace remote's projected navigation facts. * Settings (`/settings`) — routed by the `organisation` feature remote at runtime. The shell registers the route group; the remote owns the organisation settings panels including **Users**, **Billing**, and **Assistant activity**. Users calls the organisation self-service routes at `/api/global/org/*` on `api-global`, which relays to `stralos-admin-api` server-to-server; Billing talks directly to `stralos-api-billing`. * Hand-off ticket scrub and the `__STRALOS_AUTH__` lifecycle bridge. The security surface itself is served by the login host; the shell links to it from the user menu. * Employee support session banner — visible when `impersonatedBy` is present on the session user object. * Non-production environment banner: visible on development and test hostnames. The development banner can be hidden for the current page load. * New version notification banner — shown when a newer deployment is detected. On development and test, the notification appears inside the environment banner rather than as a separate second banner. On production, the reload happens automatically at the next navigation with no user-visible notice. * Feature route registration. * Route catalogue and nav bridge (AI copilot foundations M0b.3). * Command palette (Cmd+K / Ctrl+K), mounted globally in the authenticated chromed branch. Sourced from `ROUTE_CATALOG`; `nav: "primary"` entries only; project-scoped entries are offered when a project is open and resolved against that project's ID. Entity search is not wired (follow-up). * Notifications bell in the header, between the command palette launcher and the user menu, on every signed-in route (`src/notifications/`). It polls api-global's unread count every 60 seconds while the tab is visible and lists, marks read, and marks all read through api-global's notification routes. See [Notifications](https://help.stralos.app/internal/notifications.md#notifications-bell). * AI copilot toggle in the header `trailingActions` slot, availability bridge, and toggle-state persistence (ai-copilot M1). The toggle is a labelled **Talk with Doug** button (**Close Doug** while open), and the user menu has a matching **Talk with Doug (AI Assistant)** item; both render only while the assistant is available. There is no floating assistant pill. The panel itself and all draft network calls are owned by the assistant remote, mounted as a widget in the `appframe-aside` slot. * **Your settings** user menu item — dispatches `stralos:user-settings-open` for every signed-in member, without a feature flag. The item is absent from billing recovery because that layout does not mount the widget. The settings sheet itself is owned by `stralos-feature-user-settings`, a `floating-end` widget remote. The shell cannot call into it directly; it listens for the window event and opens its sheet. The event name is a cross-repository contract (`src/userSettings.ts`). * Text size preference — a per-person text size control in the user menu. The preference is stored in `localStorage` under `stralos.textSize` and restored on the next page load. Five steps are offered, labelled **-2** through **+2** as offsets from the default (0). Applied by scaling the root font size so every `rem`-based value in the shell and in all loaded remotes moves coherently without per-component overrides. ## Version detection and reload The shell watches for a newer deployment and reloads the page at the next completed in-app navigation. Version detection and reload are separate concerns: reload on navigation applies in every environment, while the visible banner is shown only in development and test. ### Detection The shell polls two documents every five minutes per tab: * `index.html` — carries the deployed shell's git SHA in its asset URLs. Changing when the shell is activated; unchanged by a remote-only deploy. * `remotes-manifest.json` — carries each remote's git SHA in its `version` field. Changing when a remote is deployed; unchanged by a shell-only activation. Either document changing is treated as a new version. Polling only one would miss a whole class of deploys. Each poll is a conditional GET (`cache: "no-cache"` with an ETag), so the steady-state cost is two 304 responses per tab every five minutes. In addition to the interval, the shell triggers an immediate check on tab visibility change (`visibilitychange`) and on back-forward cache restores (`pageshow` with `persisted: true`). These cover the long-idle tabs that are most likely to be holding a stale document and whose intervals have been throttled or frozen by the browser. ### Reload on navigation When a newer version is detected, the shell waits for the next completed in-app navigation before reloading. A navigation in progress when the version is found is skipped; the reload is deferred to a subsequent navigation. Reloads are suppressed for full-document navigations, downloads, form submissions, and explicit reloads — all of which already fetch a fresh document. The shell uses the native `window.navigation` API when available. On `navigatesuccess` the shell checks whether a reload is eligible and, if so, issues `location.reload()` after one task to allow popstate handlers to run first. When the native Navigation API is unavailable, the shell falls back to observing the `pathname` prop passed to `useNewVersionAvailable`. A pathname change from one render to the next triggers the same reload check. Both paths are active and exclusive — the native path takes precedence, and the fallback runs only when the native API is absent — so a tab in any environment reloads at its first navigation after a new version is detected. ### Reload banner **New version available** with **Reload** and **Dismiss** controls is shown only when the shell's `runtime-config.json` reports `environment: "development"` or `environment: "test"`. In production, the reload happens automatically at the next navigation with no user-visible notice. When a development or test hostname shows an environment banner, the update message appears inside it. If the runtime environment is development or test but the hostname has no environment banner, `ShellNotices.tsx` renders the standalone notice. Production shows no update notice. The `versionAvailability.ts` module owns detection. The `NewVersionNotice` component owns the standalone banner. `EnvironmentNotice` renders the embedded update message when the host has a non-production banner. The `useNewVersionAvailable` hook in `NewVersionNotice.tsx` wires them together and manages the reload trigger. ## Navigation order MVP navigation is gated by the PostHog `mvp` feature flag in `stralos-shell`. `App.tsx` evaluates it through `useFeatureFlag("mvp", { fallback: true })` on the shell's single PostHog instance; no separate SDK initialisation is required. While the flag is on, `filterMvpNavigation` in `src/mvpNavigation.ts` removes the areas that are not part of MVP. Because the fallback is `true`, MVP navigation is also shown before flags load and whenever PostHog is unreachable or disabled, so a customer never sees unfinished areas by accident. Only a successful evaluation that returns `mvp` as off shows the full navigation. Global navigation items appear in this order: **Dashboard**, **Projects**, **Resources** (group), **Settings**. The **Resources** group is a non-routing navigation header whose items are, in order: **Rates Library** (`/rates`), **Construction Activities** (`/activities`), **People** (`/people`), **Crews** (`/crews`), **Plant** (`/plant`), **Companies** (`/companies`), **Locations** (`/locations`), **Company scheduler** (`/scheduler`). It appears as a desktop popover or in the mobile navigation drawer. Within the Resources popover, the shell groups items into three labelled sections based on the remote key that owns each path: | Section | Items | | - | - | | **Libraries** | Rates Library, Construction Activities | | **Master data** | People, Crews, Compliance, Plant, Companies, Locations (any path not matched by another section) | | **Tools** | Company scheduler | This grouping is applied by the shell's `withResourceSections()` compositor, which reads the remote key from the manifest. A section header is omitted when no items belong to it. The destinations themselves — their labels and paths — come from the served descriptors, so a rename or relocation in the manifest takes effect without a shell release. If the popover composition already carries nested groups (from a future owner-provided section), `withResourceSections` leaves it unchanged. Navigation labels come from the `navLabel` field in each route descriptor. There is no shell-side override map; the organisation descriptor supplies **Settings** for `/settings`. Workforce owns **People** (`/people`), **Crews** (`/crews`), and the route-only Compliance report (`/compliance`). Fleet owns **Plant** (`/plant`); the retired `/plant/subcategories` path redirects there. The `workspace` remote owns **Companies** (`/companies`) and **Locations** (`/locations`). Legacy `/clients` and `/suppliers` paths redirect to `/companies`. ### Legacy company-register redirects (M5) | Legacy path | Canonical path | | - | - | | `/clients` | `/companies` | | `/clients/:id` | `/companies` | | `/suppliers` | `/companies` | | `/suppliers/:id` | `/companies` | The detail forms redirect to the list rather than `/companies/:id` because legacy client and supplier IDs are not unified party IDs. ## Locations page The **Locations** page (`/locations`) lists the organisation's own offices, yards, and depots. It reads from `GET /api/global/locations` with `owner=ours` to exclude company branches and quarries, which belong to party records and are displayed on the company detail page instead. The register lists **effectively active** locations only (feature-workspace PR 73). It requests `status=active`, which api-global filters on the effective status, so a location retired on its own and every location of a retired company are both left out; the page also filters `status === "active"` client-side as a guard. There is no **Restore location** row action: **Retire location** is the only one. A location retired on its own can still be set back to **Active** from its detail page (`/locations/:id`), which a company location reaches from the company record's Locations panel and one of the organisation's own sites reaches only by URL; for a location whose company is retired that save is refused with `409 location_owner_retired` ("This location's company is retired, so the location cannot be restored."). Reinstating a company is a future PRD. ### `OrganisationLocation` shape `api-global` returns location address and coordinate fields nested under `geoTag`, matching the shape every other geo-bearing entity in the estate uses: ```typescript theme={null} type OrganisationLocation = { id: string; name: string; kind: "office" | "yard" | "depot" | "branch" | "quarry" | "other"; status: "active" | "inactive"; geoTag: { addressLine1?: string; city?: string; region?: string; countryCode?: string; latitude?: number; longitude?: number; }; }; ``` `latitude` and `longitude` are omitted by the server when the row has no coordinates, so both fields are optional. A location with no coordinates is selectable for pricing but cannot resolve a route — the page shows a "No coordinates" indicator only for those rows. A retired location shows a "Retired" badge. The `CompanyDetailPage` Locations panel reads the same nested `geoTag` shape for a company's own branches and sites. ## Projects list routed actions Navigating to `/projects?action=add-project` opens the **New project** modal. The Projects page removes the `action` parameter before opening the modal, preserves other query parameters, and prevents React StrictMode from opening the modal twice. The modal is owned by the `workspace` remote. Use this route from feature remotes that need to start project creation. Do not import or duplicate the project editor in a remote. ## Project navigation (navigation M2) On a registered `/projects/:projectId/*` route, the `AppFrame` project navigation surface shows the **Project navigation** section for the routed project. It is absent from `/projects` and global routes, even when the header selector has a selected project. Project pages no longer render a persistent workspace header or horizontal sub-navigation. The desktop rail and mobile project drawer list entries in this order: **Overview** · **Estimate** · **Delivery** \[**Delivery estimate**, **Compare to tender**, **Sign-off**, **Variations in Delivery**, **Programme**, **Schedule**] · **Commercial** \[**Variations**] · **Documents** · **Project Settings**. * **Overview** (`/projects/:projectId`) is owned by the `workspace` remote and is the index route for the project workspace. It shows project identity, status, key dates, the contract basis panel, and quick-links to the other visible workspaces. * **Delivery** and **Commercial** are non-routing group headers with their entries indented beneath them. * **Estimate** (`/projects/:projectId/estimate`), **Documents** (`/projects/:projectId/documents`), and **Variations** (`/projects/:projectId/commercial/variations`) are served by the `estimate` remote. * **Delivery estimate** (`/projects/:projectId/delivery`), **Compare to tender** (`/projects/:projectId/delivery/compare`), **Sign-off** (`/projects/:projectId/delivery/sign-off`), and **Variations in Delivery** (`/projects/:projectId/delivery/variations`) are served by the `estimate` remote (PRD 210 §12.3). These appear before Programme and Schedule in the Delivery group. * **Programme** (`/projects/:projectId/delivery/programme`) and **Schedule** (`/projects/:projectId/delivery/schedule`) are served by the `projectSchedule` remote. Programme is declared as a `paths` entry on the `projectSchedule` descriptor alongside the primary Schedule path. * **Project Settings** (`/projects/:projectId/settings`) appears at `order: 260` in the project section when the `projectSettings` remote is available in the active composition. * **Tender** and **Finance** have no shipped descriptor destinations, so they do not appear. There is no **All Projects** item in the project rail any more. The global **Projects** entry in the header is the way back to the project register from inside a project workspace. The rail's top block is the project-context slot, which shows the current project and client name when the workspace remote renders it; until it does (an older workspace build or a load failure), the shell's fallback, an **All projects** link to `/projects`, shows there instead. See [Project rail slots](#project-rail-slots-shell). ### Delivery estimate nav links and the open estimate (PRD 210 §12.2) A project can hold multiple estimates (for example a tender estimate and a Delivery estimate). The estimate a page works in travels in the route: `/projects/:projectId/estimates/:estimateId/...`. The bare `/projects/:projectId/estimate/...` form stays as the estimate remote's primary resolver — it looks the primary up and redirects to the canonical URL — so inbound links that predate multiple estimates still land correctly. When the user is on a canonical estimate URL, every estimate nav link in the project drawer and every estimate command in the command palette carries the same `:estimateId`. This keeps the user inside the open estimate when they navigate between sections. A project-level page (Delivery, Documents, Settings) has no estimate ID in its URL; its estimate links fall back to the bare resolver path, which opens the primary. The bare `/projects/:projectId/estimate` path is the only declared nav destination. The canonical `/projects/:projectId/estimates/:estimateId` mount is `nav: "hidden"` — the shell rewrites each displayed link at render time using the open estimate from the URL, but the catalogue entry stays on the bare form so `routeId` lookups and help-page `routeId` frontmatter are unaffected across both URL forms. The shell reads the open estimate ID from the URL alone on canonical routes. On non-canonical routes (any path without `/estimates/:estimateId`), the estimate remote publishes the ID via `setActiveContext` so features that need it — such as the rate-exception badge — can still read it from the nav bridge. ### Rate exception badge (PRD 04 M4) The **Project Rates** item in the project rail carries a live exception-count badge. The badge is published by the Estimate remote using `publishNavigationBadge` on the nav bridge, so the shell renders it without owning the polling policy, count source, or display logic. The Estimate remote reads the persisted count endpoint (`GET /api/estimate/estimates/:id/rate-exceptions/count`) rather than running the exception pass itself. A stale response is published with `tone: "muted"` and `refreshing: true`. The badge renders differently depending on whether the project rail is expanded or collapsed: * **Expanded rail** — the count chip appears in a trailing badge slot (`data-nav-badge`) to the right of the item label. The glyph slot (`data-nav-glyph`) does not contain the chip. * **Collapsed rail** — only a dot indicator (`data-nav-badge-dot`) is shown. The count chip is hidden to save space, but the full accessible label (for example `Project Rates — 128 rate exceptions`) remains on the link so screen-reader users receive the complete count. Badge states: | Visual | Meaning | | - | - | | Orange solid badge with count (expanded) / dot (collapsed) | Fresh count — no issues loading. | | Grey subtle badge with count and refresh icon (expanded) / dot (collapsed) | Stale count — the pricing inputs changed after the persisted count was computed, or a refresh failed after a verified count. Click the rail item to open Project Rates and trigger a refresh. | | Grey subtle badge with `!` and refresh icon | Unavailable — no verified count yet, or every fetch has failed. Click the rail item to retry. | | No badge | Fresh count of zero — the shell suppresses a settled zero because it carries no information. A stale zero still shows with the refresh icon, because the count may be wrong and is being re-read. | The shell suppresses the badge chip when the published `displayText` resolves to a settled zero (numeric value `0` or empty string) and `refreshing` is false. A zero that arrives while `refreshing` is true is not suppressed — it says the number may be stale and is being re-read, which is the polling state the rail exists to show. The `accessibleLabel` is preserved either way, so screen-reader users are still told there are no exceptions when the chip is hidden. The publisher (`RateExceptionBadgePublisher` in `stralos-feature-estimate`) sends `String(state.count)` without a zero guard; the shell-side suppression is the host's own presentation decision. A one-line guard in the publisher would be the more durable fix and is compatible with this behaviour. The remote waits for an `estimateId` from the nav bridge before issuing any network call. On canonical estimate routes the shell reads the ID directly from the URL; on other routes the estimate remote publishes it via `setActiveContext`. If the active context is absent (for example, when the user has not yet opened the estimate workspace on this visit), the item renders without a badge. A route change clears the prior context so a badge from one visit cannot leak into a fresh visit to the same path. The `accessibleLabel` field in the badge value becomes the full accessible name of the navigation item — for example `Project Rates — 3 rate exceptions` or `Project Rates — rate exception count unavailable; open to retry` — while the visible label stays `Project Rates`. ### Project rail slots (shell) The shell renders two host-owned `RailSlotTarget`s in the project rail (`src/App.tsx`), which the workspace remote's persistent chrome portals into (see [Persistent workspace chrome](#persistent-workspace-chrome)). Each target shows the host's `fallback` for as long as the owner has rendered nothing there. | Slot (`data-rail-slot`) | Where | Owner component | Host fallback | | - | - | - | - | | `project-context` (`railHeaderTarget`) | `AppFrame.projectNavigationHeader`: the top of the project rail and mobile project menu, on a routed project page | `RailHeader`: the project name and client | An **All projects** link to `/projects` | | `estimate-switcher` (`estimateSwitcherTarget`) | `NavigationGroup.leadingContent` of the top-level **Estimate** group: the first row beneath the **Estimate** label (ui 0.75.2) | `EstimateSwitcher`: the PRD 210 estimate switcher, shown only when the project's **Multiple estimates** setting is on | None (`fallback={null}`) | `withEstimateSwitcherSlot` applies the switcher slot to the top-level group whose `label === "Estimate"` only; groups at any other level are left unchanged. The **Estimate** label always stays visible as a rail row and is never replaced by the switcher. When the workspace remote has portalled nothing (a single-estimate project, an older workspace build, or a load failure), the row beneath the **Estimate** label is empty. ### Overview page The `workspace` remote owns the **Overview** page (`/projects/:projectId`). It sources all its data from `api-global` and shows: * **Project** panel — client and status. * **Key dates** panel — start date, target submission date, and end date. * **Contract basis** panel — contract form, on-site overhead percentage, off-site overhead and profit percentage, and special conditions note. If the contract profile has not been set, the panel says so. If the load fails an inline **Retry** button appears; the other panels remain visible. * **Go to** panel — buttons linking to each visible workspace destination (Overview itself is excluded). Key dates are stored as `YYYY-MM-DD` strings and displayed as stored to avoid UTC-midnight timezone shift. ### Project selector behaviour The `workspace` remote provides the persistent header project selector. The shell mounts the remote's persistent chrome capability once in the authenticated layout, outside its route tree, so the same workspace provider and controller survive navigation between owners. The workspace remote owns selector data loading, project and client editors, and remembered project navigation; the shell does not call those domain APIs. From inside a project workspace, selecting a different project in the header selector keeps the current workspace. For example, switching from project A while on **Delivery › Programme** lands on project B's **Programme** page. From anywhere outside a project workspace, selecting a project opens that project's **Overview**. When the current project ID cannot be resolved, the workspace remote publishes `projectMissing: true`. The shell suppresses the unmatched project body only for that committed route and clears the fact on navigation. #### Destination resolution (`projectDestination`) `useProjectChrome` exposes `projectDestination(projectId)`, a pure render-time function that resolves the destination href for a given project. The rules, in order: 1. If the current path is a project-chrome path, swap the project ID segment to produce the equivalent path in the target project. 2. Otherwise, use the remembered per-project detour stored for that project. 3. Otherwise, fall back to that project's workspace home (`/projects/:projectId`). The function is total: every project ID resolves to a concrete path. A path that `isProjectChromePath` refuses (for example, because the current route is outside a project workspace) degrades to the workspace home so the selector row always has a valid `href`. `selectProject` remains the imperative API: it calls `projectDestination` then `navigate`, so the click-to-navigate path continues to work unchanged. #### Anchor rendering and modifier-click support Each project row in the selector is rendered as a real anchor element (``). This lets the browser handle Ctrl/Cmd-click and middle-click natively — those gestures open the project in a new tab without affecting the current tab. Prior to this change, rows were `div[role=menuitem]` elements that called `navigate` on click. Modifier clicks silently switched the current tab instead of opening a new one. Selection state is not set on click. The `projectChrome` effect already adopts `routeProjectId` whenever the route addresses a loaded project, so a plain click's navigation sets the selection and a modifier click correctly leaves it alone. Keyboard activation uses a `navigate` override on `Menu.Root`: zag passes an anchor item to its `navigate` prop rather than clicking it, so the override ensures Enter activates the router link instead of dispatching a bare `MouseEvent` that would trigger a full-page load. ### Persistent workspace chrome The workspace remote's `./routes` module exports `persistentChrome` alongside `workspaceRoutes`: ```ts theme={null} type HostChromeInput = Readonly<{ version: 1; requestKey: string; publish(snapshot: OwnerChromeSnapshot): void; }>; type OwnerChromeSnapshot = Readonly<{ version: 1; requestKey: string; rememberedProjectPath: string | null; projectMissing: boolean; }>; const persistentChrome = { version: 1, Provider, Header, Notice, Palette, // Optional — present only in owners that support the rail slots: RailHeader, // project/client block for the rail's top EstimateSwitcher, // estimate switcher heading the Estimate rail section }; ``` `Provider` receives `remoteKey`, its children, and the optional `hostChrome` input. It owns the shared workspace controller and UI provider. `Header` renders the project selector. `Notice` renders load failures and a missing-project message. `RailHeader` renders the routed project's name and client in the top of the project navigation rail. `EstimateSwitcher` is the estimate-switching dropdown placed beneath the **Estimate** rail entry; it is visible only when the project's **Multiple estimates** setting is on. `Palette` provides the project command palette. The standard route array supplies the workspace outlet pages. `RailHeader` and `EstimateSwitcher` are optional. An older owner that omits them renders nothing in the corresponding host targets, so the host's fallback for that slot shows instead. The shell portals each component into its `RailSlotTarget` when the owner provides it. The shell exposes this module as `RemoteRuntime.PersistentChrome` and mounts it with a non-credential session identity, host-owned header and notice targets, the active workspace outlet target, two optional rail slot targets, and an `onChromeState` callback. A null session or missing header target prevents the remote from loading. Workspace route elements register outlet targets; the persistent provider portals the matching route into each target. The two rail slot targets are `railHeaderTarget` (the rail's top block, provided when a project is routed) and `estimateSwitcherTarget` (the first row of the Estimate section). Their placement and fallbacks are in [Project rail slots](#project-rail-slots-shell). The shell accepts only the four fields in `OwnerChromeSnapshot`. It verifies the `requestKey` and `rememberedProjectPath`, then scopes the accepted snapshot to the current runtime, session identity, complete route location, and active request lease. Invalid snapshots are reported and cleared; late publications and clean-ups cannot overwrite a later visit. The workspace stores the remembered route under a user-and-organisation-scoped key. The retired unscoped shell key `stralos.nav.lastProjectPath` is neither read nor written. After the owner publishes a remembered project route, the global **Projects** rail entry resumes that route even when the user is already inside a project. There is no **All Projects** item in the project rail; while the project-context slot is empty, its host fallback links to `/projects` (see [Project rail slots](#project-rail-slots-shell)). The initial module load is shared. A missing descriptor shows a retriable header fallback only because no workspace outlet can be validated. A degraded runtime, module-load failure, or provider failure shows retriable fallbacks in the header and in a registered active route outlet; there is no separate notice fallback at that level. After the provider loads, the Header, Notice, and route leaves have independent render boundaries: **Project selector unavailable** in the header, **Workspace status unavailable** in the notice area, and the manifest's workspace fallback copy in the route outlet. A stale-chunk error attempts the guarded one-time reload before showing a fallback. ### Legacy route redirects (M3) Three project paths moved to canonical locations at navigation-migration M3. The shell registers permanent redirects for the old paths so bookmarks, pasted links, and old copilot citations continue to resolve: | Legacy path | Canonical path | | - | - | | `/projects/:projectId/plan` | `/projects/:projectId/delivery/programme` | | `/projects/:projectId/schedule` | `/projects/:projectId/delivery/schedule` | | `/projects/:projectId/variations` | `/projects/:projectId/commercial/variations` | Redirects preserve the full URL: the project id, any deeper path segments, query string, and fragment are carried across intact. A redirect is only registered when a canonical target exists in the active manifest — if the remote is absent, both the old and new paths 404 rather than looping. The Documents title route uses `end: false`. Its M4 review descendants (`/projects/:projectId/documents/review` and `/projects/:projectId/documents/review/:documentId`) therefore remain titled **Documents**. Schedule is served by the `stralos-feature-project-schedule` remote at `/projects/:projectId/delivery/schedule`. ## Route catalog The shell maintains a labelled inventory of navigable sections in `src/routeCatalog.ts`. The assistant service uses the catalogue for navigation questions and deep links. Each entry in `ROUTE_CATALOG` has the following shape: | Field | Description | | - | - | | `id` | Stable string key — matches the `routeId` field in help-page frontmatter. | | `label` | Human-readable label; matches the nav item label where the entry is a nav item. | | `pathTemplate` | react-router path template (`:param` syntax). | | `scope` | `"global"` or `"project"` (project-scoped entries always start with `/projects/:projectId`). | | `params` | Named URL parameters extracted from `pathTemplate`, in order. | | `description` | One-sentence description of what the section is for. | | `nav` | `"primary"` (appears in nav), `"hidden"` (real route, no nav item — e.g. `/compliance`), or `"chromeless"` (no shell chrome — the contractor portal and the work-items export preview). | ### Generated JSON artifact `src/routeCatalog.generated.json` is generated by `pnpm gen:route-catalog` and must be committed with catalogue changes. The drift test (`routeCatalog.drift.test.ts`) cross-checks the catalogue against the live nav sources in both directions. The assistant service vendors and parity-checks this generated JSON. It consumes the catalogue through navigation tools and the deterministic navigation fast path. ### Drift test nav sources The drift test validates every catalogue `pathTemplate` against four nav sources and checks that every path in those sources has a catalogue entry: 1. **Remote manifest paths** — `paths` entries from `DEFAULT_MANIFEST`, read via `remotePaths`. 2. **Nav builder output** — the global rail and the project workspace drawer, in both static and manifest-composed modes (`buildDefaultNavigation`, `buildRemoteNav`, `buildProjectWorkspaceNav`). 3. **Remote-host sibling constants** — `*_BASE_PATH` declarations in `remote-host.tsx`, enumerated explicitly in `REMOTE_HOST_SIBLING_CONSTANTS`. This map has been empty since shell-reduction §4.7 act 5: every former sibling is now a descriptor `paths` entry on the relevant remote. The equality guard still applies so a new constant cannot slip in unenumerated. 4. **Committed routes contracts** — the `routes-contract.json` files vendored in `integration/__contracts__` and imported via `COMMITTED_CONTRACTS` in `integration/contracts.ts`. Each file is the exact contract a remote publishes at its served SHA. A catalogue entry whose path template matches one of these contracts corresponds to a route the remote actually declares, so a typo or a dropped route fails direction (a) rather than passing silently. The contracts source replaced a hand-written `SHELL_NAV_HIDDEN_PATHS` map that had no equality guard back to anything real. Only workspace, organisation, and estimate currently emit a contract; routes belonging to activities, rates, and project-settings still rely on the manifest source until those remotes adopt the contract. To add a catalogue entry for a route belonging to a contract-emitting remote, the path must appear in that remote's committed `routes-contract.json`. A path that is only typed in the catalogue fails the drift assertion at direction (a). ## Command palette The shell provides a command palette (Cmd+K on macOS, Ctrl+K everywhere else) that lets the user navigate to any primary destination without reaching for the rail or drawer. It is mounted once in the authenticated chromed layout and driven by `src/commandPalette.ts`. ### Item source Commands are built from `ROUTE_CATALOG` — only entries with `nav: "primary"` become commands. Hidden and chromeless entries are not offered. When a project is open, project-scoped entries are resolved against the current `projectId` and listed before global destinations. When no project is open, project-scoped entries are omitted entirely. The palette searches pages, not entities. Project search (by name, a rate, or an activity) is not wired here — the shell holds no project list; that lives in the workspace remote's project selector. ### Group headings Every item carries a `group`. Global destinations with no catalogue `group` are placed under **Go to**. Project-scoped destinations with no catalogue `group` are placed under **This project**. The palette renders a heading whenever the group changes from one row to the next, so if items from the same group are non-contiguous the heading appears more than once. `buildCommandPaletteItems` guarantees contiguity: items are sorted so each group's entries are adjacent, in order of first appearance, with catalogue order preserved within each group. This means a project's ungrouped pages (Overview, Estimate, Documents, Project Settings) and its grouped pages (Delivery, Commercial) all appear under a single **This project** heading. ### MVP navigation flag When the MVP navigation feature flag is active, `buildCommandPaletteItems` applies the same filter as the rail. Destinations hidden by the MVP flag are not offered through Cmd+K. ### Launcher `CommandPaletteLauncher` renders a **Search** button in the top bar, to the left of the project selector. It shows the search icon and **⌘K** / **Ctrl K** at the `md` breakpoint and wider, and the icon alone on narrower screens. It reads the platform from `navigator.userAgentData.platform` (or `navigator.platform` as a fallback) to choose the shortcut label. The launcher is a button because it opens the palette's dialog; the palette owns the editable search field. ## `window.__STRALOS_NAV__` bridge The shell installs a nav bridge on `window.__STRALOS_NAV__` at bootstrap (synchronously in `main.tsx`, before any remote loads). It is the navigation analogue of `window.__STRALOS_AUTH__`. ```ts theme={null} window.__STRALOS_NAV__.version: 1 window.__STRALOS_NAV__.getSnapshot(): NavSnapshot window.__STRALOS_NAV__.subscribe(listener: () => void): () => void window.__STRALOS_NAV__.navigate(path: string): void window.__STRALOS_NAV__.currentRoute(): CurrentRoute window.__STRALOS_NAV__.isKnownRoute(path: string): boolean window.__STRALOS_NAV__.setActiveContext(context: { estimateId?: string }): void window.__STRALOS_NAV__.publishNavigationBadge( routeId: string, value: { displayText: string; accessibleLabel: string; tone: "emphasis" | "muted"; refreshing: boolean }, context: { path: string; contextRevision: number } ): () => void ``` `getSnapshot` and `subscribe` implement the `useSyncExternalStore` contract. Remotes use them to subscribe to route, context, and badge changes without depending on React Router directly. Remotes that remain compatible with older shells guard `publishNavigationBadge` before calling it. The returned function releases the published badge when called (for example, on component unmount). **`currentRoute()`** resolves the current pathname against the catalogue without a router dependency. It returns: ```ts theme={null} type CurrentRoute = { path: string; // the live pathname routeId?: string; // matched catalogue entry id, if any projectId?: string; // extracted :projectId for project-scoped routes estimateId?: string; // open estimate — read from the URL on canonical routes, else from setActiveContext } ``` Matching picks the most specific entry (longest `pathnameBase`) so a deep sub-route such as `/projects/abc/estimate/work-items/42` still resolves to `routeId: "estimate"`. **`getSnapshot()`** returns a `NavSnapshot` — a stable, referentially frozen object that is replaced only when the route, published context, navigation badges, or the resolved composition changes. It is the read path for `useSyncExternalStore`-style consumers. ```ts theme={null} type NavEntry = { label: string; scope: "project"; path?: string; // absent on group entries items?: readonly NavEntry[]; // present on group entries }; type NavigationBadge = { displayText: string; accessibleLabel: string; tone: "emphasis" | "muted"; refreshing: boolean; }; type NavSnapshot = { revision: number; // monotonically increasing contextRevision: number; // increments when setActiveContext is called route: CurrentRoute; // the resolved current route projectNavigation: readonly NavEntry[]; // resolved project workspace nav for the current project badges: Readonly>; // published navigation badges by route id }; ``` `projectNavigation` carries the full resolved project workspace nav for the project identified by `route.projectId`. Paths and labels reflect the live composition — remote-backed destinations use the path from the resolved manifest rather than a static fallback. The array is empty when the user is outside a project route, or before the composition resolves. The shell calls `setNavigationManifest` immediately after the remotes manifest resolves, before registering any remote, so `projectNavigation` is populated from the first snapshot a remote receives at registration time. **`subscribe(listener)`** registers a change listener compatible with `useSyncExternalStore`. It returns an unsubscribe function. The listener is called synchronously on registration, then on every snapshot change. **`navigate(path)`** calls the live React Router navigation function. Calls made before the router registers are queued and flushed in order when `NavBridgeRegistrar` mounts. **`isKnownRoute(path)`** returns `true` when a concrete app path resolves to a known catalogue route. The assistant remote calls this before rendering any inline link, citation, or server-driven `navigate` action, so an absent bridge member suppresses every deep link. The function strips a query string and fragment, requires an app-relative path (`/` prefix, not `//`), and matches catalogue templates with `end: false` so a section sub-route resolves to its section. It returns a real `boolean` — the assistant compares with `=== true`, so a truthy non-boolean would read as `false` and silently remove links. **`setActiveContext(context)`** lets a remote publish record context that is not represented in the URL. The Estimate remote publishes its selected `estimateId` and clears it on unmount. For canonical estimate routes (`/projects/:projectId/estimates/:estimateId/...`), `currentRoute()` reads `estimateId` directly from the pathname — it does not depend on a `setActiveContext` call. For non-canonical paths (for example, the Delivery estimate pages at `/projects/:projectId/delivery`), `setActiveContext` is the only source for `estimateId`. The shell drops the published context on a pathname change and on browser history navigation so a stale estimate ID cannot carry forward to a later turn. The call is best-effort and uses optional chaining so a newer remote remains compatible with an older shell: ```ts theme={null} window.__STRALOS_NAV__?.setActiveContext?.({ estimateId }); ``` **`publishNavigationBadge(routeId, value, context)`** lets a remote attach a badge to a navigation item by its stable route ID. The shell renders the badge alongside the item's icon without needing to know the remote's polling policy, count source, or display logic. `routeId` is the stable catalogue ID for the destination (for example `"estimate.builder.rates"`). The badge is only applied to a navigation item that carries a matching `routeId` field — a label match alone is not sufficient. `value` carries the display content: ```ts theme={null} type NavigationBadge = { displayText: string; // short label shown on the badge accessibleLabel: string; // full accessible name replacing the nav item's default label tone: "emphasis" | "muted"; // "emphasis" renders orange; "muted" renders grey refreshing: boolean; // when true, a spinning refresh icon appears alongside the text } ``` `context` binds the publication to the current route and active context revision so the shell can reject a stale result arriving after a navigation or context change: ```ts theme={null} type NavigationBadgeContext = { path: string; contextRevision: number } ``` Obtain `context` from the bridge snapshot rather than constructing it manually: ```ts theme={null} const nav = window.__STRALOS_NAV__; const snap = nav?.getSnapshot(); const cleanup = nav && snap ? nav.publishNavigationBadge?.(routeId, value, { path: snap.route.path, contextRevision: snap.contextRevision, }) : undefined; ``` The return value is a cleanup function. Call it when the badge is no longer valid — for example when the remote unmounts or when a fresh fetch supersedes the previous result. A cleanup from an earlier publication cannot clear a newer one for the same route ID; the bridge compares by object identity. The badge is also discarded automatically on any route or context change. The shell freezes both the badge value and the context object before storing them. The bridge validates every field and silently ignores publications with a mismatched path, a wrong context revision, or invalid field types. ## Project visit signal On every committed route, the shell records which project the tab is in, so a remote that remembers per-project state can tell whether the person has been in another project since it last looked. feature-estimate's tender check review memory uses it. The shell writes `sessionStorage` key `stralos.shell.projectVisit.v1` with the value `{ projectId: string, seq: number }` from `recordProjectVisit` in `src/projectVisit.ts`, called by `commitRouteVisit` in `src/nav-bridge.ts`: * Moving to a different project increments `seq`, starting at 1. Returning to the same project, or visiting a route outside a project, changes nothing. * The first document load counts, so a tab opened straight at a project URL (link, typed URL, bookmark or reload) records the visit before any remote loads. A remote notes `seq` and compares it on its next read. A different `seq` means the person has visited another project in this tab, even if they are back in the original one. The shell is not a published package, so a remote reads the key itself and validates the shape (a non-empty `projectId` and a positive integer `seq`), as the shell's own `readProjectVisit` does. * `sessionStorage` lasts as long as the tab. * Storage can be missing, full or blocked, and reading `window.sessionStorage` can throw. The shell guards every access and records nothing on failure. * A shell without this feature never writes the key. Treat an absent or malformed value as no information, not as no visits. ## Feature packages Current feature packages: * `stralos-feature-dashboard` * `stralos-feature-rates` * `stralos-feature-activities` * `stralos-feature-scheduler` — organisation-wide crew scheduling board (`/scheduler`) * `stralos-feature-workforce` — People, Crews, and Compliance (`/people`, `/crews`, `/compliance`) * `stralos-feature-fleet` — Plant & Vehicles (`/plant`) * `stralos-feature-estimate` * `stralos-feature-project-schedule` — project-scoped crew schedule (`/projects/:projectId/delivery/schedule`) and Programme (`/projects/:projectId/delivery/programme`) * `stralos-feature-project-settings` * `stralos-feature-workspace` — Projects, Companies, Locations, and project Overview routes * `stralos-feature-organisation` — organisation settings panels at `/settings`, including Users, Billing, and Assistant activity * `stralos-feature-assistant` — the AI copilot widget mounted in the shell's `appframe-aside` slot * `stralos-feature-user-settings` — the **Your settings** panel, mounted as a widget in the shell's `floating-end` slot. Renders nothing until the shell dispatches `stralos:user-settings-open` from the user menu. Each feature owns its page components and API client. Features should not import shell internals. ## Shared packages * `@stralos-co-nz/ui`: App frame (with `trailingActions` slot for shell-injected controls, `projectNavigationHeader` slot for owner-rendered content at the top of the project rail, `NavigationGroup.headerContent` and `NavigationGroup.leadingContent` slots for owner-rendered group headings and first rows in the project rail, and support for grouped navigation entries), [design library](https://help.stralos.app/internal/design-library.md) page-composition primitives (`PageHeader`, `DataTable`, `StatusBadge`, `SectionCard`, `Toolbar`, `RowMenu`, `KindChip`, `KpiStrip`, `ListCount`, `SkeletonRows`, `Dialog` with `actions`, `FormGrid`, `FormField span`, `DateField`, `format` helpers), shared UI primitives, route definition types, forms, coordinate validation helpers, display helpers, shared resource pickers, the `ErrorBoundary` component, the [form feedback pattern](https://help.stralos.app/internal/form-feedback-pattern.md) (including `ConstructionSpinner` for long-running operations), the [`useFeatureFlag` hook](#feature-flag-hook), and the [AI copilot `ChatPanel` component group](https://help.stralos.app/internal/ai-copilot-frontend). * `@stralos-co-nz/maps-ui`: [Location picker](https://help.stralos.app/internal/location-picker.md) (`LocationPicker`, `GoogleMap`) for Google Places Autocomplete (New) address search and map selection, plus the `LocationEditorValues` form type. Extracted from `@stralos-co-nz/ui` in 0.52.0. * `@stralos-co-nz/calculator-ui`: calculator modal screens (trench, pit, and volume) extracted from `@stralos-co-nz/ui` at 0.51.0. Import calculator components from this package. Export names and props are unchanged from the previous `@stralos-co-nz/ui` and `@stralos-co-nz/ui/calculators` locations. The `./calculators` entry point is no longer present on `@stralos-co-nz/ui`; replace any such import with `@stralos-co-nz/calculator-ui`. It also exports supporting types such as `DisposalSubstancesState`, `FillMaterialsState`, `FillMaterialOption`, `RenderLayerAssignment`, and `DisposalSubstanceUsage`, plus `UNASSIGNED_LABEL`. * `@stralos-co-nz/domain`: shared domain types and estimating calculations. ## Fonts subpath (`@stralos-co-nz/ui/fonts`) From `@stralos-co-nz/ui` 0.23.13, the brand typefaces (Sora and IBM Plex Mono) are no longer imported inside `Provider`. They are published as a separate subpath and must be imported once by the application that owns the page: ```typescript theme={null} import "@stralos-co-nz/ui/fonts"; ``` Add this import to the root entry point of `stralos-shell`, `login-web`, and `admin-web`. A host that upgrades to 0.23.13 without adding this import will lose its typefaces. Federated remotes must **not** import this subpath. A CSS side-effect import anywhere on a remote's import graph causes the bundler to emit font files into every remote artifact (34 orphaned font files, approximately 338 KB, measured at thin-host M0). The `@stralos-co-nz/ui/fonts` subpath is intentionally unreachable from the package's root barrel or from `Provider`, so a remote that only imports named UI exports cannot accidentally pull fonts in. ## Stralos theme (`stralosConfig`) `@stralos-co-nz/ui` exports `stralosConfig`, a Chakra UI v3 `defineConfig` preset. Every feature remote and the shell apply this config through `createSystem(defaultConfig, stralosConfig)`. The theme carries the full colour ramps (green, orange, red, blue, and gray now run 50–950), `colorPalette` slots for all five of those palettes, three named text styles (`heading.page`, `heading.card`, `label.caps`), and a `table` slot recipe that applies the review's header treatment — uppercase letter-spaced headers, strong hairline, middle-aligned cells, and numeric right-alignment — to every `Table.Root` in the estate. See [Design library](https://help.stralos.app/internal/design-library.md) for the composition rules and per-component API. ### Typeface loading (ui 0.23.13) From ui 0.23.13, the five `@fontsource` typeface imports moved out of `Provider` and onto a separate `@stralos-co-nz/ui/fonts` subpath. A federated remote that bundles ui no longer carries font files. The application that owns the page (the host) is responsible for loading the typefaces once. `stralos-shell` imports this subpath in `main.tsx`, directly below the `bootstrapScrub` import: ```ts theme={null} import "./handoff/bootstrapScrub"; // must remain the first import import "@stralos-co-nz/ui/fonts"; ``` The fonts import must stay below `bootstrapScrub`. That module is the first thing `main.tsx` evaluates, and placing any import above it would push a third-party module ahead of the session-ticket scrub. `login-web` and `admin-web` each need the same import at their own entry point when they upgrade to ui 0.23.13 or later. A host that upgrades without adding the import will render without the suite's typefaces. ### Compact type scale (0.23.4) The suite uses a compact type scale. All token values sit below the browser's 16 px default — `md` (13 px) is the suite-wide text default, set via a global `body { fontSize: "md" }` rule so unstyled text matches sized controls throughout. | Token | Value | Notes | | - | - | - | | `xs` | 12 px | Small labels, footnotes | | `sm` | 12.5 px | Tight secondary text | | `md` | 13 px | **Suite default** — `body` inherits this token | | `lg` | 15 px | Section headings, prominent labels | | `xl` | 17 px | Page titles | | `2xl` | 20 px | | | `3xl` | 24 px | | | `4xl` | 32 px | Display | **Consumer rule:** use Chakra size tokens (`fontSize="md"`, `textStyle`, etc.) rather than hard-coded `px` values. A hard-coded value that matched the old default will appear oversized after the compact scale lands — the named token is the correct abstraction. ### Border radius Sharp geometry is a Stralos brand signature. Corner radii are intentionally small: `xs`–`md` map to 2 px and `lg`–`xl` map to 4 px. ### Focus ring The global focus ring is `2px solid {colors.teal.500}` with a 1 px offset, applied to every `:focus-visible` element. ### Colour palette slots and the `_light` key requirement Each palette block in `stralosConfig` provides eight `colorPalette` slots that Chakra's `Badge`, `Button`, and other components read: `fg`, `muted`, `subtle`, `emphasized`, `border`, `solid`, `contrast`, and `focusRing`. Slots whose values differ between light and dark mode are expressed as objects. Chakra's own built-in palette blocks key those objects with `_light` and `_dark`. Because `createSystem` deep-merges object values, a Stralos override that keys only `base` and `_dark` leaves Chakra's `_light` entry intact. The `:root, .light` rule then emits Chakra's value rather than the brand value, making the override appear unwritten on screen. The required shape for a conditioned slot is: ```ts theme={null} { base: "{colors.teal.50}", _light: "{colors.teal.50}", _dark: "{colors.teal.950}" } ``` `base` and `_light` must point at the same token. Scalar slots (`solid`, `contrast`, `focusRing`) replace Chakra's object outright and are not affected by this requirement. All five brand palettes (`navy`, `teal`, `green`, `orange`, `red`, `blue`, `gray`) follow this convention. `theme.test.ts` pins the conditioned slots for each palette through a real `createSystem` call and asserts that all three CSS emissions (`base`, `_light`, `_dark`) match the brand tokens. #### Teal palette fix (stralos-ui #137) Prior to this fix, the `teal` palette block keyed its conditioned slots (`fg`, `muted`, `subtle`, `emphasized`) with `base` and `_dark` only. Chakra's own `_light` block survived the merge, so `:root, .light` emitted Chakra's values. The most visible effect was `teal.muted`: the hover background of every teal outline and ghost control rendered as `teal.200` (stronger mint) in light mode instead of the brand's `teal.50`. The fix adds `_light` to all four conditioned teal slots, matching the convention already in place for the other palettes. The affected controls — teal outline buttons, ghost buttons, and any element reading `teal.muted` — now hover to the correct brand value in light mode. ### Tabular numerals `td`, `th`, and any element with `data-numeric` receive `font-variant-numeric: tabular-nums` globally. Money and quantity columns align in tables without per-cell styling. ## ErrorBoundary (`@stralos-co-nz/ui`) `ErrorBoundary` is a React class component that catches render errors in its subtree and shows a recoverable fallback card instead of white-screening the app. It is intentionally dependency-light so it can wrap shell routes and federated remotes as a per-remote isolation layer. ### Props | Prop | Type | Description | | - | - | - | | `featureName` | `string` (optional) | Names the affected area in the fallback heading, for example `Something went wrong in Rates`. Omit for a generic heading. | | `onError` | `(error: Error, info: ErrorInfo) => void` (optional) | Provider-neutral callback invoked when a render error is caught. Pass the shell's sanitising reporter here. | | `onRetry` | `() => void` (optional) | Called after the boundary resets when the user clicks **Retry**. Use this to re-trigger any data loads the failed subtree requires. | | `children` | `ReactNode` | The subtree to protect. | ### Behaviour * The fallback renders without a Chakra UI provider, so it is safe at the shell root and around federated remotes that may not have a Chakra context. * The fallback carries `data-ph-no-capture`; the shell's PostHog configuration blocks matching elements from session replay. * If `onError` throws, that reporter failure is swallowed. Console reporting occurs only when no `onError` callback is supplied. * Clicking **Retry** resets the boundary state and calls `onRetry` if supplied. The child subtree re-renders from scratch. > [!WARNING] > > `data-ph-no-capture` protects session replay only. The fallback renders > `error.message` to the user without sanitising it. Callers must ensure render > errors never carry credentials, capability tokens, or other sensitive values. > Telemetry sanitisation does not change the fallback text. ### Usage ```tsx theme={null} import { ErrorBoundary } from "@stralos-co-nz/ui"; import { captureClientException } from "./observability/posthog"; captureClientException(error, { source: "error_boundary", feature: "Rates", component_stack: info.componentStack ?? undefined, }) } onRetry={() => refetch()} > ``` ## Feature flag hook `useFeatureFlag` from `@stralos-co-nz/ui` reads flags through the shell's single PostHog instance. Remotes must not initialise their own SDK. ```tsx theme={null} import { useFeatureFlag } from "@stralos-co-nz/ui"; const { enabled, ready } = useFeatureFlag("example_feature", { fallback: false }); if (!ready) return ; return enabled ? : ; ``` The flag name above is an example. Create your flag in PostHog before shipping its consumer. | State | `enabled` | `ready` | | - | - | - | | Shell has not published a decision | Configured `fallback` | `false` | | Flag evaluation succeeds | Boolean value returned by PostHog; an unknown key is `false` | `true` | | Shell reports flags unavailable, subscription fails, or flag loading fails | Configured `fallback` | `true` | The hook subscribes to `window.__stralosPosthog` and `stralos:posthog-ready`, including later evaluations after identity changes. Successful refreshes can update an already-resolved flag. If the shell never publishes a decision, the hook remains loading; it has no independent timeout. Outside a browser it resolves to the fallback. Choose the fallback that is safe for the feature. An unknown key after a successful evaluation returns `false` even when the fallback is `true`. Flags control browser behaviour. API permission checks remain responsible for authorisation regardless of the flag value. The package also exports `FeatureFlagState`, `FeatureFlagOptions`, `FeatureFlagReader`, `FeatureFlagCallback`, and `FeatureFlagContext`. See [Feature flags](https://help.stralos.app/internal/observability.md#feature-flags) for the shell publication contract. ## Form feedback pattern (`@stralos-co-nz/ui`) `@stralos-co-nz/ui` ships a standardised set of components and hooks for form feedback: `useFormValidation`, `FormField`, `SubmitButton`, `notify`, `notifyValidationErrors`, `Dialog`, `DialogCancelButton`, `useDialogClose`, and `ConfirmDialog`. Use this pattern for new or migrated modal editors and calculator forms. See [Form feedback pattern](https://help.stralos.app/internal/form-feedback-pattern.md) for full API documentation and usage examples. ## AppFrame grouped navigation `AppFrame` accepts a `navigation` prop typed as `NavigationEntry[]`. A `NavigationEntry` is either a flat `NavigationItem` or a `NavigationGroup` — a non-navigating header that collects related items beneath it. Groups can nest: a group's `items` array accepts any `NavigationEntry`, so a feature section and its child destinations can live in one navigation surface. ### Types ```ts theme={null} export type NavigationItem = { /** * Owner-rendered navigation control. * When set, AppFrame renders this node in place of the routed button — the * owner is responsible for routing, active state, and accessibility. * Use this for controls like a workspace project picker that need to live * in the nav surface but are not a single destination link. * On mobile, the drawer closes only when an anchor element inside the * control is activated; a button click that does not navigate leaves the * drawer open. */ content?: ReactNode; label: string; /** Optional accessible name when the visible label is intentionally shorter. */ ariaLabel?: string; path: string; active?: boolean; scope?: "global" | "project"; /** Optional compact glyph used by vertical and mobile navigation surfaces. */ icon?: ReactNode; /** * A small trailing marker (a count, an AttentionBadge, a "New" chip). * The rail's accessible name is ariaLabel ?? label; include meaningful * badge information in ariaLabel so screen-reader users receive it. */ badge?: ReactNode; }; export type NavigationGroup = { label: string; /** Optional leading icon rendered beside the group label. */ icon?: ReactNode; /** * Owner-rendered control shown in place of the label text in the project rail and mobile * project menu (e.g. an estimate switcher heading the Estimate section). `label` still * names the group for assistive technology and is shown when the rail is collapsed. * Additive: when omitted, the label renders as before. */ headerContent?: ReactNode; /** * Owner-rendered control shown as the first row inside the group, under its label (e.g. the * estimate switcher beneath the Estimate heading). Hidden while the rail is collapsed; shown in * the mobile drawer too. Additive: when omitted, the group renders only its items. */ leadingContent?: ReactNode; scope: "global" | "project"; /** Nested groups allow feature sections and their child destinations to stay in one rail. */ items: NavigationEntry[]; }; export type NavigationEntry = NavigationItem | NavigationGroup; ``` `isNavigationGroup(entry)` is exported as a type guard. It returns `true` only when the entry has no `path` and carries an `items` array. A caller's item type that happens to carry its own `items` field still renders as an item because `path` takes precedence. ### Scope partitioning `AppFrame` partitions top-level entries by scope: * `scope === "global"` entries render as **Global navigation** (desktop header strip, mobile drawer). * All other entries render as **Project navigation** (desktop collapsible rail, mobile drawer). Items inside a group inherit the group's scope; their own `scope` field is ignored. ### Rendering — desktop Global navigation renders as a horizontal strip inside the sticky header. Flat items are routed buttons. Groups render as popover triggers whose content lists their items; nested groups remain available within that popover. Project navigation renders as a collapsible left rail (`