@imfusion/web-ui 0.10.1-dev.6.gf715361a → 0.10.1-dev.61.g9d1000b8

package/src/llms/install-templates/hooks/session-start.sh

@@ -2,4 +2,18 @@
 # SessionStart: inject the web-ui router pointer once per session. Fixed string — the
 # hook-injection eval asserts on it verbatim.
 echo "This project depends on @imfusion/web-ui. Start at the imf-web-ui skill: it decides whether guidance is needed and routes to the right companion. Repo docs carry only what is unique to this repo."
+
+# Installed skills that differ from the package's copy are stale. A symlinked checkout
+# carries work-in-progress skills, so it never counts.
+ROOT=$(cd "$(dirname "$0")/../../.." && pwd) || exit 0
+PACKAGE="$ROOT/node_modules/@imfusion/web-ui"
+[ -d "$PACKAGE/src/llms/skills" ] && [ ! -L "$PACKAGE" ] || exit 0
+for dir in "$PACKAGE"/src/llms/skills/imf-web-ui* "$ROOT"/.agents/skills/imf-web-ui*; do
+  [ -d "$dir" ] || continue
+  name=$(basename "$dir")
+  if ! diff -rq "$PACKAGE/src/llms/skills/$name" "$ROOT/.agents/skills/$name" >/dev/null 2>&1; then
+    echo "The installed imf-web-ui skills differ from the @imfusion/web-ui package in node_modules. Tell the user and offer the imf-web-ui-update skill, or \`npx web-ui install skills\`."
+    break
+  fi
+done
 exit 0

package/src/llms/install-templates/hooks/stop.sh

@@ -10,9 +10,14 @@ git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
 [ -n "$(git status --porcelain -- '*.ts' '*.tsx' '*.js' '*.jsx' '*.css' 2>/dev/null)" ] || exit 0
 # Gate only turns that actually edited files — a tree left dirty by an earlier
 # session must not block a question-answering turn. Edit evidence: Write/Edit
-# tool calls (Claude transcript) or apply_patch calls (Codex rollout).
+# tool calls (Claude transcript) or apply_patch calls (Codex rollout), searched
+# only after the turn's opening entry: the last real user prompt (not a tool
+# result or injected meta message) or the last Codex task_started event. Claude
+# matches only tool_use calls: its transcript also stores the tool definitions,
+# whose "name":"Edit" entries are not edits.
 TRANSCRIPT=$(printf '%s' "$PAYLOAD" | sed -n 's/.*"transcript_path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n 1)
 [ -f "$TRANSCRIPT" ] || exit 0
-grep -q '"name":"Write"\|"name":"Edit"\|"name":"MultiEdit"\|"name":"NotebookEdit"\|apply_patch' "$TRANSCRIPT" || exit 0
+TURN_START=$(grep -En '"type":"user"|"type":"task_started"' "$TRANSCRIPT" | grep -Ev '"type":"tool_result"|"isMeta":true' | tail -n 1 | cut -d: -f1)
+tail -n +$(( ${TURN_START:-0} + 1 )) "$TRANSCRIPT" | grep -Eq '"type":"tool_use","id":"[^"]*","name":"(Write|Edit|MultiEdit|NotebookEdit)"|"name":"apply_patch"' || exit 0
 printf '{"decision":"block","reason":"web-ui stop gate: this turn changed source files. Run the project verification (verify:typecheck, verify:lint, and verify:format at minimum), fix what it reports, then finish. If it already ran after the last change, say so and finish."}\n'
 exit 0

package/src/llms/llms.gen.txt

@@ -11,7 +11,7 @@ props, which always live in the docgen file above.
 
 ## AccountCard
 - category: Display, status: experimental
-Card linking to the signed-in person's account: avatar, a large name or email, a quiet line under it, and organization and role at its foot, with a trailing action such as Log out. Also called an ID card or user row; for a bare person badge, use Avatar.
+The signed-in person's account row: the avatar in a lead column, the name or email, a quiet line under it, and organization and role below, with a trailing action such as Log out. Also called an ID card or user row; for a bare person badge, use Avatar.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .account-card (jq: jq '.account-card' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 
 ## AppShell
@@ -73,11 +73,22 @@ Show-and-hide region for secondary content such as FAQs, settings, or details. A
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .collapsible (jq: jq '.collapsible' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 - further reading (usage/anatomy, not props): https://base-ui.com/react/components/collapsible.md
 
+## ColorSchemeToggle
+- category: Inputs, status: experimental
+Light, System, and Dark segments that set and remember the page's color scheme. Also called an appearance or theme switch; built on ToggleGroup, which is the choice for any other segmented selection.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .color-scheme-toggle (jq: jq '.color-scheme-toggle' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+
 ## CopyButton
 - category: Buttons, status: stable
 Copies a value to the clipboard and briefly shows confirmation. Also called a copy-to-clipboard button; commonly used with Code.Block.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .copy-button (jq: jq '.copy-button' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 
+## Dialog
+- category: Layout, status: experimental
+Modal window over a dimmed page for focused tasks, forms, confirmations, or viewers. Also called a modal; use Drawer for a panel from the screen edge and Popover for content anchored to a trigger.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .dialog (jq: jq '.dialog' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/dialog.md
+
 ## Drawer
 - category: Layout, status: stable
 Off-canvas panel that slides in from a screen edge for navigation, settings, filters, or focused tasks. Also called a sidebar, side panel, or sheet.
@@ -173,6 +184,12 @@ Link as a whole row: optional leading icon, label, optional description line, an
 Horizontal layout primitive for spacing, aligning, and wrapping children. Also called a horizontal stack or flex row.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .row (jq: jq '.row' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 
+## ScrollArea
+- category: Layout, status: experimental
+Scrollable region with the library's overlay scrollbar and edge fades, for lists, panels, and dialog bodies. Also called a scroll container; use it instead of a bare overflow: auto.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .scroll-area (jq: jq '.scroll-area' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/scroll-area.md
+
 ## Select
 - category: Inputs, status: stable
 Dropdown for choosing a value from a known list. Also called a picker; use it for a labeled, keyboard-accessible option list.

package/src/llms/skills/imf-web-ui-audit/SKILL.md

@@ -23,15 +23,20 @@ it low, and do not let it crowd the sections a consumer has to act on.
 
 Invoke `imf-web-ui-user-profile` first and explain at its levels throughout.
 
-1. Resolve the argument. Bare means `full`; an unknown topic is an error, not a reason to widen the scope.
+1. Resolve the argument. Bare means `full`; an unknown topic is an error, not a reason to widen the scope. Then check that
+   `node_modules/@imfusion/web-ui/package.json` exists. Without it, token, installed-version, and installed-type checks can
+   only come back Unverified, so tell the human before dispatch and ask whether to install dependencies first or continue
+   with those checks unverified.
 2. Enter plan mode unless this audit is being called as verification by another skill or the host has no plan mode.
 3. Read the report template and existing reviewer notes, then dispatch one investigator per in-scope topic. Tell each
-   investigator to use only `Read`, `Glob`, and `Grep`, with no shell commands or writes. An investigator checks every
-   section in that topic and writes nothing. Once dispatch starts, the host performs no repository inspection: the returned
-   reports are the evidence, and the host merges them without reading or searching the files again. Gathering the evidence
-   twice spends context on the second pass and reports what the host still remembers. Inspect a topic inline only after its
-   dispatch has been tried and refused, and say which attempt failed. A `full` audit also dispatches one marker investigator;
-   a named-topic audit gives that search to the topic's investigator. See [Deferred-work markers](#deferred-work-markers).
+   investigator to inspect statically: `Read` plus the host's file search (`Glob` and `Grep`, or a read-only search tool when
+   the host has no `Glob` or `Grep`), with no shell commands or writes. An investigator checks every section in that topic
+   across the whole frontend tree and writes nothing; one without any search tool says so and stops instead of auditing only
+   the paths it already knows. Once dispatch starts, the host performs no repository inspection: the returned reports are the
+   evidence, and the host merges them without reading or searching the files again. Gathering the evidence twice spends
+   context on the second pass and reports what the host still remembers. Inspect a topic inline only after its dispatch has
+   been tried and refused, and say which attempt failed. A `full` audit also dispatches one marker investigator; a
+   named-topic audit gives that search to the topic's investigator. See [Deferred-work markers](#deferred-work-markers).
 4. Merge the evidence into the shared report format in
    [`templates/REPORT.md`](../imf-web-ui-conventions/templates/REPORT.md). Before presenting or writing it, check that every
    Broken, Missing, Deviation, and Unverified entry has a severity, evidence, impact, and next action; do not compact
@@ -55,7 +60,15 @@ Classify every result as one of these:
 
 Use the report contract's severity, `path:line` evidence, concrete impact, and smallest next action. Unverified entries use
 that same structure: unavailable runtime evidence, the impact of the unknown, and the check that resolves it. Do not promote
-an optional tool or a working alternative to a missing finding.
+an optional tool or a working alternative to a missing finding. A `vite.config.ts` without `localWebUILink()` registered from
+`@imfusion/web-ui/vite` is Missing. A `tsconfig.json` without the `paths` block from the `tooling` topic is Missing too. Each
+next action is the add from that topic. A Vite config that reads tsconfig `paths` (`resolve.tsconfigPaths` or
+`vite-tsconfig-paths`) is Broken: it loads the React types package as React once Web UI comes from the registry. The fix is
+to drop it and give the `#/` alias through `imports` in `package.json`. A major or minor mismatch between the project and Web
+UI on a package listed under Aligned runtime packages in the `tooling` topic is a Deviation. Report both versions, with
+`npm install <package>@<Web UI's version>` as the fix. A route-local file that the inline rule in the `project-structure`
+topic says belongs in its route file is a Deviation, and so is a route file over 250 lines that inlines parts the rule would
+keep in its `-` folder. Report the line counts, with the move as the fix.
 
 ## Topics
 
@@ -83,13 +96,13 @@ UI component or a hard-coded color waiting for a token, is evidence for that top
 ## Agent tooling checks
 
 For `agent-tooling`, compare the declared version in `package.json`, the installed
-`node_modules/@imfusion/web-ui/package.json`, every `.imf-web-ui-skill-version.json` marker, the `AGENTS.md` fence, hook
-scripts, and both host registrations with the shipped topic. Version drift, extra hooks, stale markers, and missing
-registrations are findings; point version drift to `imf-web-ui-update`. Registry availability is unverified. Read files as
-text; do not run installers or hooks.
+`node_modules/@imfusion/web-ui/package.json`, the installed skills against `node_modules/@imfusion/web-ui/src/llms/skills`,
+the `AGENTS.md` fence, hook scripts, and both host registrations with the shipped topic. Version drift, extra hooks, skills
+that differ from the package copy, and missing registrations are findings; point version drift to `imf-web-ui-update`.
+Registry availability is unverified. Read files as text; do not run installers or hooks.
 
 ## Safety
 
-Use only `Read`, `Glob`, `Grep`, and equivalent static inspection. Do not run Git, shells, Node, npm, npx, package scripts,
-linters, tests, builds, hooks, or imported config. Report runtime state as unverified. Investigators inherit this
-restriction.
+Use only `Read`, the host's read-only file search, and equivalent static inspection. Do not run Git, shells, Node, npm, npx,
+package scripts, linters, tests, builds, hooks, or imported config. Report runtime state as unverified. Investigators inherit
+this restriction.

package/src/llms/skills/imf-web-ui-conventions/templates/AUDIT_CHECKLIST.md

@@ -14,7 +14,7 @@ sections one to one — change a topic's sections and this file follows in the s
 - [ ] Stay behind the library
 - [ ] Wrap primitives when the app has a reason to
 - [ ] Lock a field: read-only or disabled
-- [ ] Derive types, don't import them
+- [ ] Derive types, don't copy them
 - [ ] Integrations own their peers
 - [ ] Styling crosses the boundary through seams
 
@@ -89,6 +89,7 @@ sections one to one — change a topic's sections and this file follows in the s
 - [ ] Topic registry and key factory
 - [ ] Options factories and naming
 - [ ] Router context access
+- [ ] Loading states
 - [ ] Automatic invalidation
 - [ ] Testing the data layer
 
@@ -108,7 +109,8 @@ sections one to one — change a topic's sections and this file follows in the s
 - [ ] Oxfmt
 - [ ] Oxlint and TypeScript
 - [ ] Pre-commit checks
-- [ ] Vite plugins
+- [ ] Vite plugins, including `localWebUILink()`
+- [ ] Aligned runtime packages
 
 ## npm project — `npm-project`
 

package/src/llms/skills/imf-web-ui-conventions/topics/agent-tooling.md

@@ -12,12 +12,13 @@ npx web-ui install skills --harness=claude
 
 It installs or refreshes the `imf-web-ui-*` skills, updates the managed `AGENTS.md` fence, and removes skills that the
 package no longer ships. The skills always live in `.agents/skills/`. `--harness` selects `claude`, which also links each
-skill into `.claude/skills/`, `codex`, or `all`; without it, the command prompts and remembers the choice. Pass
-`--reconfigure` to choose again. On a project that already has an install, re-running `install skills` without `--harness`
-reuses the remembered harness instead of narrowing it.
+skill into `.claude/skills/`, `codex`, or `all`; without it, the command prompts on a first install. Pass `--reconfigure` to
+choose again. On a project that already has an install, re-running `install skills` or `install hooks` without `--harness`
+reads the harness back from the installed files: Claude skill links and installer-owned hook registrations, with Codex
+assumed when skills leave no trace.
 
-Skill version markers (`.imf-web-ui-skill-version.json`) show which package version installed each skill. Refresh them with
-the installer; do not hand-edit the vendored files.
+Refresh the skills with the installer; do not hand-edit them. Keep `.agents/skills/imf-web-ui*` out of the project's
+formatter: a reformatted skill no longer matches the package copy, and the session-start check reports it as stale.
 
 ## The hooks
 
@@ -36,7 +37,8 @@ harness that is not selected.
 
 The shipped events are:
 
-- `SessionStart`: point the agent at the Web UI router once per session.
+- `SessionStart`: point the agent at the Web UI router once per session, and tell it when the installed skills differ from
+  the copy in `node_modules/@imfusion/web-ui`.
 - `SubagentStart`: provide the same pointer to spawned agents.
 - `UserPromptSubmit`: name the companion skills relevant to the prompt.
 - `Stop`: ask for project verification after a turn edits source files.
@@ -44,9 +46,6 @@ The shipped events are:
 Read existing registrations first. If the project already covers an event, do not stack a second hook; adapt the existing
 registration and keep the missing behavior.
 
-`baseline-staleness.sh` is a pre-commit check, not an agent hook. It compares installed skill markers with the installed
-package version.
-
 ## Codex trust
 
 Codex runs project hooks only after the project is trusted and each script is approved through `/hooks`. Revisit that review

package/src/llms/skills/imf-web-ui-conventions/topics/data.md

@@ -70,8 +70,10 @@ Cross-topic invalidation can then use `keys.topic` instead of rebuilding a prefi
 
 ## Options factories and naming
 
-Queries use `get*` names such as `getAll`, `getById`, and `getDetails`. Mutations use bare verbs such as `update` or
-`delete`. Do not add a topic prefix or `Options` suffix; `context.api.user.getDetails()` already supplies the context.
+Queries use `get*` names such as `getAll`, `getById`, and `getDetails`. Mutations use verbs such as `update` or `delete`. A
+name never repeats its topic or adds an `Options` suffix; `context.api.user.getDetails()` already supplies the context. When
+a topic has more than one mutation target, add the sub-resource to the verb: `api.projects.removeMember(projectId)` and
+`api.projects.setMemberPermissions(projectId)`, where a bare `remove` would read as deleting the project.
 
 A query factory owns its key and parsing:
 
@@ -102,6 +104,19 @@ not inline those options at the call site.
 Put the API object and `QueryClient` in router context. Loaders use `context.api.<topic>.<fn>()`; route components read the
 same context with `Route.useRouteContext()`. Direct imports are for plain utilities and tests outside the route tree.
 
+## Loading states
+
+Pick the Skeleton part by how the data loads:
+
+- Data read with `useSuspenseQuery` inside a Suspense boundary uses `Skeleton.Suspense`, with the bones as its `fallback`.
+  Content fades in when the fallback showed; cached data mounts without a fade.
+- Secondary data read with `useQuery` that may arrive later uses `Skeleton.Root` with `loading={isPending}` around the real
+  content, which cross-fades when the data lands.
+- A route whose loader blocks navigation until the data is cached shows its `pendingComponent`. The router unmounts it, so
+  nothing reveals.
+
+A layout that reads suspending data needs its own boundary. Otherwise a suspension blanks the whole layout.
+
 ## Automatic invalidation
 
 Mutation keys start with the topic they change. The shared `MutationCache` invalidates that topic after success by default.

package/src/llms/skills/imf-web-ui-conventions/topics/git.md

@@ -7,12 +7,15 @@ Use the repository's tracked configuration and keep verification scopes clear.
 Run once in a clone:
 
 ```sh
-git config core.hooksPath .githooks
+git config core.hooksPath .vite-hooks/_
+vp config --no-agent
 git config pull.rebase true
 git config merge.ff only
 ```
 
-The hooks are tracked in `.githooks/`. Check both the Git setting and the directory; a missing hook path fails silently.
+Vite+ manages the hooks. The hook scripts are tracked in `.vite-hooks/`; `vp config` installs the dispatcher into the
+git-ignored `.vite-hooks/_/`. `vp config` leaves a `core.hooksPath` that points elsewhere alone, so set it first. Every clone
+and worktree needs its own dispatcher. Check both with `vp hooks status`; a missing dispatcher skips the hooks silently.
 
 ## Verify scopes
 
@@ -25,6 +28,6 @@ The `staged` block and the scripts under `scripts/verify/` own the step lists. H
 
 ## Staleness at commit time
 
-Pre-commit also runs advisory checks for vendored skill markers and documentation drift. If a staged change makes a doc
-stale, update the doc in the same commit. For an outdated installed skill, run `npx web-ui install skills` (also
-`npx web-ui install hooks` if the project uses hooks) with the project's existing `--harness` in the consumer project.
+Pre-commit also runs an advisory check for documentation drift. If a staged change makes a doc stale, update the doc in the
+same commit. Outdated installed skills surface at session start instead, as the `agent-tooling` topic describes; refresh them
+with `npx web-ui install skills` (also `npx web-ui install hooks` if the project uses hooks).

package/src/llms/skills/imf-web-ui-conventions/topics/library-setup.md

@@ -29,6 +29,9 @@ instead, so component colors cannot resolve against the opposite scheme:
 <WebUIProvider colorScheme="dark">
 ```
 
+To let the user pick Light, System, or Dark, place a `ColorSchemeToggle`. It stores the choice and works only while the
+provider's `colorScheme` is unset.
+
 ## Symptoms of broken setup
 
 - Unstyled components usually mean the `styles.css` import is missing.

package/src/llms/skills/imf-web-ui-conventions/topics/project-structure.md

@@ -35,8 +35,11 @@ A route file holds its search schema and `validateSearch`, its loaders, and its
 Route-local code that outgrows small in-file components (views, forms, hooks, tests) goes in a sibling folder named `-` plus
 the route file's name: `route.tsx` gets `-route/`, `products.tsx` gets `-products/`. TanStack Router ignores files and
 folders with a leading `-` when it builds the route tree, so the folder never becomes a route. The folder holds the route's
-views with their props types, hooks, `.module.css` files, and tests. A component small enough to sit in the route file stays
-there.
+views with their props types, hooks, `.module.css` files, and tests.
+
+A part used by one route file is inlined into it when it is a component under 50 lines, calls no `use*` hook, has no
+stylesheet or test of its own, and leaves that route file under 250 lines. Every other single-route part goes in the `-`
+folder. The thresholds keep tiny wrappers out of their own files without letting a route file grow into a page of views.
 
 `partials/` holds only parts that more than one route uses.
 

package/src/llms/skills/imf-web-ui-conventions/topics/styling.md

@@ -9,7 +9,9 @@ Use native CSS and Web UI's public seams. The library's CSS Modules and token na
 - Nest states, pseudo-elements, and child selectors under the root.
 - Write declarations before nested rules; browsers before Chrome 130, Firefox 132, and Safari 18 move later ones above them.
 - Do not nest under a selector list whose selectors differ in specificity. The nested rule takes the highest one.
-- Lift repeated values into custom properties, especially when a state or variant changes several descendants.
+- Lift a value into a custom property on the component's root when it repeats within that stylesheet, or when a state or
+  variant changes several descendants. A value that only recurs across files stays a literal in each; when those files show
+  one design element, a shared component owns it. Never define component values on `:root`.
 - Keep structurally different rules explicit; not every repeated value needs an abstraction.
 
 ```css

package/src/llms/skills/imf-web-ui-conventions/topics/tooling.md

@@ -49,7 +49,7 @@ from `vite-plus/test`. It needs Node `^22.22.1 || ^24.11 || >=26` and Git 2.32 o
 `vp <command>` is a built-in; `vp run <script>` runs a package script.
 
 Move an existing Vite, Vitest, ESLint, or Prettier project with `vp migrate --no-hooks` (`vp help migrate` lists its
-options), then check the result against this topic. The hook lives in `.githooks/`, as `git.md` describes.
+options), then check the result against this topic. The hook lives in `.vite-hooks/`, as `git.md` describes.
 
 ## Oxfmt
 
@@ -101,12 +101,19 @@ export default defineConfig({
 });
 ```
 
-Use strict TypeScript with bundler module resolution, `verbatimModuleSyntax`, unused-value checks, and `#/` paths. Keep
-`import type` for type-only imports.
+Use strict TypeScript with bundler module resolution, `verbatimModuleSyntax`, unused-value checks, and `import type` for
+type-only imports. The `#/` alias is a subpath import in `package.json`, which Vite and TypeScript both read without a
+plugin:
+
+```json
+"imports": {
+  "#/*": "./src/*"
+}
+```
 
 ## Pre-commit checks
 
-`.githooks/pre-commit` runs `vp staged --hide-unstaged --fail-on-changes --revert --diff-filter=ACMRD` with `set -e`. Those
+`.vite-hooks/pre-commit` runs `vp staged --hide-unstaged --fail-on-changes --revert --diff-filter=ACMRD` with `set -e`. Those
 flags make the checks see only the staged state, include deletion-only commits, fail the commit when a check would change a
 file, and restore the tree afterwards, so the hook never rewrites or stages files. The `staged` block in `vite.config.ts` is
 a function returning path-free commands such as `npm run --silent verify:lint`, so each project-wide check runs once. Use
@@ -119,10 +126,10 @@ Register Web UI's Vite plugins in the application configuration:
 ```ts
 import { defineConfig } from "vite-plus";
 import react from "@vitejs/plugin-react";
-import { imfusionBrandAssets, readableCssModuleNames } from "@imfusion/web-ui/vite";
+import { imfusionBrandAssets, localWebUILink, readableCssModuleNames } from "@imfusion/web-ui/vite";
 
 export default defineConfig({
-  plugins: [react(), imfusionBrandAssets(), readableCssModuleNames({ prefix: "app" })]
+  plugins: [react(), imfusionBrandAssets(), readableCssModuleNames({ prefix: "app" }), localWebUILink()]
 });
 ```
 
@@ -130,5 +137,37 @@ export default defineConfig({
 Register `readableCssModuleNames` in every compiler that processes the app's CSS, including development, Storybook, and
 production. A compiler left out produces different class names and styles that appear to work only in some environments.
 
-`localWebUILink` dedupes the library's peer dependencies when `@imfusion/web-ui` is linked from a local checkout
-(`file:../web-ui`), so the app loads one React. It does nothing for an installed package and does not cover server rendering.
+## Aligned runtime packages
+
+Web UI and the app run the same versions of these packages. The `peerDependencies` of
+`node_modules/@imfusion/web-ui/package.json` give the accepted ranges, and its `devDependencies` give the version Web UI
+builds and tests with. A matching major and minor is the rule; a patch difference is fine.
+
+- `react`, `react-dom`
+- `@types/react`, `@types/react-dom`
+- `@base-ui/react`, which brings `@floating-ui/*` with it
+- `vite-plus`
+- `vite`, the `npm:@voidzero-dev/vite-plus-core` alias that `vite-plus` provides
+
+## Version drift
+
+Aligned versions are the primary fix. The plugin and the `paths` block below catch the drift that slips through.
+
+`localWebUILink` stays registered for good. It does nothing for an installed package. When `@imfusion/web-ui` is a symlinked
+checkout, it keeps one React in dev, build, and Vitest.
+
+Add this to `compilerOptions` in `tsconfig.json`, merged by hand into an existing `paths`. For a symlinked checkout it keeps
+one set of React and Vite types for `tsc`:
+
+```json
+"paths": {
+  "react": ["./node_modules/@types/react"],
+  "react/*": ["./node_modules/@types/react/*"],
+  "vite": ["./node_modules/vite"]
+}
+```
+
+Only TypeScript reads these `paths`. Never let Vite read them: leave `resolve.tsconfigPaths` off and do not add
+`vite-tsconfig-paths`. Either one applies the `react` mapping at runtime, loads the types package as React, and breaks the
+build and tests once `@imfusion/web-ui` is installed from the registry. A symlinked checkout hides the break, because
+`localWebUILink()` dedupes React first.

package/src/llms/skills/imf-web-ui-conventions/topics/typescript.md

@@ -6,6 +6,8 @@ Prefer pure functions, immutable values, and side effects at the edges.
 
 - Do not use `any`. Accept `unknown` at an untrusted boundary and narrow it.
 - Infer local values; give exported functions explicit return types.
+  - TanStack options factories (`queryOptions`, `mutationOptions`, and similar) return their helper's inferred type. Spelling
+    it out loses the typed query key (`DataTag`) or repeats the helper's own generics.
 - Model states directly instead of filling a nullable value later.
 - Derive types from their source. Use `z.infer` for schemas and `React.ComponentProps` for Web UI components.
 - Avoid `as`. Keep an assertion only at an untyped third-party boundary where it is the honest boundary.

package/src/llms/skills/imf-web-ui-setup/SKILL.md

@@ -45,10 +45,19 @@ Include these pieces unless the existing project already has them or the user re
 - one server-backed current-user query at the route boundary;
 - a minimal `AppShell` in `_app/`, unless the user says the product has no persistent authenticated navigation;
 - an API topic folder for data shown by the first screen;
-- the root provider and library wiring.
+- the root provider and library wiring;
+- the Vite plugins below.
 
 The plan describes the exact starter files. It does not copy a generic starter project.
 
+## Vite plugins
+
+Propose a `vite.config.ts` that registers `imfusionBrandAssets()`, `readableCssModuleNames()`, and `localWebUILink()` from
+`@imfusion/web-ui/vite`, next to the plugins the project already has. Register `localWebUILink()` in every project: without a
+symlinked checkout it does nothing. Also propose the `tsconfig.json` `paths` block. Both keep one React and one set of types
+when the package is a symlinked checkout. Vite must not read those `paths`: never propose `resolve.tsconfigPaths` or
+`vite-tsconfig-paths`, and give the `#/` alias through `imports` in `package.json`. The `tooling` topic has the exact config.
+
 ## Installer steps
 
 For `agent-tooling`, list the `npx web-ui install` commands as steps for the human. Read existing registrations first and do

package/src/llms/skills/imf-web-ui-update/SKILL.md

@@ -79,8 +79,9 @@ npx web-ui install skills
 npx web-ui install hooks
 ```
 
-Both commands reuse the recorded harness. An install from the old `web-ui-install` has no record: pass the project's existing
-harness once, e.g. `--harness=all`. Stop on install failure. Do not use `--force` or `--legacy-peer-deps`.
+Both commands read the harness back from the installed files and print it. Codex leaves no trace without hooks, so a Claude
+and Codex install without hooks reads as Claude only; when the printed harness is wrong, pass the project's harness, e.g.
+`--harness=all`. Stop on install failure. Do not use `--force` or `--legacy-peer-deps`.
 
 The installer owns the vendored skills, its `AGENTS.md` fence, and hook scripts. Run the installer commands after the package
 update even when the existing registrations look complete: they refresh scripts, prune retired registrations, and merge
@@ -88,14 +89,20 @@ installer-owned entries idempotently into the registration file for the chosen h
 `.codex/hooks.json`, or both). Stop on malformed settings or installer conflicts. Read existing host registrations first and
 do not stack an event the project already covers.
 
-After the installer command, inspect the installed skill diffs and briefly report any guidance changes; version-marker
-changes alone do not count.
+After the installer command, inspect the installed skill diffs and briefly report any guidance changes.
 
 Then re-read, in full, every changed skill and reference the remaining work uses, starting with this update skill when it
 changed. A diff shows what moved, not the step order you continue under, so it does not replace the re-read. Continue from
 the current step using the updated guidance, keeping the original baseline, user choices, and completed changes in mind.
 Check for newly required steps without repeating completed mutations or expanding the approved scope.
 
+## Align the runtime packages
+
+After the install, compare the app's installed versions of the packages listed under Aligned runtime packages in the
+`tooling` topic with Web UI's own `package.json` in `node_modules/@imfusion/web-ui`. Report every major or minor mismatch and
+propose `npm install <package>@<Web UI's version>` for each. Make the change as its own commit, in this same update, after
+the base commit and with its own approval.
+
 ## Verify the base update
 
 After every mutating command, compare the status with the preflight snapshot. Stop on an unexpected path or overlapping
@@ -110,7 +117,7 @@ Run the consumer's documented full verification. Read its scripts first; prefer
 non-watch format, lint, typecheck, test, and build commands that exist.
 
 Verify that the installed package, manifest, and lockfile match the recorded target version. A mismatch is a base-update
-conflict. Check skill markers, the `AGENTS.md` fence, hook registrations, and the final update-owned path list.
+conflict. Check the `AGENTS.md` fence, hook registrations, and the final update-owned path list.
 
 Report before the first commit:
 

package/src/llms/skills/imf-web-ui-ux/SKILL.md

@@ -7,8 +7,8 @@ description:
 
 # Shape the screen
 
-Use this skill for screen-level decisions. Verify component APIs with `imf-web-ui-components`; put code and styling rules in
-`imf-web-ui-conventions`.
+Use this skill for screen-level decisions. The patterns below name no components: check which component fits a pattern, and
+its API, in `imf-web-ui-components`. Put code and styling rules in `imf-web-ui-conventions`.
 
 Invoke `imf-web-ui-user-profile` first and explain at its levels throughout.
 
@@ -34,33 +34,31 @@ unanswered, make the conservative choice and state the assumption.
 ## Choose a surface
 
 - Use a full page by default.
-- Use `Drawer` for a focused task that keeps the current page in context.
-- Use `Popover` for small contextual content or a light form.
-- Use `Tooltip` for a hint only. It must not contain required or interactive information.
-- Use `Collapsible` for secondary content inside the page.
-- Use `Tabs` for parallel views of one subject. If users must complete every section, use a flow instead.
-
-The library has no modal `Dialog` or `Toast`. Raise those gaps rather than hand-rolling a replacement without a product
-reason.
+- Use a side panel for a focused task that keeps the current page in context.
+- Use a floating panel anchored to its trigger for small contextual content or a light form.
+- Use a hover or focus hint for a short label only. It must not contain required or interactive information.
+- Use a collapsible region for secondary content inside the page.
+- Use tabs for parallel views of one subject. If users must complete every section, use a flow instead.
+- Use a modal dialog for a decision that must be settled before the page continues, such as a destructive action. If no
+  component fits a pattern, raise the gap rather than hand-rolling a replacement without a product reason.
 
 ## Choose between similar controls
 
-- `Button` performs an action, `ChipLink` goes somewhere, and `Chip` labels something.
-- Use `ChipLink` for a link inside text or a row of chips, and `RichLink` for a link that fills its own row, such as a list
-  of resources.
-- Use plain `Table` parts for static small data. Pair them with a headless table library for sorting, pagination, or column
-  logic. TanStack Table is the recommended choice.
-- Use `Callout` for persistent in-place status. Put transient confirmation near the action until a toast pattern exists.
-- Use `Switch` for an immediate setting and `Checkbox` for a submitted choice.
-- Use `Select` for a known list, and consider a different control when the list is very short or very large.
-- Use `Slider` when relative position matters more than typing an exact value.
+- An action is a button, navigation is a link, and a label is a chip.
+- Use an inline link inside text or in a row of chips, and a full-row link for a list of resources.
+- Use a plain table for static small data. Pair it with a headless table library for sorting, pagination, or column logic.
+  TanStack Table is the recommended choice.
+- Use an in-place status message for persistent status. Keep transient confirmation near the action it confirms.
+- Use a switch for an immediate setting and a checkbox for a submitted choice.
+- Use a select for a known list, and consider a different control when the list is very short or very large.
+- Use a slider when relative position matters more than typing an exact value.
 
 ## Build the hierarchy
 
-- Frame an application with `AppShell`.
-- Compose `Stack` and `Row` for spacing and arrangement, and wrap long-form text in `Prose`. Use `Separator` for a real
+- Frame an application with the library's app shell.
+- Arrange content with stack and row layouts, wrap long-form text in a prose container, and use a separator for a real
   division.
-- Use `Typo` for text hierarchy instead of styling raw headings beside it.
+- Use the library's typography components for text hierarchy instead of styling raw headings beside them.
 - Give a view one primary action. Make other actions quieter.
 - Choose density from the user's frequency and data volume: frequent work and large data need compact layouts; occasional
   work benefits from more explanation and space.
@@ -70,14 +68,37 @@ reason.
 Plan these states with the loaded view:
 
 - **Empty**: say what belongs here and what the user can do next.
-- **Loading**: use `Spinner` or a stable skeleton; keep the frame from jumping.
-- **Error**: explain what failed and the next action in a `Callout` near the problem.
+- **Loading**: use a spinner or a stable skeleton; keep the frame from jumping. The `imf-web-ui-conventions` data topic says
+  which skeleton part fits each way the data loads.
+- **Error**: explain what failed and the next action in an in-place status message near the problem.
 - **Loaded**: the normal view.
 
 ## Keep custom UI native
 
-When the library does not cover a piece, compose its primitives and use `--imf-ui-*` tokens. The implementation details are
-in `imf-web-ui-conventions`.
+When no component covers a piece, compose its primitives and use `--imf-ui-*` tokens. The implementation details are in
+`imf-web-ui-conventions`.
 
 For a screen review, read the relevant reference under `references/`: `usability-heuristics.md`, `visual-design.md`, or
 `forms.md`.
+
+## Public backdrop handover
+
+Public pages share a backdrop with the Keycloak login page: a light column with an animated line mesh, and a brand-colored
+panel. Both sides draw the same geometry, so the cross-origin navigation between them looks seamless. Read the geometry from
+these tokens and never from literals:
+
+- `--imf-ui-size-backdrop-edge`: where the brand panel starts on wide landscape screens.
+- `--imf-ui-size-backdrop-band-height`: the height of the light band on top of narrow or portrait screens, with the panel
+  below it.
+
+The switch between the two layouts is a media query, which a token cannot carry. Use the same breakpoint as the reference
+implementations.
+
+The backdrop also paints before React mounts, so the first frame already matches. Put the same two columns on `body` as a
+hard-stop `linear-gradient`, with `min-block-size: 100dvh`. In a single-page app, a marker on `html`
+(`data-backdrop-pending`), set by an inline script in `index.html` for the routes that show the backdrop, gates that
+gradient. The backdrop component removes the marker when it mounts. Generate that script's route list at build time from the
+router's own source, never as a hand-written copy: with TanStack file routes, a small Vite plugin (`transformIndexHtml`)
+reads the folder of backdrop routes and fills a placeholder in `index.html`, so a new route gets the pre-paint without anyone
+touching the script. The ImFusion Portal's public backdrop component and the Keycloak login theme's copy of it are the
+reference implementations.