# 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`, `subscribe`, `beginSignIn`, `signOut`, `attachCredential`, `recoverSession`, and `notifyUnauthenticated`. It owns token acquisition and storage. The owner may also implement `readSubject()`. 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, such as a hashed account id - `null` when nobody is signed in - never an access token, refresh token, or any other credential Without `readSubject()` (or when it returns `null` or `""` while authenticated), the runtime cannot tell a refresh from an account switch, so every notification from an authenticated owner clears server state. This is the safe default. The `demo` adapter reports one fixed demo user as its subject. ## 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. ### 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//context-routes.ts` | `FEATURE_CONTEXT_ROUTES` | 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`): the feature's contract (routes, route runtime contracts, API operations, invalidation, schemas, runtime schemas, mappers), its adapter contributions (`defineFeatureAdapterContribution`, with `needs` naming the platform capabilities it receives), its runtime descriptor (route codecs), its message catalogs and its contract contributions. `src/features/reference-feature/feature-module.ts` is the complete example. 2. Create `src/features//context-routes.ts` exporting `FEATURE_CONTEXT_ROUTES`. Page components are imported lazily here; the owning context loads this file only when its route root is visited (`src/features/reference-feature/context-routes.ts`). 3. Name the owning context in `FEATURE_CONTEXT_ID`. Use an existing context or add `src/contexts//context-module.ts` owned by the app. 4. If the feature has application input, augment `ApplicationFeatureInputs` from the feature (`src/features/local-draft-feature/application/local-draft-api.ts`). 5. 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. 6. 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: | File | Change | | --- | --- | | `src/.generated/*` | regenerated automatically | | `src/contexts//context-module.ts` | only when the feature needs a new context | | `config/runtime/.json` | optional `FEATURE_OVERRIDES` entry to switch the feature off | | `src/bootstrap/runtime-adapters.ts` | only when `needs` includes `indexedDb`: add the capability, built as in `recipes/frontend-capabilities/indexeddb-feature-capability.ts` | 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`). ### 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.