@imfusion/web-ui 0.6.4-dev.8.g41d03f2f → 0.7.0

package/dist/vite.js

@@ -0,0 +1,55 @@
+import { readFileSync as e, readdirSync as t } from "node:fs";
+import { dirname as n, join as r } from "node:path";
+import { fileURLToPath as i } from "node:url";
+//#region src/vite/brand-assets.ts
+var a = n(i(import.meta.resolve("@imfusion/web-ui/assets/favicon/favicon.svg"))), o = t(a).map((t) => ({
+	name: t,
+	source: e(r(a, t))
+})), s = {
+	".ico": "image/x-icon",
+	".png": "image/png",
+	".svg": "image/svg+xml"
+};
+function c(e) {
+	return s[e.slice(e.lastIndexOf("."))] ?? "application/octet-stream";
+}
+function l() {
+	return {
+		name: "imf-ui:brand-assets",
+		configureServer(e) {
+			e.middlewares.use((e, t, n) => {
+				let r = o.find(({ name: t }) => e.url?.split("?")[0] === `/${t}`);
+				if (!r) {
+					n();
+					return;
+				}
+				t.setHeader("Content-Type", c(r.name)), t.end(r.source);
+			});
+		},
+		generateBundle() {
+			for (let e of o) this.emitFile({
+				fileName: e.name,
+				source: e.source,
+				type: "asset"
+			});
+		}
+	};
+}
+//#endregion
+//#region src/vite/readable-css-module-names.ts
+function u(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 d({ prefix: e }) {
+	let t = `${e}-[name]-[local]`;
+	return {
+		name: "imf-ui:readable-css-module-names",
+		config: (e) => u(e, t)
+	};
+}
+//#endregion
+export { l as imfusionBrandAssets, d as readableCssModuleNames };

package/dist/web-ui-cli.js

@@ -0,0 +1,322 @@
+#!/usr/bin/env node
+import { chmodSync as e, cpSync as t, existsSync as n, lstatSync as r, mkdirSync as i, readFileSync as a, readdirSync as o, readlinkSync as s, realpathSync as c, rmSync as l, symlinkSync as u, writeFileSync as d } from "node:fs";
+import { dirname as f, relative as p, resolve as m } from "node:path";
+import { fileURLToPath as ee } from "node:url";
+import { Command as te, Option as ne } from "commander";
+import * as h from "@clack/prompts";
+import { spawnSync as g } from "node:child_process";
+var _ = {
+	harnesses: {
+		claude: {
+			label: "Claude Code",
+			hookSettings: ".claude/settings.json",
+			hookTemplate: "settings.json"
+		},
+		codex: {
+			label: "Codex",
+			hookSettings: ".codex/hooks.json",
+			hookTemplate: "codex-hooks.json"
+		}
+	},
+	namespace: "imf-web-ui",
+	hooksDir: ".agents/hooks/imf-web-ui",
+	templatesDir: "src/llms/install-templates",
+	skillsSource: "src/llms/skills",
+	skillsDir: ".agents/skills",
+	linkDir: ".claude/skills",
+	versionMarker: ".imf-web-ui-skill-version.json"
+};
+//#endregion
+//#region src/cli/paths.ts
+function re(e) {
+	let t = e;
+	for (; !n(m(t, "package.json"));) {
+		let n = f(t);
+		if (n === t) throw Error(`Could not find package.json above ${e}`);
+		t = n;
+	}
+	return t;
+}
+var v = re(f(ee(import.meta.url))), y = process.cwd(), ie = `<!-- ${_.namespace}:begin`, b = `<!-- ${_.namespace}:end -->`, ae = m(v, _.templatesDir, "AGENTS.md"), x = m(y, "AGENTS.md");
+function S(e) {
+	let t = e.indexOf(ie), n = e.indexOf(b);
+	return t === -1 || n === -1 ? null : e.slice(t, n + b.length);
+}
+function oe() {
+	if (!n(x)) return "absent";
+	let e = S(a(ae, "utf-8"));
+	if (!e) return "absent";
+	let t = a(x, "utf-8"), r = S(t), i = r ? t.replace(r, e) : `${t.trimEnd()}\n\n${e}\n`;
+	return i === t ? "unchanged" : (d(x, i), r ? "updated" : "added");
+}
+//#endregion
+//#region src/cli/skills.ts
+var C = Object.keys(_.harnesses).filter((e) => e in _.harnesses), se = [...C, "all"];
+function w(e) {
+	return e === "all" ? C : [e];
+}
+function T(e) {
+	return `./${p(y, e)}`;
+}
+var E = _.namespace, D = _.versionMarker, O = m(v, _.skillsSource), k = m(y, _.skillsDir), A = m(y, _.linkDir), j = class extends Error {}, M = JSON.parse(a(m(v, "package.json"), "utf-8"));
+if (typeof M != "object" || !M || !("version" in M) || typeof M.version != "string") throw Error(`${m(v, "package.json")} has no string "version" field`);
+var N = M.version;
+function P(e) {
+	return e === E || e.startsWith(`${E}-`);
+}
+function F() {
+	return n(O) ? o(O, { withFileTypes: !0 }).filter((e) => e.isDirectory() && P(e.name)).map((e) => e.name).sort() : [];
+}
+function I(e) {
+	let t = m(k, e, D);
+	if (!n(t)) return null;
+	try {
+		let e = JSON.parse(a(t, "utf-8"));
+		if (typeof e != "object" || !e) return null;
+		let n = "harnesses" in e && Array.isArray(e.harnesses) ? e.harnesses : null;
+		return n ? C.filter((e) => n.includes(e)) : null;
+	} catch {
+		return null;
+	}
+}
+function L(e) {
+	for (let t of e) {
+		let e = I(t);
+		if (e && e.length > 0) return e;
+	}
+	return null;
+}
+function R(e, t, r) {
+	if (n(e)) for (let n of o(e).filter(P)) t.has(n) || (l(m(e, n), {
+		recursive: !0,
+		force: !0
+	}), h.log.info(`Removed skill: ${n} (${r})`));
+}
+function ce() {
+	return n(A) && n(k) && c(A) === c(k);
+}
+function le(e) {
+	let t = m(A, e), n = p(A, m(k, e)), a = r(t, { throwIfNoEntry: !1 });
+	a?.isSymbolicLink() && s(t) === n || (a && l(t, {
+		recursive: !0,
+		force: !0
+	}), i(A, { recursive: !0 }), u(n, t));
+}
+function z(e, n) {
+	try {
+		i(k, { recursive: !0 });
+		for (let r of e) {
+			let e = m(k, r);
+			l(e, {
+				recursive: !0,
+				force: !0
+			}), t(m(O, r), e, { recursive: !0 }), d(m(e, D), JSON.stringify({
+				version: N,
+				harnesses: n
+			}, null, 2) + "\n");
+		}
+		if (R(k, new Set(e), "no longer in this bundle"), h.log.success(`Skills -> ${T(k)}/${E}*`), ce()) return;
+		if (n.includes("claude")) {
+			for (let t of e) le(t);
+			R(A, new Set(e), "no longer in this bundle"), h.log.success(`Claude Code -> ${T(A)}/${E}* (symlinks -> ${T(k)})`);
+		} else R(A, /* @__PURE__ */ new Set(), "claude not selected");
+	} catch (e) {
+		throw e instanceof Error ? new j(e.message) : e;
+	}
+}
+//#endregion
+//#region src/cli/hooks.ts
+var B = m(v, _.templatesDir), V = m(B, "hooks"), H = m(y, _.hooksDir), U = class extends Error {};
+function ue(e, t) {
+	if (typeof e != "object" || !e || Array.isArray(e)) throw new U(`${t} is not a JSON object.`);
+	let n = { ...e };
+	if ("hooks" in n) {
+		if (typeof n.hooks != "object" || n.hooks === null || Array.isArray(n.hooks)) throw new U(`${t}: "hooks" is not a JSON object.`);
+		for (let [e, r] of Object.entries(n.hooks)) if (!Array.isArray(r)) throw new U(`${t}: "hooks.${e}" is not a JSON array.`);
+	}
+	return n;
+}
+function W(e) {
+	let t;
+	try {
+		t = JSON.parse(a(e, "utf-8"));
+	} catch {
+		throw new U(`${e} is not valid JSON.`);
+	}
+	return ue(t, e);
+}
+function de(e) {
+	let t = y;
+	for (; t !== f(t) && !n(m(t, "node_modules", ".bin"));) t = f(t);
+	let r = m(t, "node_modules", ".bin", "prettier");
+	n(r) && g(r, ["--write", e], {
+		cwd: y,
+		stdio: "ignore"
+	});
+}
+function fe() {
+	let n = o(V).filter((e) => e.endsWith(".sh"));
+	i(H, { recursive: !0 });
+	for (let r of n) {
+		let n = m(H, r);
+		t(m(V, r), n, { force: !0 }), e(n, 493);
+	}
+	let r = o(H).filter((e) => e.endsWith(".sh") && !n.includes(e));
+	for (let e of r) l(m(H, e), { force: !0 });
+	return {
+		installed: n,
+		removed: r
+	};
+}
+var G = `${_.hooksDir}/`;
+function K(e) {
+	if (typeof e != "string") return null;
+	let t = e.lastIndexOf(G);
+	if (t === -1) return null;
+	let n = /^([\w.-]+)["']?$/.exec(e.slice(t + G.length));
+	return n ? n[1] : null;
+}
+function q(e) {
+	return typeof e == "object" && !!e && "hooks" in e && Array.isArray(e.hooks);
+}
+function J(e) {
+	return q(e) ? e.hooks : null;
+}
+function Y(e) {
+	return typeof e == "object" && e && "command" in e ? e.command : void 0;
+}
+function X(e) {
+	let t = J(e);
+	return t ? t.map((e) => K(Y(e))).filter((e) => e !== null) : [];
+}
+function pe(e, t, n) {
+	e.hooks ??= {};
+	let r = 0, i = 0, a = [];
+	for (let [r, o] of Object.entries(e.hooks)) {
+		let s = 0, c = o.map((e) => {
+			if (!q(e)) return e;
+			let t = e.hooks, r = t.filter((e) => {
+				let t = K(Y(e));
+				return t === null || n.includes(t);
+			});
+			return s += t.length - r.length, r.length === t.length ? e : {
+				...e,
+				hooks: r
+			};
+		}).filter((e) => {
+			let t = J(e);
+			return t === null || t.length > 0;
+		});
+		s !== 0 && (i += s, c.length === 0 && !(r in t) ? a.push(r) : e.hooks[r] = c);
+	}
+	a.length > 0 && (e.hooks = Object.fromEntries(Object.entries(e.hooks).filter(([e]) => !a.includes(e))));
+	for (let [n, i] of Object.entries(t)) {
+		e.hooks[n] ??= [];
+		for (let t of i) {
+			let i = X(t);
+			e.hooks[n].some((e) => X(e).some((e) => i.includes(e))) || (e.hooks[n].push(t), r++);
+		}
+	}
+	return {
+		added: r,
+		removed: i
+	};
+}
+function me(e) {
+	let t = /* @__PURE__ */ new Map(), r = /* @__PURE__ */ new Map();
+	for (let i of C) {
+		let a = m(y, _.harnesses[i].hookSettings);
+		if (n(a) && t.set(i, W(a)), e.includes(i)) {
+			let e = m(B, _.harnesses[i].hookTemplate);
+			r.set(i, W(e).hooks ?? {});
+		}
+	}
+	let { installed: a, removed: o } = fe();
+	h.log.success(`Agent hooks -> ${T(H)} (${String(a.length)} scripts)`), o.length > 0 && h.log.info(`Removed stale hook script(s): ${o.join(", ")} (no longer shipped)`);
+	for (let n of C) {
+		let o = e.includes(n);
+		if (!o && !t.has(n)) continue;
+		let s = m(y, _.harnesses[n].hookSettings), c = r.get(n) ?? {}, l = t.get(n) ?? {}, u = pe(l, c, o ? a : []);
+		if (u.added === 0 && u.removed === 0) {
+			o && h.log.info(`Hook registrations already present in ${T(s)}`);
+			continue;
+		}
+		i(f(s), { recursive: !0 }), d(s, JSON.stringify(l, null, 2) + "\n"), de(s);
+		let p = [u.added > 0 && `registered ${String(u.added)}`, u.removed > 0 && `removed ${String(u.removed)} stale`].filter(Boolean);
+		h.log.success(`${p.join(", ")} hook registration(s) in ${T(s)}`);
+	}
+}
+//#endregion
+//#region src/cli/index.ts
+function Z() {
+	return new ne("--harness <harness>", "claude, codex, or all").choices(se);
+}
+async function he(e, t, n) {
+	if (t) return h.log.info(`Harness from --harness flag: ${t.join(", ")}`), t;
+	let r = L(e);
+	if (r && !n) return h.log.info(`Refreshing the existing install: ${r.join(", ")} — pass --reconfigure to choose differently.`), r;
+	if (!process.stdin.isTTY) return console.error("Pass --harness=claude|codex|all — no terminal to prompt in."), process.exitCode = 1, null;
+	let i = await h.multiselect({
+		message: "Install into which harness (or harnesses)?",
+		options: C.map((e) => ({
+			value: e,
+			label: _.harnesses[e].label
+		})),
+		required: !0
+	});
+	return h.isCancel(i) ? (h.cancel("Cancelled — nothing installed."), null) : i;
+}
+async function ge(e) {
+	let t = e.harness ? w(e.harness) : null, n = F();
+	if (h.intro(`@imfusion/web-ui install skills — ${String(n.length)} skills`), n.length === 0) {
+		h.log.error("No skills found. Reinstall @imfusion/web-ui and try again."), h.outro("Nothing installed."), process.exitCode = 1;
+		return;
+	}
+	let r = await he(n, t, e.reconfigure === !0);
+	if (!r) return;
+	h.log.message(`Skills in this bundle:\n${n.map((e) => `  - ${e}`).join("\n")}`);
+	try {
+		z(n, r);
+	} catch (e) {
+		if (e instanceof j) {
+			h.log.error(e.message), h.outro("Install failed."), process.exitCode = 1;
+			return;
+		}
+		throw e;
+	}
+	let i = oe();
+	(i === "updated" || i === "added") && h.log.success(`Refreshed the ${_.namespace} block in ./AGENTS.md`), h.outro(`Done — ${String(n.length)} skills installed.`);
+}
+function _e(e) {
+	let t = e.harness ? w(e.harness) : null, n = L(F());
+	if (!t && !n) {
+		console.error("No harness recorded. Pass --harness=claude|codex|all."), process.exitCode = 1;
+		return;
+	}
+	let r = t ?? n ?? [], i = r.filter((e) => !(n ?? []).includes(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;
+	}
+	h.intro("@imfusion/web-ui install hooks");
+	try {
+		me(r);
+	} catch (e) {
+		if (e instanceof U) {
+			console.error(e.message), process.exitCode = 1;
+			return;
+		}
+		throw e;
+	}
+	h.outro("Done — agent hooks installed.");
+}
+var Q = new te();
+Q.name("web-ui").description("Command-line tools for @imfusion/web-ui").version(N);
+var $ = Q.command("install").description("Install @imfusion/web-ui agent skills or hooks into a project");
+$.command("skills").description("Install skills for the chosen harness").addOption(Z()).option("--reconfigure", "Re-open the harness selection prompt on an existing install").action(ge), $.command("hooks").description("Install agent lifecycle hooks (requires skills already installed for the harness)").addOption(Z()).action(_e), $.action(() => {
+	$.help();
+}), Q.action(() => {
+	Q.help();
+}), await Q.parseAsync();
+//#endregion

package/docs/user-guide/AgentTooling.mdx

@@ -0,0 +1,133 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+import { Typo } from "#/components/typo";
+
+<Meta title="User Guide/Agent Tooling" />
+
+<Typo.Hero>Agent tooling</Typo.Hero>
+
+The package ships skills and lifecycle hooks for coding agents working in a project that uses `@imfusion/web-ui`. Both are
+optional, but highly recommended: the library is built to be set up and used through an agent.
+
+## Supported agents
+
+The skills follow the [Agent Skills](https://agentskills.io/) standard and install into `.agents/skills/`. Project
+instructions go into [`AGENTS.md`](https://agents.md/): when the project has one, the installer keeps a fenced Web UI block
+in it up to date.
+
+| Agent | Skills | `AGENTS.md` | Hooks |
+| --- | --- | --- | --- |
+| [Codex](https://developers.openai.com/codex/skills) | Reads `.agents/skills/` | [Reads it](https://developers.openai.com/codex/guides/agents-md) | [Supported](https://developers.openai.com/codex/hooks) |
+| [Claude Code](https://code.claude.com/docs/en/skills) | Reads only `.claude/skills/`, so the installer links each skill there | [Reads it](https://code.claude.com/docs/en/changelog#2-1-277) when the project has no `CLAUDE.md`; otherwise add `@AGENTS.md` to `CLAUDE.md` | [Supported](https://code.claude.com/docs/en/hooks) |
+| Other Agent Skills clients | Check the agent's docs for `.agents/skills/` | Check the agent's docs | Not installed |
+
+The installer targets Codex and Claude Code. Other agents that implement the standard are listed on
+[agentskills.io](https://agentskills.io/); one that reads `.agents/skills/` picks up the same skills, without the hooks.
+
+## Install
+
+Install the package first, then run this in the project root:
+
+```sh
+npx web-ui install skills --harness=all
+npx web-ui install hooks --harness=all
+```
+
+`--harness` picks the agent the tooling is installed for:
+
+| Value | Installs for |
+| --- | --- |
+| `claude` | Claude Code |
+| `codex` | Codex, and any agent that reads `.agents/skills/` |
+| `all` | Both |
+
+Without `--harness`, `install skills` prompts once and records the choice, and later runs reuse it. `install hooks` needs the
+skills installed for the same harness first. Leave out the second command to install only the skills.
+
+`npx web-ui --help` lists the commands, and `--help` on any subcommand lists its options.
+
+## Skills
+
+`/imf-web-ui` is the router: the entry point for UI work and library questions. It routes usage questions to the packaged user
+guides and development tasks to the matching companion skill, and it keeps small tasks small instead of loading every
+reference just because the package is installed.
+
+With the hooks installed, the agent is pointed at the router at the start of every session. Without them, the agent usually
+picks it up from the skill's description; invoke it by name when it does not.
+
+The router answers library questions from the packaged user guides and hands other tasks to a skill. Setup, audit, and UX
+work from `imf-web-ui-conventions`, a knowledge skill that holds the ImFusion frontend conventions. Solid outlines are the
+skills you run; dashed boxes are knowledge the agent reads:
+
+<ConsumerLlmFrameworkDiagram />
+
+| Skill | Use it for |
+| --- | --- |
+| `/imf-web-ui` | The router: any UI task or library question. |
+| `/imf-web-ui-components` | Component props, parts, defaults, and icons. |
+| `/imf-web-ui-ux` | Choosing components and shaping screens or flows. |
+| `/imf-web-ui-setup` | First-time wiring and approved project setup. |
+| `/imf-web-ui-audit` | A read-only check of an existing project. |
+| `/imf-web-ui-update` | Updating the package and its installed tooling. |
+
+## Hooks
+
+The hooks put the agent on the right skill at the right moment and ask it to verify the project after it edits source files:
+
+| Event | What the hook does |
+| --- | --- |
+| `SessionStart` | Points the agent at the router once per session. |
+| `SubagentStart` | Gives the same pointer to spawned agents. |
+| `UserPromptSubmit` | Names the companion skills relevant to the prompt. |
+| `Stop` | Asks for project verification after a turn edits source files. |
+
+## Keeping it current
+
+Ask the agent to update the library, for example "Update @imfusion/web-ui". That runs `/imf-web-ui-update`, which installs
+the newer package and refreshes the skills, hook scripts, and registrations to match it.
+
+To do the same by hand, update the package, then run:
+
+```sh
+npx web-ui install skills
+npx web-ui install hooks
+```
+
+Both reuse the recorded harness. Leave out the second command if the project skips hooks. Together they bring the installed
+tooling in line with the package version and remove anything the package no longer ships.
+
+## Reference
+
+### Where the files go
+
+- Skills: `.agents/skills/` for every harness. `claude` also links each skill from `.claude/skills/`.
+- Hook scripts: `.agents/hooks/imf-web-ui/`.
+- Hook registrations: `.claude/settings.json` for Claude Code, `.codex/hooks.json` for Codex.
+
+### Changing the harness
+
+Pass a different `--harness`, or `--reconfigure` to get the prompt again. Dropping `claude` removes its `.claude/skills`
+links. The next `install hooks` run removes the registrations from a harness that is no longer selected and adds them for the
+newly selected one.
+
+### What the installer owns
+
+The installer owns every skill directory named `imf-web-ui` or `imf-web-ui-*`. It overwrites and prunes those directories and
+leaves every other skill alone, so a project must not put its own skills under that prefix.
+
+Hook registrations merge into the chosen harness's file without touching unrelated entries. For each event, the installer
+adds a shipped hook unless that same script is already registered there; other hooks on that event stay alongside it.
+
+An agent reads the `agent-tooling` topic in the installed `imf-web-ui-conventions` skill before adapting a hook registration.
+
+### Codex trust
+
+Codex only runs project hooks after the project is trusted and each script is approved through `/hooks`. Revisit that review
+after a hook script changes. Claude Code has no equivalent trust gate.
+
+### Where the files come from
+
+The skills ship inside the package under `src/llms/skills/`, and `web-ui install` copies them into the project. The package
+also exposes generated component, token, and icon indexes for the lookup skill. User guides ship as readable MDX under
+`docs/user-guide/`; agents read them from the installed package without a running Storybook.
+
+<PageNav />

package/docs/user-guide/BrandAssets.mdx

@@ -0,0 +1,103 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+import faviconUrl from "#/assets/public/favicon/favicon.svg";
+import ogUrl from "#/assets/public/favicon/og-image.png";
+import { Typo } from "#/components/typo";
+
+<Meta title="User Guide/Brand Assets" />
+
+<Typo.Hero>Brand assets</Typo.Hero>
+
+The package ships the ImFusion favicon set and a social sharing image as plain files. Import them through the `assets`
+subpath:
+
+```
+@imfusion/web-ui/assets/<folder>/<file>
+```
+
+These are static files rather than components, so an application references them from its HTML head, copies them into its own
+output, or resolves them on disk during its build.
+
+## Files
+
+| File                           | Size       | Use                                                       |
+| ------------------------------ | ---------- | --------------------------------------------------------- |
+| `favicon/favicon.ico`          | 16, 32, 48 | The fallback every browser understands                    |
+| `favicon/favicon.svg`          | any        | Preferred by current browsers; stays sharp on any display |
+| `favicon/favicon-16.png`       | 16         | Explicit small PNG                                        |
+| `favicon/favicon-32.png`       | 32         | Explicit standard PNG                                     |
+| `favicon/apple-touch-icon.png` | 180        | iOS home screen                                           |
+| `favicon/icon-192.png`         | 192        | Web app manifest                                          |
+| `favicon/icon-512.png`         | 512        | Web app manifest, splash screens                          |
+| `favicon/og-image.png`         | 1200×630   | Link previews in chat and social apps                     |
+
+The mark sits on a square brand-blue tile. The white ImFusion glyph is scaled proportionally within it with a small inset at
+the sides.
+
+<div style={{ display: "flex", gap: "1.5rem", alignItems: "flex-end", margin: "1.5rem 0" }}>
+  {[16, 32, 64, 128].map(size => (
+    <div key={size} style={{ textAlign: "center" }}>
+      <img src={faviconUrl} width={size} height={size} alt="" style={{ display: "block", marginBottom: "0.5rem" }} />
+      <code style={{ fontSize: "0.75rem" }}>{size}</code>
+    </div>
+  ))}
+</div>
+
+<img src={ogUrl} alt="" width="480" style={{ display: "block", borderRadius: "0.5rem", margin: "1.5rem 0" }} />
+
+## Use the files
+
+Pick the method that matches how the application builds:
+
+| Method | Use it when | Public URLs |
+| --- | --- | --- |
+| [Vite plugin](#vite-plugin) | The application builds with Vite | Stable root paths such as `/favicon.ico` |
+| [Copy step](#copy-step) | Another build system, or a static directory served as is | Whatever the copy target gives them |
+| [Direct import](#direct-import) | One file used from application code, such as a manifest or an `<img>` | Hashed by the bundler |
+
+### Vite plugin
+
+Register the plugin, then reference the stable root URLs from the document head:
+
+```ts
+import { defineConfig } from "vite";
+import { imfusionBrandAssets } from "@imfusion/web-ui/vite";
+
+export default defineConfig({
+  plugins: [imfusionBrandAssets()]
+});
+```
+
+```html
+<link rel="icon" href="/favicon.ico" sizes="48x48" />
+<link rel="icon" href="/favicon.svg" type="image/svg+xml" />
+<link rel="apple-touch-icon" href="/apple-touch-icon.png" />
+<meta property="og:image" content="https://example.com/og-image.png" />
+```
+
+The plugin serves the complete favicon set during development and emits it at the root of the build output. Give `og:image`
+an absolute URL. Chat and social applications fetch it from their own servers, so a relative path does not resolve.
+
+### Copy step
+
+Copy the files into the application's static-files directory during its build, then reference them from its HTML the same way
+as above. Resolve the package path rather than hard-coding a path into `node_modules`:
+
+```ts
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const faviconDir = dirname(fileURLToPath(import.meta.resolve("@imfusion/web-ui/assets/favicon/favicon.svg")));
+```
+
+### Direct import
+
+A bundler can also take one file directly:
+
+```ts
+import iconUrl from "@imfusion/web-ui/assets/favicon/icon-512.png";
+```
+
+The bundler returns the asset's URL for use in application code. Vite also processes `index.html` and rewrites supported
+asset references there. Use the plugin or the copy step when the files need stable public filenames.
+
+<PageNav />

package/docs/user-guide/Changelog.mdx

@@ -0,0 +1,26 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+import { MarkdownDoc } from "#/storybook/docs/markdown-doc";
+import { DocParagraph } from "#/storybook/docs/screenshot-carousel/doc-paragraph";
+import { Separator } from "#/components/separator";
+import { Typo } from "#/components/typo";
+
+import doc from "../../CHANGELOG.md?raw";
+
+<Meta title="User Guide/Changelog" />
+
+<MarkdownDoc sourcePath="CHANGELOG.md" 
+  components={{
+    h1: <Typo.Hero />,
+    h2: <Typo.H1 />,
+    h3: <Typo.H2 />,
+    h4: <Typo.H3 variant="primary" />,
+    p: <DocParagraph variant="primary" />,
+    ul: <Typo.UnorderedList variant="primary" />,
+    hr: <Separator spacing="spacious" variant="dashed" />
+  }}
+>
+  {doc}
+</MarkdownDoc>
+
+<PageNav />