@imfusion/web-ui 0.10.1-dev.37.g9147f90f → 0.10.1-dev.45.ga6a3c86a

package/dist/vite/local-web-ui-link.d.ts

@@ -1,8 +1,21 @@
 import { Plugin, UserConfig } from 'vite';
-/** Returns `undefined` for an installed package; only a checkout outside `node_modules` needs the config. */
-export declare function localWebUILinkConfig(root: string): UserConfig | undefined;
+interface LinkConfig extends UserConfig {
+    test?: {
+        server?: {
+            deps?: {
+                inline?: (string | RegExp)[];
+            };
+        };
+    };
+}
 /**
- * Lets a consumer link a local checkout (`"@imfusion/web-ui": "file:../web-ui"`) without loading two copies of React in
- * client dev and build. SSR is not covered. Does nothing for an installed package, so it can stay registered.
+ * Returns `undefined` unless `node_modules/@imfusion/web-ui` under `root` is a symlink. A symlinked checkout resolves its
+ * own copy of every peer, so the peers are deduped for Vite and the checkout's dependencies are inlined for Vitest.
+ */
+export declare function localWebUILinkConfig(root: string): LinkConfig | undefined;
+/**
+ * Lets a consumer keep `localWebUILink()` registered for good. It does nothing for an installed package. With a
+ * `file:` dependency on a Web UI checkout it makes the checkout share the app's React.
  */
 export declare function localWebUILink(): Plugin;
+export {};

package/dist/vite.js

@@ -1,11 +1,11 @@
 import { n as e } from "./paths-B5Ht3ETc.js";
-import { readFileSync as t, readdirSync as n, realpathSync as r } from "node:fs";
-import { dirname as i, join as a, resolve as o, sep as s } from "node:path";
+import { existsSync as t, readFileSync as n, readdirSync as r, realpathSync as i } from "node:fs";
+import { dirname as a, join as o, resolve as s } from "node:path";
 import { fileURLToPath as c } from "node:url";
 //#region src/vite/brand-assets.ts
-var l = i(c(import.meta.resolve("@imfusion/web-ui/assets/favicon/favicon.svg"))), u = n(l).map((e) => ({
+var l = a(c(import.meta.resolve("@imfusion/web-ui/assets/favicon/favicon.svg"))), u = r(l).map((e) => ({
 	name: e,
-	source: t(a(l, e))
+	source: n(o(l, e))
 })), d = {
 	".ico": "image/x-icon",
 	".png": "image/png",
@@ -20,11 +20,7 @@ function p() {
 		configureServer(e) {
 			e.middlewares.use((e, t, n) => {
 				let r = u.find(({ name: t }) => e.url?.split("?")[0] === `/${t}`);
-				if (!r) {
-					n();
-					return;
-				}
-				t.setHeader("Content-Type", f(r.name)), t.end(r.source);
+				r ? (t.setHeader("Content-Type", f(r.name)), t.end(r.source)) : n();
 			});
 		},
 		generateBundle() {
@@ -38,33 +34,42 @@ function p() {
 }
 //#endregion
 //#region src/vite/local-web-ui-link.ts
-function m(e) {
-	if (r(e).split(s).includes("node_modules")) return;
-	let n = JSON.parse(t(o(e, "package.json"), "utf-8")), i = typeof n == "object" && n ? Reflect.get(n, "peerDependencies") : {};
-	if (typeof i != "object" || !i) throw Error(`${e}/package.json has no peerDependencies`);
-	return { resolve: { dedupe: Object.keys(i) } };
+var m = [
+	"/@base-ui/",
+	"/@floating-ui/",
+	"/use-sync-external-store/"
+];
+function h(r) {
+	let a = s(i(r), "node_modules", "@imfusion", "web-ui");
+	if (!t(a) || i(a) === a) return;
+	let o = JSON.parse(n(s(e, "package.json"), "utf-8")), c = typeof o == "object" && o ? Reflect.get(o, "peerDependencies") : {};
+	if (typeof c != "object" || !c) throw Error(`${e}/package.json has no peerDependencies`);
+	return {
+		resolve: { dedupe: Object.keys(c) },
+		test: { server: { deps: { inline: m.map((e) => new RegExp(e)) } } }
+	};
 }
-function h() {
+function g() {
 	return {
 		name: "imf-ui:local-web-ui-link",
-		config: () => m(e)
+		config: (e) => h(s(e.root ?? process.cwd()))
 	};
 }
 //#endregion
 //#region src/vite/readable-css-module-names.ts
-function g(e, t) {
+function _(e, t) {
 	let { lightningcss: n, modules: r, transformer: i } = e.css ?? {}, a = n?.cssModules;
 	if (typeof a != "boolean" && r !== !1 && !a?.pattern && !(typeof r == "object" && r.generateScopedName)) return i === "postcss" ? { css: { modules: { generateScopedName: t } } } : { css: {
 		transformer: "lightningcss",
 		lightningcss: { cssModules: { pattern: t } }
 	} };
 }
-function _({ prefix: e }) {
+function v({ prefix: e }) {
 	let t = `${e}-[name]-[local]`;
 	return {
 		name: "imf-ui:readable-css-module-names",
-		config: (e) => g(e, t)
+		config: (e) => _(e, t)
 	};
 }
 //#endregion
-export { p as imfusionBrandAssets, h as localWebUILink, _ as readableCssModuleNames };
+export { p as imfusionBrandAssets, g as localWebUILink, v as readableCssModuleNames };

package/dist/web-ui-cli.js

@@ -278,19 +278,19 @@ function me(e) {
 	if (i.length > 0) {
 		for (let e of i) console.error(`No skills installed for ${e}. Run \`npx web-ui install skills --harness=${e}\` first.`);
 		process.exitCode = 1;
-		return;
-	}
-	v.intro("@imfusion/web-ui install hooks");
-	try {
-		de(r);
-	} catch (e) {
-		if (e instanceof U) {
-			console.error(e.message), process.exitCode = 1;
-			return;
+	} else {
+		v.intro("@imfusion/web-ui install hooks");
+		try {
+			de(r);
+		} catch (e) {
+			if (e instanceof U) {
+				console.error(e.message), process.exitCode = 1;
+				return;
+			}
+			throw e;
 		}
-		throw e;
+		v.outro("Done — agent hooks installed.");
 	}
-	v.outro("Done — agent hooks installed.");
 }
 var Q = new ee();
 Q.name("web-ui").description("Command-line tools for @imfusion/web-ui").version(P);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imfusion/web-ui",
-  "version": "0.10.1-dev.37.g9147f90f",
+  "version": "0.10.1-dev.45.ga6a3c86a",
   "description": "The official Web UI component library for ImFusion web apps",
   "author": "ImFusion GmbH",
   "homepage": "https://imfusion.com",
@@ -138,7 +138,7 @@
     "@types/react": "19.2.14",
     "@types/react-dom": "19.2.3",
     "@vitejs/plugin-react": "6.0.1",
-    "@vitest/browser-playwright": "5.0.3",
+    "@vitest/browser-playwright": "5.0.4",
     "concurrently": "9.2.1",
     "culori": "4.0.2",
     "fast-xml-parser": "5.11.2",
@@ -148,19 +148,21 @@
     "mermaid": "12.0.0",
     "playwright": "1.60.0",
     "prettier": "3.8.3",
+    "react": "19.2.5",
     "react-docgen-typescript": "2.4.0",
+    "react-dom": "19.2.5",
     "remark-gfm": "4.0.1",
     "storybook": "10.6.2",
     "tsx": "4.21.0",
     "typescript": "6.0.3",
-    "vite": "npm:@voidzero-dev/vite-plus-core@1.1.0",
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.2.0",
     "vite-plugin-dts": "5.0.0",
-    "vite-plus": "1.1.0",
-    "vitest": "5.0.3"
+    "vite-plus": "1.2.0",
+    "vitest": "5.0.4"
   },
   "overrides": {
-    "vite": "npm:@voidzero-dev/vite-plus-core@1.1.0",
-    "vitest": "5.0.3",
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.2.0",
+    "vitest": "5.0.4",
     "storybook": {
       ".": "$storybook",
       "vite-plus": "$vite-plus"

package/src/docgen/doc.gen.json

@@ -118,7 +118,7 @@
   "app-shell": {
     "root": {
       "name": "AppShell.Root",
-      "description": "",
+      "description": "AppShell — application layout shell.\n\nThe classic dashboard frame: collapsible navbar/aside sidebars, a page\nheader, an optional footer, and a scrolling main content area. Also called\nan app layout, application frame, dashboard shell, or sidebar layout.\n\nComposed of eight sub-components used with dot-notation: `AppShell.Root` wraps\n`AppShell.Header`, `AppShell.Navbar`, `AppShell.Aside`, `AppShell.Footer`,\n`AppShell.Main`, and (inside a sidebar) `AppShell.Section` and `AppShell.NavItem`.\n\nSizing is CSS-driven — override the `--imf-ui-appshell-*` custom properties\nrather than passing dimension props. Below the responsive breakpoints the\nnavbar (`md`) and aside (`lg`) open as drawers, and the shell renders the\nnavbar's toggle itself.\n\nCopied and adapted from Mantine's AppShell; no upstream runtime dependency.\nMIT licensed (see Mantine repo).",
       "props": [
         {
           "name": "ref",
@@ -141,6 +141,13 @@
             "defaultValue": "Close panel",
             "description": "Accessible name of the close button shown while the aside is a drawer."
           },
+          {
+            "name": "defaultOpen",
+            "required": false,
+            "type": "boolean",
+            "defaultValue": null,
+            "description": "Whether the drawer starts open when `open` is omitted."
+          },
           {
             "name": "onOpenChange",
             "required": false,
@@ -185,68 +192,6 @@
           }
         ]
       },
-      {
-        "name": "AppShell.Burger",
-        "description": "AppShell.Burger — the menu toggle: three sheared bands that cross while the navbar drawer is open. With no props it\nopens and closes that drawer. Takes its color from the surface and hides from `md` up, where the navbar is docked, and\nsteps back while the drawer is open, so the drawer's own close is the only one shown.",
-        "props": [
-          {
-            "name": "className",
-            "required": false,
-            "type": "string | ((state: ButtonState) => string)",
-            "defaultValue": null,
-            "description": "CSS class applied to the element, or a function that\nreturns a class based on the component's state."
-          },
-          {
-            "name": "focusableWhenDisabled",
-            "required": false,
-            "type": "boolean",
-            "defaultValue": "false",
-            "description": "Whether the button should be focusable when disabled."
-          },
-          {
-            "name": "label",
-            "required": false,
-            "type": "string",
-            "defaultValue": null,
-            "description": "Accessible name. Defaults to \"Open navigation\" or \"Close navigation\" from `opened`."
-          },
-          {
-            "name": "nativeButton",
-            "required": false,
-            "type": "boolean",
-            "defaultValue": "true",
-            "description": "Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (for example, `<div>`)."
-          },
-          {
-            "name": "opened",
-            "required": false,
-            "type": "boolean",
-            "defaultValue": null,
-            "description": "Draws the cross and sets `aria-expanded`. Defaults to whether the navbar drawer is open."
-          },
-          {
-            "name": "ref",
-            "required": false,
-            "type": "Ref<HTMLDivElement>",
-            "defaultValue": null,
-            "description": "Allows getting a ref to the component instance.\nOnce the component unmounts, React will set `ref.current` to `null`\n(or call the ref with `null` if you passed a callback ref).\n@see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs}"
-          },
-          {
-            "name": "render",
-            "required": false,
-            "type": "| ReactElement<\n    unknown,\n    string | JSXElementConstructor<any>\n  >\n| ComponentRenderFn<HTMLProps, ButtonState>",
-            "defaultValue": null,
-            "description": "Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
-          },
-          {
-            "name": "style",
-            "required": false,
-            "type": "| CSSProperties\n| ((state: ButtonState) => CSSProperties)",
-            "defaultValue": null,
-            "description": "Style applied to the element, or a function that\nreturns a style object based on the component's state."
-          }
-        ]
-      },
       {
         "name": "AppShell.Footer",
         "description": "",
@@ -262,7 +207,7 @@
       },
       {
         "name": "AppShell.Header",
-        "description": "",
+        "description": "AppShell.Header — the page row: a title and actions at every width. Below `md` it sits under the shell's bar, and from\n`md` it sits beside the rail.",
         "props": [
           {
             "name": "ref",
@@ -297,11 +242,18 @@
             "defaultValue": null,
             "description": "The signed-in account at the foot of the rail, usually an `AccountCard`. Without it the foot is omitted."
           },
+          {
+            "name": "defaultOpen",
+            "required": false,
+            "type": "boolean",
+            "defaultValue": null,
+            "description": "Whether the drawer starts open when `open` is omitted."
+          },
           {
             "name": "logo",
             "required": false,
             "type": "ReactNode",
-            "defaultValue": "<ImFusionLogo variant={variant === \"branded\" ? \"oncolor\" : \"brand\"} size=\"sm\" />",
+            "defaultValue": "variant === \"branded\" ? oncolorLogo : brandLogo",
             "description": "The brand at the top of the rail. Defaults to the ImFusion logo; `null` leaves the row empty."
           },
           {
@@ -336,7 +288,7 @@
       },
       {
         "name": "AppShell.NavItem",
-        "description": "AppShell.NavItem — a navbar link: icon, mono label, and an optional description. Takes its color from the navbar;\n`aria-current=\"page\"` underlines the label. Pass a router link through `render`.",
+        "description": "AppShell.NavItem — a navbar link: icon, mono label, and an optional description. Takes its color from the navbar;\n`aria-current=\"page\"` underlines the label. Pass a router link through `render`. Followed inside the navbar drawer,\nit closes the drawer.",
         "props": [
           {
             "name": "description",

package/src/llms/install-templates/hooks/baseline-staleness.sh

@@ -4,6 +4,8 @@
 # and warns on drift. Always exits 0 — staleness never blocks a commit.
 PKG=node_modules/@imfusion/web-ui/package.json
 [ -f "$PKG" ] || exit 0
+# A symlinked checkout reports its own dev version.
+[ -L node_modules/@imfusion/web-ui ] && exit 0
 CURRENT=$(node -p "require('./$PKG').version" 2>/dev/null) || exit 0
 
 # .claude/skills may be a symlink to .agents/skills; skip markers already read.

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

@@ -10,9 +10,12 @@ 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.
 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 '"name":"Write"|"name":"Edit"|"name":"MultiEdit"|"name":"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/skills/imf-web-ui-audit/SKILL.md

@@ -60,7 +60,11 @@ 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 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.
 
 ## Topics
 

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

@@ -109,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/tooling.md

@@ -119,10 +119,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 +130,32 @@ 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`, and it does nothing for an installed package:
+
+```json
+"paths": {
+  "react": ["./node_modules/@types/react"],
+  "react/*": ["./node_modules/@types/react/*"],
+  "vite": ["./node_modules/vite"]
+}
+```

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

@@ -45,10 +45,18 @@ 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. 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

@@ -96,6 +96,13 @@ changed. A diff shows what moved, not the step order you continue under, so it d
 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