# Starter experience contract The repository provides a runnable, domain-neutral application rather than only infrastructure contracts. The starter experience is intentionally replaceable at the page level while the shell, providers, boundaries, primitives, and state surfaces remain reusable. ## Runtime composition ```text validated config + coherent release manifest -> concrete adapters -> QueryClientProvider -> ApplicationProvider -> RouterProvider -> ThemeProvider -> SessionProvider -> AppShell -> lazy route boundary ``` Boot stops before product mount when configuration or release coherence fails. Each lazy page renders inside Suspense and a telemetry-aware route boundary. Route changes move focus to the new page heading; the skip link and landmarks remain stable in the shell. ## Registered routes The route list is `ROUTE_REGISTRY` (`src/features/installed-feature-contracts.ts`): the platform routes of `src/contracts/routes.ts` plus the routes of every installed feature. The platform overview page (`/examples/platform`) shows the composed list at runtime, so this document does not keep a copy of it. Navigation labels and order come from `ROUTE_REGISTRY`; the sidebar does not maintain a second route list. The client access decision never claims to be authorization. ## Authentication seam The session port exposes state subscription, sign-in start, sign-out, credential attachment, recovery, and unauthenticated notification. Credentials remain opaque to the application and presentation layers. - `demo`: local/development-only state transition with no credentials - `external`: delegates to `globalThis.__CA_FRONTEND_AUTH_OWNER__` - missing/invalid external owner: fails closed as `integration-failed` An external owner implements `readState`, `readSubject`, `subscribe`, `beginSignIn`, `signOut`, `attachCredential`, `recoverSession`, and `notifyUnauthenticated`. It owns token acquisition and storage. An owner that lacks any of these methods is rejected, and the session fails closed as `integration-failed`. `readSubject()` is required. The server-state cache is cleared only when the session state or the subject changes, so a token refresh for the same user keeps cached data. `readSubject()` must return: - an opaque, non-empty string that stays the same for one user across token refreshes and differs between users: the OIDC `sub` claim, Supabase `session.user.id`, or Firebase `user.uid` - `null` when nobody is signed in - never an access token, refresh token, or any other credential If `readSubject()` returns `null` or `""` while the owner reports `authenticated`, the runtime cannot tell a refresh from an account switch. It fails closed: every such notification clears server state, and each one records the `cache.operation.failed` diagnostic with `operation: SCOPE_FENCE` and `reason: SUBJECT_MISSING`. Seeing that diagnostic means the owner is not reporting its subject. The `demo` adapter reports one fixed demo user as its subject. Migration: `readSubject()` used to be optional. An owner written for an earlier release must add it; without it the owner is rejected at startup (the session becomes `integration-failed`) and a TypeScript owner no longer compiles against `ExternalSessionOwner`. A code path that implements `AuthSessionPort` or `SessionGateway` directly must add `getSubject()` the same way. ## Extending the starter New platform work should follow [routing, page templates, and reusable patterns](./routing-pages-and-patterns.md) and the [TypeScript, state, and data-flow target](./typescript-state-and-data-flow.md) rather than adding another independent route or data-loading convention. ### Replacing the starter screens `/` (`src/presentation/pages/home-page.tsx`) and `/examples/*` (`src/presentation/examples/`) are template content. Their own tests are the `tests/component/starter-*.test.tsx` files; delete them together with the screens. The platform's component tests (router, boundaries, shell, runtime tree) run on the pages of the test-only feature in `tests/helpers/fixture-feature.tsx` and keep passing when the starter screens change. Browser-level checks of the starter screens stay in `tests/e2e` and `tests/visual`. ### Ownership declarations Features, contexts and apps are discovered by `scripts/generate-product-feature-index.ts`. Each boundary declares only its parent, as exported string or integer literals the generator reads: | File | Exports | | --- | --- | | `src/apps//app-module.ts` | `APP_MODULE_ID`, `APP_MAX_CONTEXTS` | | `src/contexts//context-module.ts` | `CONTEXT_MODULE_ID`, `CONTEXT_APP_ID`, `CONTEXT_ROUTE_PATH`, `CONTEXT_MAX_FEATURES` | | `src/features//feature-module.ts` | `FEATURE_MODULE_ID`, `FEATURE_CONTEXT_ID`, `FEATURE_MODULE` | | `src/features//feature-runtime.ts` | `FEATURE_RUNTIME` (imported only by `feature-module.ts`, dynamically) | | `src/features//context-routes.ts` | `FEATURE_CONTEXT_ROUTES` | | `src/contexts//context-layout.tsx` (optional) | `CONTEXT_LAYOUT`, the context's own layout ("Product home and layouts") | The generator writes `src/.generated/` (git-ignored): the feature index the installed catalogs import, the context index the router loads lazily, and the selected app. Every build and check script runs it first; run it yourself with `corepack pnpm generate:feature-index`. It fails, naming the file, when: - a directory under `src/features/` has no `feature-module.ts` and no `NOT_INSTALLED` marker file (`src/features/local-draft-feature/NOT_INSTALLED` is the one intentional example); - a feature names an undeclared context, or a context an undeclared app; - a context or app exceeds its declared budget; - `VITE_PRODUCT_FEATURES` names a feature the app does not declare. The variable narrows the installed set here, before anything is compiled. ### Adding a feature 1. Create `src/features//feature-module.ts`. Build `FEATURE_MODULE` with `defineFeatureModule` (`src/features/feature-module.ts`). This is the feature's declaration, and it is in the initial chunk, so it holds data only: the declaration contract (routes, route runtime contracts, invalidation, topic versions and the external `contractPackages` the release manifest is checked against at boot), its message catalogs, and `loadRuntime`, which imports `feature-runtime.ts` dynamically. `src/features/reference-feature/feature-module.ts` is the complete example. 2. Create `src/features//feature-runtime.ts` with `defineFeatureRuntime`: the API contract (operations, schema metadata, runtime schemas, mappers), the adapter contributions (`defineFeatureAdapterContribution`, with `needs` naming the platform capabilities it receives) and the contract contributions. The router loads it (`application.features.load`) when one of the feature's routes is entered. Do not import it statically from anywhere: each feature would add its whole executable code to the initial chunk again, about 3.9 KB gzip (`tests/unit/feature-shape-growth.test.ts` bounds one feature at 1 KiB). An HTTP API is written once, as its contract contribution descriptor: it executes, and `check:registries` governs the FE-REG-API row projected from it (`projectApiOperationRows` in `src/contracts/api-operations.ts`). A product feature's contract contribution uses an `EXTERNAL_PACKAGE` source. `TEMPLATE_FIXTURE` belongs to `reference-feature` only and never joins the release contract set; the composer rejects it anywhere else. 3. Create `src/features//context-routes.ts` exporting `FEATURE_CONTEXT_ROUTES`. Page components are imported lazily here, and each route handle carries the route's params/search `codecs`; the owning context loads this file only when its route root is visited (`src/features/reference-feature/context-routes.ts`). Each handle's `routeId` must be a route of a feature contract in the same context; the context refuses the routes when they load, naming the route, context and features (`src/contexts/bounded-context-module.ts`). 4. Name the owning context in `FEATURE_CONTEXT_ID`. Use an existing context or add `src/contexts//context-module.ts` owned by the app. Every route path in the feature contract must sit at or under that context's `CONTEXT_ROUTE_PATH` and must not fall under another context's identical or more specific root: the router renders feature routes only inside the owning context. The app module refuses anything else when it loads, naming the route, feature and context (`src/apps/deployable-app-module.ts`). A route that takes over the platform home is the exception ("Product home and layouts"). 5. If the feature has application input, augment `ApplicationFeatureInputs` from the feature (`src/features/local-draft-feature/application/local-draft-api.ts`). 6. Run `corepack pnpm check:architecture`, `corepack pnpm check:types`, `corepack pnpm check:registries` and the tests. `tests/unit/two-feature-install-typecheck.test.ts` keeps the installed catalogs compiling with more than one feature. 7. Run `corepack pnpm test:sample-removal -- --feature=` to prove the product still builds and passes its gates without the feature. Files outside the feature directory. Everything else a feature needs is in `src/features//` and `tests/features//`. | File | When | What fails without it | | --- | --- | --- | | `src/.generated/*` | never by hand: every build and check script regenerates it | — | | `src/contexts//context-module.ts` | the feature needs a new context | `generate:feature-index`: `Feature belongs to undeclared context ` | | `src/contexts//context-layout.tsx` | the context needs its own frame instead of `AppShell` (see "Product home and layouts" below) | nothing: without it the context renders in `AppShell` | | `artifacts/tests/a11y-manual/.md` | every route the feature adds. Copy a record and reset it to `Status: pending-manual-review` | `test:unit` (`tests/unit/manual-a11y-evidence.test.ts`), `verify:documentation` (names the route IDs) and FE-GATE-009 (`review:a11y-manual -- --format-only`). FE-GATE-028 requires the signed review at release | | `tests/e2e/accessibility.spec.ts` | a route path has a parameter other than `:resourceId`, or a protected page cannot render while every API answers `[]` | `test:a11y` (FE-GATE-009): the spec fills in only `:resourceId` and answers every API with `[]` | | `src/bootstrap/product-composition.ts` (product-owned) | `needs` names a capability the template does not build: augment `FeaturePlatformCapabilities` and return the capability here. `indexedDb` is built as in `recipes/frontend-capabilities/indexeddb-feature-capability.ts`. Credentials for a product auth profile are returned here too | `check:types`; at runtime `feature needs , which the host did not provide` | | `src/contracts/product-contracts.ts` (product-owned) | a product auth profile or a product runtime-config key | auth profile: every gate that loads the operation, with `REST security profiles are incoherent for : unknown authProfileId …`. Config key: `check:types` where it is read | | `config/runtime/.json` | optional: a `FEATURE_OVERRIDES` entry switches the feature off | nothing | | `package.json`, the lockfile, `config/security/dependency-change-evidence.json` | the contract contribution imports a generated `@org-contracts/*` package as a production dependency | `generate:supply-chain` (in `check:bundle`): `high-risk dependency missing review: add:` | The central catalogs (`src/features/installed-*.ts`) and the registry governance file do not change: consumer directories there are globs over every feature (`src/features/*/adapters`, `config/contracts/registry-governance.json`). A route's params/search schema ids are checked against the schemas the feature registers, and its `loadingSurface` only has to be a kebab-case name, so a route with its own schema and loading surface needs no governance edit either. The registry baseline does not change either. New routes, API operations, schemas and invalidation topics, namespaces and edges are additive registry changes; `update:registry-baseline` or breaking evidence is needed only to remove or change a row or graph item. `tests/unit/second-api-feature-registries.test.ts` adds such a feature (an API operation, a route with its own search schema and loading surface, and an invalidation topic) to a copy of the repository and runs `check:registries` on it. Schema, operation, mapper, route and chunk ids and invalidation topics are global. Prefix them with the feature; `NoRequest` already belongs to the sample. MSW scenarios for the feature's own operations come from `createHttpScenarioHandler` (`tests/mocks/handlers/http-scenarios.ts`) with the feature's installed contract; the shared scenario catalog does not change. ### Product home and layouts A product whose home is a feature screen, or whose screens use a frame other than `AppShell`, declares it. The router and the catalogs do not change. - **Home.** A feature takes over the platform home by declaring a route with the id `APP_HOME` in its contract. The platform names the routes a feature may take over (`FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS` in `src/contracts/routes.ts`); any other platform route id is still a duplicate. Two features declaring `APP_HOME` fail when the catalogs load, naming both. The router mounts the route at its own path with the owning context, whatever that context's route root. Leaving the feature out of the build (`VITE_PRODUCT_FEATURES`) brings the platform home back; switching it off at runtime shows the disabled-feature page at its path. - **Layout.** A context with `src/contexts//context-layout.tsx` exporting `CONTEXT_LAYOUT` (a component) renders under that layout instead of `AppShell`. The generated index loads the file lazily, when one of the context's routes is entered. The router mounts the context at each registered path of its features under the layout, so an unknown URL still gets the not-found page in `AppShell`. Contexts whose layout files export the same component keep one layout instance when the user moves between them, so several route roots can share a layout. - **Accessibility.** The layout renders a skip link to `#main-content` and exactly one `
` around ``. The router moves focus there on every route change. Layout routes are siblings of `AppShell`, never inside it. - **Failures.** A layout chunk a deploy removed gets the reload-once recovery of a route chunk. Route and feature boundaries work as they do in `AppShell`. - The route root rule of step 4 spans every layout: a root takes the URLs under it whichever layout either context has. `tests/component/context-layouts.test.tsx` installs a product declared this way (`tests/helpers/fixture-layout-product.tsx`). ### Before shipping - Use the semantic tokens, UI primitives, and state surfaces before adding a project-specific variant. - Add component behavior, all-engine E2E, automated axe, and signed manual route evidence. Theme preference is the public `COLOR_SCHEME` storage contract. Authentication tokens and other secrets remain forbidden storage keys.