@ccoalm/ccl-skills 0.1.0

package/dist/assets/marketplace/plugins/ccl-skills/skills/web-react-dev/references/source-evidence-map.md

@@ -0,0 +1,60 @@
+# Web Client Source Evidence Map
+
+Use this reference when auditing or re-extracting web client guidance. The rules below describe *how* to classify React/Vue/Vite/Umi/Next sources; specific local repository paths and dated cross-check logs live in the private provenance archive outside this skill tree.
+
+Users without code access can still apply the distilled patterns in this file. Do not require access to specific paths unless the task explicitly asks to audit, update, or re-extract implementation evidence.
+
+## Source Coverage
+
+For each web subproject in scope, classify before extracting rules. The shape below is the classification frame; specific entries live in the private archive.
+
+| Dimension | Typical stack signature | Useful extraction | Decision |
+| --- | --- | --- | --- |
+| Broad web inventory | Batch manifest scan across React/Vue/Vite/Umi/Next/admin/webapp projects | Web skill should cover rendered browser apps, build scripts, API clients, component tests, browser smoke, and generated-client commands | Keep |
+| Rich React web source | Umi/React apps with a major component library, charts, DnD, canvas/paper engines, markdown, upload/storage SDKs, process tasks, and route shells | Strong evidence for route/state ownership, complex workbench UI, upload/preview/review, long-task feedback, generated API clients, browser verification | Keep mechanics, discard domain nouns |
+| Modern React admin source | Vite React apps with TypeScript, design-system Pro Components, Vitest, Testing Library, Playwright e2e, API generation, check scripts | Strong evidence for layered tests: typecheck/lint/build, component tests, generated API, browser e2e for critical flows | Keep |
+| Vue/web sources | Vite Vue apps with Pinia, Element Plus, document/PDF/media viewers, socket/streaming, Vitest, bundle analysis, oxlint/oxfmt | Useful for web-runtime behavior, heavy document/media rendering, streaming, analytics, and performance gates; not React-specific architecture | Merge only generic browser/client rules |
+| Infra operations console | React/Umi/Ant Design Pro operations console with generated API client/types, list/detail routes, ProTable, DrawerForm mutations, runtime status tags, copied service identifiers, deploy/runtime metadata display | Confirms operations-console rules for list-detail-drawer route contracts, dense runtime tables, long identifier handling, status severity tags, mutation refresh, generated-client normalization, browser stress checks | Merge into React architecture and UI quality; discard private service/domain labels |
+| Weak/negative sources | Low-quality enterprise UI, generated/static bundles, old worktrees, local copies | Useful for rejection rules only: do not absorb visual style or IA when UI quality is weak | Discard as positive design guidance |
+
+## Source Classification Method
+
+Before extracting rules from a subproject:
+
+1. Confirm the stack signature from `package.json` (framework + design-system + test runner + API-client generator). Stack guesses by directory name alone are not evidence.
+2. Read at least one entry component to confirm whether the subproject is a workbench/Pro app, an H5 app, an admin console, a marketing site, or a legacy app.
+3. Map the subproject into one of the rows above. If it does not fit, classify it as weak/negative and explain why.
+4. For default-empty checked-out branches, inspect remote branches before declaring the subproject empty. The active code may live on a feat or release branch, not on `main`.
+
+## Cross-Skill Routing
+
+- Visual/state design judgment → `product-ui-ux-design`.
+- React/browser implementation ownership → stays here.
+- Flutter/Android/iOS/RN implementation → `app-cross-platform-dev`.
+- Mini-program implementation → `miniapp-product-dev`.
+- Test-layer planning → `testing-strategy`.
+- Backend service implementation → the relevant backend skill.
+
+## Keep / Merge / Discard
+
+- **Keep**: inspect package scripts, route owner, state owner, API client, generated clients, and rendered browser surface before claiming completion.
+- **Keep**: API-backed UI needs component states, API-client/contract failure parsing, and browser smoke for a visible path.
+- **Keep**: for workbench/H5 surfaces, explicitly check startup context, route guard, permission visibility, request interception, long-running job status, upload failure/retry, text overflow, and foreground/background recovery where relevant.
+- **Keep**: for complex workspace shells, implement navigation from route/permission metadata, persist only valid active task/download entries, clear route selection versus process-task selection consistently, measure overflow before tooltips, and verify secondary panel collapse before primary content is compressed.
+- **Keep**: for complex workspace workbenches, encode these browser-visible contracts: startup context before shell render, token-to-theme component states, route-derived sidebar, durable process/download entries, restored-state validation, measured overflow, sticky/stacked layout fallback, AI panel collapse/fullscreen/floating behavior, upload/parse polling states, and screenshot checks at baseline plus narrow/wide desktop widths.
+- **Keep**: for high-throughput evaluation workbenches, encode queue/task ownership, selected record, selected sub-unit, queue switcher density, header action grouping, task-type variants, split layout calculation, current-unit header sync, selected-card boundary state, card default/hover/selected/completed states, empty/delayed artifact shell state, persisted settings, submit modes, precision/table row states, inline numeric edit state, aligned multi-actor comparison, mode-specific batch/default/common-value configuration, incomplete-item confirmation, batch state, media retry, per-item annotation state, long-artifact fit/stitching, option-disablement rules, inline micro-action states, disabled reason tooltips, quality/timing blockers, sticky issue tags, shape-subtool menu state, icon-only/labeled/compact/expanded toolbar variants, settings/history/statistics drawers, full-screen popup containment, AI item-level enable/configuration/strategy state, AI hierarchical item-list state, AI selected-item metadata state, AI empty-config panel state, AI required-context/reference/rationale fields, AI result-use mode, bounded long reference/output panels, inline AI-reviewed tags, AI-review unsupported/rerun states, and queue-end recovery as explicit runtime state.
+- **Keep**: for device capture and heavy upload flows, encode readiness, device config cache/re-check, fallback source, active batch/session id, capture/upload counters, speed, preview mode, pause/continue/finish state, stale-session exit, before-unload/offline handling, exception polling, and result-management entry as explicit runtime state.
+- **Keep**: for progress/quality monitoring workbenches, encode mode entry, permission-gated tabs, dimension-owned fetches, numerator/denominator calculation, refresh/export jobs, scope-filter resets, expanded detail state, preserved deep-link filters, table resizing, empty-detail disabled reasons, and rework/reset permission as explicit runtime state.
+- **Keep**: for structured assignment workbenches, encode unit tree data, row identity, batch-selection state, disabled reasons, split/merge operation state, method/strategy drawers, role-owner drawers, quota/rate validation, permission summary, import/export jobs, save/autosave/finalize state, started-work risk confirmation, owner soft-delete or historical preservation, and post-action scroll/focus as explicit runtime state.
+- **Keep**: assignment validation should be a state machine, not a toast list: compute invalid units, scroll/focus the first invalid unit, show row/field-level visual state, clear the state on repair, and keep finalization summaries tied to the exact optional rules and permissions being committed.
+- **Keep**: for structured creation/import workspaces, encode source selection, upload validation, process polling, autosave/final-save split, canvas/editor modes, validation blockers, structure DnD, duplicate repair, cleanup of dependent derived data, and downstream lock state as explicit state machines.
+- **Keep**: for app-hosted auth/profile surfaces, encode splash handoff, consent modal, login modes, conditional account-opening or binding, verification-code mechanics, first-login password setup, account/privacy/about route clusters, logout/delete cleanup, and post-session navigation as explicit state machines.
+- **Merge**: design/layout acceptance belongs in the design skill; web skill owns implementation and browser runtime proof.
+- **Route**: mobile/app work to `app-cross-platform-dev`; broad test-layer planning to `testing-strategy`.
+- **Discard**: source business vocabulary, old worktree manifests, visual taste from weak UI sources, and component-library naming as a substitute for UX.
+
+Coverage label: broad manifest inventory plus representative file-level refresh, not node-by-node inventory of every web component.
+
+## Where The Specific Provenance Lives
+
+Specific subproject paths, real branches, package.json signatures, and dated cross-check logs live in the maintainer's private archive. They are not included in this file, so any cross-organization use of this skill stays clean.

package/dist/assets/marketplace/plugins/ccl-skills/skills/web-react-dev/references/web-quality-release.md

@@ -0,0 +1,190 @@
+# Web Quality And Release
+
+## API Integration
+
+- Use typed API clients or schema validation when available.
+- Test URL, method, headers, request body, response envelope, empty body, invalid JSON, non-2xx, timeout/abort, network failure, permission denied, and feature-closed responses where relevant.
+- Map backend errors to user-readable state and developer-observable diagnostics.
+- Keep request cancellation and stale response handling explicit for search, filters, autosave, and rapidly changing inputs.
+
+## API Client Recipe
+
+For API-backed pages, centralize these mechanics in the client or the narrowest shared request wrapper the repo already uses:
+
+| Concern | Required behavior | Test evidence |
+| --- | --- | --- |
+| Request metadata | Attach or preserve request id, trace id, operation name, app/client version, auth context, and upload/long-running classification where available | Assert headers/body/query metadata and redaction behavior |
+| Response parsing | Accept the repo's canonical envelope; classify empty body, invalid JSON, non-2xx envelope, backend error envelope, and malformed success separately | Contract tests for each response shape |
+| Cancellation | Distinguish user/navigation/rapid-input cancellation from network failure and timeout | Test abort/cancel path without user error toast |
+| Auth and permission | Convert expired auth, forbidden, feature-closed, and scope-mismatch responses into route guard, disabled state, or permission state | Component/API tests for 401/403/closed responses |
+| User error mapping | Show readable state near the affected region; keep raw transport details for logs/devtools, not UI copy | Component test asserts visible message and retry/next action |
+| Long work | Expose task id/status, polling/retry/backoff, stale result protection, refresh recovery, and final status | API-client test plus browser smoke for one pending-to-final flow |
+
+## Test Layers
+
+- Unit tests: pure mapping, validation, reducers, derived data, error translation, and utility behavior.
+- Component tests: loading/empty/error/success states, forms, validation, permissions, emitted request intent, keyboard interaction, and visible state.
+- API-client/contract tests: request/response and failure parsing.
+- Browser/E2E smoke: critical route opens, primary action succeeds, one realistic failure path is readable, console has no new serious errors, and visible result is asserted.
+- Scenario tests: build the scenario matrix in `testing-strategy`; for web surfaces, map each scenario to component state, API-client contract, and only the necessary browser smoke instead of duplicating every branch in E2E.
+
+## Performance And Deployment
+
+- Check bundle growth, code splitting, image optimization, caching headers, long tasks, unnecessary rerenders, list rendering, hydration/runtime errors, and Core Web Vitals risk.
+- Build-time environment variables must be explicit; do not hide production behavior behind local-only defaults.
+- Release checks should include build, smoke route, error monitoring, analytics event sanity, rollback or feature flag path, and cache invalidation/CDN implications when relevant.
+
+## Build Tooling Currency
+
+- **Vite 8 (released 2026-03) is the current stable**, shipping Rolldown as the default Rust-based bundler (10-30x faster builds, full plugin compatibility per Vite's own announcement). **Vite 7** (Node.js 20.19+/22.12+ required, Node 18 dropped; ESM-only distribution) remains the previous stable line for teams not yet ready for the Rolldown migration trade-off (Rust-toolchain debugging, plugin compat audit). Migration cadence: upgrade Node first if pinned to Node 18; then plan Vite 7 → 8 with a build-perf + plugin-compat smoke before flipping defaults. The historical `rolldown-vite` opt-in package is no longer the path forward — Vite 8 ships Rolldown directly.
+- **Tailwind CSS v4 (stable Jan 2025) uses CSS-first configuration**: no `tailwind.config.js` for new projects; configure via `@theme { --color-brand: ... }` directives in the same CSS file that imports Tailwind. The first-party Vite plugin + automatic content detection eliminates most config; full builds 5x faster, incremental 100x faster than v3. Migration from v3 to v4 is not free (config shape, plugin API, some utility-class differences) — the migration guide is authoritative; do not infer migration steps from training-data memory.
+- **Biome v2 (June 2025, "Biotype") for formatter + linter** when the team wants ESLint + Prettier collapsed into one Rust tool. Type-aware linting without TypeScript compiler dependency (Biome implements its own type inference for lint rules — this does NOT replace `tsc --noEmit` in CI for full type-check); 502 rules from ESLint sources; CSS + GraphQL formatting stable; `biome migrate eslint` automates most config porting. Trade-off: smaller plugin ecosystem than ESLint; if the project depends on niche ESLint plugins (custom org rules, framework-specific lint), audit those before migrating. ESLint flat config + Prettier remains valid for teams with deep ESLint plugin investment.
+- **React Compiler ESLint plugin**: when React Compiler is enabled (per `react-architecture.md`), keep `eslint-plugin-react-hooks` at the version that ships the compiler-aware preset; the recommended preset enforces the rules Compiler relies on (no mutating props, deterministic render, etc.). Without it the compiler may silently skip components that violate its assumptions.
+
+## Framework-Era Patterns (When To Adopt, When To Defer)
+
+Several React-adjacent architectures became visible in industry conversation (RSC / Server Actions / Islands / Module Federation / Suspense data fetching). They are real and useful in narrow contexts; they are not the new default for every React app. Rules below define when to opt in.
+
+### React Server Components / Server Actions / Streaming SSR
+
+- **Adoption condition**: the app is on a framework/runtime with **production-supported RSC and Server Functions enabled for this app path** — Next.js App Router in RSC mode is the canonical example; other frameworks ship RSC as opt-in or experimental on specific paths. Framework-native loaders / actions (Remix / React Router framework mode, Modern.js, RedwoodJS) are valid server data patterns but are NOT automatically RSC / Server Actions — `loader` / `action` / `useFetcher` are their own primitive. Mixing hand-rolled RSC into a Vite + React Router v6 SPA is a research project, not a delivery path.
+- **Where RSC pays off**: content-heavy pages with mostly read traffic and small mutation surface (marketing, docs, dashboards with a stable read shape, list/detail screens). The data dependency moves to the server; the client bundle shrinks; first-load latency drops.
+- **Where it does not**: highly-interactive workbench surfaces (the chart/table workbenches in `react-architecture.md`'s heavy-dashboard pattern), live-collaboration editors, anything whose interactivity-to-content ratio is high. The "use server" / "use client" boundary becomes a maintenance tax that outweighs the SSR win.
+- **Server Actions / Server Functions** (`'use server'`) are async network calls with serializable args, designed for mutations / form POST paths where the framework owns revalidation. They can replace some fetch-based form submissions on RSC frameworks (progressive enhancement: form works without JS). They are NOT a general data-fetching replacement and they are not meant for retrofitting the API surface on a non-RSC framework.
+- **Streaming SSR with `<Suspense>` boundaries** is independent of RSC and works in plain React 18+: choose Suspense boundaries that match user-visible regions (header / nav / primary content / secondary panel) so the slowest region does not block the rest. Boundary placement is design — every fallback geometry must match the resolved region or layout jumps when the fallback resolves. Pair with `ErrorBoundary` at the same node — Suspense alone catches loading, not failure.
+- **Don't pick the framework for the buzz; pick it for the deploy story.** Many SaaS / admin / data-console apps already work on Vite + React Router + TanStack Query and would gain little from migrating to App Router; the migration cost (auth, middleware, build pipeline, hosting, third-party SSR compatibility) is real.
+
+### Suspense Data Fetching And `use()` Hook (React 19+)
+
+- **`use(promise)` requires a Suspense-compatible data source**: a framework loader (Next App Router, React Router data APIs, Relay) or a cache library that throws promises (TanStack Query with `suspense: true`, React Query's `useSuspenseQuery`). Calling `use(fetch(...))` directly in a component creates a new promise on every render and falls into an infinite-suspense loop.
+- **Suspense boundary placement is part of the page contract**: each boundary represents a user-visible region with its own loading geometry and its own error boundary. A single top-level boundary turns the whole page into a spinner; a boundary per micro-component turns the page into a flicker fest. Match boundaries to design regions.
+- **Fallback geometry MUST match resolved geometry.** A skeleton row that's 40px tall when the loaded row is 80px causes layout jump on resolve. Reserve space in the skeleton; check rendered behavior in the browser.
+
+### Islands Architecture / Partial Hydration
+
+- **Adoption condition**: the surface is content-dominant with sparse interactivity (marketing, docs, blog, knowledge base, public help center, status page). Astro / Fresh / Marko / Eleventy + islands are the appropriate stack.
+- **Not for**: data consoles, admin workbenches, editors, dashboards. The "island" concept assumes most of the page is static; SaaS workbench pages are >90% interactive — turning them into islands fragments the state model.
+- **Within React: `astro:react` or similar lets a Vite/Astro static site host React islands.** This is a legitimate pattern for content sites that need occasional interactive widgets; it is not a SaaS app architecture.
+
+### Module Federation / Micro-Frontends
+
+- **Adoption condition** (all must hold, not any): (1) multiple independent teams deploy independently to the same shell, (2) shell + remote runtime version compatibility is a contractual concern with maintained governance, (3) the shared runtime overhead (shared React, shared design system, shared auth, shared analytics) is non-trivial AND can survive cross-team version skew, (4) a monorepo + code-splitting alternative was evaluated and rejected with reasons.
+- **Default for SaaS portfolios is NOT micro-frontends**: a monorepo + meta-framework + per-feature code splitting (`React.lazy` / route-based splits) gets you per-feature lazy loading and per-team ownership without the runtime composition tax. Module Federation 2.0 / `single-spa` are real tools, but they introduce shared-dependency version contracts, runtime-error-class issues, type-sharing problems, and CSP / origin / CORS concerns that monorepo splits do not.
+- **If adopted**: pin shared singletons (`react`, `react-dom`, the design-system runtime) via the federation config; document the version-compatibility window; gate cross-remote breaking changes through a contract test; never let a remote inject global side effects (analytics, error boundaries, route registration) without the shell's awareness.
+
+## Lane-Aware Static Deployment On Object Storage
+
+When the front-end build output (HTML, JS, CSS, assets) is served from object storage (S3 / OSS / TOS / GCS) instead of a stateful web server, and the portfolio runs multiple environments / canary lanes / preview lanes side by side, a thin server-side router sits between the user and the bucket to select the right lane's artifacts. The pattern is mature but security-sensitive; the rules below are necessary, not optional.
+
+### Storage And Bucket Posture
+
+- **Storage layout**: the build artifacts of each lane live under a stable prefix; the lane prefix is the unit of isolation. The standard lane (production baseline) has its own well-known prefix. The router resolves an inbound request to a `(lane, prefix, path)` tuple and serves the matching object.
+- **Bucket separation by trust**: protected lanes (canary, preview, tenant-isolated, internal) and the public production baseline MUST live in separate buckets — the production baseline can be public-readable for CDN performance; protected lanes MUST be in a private bucket with identity-bound or network-bound origin access control. Mixing public and protected lanes in one bucket is a finding, because any per-prefix policy is easy to misconfigure into a public exposure.
+- **Origin access control choice depends on the topology, but the lane-resolution contract is the same**: when a managed CDN fetches directly from object storage, use the provider's CDN-bound origin-access mechanism (S3 OAC bound to CloudFront, OSS-CDN equivalent) — but direct CDN-to-bucket is valid only for immutable public baseline assets that need no lane resolution, token exchange, manifest verification, or response-header control. Any path that needs lane resolution / preview-token validation / response-header policy / structured logging MUST go through the router; routing it directly via CDN bypasses the entire trust model. When a custom router proxies bytes from object storage, the router authenticates with its own IAM / service-account identity that has the minimum required permissions, and the bucket policy restricts access to that identity (and to the CDN-bound identity if a CDN sits in front). Do not rely on `Referer`-based bucket policies — `Referer` is client-set and trivially spoofable by non-browser clients (curl, scripts, native apps). The "TOS equivalent" or any other provider's equivalent must be identity-bound or network-bound and resistant to client-supplied header spoofing.
+- **Immutable artifact prefixes**: each deployment writes to a fresh content-addressed prefix (e.g. `<commit-sha>/`); existing prefixes are never overwritten. The deploy step uploads all artifacts, verifies them against a generated build manifest (per-file expected size + content checksum via the provider's authoritative checksum API — `x-amz-checksum-*` on S3, equivalents on OSS / GCS / TOS), and only then flips the active manifest to the new prefix. ETag is not a reliable content checksum for multipart uploads — do not equate ETag match with content match.
+- **Artifact retention and GC**: old immutable prefixes are kept for at least `max(CDN cache TTL, browser cache TTL, service-worker cache TTL, rollback window)` after they stop being active. Premature GC orphans live clients still holding old HTML that references old chunks → blank screens and chunk-load errors. Retention policy is part of the deployment contract, not an afterthought; GC is a separate scheduled job with explicit safety margins, never tied to "deploy succeeded" timing.
+
+### Trust Model For Lane Selection
+
+- **Router origin lockdown**: the router MUST NOT be reachable directly from the public internet or from any caller that bypasses the trusted edge. Enforce by private networking (internal load balancer, VPC-internal listener, no public DNS), mTLS / shared internal auth between edge and router, or an explicit trusted-proxy chain plus a router-side check that rejects any request not carrying the proxy's authenticated identity. If an attacker can reach the router directly with their chosen lane header, "edge strips and re-injects" provides nothing.
+- **Lane signal trust**: client-controllable signals (request headers, query strings, host names when DNS is shared) MUST be validated and re-asserted at the edge before they reach the router. The edge (CDN, ingress controller, reverse proxy, or auth gateway) strips client-supplied lane headers and re-injects the authorized value based on authenticated session, signed token, or platform identity. The router treats the edge-rewritten value as authoritative; raw inbound lane headers are rejected.
+- **Signed preview tokens**: for shareable preview links, the query token MUST bind {lane, app, route or prefix, target commit / build, tenant or audience, allowed host(s), expiry, key id, nonce} with HMAC or asymmetric signature, and be replay-bounded (server-side nonce store or jti deny-list within the expiry window). Short expiry (minutes). Because query tokens leak into web-server logs, browser history, `Referer`, and CDN cache keys, **the safe pattern is single-use exchange, not long-lived URL auth**: the first request validates the token, sets a short-lived `HttpOnly; Secure; SameSite=Lax` cookie or signed session for the lane, then redirects to a clean URL without the token. The cookie itself is scoped tightly: **host-only** (no `Domain=` attribute, so it never widens to `*.example.com`), `Path=/` for the lane's path scope only, and the session payload itself binds the allowed host(s). `SameSite=Lax` is the right choice here because cross-site top-level navigations from chat / email / external links are exactly the preview-link use case; `SameSite=Strict` would drop the session on the initial cross-site navigation. The token-exchange landing page is the only entry that needs cross-site cookie acceptance; deeper navigation within the preview is same-site. Subsequent requests use the cookie/session; the original token is consumed and cannot be replayed. Server-side: the router MUST verify the session's lane is permitted for the inbound canonical host and reject mismatch (a preview session presented on a production-only host fails closed) so a broad-cookie or replayed-session attempt cannot serve preview/canary artifacts on the production surface. Strip the token from the URL before logging, set `Referrer-Policy: no-referrer` on the preview shell so outbound links cannot leak the token, redact tokens from access logs and traces.
+- **Host-based lane selection** uses a canonical host value the edge asserts after enforcing a host allowlist; raw `Host` / `X-Forwarded-Host` headers and substring matching on host are findings.
+- Inside the trust boundary, the router consults inputs in a fixed priority and records which one decided the lane. **Authenticated session takes precedence over edge defaults**: a valid preview-lane session (set by single-use token exchange) wins over a canonical-host or edge-injected default; otherwise a user holding a preview session on a shared production host would be silently served production. Effective order: signed session/cookie (authoritative once established) > canonical-host (only when the host is dedicated to one lane) > edge-injected header (only when no session is set) > signed query (one-shot, exchanged immediately).
+
+### Prefix Resolution And Pre-Check Semantics
+
+- **Per-lane prefix resolution**: avoid bucket prefix LIST as the control plane — it does not scale across many router instances and rate-limits under traffic. Instead, the deploy step publishes a small active-lanes manifest (`active-lanes.json` or equivalent), the router fetches it with conditional GET / ETag and stale-while-revalidate, jittered refresh interval, single-flight on miss, and a bounded stale-fallback policy when the manifest is unreachable. A "list all prefixes every 5-30 s" loop is acceptable only for tiny portfolios; document the cutover threshold.
+- **`active-lanes.json` is the highest-risk pointer**: a wrong value here serves wrong lane/commit globally. Treat it with the same rigor as `routes.json` — signed by the deploy identity (HMAC or asymmetric), integrity verified on each fetch, write access restricted to the deploy identity, read access restricted to the router identity (not publicly readable). On signature failure or read failure, the router fails closed (uses last known-good with a bounded max-staleness, then 503) rather than reverting to bucket LIST. **Replay protection is stateful, not timestamp-only**: the router stores the highest generation id seen per (app, lane) and rejects any signed manifest with a generation ≤ that high-water mark. A timestamp inside the payload without router-side state lets an attacker replay an older valid manifest. The high-water store is durable across router restarts (shared cache / consensus store) so a fresh router instance does not accept stale-but-valid manifests.
+- **Cache miss policy**: canary, stress, shadow, tenant-isolated, and preview lanes fail closed (return 404 / 503) on cache miss. Fallback eligibility is determined by the route's lane-isolation policy plus downstream-capability policy, not by HTTP verb — almost all static HTML routes are GET but the HTML they boot can mutate state, so "read-only route" is not a safe gate. Only routes explicitly tagged as fallback-safe (no tenant binding, no downstream API audience binding, no preview/canary semantics) may fall back to the standard baseline.
+- **Pre-check before serve**: HEAD against the resolved object key tells you whether the artifact exists *only* when you can distinguish "missing" from "denied" / "service error" / "throttled". S3 `HeadObject` returns generic errors and is permission-dependent: a 403 can mean "object missing without ListBucket" or "access denied"; a 503 can mean throttle. The router MUST classify HEAD result before deciding fallback: 200 → serve; explicit not-found (404 with ListBucket permission) → consider fallback per lane-isolation policy; anything else (5xx, 403 with ambiguous semantics, network error) → surface as service error, NEVER silently fall back to standard (silent fallback turns IAM / KMS / config errors into cross-lane data leaks).
+- **Path normalization**: a catch-all router plus object-key suffix mapping needs explicit rules for URL decoding, `%2f` handling, dot-segment removal, duplicate-slash collapse, case sensitivity, query stripping, and an allowlist of accepted route keys. Without normalization, a route table bug can become arbitrary object-key fetch within the lane prefix.
+- **Route-table suffix rules**: even with a signed `routes.json`, the suffix values must be relative (no absolute object keys), pass a strict character allowlist (no `..`, no leading `/`, no `%2e%2e`, no double-decoded traversal), and confine the final resolved key to the active lane prefix. Validate the route value AFTER URL decode AND any application-level decode pass; do not trust the signed payload's structure alone. A route mapping to another lane's prefix or to an absolute key is a router-level bug, not a contract decision the route table can authorize.
+
+### Routing Table And Atomic Rollback
+
+- **Routing table as versioned artifact**: the router reads `routes.json` (or equivalent) from the bucket; the table maps URL paths to object-key suffixes. The table is a deployment artifact, signed/versioned with the app, never hand-edited.
+- **Atomic flip is partial atomicity, not full**: object-storage versioning + manifest write is atomic only for the one manifest object; router cache, CDN cache, browser cache, service worker cache, and HTML-to-JS-chunk version compatibility are not. To approach end-to-end atomicity: (1) every deployment uses immutable content-addressed prefixes; (2) the router pins one manifest version per request (read once at request entry, use throughout) so a mid-request flip cannot mix old HTML with new chunks; (3) conditional writes / generation IDs / pre-conditions on the manifest write prevent concurrent deploy races; (4) CDN TTL on the manifest is short (seconds), TTL on immutable content prefixes is long (hours-days, with versioning); (5) document the partial-atomicity boundary so operators know what a "rollback" actually rolls back.
+- **Cache key includes lane (and many CDNs ignore raw `Vary`)**: CDN cache key MUST include the resolved lane signal and any auth-derived identity that influences the served artifact. Many CDN cache policies ignore arbitrary `Vary` headers unless the CDN's own configuration explicitly lists the header as a cache-key dimension — relying on `Vary` alone is insufficient. Configure the CDN cache key explicitly through the provider's mechanism (CloudFront cache policy, Cloudflare cache rules, fastly VCL, etc.) to include the lane dimension. Protected and tenant-specific HTML should be served with `Cache-Control: private, no-store` (or `private, max-age=0, must-revalidate`) so neither shared CDN nor browser back/forward cache can leak it cross-user. Public baseline HTML can be cached normally but the cache key still includes the resolved lane to avoid cross-lane leakage at the edge.
+- **Signed-URL redirect policy**: the router SHOULD proxy bytes from object storage rather than 302-redirect to a signed object-storage URL. Redirects leak bucket keys / lane prefixes into client logs and `Referer`, weaken response-header control (CSP, X-Frame-Options, cache headers cannot be set on a signed-URL hop), can outlive the user's lane assignment or a rollback, and get cached independently by browsers and CDNs. If a redirect is unavoidable (very large file), the signed URL must be short-lived (minutes), single-use where the storage supports it, scoped to the exact key, and marked non-cacheable; protected lanes never redirect.
+
+### Lane Binding Extends Beyond Static Artifacts
+
+A "lane-aware deployment" that only routes static artifacts is **incomplete and dangerous** — a preview / canary HTML shell still talks to API endpoints, reads runtime config, sets cookies, and uses auth tokens. Without lane binding on the downstream calls, the preview shell mutates production data while looking like preview. Architecture extends lane binding all the way down:
+
+- The HTML shell receives a per-request runtime-config injection (or fetches a per-lane runtime-config endpoint) so it knows the lane it was served from. The shell does not infer the lane from URL or guess.
+- Outbound API calls from the shell may carry a lane hint, but the API gateway / service mesh does NOT trust a client-supplied lane signal. The gateway derives the authoritative lane from the authenticated session / signed token / canonical host (the same trust model as the static router) and rejects any request whose client-claimed lane does not match the derived value. A browser-set header / query param alone is attacker-controlled; treating it as routing input is a cross-lane routing hole.
+- The API gateway / service mesh enforces the same lane policy on the downstream calls: a request whose authenticated lane is preview cannot land on production API instances, and vice versa.
+- Auth tokens issued for a preview / canary lane are audience-scoped to that lane; production tokens are not accepted by the preview-lane downstream, and vice versa.
+- Cookies set by the preview shell are scoped (`Path`, `Domain`, `SameSite`) so they cannot bleed into production app loads in the same browser.
+- Cross-lane writes are blocked at the data layer too: tenant id + lane signal both validated before a write commits, so a misconfigured shell cannot mutate the wrong tenant.
+
+### Service Worker Scope And Cache Isolation
+
+Service Workers can poison lanes across deploys if not constrained, because they intercept all requests within their scope and survive page reloads:
+
+- **No Service Worker for protected lanes** unless each lane has its own origin (e.g. a per-lane subdomain) — same-origin lanes share a SW registry and a preview lane's SW can intercept production traffic in the same browser (and vice versa).
+- **Scope ceiling**: by default a SW's scope is its script directory, but the response header `Service-Worker-Allowed` CAN widen scope within the same origin beyond the script's path. For shared-origin lane deployments, the SW-serving response MUST NOT emit a wider-than-script-path `Service-Worker-Allowed`, and the registration code MUST NOT request a wider `scope` option. A SW served from `/sw.js` (no widening header) controls `/` already; a widening header would let a sub-path SW control `/` too. Enforce by inspecting the response header at delivery time, not only by where the script lives.
+- **Cache name includes lane + manifest version** so a SW for production cannot serve cached production HTML to a preview lane (or vice versa).
+- **On lane transition, unregister + clear caches**: when the user moves from preview back to production (or between tenants), the previous lane's SW is unregistered and its caches cleared explicitly. Stale SW survival is a top source of "rolled back but still seeing old version" incidents.
+- **Protected HTML is not SW-cached**: the SW's fetch handler explicitly excludes protected-lane HTML paths from offline caching; only public baseline assets are cacheable.
+
+### Observability And Error Contract
+
+- Every request records the resolved `(lane, prefix, path, manifest_version)` plus a request id and structured log fields. A 5xx-class error in the router surfaces the resolved tuple to the operator (in the logged record, not in the user-facing body — see XSS / info-leak rules). Generic error strings like "environment incorrect" without the resolved tuple make on-call triage impossible.
+- **Logs are a credential sink unless redacted**: the logging pipeline strips signed preview tokens, signed object-storage URLs, auth-derived identity, and sensitive tenant/lane labels before persistence. Field-level redaction at the logger, not in ad-hoc per-call code. Combined with the single-use-exchange rule for query tokens, this prevents long-term log exposure of preview credentials.
+
+### Security Headers
+
+- **Content-Security-Policy**: set deliberately for HTML served by the router; do not default to permissive. CSP rules live in middleware, but middleware must be route-aware (or declaratively configured per route family) when different routes need different CSPs. When the HTML shell needs per-request runtime-config injection (lane id, tenant, feature flags, auth audience), do NOT relax CSP with `unsafe-inline` — generate a per-response nonce and serve the inlined config as `<script nonce="...">` with CSP `script-src 'self' 'nonce-...'`, or fetch the config from a same-origin lane-aware endpoint immediately on shell load. `unsafe-inline` defeats the entire CSP injection-defense surface and is a finding.
+- **Clickjacking**: use `Content-Security-Policy: frame-ancestors <origin-list>` for origin-specific embedding policy — the only mechanism modern browsers support for allowlist-style control. `frame-ancestors` does not fall back to `default-src`, is not valid in `<meta>` (must be sent as a response header), and applies to every ancestor in nested-frame chains. `X-Frame-Options` is limited to `DENY` / `SAMEORIGIN` (`ALLOW-FROM` is obsolete and ignored by current browsers); use it only as a legacy fallback for `DENY` / `SAMEORIGIN`.
+- **Host pinning**: the router pins the trusted host set in config and rejects requests with unexpected `Host` values that survived the edge.
+- **No request echo**: never echo request paths, header values, or query strings into the response body or error messages; they may carry attacker-controlled content.
+- **Client-side XSS — untrusted-HTML and URL sinks**: React escapes text children by default, so the risk is the raw sinks. Any `dangerouslySetInnerHTML` (or direct `innerHTML`, inline-`<svg>`, or other raw-HTML sink) fed backend-supplied, user-supplied, or otherwise untrusted content MUST be sanitized at the sink — through the shared sanitizer (`shared/security/sanitizeHtml` per the sanitization-library policy in `react-architecture.md`) or DOMPurify / Trusted Types; the CSP above is defense-in-depth, not the primary control (OWASP Top 10 2021 A03:2021-Injection, which folds in Cross-Site Scripting). Likewise treat a `href` / `src` / `window.location` / router-redirect target taken from user input (`?returnTo=` / `?next=`, `<a href={userValue}>`) as untrusted, and scope the allowlist to the sink: a link **`href`** may allow `http`/`https`/`mailto` plus same-origin relative paths; a resource **`src`** splits by class — an image/media `src` allows `http`/`https` from trusted origins (not `mailto`), but an **executable or embed `src`** (`<script>`, `<iframe>`/`<object>`/`<embed>`, active-SVG context) is never constructed from a user-supplied value at all — even a same-origin path can be attacker-chosen — use a fixed static asset path or a closed per-sink allowlist, enforced with a per-sink CSP (`script-src` / `frame-src`, and `object-src 'none'` unless a closed allowlist is truly required), SRI for any remote script, and `sandbox` on untrusted iframes; a **redirect / `window.location` / router navigation** target is strictest — allow only same-origin relative paths or an explicitly allowlisted origin set, never an arbitrary user-supplied absolute URL (that is the open-redirect). Reject `javascript:` / `data:` and other active schemes at every sink.
+
+### Storage Consistency vs Cache Propagation
+
+- Modern S3 and GCS are strongly consistent for read-after-write and list-after-write of objects; older provider docs and other providers may differ — record the chosen provider's actual guarantees in architecture. The dominant propagation risk is not storage consistency but CDN cache, browser cache, and service-worker cache; deployment design should target those layers.
+
+### Anti-Pattern Guardrails (Recurring In Prototype-Grown Routers)
+
+- Debug `console.log` statements in the request hot path. Replace with structured logging at info/warn/error levels and a sampling policy for high-volume routes.
+- Mixed environment-detection sources (host substring check vs `process.env` flag) that can disagree. Pick one canonical signal and derive everything from it.
+- Catch-all `try { ... } catch { ctx.body = 'error' }` that swallows the original error class. Log the cause with the resolved tuple; return a stable error code.
+- Empty controller / service / model files committed as scaffold. Either implement or remove them; the linter should flag.
+
+## Cross-Stack Contract (Front-End Side Of The Back-End Envelope)
+
+The front-end API client is one half of the front-end-back-end contract. The other half is owned by the architecture-layer back-end skills (`python-service-architecture/references/api-contract-and-schema.md` and `go-microservice-architecture/references/protobuf-contract-architecture.md`); these rules apply to the front-end consumer side and must stay symmetric with the producer side.
+
+- **Response envelope consumption**: when the portfolio uses HTTP-200-always + JSON envelope (`{code, message, data}` with optional `{success}`), the front-end client classifies `code === success-code` as domain success, any other code as a typed domain error keyed by `code`, and HTTP-level non-2xx as a transport error. Domain error → user-readable mapping happens in the API client or in the narrowest shared error helper, not scattered in every page. When the portfolio uses HTTP-status-as-semantic instead, the client maps status families to the same internal classification. Mixing both styles across apps in the same portfolio is a portfolio-level finding.
+- **Trace propagation surface**: every outbound request attaches `X-Request-ID` (client-generated UUID) and propagates `X-Trace-ID` when the runtime carries one. Every response surfaces the trace id back (header or envelope field). The client exposes the trace id to user-facing error UI so support flows can map a screenshot to a back-end log. Skipping client-side trace id injection breaks end-to-end correlation regardless of how good the back-end tracing is.
+- **Auth header contract**: front end attaches the agreed auth header (`x-token` / `Authorization` / equivalent) and the agreed app identity header (`x-app-id` / equivalent). Header names, value format, and expiry semantics are portfolio contracts; the front end does not invent its own. For refresh-token flow when the portfolio supports it: a 401 response with a refresh-eligible signal triggers one silent refresh + retry; without that signal the client clears auth and routes to login.
+- **Timeout layering**: outer caller budget is always longer than inner callee budget so an inner failure can return a structured error before the outer caller gives up. For a normal request path that is `browser/client → gateway → downstream RPC`, the relationship is `client timeout > gateway timeout > downstream RPC timeout` (typical: client ~30 s, gateway ~20 s, downstream RPC ~10 s, tuned per endpoint risk). If the client times out before the gateway can return, the user sees a network error when the back end could have returned a typed code with the trace id — that loses both the error class and the trace. Long-running operations (export, batch, large-file upload) use an explicit per-request override on every layer of the chain; SSE/WebSocket use a heartbeat rather than a single timeout. A single global 10 s timeout applied to every operation is a finding for export-heavy or upload-heavy apps.
+- **Object-storage client-signed upload**: large-file upload goes through the platform's signed-upload path — the front end calls a back-end token endpoint (e.g., `/kms/get-tos-token` or equivalent) to receive an STS credential, then writes directly to object storage with the client-side SDK. The auth header / main API channel never carries the file body. Failure modes (token expiry mid-upload, partial multi-part failure, network drop, deduplicated retry) are part of the client wrapper, not the calling page.
+- **Network vs business error classification**: AbortError / timeout / `navigator.onLine === false` map to "network error" with a retry affordance; envelope errors with a known code map to typed domain errors; unknown envelope shapes map to "unknown error" and surface the trace id. The client does not silently swallow any of these.
+
+## Multi-App CI/CD And Quality Gates
+
+For portfolios with multiple React apps sharing a back-end:
+
+- PR gate must run remotely (GitLab CI / GitHub Actions / equivalent), not only as a local pre-commit hook. Pre-commit catches obvious lint/format problems; PR-level gates catch what locally was skipped, what dirty branches drag in, and what the merge introduces.
+- Required PR gate stages, in this order: install (frozen lockfile) → type check (`tsc --noEmit`) → lint → unit/component tests → build. Skipping any of these because "the local hook ran" is a recurring source of broken main branches.
+- Husky + lint-staged + `verify-commit` are the local layer; they enforce style and message format. They are not a substitute for the PR gate.
+- Lane / environment separation in CI (online vs offline lanes, canary vs production deploy targets) belongs at the deploy stage, not at the build stage. Build artifacts should be lane-independent where possible; lane choice is a deploy-time variable.
+- A portfolio without remote PR gates is a deliberate trade-off (fast iteration, small team, single owner) or an oversight; document which. Adding PR gates retroactively to ten apps is expensive — start one app at a time with the lightest gate (type check + lint + build) and expand.
+
+## Test Coverage Floor
+
+A portfolio with **zero unit tests, zero component tests, and zero E2E** across every app is a structural finding, not an app-level oversight. The minimum bar that catches the most common regressions cheaply:
+
+- One unit-test framework chosen at the portfolio level (Vitest, Jest, or Bun test); even a small initial suite gates the most-imported utilities (env-aware config, API client, error mapping).
+- One component-test runner (`@testing-library/react` + the unit-test framework) for the per-app top-five risky components: forms with validation, the API-error fallback, the auth/permission gate, the long-running task UI, and the error boundary.
+- One E2E framework (Playwright or Cypress) for one golden path per app: login → main screen → primary action → logout. Adding more flows is cheap once the framework is wired; the wiring is the expensive step.
+- A coverage floor (e.g., 30% on shared utilities, 50% on API client, golden-path E2E green) gated in PR catches regressions before they hit users; aiming for high coverage on day one is not the goal.
+
+## Cross-App Quality Hygiene
+
+- Dead dependencies (declared in package.json with zero imports) are a recurring finding when multiple authors edit shared starter templates. Lint or a per-CI step (e.g., `depcheck`) catches them.
+- Per-app `@umijs/max` / `next` / `vite` major-version skew (`4.0.x` to `4.4.x` across apps in the same portfolio) is a finding; cap the skew and run a periodic bump pass on the lowest-pinned app.
+- Generated outputs (OneAPI clients, Hertz/Kitex stubs, OpenAPI clients) check into the repo and run formatter-skip rules; CI should fail when generated output is stale relative to the IDL/schema source.

package/dist/assets/marketplace/plugins/ccl-skills/skills/web-react-dev/references/web-ui-quality.md

@@ -0,0 +1,83 @@
+# Web UI Quality
+
+## Rendered Surface Checks
+
+- Inspect changed screens in a real browser for layout, hierarchy, density, responsive breakpoints, scroll behavior, empty/error states, and dynamic content.
+- Capture screenshots or browser evidence for nontrivial UI changes.
+- Watch for text overflow, unstable heights, clipped controls, nested cards, accidental hero layouts in work surfaces, and visual states that move layout unexpectedly.
+- Gate web-font loading so a late font swap does not reflow text (a CLS source). Note `font-display: swap` *avoids invisible text (FOIT) but can itself cause the swap shift* — to minimize layout shift use `optional` (locks to the fallback for the page if the font is slow) or keep `swap`/`fallback` but match metrics with a `size-adjust` / `ascent-override` / `descent-override` fallback `@font-face` plus `<link rel=preload>`; reserve `block` for tiny icon-font cases. For script-measured text, do not block first render on `document.fonts.ready` alone — it only ever resolves (a stalled font can delay it to the UA timeout, and a failed font still resolves); instead reserve space with fallback-compatible metrics, render, then remeasure after `document.fonts.load("400 16px <family>", sampleText)` resolves (the first argument is a CSS font shorthand string, not a family name alone) or a bounded timeout/`requestAnimationFrame` fallback fires. Reserve space for async-loaded images, media, and embeds the same way so first paint does not jump.
+- Verify the four UI/UX judgment layers in the rendered page:
+  - Aesthetic: hierarchy, rhythm, contrast, spacing, material treatment, and mood match the design checkpoint.
+  - Interaction: the visible flow makes the next action clear, preserves context through drawers/modals/details, and returns users to the right place.
+  - Behavioral: pending, disabled, retry, cancel, duplicate-submit, offline/stale, partial, and interrupted states are visible where relevant.
+  - Psychology: the screen reduces uncertainty, waiting anxiety, fear of mistakes, and loss of control.
+
+## Accessibility
+
+- Prefer semantic HTML before ARIA. Use buttons for actions and links for navigation.
+- Every interactive control needs an accessible name, keyboard reachability, visible focus, and a clear disabled/loading state.
+- Forms need labels, validation messages associated with fields, error summary when useful, and keyboard-friendly submit/retry behavior.
+- Modals, popovers, menus, and drawers need focus management, escape/outside-click behavior where appropriate, and return focus on close.
+- Check contrast, text wrapping, zoom/text scaling, and screen reader names for icon-only controls.
+
+## Responsive And Browser Behavior
+
+- Define stable dimensions for fixed-format UI such as grids, toolbars, tables, boards, and controls.
+- Define the primary viewport, stress viewport, and collapse rule before coding. Secondary panels, filters, metadata, and previews should collapse or dock before the primary reading/editing region becomes unusable.
+- Use virtualization or pagination for large lists/tables when rendering cost becomes visible.
+- Preserve useful URL state for shareable/filterable pages.
+- Handle back/forward, reload, auth expiry, offline/stale data, and browser storage expiry deliberately.
+- Long task and upload/review pages should model route-leave, reload, polling timeout, stale task, and terminal failure as component states when the user could lose work or confidence.
+- Dense operations tables need browser checks for long service names, domains, image tags, owner names, status messages, fixed action columns, horizontal scroll, and narrow desktop stress width before the page is treated as shippable.
+
+## Chart And Analytics Workbench Implementation
+
+- Own chart/table modules as runtime state, not static presentation. Keep active scope, selected module, chart/table mode, local settings, comparison target, export/download job, loading/empty/error/stale state, and drill-down context in explicit React owners.
+- Use a shared chart adapter for repeated chart behavior: number formatting, percent precision, zero-label hiding, long-label rotation/truncation, scroll/data-zoom thresholds, legend scroll, tooltip wrapping, mark-line labels, resize cleanup, and negative/under-baseline label placement.
+- Separate raw threshold mode from comparison mode in state and rendering. Threshold mode uses configured bands; comparison mode uses higher/lower semantics against a selected baseline. Switching modes must update legends/copy and preserve compatible filters.
+- User-scoped visual settings need scoped cache keys, invalid-interval validation, disabled save, inline error, reset/default behavior, and module-level refresh of affected data without reloading the whole workbench.
+- Dynamic grouped tables need fixed identity columns, right-aligned numeric cells, grouped headers generated from data shape, sticky or fixed columns only while they remain readable, horizontal scroll boundaries, and measured overflow tooltips for long labels.
+- Entity/sub-item breakdown charts need source and target selectors that cannot select the same entity, special baseline options modeled explicitly, split loading/error/retry for each compared side when the data is fetched separately, and cache invalidation by scope/type/id.
+- Chart cards should keep stable geometry under loading, empty, error, long legends, data zoom, and table mode. A 400px-class chart region, compact title/action row, and stable table container are safer than content-sized charts that jump while data loads.
+- Visual token ownership still applies to analytics pages: theme-map repeated primary, neutral background, border, text, muted text, semantic comparison, and status colors. Local hard-coded chart series colors are acceptable when documented by the chart adapter and covered by legend/contrast checks.
+
+## Shared UI Fallback Surface
+
+In a portfolio that ships multiple React apps, the three "non-happy-path" surfaces below drift visually and behaviorally when each app re-rolls its own. Treat them as portfolio-level shared components, not per-app implementations:
+
+- **Loading surface**: spinner / skeleton / shimmer choice, sizes (page-level vs box-level vs inline), and copy (a localized "loading..." string vs nothing). Apps consuming the same brand should share at least the box-level and page-level loading components.
+- **Empty surface**: empty illustration / icon, primary message, secondary explanation, primary action (refresh / create / change filter), and the "this is empty because" diagnostic line when the user might think the page is broken.
+- **Error surface**: error illustration / icon, user-readable message, support handle (request id / trace id surfaced to the user for support), primary recovery action (retry, go home), and a secondary path (report bug). A bare generic "request failed" toast that never surfaces the request id is a support-cost finding.
+
+A single global `ErrorBoundary` at the route layer plus one inline `<DataBoundary>` (loading / empty / error tri-state) component cuts most of the per-page reinvention. Per-app variants are acceptable only when the surface has a domain reason (chart card vs list vs form).
+
+## Shared Device And Inactivity Session
+
+When the surface runs on a shared device (a public kiosk, a counter-staff terminal, a lobby check-in screen, a clinic intake tablet, a retail store-back tablet) rather than a personal device, the session-management contract differs from a normal web app:
+
+- **Inactivity detection listens on the full input event set**: `pointerdown / mousedown / click`, `touchstart / touchmove / touchend`, `mousemove`, `scroll`, `keydown` — at minimum. A subset misses real activity classes: pointer-only misses touch; click-only misses scroll-only browsing; keyboard-only misses pure-touch UIs. Each registered listener is removed in the cleanup return value of the same hook / effect — leaked listeners survive Hot Module Replacement and accumulate during development.
+- **Custom scroll containers register their own listeners**: when the page uses CSS-Y-scroll containers (`overflow: auto` divs, virtualization wrappers) instead of body scroll, the `scroll` event does not bubble to `document` and the inactivity timer does not reset on scroll-only interaction. Add an explicit selector (`.scrollable-div`, `[data-scroll-region]`, framework's scroll-container class) and register the listener on each matched node, with the same cleanup.
+- **Reset is throttled, not raw-debounced**: `lodash.throttle(..., 200ms)` (or equivalent) wraps the timer-reset callback so a continuous gesture (mousemove drag, touch scroll inertia) does not call `clearTimeout / setTimeout` hundreds of times per second. The throttle window is short enough that the user's last gesture still resets the timer.
+- **Two-stage terminal UX**: detect inactivity → show a modal with a visible countdown ("system will exit in 5s") that the user can dismiss with a primary "stay" action; on countdown 0 with no dismissal, run the terminal action (logout, return to neutral home, lock screen). Single-stage immediate logout loses the user's in-progress work on a stale screen; no-countdown modal leaves users uncertain what is about to happen.
+- **Terminal action is "return to neutral", not "log out and stay"**: on a shared device the next user is a different person, so the terminal action navigates to a known clean state (the public home page with no user context, the login screen, the device's welcome surface). Just unsetting `auth.user` leaves the previous user's UI state visible until the next navigation — a privacy leak the rest of the page does not know to clear.
+- **Cross-tab / cross-component coordination: durable store is authoritative, broadcast is only notification**: tabs coordinate through `localStorage` (or another durable same-origin store like IndexedDB) holding the shared `lastActivityAt` / `expiresAt`. `BroadcastChannel` may be added as a low-latency notification path that wakes other tabs, but the broadcast carries no authority — every consumer re-reads the durable store before acting. Immediately before running the terminal action, the tab re-reads `expiresAt` from the same durable store that holds it and aborts if another tab has extended it. `BroadcastChannel` alone is unsafe: BroadcastChannel state is per-tab and in-memory, a throttled background tab or a BFCache-resumed tab missed every prior broadcast and has no way to learn the current `expiresAt`. Broadcasting "activity happened" alone (without the durable store backing it) lets an idle tab run the terminal action milliseconds after another tab refreshed activity. Scoping: the shared key includes `device-mode` (shared-device vs personal-device) so personal-tab activity on the same origin does not extend shared-device sessions.
+- **Inactivity timeout is shorter on shared devices than personal**: 30s to 5min is the realistic shared-device range (public kiosk ≈ 30s-2min, counter terminal ≈ 5-15min); the same app on a personal device might be 30min to never. Choose the value from the deployment context, not from the developer's laptop.
+- **Server-side session expiry is independent of client-side inactivity**: client-side inactivity is a UX defense (clean handoff between users on the device); the server enforces session lifetime, idle-token expiry, and concurrent-session limits independently. A client that quietly extends a session by faking activity must still be cut off by the server's token TTL. Conversely, a network-disconnected client whose timer pauses does not get an indefinite session — the server invalidates it on its own clock.
+
+## Animation And View Transitions
+
+- **Prefer compositor-friendly properties for hot-path motion.** Use `transform` and `opacity` for high-frequency, large-area, route, scroll-linked, or continuous motion — the browser can usually animate them off the main thread; avoid animating layout properties (`width`, `height`, `top`, `left`, `margin`) on hot paths, since they retrigger layout each frame and jank. Targeted paint-only transitions (`color`, `background-color`, `border-color`, shadow) are fine for small state/theme changes. Never use `transition: all` — list the exact properties so an unrelated change does not animate unexpectedly. Use `will-change` sparingly and remove it after the animation.
+- **Honor `prefers-reduced-motion` for any non-essential motion.** Wrap transitions / parallax / autoplay / continuous-loop animations in `@media (prefers-reduced-motion: reduce)` (CSS) or `matchMedia('(prefers-reduced-motion: reduce)')` (JS) — substitute instant state change for animation. Decorative motion that ignores the user setting is an accessibility finding.
+- **View Transitions API is progressive enhancement only.** For SPA in-app transitions use `document.startViewTransition()`; for cross-document MPA navigation the `@view-transition` CSS at-rule is the opt-in. Feature-detect (`'startViewTransition' in document`) before invoking the JS API; the non-transition path (instant DOM update) MUST be the fallback. Browsers without support, users with `prefers-reduced-motion: reduce`, and slow devices all need the no-animation outcome to work identically. **Framework router integration is not universal** — Next's view-transition config and React's `<ViewTransition>` component are still flagged experimental / Canary at the time of writing; verify your router's integration status before adopting at the route layer.
+- **Transitions never delay user-perceptible feedback.** A submit button that animates the form away before showing pending/success state hides the action result. Use view transitions for navigation choreography between stable states, not as a substitute for loading / disabled / error UI.
+- **Transitions cannot block focus restoration.** When a route or modal transition starts, focus must still land on the post-transition target (heading, primary action, error message) within the same frame the transition completes — keyboard users cannot wait for animation to interact.
+- **One transition system per portfolio.** Mixing `framer-motion` + `react-spring` + raw `@keyframes` + View Transitions in the same app fragments timing curves, easing, and reduced-motion handling. Pick one for component-level motion (framer-motion is common) and use View Transitions for route-level choreography when supported; document the split.
+
+## Cross-Cutting Concerns At Implementation Time
+
+These cross-cutting concerns get under-invested when each PR ships one feature; capture the implementation rules at the portfolio level:
+
+- **i18n boundary**: wrap user-visible strings in the i18n call site even when the portfolio ships in one language today; the lint plugin (or a custom one) flags string literals in JSX as findings. The cost of catching them at write time is small; the cost of migrating thousands of literals later is large.
+- **a11y baseline**: enable `eslint-plugin-jsx-a11y` recommended rules; a per-PR cap of jsx-a11y violations starts at "current count" and only ratchets down. Focus management for modal / drawer / popover open-close cycles is a per-component checklist, not optional polish.
+- **Responsive breakpoint source**: read breakpoint values from one place (the CSS engine config, the component suite theme, or a shared `breakpoints.ts`). A raw `max-w-[600px]` in one app and `lg:px-8` in another is acceptable as long as both resolve to the same scale.
+- **Trace surface for support**: every user-visible error should surface the request id / trace id (small text, copy-on-click, or attached to the bug-report flow). Without it, on-call cannot map a screenshot to a log line. Read it from the response header (the back end already emits it — see the cross-stack contract in `python-service-architecture/references/api-contract-and-schema.md` and `go-microservice-architecture/references/protobuf-contract-architecture.md`).