@imfusion/web-ui 0.10.1-dev.41.g467e0e1a → 0.10.1-dev.45.ga6a3c86a

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

@@ -2,9 +2,8 @@
 name: imf-web-ui-conventions
 description:
   "Apply the ImFusion frontend conventions to consumer code. Use this whenever a task writes a wrapper or custom UI, CSS,
-  TypeScript, data fetching, validation, tests, project files, configuration, documentation, dependencies, linking a local
-  Web UI checkout, or agent tooling in a project that uses @imfusion/web-ui. Read only the topic references that match the
-  task."
+  TypeScript, data fetching, validation, tests, project files, configuration, documentation, dependencies, or agent tooling
+  in a project that uses @imfusion/web-ui. Read only the topic references that match the task."
 user-invocable: false
 ---
 
@@ -15,27 +14,27 @@ a gap or to make a deliberate deviation visible; do not refactor a project just
 
 ## Choose a topic
 
-| Topic                                            | Read when                                                             |
-| ------------------------------------------------ | --------------------------------------------------------------------- |
-| [library-setup](topics/library-setup.md)         | Installing or repairing stylesheet and provider wiring.               |
-| [library-boundary](topics/library-boundary.md)   | Rendering, locking, or wrapping components, or choosing a peer.       |
-| [authentication](topics/authentication.md)       | Protecting routes or defining login and logout.                       |
-| [react](topics/react.md)                         | Designing component roles, state ownership, or effects.               |
-| [components](topics/components.md)               | Adding files or deciding component anatomy.                           |
-| [typescript](topics/typescript.md)               | Writing TypeScript or naming values.                                  |
-| [styling](topics/styling.md)                     | Writing CSS or customizing Web UI.                                    |
-| [tokens](topics/tokens.md)                       | Choosing an exact token name.                                         |
-| [class-names](topics/class-names.md)             | Mapping variants and `className` to CSS.                              |
-| [validation](topics/validation.md)               | Accepting data from outside the frontend.                             |
-| [data](topics/data.md)                           | Adding API queries, mutations, or invalidation.                       |
-| [project-structure](topics/project-structure.md) | Adding files or routes.                                               |
-| [testing](topics/testing.md)                     | Deciding what to test.                                                |
-| [tooling](topics/tooling.md)                     | Adding a dependency, configuring a tool, or linking a local checkout. |
-| [npm-project](topics/npm-project.md)             | Changing `package.json`, scripts, pins, or Node.                      |
-| [git](topics/git.md)                             | Configuring hooks or choosing verification scope.                     |
-| [agent-tooling](topics/agent-tooling.md)         | Installing skills or lifecycle hooks.                                 |
-| [assets](topics/assets.md)                       | Adding images, icons, or other static files.                          |
-| [docs-structure](topics/docs-structure.md)       | Writing or reorganizing repository docs.                              |
+| Topic                                            | Read when                                                       |
+| ------------------------------------------------ | --------------------------------------------------------------- |
+| [library-setup](topics/library-setup.md)         | Installing or repairing stylesheet and provider wiring.         |
+| [library-boundary](topics/library-boundary.md)   | Rendering, locking, or wrapping components, or choosing a peer. |
+| [authentication](topics/authentication.md)       | Protecting routes or defining login and logout.                 |
+| [react](topics/react.md)                         | Designing component roles, state ownership, or effects.         |
+| [components](topics/components.md)               | Adding files or deciding component anatomy.                     |
+| [typescript](topics/typescript.md)               | Writing TypeScript or naming values.                            |
+| [styling](topics/styling.md)                     | Writing CSS or customizing Web UI.                              |
+| [tokens](topics/tokens.md)                       | Choosing an exact token name.                                   |
+| [class-names](topics/class-names.md)             | Mapping variants and `className` to CSS.                        |
+| [validation](topics/validation.md)               | Accepting data from outside the frontend.                       |
+| [data](topics/data.md)                           | Adding API queries, mutations, or invalidation.                 |
+| [project-structure](topics/project-structure.md) | Adding files or routes.                                         |
+| [testing](topics/testing.md)                     | Deciding what to test.                                          |
+| [tooling](topics/tooling.md)                     | Adding a dependency or configuring a tool.                      |
+| [npm-project](topics/npm-project.md)             | Changing `package.json`, scripts, pins, or Node.                |
+| [git](topics/git.md)                             | Configuring hooks or choosing verification scope.               |
+| [agent-tooling](topics/agent-tooling.md)         | Installing skills or lifecycle hooks.                           |
+| [assets](topics/assets.md)                       | Adding images, icons, or other static files.                    |
+| [docs-structure](topics/docs-structure.md)       | Writing or reorganizing repository docs.                        |
 
 ## How to use the topics
 

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

@@ -110,6 +110,7 @@ sections one to one — change a topic's sections and this file follows in the s
 - [ ] Oxlint and TypeScript
 - [ ] Pre-commit checks
 - [ ] Vite plugins, including `localWebUILink()`
+- [ ] Aligned runtime packages
 
 ## npm project — `npm-project`
 

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

@@ -130,33 +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` keeps a local Web UI checkout linked for good. With no link it does nothing. After
-`npx web-ui link <checkout>` it serves the linked build without pre-bundling it and reloads the page on each sync;
-`npx web-ui unlink` restores the published package. Restart the dev server after either command, since the plugin reads the
-link when Vite starts. The plugin does not cover server rendering.
+## Aligned runtime packages
 
-## Enable or disable the live Web UI link
+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.
 
-Use this when a consumer must run against unreleased Web UI changes. The link copies the checkout's `dist/` into the
-consumer's installed package and syncs it after each rebuild, so uncommitted edits in the checkout reach the consumer too.
+- `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
 
-To enable:
+## Version drift
 
-1. Confirm `localWebUILink()` is registered in the consumer's `vite.config.ts`. If it is missing, ask before adding it.
-2. Find the checkout path: use `WEB_UI_CHECKOUT` when it is set, and ask otherwise.
-3. Start `npm run dev:lib` in the checkout as a background process. `web-ui link` refuses a checkout without `dist/`.
-4. Start `npx web-ui link <checkout>` in the consumer as a background process. It keeps running and syncs on each rebuild.
-5. Restart the consumer's dev server.
-6. Verify the rebuild arrives: after a rebuild, `diff -rq <checkout>/dist node_modules/@imfusion/web-ui/dist` prints nothing.
+Aligned versions are the primary fix. The plugin and the `paths` block below catch the drift that slips through.
 
-To disable:
+`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.
 
-1. Stop the background `web-ui link` and `npm run dev:lib` processes.
-2. Run `npx web-ui unlink` in the consumer.
-3. Restart the consumer's dev server.
+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:
 
-`npm install` and `npm ci` replace the linked package with the published one. After either, run `npx web-ui link <checkout>`
-again and restart the dev server.
-
-Do not commit while linked when the consumer's checks depend on unreleased Web UI API. They pass against the checkout and
-fail against the published 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

@@ -53,8 +53,9 @@ The plan describes the exact starter files. It does not copy a generic starter p
 ## 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: with no
-link it does nothing. The `tooling` topic has the exact config and the workflow for enabling a live link.
+`@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
 

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

package/dist/paths-CZtwNknt.js

@@ -1,132 +0,0 @@
-import { chmodSync as e, copyFileSync as t, cpSync as n, existsSync as r, mkdirSync as i, readFileSync as a, readdirSync as o, rmSync as s, watch as c, writeFileSync as l } from "node:fs";
-import { dirname as u, join as d, relative as f, resolve as p } from "node:path";
-import { fileURLToPath as m } from "node:url";
-import { spawnSync as h } from "node:child_process";
-//#region src/cli/link.ts
-var g = "@imfusion/web-ui", _ = ".local-link.json", v = [
-	"exports",
-	"module",
-	"types",
-	"bin"
-], y = class extends Error {};
-function b(e) {
-	return p(e, "node_modules", "@imfusion", "web-ui");
-}
-function x(e) {
-	return r(d(e, _));
-}
-function S(e) {
-	return p(e, "node_modules", ".web-ui-link");
-}
-function C(e) {
-	let t = JSON.parse(a(e, "utf-8"));
-	if (typeof t != "object" || !t || Array.isArray(t)) throw new y(`${e} is not a JSON object.`);
-	return Object.fromEntries(Object.entries(t));
-}
-function w(e) {
-	if (!r(d(e, "package.json"))) throw new y(`${g} is not installed at ${e}. Run npm install in the consumer first.`);
-}
-function T(e) {
-	let t = d(e, "package.json");
-	if (!r(t) || C(t).name !== g) throw new y(`${e} is not a ${g} checkout.`);
-	if (!r(d(e, "dist", "index.js"))) throw new y(`${e} has no dist/ build. Run npm run dev:lib in that checkout first.`);
-}
-function E(e, t) {
-	i(t, { recursive: !0 }), n(e, t, {
-		recursive: !0,
-		force: !0
-	});
-	for (let n of o(t, {
-		recursive: !0,
-		withFileTypes: !0
-	})) {
-		let i = d(n.parentPath, n.name);
-		r(d(e, f(t, i))) || s(i, {
-			recursive: !0,
-			force: !0
-		});
-	}
-}
-function D(e, t) {
-	let n = { ...e };
-	for (let e of v) e in t && (n[e] = t[e]);
-	return n;
-}
-function O(t, n) {
-	let r = n.bin, i = typeof r == "string" ? [r] : typeof r == "object" && r ? Object.values(r) : [];
-	for (let n of i) typeof n == "string" && e(d(t, n), 493);
-}
-function k(e, t) {
-	let n = b(e), r = d(S(e), "backup");
-	if (!x(n)) return;
-	E(d(t, "dist"), d(n, "dist"));
-	let i = D(C(d(r, "package.json")), C(d(t, "package.json")));
-	l(d(n, "package.json"), `${JSON.stringify(i, null, 2)}\n`), O(n, i);
-}
-function A(e, n) {
-	let r = b(e);
-	if (w(r), T(n), !x(r)) {
-		let n = d(S(e), "backup");
-		s(n, {
-			recursive: !0,
-			force: !0
-		}), E(d(r, "dist"), d(n, "dist")), i(n, { recursive: !0 }), t(d(r, "package.json"), d(n, "package.json"));
-	}
-	return l(d(r, _), `${JSON.stringify({
-		checkout: n,
-		linkedAt: (/* @__PURE__ */ new Date()).toISOString()
-	}, null, 2)}\n`), k(e, n), r;
-}
-function j(e) {
-	let n = b(e);
-	if (!x(n)) return [`${n} is not linked. Nothing to restore.`];
-	let i = S(e), a = d(i, "backup");
-	if (!r(d(a, "dist")) || !r(d(a, "package.json"))) throw new y(`No backup at ${a}. Run npm install to restore the published package.`);
-	return E(d(a, "dist"), d(n, "dist")), t(d(a, "package.json"), d(n, "package.json")), s(d(n, _)), s(i, {
-		recursive: !0,
-		force: !0
-	}), [
-		"Restored dist/ from the published build.",
-		"Restored package.json.",
-		"Removed the link marker and the backup."
-	];
-}
-function M(e, t, n) {
-	let r = b(e), i, a = c(d(t, "dist"), { recursive: !0 }, () => {
-		clearTimeout(i), i = setTimeout(() => {
-			if (!x(r)) {
-				n("Package is no longer linked; stopped syncing."), a.close();
-				return;
-			}
-			try {
-				k(e, t), n(`Synced at ${(/* @__PURE__ */ new Date()).toLocaleTimeString()}`);
-			} catch (e) {
-				n(`Sync failed, retrying on the next change: ${e instanceof Error ? e.message : String(e)}`);
-			}
-		}, 150);
-	});
-	return a;
-}
-//#endregion
-//#region src/cli/paths.ts
-function N(e) {
-	let t = e;
-	for (; !r(p(t, "package.json"));) {
-		let n = u(t);
-		if (n === t) throw Error(`Could not find package.json above ${e}`);
-		t = n;
-	}
-	return t;
-}
-var P = N(u(m(import.meta.url))), F = process.cwd();
-function I(e) {
-	let t = F;
-	for (; t !== u(t) && !r(p(t, "node_modules", ".bin"));) t = u(t);
-	let n = p(t, "node_modules", ".bin"), i = p(n, "vp"), [a, o] = r(i) ? [i, ["fmt", ...e]] : [p(n, "prettier"), ["--write", ...e]];
-	r(a) && h(a, o, {
-		cwd: F,
-		stdio: "ignore"
-	});
-}
-//#endregion
-export { A as a, M as c, y as i, P as n, j as o, F as r, x as s, I as t };