Frontend Data and State

Requirement A frontend MUST generate its client, types, schemas, and operation options from the API's published OpenAPI document.

Rationale A handwritten copy of a request, a response, or a schema drifts from the contract silently. A generated one turns a contract change into a compile error in every application at once.

Requirement A frontend MUST configure the generated client once, and route every read and write through it.

Rationale The client owns the base address, the credentials, the headers, and the mapping from a failure to a problem. A call that builds its own request opts out of all four.

Requirement The API MUST hold the browser session in an HTTP-only cookie, with frontend code holding no token.

Rationale Every value a script can read is a value any script on the page can read. The API runs the authorization code flow and keeps the tokens encrypted in the cookie. A refused sign-in lands on a signed-out page rather than on an error.

Requirement A client MUST send its marker header on every write, with the API accepting a cookie-authenticated write only when it carries that header.

Rationale A browser sends its cookie on a cross-site request on its own, so the header separates a page's write from a forged post. A page on another site cannot add a custom header without a preflight the API never grants. The name varies by project, so configuration owns it rather than code. The header has the form X-<Project>-Request with the value 1.

Requirement A frontend MUST convert every failure into one problem type, deciding from its code and showing its trace identifier in copyable form.

Rationale Displaying a raw response body leaks whatever the API includes and gives the reader no consistent recovery path. A code is a published identifier, so a page's decision survives a reworded message. The trace identifier lets support find the request the reader saw fail. It never serves as the headline.

Requirement A refusal MUST render beside the record or control that was refused, in the sentence the application holds for that code.

Rationale A refusal at the top of a page says that something failed, but not what. The application's own sentence says what was asked, and the code in the markup lets a test provoke it by name.

Example For example, borrowing an unavailable copy refuses with failure/lending.copy_not_available under result/borrow-copy.copy-unavailable. The page renders the application's sentence for that code beside the Borrow control, with the code in the markup so a test can provoke it by name.

{#if refusal?.code === 'failure/lending.copy_not_available'}
  <RefusalNotice code="failure/lending.copy_not_available">
    This copy is already on loan.
  </RefusalNotice>
{/if}

The sentence comes from the application's dictionary rather than the response body, and the trace identifier stays in the detail in copyable form.

Requirement A field problem MUST reach the field it names through the frame's one helper, with the form staying open until resolved or abandoned.

Rationale A list of problems above a long form makes the reader read each sentence and each label to pair them.

Requirement A form MUST validate against the generated schema for its request body, extended with the application's own rules rather than replaced by them.

Rationale The generated schema is the contract, so it holds even where the browser accepts more. An extension adds the required message and any rule the contract cannot express.

Requirement A successful command MUST invalidate every query whose answer it changed, and no other query.

Rationale The query cache owns freshness, so a command that changes a record and leaves its cache entry shows the old record until something else refetches. An unrelated invalidation costs a request per affected page.

Example The generated client in packages/api/src/generated/sdk.gen.ts holds both sides of one write. The loans route calls borrowCopy({ copyId: 'copy-1' }), and the list reads through listLoans.

export const borrowCopy = (options) => (options.client ?? client).post({
    url: '/api/lending/borrow-copy',
});

export const listLoans = (options) => (options.client ?? client).get({
    url: '/api/lending/list-loans',
});

After borrowCopy succeeds, the page invalidates the listLoans query and no other query, so the list shows the new loan without refetching unrelated pages.

Requirement A value MUST live with the narrowest owner that can hold it: server data, then the address, then form state, then the component's own state.

Rationale A store placed above that order makes unrelated components re-render and hides where a value changes.

Requirement A value naming a person MUST travel in a request header rather than the query string, with the contract declaring the header each operation reads.

Rationale A query string is written into a proxy log, the browser history, and the referrer of whatever the reader opens next. The address keeps its own copy, so a filtered list stays a link somebody can share.

Requirement A page MUST offer a command from the session Actor's Permissions at the record's scope, with the API deciding every command.

Rationale Permissions are the project's Permission records: an Actor holds a Role at a scope, a Role allows Permissions, and a use case needs Permissions. The page reads the Actor's permission codes from the session the API returns for the signed-in Actor. The page avoids offering what would be refused, and the API refuses what is offered in error. A page hiding a control nobody may use makes the surface look thinner than the product is.

Requirement A formatter rendering a timestamp MUST receive an explicit IANA time zone, resolved by the caller from the record the screen shows.

Rationale An instant read out of the API carries no zone, so an implicit one would show a dispatch cut-off time in the reader's own city. A record with its own zone states it. Otherwise the account's zone applies, and an account that chooses none falls back to UTC.

Requirement A frontend MUST NOT store a refresh token, a provider secret, or a privileged credential in browser storage or a browser-visible variable.

Rationale Local storage, session storage, IndexedDB, and a build-time public variable can be read by any script on the page. A preference a reader chooses is not a secret and may be stored under a named key in the frame.

Requirement An optimistic update MUST declare its stable client identity, its conflict behavior, its failure rollback, and its reconciliation path.

Rationale Money, irreversible actions, and uncertain authorization wait for the server result instead.

Requirement An optimistic update MUST announce its reconciled outcome through a live region when the server result differs from the value shown.

Rationale A rollback is a silent visual change. A reader using a screen reader hears the optimistic value announced, and nothing tells them it is withdrawn. The ARIA live-region technique is the mechanism, and a test of the route asserts the announcement.

Requirement Copy MUST resolve through locale dictionaries with fill and plural support, one chunk per language, and typed keys with a declared fallback.

Rationale A second copy of one sentence in two components drifts at the first rewording. A dictionary per language keeps one sentence in one place, and a key the catalog lacks fails where the fallback says it fails.

Example A workspace may carry its own dictionary machinery when it meets the same contract.