@imfusion/web-ui 0.10.1-dev.41.g467e0e1a → 0.10.1-dev.46.g5fe8962a

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/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,15 +68,15 @@ 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. 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 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`.

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

@@ -6,9 +6,9 @@ validation. These rules cover structure and feedback.
 ## Structure
 
 - Remove fields that can be derived or asked later.
-- Use one column by default. Put short, inseparable values such as city and postal code in a `Row`.
-- Group related fields in a `Stack` and separate groups with more space.
-- Use a labeled `Fieldset` or heading for each group.
+- Use one column by default. Put short, inseparable values such as city and postal code on one row.
+- Group related fields with tight spacing and separate groups with more space.
+- Use a labeled fieldset or heading for each group.
 - Match a field's size to the value it expects.
 
 ## Labels
@@ -21,10 +21,10 @@ hints near the field before the user starts typing.
 Validate when the user finishes a field, except where live feedback genuinely helps, such as password requirements. Keep the
 error next to the field and use more than color to show it.
 
-An error says what is wrong and how to fix it. Keep the user's input. A server or form-level failure belongs in a `Callout`
-near the actions; field-level failures stay with their fields.
+An error says what is wrong and how to fix it. Keep the user's input. A server or form-level failure belongs in an in-place
+status message near the actions; field-level failures stay with their fields.
 
 ## Submission
 
-Use one primary `Button` whose label names the result, such as `Create project`. While submitting, keep the form visible and
+Use one primary button whose label names the result, such as `Create project`. While submitting, keep the form visible and
 show progress. A failed submission must leave the user's input on screen.

package/src/llms/skills/imf-web-ui-ux/references/usability-heuristics.md

@@ -5,12 +5,12 @@ user research.
 
 1. **Show system status.** Give async actions visible progress and confirmation.
 2. **Use the user's language.** Labels and ordering should match the domain, not an API's private names.
-3. **Provide an exit.** Drawers and popovers need clear dismissal; destructive actions need confirmation or undo.
+3. **Provide an exit.** Side panels and floating panels need clear dismissal; destructive actions need confirmation or undo.
 4. **Be consistent.** Reuse the library's established components and semantics.
 5. **Prevent errors.** Constrain known choices and disable actions that cannot work.
 6. **Support recognition.** Keep relevant options and context visible instead of making users remember them.
 7. **Support frequent users.** Add keyboard shortcuts or dense layouts when the task is frequent and data-heavy.
 8. **Remove decoration without a job.** Every element should support the action or the data.
 9. **Make errors recoverable.** Say what failed and what to do next, near the problem.
-10. **Keep help contextual.** Prefer a short hint beside a control to essential information hidden in a tooltip or separate
-    page.
+10. **Keep help contextual.** Prefer a short hint beside a control to essential information hidden in a hover hint or
+    separate page.

package/src/llms/skills/imf-web-ui-ux/references/visual-design.md

@@ -7,12 +7,12 @@ Use this when a screen works but still looks wrong. Decide the hierarchy before
 Write the intended order of attention: title, primary action, content, and supporting details. Use contrast and scale to make
 that order visible. Keep variation limited; if everything is loud, nothing leads.
 
-Reserve saturated status colors for meaning. The primary `Button` should be the strongest action treatment on the screen.
+Reserve saturated status colors for meaning. The primary button should be the strongest action treatment on the screen.
 
 ## Grouping
 
-Use proximity first: tight gaps inside a group, larger gaps between groups. `Stack` gap values encode this relationship. Use
-a shared `Card` or bordered region only when spacing alone does not make the relationship clear.
+Use proximity first: tight gaps inside a group, larger gaps between groups. Spacing values encode this relationship. Use a
+shared card or bordered region only when spacing alone does not make the relationship clear.
 
 Similarity helps related elements stay recognisable across a layout. It supports proximity; it does not replace it.
 

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 };