# 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. ### 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` | 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 twice: its API contract operation (V2) is what `check:registries` governs, and its contract contribution descriptor (V3) is what executes. `tests/unit/http-operation-v2-v3-parity.test.ts` fails when one exists without the other or when they disagree. 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`). 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`). 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: | 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.