Frontend architecture

​

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.
• 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

​

Detection

• 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.

​

Reload on navigation

​

Reload banner

​

Navigation order

​

Legacy company-register redirects (M5)

​

Locations page

​

OrganisationLocation shape

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;
  };
};

​

Projects list routed actions

​

Project navigation (navigation M2)

• 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.

​

Delivery estimate nav links and the open estimate (PRD 210 §12.2)

​

Rate exception badge (PRD 04 M4)

• 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.

​

Project rail slots (shell)

​

Overview page

• 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).

​

Project selector behaviour

​

Destination resolution (projectDestination)

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).

​

Anchor rendering and modifier-click support

​

Persistent workspace chrome

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
};

​

Legacy route redirects (M3)

​

Route catalog

​

Generated JSON artifact

​

Drift test nav sources

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.

​

Command palette

​

Item source

​

Group headings

​

MVP navigation flag

​

Launcher

​

window.__STRALOS_NAV__ bridge

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

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
}

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<Record<string, NavigationBadge>>; // published navigation badges by route id
};

window.__STRALOS_NAV__?.setActiveContext?.({ estimateId });

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
}

type NavigationBadgeContext = { path: string; contextRevision: number }

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;

​

Project visit signal

• 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.

• 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

• 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.

​

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 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 (including ConstructionSpinner for long-running operations), the useFeatureFlag hook, and the AI copilot ChatPanel component group.
• @stralos-co-nz/maps-ui: Location picker (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)

import "@stralos-co-nz/ui/fonts";

​

Stralos theme (stralosConfig)

​

Typeface loading (ui 0.23.13)

import "./handoff/bootstrapScrub"; // must remain the first import
import "@stralos-co-nz/ui/fonts";

​

Compact type scale (0.23.4)

​

Border radius

​

Focus ring

​

Colour palette slots and the _light key requirement

{ base: "{colors.teal.50}", _light: "{colors.teal.50}", _dark: "{colors.teal.950}" }

​

Teal palette fix (stralos-ui #137)

​

Tabular numerals

​

ErrorBoundary (@stralos-co-nz/ui)

​

Props

​

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.

​

Usage

import { ErrorBoundary } from "@stralos-co-nz/ui";
import { captureClientException } from "./observability/posthog";

<ErrorBoundary
  featureName="Rates"
  onError={(error, info) =>
    captureClientException(error, {
      source: "error_boundary",
      feature: "Rates",
      component_stack: info.componentStack ?? undefined,
    })
  }
  onRetry={() => refetch()}
>
  <RatesPanel />
</ErrorBoundary>

​

Feature flag hook

import { useFeatureFlag } from "@stralos-co-nz/ui";

const { enabled, ready } = useFeatureFlag("example_feature", { fallback: false });
if (!ready) return <Skeleton />;
return enabled ? <NewFeature /> : <ExistingFeature />;

​

Form feedback pattern (@stralos-co-nz/ui)

​

AppFrame grouped navigation

​

Types

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;

​

Scope partitioning

• scope === "global" entries render as Global navigation (desktop header strip, mobile drawer).
• All other entries render as Project navigation (desktop collapsible rail, mobile drawer).

​

Rendering — desktop

​

Rendering — mobile

• Open top menu opens a start-edge drawer for global navigation.
• Open project menu opens a start-edge drawer for project navigation.

​

Accessibility

• The desktop project rail is labelled aria-label="Project menu" and contains a <nav aria-label="Project navigation">.
• The desktop header strip is wrapped in <nav aria-label="Global navigation">.
• An active item carries aria-current="page"; a group with an active descendant receives data-nav-group-active="true".
• Global group popovers are labelled aria-label="<group label> navigation".
• Each navigation link uses ariaLabel as its accessible name when set, falling back to label. Use ariaLabel when the visible label is deliberately short and a richer name (for example, including a status count or qualification) improves assistive-technology output. The visible text is always label regardless of whether ariaLabel is set. On collapsed desktop rail items, title is always set to label so hover tooltips show the short label rather than the longer accessible name.

​

Backward compatibility

​

Shell usage

​

Project rail slots (ui 0.75.1 and 0.75.2)

<AppFrame
  navigation={entries}
  projectSelector={<ProjectSelector />}
  projectNavigationHeader={<ProjectRailHeader project={project} />}
>
  {children}
</AppFrame>

const estimateGroup: NavigationGroup = {
  label: "Estimate",
  scope: "project",
  leadingContent: <EstimateSwitcherSlot />,
  items: estimateNavItems,
};

​

API base URL resolution

1. The module’s VITE_STRALOS_*_API_URL build-time variable.
2. The matching property in window.__STRALOS_API_URLS__.
3. The matching localStorage["stralos.<module>ApiUrl"] support override.
4. sameOriginFallback(devDefault).

​

Billing API (stralos-api-billing)

1. VITE_STRALOS_BILLING_API_URL build-time variable.
2. window.__STRALOS_API_URLS__.billing.
3. localStorage["stralos.billingApiUrl"] support override.
4. sameOriginFallback("http://localhost:3308").

​

Billing access boundary (BillingAccessBoundary)

• A first check with no previous answer, or a definitive failure (4xx other than 408 or 429, or a parsed but invalid response body), applies at once: the product is replaced with Billing is unavailable.
• A transient failure — a network rejection, timeout, 5xx, 408, 429, or JSON parse error — on a background poll after a known answer keeps that answer and schedules a retry in 10 seconds. Only three consecutive transient failures (~20 seconds) replace a known answer with Billing is unavailable.
• Any 200 answer, including a denial, always applies at once.

• An admin is never redirected to /settings/billing for subscription_required.
• No Manage billing link is shown, for any role.
• The read_only bar and the blocked screen name the contractor company, for example “Acme Contracting’s billing needs attention, so this company is read-only for now.” The blocked screen adds “Please ask an admin at Acme Contracting to check Settings → Billing.”

• The read_only bar is labelled “Free beta ended”. Admins see “Your 14-day free beta has ended. Please add a card to keep working in Stralos. Everything you’ve set up is safe.” with an Add a card link to /settings/billing. Members see “Your company’s free beta has ended. Please ask your admin to add a card. Everything you’ve set up is safe.” with no link.
• The blocked screen is titled Your free beta has ended, with “Please add a card to restore access.” for admins and “Please ask your admin to add a card to restore access.” for members, each followed by “Everything you’ve set up is safe.”
• An admin is redirected to /settings/billing once per sign-in, keyed on the stralos.auth.signInId stamp in localStorage. Reaching a billing recovery route, by the redirect or directly, records that stamp under stralos.billing.betaEndedShownFor, so the redirect does not repeat in that sign-in. With no stamp (storage blocked, or a session from before the stamp existed) there is no redirect; the banner link still goes to billing.

​

Projects setup lock

• isSetupLockedPath matches /projects and every path under /projects/. Those routes render the locked panel instead of the remote page.
• filterSetupLockedNavigation removes Projects entries from the global rail, and the command palette drops destinations whose path template is in the Projects area (isSetupLockedDestination).
• The locked panel is titled Projects open once setup is done. An admin sees “Projects need your office, a client company and at least one rate. Next, please add …” and a Do this next button to the next step’s page, taken from nextStep or else the first missing step in the order office, client, rate. A member sees “Your admin is still setting things up. Please ask them to add …”, listing the missing steps, with no button.
• Arriving at a locked path while the answer is being re-checked shows an empty busy area rather than the panel, so finishing setup and then opening Projects never flashes the locked panel.

​

Shell geocoding

​

window.__STRALOS_GOOGLE_MAPS__ seam

type GoogleMapsRuntimeConfig = {
  apiKey: string;
  mapId?: string;
  linzApiKey?: string;
  readonly countryCode?: string;
};

​

Auth contract

​

localStorage session keys

​

Employee support session notice

​

Non-production environment banner

​

Shell notices and AppFrame height

​

Login client configuration

{
  "auth": {
    "hostedDomain": "auth.dev.stralos.app",       // Cognito ceremony host; bare hostname
    "clientId": "1a2b3c4d5e6f7g8h9i0jklmnop",
    "loginOrigin": "https://login.dev.stralos.app" // full origin of the login host; controls the Security menu link
  }
}

​

Google Maps runtime configuration

{
  "googleMaps": {
    "apiKey": "<browser-safe API key>",  // required; whitespace-only values are rejected
    "mapId": "<Map ID>",                 // optional
    "linzApiKey": "<LINZ Basemaps key>"  // optional; enables the LINZ aerial layer
  }
}

​

Login email prefill (removed at IDP-M2)

​

Regional provider hints (removed)

​

Cross-bundle refresh bridge

window.__STRALOS_AUTH__.refreshAccessToken(): Promise<string | null>
window.__STRALOS_AUTH__.switchOrg(organisationId: string): Promise<SwitchOrgResult>
window.__STRALOS_AUTH__.refreshOrganisationNames(): Promise<boolean>
window.__STRALOS_AUTH__.clearSession(): void
window.__STRALOS_AUTH__.logout(): void
window.__STRALOS_AUTH__.signOut(): Promise<void>

• The session identity is captured before the async module import. If a teardown happens during that import, the identity will have changed and the method returns false without making a network call.
• After the fetch completes, the session identity is checked again. A response that arrived after a teardown-and-new-session is discarded.

• Retry the failed request at most once. A second 401 means the session is dead — clear the session (via clearSession if available, otherwise remove the three stralos.auth.* keys) and redirect to /login?reason=expired. Never trigger another refresh for that request. Skipping the clear causes a redirect loop.
• Never run a second refresher of your own alongside this call. A parallel refresher races the rotating refresh token and invalidates the session for every bundle.
• Do not call switchOrg while a refresh is in flight, and do not call refreshAccessToken while a switch is in flight. Both serialise through the same lock, so queuing is safe, but the caller must not assume the token state is stable between the two calls.
• Feature-detect each member before calling it. A member present on the StralosAuthBridge type but absent from the published object means the shell version pre-dates that member.

​

Organisation name in the app header (UI consistency review rule 1)

​

Organisation switcher (org-users-directory M3)

​

Behaviour

​

Failure states

​

Organisation labelling

1. If the AvailableOrganisation carries a non-empty organisationName, that name is used verbatim.
2. Otherwise it falls back to orgShortLabel() — the first eight characters of the organisation ID prefixed with Business ….

​

parseMemberships validation

• Rejects any entry missing a non-empty organisationId.
• Accepts organisationName only when it is a string with at least one non-whitespace character — a whitespace-only value is treated as absent and the field is omitted entirely.
• Accepts countryCode only when it is a two-uppercase-letter ISO 3166-1 alpha-2 string or explicit null. Any other value is omitted entirely.
• Normalises role to "admin" or "member" with a safe default.
• Falls back to "active" for status when the field is absent.
• Accepts viaContractorName only when it is a string with at least one non-whitespace character; otherwise the field is omitted. It is present only for a company the person reaches through a contractor company.

​

User menu rendering

​

Organisation name cache (organisationNames.ts)

​

Personal security settings

• When auth.loginOrigin is present and valid, the menu shows Security as a link to <loginOrigin>/security.
• When the key is absent, the menu item is hidden — not disabled. A deployment that has not yet set the key keeps sign-in and settings but loses this one menu item.

​

Email prefill on the step-up form

• The parameter is omitted entirely when the shell has no email address for the current session. ?email= (an empty value) is not written.
• URL.searchParams.set performs the encoding. A plus-addressed mailbox (user+tag@example.com) arrives as %2B rather than a literal +, which a form decoder would misread as a space.
• The URL is a navigation target only. It is not logged, not captured as an analytics property, and not stored. The anchor element carries data-ph-no-capture so session replay does not record the attribute value.
• The field is editable on the login host and is never auto-submitted. It is a convenience, not an automatic authentication step.

​

OAuth relying-party login (IDP-M1)

​

safeInternalPath open-redirect guard

​

IDP-M7c hand-off receiver

​

Bootstrap scrub and observability gate

​

Redemption and navigation

POST /api/login/auth/handoff
Content-Type: application/json

{ "token": "<JWS>" }

​

Hand-off outcomes

​

AI copilot chat panel (stralos-ui)

​

Estimate feature module structure

​

Layer assignment control

1. The focus work item (the item whose row was clicked to open the modal), if any.
2. All other work items and their eligible activity containers, grouped by the estimate’s own section headings in the outline’s order.
3. Unsectioned items last.

​

API client modules

​

Estimate feature load guard

​

Why a visit and not an id

​

useVisitGeneration(key)

const { visit, currentVisitRef } = useVisitGeneration(projectId);

​

useGuardedLoad(currentVisitRef)

const loadSummary = useGuardedLoad(currentVisitRef);

// Inside an event handler or effect:
loadSummary(
  visit,          // the visit the CALLER was created in
  () => fetchSummary(estimateId),
  (data) => setSummary(data),
  (err) => setError(err),
);

1. Refuse at issue time — if the caller’s visit differs from currentVisitRef.current, the load is not started. Checking only after the await would bump the shared token and cancel the current load before discarding the stale one.
2. Per-loader monotonic token — each issued request increments an internal counter. An earlier response from the same visit cannot overwrite a newer one.
3. Visit check on commit — the response is discarded if the visit changed while the request was in flight.

​

Activities feature module structure

​

Activities list scroll containment

• Rate sheets list and detail (shown together on one page)
• Activity rates and production profiles sections
• Sheet preview and the rate sheet refresh report

​

Activities calculator save model

1. Calls POST /activity-calculators (create) or PUT /activity-calculators/:id (update) with the geometry and, when changed, the name.
2. If any Used by choices are held (pendingRef), calls flushPendingAssignments to write only the applicable choices via PUT /activity-calculators/:id/links.
3. Closes the modal only when both steps succeed. A refused create leaves the estimator’s geometry on screen.

​

CalculatorAssignmentsDialog layout and warning behaviour

• "<Layer> is N% allocated; the other N% lands nowhere." — a partitioned stratum whose shares sum to less than 100%.
• "N m³ of <layer> is not allocated anywhere." — the engine’s own under-allocation report.
• "The reinstatement stack asks for N m³ more material than this excavation produces, so that much has to be bought in." — reuse exceeds available excavation volume.

​

Activities layer assignment control

​

Assignability states

• no-output — the layer is in the saved config and the engine emits a row for it, but the row carries no outputs (zero depth, or a bedding layer fully displaced by a pipe). The layer is saved; the geometry simply produces nothing.
• declared-only — the layer appears in the stored config but the engine emits no row for it at all (e.g. the engine could not derive a measurement from the current geometry). This is “saved but produces nothing”, not “not saved yet”.

​

All choices are held until Save

• applicable — the layer exists in the post-save vocab and the choice can be written. Pending clears (activityId: null) are applicable whenever the layer is still present.
• noQuantity — the layer is saved but the engine emits no row. The choice is not applied; the estimator is told which layer and why. The cell also shows this reason, but the modal that contains it closes on a successful Save, so the message is raised at the save boundary.
• missing — the layer no longer exists in the post-save config. The choice is silently dropped; a deleted layer’s links are gone with it.

​

layerPresence

​

Library calculator workbench routing

​

Calculator row ownership

​

Rates input formatting

​

Work-items-capture M2: pricing snapshot and autosave

• Live preview — computeWorkItemTotals from @stralos-co-nz/domain runs in the browser for each work item row. Component inputs carry the same materialised fields the server uses, so preview totals match server totals.
• Pricing snapshot (§5.0) — on each pricing change, toMaterialisedOverride builds a WorkItemPricingComponentOverride carrying rateOptionId, unitCost, pricedUnit and conversionFactor alongside the standard override fields, plus the PRD 04 provenance block (provenance, resolvedTier, resolvedLocationLabel, resolvedRule, resolvedRuleOutcome). The frozen pricedUnit and conversionFactor pair is owned by the atomic pricing-rule route. Generic autosave uses sparse PATCH /work-items/:id/pricing, which strips that pair and preserves the server’s stored values. density and materialPricingUnit are retired: the conversion is the chosen option’s own conversionFactor, and the priced unit is pricedUnit.
• Freeze rule — once a component has a persisted snapshot, its materialised fields are read verbatim from the snapshot rather than recomputed from live rate data. A re-pick or component edit drops the snapshot version so the next flush hydrates fresh values.
• Autosave — a debounced flush (~500ms) compares each work item’s next materialised state with lastSavedPricingRef, the last state the server accepted. It sends only changed client-owned component entries, explicit remove entries for components that have been deleted from the work item, and pricingSource only when that value changed. Components absent from the patch are preserved. A remove entry is sent only when the component itself is gone — a component that is merely absent from the current local snapshot does not trigger a remove. Only one flush runs at a time; a flush arriving while a prior one is in flight is queued. The snapshotDropVersionRef guards against a slow patch resurrecting a snapshot that was already replaced, and a successful atomic selection advances the same saved baseline.
• Input clamping — all numeric values are clamped to declared decimal-place scales via clampToScale before being passed to the domain helpers. This defends against RangeError from @stralos-co-nz/domain v0.2.1’s strict scaled-integer validation.
• Subcontract bid display (§4.5) — unit-rate bids use bidEffectiveAmountCents (half-up) for display totals; the raw per-unit rate is kept separately for the domain’s ranking logic.
• Explicit-pick unit-switch guard — selectInternalOptionWithResolutionAndSave ignores a stale conversion_missing mark only when a unit-switch caller is moving the row to the selected option’s own unit. toAtomicPricingSelection still judges the option against that target unit, so every other unpriceable selection remains blocked. WorkItemComponentPricingSelection declares the optional unit field sent by this atomic write.

​

Inline grid editor (InlineQuantity / InlineMarkup)

​

State model

• dirtyRef — set on the first keystroke; cleared on commit or revert. Gates the [value] prop-sync: a dirty cell ignores incoming prop updates so a background refresh cannot overwrite a live edit.
• propGenRef — incremented on every [value] effect run. A completing save checks whether the generation advanced during the await; if it did, the save does not rewind committedValueRef to the saved value because a fresher prop already landed.
• revertingRef — set by Escape before the blur it triggers fires, so the blur’s commit call exits early and the edited draft is not persisted.
• savingRef / saving — set during the async save. The input becomes readOnly while saving; aria-busy is set to "true".

​

Commit rules

• Blur and Enter both call commit.
• A blank field or a non-finite parse is treated as a revert to committedValueRef, not a zero-save.
• A value equal to committedValueRef is a no-op (no onSave call).
• InlineMarkup treats a blank field as null (inherit estimate default), not zero.

​

Grid keyboard traversal

​

Project settings feature module structure

​

API wire invariants

• Status is server-owned. upsertProject (PUT /api/global/projects/:id) never includes a status field. Status transitions go exclusively through transitionProject (POST /api/global/projects/:id/transition).
• Nullable-clear fields. endDate and colour on the project record, and specialConditionsNote on the contract profile, follow the nullable-clear pattern: an explicit null clears the stored value; omitting the key leaves it untouched.
• end_date_before_start_date 422. The server returns 422 with code: "end_date_before_start_date" when the submitted end date falls before the start date. ProjectSettingsPage surfaces this inline on the End date field and clears it when either date field is edited.
• Contract profile GET is 404-free. GET /api/global/projects/:id/contract-profile always returns a payload (with exists: false when no profile has been saved). The ContractBasisCard does not treat a missing profile as an error.
• Concurrent-write gate. A single busy flag (isSaving || pendingAction !== null) prevents a metadata PUT and a lifecycle transition POST running simultaneously. Both target the same project resource and their responses would race if concurrent.
• Companies register — role filter is mandatory. listClients sends ?role=client and getRatePreferenceCatalogues sends ?role=supplier. Omitting the filter returns all parties (clients, suppliers, and subcontractors) and silently fills the picker with companies that do not belong. The test in api.companies.test.ts pins this contract. A supplier is available for pricing only when isSupplier is true and the company status is active.

​

Project status label resolution

• Use resolveProjectStatusLabel whenever copy names a project lifecycle status. Pass the complete StatusLabelSource, including isFallback.
• Use formatStatusLabel for a status enum that has no authoritative display-name list and for unknown legacy values. If another status becomes setting-list-backed, add or use its domain resolver instead of flattening it with formatStatusLabel.
• Search the current source for resolveProjectStatusLabel and formatStatusLabel when auditing callers. That is the canonical caller inventory; a hard-coded list in this document would drift.

​

useSettingList broadcast to live consumers

​

Unit-catalogue presentation values

​

UnitCombobox component

​

Props

​

KeyCombobox component

​

Props

​

Where KeyCombobox is used

​

Relationship to shared SelectCombobox

​

GroupedSettingSelect component (removed)

​

Dashboard lifecycle stats (lifecycle M4)

​

Stats endpoint contract

// GET /api/global/projects/stats?window=30d|90d|12m
// GET /api/global/projects/stats?from=YYYY-MM-DD&to=YYYY-MM-DD
{
  countsByStatus: Record<string, number>; // non-archived projects only; absent = zero
  winRate: { window: string; won: number; lost: number };
}

​

Graceful degradation

• The pipeline funnel shows a dash (—) for every status count.
• The win rate tile shows Stats unavailable.
• The project list and active-estimate count are unaffected (they use a separate listProjects call).

​

Status label resolution

​

Win rate display rule

​

Calculator modals (@stralos-co-nz/calculator-ui)

​

Package source

​

Project schedule: M6 resource grading (stralos-feature-project-schedule)

​

Resource grading in the assignment drawer

• If the project has no requirements of the resource’s kind (person/plant) → recommended, no reasons.
• If at least one requirement of that kind lists the resource in its recommended array → recommended.
• Otherwise → other, with reasons taken from the requirement of the same kind that has the fewest reasons (the closest match). If the recommendation payload omits the resource entirely (e.g. inactive user) → other with an empty reasons array.

​

Project navigation

​

Current risk