@ccoalm/ccl-skills 0.1.0

package/dist/assets/marketplace/plugins/ccl-skills/skills/web-react-dev/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: web-react-dev
+description: Use when designing, implementing, reviewing, debugging, testing, or shipping React web client features, including component structure, routing, state ownership, API/data fetching, forms, browser behavior, accessibility, performance, build/deploy, and rendered browser verification. Product-agnostic; use miniapp-product-dev for WeChat/Alipay/Douyin/Baidu mini-programs, app-cross-platform-dev for Flutter/React Native/Android/iOS apps, product-ui-ux-design for UI/UX rules, backend skills for services, and testing-strategy for test-layer planning. Triggers also include "用 React 实现这个前端", "React 组件怎么写", "React 写一个", "Tailwind 怎么写", "Next.js / Vite 项目配置", "重构这个 React 组件/页面(局部)", "refactor a React component/file".
+---
+
+# Web React Dev
+
+Use this skill for React web client engineering. It covers browser-rendered React applications, React components, routing, data fetching, forms, frontend API integration, accessibility, performance, build, and deploy checks. It does not own mini-program host behavior, Flutter, native mobile, backend service design, or visual design system rules.
+
+## Routing
+
+- Use `product-rd-workflow` first when the work spans product, design, architecture, implementation, testing, review, and release.
+- Use `product-ui-ux-design` before or alongside coding for interaction model, layout, visual hierarchy, density, states, and UI acceptance.
+- Use `miniapp-product-dev` for WeChat/Alipay/Douyin/Baidu mini-program pages, host-platform APIs, developer tools, review submission, and release. For React/H5 embedded inside a mini-program webview, this skill owns the React page while `miniapp-product-dev` owns the mini-program shell, bridge, host capabilities, and review/release evidence.
+- For Taro projects (React syntax compiled to mini-program runtime): this skill owns the React layer (component decomposition, hooks, state ownership, effect discipline, accessibility primitives) and the **pure** shared layer in the repo's established shared module: DTOs, types, validators, pure mapping functions.
+  - `miniapp-product-dev` owns Taro lifecycle hooks (`useReady`/`useLoad`/`useDidShow`/`useDidHide`), `Taro.*` runtime APIs, platform branching (`process.env.TARO_ENV`, conditional compilation, platform-specific files), subpackage configuration, host capability adapters, multi-target build invocation, host review/release, and rendered mini-program evidence.
+  - Shared **runtime adapters** that mini-program targets consume are co-owned with a named final-decision owner per adapter, recorded in the repo. The adapter list and the miniapp acceptance-gate enumeration are canonical in `miniapp-product-dev` (the `Shared runtime adapters consumed by mini-program targets` row under `## Sibling Boundary With web-react-dev`); that gate is blocking and its miniapp contract tests must pass before mini-program targets import the adapter. Web sets browser semantics and cannot merge an adapter change that is browser-safe but mini-program-unsafe. Do not re-add a fixed kill-switch dimension list here: the owner's safety contract names the property (`fail-closed flag evaluation`) and its release contract makes each host platform's gray-release mechanism its own contract, so the dimensions a given adapter needs come from that platform's contract, not from a list on this side. Before merging an adapter change, the merge record must carry the canonical row's gate token and a passing miniapp-contract run recorded on the change under merge (rule canonical in that row); a merge record without the token, or asserting mini-program-safety without the contract run, is a violation.
+  - When shared code must run in both web and mini-program targets, keep `react-dom`, DOM mutation, browser observers (`IntersectionObserver`/`ResizeObserver`/`MutationObserver`), RAF/layout APIs, and other browser globals out of the shared layer; use Taro cross-platform equivalents at the consumer side.
+- Use `app-cross-platform-dev` for Flutter, React Native, native Android, native iOS, app store release, and device-native capability work.
+- Use Go or Python backend skills for API/service ownership, persistence, auth services, queues, and server contracts.
+- For backend HTTP integrations, preserve current client wire behavior unless an explicit consumer-migration decision exists. Classify JSON vs protobuf-backed HTTP using `../platform-service-connectivity/references/protobuf-http-contract-signals.md`.
+  - First decide whether the client diff touches the HTTP contract or wire behavior. Wire-unchanged UI/component/state work does not need a backend owner round-trip and must not claim backend contract conformance.
+  - For unrelated client work, classify the diff with the canonical gate. If the surface is out of scope, client work may continue without claiming backend contract conformance.
+  - If the canonical gate classifies the diff as in scope, confirm the backend's recorded wire format or route back to the backend contract owner.
+  - Routine JSON/OpenAPI changes use the existing API contract record and do not require backend wire-format confirmation when the canonical reference classifies the surface as out of the protobuf wire-format gate.
+  - Client API wrappers must consume the backend contract's recorded response envelope per `../platform-service-connectivity/references/http-response-envelope-contract.md`: for surfaces on the canonical `code`/`message`/`data` envelope, components and domain state read typed business data from `data`; other shipped or non-JSON envelopes are consumed per their recorded contract. Read only fields present in the recorded contract — do not infer business fields from unrecorded top-level or fallback shapes — and scatter no duplicate envelope parsing across the client.
+  - If backend wire-format evidence is unreachable for an in-scope surface, stop at `pending-contract-owner`, name the backend owner or owning repo, record the attempted lookup, and set the next escalation path. An assumed-wire-format note never unblocks merge. The blocker clears only when a checkable owner record, quoted prior backend record, or explicit migration decision is available; if no owner responds within the team's review SLA, keep the client change blocked or downscope the touched wire-format surface and record the dropped surface as an open owner-routed gap. Do not claim backend contract conformance or completion for the removed slice.
+  - Do not fork IDL or hand-maintain duplicated DTOs in the web repo.
+- Use `testing-strategy` to choose unit/component/API/E2E layers; return here for React-specific implementation.
+- Use `test-artifact-management` when the ask is about generating structured test cases from a Feishu requirements doc or codebase and tracking them in Feishu Bitable before implementation begins.
+- Use `defect-diagnosis` first for failed tests, browser bugs, hydration/rendering issues, flaky UI, API integration symptoms, or production regressions.
+- For money, quota, permission, tenant/user data, high-impact AI, repeated submit, async finality, or support-traceable incidents, apply `product-rd-workflow` high-risk resilience gates before treating the UI as complete.
+
+## Core Workflow
+
+Before editing components, routes, state, API clients, styles, configs, or tests, complete enough analysis and planning for the change to be reviewable. Scale the plan to risk: a simple low-risk single-component change can use a short inline plan; multi-file, user-visible, API-visible, accessibility-sensitive, release, bug-fix, branch/MR, unclear-risk, or high-risk work needs explicit task split, design checkpoint, acceptance checks, verification commands, rollback or stop conditions, and named handoffs to design, testing, miniapp/app, backend, or diagnosis skills before edits.
+
+Repo-local agent contracts (`AGENTS.md` at the repo root and in source directories) are part of the delivery contract: when a change moves a stable boundary, generated surface, workflow, or directory-local rule, update the nearest contract in the same MR and keep coverage in sync per `product-rd-workflow`'s spec / repo-contract sync gate.
+
+When checking a React project against team standards, split findings into deterministic checks and agent review checks. Deterministic checks cover package scripts, typecheck/lint/test/E2E commands, generated API client usage, environment configuration, CI gates, bundle/performance budgets, and request/trace identifier propagation in central clients. Agent review checks cover component ownership, state placement, API contract alignment, finite-value mapping, accessibility/design quality, and whether tests assert behavior instead of only rendering. For the concrete deterministic executor list (ecosystem linter/analyzer rules — `eslint-plugin-react-hooks`, `@typescript-eslint` typed rules, `dependency-cruiser`, tsconfig `strict`/`noUncheckedIndexedAccess`) and the shipped client language-basics conformance checkers, see `testing-strategy/references/fitness-functions.md` §4.1.3 (client language-basics; spec 006). Prefer enabling ecosystem rules over hand-rolling checks.
+
+1. Define the web surface.
+   - Route/page, component boundary, URL params/query state, auth/permission state, responsive breakpoints, and browser support.
+   - User-visible states: loading, skeleton, empty, partial, success, error, retry, disabled, permission denied, stale/offline, and optimistic update.
+   - Data boundary: API client, request cancellation, cache/revalidation, mutation invalidation, pagination, streaming/websocket if used, and typed error mapping.
+   - API observability: central clients should attach or preserve request/trace/operation identifiers, measure duration, distinguish cancel from failure, classify upload or long-running requests, and map backend envelopes into typed user-facing errors.
+   - Finite-value boundary: generated API enums, backend string codes, URL query values, route params, filters, analytics dimensions, and display labels should flow through one typed client/domain mapping module. Components should use the mapped symbols and label tables instead of scattering raw values such as `"US"`, `"CN"`, `"active"`, or `"default"` in render, tests, routing, or tracking code. If shared client-domain ownership is unclear, keep a local mapper for the slice, mark temporary duplicate/raw uses with `finite-value-debt: <task-ref> <owner> <deadline> <reason>`, and record the consolidation owner. Architecture owns the cross-stack semantic decision when the same value must align across web, app, mini-program, backend, storage, and analytics.
+
+2. Analyze the existing web surface.
+   - Locate the owning route/page, component tree, state owner, API client, data-fetching layer, styling system, tests, and build scripts before editing.
+   - Identify whether state belongs in URL/query params, cache/server state, form state, local component state, browser storage, or global app state.
+   - Read repo wrappers first: package manager, dev/build scripts, lint/typecheck/test runners, browser/E2E tools, environment variables, and generated clients.
+   - If a design exists, map visible states and interactions to component ownership before implementing.
+   - For any visible UI change, map the design checkpoint to implementation ownership before coding: visual hierarchy/density, interaction flow, behavioral feedback, user psychology, responsive collapse, and screenshot acceptance. Do not reduce the design to component names. Also record `product-ui-ux-design`'s implementation-owner checkpoint before the first edit — its field list (design/stack/test owners, entry-rule evidence, rendered/device evidence status) and copy-only path are authoritative there; load the named owner skills rather than only naming them, and treat a completion claim without `captured/verified` rendered evidence as incomplete — an explicitly accepted gap closes the slice only as `pre-runtime-test ready` / handoff, never as complete/done.
+   - For UI/UX redesign slices meeting `product-ui-ux-design`'s page-slice trigger conditions — that gate's trigger list is authoritative and must be checked, not paraphrased, whenever a screen/surface change could be a redesign, restyle, new-style declaration, structural/visual-system change, continuation, or redesigned-surface reference — apply its cross-stack page-slice gate before React mechanics: RED-first focused assertion, IA regrouping by user intent/consequence, behavior-contract preservation, state matrix, rendered evidence, and the design verdict (`accepted` / `rejected` / `pending`; missing = `pending`, and `design-rejected` blocks complete/MR-ready/normal/draft MR per the **Rejected-surface rule**). Web is not a lower-evidence surface than app; component tests or DOM snapshots must be paired with browser-rendered evidence for changed layout, interaction, or visual states.
+
+3. Structure React code by ownership.
+   - Decompose UI by responsibility, not by arbitrary visual fragments.
+   - Put state at the lowest owner that needs to read/write it; lift only when siblings need shared state.
+   - Keep derived data derived during render or memoized only when measured or clearly necessary.
+   - Avoid Effects for pure derived state, event handling, or data transformations that can happen during render.
+   - Isolate side effects: network, subscriptions, timers, storage, analytics, and imperative browser APIs.
+   - Keep route loaders/actions, client caches, or data-fetching libraries aligned with the repo pattern.
+
+4. Implement browser behavior deliberately.
+   - Forms need validation, submit pending state, disabled/retry behavior, server error mapping, and keyboard behavior.
+   - Navigation needs route guards, deep links, back/forward behavior, scroll/focus restoration, and not-found/permission states.
+   - Tables/lists need stable keys, empty/error rows, pagination or virtualization when needed, persisted filters where useful, selected-count state, bulk operation feedback, clear reload/reset behavior after actions, and non-janky loading.
+   - Workbench pages need explicit route/layout ownership, context strips, active job/task entries, permission-gated actions, and drawer/detail inspection that preserves parent context.
+   - Workbench layout needs code-level geometry: bounded shell/header/control/work regions, sticky or preserved context, named collapse rules, stable empty/loading/error geometry, and secondary panels that collapse before primary content becomes unreadable.
+   - Complex workbench variants are reference-level material, not entrypoint material. If the surface is a dense review, report, assignment, resource, assistant, media/capture, or app-hosted workspace, load `references/complex-workspace-patterns.md` and apply only the relevant pattern family.
+   - In complex workspaces, declare state owners for route/context, selection, filters, permissions, async jobs, restored preferences, media readiness, submit/finality, and child drawers/panels before coding. Validate restored state against the current route, identity, permission, task type, and available item count.
+   - Mature workspace shells should implement code-level contracts, not only CSS: token-to-theme binding, startup context, route/permission-derived navigation, durable jobs, measured overflow, secondary-panel collapse, upload/parse state machines, and browser screenshot acceptance at declared stress widths.
+   - Token provenance must be visible in code: map design tokens into the component-library theme first, then local CSS should reference theme variables or documented semantic values.
+   - Workbench shell responsiveness needs explicit code thresholds: minimum widths, fallback layout, scroll owner, sticky enablement, and collapse order.
+   - Embedded, hosted, or app-container web shells need code-level ownership for entry paths, host/source detection, allowlisted origins, defensive message parsing, layout switching, persisted host flags, normal-browser fallback, lifecycle restore, and storage failure recovery.
+   - Auth, account, assistant, report, assignment, resource, media/capture, and AI-recognition variants are detailed in `references/complex-workspace-patterns.md`; do not keep their source-specific state catalogs in this entrypoint.
+   - Long work, high-risk submits, destructive actions, and AI/data operations need pending/final state, duplicate-submit protection, timeout/failure UI, retry/recovery, and a stable visible identifier when support or reconciliation may be needed.
+   - Configurable shortcuts or command palettes need a parsed and normalized registry, platform-aware display labels, reserved/non-rebindable shortcut checks, duplicate and conflict warnings before lossy config parsing, explicit scope/context priority, user override plus explicit unbind semantics, invalid-config fallback to defaults, reload/delete cleanup, command action allowlists, and collision-safe discovery UI. Dispatch must isolate shortcuts from text inputs, editable fields, composition/IME, modal focus traps, and command palette focus; chords or multi-step sequences need timeout/cancel handling, propagation rules, and cleanup on unmount.
+   - Chart, canvas, image, PDF, annotation, dense table, card, menu, browser storage, and cross-tab behavior need lifecycle cleanup, measured overflow, accessibility, and browser evidence at realistic container widths.
+
+5. Debug systematically when behavior is wrong.
+   - Reproduce with the smallest page, route, component test, browser trace, or network fixture that shows the failure.
+   - Classify the failure by layer: route, render/hydration, component state, effect/subscription, API contract, cache/revalidation, browser storage, permission/auth, build/env, or deployment/cache.
+   - Inspect console errors, failed network requests, request/response payloads, React warnings, route params, cache state, feature flags, and environment variables before changing code.
+   - Prove whether the issue is browser-only, data-contract, state ownership, styling/layout, or backend behavior; route backend fixes to backend skills.
+   - Add regression evidence at the lowest sufficient layer, then run browser smoke for visible flows.
+
+6. Verify in a real browser.
+   - Run the repo's formatter, typecheck, lint, unit/component tests, and build or affected checks.
+   - **TC traceability**: link tests via the `createTcSuite(test, describe)` factory wrapper. Registers at collection time so `.skip` / `.skipIf` / `.todo` still map to Bitable status. Full overloads supported: `.concurrent` / `.each` / `(name, options, fn)` / `(name, fn, timeout)`. Helper from `test-artifact-management/references/tc_helpers/tc.ts`, installed under `test/tc.ts`. See `test-artifact-management/references/tc-marker-conventions.md`. Before adding tests, `grep -rn 'tcTest\|tcDescribe' src/ __tests__/` plus the sidecar `test/results/tc-map.jsonl` to check for existing coverage — extend rather than duplicate. When a TC is marked 废弃, grep both source and sidecar; follow deprecation cascade in `testing-strategy`. Tests without any TC link: prompt user only when the underlying code is also removed.
+   - **废弃级联：业务代码是否仍在用** — TS/JS 用 `madge` 拿依赖图最准，没安装则 grep 兜底：
+     1. `npx madge --dependents src/path/to/Module.tsx`（列出谁 import 了它）；或 `grep -rEn "from ['\"][./]*<path>" src/`
+     2. 排除测试文件后还有 import → 产品代码在用，不删；只剩这个测试 → 同 commit 删模块 + 测试
+     3. 路由级别另查：`grep -rn "<RouteComponent>" src/router src/routes`；运行时 lazy import (`React.lazy(() => import('...'))`) madge 能抓但要 `--include-npm` 等参数核对
+     4. 边界：路径别名（`@/foo`）需 madge 的 `tsconfig` 配；动态 `import(name)` 字面值为变量时 grep 抓不到；CSS / 静态资源 import 的 dead-asset 由 build 报告
+   - For API-backed UI, test component states, API client parsing/error translation, and at least one browser/E2E smoke path when feasible.
+   - Inspect the rendered page in a browser for any visible UI change, responsive behavior, empty/error states, and console/network errors.
+   - For UI/UX redesign evidence, include the declared stress viewport, or when none exists use the minimum supported width plus one narrow stress width such as 320px; text wrapping/overflow; loading/empty/error/final states; keyboard/focus path; and a browser screenshot or equivalent visual artifact. Mark each dimension covered or `N/A` with a one-line reason; `N/A` is valid only when the reason names a verifiable structural fact, explains why that fact makes the dimension unreachable or unchanged for this slice, and includes a checkable pointer such as a file path, config key, or commit that resolves at review time. Persist evidence artifacts where reviewers can access them using sanitized/test accounts and redacting tokens, PII, credentials, private paths, and raw personal data; delete temporary smoke pages or helper scripts before commit unless the repo intentionally owns them.
+   - For browser-runtime changes, browser smoke is a completion gate when lower layers cannot prove the behavior. This includes changes to routing, browser storage/session restore, streaming/fetch finality, visibility or foreground/background behavior, permission/capability prompts, WebView bridge callbacks, upload/media flows, and rendered loading/error/final states. If the browser or app server is missing, first attempt normal setup; if still unavailable, stop at `pre-runtime-test ready` or `blocked` and name the owner, attempted commands, residual risk, and next unblock action. `pre-runtime-test ready` is handoff-only, not merge-ready, release-ready, or complete.
+   - Check accessibility names, labels, focus order, keyboard navigation, aria only when semantic HTML is insufficient, contrast, and text wrapping.
+   - Check performance when relevant: bundle impact, unnecessary renders, long lists, image loading, code splitting, hydration/runtime errors, and Core Web Vitals risk.
+
+## Non-Negotiable Rules
+
+- Do not use mocked happy-path component tests as proof that API integration works.
+- Do not add Effects for state that can be derived from props/state during render.
+- Do not ship user-visible UI without inspecting the rendered browser surface when layout or interaction changed.
+- Do not add hidden keyboard traps, icon-only controls without accessible names, or mouse-only critical actions.
+- Do not ship configurable shortcuts as scattered `keydown` handlers; centralize parsing, normalization, scope resolution, reserved-key enforcement, unbind/override behavior, and text-input or modal isolation.
+- Do not let server transport errors leak directly into user copy; map them to useful UI states.
+- Do not ship high-risk actions with only optimistic UI or generic success/error toasts; users must be able to tell whether the operation is pending, succeeded, failed, retryable, blocked, or needs support.
+- Do not treat a frontend API client as done until empty response, invalid JSON, non-2xx envelope, auth expiry, network failure, cancellation, and backend error message extraction are covered at the client or component boundary when relevant.
+- Do not scatter backend enum/string literals through React components, URL/query handling, analytics, or tests. Centralize finite-value parsing, display labels, defaults, and unknown-value behavior at the API/client-domain boundary, and keep raw literals only in clearly named boundary conversion tests that cover every known external value plus unknown/default behavior. Migrate existing non-boundary test raw literals for that value in the same pull request or mark each remaining use with `finite-value-debt: <task-ref> <owner> <deadline> <reason>`, even when the current slice does not introduce a new mapper.
+- Do not debug React/browser failures from code inspection alone when a browser reproduction, console output, network trace, screenshot, or focused test can be collected.
+- Do not claim a web client fix is complete without naming the browser/rendered verification that was run. If required browser/runtime verification is unavailable after remediation, the status is `pre-runtime-test ready` or `blocked`, not complete.
+
+## Reference Loading
+
+- For source provenance, current extraction boundary, and keep/merge/discard decisions, read `references/source-evidence-map.md` when auditing or re-extracting this skill.
+- For embedded H5 inside a host (mini-program `web-view` / native WebView / payment / vendor app WebView) — H5-author POV: env detection, bridge abstraction, auth-from-host (cookieless), hardware-back integration, safe-area + viewport-fit, host capability degradation, WeChat JSSDK specifics, offline / lifecycle, cross-app navigation, anti-patterns, multi-host smoke matrix — read `references/embedded-h5-in-host.md`. The host-side contract (web-view component / WebView shell config / native bridge setup) is owned by `miniapp-product-dev` (mini-program host) and `app-cross-platform-dev` (native WebView shell).
+- For joint extraction from Figma design source AND a React/web monorepo (with package class mapping, design-token cross-validation, deprecation-marker detection), read `../skill-extraction-workflow/references/two-source-extraction-pattern.md`. Use when both sources are available; produces aligned design + implementation rules with cross-source token validation.
+- For component decomposition, state ownership, effects, routing, forms, and data fetching, read `references/react-architecture.md`.
+- For dense review, report, assignment, resource, assistant, media/capture, or app-hosted workspace state-machine patterns, read `references/complex-workspace-patterns.md`.
+- For browser accessibility, keyboard/focus, responsive behavior, and visual verification, read `references/web-ui-quality.md`.
+- For API integration, caching, error handling, testing, performance, build, and deployment readiness, read `references/web-quality-release.md`.

package/dist/assets/marketplace/plugins/ccl-skills/skills/web-react-dev/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Web React Dev"
+  short_description: "Build React web client features"
+  default_prompt: "Use $web-react-dev to design, implement, test, or release a React web client feature."

package/dist/assets/marketplace/plugins/ccl-skills/skills/web-react-dev/references/complex-workspace-patterns.md

@@ -0,0 +1,47 @@
+# Complex Workspace Patterns
+
+Use this reference after `web-react-dev/SKILL.md` identifies a React surface as a dense workspace rather than a normal page/form/list. Keep the entrypoint small; apply only the relevant pattern family below.
+
+## Pattern Families
+
+### Review / evaluation workspaces
+
+- Own queue/task identity, selected record, selected sub-unit, current-item header, queue switching, batch selection, submit mode, incomplete-item confirmation, and queue-end recovery.
+- Keep artifact layout readable by deriving split count from container width and a declared minimum card width. Persist user display preferences with scope and expiry, then validate restored settings against route, permission, task type, and item count.
+- Preview media/documents with automatic transient retry plus manual retry. Keep per-item annotation, disabled reasons, local/global success feedback, quality/timing gates, and history/statistics drawers as separate state owners.
+
+### Insight / report / analytics workspaces
+
+- Treat list filters, detail route params, selected report/module, menu state, local section anchors, scope filters, exports/downloads, module config changes, and parent return context as one route contract.
+- Validate cached filters against the current option set; clear stale dependent filters deliberately and refetch authoritative data after create/edit/delete/default mutations.
+- Chart, canvas, image, PDF, or annotation components need cleanup, resize handling, device-pixel-ratio correctness, zoom/pan/reset where relevant, and browser evidence for overflow, long labels, and drill-down linkage.
+
+### Assignment / roster / resource management workspaces
+
+- Keep structure edits, owner edits, permission edits, quota edits, import/export jobs, save/autosave/finalize, and read-only/started variants as separate state transitions.
+- Selection drawers need search, cascade filters, role/qualification filters, all/partial selection, selected-count panel, disabled existing owners, max-count handling, bulk clear, removal, and no-result states.
+- Resource and taxonomy flows need route scope, resource type, hierarchy mode, selected tree node, filters, pagination, selected resource, preview/detail, share/publish/download settings, upload/import jobs, and cached-filter restoration as distinct owners.
+
+### Assistant / AI workspaces
+
+- Compose state should separate prompt text, attachments, capability modifiers, model indicator, send/cancel, generated-output actions, IME composition, and scroll/history recovery.
+- Streaming needs terminal states: waiting for first response, append, timeout abort, auth/session expiry, quota/content refusal/model unavailable, network/user-send failure, user cancel, server interrupt, done, regenerate, copy, and timer/controller cleanup.
+- AI-generated structured output needs validation, renderer failure fallback, save/retry/remove semantics, already-saved state, and generated-to-saved-object reviewability.
+
+### Media / capture / import workspaces
+
+- Capture/import flows should model file identity, metadata form state, parent/child cascades, consistency checks, parse/enrichment polling, background continue, retry/reupload, partial failure, and navigation to the next editor/detail step.
+- Native-assisted or app-hosted capture treats the bridge payload as an API contract: normalize success/cancel/failure, parse payloads safely, validate object key/URL/file type/name, and keep callback cleanup scoped.
+- Do not clear loading or host overlay state immediately after native success if a route handoff is still pending; hold it until the destination route mounts and signals readiness.
+
+### Auth / account / app-hosted foundations
+
+- Auth/onboarding surfaces need explicit mode ownership: splash handoff, consent, password login, phone-code login, account opening/binding, first-password setup, reset, guest/public mode, privacy/legal links, and deterministic back paths.
+- App-hosted React surfaces need lifecycle ownership in React code: save/restore foreground/background state, expire stale state, omit or protect sensitive fields, validate restored route/context, and recover when browser storage, host storage, or injected app info is unavailable.
+- Account/profile/privacy/about routes should share logout, account deletion, legal document loading, version/about, cache cleanup, and post-action navigation contracts.
+
+## Acceptance Checks
+
+- State owner map exists for every selected pattern family.
+- Long content, empty/no-data, error/retry, slow/weak network, permission/disabled, narrow/responsive, accessibility text scaling, interruption/return recovery, and repeated-use/cache-hit behavior are either tested or explicitly out of scope.
+- Browser or host-container evidence captures the declared stress widths and the primary pending/final/error states. If rendered evidence cannot run after normal remediation, status is `pre-runtime-test ready` or `blocked`, not complete.

package/dist/assets/marketplace/plugins/ccl-skills/skills/web-react-dev/references/embedded-h5-in-host.md

@@ -0,0 +1,87 @@
+# Embedded H5 In Host
+
+Use this reference when the React web surface is embedded **inside a host** rather than running as a standalone browser page. Common hosts: mini-program `web-view` (WeChat / Alipay / Douyin / Baidu / QQ), native mobile WebView (`WKWebView` / Android `WebView`), payment-vendor WebView, vendor-app WebView (banking apps, super apps). Not for: standalone PWA, public website, marketing landing page.
+
+The host imposes constraints a standalone React app does not face. This ref names the recurring contract surface; sibling responsibility lives in `miniapp-product-dev` (mini-program host side) and `app-cross-platform-dev/references/{ios-dev, android-dev, mobile-platform-boundaries}.md` (native WebView shell side).
+
+## When This Ref Applies
+
+- The page loads inside a host's WebView, not the user's browser.
+- The host owns auth, navigation, share, payment, scan, file/image upload, location, status bar, and back-button behavior. The H5 is a guest.
+- Source-of-truth for the contract is the host's official docs (WeChat JSSDK / WKWebView WKScriptMessageHandler / Android `WebView` `addJavascriptInterface`); H5-side guesses without consulting host docs ship broken.
+
+## Host Environment Detection
+
+- **Detect the host explicitly** before invoking any host-specific bridge: WeChat = prefer `wx.miniProgram.getEnv(...)` (canonical async check that resolves `{miniprogram: true|false}`) — `window.__wxjs_environment === 'miniprogram'` and UA `MicroMessenger` substring remain as legacy / early-detection fallbacks before WeChat JSSDK is loaded; Alipay = UA contains `AlipayClient`; mini-program `web-view` = check for `wx.miniProgram` / `my.miniProgram` / `tt.miniProgram` etc. Cache the detection at app init; do NOT re-sniff in every component.
+- **Defensive feature checks** beat UA-sniffing for capability presence (`typeof wx !== 'undefined' && typeof wx.config === 'function'`). UA-sniffing is for env classification + analytics labeling; per-call feature check is for guarding the actual invocation.
+- **In-browser fallback path** is mandatory: the same H5 may open outside the host (testing, sharing as plain URL, fallback when host restricts). For each host-capability touchpoint, design and test the in-browser degradation (disabled button + tooltip, alternative web-native flow, or explicit "open in <host>" prompt).
+
+## Bridge Contract Abstraction
+
+- **Never hardcode one host's bridge directly in component code**: wrap all host calls in a thin per-host adapter (`HostBridge.share(...)`, `HostBridge.pay(...)`, `HostBridge.scan(...)`) plus a single registry that resolves to WeChat / Alipay / Native / Web-fallback at runtime. Without this, every host added later means rewriting call sites. When adopting an existing native bridge library (DSBridge, WebViewJavascriptBridge, custom in-house bridge), verify the library's current maintenance state and security posture — both legacy libraries are still in use in production codebases but their repos may be inactive; the abstraction layer above them lets you swap the implementation without touching call sites.
+- **Bridge calls are async** and can fail / time out / be denied by the user. Treat every bridge invocation as a network call: typed result, error class, timeout, user-cancel state, and UI feedback when the host is slow. Synchronous-call assumption is the recurring source of "tap does nothing" bugs when the bridge is slow on first invocation.
+- **JS-bridge auth is per-message, not per-handshake** (per `miniapp-product-dev/references/platform-capabilities.md` WebView bridge contract): the host re-validates origin + nonce + session tuple on every inbound bridge call. H5 cannot cache a successful handshake and assume future calls succeed.
+
+## Auth From Host (Cookieless Session)
+
+- **Do not assume cookies / localStorage persist across host sessions**: mini-program `web-view` and many native WebViews isolate storage per app launch or even per page-open. Treat storage as cache, not as source of session truth.
+- **Auth token comes from the host**, not from a cookie-based login flow. Standard patterns: (a) signed URL query parameter from the host (`?token=<host-issued-jwt>`); (b) bridge call to fetch token (`HostBridge.getAuthToken()`); (c) host-injected initial JavaScript variable. Document which pattern the project uses; do not mix.
+- **Token rotation needs an explicit refresh path** (for authenticated H5 consuming a host-issued token; not needed for unauthenticated content surfaces): on 401, attempt token refresh via bridge; if refresh fails or no bridge, surface a re-login flow that respects the host's auth model (e.g., navigate back to host login surface, not to an H5 login page that the host can't drive).
+
+## Hardware Back Button + History Integration
+
+- **Android hardware back is part of the contract**: the host's `Activity` `onBackPressed` (or modern `OnBackPressedDispatcher` per `app-cross-platform-dev/references/android-dev.md`) typically intercepts back and either calls `webView.goBack()` (when `canGoBack()` is true) or finishes the host activity. H5 `history.pushState` / `popstate` integrates correctly when host wires this through; without it, hardware back exits the entire WebView when H5 expected internal navigation.
+- **WeChat Android JSSDK + HTML5 History API caveat**: per WeChat JSSDK docs (defensive against Android-WeChat-specific signing behavior, not anchored to a single historical version), `pushState` SPA routing can break `wx.config` signature on Android because the signed URL diverges from the runtime URL. Workaround: re-call `wx.config` after route change with a freshly-signed URL, or use hash routing (`#/path`) for WeChat-embedded SPAs.
+- **iOS swipe-back gesture**: WKWebView's interactive `allowsBackForwardNavigationGestures` (host-side flag) drives the swipe-back-to-previous-page behavior. H5 cannot block this from the page; if a flow MUST prevent unsafe back (mid-payment, mid-upload), coordinate with the host to disable the gesture for that route.
+
+## Safe Area + Viewport In WebView
+
+- **Viewport-fit cover + env(safe-area-inset-*) is mandatory for full-screen H5 on notched devices**: `<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">` is the opt-in for content extending into the safe-area region; CSS `padding-top: env(safe-area-inset-top)` / `padding-bottom: env(safe-area-inset-bottom)` etc. then keeps interactive content inside the safe region. Without `viewport-fit=cover` the page leaves system white space at notch; without `env(safe-area-inset-*)` the page hides behind the home indicator.
+- **`100vh` is unreliable in WebView**: mobile browsers compute `100vh` including/excluding URL bar inconsistently; in WebView the host chrome height shifts on scroll. Use `100dvh` (dynamic viewport units, well-supported in modern browsers) or measure `window.innerHeight` + observe `visualViewport` for keyboard-affected sizing.
+- **Keyboard handling**: iOS WebView pushes the entire viewport up when the keyboard appears (forcing layout shifts); Android WebView resizes the viewport (so `position: fixed` elements may not stay fixed). Use `visualViewport.height` + `visualViewport.offsetTop` to position keyboard-following UI, not raw `window.innerHeight` deltas.
+
+## Host Capability Surfaces
+
+- **Native capability invocation routes through host APIs, not browser APIs**. Common surfaces with their host-vs-browser distinction:
+  - **Share** — host has its own share sheet (`wx.shareToTimeline` / `wx.miniProgram.postMessage` + `onShareAppMessage`); `navigator.share` is rarely available in WebView. Always check `HostBridge.canShare()` before showing share UI.
+  - **Image / file upload** — host wraps native camera + photo library (`wx.chooseImage` + `wx.uploadImage`); `<input type="file">` may be blocked / quirky inside WebView. Use the bridge if available.
+  - **Payment** — host has native payment (`wx.requestPayment` from mini-program web-view; WeChat Pay JSAPI; Alipay tradePay). Web payment via `<form>` POST works but loses the native UX (no Touch ID / Face ID prompt, no host wallet UX).
+  - **Scan (QR / barcode)** — host has native scan (`wx.scanQRCode`); web-only via `getUserMedia` + decoder library works but requires camera permission and adds bundle weight.
+  - **Location** — host has native location with the host's permission state (`wx.getLocation`); browser `navigator.geolocation` works but prompts independently of host permission and may have lower accuracy.
+  - **Subscribe message / push** — H5 cannot subscribe to mini-program / app push directly; coordinate with host (mini-program `requestSubscribeMessage` runs on the host page, not in `web-view`).
+- **Degrade gracefully when the host capability is absent** (when running in browser): hide the action, swap to a web-native alternative, or show "Please open in <host>" call-to-action. Crashing or silently failing on missing host APIs is the recurring source of "works in WeChat, broken everywhere else" tickets.
+
+## WeChat JSSDK Specifics (Public Account / web-view)
+
+- **`wx.config` signature requires all five parameters** (`appId` + `timestamp` + `nonceStr` + `signature` + `jsApiList`) — signature is computed server-side from the current page URL excluding hash. SPA hash routing keeps the signed URL stable; SPA `pushState` routing requires re-signing on every route change. Verify in WeChat developer tools / `wx.ready` + `wx.error` callbacks.
+- **`web-view` in mini-program only exposes a subset of JSSDK** — the full JSSDK API list works in WeChat browser (公众号 H5); inside mini-program `web-view`, only `wx.miniProgram.*` bridge methods (`navigateTo`, `redirectTo`, `navigateBack`, `switchTab`, `reLaunch`, `postMessage`, `getEnv`) are reliably available. Test the actually-needed API on the actually-targeted host surface.
+- **Domain whitelist (业务域名)**: per `miniapp-product-dev/references/platform-capabilities.md` Network Domain Allowlist, every domain the H5 loads (HTML / API / asset) must be registered in the mini-program / public-account console as an authorized business domain — production calls to unregistered domains are silently blocked. Developer-tool "skip domain check" masks this; CI / pre-release smoke disables that flag.
+
+## Offline / Cache / Lifecycle
+
+- **Host may aggressively cache the entry HTML** (WeChat caches public-account HTML for performance). Cache-bust strategy: append a content-hash query parameter to the entry URL, OR use HTTP cache headers the host respects (`Cache-Control: no-cache, must-revalidate` for HTML; immutable hashed JS/CSS assets). Hash-busted JS without a fresh HTML reload = stale code shipping.
+- **Service Workers in WebView are NOT a portable guarantee** — verify per target host. Android `WebView` has an official `ServiceWorkerController` API (must be explicitly enabled and respects same-origin); WeChat WebView's full SW support is not something you should assume. Do not bet on Service Worker for critical offline behavior in WebView without per-host verification; use host-side cache (where the host owns the WebView) or accept online-only operation.
+- **Visibility / lifecycle events**: H5 inside WebView receives `pageshow` / `pagehide` / `visibilitychange` events but the timing differs from a browser tab (the host may freeze the WebView when backgrounded, terminate on memory pressure). Save in-progress state on `pagehide` / `visibilitychange`, not on `beforeunload` (often not fired in WebView).
+- **Cold-start vs warm-start**: if the host keeps the WebView alive across navigations, the H5 may re-receive a `pageshow` event with `persisted=true` (BFCache-style restoration). Initialize idempotently — code that assumes single `DOMContentLoaded` per session breaks when warm-started.
+
+## Cross-App / Cross-Page Navigation
+
+- **Open a mini-program from H5** (only in WeChat browser, NOT inside mini-program web-view): requires the page domain to be associated with the target mini-program in the WeChat console; primary API is the `wx-open-launch-weapp` web component (current public path). JSSDK `wx.invoke(...)` legacy paths may exist in some integrations but verify against current WeChat docs before adopting.
+- **Open native app from H5**: URL schemes (`myapp://...`) work when the app is installed and the host allows it; Universal Links (iOS) / App Links (Android) are more reliable but require server-side `apple-app-site-association` / `assetlinks.json` setup. Inside many in-app WebViews, URL scheme jumps are blocked — coordinate with the host.
+- **Inside mini-program `web-view`, navigation between H5 and mini-program pages** uses `wx.miniProgram.navigateTo` (to mini-program page) / `wx.miniProgram.postMessage` (sends data back to the mini-program's `web-view` `bindmessage` handler, delivered at host-defined moments — typically mini-program back navigation, component destroy, or share — NOT guaranteed immediate delivery).
+
+## Anti-Patterns — Avoid Or Require Justification
+
+- Using `window.alert` / `window.confirm` / `window.prompt` as primary user UI — WebView host may render them in confusing ways or block them entirely; use host bridge for modal UI when available, otherwise an in-page React modal. Low-risk dev-only diagnostics in `alert()` are not blanket-forbidden, but should never ship as production user flow.
+- Using `document.cookie` for **session** state — WebView cookie persistence is unreliable across cold-starts; use host token via bridge for session. First-party non-session cookies (preferences, tracking with consent) remain valid where the host respects them.
+- Relying on third-party cookies — most WebViews and modern browsers block them; use first-party storage + server-side session if cross-origin auth is needed.
+- Calling `window.open` for new windows — WebView typically does not support multi-window; route through host bridge.
+- Assuming `console.log` reaches the developer — WebView consoles are not always exposed; use a host bridge logging method or remote logging service for production diagnostics.
+- Polling `navigator.onLine` for connectivity — unreliable in WebView; use fetch-failure as the actual signal and let the host-level network indicator (mini-program / system notification) handle the user-visible offline state.
+- Adopting **PWA acceptance criteria** (manifest install prompt, Service Worker offline-first, push notifications) for the H5-in-host build — these are valid for standalone PWA but are NOT acceptance criteria inside a host WebView; the host owns app-shell / push / offline. If the same H5 also ships as standalone PWA, treat as a separate build target with its own acceptance.
+
+## Verification
+
+- **Real host device test is blocking when the change touches host-dependent behavior**: bridge invocation, auth-from-host, share / payment / scan / image-upload / location, hardware back, lifecycle (cold-start / warm-start / visibility), safe-area + viewport, keyboard handling. Browser smoke + responsive emulator is structural only for these. Per `mobile-quality-release.md` and `miniapp-product-dev/references/qa-release.md` real-host flow templates: open the H5 inside the actual host (real WeChat client, real native app build) on a real device; verify the host-specific path end-to-end. For copy-only / static-layout / pure-React-internal changes that don't cross the host boundary, browser smoke plus a single targeted host smoke is sufficient.
+- **Multi-host smoke matrix** when shipping to ≥2 hosts: WeChat browser / WeChat mini-program web-view / native iOS app WebView / native Android app WebView are four distinct environments — the same H5 may render correctly in three and break in the fourth (most commonly: Android WebView with custom UA or AppCompat WebView).
+- **In-browser fallback test**: open the H5 in a plain mobile browser (Safari iOS, Chrome Android). Confirm the in-browser degradation is sane: actions that need host APIs are disabled with explanation, no JavaScript errors in console, no host-specific assumptions break the page.

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

@@ -0,0 +1,194 @@
+# React Architecture
+
+## Component And State Boundaries
+
+- Build a component hierarchy from the UI model and data model. Components should have clear ownership of responsibility.
+- Keep state at the lowest common owner. Lift state only when another component genuinely needs to coordinate with it.
+- Distinguish server/cache state, route state, form state, transient interaction state, and derived render data.
+- Prefer controlled forms when validation, submit state, or server errors matter; keep uncontrolled inputs only when the repo pattern and UX allow it.
+- **React 19 form / async state primitives (released 2024-12-05)**: `useActionState` handles state + pending around Actions (covers common Action cases — not a universal replacement for every async pattern); `useFormStatus` lets a button / spinner read parent `<form>` pending state without prop drilling or Context; `useOptimistic` shows immediate UI feedback while the Action is in flight, reverting if the server rejects. For new React 19+ form code, prefer these over hand-rolled `useState` + `try/catch` + manual pending flag — they integrate with `<form action={...}>` and Server Functions without extra wiring.
+- **`ref` is a prop starting in React 19** for function components — drop `forwardRef` for new components (still valid for code targeting React 18 or earlier). Pass `ref` like any other prop; the type is `Ref<T>`. Existing `forwardRef` components keep working; do not refactor working code for cosmetics.
+- Use stable keys for lists. Do not use array index keys when ordering can change.
+- Preserve the design judgment layers in component boundaries. Layout components own aesthetic hierarchy and density; flow components own entry/current/next/return logic; state machines own waiting/retry/cancel/recovery behavior; copy and feedback components own user certainty, risk explanation, and perceived control.
+
+## Effects And Side Effects
+
+- Use Effects for synchronization with external systems: network subscriptions, browser APIs, timers, analytics, storage, and imperative widgets.
+- Do not use Effects to calculate derived data, mirror props into state, or handle user events that can run in event handlers.
+- Always define cleanup for subscriptions, timers, and long-running async work where cancellation matters.
+- **Memoization (`React.memo` / `useMemo` / `useCallback`) is a perf optimization, not a default.** Before reaching for it, fix the root cause: state living too high (lift down), children re-rendering because the parent passes new object/array literals every render (move literals out or memoize the parent's state), Effects writing state that triggers more renders (eliminate the Effect). Apply memoization only when a measured render cost or a referentially-stable dependency contract (effect deps, memo child, third-party hook) actually requires it. Wrapping every component in `memo` and every value in `useMemo` adds overhead and obscures the real bottleneck — see also Dan Abramov "Before You memo()" framing.
+- **React Compiler (stable as v1.0 since 2025-10) auto-memoizes components and hooks** based on static analysis — recommendation when the project is on a supported framework (Expo / Vite / Next.js shipped first-party integrations). Enable per `react.dev/learn/react-compiler` instructions; ESLint plugin `eslint-plugin-react-hooks` recommended preset ships the compiler-aware lint rules. With Compiler enabled, prefer compiler-driven memoization for new code; manual `React.memo` / `useMemo` / `useCallback` stay valid as escape hatches for precise control, existing behavior the team wants to preserve, or measured perf needs the compiler can't cover. React ships a `preserve-manual-memoization` lint mode that keeps existing manual memoization in place during adoption — use it to migrate incrementally rather than ripping out all hand-written memo at once.
+
+## Custom Hooks Discipline
+
+Custom hooks are React's primary mechanism for reusing **stateful or effectful** logic. They are not a way to organize pure functions.
+
+- **Only extract a custom hook when the logic owns state, effects, refs, context, subscriptions, or other hooks.** Pure transformations (formatting, mapping, validation) belong in plain functions — `formatCurrency(amount)`, not `useFormatCurrency(amount)`. Wrapping a pure function in `useCallback`/`useMemo` and calling it a hook adds re-render overhead with zero reuse benefit.
+- **Cleanup is part of the hook contract.** Subscriptions, timers, observers (`IntersectionObserver` / `ResizeObserver`), `addEventListener`, AbortController-backed fetches, websockets — each MUST return cleanup from its effect. A hook that creates a side effect without exposing or owning its teardown leaks across HMR, route changes, and StrictMode double-invoke.
+- **Hook output is the contract; internal state shape is private.** Return `{value, set, reset}` or `[value, setValue]`, not the raw `useState` tuple a caller might destructure. Renaming an internal state variable should never be a breaking change.
+- **Stable references where it matters.** Callbacks returned from a hook that consumers will pass to effects or memoized children must be referentially stable (wrap in `useCallback` or use a ref pattern); values that change every render do not need stabilization.
+- **One hook per concern.** `useUserProfile` that also handles toast notifications and analytics is three hooks. Compose at the call site (`useUserProfile()` + `useToastOnError()` + `useTrackView()`), not inside one mega-hook.
+- **Don't reach for a library before writing the hook.** `useToggle` / `useDebounce` / `useLocalStorage` / `useEventListener` are <20 lines each; an in-repo `hooks/` directory is usually a better dependency than ahooks / react-use for these. Reach for the library only when the surface justifies it (focus management, drag-drop, virtualization, animation timeline).
+- **Hook names declare reactivity.** A function that starts with `use` MUST follow the Rules of Hooks (called at the top level of a component or another hook, not inside conditions / loops / event handlers). If the logic does not need reactive integration, do not prefix with `use` — it misleads readers and trips lint. **Exception**: React's built-in `use(resource)` API (React 19+) is intentionally allowed inside conditions and loops, but still only inside a Component or another Hook and not inside `try`/`catch`. This exception applies ONLY to the built-in `use`; custom hooks remain bound by the standard Rules of Hooks.
+
+## TypeScript Discipline in React
+
+TS in React is a correctness tool, not decoration. The patterns below catch the bug classes that React/JS leave latent.
+
+- **`strict: true` is the floor.** `strictNullChecks` + `noImplicitAny` (both in the `strict` family) catch most of the "undefined surprise" class bugs that survive runtime tests. `noUncheckedIndexedAccess` is NOT in the `strict` family but is a strongly recommended additional flag — it makes `arr[i]` and `obj[key]` return `T | undefined`, catching a class of bugs the base `strict` does not. A repo on loose TS is not getting the value of TS.
+- **Async/UI state is a discriminated union, not a boolean soup.** `{ isLoading, isError, isSuccess, data, error }` invites impossible states (`isLoading: true` AND `isSuccess: true`); model as `type State<T> = { status: 'idle' } | { status: 'loading' } | { status: 'success'; data: T } | { status: 'error'; error: Err }`. The render path switches on `state.status` and the compiler narrows `data`/`error` accordingly. Many server-state libraries (TanStack Query, RTK Query) expose this as `status` — use it; do not flatten it back into booleans.
+- **Brand cross-boundary / security / cache identities, not every string.** Tenant id, user id, account id, report id, scope id, the routed-identity tuple keys in the heavy-dashboard cache section above — these carry permission and cache-key semantics and benefit from branding: `type TenantId = string & { __brand: 'TenantId' }`. Constructors validate at the boundary; downstream code cannot accidentally swap `userId` for `tenantId`. Catches the cache-key-collision and permission-tuple-mismatch bug class that pure-string typing cannot. Do NOT brand transient operational ids that never cross a security or cache boundary (per-request UUIDs, trace ids, ephemeral file upload keys with no authorization meaning) — the constructor / parse / mock cost outweighs the safety win.
+- **Component prop types use `never` to make impossible combinations uncallable.** A variant prop like `type ButtonProps = ({ variant: 'icon'; icon: IconName; label?: never } | { variant: 'text'; label: string; icon?: never })` makes the wrong call site a compile error instead of a runtime warning.
+- **Generic event handlers belong on the DOM, not on every wrapper.** `onClick: React.MouseEventHandler<HTMLButtonElement>` for raw DOM; a domain handler is `onConfirm: (item: ItemId) => void` — do not leak `React.SyntheticEvent` through three layers of abstraction.
+- **No `any` in shipped code; `unknown` at boundaries.** API responses parse into `unknown`, narrow via Zod / Valibot / hand-written guards before reaching components. `any` from a third-party type defines a fix-it-yourself debt; track it.
+- **`React.FC` is optional and discouraged for new code.** Prefer `function Component(props: Props) { ... }` — explicit return type, no implicit `children`, no `defaultProps` legacy. `React.FC` is not wrong, but the explicit form is easier to refactor.
+
+## Component Reuse Pattern Choice
+
+Three reuse patterns recur in React libraries; pick by what the consumer needs to control:
+
+- **Custom hook** — when reuse is logic only, no rendering shape required. Default choice for state machines, subscriptions, side-effect orchestration. See discipline above.
+- **Headless / unstyled primitives** (Radix UI, Headless UI, Ariakit, downshift, react-aria) — when reuse is a11y + behavior (focus trap, keyboard navigation, ARIA contract) but every consumer needs different visual treatment. Default for design-system primitives: the primitive owns keyboard / focus / ARIA / portal / dismiss, the consumer owns styling. **Do not invent a custom focus-trap or ARIA implementation when a maintained headless primitive exists** — the bug surface is well-known and the maintained library has fixed bugs you have not heard of yet.
+- **Compound components** (e.g., `<Select><Select.Trigger/><Select.Content/><Select.Item/></Select>`) — when consumers need to arrange children but share an implicit parent context. Cleaner than render props for this case. Default for `Tabs` / `Accordion` / `Select` / `Menu` / `Tooltip` shells.
+
+**Legacy patterns to recognize, not to reach for**:
+- **Higher-Order Components (HOCs)** — `withAuth(Component)` / `connect(mapStateToProps)(Component)`. For the same concern in NEW code, prefer a custom hook (`useAuth()` / `useSelector()`). Existing HOC APIs are acceptable when a library / framework contract requires them (React-Redux `connect` is still a valid public API) — do not refactor working HOC integrations on cosmetic grounds. Do not introduce a new HOC when a hook does the same job.
+- **Render props** — `<DataLoader>{(data) => <UI data={data}/>}</DataLoader>`. Replaced by custom hooks + Suspense. A render-prop API in 2025+ is usually a code-review finding ("why not a hook?") unless the consumer genuinely needs to control wrapping JSX (rare).
+
+When you see HOC or render props in new feature code, ask whether a hook + (optionally) a headless primitive does the same job with less indirection.
+
+## Routing And Data
+
+- Treat URLs, route params, query params, and deep links as contracts.
+- Keep auth/permission gates explicit. A hidden button is not enough if the route/API can still be reached.
+- Treat runtime initialization as part of the route contract. Tenant/account/session context, selected workspace, role vector, feature flag, and external host context must either resolve before protected UI renders or produce an explicit login/permission/retry state.
+- Permission is both navigation and action logic. Menus, routes, buttons, bulk operations, drawers, and API calls should share the same permission model instead of each inventing partial checks.
+- Use the repo's data-fetching pattern first: framework loaders/actions, React Query/SWR/Apollo, or a local API client.
+- **Router choice for non-framework SPAs**: when the project does NOT use a meta-framework (Next/Remix/Modern.js etc.), TanStack Router is the type-safe-first option — file-based routing with `.` for nested routes, end-to-end type inference for navigation / search params / loader data, built-in `loader` API + caching + automatic preloading. Pick it when type-safety on route navigation is a real concern (compile-error on broken `<Link to="/...">`) AND the team accepts the bundler-integrated route-generation step. For simpler apps or established React Router v6+ projects, the migration cost is not automatic; do not switch routers without a real type-safety pain point.
+- Model loading, empty, partial, stale, error, retry, optimistic, and permission states. Do not rely on a single generic spinner for complex flows.
+- Keep development-only diagnostics out of production. Debug consoles, mock accounts, bypass query params, and local-only bridge helpers must be gated by environment and reviewed as release risks.
+
+## UI Implementation Acceptance
+
+- Tables/lists must implement stable header, row, cell, selection, hover, bulk action, truncation, empty, loading, and error behavior instead of relying on default table rendering.
+- Modals, drawers, popovers, and detail panels must preserve parent context and return path. Closing or completing a child surface should leave filters, selection, scroll, and pending work predictable.
+- Charts and metric cards must show data freshness, missing/partial/stale states, exact-value access, and drill-down or row linkage when the chart drives a decision.
+- Progress steps and long-task UI must distinguish queued, running, partial, retryable failure, terminal failure, and success. A toast alone is not enough for work that users may wait on or retry.
+- **Routes that temporarily want different chrome (sidebar collapsed, header hidden, footer minimized, dark-mode override) MUST NOT mutate the user's durable global preference.** A heavy-content workflow route reasonably wants more viewport, but `setCollapsed(true)` on mount with cleanup that only clears timers silently overwrites the user's last sidebar choice; on every leave the user must manually re-expand. **Default pattern: route-local override consumed by the layout as `(localOverride ?? globalPreference)`.** The override is route metadata (declared on the route definition or returned by a layout-aware loader), available before first render so the shell never shows a hydration flash, automatically scoped to the matched route/layout boundary (not arbitrary child mount lifetimes, not Suspense fallbacks, not keyed-child remounts), non-persistent (it does not touch localStorage / persisted store / cross-tab sync), and cleared by route exit. The global preference is never mutated by the route. **Read-modify-restore is a discouraged fallback** for hosts that cannot offer a route-local override slot; if it must be used: (a) require an owner-lease or ref-counted override registry so concurrent route owners don't restore each other's stale snapshots, (b) define "prior value" as the durable global preference excluding this route's override — not the mount-time snapshot — so a value the user changed in another tab or via a settings panel during the route's lifetime is preserved, (c) keep the override non-persistent (don't write through Redux-persist / Zustand persist / localStorage), (d) bind the override lifetime to the route/layout boundary, not a child component's mount lifetime. The same rule applies to any global-event-bus-driven UI override.
+
+## Multi-App Portfolio Stack Choice
+
+When a portfolio has multiple React apps (desktop / mobile-H5 / PC / admin) sharing a back-end:
+
+- Pick a single meta-framework per portfolio (Umi, Next, Modern.js, Remix, etc.) and document the rationale; mixing meta-frameworks across apps in the same portfolio multiplies tooling, lint, build, and onboarding cost.
+- Pick one package manager (pnpm is the common choice) and one TypeScript base config shared via the meta-framework's generated tsconfig or an explicit `tsconfig.base.json`. Per-app `extends` only for app-specific overrides.
+- Choose component library by surface type: a desktop React component suite for PC/admin apps and a mobile-optimized component suite for H5/mobile-web. Pair the mobile suite with a utility-first CSS engine when typography/spacing density varies; pair the desktop suite with the framework's design-token entry point.
+- Allow per-app meta-framework patch versions but cap the major version skew. Frameworks evolve fast; portfolios that span more than one major version pay tax on every shared dependency.
+- A portfolio without root-level `pnpm-workspace` and shared dependency lock points is a deliberate choice (each app self-contained) or an oversight; record which one.
+
+## State And Data Fetching Library Choice
+
+- Pick one global-state library per portfolio (Redux + redux-persist, Zustand, Recoil, Jotai, or the meta-framework's built-in model store) and use it consistently. Mixing 2-3 state libraries across apps in the same portfolio is a portfolio-level finding, not an app-level decision.
+- Pick one server-state cache library (TanStack Query, SWR, Apollo, RTK Query) for any portfolio that has more than one screen reading the same endpoint. Hand-rolled `useEffect + setState + manual cache` is acceptable only for single-screen prototypes; at portfolio scale it leaks stale/dedupe/revalidate concerns into every page.
+- Pick one form library (react-hook-form + zod is the common choice; framework-native Form is acceptable when the component suite ships one) and use it consistently. Mixing react-hook-form, framework Form, and hand-rolled controlled inputs in the same portfolio is a finding.
+- Declared-but-unused dependencies (`zustand` in package.json with zero imports, `@ahooks/use-url-state` declared but referenced nowhere) are dead deps. Audit them in lint or CI.
+
+## Feature-Domain Library Exceptions
+
+The default "one library per concern per portfolio" rules above hold strictly for state-management, server-state cache, form, and routing. For library classes that govern narrower surfaces (a single visual primitive or a single non-visual capability), a narrow carve-out allows feature-local isolation when strict conditions are met. This subsection defines which classes are eligible, what evidence is required, and how containment is enforced.
+
+### Library class decision table
+
+| Library class | Default rule | Carve-out eligibility |
+|---|---|---|
+| State-management, server-state cache, form, routing | One per portfolio | **Not eligible** — strict; mixing is always a portfolio-level finding |
+| Toast / notification widget, animation library, icon set (see special case) | One per portfolio | **Visual-class eligible** — design-source evidence required (condition a visual path) |
+| Charting engine without UI, virtualization engine without UI, date/timezone correctness library without UI, drag-drop keyboard/focus engine without UI, markdown / rich-text parser-and-renderer engine without UI, sanitization library, i18n rich-text engine without UI, upload protocol/client without UI, editor-extension contract without UI | One per portfolio | **Non-visual-class eligible** — measurable budget / contract evidence required (condition a non-visual path); check shared code / policy inventory (condition c non-visual path) |
+| Chart widget, virtualized list/grid widget, date / time picker widget, drag-drop sortable / dropzone / list-reorder widget, markdown / rich-text editor or viewer widget, uploader widget, map widget, dialog / modal widget | One per portfolio | **Hybrid-class eligible** — both inventories (design-system + shared code / policy) must be silent; load `product-ui-ux-design/references/tokens-and-components.md` cross-reference for editor / rich-text classes |
+| Icon set | One UI-kit family per stack (see `product-ui-ux-design/references/multi-stack-strategy.md` and `multi-project-token-consistency.md`) | **Eligible only as feature-local glyphs**, never as a second UI-kit family — see Icon-set special case below |
+| Any class not listed above | One per portfolio | **Case-by-case escalation** — the carve-out applies only after the maintainer of the consuming skill / portfolio (typically `product-ui-ux-design` for visual classes, `app-cross-platform-dev` / `web-react-dev` for capability classes) reviews the case against the same four conditions and either extends this table or rejects. **Audit any new label against the anti-loophole meta-principle in condition (c) before adding it.** |
+
+### Four required conditions (all must hold simultaneously)
+
+(a) **Evidenced requirement beyond default library's capability**, scoped by class:
+  - For **visual-class surfaces** (toast/notification widget, animation library, icon set — the entries in the visual-class table row): the requirement is a typed enumerable in the design source — the design file ships multiple distinct sizes / containers / interaction patterns / state variants for the surface class. Subjective "the default looks ugly", "easier API", or "I prefer this library" is **not** the carve-out.
+  - For **non-visual capability classes** (the headless `without UI` entries in the decision table — charting engine, virtualization engine, date/timezone correctness library, drag-drop keyboard/focus engine, markdown/rich-text parser-and-renderer engine, sanitization library, i18n rich-text engine, upload protocol/client, editor-extension contract): the requirement is a measurable budget or external contract — a performance budget (e.g. render 10k rows under 16ms / frame), a WCAG accessibility criterion, a security/sanitization specification, a locale or timezone correctness case the default library demonstrably mishandles, or a browser/device support matrix entry. Design-source evidence is not required for these classes, but the budget / criterion / spec / case / matrix must be cited and pinned to a specific version of the default library. **Bare nouns and "helper" / "plugin" suffixes are forbidden labels here** — see anti-loophole meta-principle in condition (c); any user-facing widget routes to the hybrid path, not this list.
+  - For **hybrid classes** (the `widget / picker / sortable / uploader / map / editor or viewer / dialog` entries in the decision table): the requirement is a named external contract that the default library / no-library path does not satisfy. Per-class evidence shapes: **Chart widget** needs an interaction / a11y / drill-down / large-series-performance contract beyond what the default chart wrapper exposes. **Virtualized list/grid widget** needs a row-count / scroll-restoration / variable-height / keyboard / a11y contract. **Date picker widget** needs a locale / range / mask / a11y contract. **Drag-drop widget** needs a keyboard / screen-reader / touch / multi-list contract. **Markdown/rich-text editor or viewer widget** needs a content-schema / serialization / cross-version migration / paste-sanitization / preview contract. **Uploader widget** needs storage / API / file-policy (types, max size, virus-scan) / resume contract. **Map widget** needs provider / license / data-privacy / performance / a11y contract. **Dialog/modal widget** needs focus-trap / portal / scroll-lock / a11y / nested-stacking contract. Vague "interaction need" or "feature request" is **not** sufficient for these classes — the hybrid carve-out requires evidence rigor matching the non-visual class PLUS a security / privacy / data-contract dimension.
+
+(b) **Default library demonstrably cannot satisfy the requirement via its supported public API at the pinned version**:
+  - "Cannot satisfy" means the supported public API at the pinned version exposes no path. It does NOT mean "the default required private DOM selectors, monkey patches, forks, CSS hacks, or reimplementing the surface" — those routes are themselves anti-patterns, not evidence of an unsatisfied requirement.
+  - Documented by a docs link to the relevant default-library API surface OR a short spike commit reference showing the attempt and the result.
+
+(c) **No shared abstraction owns this surface class — checked against the right authority for the class**:
+  - For **visual classes** (toast/notification widget, animation library, icon set — the entries in the visual-class table row): authoritative source is the design-system inventory. Load `product-ui-ux-design/references/design-system-source-of-truth.md` to identify the team's design-system file(s). Count only **published, in-use components** in that file — exclude WIP / todo / explicit-deprecation-marked components; exclude third-party mirror kits unless the mirror IS the team's documented design system.
+  - For **non-visual capability / security / data classes** (the headless `without UI` entries in the table — sanitization library, markdown/rich-text parser-and-renderer engine without UI, virtualization engine without UI, charting engine without UI, date/timezone correctness library without UI, drag-drop keyboard/focus engine without UI, i18n rich-text engine without UI, upload protocol/client without UI, editor-extension contract without UI): authoritative source is the shared code / package inventory plus owning policy docs — `shared/` modules, `lib/` packages, internal `@<org>/*` package registry, plus any security / platform / privacy policy doc that the team has named as canonical for this capability class. A feature-local sanitizer when `shared/security/sanitizeHtml` already exists is a **policy violation**, not a valid carve-out, regardless of design-system silence.
+  - **Anti-loophole meta-principle for class labels (binding rule)**: any class that exists as both a headless library (no UI) AND a user-facing widget MUST be split into two labels — `X engine / protocol / parser / library / renderer without UI` stays non-visual, `X widget / picker / sortable / dropzone / uploader / editor / viewer / dialog / chart / map` is hybrid. Bare nouns (`upload`, `date picker`, `drag-drop`, `chart`, `markdown`, `editor`, `i18n rich-text`) are forbidden as class labels because they conflate the two and let a feature reclassify its widget as "engine" to skip the design-system inventory check. Same forbid applies to ambiguous suffixes `helper` / `plugin` / `lib` — they are NOT valid labels in any bucket; disambiguate to either `... engine / contract / library / renderer / parser without UI` (non-visual) or to a concrete widget noun (hybrid). **When adding or editing a class entry anywhere in this subsection (decision table, condition (a), condition (c)), audit the label against this rule first; the rule applies recursively to every list and every row, not only to new additions.** A change that introduces or leaves a bare noun, `helper`, `plugin`, or `lib` suffix is itself a regression of this rule.
+  - For **hybrid classes** (the `widget / picker / uploader / editor or viewer / map / dialog` entries — concrete widget nouns; never bare nouns or `plugin` / `helper` / `lib` suffixes): check both inventories — design-system for the visual / interaction shell, shared code / policy for the data / security / contract layer. A hybrid carve-out passes only when both inventories are silent.
+  - If the authoritative inventory has the abstraction, the right fix is to use it (not to fork). If silent, the carve-out is one acceptable path; **promoting the feature's local choice into a shared abstraction is the better long-term fix** when other features will likely want the same capability — a feature that adopts the carve-out should also raise the promotion request to the owning skill (`product-ui-ux-design` for visual, security / platform skill for capability / data).
+
+(d) **Isolation is structurally contained — all runtime / build / style references, not just component imports**:
+  - Every reference path to the alternate library — component imports, hook imports, service / API-client imports, route loader / action imports, worker / job-runner imports, style imports, generated wrapper imports, type imports, config / token reads — must originate inside `features/<X>/` (or the equivalent feature-path). A library imported by a feature's hook in `lib/` or by an API client in `services/` is **leaked**, even if no component outside the feature directory touches it.
+  - The package MUST NOT be loaded as: an app-root provider, a global stylesheet (`<link>` / `<style>` injection at app entry), a theme-mutation effect, a shared package export from a `shared/` / `common/` / `lib/` module, a shared route or layout dependency, a bundler alias / resolution rule, a CSS-in-JS theme augmentation, a generated client / typings ambient declaration, a peer dependency that other features inherit by virtue of being in the same workspace, or a worker / service-worker entrypoint.
+  - The feature's README names the alternate library as an intentional choice with citations satisfying (a), (b), and (c).
+  - A lint rule or module-boundary configuration enforces the containment — a check that runs in CI, not just a verbal convention. The lint rule MUST cover all reference paths above (not only component imports), or the containment is unenforceable.
+
+When all four hold, the isolation is **not a portfolio-level finding** — it is a documented exception. When any one fails, fall back to the default rule: one library per concern per portfolio, mixing is a finding.
+
+### Icon-set special case
+
+A second icon set is more often a second visual-system vocabulary than a narrow feature-local library. Even under the carve-out, icon-set isolation MUST be **feature-local glyphs only** (the feature's domain-specific glyphs that the design system does not provide), NOT the feature's primary icon vocabulary; MUST be **tokenized to brand colors** via the design-system's color tokens (not the third-party icon library's defaults); and MUST be confirmed not to function as a second UI-kit family. Before any icon-set package is added across more than one feature, escalate to `product-ui-ux-design/references/multi-stack-strategy.md` and `multi-project-token-consistency.md` review — multi-feature icon usage is typically a design-system update, not a feature carve-out.
+
+## Cross-Cutting Concerns Discipline
+
+Several concerns recur in every front-end portfolio and benefit from portfolio-level rules rather than per-app reinvention:
+
+- **i18n**: pick one library (react-intl, i18next, lingui) and one translation-file convention before the first user-facing string. Hard-coded strings across apps in a portfolio that ships in one language today become migration debt the day a second language is added.
+- **a11y**: ARIA attributes, focus management, keyboard navigation, and contrast budgets are tooling choices (eslint-plugin-jsx-a11y baseline + a per-component checklist), not per-app investment.
+- **Theme switching and design tokens**: design tokens (brand colors, spacing scale, typography units, radii, shadows) are owned by the design source of truth — typically the Figma file curated by `product-ui-ux-design`. **`web-react-dev` does not redefine tokens** and does not author them in front-end code; it consumes the synced output. For the canonical token set, sync mechanism, and per-platform desktop/mobile mapping, read `product-ui-ux-design/references/tokens-and-components.md` and the platform-specific pattern references. Hard-coded color literals in component code are a sync-pipeline finding (sync missing, or synced token not being referenced), not a place to invent a parallel front-end token file. Multi-theme support arrives by switching the token set in the design source and re-running the sync, not by rewriting components.
+- **Theme injection completeness**: every app in the portfolio that depends on the brand theme must inject it at the framework or root level — examples vary by meta-framework (`antd: { theme: brandTheme }` in UmiJS / Next + antd, `<ConfigProvider theme={brandTheme}>` wrapping the app root in raw React + antd, `ThemeProvider theme={brandTheme}` in styled-components / MUI, etc.). Beware three failure modes that all read as "themed" to a naive grep: (1) **slot exists but is empty** — `antd: {}` or `ConfigProvider` with no `theme` prop — renders the UI-kit default; (2) **dark-mode library mistaken for brand theme** — a `ThemeProvider` from `next-themes`, `tailwindcss/dark`, or similar only handles light/dark, not brand color, so an app whose only theme provider is dark-mode-only is silently off-brand; (3) **theme module exists but is never imported** — the brand `themeConfig` is written but no entry imports it. Static check: grep for the framework-specific theme slot, confirm the slot references a non-empty brand theme object, AND confirm that object is reachable from the app entry. See `product-ui-ux-design/references/multi-project-token-consistency.md` "Empty framework-wrapper theme config" for the cross-stack rule and downstream verdict.
+- **ErrorBoundary and global error UI**: define one error-boundary fallback component + one empty-state component + one loading skeleton at the portfolio level. Per-app re-rolls drift visually and behaviorally.
+- **Responsive breakpoints**: pick one breakpoint scale (the CSS engine's, the component suite's, or a shared `breakpoints.ts`) and use it across desktop and mobile-web apps. Mobile-first utility-CSS on H5 + desktop-first grid on PC is acceptable; the breakpoint values must still come from one place.
+
+## Multi-Level Business Module Shell
+
+Use this pattern when one product surface ships several hierarchy levels (per-row, per-group, per-tenant, per-org, per-federation) of the same business module, each with shared chrome and per-level differences.
+
+- **One polymorphic shell, not N parallel implementations**. The shell owns header, filter bar, scope persistence, status polling, refresh, and export. Per-level differences (menu shape, available metric set, available export dimensions, navigation paradigm) inject via parameters — for example `<app-type>`, `<level>`, `getMenuItems`, `getExportDimensions` — rather than forking the shell into `<L1>Shell / <L2>Shell / <L3>Shell / <L4>Shell` files. Forks duplicate the shell drift surface and grow O(level × bugfix) maintenance cost.
+- **Per-level menu/handler factory**: each level's `menu.tsx` exposes one or two factory functions (e.g. one set of menu items for the broad/aggregate `<mode-A>` view and another for the focused/single-entity `<mode-B>` view) plus one menu-items generator that filters items by mode/permission. Two factories per level, not one big switch on level inside one giant file.
+- **Menu keys must be stable across levels; labels may vary — and "menu key" is NOT a routed/cache/persistence key**. Re-use the same menu identifier (`metricId` / `menuMetricId`) when the underlying metric/chart/calculation is the same, even when the user-facing label is different on different levels (one level says "row-level comparison", another says "group-level comparison"). Forking that shared identifier breaks the formula/calculation layer — it forces label-only design changes into code redeploys, and it splits analytics taxonomy at the metric level. The shared identifier drives: per-level label maps, formula references, analytics taxonomy entries. The shared identifier does NOT directly drive route / cache / persistence / export-job keys. Each of those is a separate key class with its own required shape (see `product-ui-ux-design/references/analytics-visualization-interactions.md` "Multi-Level Hierarchy Navigation" key-class section for the full matrix). Implementation summary: route / deep-link / export filename use routed identity `(moduleInstanceId | metricId, level, scope, report, tenant, schema-version)`; export job payload / server-side data request add `filter-set` + `config-version` + sheet selection + snapshot token; data cache adds `sheetType` + `filter-set` + `config-version` to the routed identity; local persistence uses `(userId, tenant, report, level, scope/resource, schema-version, surface-version)` plus module identity. Keep `metricId` and `moduleInstanceId` as separate types so the type system catches misuse.
+- **Single permission gate per shared action — but the gate is `(action, level, scope, resource)`, not `(action)` alone**. The shell is one place where the check lives, but the check itself must evaluate the full tuple. A user who has `export` at the parent level often does not have `export` at the leaf level, or vice versa; collapsing the check to "can the user export at all" silently widens the surface. Server-side export job APIs must re-evaluate the same tuple — client gating is for UX, not for security. Submenu modules may rely on the shell gate for affordance visibility, but mutations (export, edit-rules, publish) must re-assert authority against the API on submit.
+- **Two navigation paradigms in the same product are acceptable when the user role differs**: a per-row leaf level (frequent visit, browse top-to-bottom) reasonably uses an in-page anchor-scroll group (one viewport, all modules stacked, scroll-spy + URL menu key); a per-group leaf level (lower frequency, deeper inspection) reasonably uses leaf menu items that route to module-only views. Pick the navigation paradigm per role, not per developer preference. Mixing both inside one level confuses users.
+
+## Heavy Dashboard Cache And Invalidation
+
+Use this pattern when one page composes many chart/table modules sharing the same scope (report id, time range, scope filter) but differing in axis (per-row, per-group, all).
+
+- **Split sheet types by per-call cost, not by module count — and tag every in-flight request with a generation token**. Cache the all-scope sheet types (e.g. all-row comparison data) in one batch fetch; cache the single-scope sheet types (e.g. focused current-row drill data) per current scope; everything else stays on-demand. A monolithic "fetch everything per scope change" pattern bloats both wall time and bandwidth. The race-safety requirement is non-negotiable: every cache-key must encode the full `(sheetType | moduleInstanceId | metricId, report, level, scope, filter-set, tenant, schema-version, config-version)` tuple — omitting the data identity (sheetType / moduleInstanceId / metricId) collides every module within the same report/scope/filter and exports build from mixed snapshots. Every in-flight request must carry a request-generation token. When scope changes, abort or ignore responses for older generations — otherwise a slow all-scope response and a fast single-scope response can land out of order and the rendered page combines stale aggregates with fresh drill-downs. **Export must come from a consistent snapshot, not from "wait for nothing-in-flight"**: a naive "block export while any dependent query is in-flight or known-stale" rule deadlocks against long-running polls or slow background refreshes. The correct rule is: export builds from the last consistent snapshot of the cache (all keys in the snapshot share the same generation token); if no consistent snapshot exists yet, the export queues a refresh and waits on its completion (showing the user a "preparing export" state); the exported artifact carries timestamp and staleness disclosure so the recipient knows when the snapshot was taken.
+- **Map config-key → affected sheet types and invalidate the minimum set, with a conservative default for unknown keys**. When the user changes a per-module setting (a threshold band, a segment interval, a hierarchy band), only refetch the sheet types that depend on it. A simple `Record<ConfigKey, SheetType[]>` map declared next to the cache makes the dependency explicit; "always refetch on any config change" is the lazy default that lights up the network tab on every interaction. **But hand-maintained maps go stale fast**: when a new config key ships and the engineer forgets to add it, the UI silently uses the old rule and exports based on the old config. Mitigate by (a) deriving the map from typed backend metadata where possible, (b) defaulting unknown config keys to "invalidate everything" rather than "invalidate nothing", (c) including a `config-version` epoch in every cache key so a config schema change forces a full refresh, and (d) writing a test per config key that asserts the affected sheet types refetch.
+- **Polling cost compounds with concurrent reports**. If a status-polling pattern runs every N seconds per open report and users routinely open many reports in tabs, the absolute request rate becomes a server concern even when each request is cheap. Either move to push (WebSocket / SSE), centralize polling at the workspace level, or back off with exponential intervals after the first few cycles.
+- **Local persistence keys need the full routed-identity tuple, not just `(userId, level)`**: filter state, comparison target, selected menu key persisted to local storage should compose at least `(userId, tenant, report, level, scope/resource, schema-version, surface-version)`, plus `metricId | moduleInstanceId` where the persisted value is module-specific. A persistence key of only `(userId, level)` corrupts on tenant switch, on report switch within the same level, or on schema/surface upgrade — the user opens a new report and sees a stale selected module / comparison target from a different report. Sharing the persistence cache across any of these dimensions accidentally is one of the easier ways to ship a state-leak bug.
+- **Differentiate "compare with cache" vs "compare with target"**: a chart that color-codes cells by threshold band is one rendering rule; a chart that color-codes cells by comparison to a target row is a different rendering rule. Mixing them in one component (a single `cellRender` that branches on `mode==='threshold' | 'compare'`) is acceptable; mixing them in one rendered chart without an explicit mode switch / legend / copy is not. The user must know which rule colored their cell.
+
+## Rich Text Editor: Domain Extension
+
+When a product ships an editor for domain-specific content (structured documents with fill-in-the-blank fields and inline math, content cards with frame/border decorations, documents with citations or annotations) rather than freeform prose, the editor framework is extended with domain primitives rather than rebuilt:
+
+- **Pick an editor framework with an explicit extension model**: Quill (Parchment blots), TipTap (ProseMirror nodes/marks), Slate (custom element types), Lexical (custom nodes), ProseMirror direct. The extension model is what makes domain primitives first-class — schema-aware copy/paste, selection, undo/redo, serialization. Frameworks without an explicit extension model (`contenteditable` + hand-rolled mutation observer) collapse under second-order requirements (paste sanitization, collaborative editing, undo grouping).
+- **Domain primitives are custom blot / node types, not nested DOM hacks**: a fill-in-the-blank field, a formula, a frame decoration, a citation marker are first-class Blot / Node subclasses with `blotName`, `tagName`, `className`, a typed `create(data)` constructor, and a typed `value(domNode)` deserializer. Treating them as styled spans with class hooks (`<span class="my-primitive">`) loses the editor's structural awareness: paste produces orphan spans, undo collapses them, and serialization round-trips drop the data.
+- **Stable cross-edit identity uses a typed UUID prefix**: each blot instance carries an id like `<primitive-type>-<uuid>`; on subsequent renders the constructor accepts the existing id if it matches the prefix or generates a new one. Without stable identity, every keystroke regenerates the blot, breaks editing focus, and confuses collaborative-edit ID tracking.
+- **External-rendering integration uses a reuse-vs-regenerate ladder, with a trust boundary**: when a blot wraps an external-rendered artifact (TeX → SVG via MathJax, code → highlighted HTML via Shiki, diagram → SVG via Mermaid), the create path is (1) reuse a pre-rendered element ONLY when it is trusted same-renderer output produced earlier in the same authenticated session (the editor itself just generated it); (2) for any caller-provided / paste / import / collaboration / API-originated / storage-roundtrip pre-rendered HTML/SVG, regenerate from the canonical source string (the TeX, the code, the diagram DSL) — inline SVG can carry script-adjacent payloads, inline event handlers, `foreignObject`, external references, and CSS abuse that the canonical-source path does not; (3) else if the rendering engine is loaded, call it synchronously on the canonical source; (4) else fall back to raw textual content. If the canonical source is unavailable and the pre-rendered element MUST be reused, sanitize under a strict same-renderer allowlist (tag set, attribute set, no event handlers, no script, no external references) — sanitization is fallback, not default.
+- **Storage contract keeps canonical source, not just rendered output**: persisted content stores the source string (TeX, code, diagram DSL) AND the `renderer_version` used at last render, NOT just the rendered SVG/HTML. Without the canonical source, the multi-version migration below has nothing to re-render from and is stuck reusing untrusted historical output. The rendered output may be cached alongside as a performance optimization, but the source is the authoritative field.
+- **Multi-version engine coexistence during upgrade**: when the math/render/highlight engine is upgraded (e.g. MathJax v2 → v3, formula engine v2 → v3), persisted content was authored against the old engine. The editor ships both engines during the rolling cutover; content's `renderer_version` field picks the matching engine to re-render from the canonical source. Migration is incremental: re-author touches migrate; un-touched content stays on the old engine until a deliberate batch migration runs over the canonical source. Old engines remain shipped until migration coverage is proven (a fraction-migrated metric reaches the policy threshold); a flag-flip cutover before then invalidates every historical document.
+- **Renderer-engine asset loading is self-hosted and integrity-checked by default**: a product-critical editor engine (MathJax, Mermaid, Shiki grammar bundles) loads from self-hosted assets pinned to a specific version with Subresource Integrity (SRI) hash AND a strict Content Security Policy entry. Public-CDN sourcing introduces supply-chain risk, CSP fragmentation, version-skew across regions, and race conditions if the CDN is mutated. CDN sourcing is an availability fallback (when the self-hosted asset is unreachable), not the primary architecture; if used, every source in the fallback list carries the same SRI hash (not a different one per source) and a single-flight loader prevents two parallel scripts racing on `window.MathJax = ...`. Emit a metric on each fallback so source incidents are visible.
+- **Asset URLs are config inputs, never literals**: the asset list, font URLs, and bucket addresses live in build/runtime config — never in editor library source. Hardcoded project/vendor asset URLs in shared editor library code bake project identity into the bundle, leak bucket addresses to anyone who reads the source, and break the library when used in another deployment.
+- **Domain primitives have a serialization contract that survives copy/paste and storage**: each blot's `value()` exposes only the fields the contract guarantees; transient fields (computed dimensions, render cache, DOM-only flags) are not serialized. Round-trip discipline: serialize → deserialize → serialize MUST equal the original serialization. Test this per blot.
+- **Editor framework choice is portfolio-wide, not per-app**: when multiple apps in a portfolio embed a rich editor (an authoring surface, a review surface, a mobile preview surface), pick one editor framework and one domain-primitive package; pair the per-platform variant via configuration rather than parallel framework-specific blot ports. Two editor frameworks in one portfolio doubles the maintenance and the bug surface.
+
+## Operations Console Surfaces
+
+- For admin or operations consoles, treat list, detail, and edit drawer flows as one route contract: list filters and pagination, detail URL params, reload after mutation, and parent context must stay predictable.
+- Tables that inspect runtime resources need explicit columns for identity, runtime/config, health/status, age, ownership, and actions; long identifiers and images need copy affordances plus measured truncation or tooltips.
+- Runtime status tags should encode severity consistently and expose the underlying reason or message for non-healthy states.
+- Form drawers that mutate deploy/runtime config need required-field validation, disabled immutable fields during edit, pending submit state, success-triggered authoritative refresh, and visible failure mapping.
+- Link navigation should use route helpers or base-path ownership rather than hard-coded relative strings when the app can be hosted under a prefix.
+- Generated API clients and generated typings are implementation surfaces: keep them reproducible, but wrap or normalize response envelopes at page boundaries so pages do not scatter `code <= 299` checks.