toga-ai 1.0.612 → 1.0.613

package/knowledge/2.0/standards/frontend.md

@@ -0,0 +1,629 @@
+---
+title: Front-End (React) Coding Standards
+framework: "2.0"
+project: _Underscore
+client: shared
+type: standard
+status: active
+updated: 2026-08-18
+owners: [jcardinal]
+files: []
+related:
+  - ../apps/toga25-supply/architecture.md
+  - ../apps/toga-blox/architecture.md
+  - frontend-deploy.md
+  - backend-php.md
+---
+
+## Scope & how to read this document
+
+This is the coding standard for **any React app on the 2.0 platform** — not a spec for any one
+product. It is layered by altitude, and each rule carries a strength marker so you know how far to
+trust it:
+
+- **MUST / SHOULD** — the practice **converges across both reference apps** (`toga25-supply` and
+  `toga25-desk`) or is a hard platform requirement. Treat it as team law.
+- **Reference pattern (desk-only, n=1)** — only one app has worked this out so far. Present tense:
+  "here is a well-built pattern to reuse," **not** "the team requires this." A second consumer
+  promotes it to MUST/SHOULD; until then, copy it with your eyes open.
+
+The three parts:
+
+- **Part 1 — Universal React / TypeScript.** Portable to any React app anywhere.
+- **Part 2 — TOGA 2.0 platform conventions.** What consuming the shared 2.0 stack requires.
+- **Part 3 — Open items.** Described and flagged, **not** prescribed as settled.
+
+Evidence was mined from `@agilant/toga-blox` (repo `toga-blox-npm`), `toga25-supply`, and
+`toga25-desk`. Where a claim was checked against source, it is stamped (e.g. "Verified 2026-08-18").
+Anything about env files, build mode, Amplify, the per-environment blox channel, or
+`--legacy-peer-deps` is owned by **`frontend-deploy.md`** and is only cross-referenced here.
+
+---
+
+# Part 1 — Universal React / TypeScript standards
+
+*(Portable to any React app. Convergent unless a rule is tagged as a reference pattern.)*
+
+## 1. Project structure & module organization — **MUST / SHOULD**
+
+**MUST: organize feature-first.** A page folder colocates the page's view, its data hook, its
+sub-components, and its CSS. Do not spread one screen's files across parallel `components/`,
+`hooks/`, `styles/` trees by type — group by feature.
+
+**MUST: split the view-model hook from the dumb view.** A `use<Feature>()` hook owns **all**
+fetching, mutation wiring, and derived state, and returns a **flat presentational shape**; the
+component just renders that shape. The two apps name the hook differently but the shape is
+identical — `toga25-supply` uses `use*PageViewModel` in a `viewModel/` folder beside the page
+(verified: `toga25-supply/src/pages/<Entity>/viewModel/`); `toga25-desk` uses `use<Feature>` beside
+the page. Either name is fine; the split is the rule.
+
+```
+pages/
+  Orders/
+    Orders.tsx                 // thin view — renders what the hook returns
+    viewModel/
+      useOrdersPageViewModel.ts // owns fetching + derived state, returns a flat shape
+    components/                // sub-components used only by this page
+    Orders.module.css
+```
+
+**MUST: keep the top-level layers separated by dependency direction.**
+
+- `api/` — pure request functions. **Imports nothing from React.** No hooks, no components.
+- `lib/` — framework-agnostic helpers and the query client (also React-free).
+- `components/` — reusable presentational primitives.
+- `routes/`, `theme/` — routing table and design tokens.
+
+**SHOULD: treat `.ts` vs `.tsx` as a deliberate Fast-Refresh boundary.** Pure data/wiring modules
+stay `.ts` with **no JSX**, so `react-refresh` never invalidates them on an unrelated edit. A file
+that must export *both* a component and a hook (a context/provider module) breaks the
+one-export-kind rule on purpose and carries an explicit opt-out:
+
+```ts
+// eslint-disable-next-line react-refresh/only-export-components
+export const useAuth = () => useContext(AuthContext);
+```
+
+**SHOULD: use barrels sparingly.** An empty or pass-through barrel is scaffolding noise — add one
+only when it earns its keep by hiding a genuinely multi-file module behind one entry point.
+
+## 2. TypeScript configuration — **MUST**
+
+**MUST: strict, with project references.** The root `tsconfig.json` references
+`tsconfig.app.json` + `tsconfig.node.json`. Verified 2026-08-18: `toga25-supply` and `toga25-desk`
+ship the **identical** app-config flag set — the two files differ only in whitespace.
+
+```jsonc
+// tsconfig.app.json — the enforced set (both apps, verbatim)
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "erasableSyntaxOnly": true,
+    "noUncheckedSideEffectImports": true,
+    /* strictness */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    /* alias — mirrored in the bundler */
+    "baseUrl": ".",
+    "paths": { "@/*": ["src/*"] }
+  }
+}
+```
+
+**MUST: the `@/*` alias is declared in BOTH the tsconfig and the bundler** (`vite.config.ts`
+`resolve.alias`). A path alias that exists in only one of the two type-checks-but-won't-build (or
+the reverse). Keep them in lockstep.
+
+## 3. State management doctrine — **MUST** (high-value)
+
+There are exactly **three homes** for state, and they do not overlap. Verified 2026-08-18 across
+both apps.
+
+| Home | Holds | Never holds |
+|---|---|---|
+| **React Query** | ALL server / async state | anything you can compute locally |
+| **Zustand** | a MINIMAL durable client/session slice — current user, tenant/hostname identity, theme | server data of any kind |
+| **`localStorage`** | losable pure-UI preferences — collapsed sections, pins, lock state | anything that must be correct, anything server-owned |
+
+- **MUST: one `QueryClient` at module scope.** Constructed once (`const queryClient = new
+  QueryClient({...})`), not inside a component. Verified in both `App.tsx`.
+- **MUST: server data never lives in Zustand.** If it came from the API, it belongs in React
+  Query's cache so invalidation and refetch work. Zustand is for identity and preference only.
+- **SHOULD: clear the query cache on auth transitions** so a new session never inherits the prior
+  user's cached rows (login, logout, tenant switch). See §12 and §18.
+
+**Reference pattern (desk-only, n=1): namespace `localStorage` keys per tenant + user.**
+`toga25-desk` writes UI-preference keys as `app:{clientUuid}:{userId}:key` so one tenant's or one
+user's pins/collapse state can never surface under another's. The **principle — namespace
+tenant-scoped client storage so it cannot bleed across tenants (SHOULD, see §18)** — is what you
+adopt; the exact key shape is the reference implementation to copy or improve.
+
+## 4. Data fetching with React Query — **MUST / SHOULD**
+
+**MUST: the per-page view-model hook owns fetching** (§1). Components do not call the API directly.
+
+**MUST: set cache policy by data kind.**
+
+| Data kind | `staleTime` / `gcTime` | `retry` | Invalidation |
+|---|---|---|---|
+| session-immutable reference data (enums, table meta) | `Infinity` | `false` | none needed this session |
+| editable records | short `staleTime` | default | invalidate on mutate |
+| global defaults | — | `1` | `refetchOnWindowFocus: false` |
+
+```ts
+const queryClient = new QueryClient({
+  defaultOptions: { queries: { retry: 1, refetchOnWindowFocus: false } },
+});
+```
+
+**SHOULD: fetch with React Query, not react-router data APIs.** Both apps **deliberately avoid**
+router `loader`/`action`/`useLoaderData`; data flows through React Query so caching, invalidation,
+and optimistic updates live in one system. Do not mix the two paradigms.
+
+**Reference pattern (desk-only, n=1): optimistic + failure-tolerant preference persistence.** For
+losable UI prefs, `toga25-desk` mutates local state optimistically, fires the persist
+request-and-forgets, and on failure **keeps the optimistic state** plus a `console.warn` (a failed
+pin write must not throw the user out of what they were doing); it also write-throughs to
+`localStorage` so the very first paint is already correct. Reuse this shape for *preference* state
+only — never for records that must be server-authoritative.
+
+## 5. URL as the source of truth for view state — **MUST (as a principle)**
+
+**MUST: table view state lives in the URL.** Pagination, sort, filters, and column state go in the
+query string so a view is shareable and back-button-safe. Both apps do this.
+
+**The exact URL grammar is app-specific — the team does NOT yet mandate one.** The two apps encode
+it differently, and both are presented here as reference examples, not as the standard:
+
+- `toga25-supply` — a **slug-namespaced grammar**: `{slug}_page`, `{slug}_sort[i]`, and filter
+  operators like `_starts` / `_ends` / `_between` / `_min` / `_max`. (See
+  `../apps/toga25-supply/features/column-visibility.md` and `meta-driven-table-data.md`.)
+- `toga25-desk` — **literal-comma CSV params**: `cols`, `sort`, `q`.
+
+A single grammar may be standardized once a second app validates one; until then, match the app
+you are in.
+
+**The convergent sub-rules that ARE worth standardizing now — MUST:**
+
+- **Distinguish an ABSENT param from a PRESENT-but-empty one.** "Filter not set" and "filter
+  explicitly cleared" are different states. Use `searchParams.has(key)`, not a truthiness check on
+  the value.
+- **A param that changes the query result MUST be part of the React Query key.** Page, sort, and
+  filters belong in the key so a change refetches (and resets to page 1).
+- **A presentation-only param MUST be excluded from the key.** Column visibility changes what you
+  see, not what the server returns — putting it in the key forces a pointless refetch. (See
+  `../apps/toga25-supply/features/column-visibility.md`.)
+
+**Reference pattern (desk-only, n=1):**
+- To keep **literal commas** in `cols`/`sort`, write the URL via `useNavigate({ search })`, not
+  `setSearchParams` (which percent-encodes commas into `%2C`).
+- A **debounced-commit** text box for `q`, with a **back/forward reseed guard** so a browser
+  navigation re-seeds the input without the debounce clobbering the restored value.
+
+## 6. Routing — **MUST / SHOULD**
+
+**MUST: `createBrowserRouter`.** Both apps use the data-router.
+
+**MUST: one source of truth for path strings.** No bare path literals scattered at call sites.
+`toga25-supply` centralizes them in a `ROUTE_REGISTRY`; `toga25-desk` uses `src/routes/paths.ts`
+with a `pathForRouteKey` resolver. Pick one shape per app and route every link/navigate through it.
+
+**SHOULD: guard wraps layout; layout carries the error boundary.** An auth-guard route **wraps** the
+layout route, and the layout route sets an `errorElement` with a defensive fallback that reads
+`useRouteError()`. A thrown render error lands on a real page, not a white screen.
+
+**SHOULD: flat, kebab-case, single-segment routes by default.** Nest only for a genuine section
+(e.g. a settings area with its own sub-nav), and give a nested section an **index redirect** to its
+default child. Always define a **catch-all** route.
+
+**Reference pattern (supply-only, n=1): resolve ACL-permitted routes *inside* the layout
+outlet** so the router instance stays stable across tenant/ACL resolution. `toga25-supply` builds
+the permitted route set inside the layout rather than rebuilding the router when the tenant or ACL
+resolves — rebuilding the router remounts the tree and drops in-flight view state. Reuse this if
+your permitted routes depend on async identity.
+
+## 7. Forms — **SHOULD**
+
+Both apps use **react-hook-form**; this is the convergent forms library.
+
+- **SHOULD: `useForm` under a `<FormProvider>`.** Field components read context via
+  `useFormContext()`.
+- **SHOULD: hydrate from query data with `reset()` in an effect keyed on the record id** — so
+  loading a different record re-seeds the form and an in-flight edit is not silently carried over.
+- **SHOULD: `mode: "onChange"`** where live validation is wanted.
+- **SHOULD: submit via `handleSubmit(onValid, onInvalid)`** — handle the invalid branch explicitly;
+  do not let a failed validation submit silently.
+
+```tsx
+const form = useForm({ mode: "onChange" });
+useEffect(() => { form.reset(recordData); }, [record.id, recordData]); // re-seed per record
+// ...
+<form onSubmit={form.handleSubmit(onValid, onInvalid)}>
+```
+
+**Reference pattern (desk-only, n=1):**
+- A `<Controller>` wrapping a **typeahead select** so the **form value stays a scalar id** while the
+  widget displays and searches by name — the persisted value is the FK, the UI is the label.
+- An **app-side named-validator layer**: a `{ email, phone }` regex map applied through RHF
+  `setError` / `clearErrors`. This exists **only because** the shared input component exposes no
+  validator passthrough (see Part 2 §22). It is a workaround, not an aspiration — if/when
+  `BaseInput` gains a validator prop, this layer goes away.
+
+## 8. Theming & design tokens — **MIXED (layer carefully)**
+
+**Universal / convergent — SHOULD: layer your tokens semantically.**
+Raw scales → semantic aliases (`--ink-*`, `--action-*`, `--status-*`) → components reference **only**
+the semantic layer. No hex literal, and no raw-scale reference, appears at a component call site. A
+central record-kind / identity map means no icon or color literal is inlined per entity either.
+
+**Universal — SHOULD: dark mode is a color swap and nothing more.**
+- Light tokens live on **bare `:root`**.
+- Dark is a **grouped selector that out-specifies `:root`** — `html.dark, :root.dark, .dark { … }`.
+  A `:where(.dark)` selector sits at specificity 0 and **loses** to `:root`; do not use it for the
+  dark block.
+- Dark **redeclares colors only.** Type, spacing, radii, and motion are shared and defined once —
+  never re-stated in the dark block.
+- **Restate the semantic aliases inside the dark block** so a document-level `.dark` and a
+  subtree-level `.dark` behave identically.
+
+```css
+:root { --ink-1: #1a1a1a; --action: #2563eb; }        /* light on bare :root */
+html.dark, :root.dark, .dark {                          /* out-specifies :root */
+  --ink-1: #f4f4f5; --action: #60a5fa;                  /* colors only — no spacing/type here */
+}
+```
+
+**Reference pattern (desk-only, n=1): the no-flash theme boot.**
+- A pre-paint inline `<head>` script sets `html.dark` **before React mounts**, so there is no
+  light-then-dark flash.
+- The theme store is **initialized FROM the DOM class** already set by that script — it does not
+  recompute-and-reapply on mount (recompute-on-mount is exactly what causes the flash).
+- A **module-scope `matchMedia` listener** (not a React effect) tracks the OS preference, which is
+  StrictMode-safe and fires once.
+
+**Layering note (do not misfile):** the requirement that a **host app define a full
+`--baseInput-*` / `--field-*` token set** is **not** universal theming — it is a *blox-consumption*
+requirement and lives in **Part 2 §13**. Here, only note the general truth: a shared component may
+require the host app to supply a token layer.
+
+## 9. Reusable UI primitives & interaction — **Reference pattern (desk-only, n=1)** for the primitives; **Universal** for the a11y contract
+
+The concrete primitives below are worked out in `toga25-desk` alone — reuse them as well-built
+patterns, not as team law. The **a11y contract each one implements is universal (see §10).**
+
+- **Anchored popover primitive** — portals to `document.body`; computes position in
+  `useLayoutEffect` **before paint** with `visibility: hidden` until measured (never render a
+  flash at `0,0`); repositions on scroll/resize; closes on outside-click / Escape and **restores
+  focus to the anchor**.
+- **A deliberate role contrast:** a **roving-focus `role="menu"`** (arrow keys rove over
+  `role="menuitem"`, one tab stop) versus a **focus-trapped `role="dialog"` / `role="alertdialog"`**
+  (Tab cycles within). Pick by semantics: a menu roves, a dialog traps.
+- **An imperative `await useConfirm({ … })` promise API** for confirmations — the caller awaits a
+  boolean instead of threading `isOpen` state through the tree.
+- **One shared body across a desktop popover and a mobile sheet** via a `roving` prop, so the two
+  presentations share behavior and markup.
+
+**Flag:** the focus-trap logic is duplicated across the dialog primitives — a candidate
+`useFocusTrap` hook to extract once a second consumer needs it.
+
+## 10. Accessibility — **SHOULD**
+
+ARIA here is **hand-rolled and must be correct**. When you build an interactive primitive, wire the
+full contract:
+
+- Triggers: `aria-haspopup`, `aria-expanded`.
+- Roles: `menu`/`menuitem`, `dialog`/`alertdialog`, `tablist`/`tab`, and `aria-modal` on modals.
+- Labelling: `aria-labelledby` / `aria-describedby`; `aria-current="page"` on the active nav item;
+  `aria-pressed` on toggles.
+- Live regions: `aria-live="polite"` on toasts.
+- Keyboard & focus: roving `tabindex`, focus traps in dialogs, focus restoration on close, Escape
+  to dismiss.
+- `aria-hidden` on decorative icons.
+
+**GAP (see Part 3): a11y is convention-only, not lint-enforced.** Verified 2026-08-18: **no**
+`eslint-plugin-jsx-a11y` is configured in `toga25-supply`, `toga25-desk`, or `toga-blox-npm`.
+Adopting it is recommended so these conventions are checked mechanically rather than by reviewer
+memory.
+
+## 11. Build & tooling — **MUST / SHOULD**
+
+- **MUST: Vite + `@vitejs/plugin-react`**, with the `@ -> ./src` alias mirroring the tsconfig
+  (§2). Verified 2026-08-18 in both `vite.config.ts`.
+- **MUST: `resolve.dedupe` forces a single copy of React and any heavy shared peer** that a
+  linked/external library also ships. State the **principle**: dedupe `react` + `react-dom` **plus
+  every peer your component library provides context or hooks for**. The exact members are per-app
+  because they follow that app's shared-lib surface — verified 2026-08-18:
+
+  ```ts
+  // toga25-supply/vite.config.ts
+  dedupe: ["react", "react-dom", "@tanstack/react-table"]
+  // toga25-desk/vite.config.ts
+  dedupe: ["react", "react-dom", "react-hook-form"]
+  ```
+
+  Supply dedupes the table lib (it consumes blox's table context); desk dedupes react-hook-form (it
+  consumes blox's `BaseInput`, which reads `useFormContext()`). See §13(c) for why a second copy
+  silently breaks blox's hooks.
+- **MUST: one env-read chokepoint.** Read `VITE_API` in exactly **one** module (see §17). Verified:
+  both apps read it (plus a per-host override) only in `src/api/api.ts`.
+- **SHOULD: ESLint flat config**, verified identical in both apps:
+
+  ```js
+  export default defineConfig([
+    globalIgnores(["dist"]),
+    { files: ["**/*.{ts,tsx}"],
+      extends: [ js.configs.recommended, tseslint.configs.recommended,
+                 reactHooks.configs.flat.recommended, reactRefresh.configs.vite ] },
+  ]);
+  ```
+- **SHOULD: tab indentation in source.** This repo family indents source with **tabs** (verified;
+  see `../apps/toga25-supply/architecture.md`) — a string-replace edit that assumes spaces will
+  miss. (The ESLint config files themselves are 2-space, but application source is tabs.)
+- **MUST: never commit secrets** — see the committed-`.npmrc` violation in Part 3.
+
+## 12. Client-side auth & security — **MIXED (layer carefully)**
+
+**Universal / convergent — SHOULD: tokens in `localStorage`, eyes open.** The 2.0 backend is
+deliberately **Bearer-token, with no cookie session**, so the client stores the token in
+`localStorage`. Acknowledge the tradeoff honestly: this accepts an XSS token-exfiltration exposure
+that an `HttpOnly` cookie would not. Given that, **never log a token, never place it in a URL or an
+error payload,** and keep the XSS defenses of §10/Part-1 tight.
+
+**SHOULD: logout clears auth state + the query cache, but NOT the world.** On logout, clear auth
+state and call `queryClient.clear()` so the next user does not inherit cached rows. Do **not**
+blanket-`localStorage.clear()` — that also wipes UI preferences. **Honest divergence:**
+`toga25-desk` preserves prefs on logout; `toga25-supply` currently blanket-clears. This is a known
+inconsistency; **the preserve-prefs behavior is the recommended one.**
+
+**Reference pattern (desk-only, n=1): classify a login failure.** `toga25-desk` sorts a failed
+login into **network / credentials / server** by HTTP status + API error code, and messages the
+user accordingly. `toga25-supply` deliberately does **not** classify — so this is a recommendation,
+not a convergent rule.
+
+**Platform-coupled — SHOULD (conceptually Part 2): field-limit every request.** Send an explicit
+`fields` list so an unfielded FK expansion cannot pull sensitive columns (a bcrypt hash, an LDAP
+DN) into the client. This is coupled to api2 serialization — see Part 2 §16.
+
+**Reference pattern (supply-only, n=1): gate cache clears behind restoration.** If you **persist**
+the React Query cache (supply does, via `PersistQueryClientProvider` +
+`createSyncStoragePersister` — verified 2026-08-18), a `queryClient.clear()` that races a late
+`restoreClient()` can be silently undone. Gate every clear behind an `awaitRestoration()` promise
+so restoration cannot resurrect a cleared cache.
+
+---
+
+# Part 2 — TOGA 2.0 platform conventions
+
+*(Consuming the shared stack. These are platform requirements, not portable advice.)*
+
+## 13. Consuming `@agilant/toga-blox` — **MUST**
+
+`@agilant/toga-blox` is the front-end shared core — the React analog of `_underscore` / `library`
+on the back end. A consuming app **MUST** meet every requirement below.
+
+**(a) Pin an exact published version — never a caret.** Some published versions ship an **empty
+`dist`** and break the build; a caret can float you onto one. Both apps pin exact versions
+(verified 2026-08-18: supply `1.0.330-sandbox-client.128`, desk `1.0.328-sandbox-client.125`).
+
+**(b) Declare blox's peer deps that do not hoist into your app.** blox lists them as peers, so npm
+will not necessarily install them for you: verified 2026-08-18 they include `react-hook-form`,
+`@tanstack/react-query`, `@tanstack/react-table`, `framer-motion`, `react-router-dom`, and `axios`
+(pinned exactly by blox at `1.8.4`). A missing peer surfaces as a runtime "undefined is not a
+component," not a build error.
+
+**(c) Dedupe `react` / `react-dom` (+ `react-hook-form` / `@tanstack/react-table`) to a single
+copy.** blox is shipped **unbundled** — its `build` is `tsc && copyfiles … && fix-esm-imports`
+(verified 2026-08-18), so its imports stay external and resolve against **your** `node_modules`. A
+second React copy silently breaks its hooks and context (the classic "Invalid hook call" / null
+`useRef`). See §11.
+
+**(d) The bundler must handle blox's assets.** It MUST support **CSS-Module imports and asset
+imports from `node_modules`**, and it MUST **scan the blox package for Tailwind utilities** (add the
+package path to your Tailwind content globs) or blox components render unstyled.
+
+**(e) The app MUST define the full `--*` host-token set.** blox ships **scoped CSS-Module classes
+but ZERO token values** — there is no `:root` token block anywhere in blox. An app that does not
+define `--baseInput-*`, `--field-*`, `--btn-*`, `--primaryTable-*`, and the rest renders
+**unstyled**. The convergent technique: **define those host tokens by resolving your own
+already-semantic tokens**, so blox themes automatically with **no blox stylesheet imported**:
+
+```css
+:root {
+  --baseInput-bg: var(--field-bg);      /* host token resolves to YOUR semantic token */
+  --baseInput-text: var(--ink-1);
+  --btn-bg: var(--action);
+}
+```
+
+**(f) `getFontAwesomeIcon` hard-imports FontAwesome PRO packages.** So `npm install` requires the
+**FA Pro registry auth** — the README's "free fallback" claim is contradicted by the code. Also:
+`dist/main.css` is **not compiled** (it still contains raw `@tailwind` directives) — **do not import
+it expecting styles.** Style blox through the host-token layer in (e).
+
+## 14. blox api-client init order — **MUST**
+
+Initialize the blox axios client as a **side-effect import that runs before the router mounts.**
+Verified 2026-08-18: both apps do a bare `import "./api/api"` **above** `import App` in `main.tsx`,
+and `api.ts` does:
+
+```ts
+// api/api.ts — runs at import time, before any component renders
+const baseURL = import.meta.env["VITE_API_" + host.split(".")[0]] || import.meta.env.VITE_API;
+const instance = createAxiosInstance({ baseURL, onLogout });
+setAxiosInstance(instance);
+```
+
+blox's API helpers **throw "No axios instance registered"** if any data hook or component runs
+first. The order is: create → set → *then* mount. (See `../apps/toga-blox/features/api-client.md`.)
+
+## 15. Provider nesting order — **MUST**
+
+One `QueryClient` at module scope (§3), and providers nest outer→inner in this order. Verified
+2026-08-18 in both `App.tsx`:
+
+```
+QueryClientProvider            // (Persist)QueryClientProvider if the app persists the cache
+  └─ AuthProvider              // calls useQueryClient() → MUST be inside QueryClientProvider
+      └─ ToasterProvider       // state; any route may raise a toast via useToaster()
+          └─ (app theme/confirm providers)   // supply: blox ThemeProvider · desk: ConfirmProvider
+              └─ router (RouterProvider)      // innermost
+```
+
+- **AuthProvider must sit inside QueryClientProvider** — it reads `useQueryClient()` to clear the
+  cache on auth transitions (§3/§18). Desk's `App.tsx` documents exactly this constraint.
+- **The Toaster is split: provider (state) + a portal viewport (visual).** Mount **both** — the
+  `ToasterProvider` and its viewport (`ToasterList` in supply, `ToasterViewport` in desk).
+- **Theme placement is app-specific:** supply slots blox's `ThemeProvider` here; desk themes via a
+  module-scope theme store (§8) instead. Everything above the theme layer is convergent.
+
+## 16. blox data layer for tables — **MUST**
+
+**Reuse blox's table data layer — do not reinvent server-side where/sort/fields.** Use
+`getDataTableMeta(slug)` (GET `/table-views/meta`), `getDataTableData(...)`, the `useTableData`
+hook, and the `assembleOptions` query serializer.
+
+- **The shared query-key prefix is `["table-data", slug, …]`** (verified in
+  `../apps/toga25-supply/architecture.md`), so `invalidateQueries({ queryKey: ["table-data"] })`
+  refreshes **any** table after a mutation.
+- **`additionalData` (relationship/WHERE injection) MUST be in the query key.** Omit it and the
+  first (null) render caches an **unfiltered** result that a later filtered render reads back stale.
+  (See `../apps/toga25-supply/features/record-modals-and-nested-tables.md`.)
+- **Presentation-only params are stripped from the data key** (§5) — column visibility must not
+  refetch.
+- **Field-limit requests to the visible columns** — the FK-expansion leak defense from §12.
+- **Two serializer footguns to guard:** `assembleOptions` now **omits an empty `fields` param** (a
+  past empty-`fields` 500 is fixed), **but** an empty `where` object still emits a literal `()` —
+  guard against passing an empty `where`.
+
+## 17. Multi-tenant env & deployment — **CROSS-REFERENCE ONLY**
+
+Env and build wiring — `.env.<mode>`, branch→`--mode`, the `VITE_*` console-var trap, the
+per-environment blox channel, `--legacy-peer-deps`, Node/heap — is owned by
+**`frontend-deploy.md`**. Do not restate it here.
+
+The one code-side convention worth stating: both apps read **`VITE_API`** — plus an optional
+per-host **`VITE_API_<FIRST-HOSTNAME-SEGMENT>`** override — in **exactly one module**
+(`src/api/api.ts`, §14).
+
+## 18. Client-side multi-tenant isolation — **MUST** *(cto-added)*
+
+This is the front-end face of the platform's hard multi-tenant rule. **On any tenant/identity
+change, reset BOTH the React Query cache AND tenant-scoped `localStorage`** so one tenant's cached
+data can never bleed into another tenant's session. This ties directly to §3 (clear the cache on
+auth transitions) and the per-tenant/user key namespacing (§3 reference pattern). A tenant switch
+that clears the cache but leaves tenant-scoped storage behind is a data-isolation defect, not a
+cosmetic one.
+
+## 19. Consuming the `{success, data, errors}` API envelope on the client — **MUST** *(cto-added)*
+
+The backend contract is the `{ success, data, errors }` envelope (and the V2 response envelope) —
+see `backend-php.md` and `2.0/standards/framework-rules.md`. The **client** side of that contract:
+
+- **Unwrap defensively.** The nested `data.<record>.<script>` shape is easy to get wrong; read it
+  through one helper, not ad hoc at each call site.
+- **Treat `success: false` as a user-facing outcome:** route `errors[]` to a toast the user can
+  read.
+- **Report the unexpected to Sentry.** A technical/unexpected failure goes to error reporting — do
+  **not** surface a raw server message string as a toast. (blox's api-client normalizes the wire
+  envelope for you; see `../apps/toga-blox/features/api-client.md`.)
+
+## 20. Server-driven UI (Surface) — **Reference pattern (generic shape only)**
+
+Describe the **generic mechanism only.** The concrete engine currently lives in `toga25-desk` and
+will be captured at Desk launch — **do not document Desk's specific menus/screens here.** (Supply
+has a related `surface-frontend` feature doc; the generic contract is what belongs in a standard.)
+
+The generic shape:
+
+- A **server meta bundle carries message KEYS and token SLUGS** — never final strings, never CSS.
+- **Client-side PURE, never-throw resolvers** turn keys→copy and slugs→tokens.
+- **Every consumer resolves each label/icon with a hardcoded design-literal FALLBACK**, so the UI
+  renders **before and without** the seed.
+- **The engine imports nothing from the app;** app-binding registries map action-keys→handlers.
+- **An unknown action-key renders DISABLED + `console.warn`** — never a silent no-op, never a throw.
+
+The payoff: copy and icons change as a **data edit**, with no front-end deploy.
+
+## 21. blox/app boundary & promotion discipline — **SHOULD**
+
+- **The dependency arrow points app → blox ONLY.** No blox module imports app code. (Confirmed by
+  `../apps/toga-blox/architecture.md`: the dependency runs app→library.)
+- **Build a new generic capability app-LOCAL first; promote into blox only after a 2nd consumer
+  validates the contract.** Hardening a shared contract from a single call site (n=1) bakes in that
+  app's accidents.
+- **Mark intent with a per-module header** so a future reader knows which side a module belongs on:
+
+  ```ts
+  // TODO(blox): promote once stable — imports nothing from @/
+  // APP BINDING — stays in the app
+  ```
+
+## 22. Known blox gotchas — consume defensively — **SHOULD**
+
+Work **around** these shared-lib defects; do **not** imitate them in app code:
+
+- Empty `where` → literal `()` (§16).
+- `dist/main.css` is uncompiled — do not import it (§13f).
+- **Two select stacks** coexist (`react-select` + a custom `AdvancedSelect`) and **two table
+  stacks** (`react-table` v7 + `@tanstack/react-table` v8) — verified 2026-08-18 in blox's peer
+  deps. Know which one a given component uses before you wire it.
+- Phantom/unused peer deps in blox's manifest.
+- Supply/commerce business logic has leaked into the shared lib.
+- **No custom-validator passthrough on `BaseInput`** — hence the app-side validator layer in §7.
+- A **~85-prop className-string styling contract on `BaseInput`** — verbose by design; drive it from
+  tokens, not per-instance strings.
+- **`strict: false` in blox's own tsconfig**, and **React-18-only** peers.
+
+**Fixing these is blox-authoring work, tracked separately** (a future `blox-authoring.md`), **not
+app work.** In a consuming app, guard against them and move on.
+
+---
+
+# Part 3 — Open items
+
+*(Described and flagged. NOT prescribed as settled.)*
+
+- **Front-end testing — SHOULD-lean, not yet a settled standard.** The reality (verified
+  2026-08-18): `toga25-supply` **and** `toga-blox-npm` both run **Vitest + React Testing Library**
+  (jsdom, `globals: true`, a setup file, co-located `*.test.ts(x)`). Supply has **real tests on the
+  tricky bits** — auth context, table URL-state, error classification — with `@vitest/coverage-v8`;
+  blox configures istanbul coverage. `toga25-desk` has **no test script and an empty Cypress
+  scaffold**. Recommendation: **Vitest + RTL for unit / logic-hook tests** — a firm SHOULD, since it
+  is real in 2 of 3 sources and mirrors how `backend-testing.md` prescribes a path even without a
+  formal harness — with **Cypress reserved for E2E** (acknowledged empty today). A dedicated
+  `frontend-testing.md` sibling is the likely eventual home. **Do not** conflate this with the
+  team's unresolved *backend* testing question — that is PHP-only.
+- **`eslint-plugin-jsx-a11y` not configured** (§10) — a11y is convention-only, not lint-enforced in
+  any of the three repos. Recommend adopting it.
+- **Client error-reporting gap.** Verified 2026-08-18: all three repos depend on `@sentry/react`
+  (`^8.55.0`), but **neither app initializes it** — there is **no `Sentry.init` and no top-level
+  React `ErrorBoundary`** in `toga25-supply/src` or `toga25-desk/src`. Recommend a top-level
+  `ErrorBoundary` + `Sentry.init`, with a client-error → backend-issue correlation story (§19).
+- **Undo/redo — deliberately OUT OF SCOPE.** The team's undo architecture is an unresolved
+  question. This standard prescribes **no** approach; do not infer one.
+- **React 18 → 19.** blox peers cap at React `^18` (verified 2026-08-18: blox declares
+  `react: ^18.0.0`; consumers pin `^18.3.1` and had to downgrade from 19). Upgrading blox to support
+  19 is an **open, unscheduled** question affecting every consumer — do not unilaterally bump an app
+  to 19.
+- **Committed `.npmrc` registry tokens — SECURITY VIOLATION (remediate).** The app repos commit
+  registry auth credentials in `.npmrc` (both the FontAwesome Pro registry and the private npm
+  registry). This violates `rules/common/security.md` and the `2.0/standards` secret rules. Treat
+  the committed credentials as **compromised: rotate them, move to CI-injected registry config, and
+  purge them from the tree.** This is a known issue **with a remediation pointer**, not a soft
+  "unsettled" item.
+
+---
+
+## Change history
+
+- 2026-08-18 — Initial front-end (React) coding standard: universal React/TS layer + TOGA 2.0
+  platform-conventions layer, mined from @agilant/toga-blox, toga25-supply, and toga25-desk; per-rule
+  convergence tagging; testing/a11y/error-reporting/React-19 flagged as open. (jcardinal)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.612",
+  "version": "1.0.613",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",