@imfusion/web-ui 0.5.1-dev.19.g11b806f9 → 0.5.1-dev.2.gf11bbed1

package/bin/install.test.ts

@@ -1,139 +0,0 @@
-import { beforeEach, describe, expect, it } from "vitest";
-import { spawnSync } from "node:child_process";
-import { existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const installer = resolve(fileURLToPath(new URL(".", import.meta.url)), "install.js");
-
-function runInstall(cwd: string, ...args: string[]) {
-  const result = spawnSync("node", [installer, ...args], { cwd, encoding: "utf-8" });
-  expect(result.status).toBe(0);
-  return result;
-}
-
-function readSettings(cwd: string) {
-  return JSON.parse(readFileSync(join(cwd, ".claude", "settings.json"), "utf-8")) as {
-    permissions?: { allow: string[] };
-    hooks: Record<string, { hooks: { command: string }[] }[]>;
-  };
-}
-
-let consumer: string;
-
-beforeEach(() => {
-  consumer = mkdtempSync(join(tmpdir(), "web-ui-install-"));
-});
-
-describe("web-ui-install", () => {
-  it("installs skills into both targets with version markers", () => {
-    runInstall(consumer, "--skills", "--target", "agents", "--target", "claude");
-
-    const installed = readdirSync(join(consumer, ".agents", "skills"));
-    expect(installed).toContain("imf-web-ui");
-    expect(installed).toContain("imf-web-ui-frontend-conventions");
-    expect(installed).toContain("imf-web-ui-frontend-setup");
-
-    for (const name of installed) {
-      expect(existsSync(join(consumer, ".agents", "skills", name, ".imf-web-ui-skill-version.json"))).toBe(true);
-      expect(lstatSync(join(consumer, ".claude", "skills", name)).isSymbolicLink()).toBe(true);
-    }
-  });
-
-  it("installs hooks into an installer-owned directory and registers them", () => {
-    runInstall(consumer, "--hooks");
-
-    const hookDir = join(consumer, ".agents", "hooks", "imf-web-ui");
-    const scripts = readdirSync(hookDir);
-    expect(scripts).toEqual(expect.arrayContaining(["session-start.sh", "user-prompt-submit.sh", "post-tool-use.sh"]));
-    for (const script of scripts) {
-      expect(statSync(join(hookDir, script)).mode & 0o100).toBeTruthy();
-    }
-
-    const settings = readSettings(consumer);
-    expect(Object.keys(settings.hooks)).toEqual(expect.arrayContaining(["SessionStart", "UserPromptSubmit", "PostToolUse"]));
-    // --hooks alone installs no skills
-    expect(existsSync(join(consumer, ".agents", "skills"))).toBe(false);
-  });
-
-  it("merges registrations without clobbering existing settings, idempotently", () => {
-    mkdirSync(join(consumer, ".claude"), { recursive: true });
-    writeFileSync(
-      join(consumer, ".claude", "settings.json"),
-      JSON.stringify({
-        permissions: { allow: ["Bash(git *)"] },
-        hooks: { PostToolUse: [{ matcher: "Edit", hooks: [{ type: "command", command: "echo existing" }] }] }
-      })
-    );
-
-    runInstall(consumer, "--hooks");
-    runInstall(consumer, "--hooks");
-
-    const settings = readSettings(consumer);
-    expect(settings.permissions?.allow).toEqual(["Bash(git *)"]);
-    const commands = settings.hooks.PostToolUse.flatMap(entry => entry.hooks.map(hook => hook.command));
-    expect(commands).toContain("echo existing");
-    // the shipped registration is added exactly once across both runs
-    expect(commands.filter(command => command.includes("post-tool-use.sh"))).toHaveLength(1);
-  });
-
-  it("upserts the fenced AGENTS.md block and leaves the rest untouched", () => {
-    const agentsPath = join(consumer, "AGENTS.md");
-    writeFileSync(
-      agentsPath,
-      "# AGENTS.md\n\nRepo-specific intro.\n\n<!-- imf-web-ui:begin stale -->\nold content\n<!-- imf-web-ui:end -->\n\nRepo-specific outro.\n"
-    );
-
-    runInstall(consumer, "--skills", "--target", "agents");
-    const updated = readFileSync(agentsPath, "utf-8");
-    expect(updated).toContain("Repo-specific intro.");
-    expect(updated).toContain("Repo-specific outro.");
-    expect(updated).not.toContain("old content");
-    expect(updated).toContain("resynced with `npx web-ui-install`");
-
-    // no fence yet → block is appended; missing AGENTS.md entirely → left alone
-    writeFileSync(agentsPath, "# AGENTS.md\n\nNo fence here.\n");
-    runInstall(consumer, "--skills", "--target", "agents");
-    const appended = readFileSync(agentsPath, "utf-8");
-    expect(appended).toContain("No fence here.");
-    expect(appended).toContain("<!-- imf-web-ui:begin");
-  });
-
-  it("ships hooks that stay advisory: exit 0 with and without a usable payload", () => {
-    runInstall(consumer, "--hooks");
-    const hookDir = join(consumer, ".agents", "hooks", "imf-web-ui");
-
-    const noFile = spawnSync("sh", [join(hookDir, "post-tool-use.sh")], { input: "{}", encoding: "utf-8" });
-    expect(noFile.status).toBe(0);
-
-    const missingFile = spawnSync("sh", [join(hookDir, "post-tool-use.sh")], {
-      input: JSON.stringify({ tool_input: { file_path: join(consumer, "nope.ts") } }),
-      encoding: "utf-8"
-    });
-    expect(missingFile.status).toBe(0);
-
-    const sessionStart = spawnSync("sh", [join(hookDir, "session-start.sh")], { encoding: "utf-8" });
-    expect(sessionStart.status).toBe(0);
-    expect(sessionStart.stdout).toContain("imf-web-ui-frontend-conventions");
-
-    // no node_modules in the consumer → silent success
-    const staleness = spawnSync("sh", [join(hookDir, "baseline-staleness.sh")], { cwd: consumer, encoding: "utf-8" });
-    expect(staleness.status).toBe(0);
-    expect(staleness.stdout).toBe("");
-  });
-
-  it("warns from the staleness script when skill markers lag the package", () => {
-    runInstall(consumer, "--skills", "--hooks", "--target", "agents");
-    const pkgDir = join(consumer, "node_modules", "@imfusion", "web-ui");
-    mkdirSync(pkgDir, { recursive: true });
-    writeFileSync(join(pkgDir, "package.json"), JSON.stringify({ version: "99.0.0" }));
-
-    const result = spawnSync("sh", [join(consumer, ".agents", "hooks", "imf-web-ui", "baseline-staleness.sh")], {
-      cwd: consumer,
-      encoding: "utf-8"
-    });
-    expect(result.status).toBe(0);
-    expect(result.stdout).toContain("npx web-ui-install");
-  });
-});

package/dist/build/vite-css-module-names/index.d.ts

@@ -1,20 +0,0 @@
-import { Plugin } from 'vite';
-export interface ReadableCssModuleNamesOptions {
-    /** Namespace for every generated class name. Short, stable, app-scoped (`imf-ui`, `acme`). */
-    prefix: string;
-}
-/**
- * Generates readable CSS Module class names instead of the default hash, so the DOM
- * stays legible in devtools and browser automation. `button.module.css` yields
- * `{prefix}-button-module-root` — `[name]` is the filename, which keeps its `.module`
- * suffix.
- *
- * Register it in every tool that compiles the CSS (the app build AND Storybook). A
- * compiler left out generates different class names for the same source file and its
- * styles silently don't apply.
- *
- * Defaults to opting into Lightning CSS, which drops `css.modules` options it has no
- * equivalent for (`localsConvention`). Set `css.transformer: "postcss"` to stay on
- * the PostCSS pipeline.
- */
-export declare function readableCssModuleNames({ prefix }: ReadableCssModuleNamesOptions): Plugin;

package/dist/build/vite-css-module-names.js

@@ -1,17 +0,0 @@
-//#region src/build/vite-css-module-names/index.ts
-function e(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 t({ prefix: t }) {
-	let n = `${t}-[name]-[local]`;
-	return {
-		name: "imf-ui:readable-css-module-names",
-		config: (t) => e(t, n)
-	};
-}
-//#endregion
-export { t as readableCssModuleNames };

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

@@ -1,71 +0,0 @@
----
-name: imf-web-ui-agent-setup
-description:
-  "Install or update the LLM/agent tooling @imfusion/web-ui ships in a consumer repo: the vendored imf-web-ui-* skills, the
-  AGENTS.md fence, the agent lifecycle hooks, and the staleness wiring. Also covers reaching the Agent Skills a dependency
-  ships — TanStack Intent (@tanstack/intent) and its allowlist. Wraps npx web-ui-install and adds the judgment the binary
-  can't have — reading what the repo already registers before adding anything. Load when setting up agent tooling in a
-  consumer app, when skills are stale, when hooks should be installed or adapted, or when asked to set up TanStack Intent or
-  dependency-shipped Agent Skills. Not for project tooling (imf-web-ui-frontend-setup) or library wiring
-  (imf-web-ui-library-setup)."
----
-
-# imf-web-ui-agent-setup
-
-Sets up or updates the agent side of a consumer repo. The binary does the mechanics; this skill does the judgment.
-
-## Skills
-
-`npx web-ui-install` installs or refreshes the vendored `imf-web-ui-*` skills (interactive target choice on first run,
-remembered after; `--reconfigure` re-opens it). It also refreshes the `<!-- imf-web-ui:begin/end -->` fence in an existing
-`AGENTS.md`. Stale check: `.imf-web-ui-skill-version.json` in each installed skill vs. the installed package version — older
-marker means re-run the binary, never hand-diff skill contents.
-
-## Hooks
-
-Three agent lifecycle hooks ship as templates in [`templates/hooks/`](templates/hooks/), registration in
-[`templates/settings.json`](templates/settings.json):
-
-- **SessionStart** — once per session: the conventions baseline is vendored, load it before writing.
-- **UserPromptSubmit** — a one-line conventions reminder per prompt. Per-prompt, not per-tool-call: a PreToolUse reminder
-  would re-inject the same text on every edit.
-- **PostToolUse** (advisory) — file-scope checks on the touched file after every Edit/Write, failures fed straight back.
-  Never exits non-zero.
-- **`baseline-staleness.sh`** — not registered as an agent hook; the repo's pre-commit calls it
-  ([`git.md`](../imf-web-ui-frontend-conventions/references/git.md), Staleness at commit time).
-
-**Read `.claude/settings.json` before installing.** Then pick per event:
-
-- **Nothing registered** → install as shipped: `npx web-ui-install --hooks` copies the scripts to `.agents/hooks/imf-web-ui/`
-  (installer-owned, refreshed wholesale) and merges the registrations without touching existing entries.
-- **The repo already covers an event** (its own session reminder, its own post-edit verify) → don't stack a second hook on
-  it. Use the template as a starting point instead: fold the missing behaviour into the repo's existing script, or adapt the
-  template and register that. Surface the situation and let the human pick.
-
-## Dependency-shipped skills
-
-Some libraries ship Agent Skills inside their npm package; TanStack does across much of the suite.
-[TanStack Intent](https://github.com/TanStack/intent) (`@tanstack/intent`) is the CLI that surfaces them — an agent holding a
-dependency but not its guidance writes plausible code against a half-remembered API.
-
-Setting it up is the project's own call, not something web-ui does on its behalf. Point it out:
-
-> This project has TanStack dependencies that ship their own Agent Skills. `@tanstack/intent` can make them reachable — worth
-> a look if you want your agent working from the library's own guidance.
-
-Intent offers two things: a fenced instructions block in `AGENTS.md`, and a `PreToolUse` hook that blocks an edit until a
-matching skill has been read. The house preference is both — the block alone is advice an agent can walk past. The hook
-refuses every edit while no matching skill is loadable, so a project adopting it wants the current docs open; that sequencing
-belongs to whoever runs it.
-
-**Allowlist the whole scope.** `intent.skills` takes `@tanstack/*`. Per-package entries like `@tanstack/react-query` look
-more precise and silently reach almost nothing, because the skills ship from packages the app never names directly. Exclude
-`@tanstack/devtools-event-client` — it publishes skills that are noise in an app repo.
-
-Read Intent's own docs before wiring it; it is young and moves. Whatever the project decides, guidance you didn't read is not
-guidance you have: use `npx @tanstack/cli` for TanStack docs, and never guess at a skill name.
-
-## Not this skill
-
-- Project tooling, docs structure, the audit checklist → `imf-web-ui-frontend-setup` (which delegates agent tooling here)
-- Library wiring (styles import, provider) → `imf-web-ui-library-setup`

package/src/llms/skills/imf-web-ui-agent-setup/templates/hooks/baseline-staleness.sh

@@ -1,17 +0,0 @@
-#!/usr/bin/env sh
-# Advisory baseline-staleness check, meant to be called from the repo's pre-commit hook.
-# Compares the installed imf-web-ui skill markers against the installed package version
-# and warns on drift. Always exits 0 — staleness never blocks a commit.
-PKG=node_modules/@imfusion/web-ui/package.json
-[ -f "$PKG" ] || exit 0
-CURRENT=$(node -p "require('./$PKG').version" 2>/dev/null) || exit 0
-
-for marker in .agents/skills/imf-web-ui-*/.imf-web-ui-skill-version.json; do
-  [ -f "$marker" ] || continue
-  INSTALLED=$(node -p "require('./$marker').version" 2>/dev/null) || continue
-  if [ "$INSTALLED" != "$CURRENT" ]; then
-    echo "imf-web-ui skills are stale ($INSTALLED installed, package is $CURRENT) — run: npx web-ui-install"
-    break
-  fi
-done
-exit 0

package/src/llms/skills/imf-web-ui-agent-setup/templates/hooks/post-tool-use.sh

@@ -1,21 +0,0 @@
-#!/usr/bin/env sh
-# PostToolUse (Edit|Write): advisory file-scope checks on the touched file. Never exits
-# non-zero, so a mid-flight refactor can't trap the agent. Resolve the repo from the edited
-# file, not cwd, which is not guaranteed for hooks.
-FILE=$(jq -r '.tool_input.file_path // empty' 2>/dev/null)
-[ -f "$FILE" ] || exit 0
-
-ROOT=$(cd "$(dirname "$FILE")" && git rev-parse --show-toplevel 2>/dev/null) || exit 0
-cd "$ROOT" || exit 0
-
-case "$FILE" in
-  *.ts | *.tsx | *.js | *.jsx)
-    [ -x ./node_modules/.bin/eslint ] && ./node_modules/.bin/eslint --cache "$FILE" 2>&1
-    ;;
-esac
-case "$FILE" in
-  *.ts | *.tsx | *.js | *.jsx | *.css | *.json | *.md)
-    [ -x ./node_modules/.bin/prettier ] && ./node_modules/.bin/prettier --check "$FILE" 2>&1
-    ;;
-esac
-exit 0

package/src/llms/skills/imf-web-ui-agent-setup/templates/hooks/session-start.sh

@@ -1,4 +0,0 @@
-#!/usr/bin/env sh
-# SessionStart: point the agent at the vendored conventions baseline once per session.
-echo "The ImFusion frontend conventions baseline is vendored in .agents/skills/ (imf-web-ui-frontend-conventions and siblings). Load the relevant skill before writing code, styles, or docs; repo docs in docs/ carry only what is unique to this repo."
-exit 0

package/src/llms/skills/imf-web-ui-agent-setup/templates/hooks/user-prompt-submit.sh

@@ -1,4 +0,0 @@
-#!/usr/bin/env sh
-# UserPromptSubmit: one-line conventions reminder per prompt.
-echo "Conventions check: if this task touches code, styles, data fetching, or docs, consult the matching imf-web-ui-* skill in .agents/skills/ before acting."
-exit 0

package/src/llms/skills/imf-web-ui-agent-setup/templates/settings.json

@@ -1,37 +0,0 @@
-{
-  "$schema": "https://json.schemastore.org/claude-code-settings.json",
-  "hooks": {
-    "SessionStart": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.agents/hooks/imf-web-ui/session-start.sh\""
-          }
-        ]
-      }
-    ],
-    "UserPromptSubmit": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.agents/hooks/imf-web-ui/user-prompt-submit.sh\""
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "Edit|MultiEdit|Write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR/.agents/hooks/imf-web-ui/post-tool-use.sh\"",
-            "statusMessage": "Verifying file"
-          }
-        ]
-      }
-    ]
-  }
-}

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

@@ -1,45 +0,0 @@
----
-name: imf-web-ui-frontend-conventions
-description:
-  "The ImFusion frontend conventions baseline — in-house conventions, valid in every ImFusion frontend and usable by anyone
-  who likes them. A router over topic references: library boundary, React, components, TypeScript, styling, data layer,
-  project structure, testing, stack, npm project, tooling config, git, assets, docs structure. Load when writing wrapper
-  components, custom UI, styling beyond the defaults, adding new files to a consumer app, writing repo docs, touching tool
-  config, or choosing any dependency."
----
-
-# imf-web-ui-frontend-conventions
-
-The ImFusion frontend baseline. In-house conventions, not industry claims — they encode how ImFusion frontends are built, and
-anyone else is welcome to them.
-
-**The project wins.** These defaults fill vacuums: if the host project already has a convention — a styling system, a state
-library, a folder shape — that stands. They are not a license to refactor a consumer codebase toward this document.
-
-**Alignment mode.** The exception is intent: when the user asks to _align_ the repo with the baseline ("align", "alignment"
-is the flag), the project-wins guard lifts. Deviations then become migration findings — proposed as a plan, still nothing
-changed until the human approves.
-
-## The references
-
-Each topic lives in one reference. Read the one whose moment you're in; starting a new feature usually wants several.
-
-| Reference                                               | Covers                                                              | Read when                                               |
-| ------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------- |
-| [library-boundary.md](references/library-boundary.md)   | staying behind `@imfusion/web-ui`, wrappers, type derivation, peers | touching anything that renders library components       |
-| [react.md](references/react.md)                         | component roles, state kinds and owners, effects discipline         | writing new screens, components, or wrappers            |
-| [components.md](references/components.md)               | component anatomy on disk: grouping, folders, colocation            | adding a component file                                 |
-| [typescript.md](references/typescript.md)               | functional style, types, naming                                     | writing any code                                        |
-| [styling.md](references/styling.md)                     | native CSS Modules, tokens, the override contract                   | writing CSS or styling beyond the defaults              |
-| [class-names.md](references/class-names.md)             | CVA variants, `cx`, merging the incoming `className`                | writing a component with variants or a `className` prop |
-| [data.md](references/data.md)                           | `api/`+`http/` shape, Zod boundary, query/mutation patterns         | adding an API topic, a fetch, or a mutation             |
-| [project-structure.md](references/project-structure.md) | the `src/` tree, file naming, imports                               | adding files rather than editing existing ones          |
-| [testing.md](references/testing.md)                     | what's worth testing and what isn't                                 | writing or reviewing tests                              |
-| [stack.md](references/stack.md)                         | the topic→tool map, when a library owns a layer                     | choosing or adding any dependency                       |
-| [npm-project.md](references/npm-project.md)             | `package.json`, the `verify:*` script set, dependency pinning       | running or adding a script, adding a dependency         |
-| [tooling.md](references/tooling.md)                     | Prettier, ESLint, tsconfig, staged files, CSS class names           | touching tool config                                    |
-| [git.md](references/git.md)                             | `git:config`, verify scopes, staleness at commit time               | wiring hooks or the commit path                         |
-| [assets.md](references/assets.md)                       | image formats, the WebP recipe                                      | adding images or other static assets                    |
-| [docs-structure.md](references/docs-structure.md)       | what a repo documents, where, how it's written                      | writing or restructuring repo docs                      |
-
-`imf-web-ui-frontend-setup` bootstraps and audits a repo against this baseline.

package/src/llms/skills/imf-web-ui-frontend-conventions/references/assets.md

@@ -1,23 +0,0 @@
-# Assets
-
-Import everything from `src/assets/` so the bundler fingerprints and bundles it. Never reference an image by public-path
-string.
-
-## Photographs — WebP
-
-```bash
-magick source.png -resize 2000x -quality 80 -define webp:method=6 src/assets/name.webp
-```
-
-- Quality 80 is visually lossless on photos and routinely cuts file size by an order of magnitude.
-- `method=6` is the densest encoding. It's a one-off cost at conversion time, so take the smaller file.
-- Cap the long edge at 2000px — nothing on the market resolves more in a content image.
-- No `<picture>` fallback needed; WebP is supported everywhere since 2020.
-
-## Other formats
-
-- **Alpha, or pixels that must stay exact** → PNG, optimized with `oxipng` or `pngquant`.
-- **Icons, logos, line art** → inline SVG component, so it inherits `currentColor` and follows the theme.
-
-These rules apply to assets as they're added or touched. Existing assets in another format are not findings to sweep —
-convert opportunistically, when you're working on them anyway.

package/src/llms/skills/imf-web-ui-frontend-conventions/references/class-names.md

@@ -1,42 +0,0 @@
-# Class names in components
-
-How a component turns props into a `className` string. What the build does with the result is [tooling.md](tooling.md); what
-goes in the stylesheet is [styling.md](styling.md).
-
-**CVA is the only tool.** `class-variance-authority` maps variant props to CSS Module classes. No `clsx`, no
-`tailwind-merge`, no local `cn()` helper. `cx` is CVA's own concatenator and `@imfusion/web-ui` re-exports it, so it comes
-from the library alongside the components.
-
-```tsx
-import { cva } from "class-variance-authority";
-import classes from "./chip.module.css";
-
-const chip = cva(classes.root, {
-  variants: {
-    appearance: { outline: classes.appearanceOutline, solid: classes.appearanceSolid },
-    inline: { false: null, true: classes.inline }
-  }
-});
-
-export function Chip({ appearance = "outline", inline = false, className, ...props }: Props) {
-  return <span {...props} className={chip({ appearance, inline, className })} />;
-}
-```
-
-- **Base class is CVA's first argument**, variant values are CSS Module references, never string literals. A boolean axis
-  uses `null` for its off-state.
-- **The incoming `className` goes into CVA's `className` slot**, which appends it last so a caller's class always wins. With
-  no variants to map, `cx(classes.inline, className)` does the same job.
-- **Every component that accepts `className` merges it.** A component whose surface is deliberately closed omits the prop
-  entirely rather than accepting and ignoring it.
-- **Defaults live in the props destructuring, not CVA's `defaultVariants`.** react-docgen-typescript reads the destructuring,
-  so defaults declared in CVA don't reach the generated docs.
-- **Resolve a function-form `className` before merging.** Components built on a library that passes render state
-  (`className={state => …}`) receive either shape:
-
-  ```tsx
-  className={state => cx(classes.root, typeof className === "function" ? className(state) : className)}
-  ```
-
-- **Two components sharing one visual share one CVA module**, a `{name}.cva.ts` next to them, so their variant axes can't
-  drift apart.

package/src/llms/skills/imf-web-ui-frontend-conventions/references/components.md

@@ -1,63 +0,0 @@
-# Components
-
-How a component lives on disk and how dumb it stays. Roles, state, and effects in full are [react.md](react.md); styling is
-[styling.md](styling.md).
-
-## As dumb as possible
-
-Data comes from outside — props-fed, never self-fetching. Presentational logic (formatting a label, deriving a display state)
-is fine; owning data is not:
-
-```tsx
-// components/user-card/user-card.tsx
-interface Props {
-  name: string;
-  role: string;
-  onEdit: () => void;
-}
-
-export function UserCard({ name, role, onEdit }: Props) {
-  return (
-    <Card.Root>
-      <Card.Content>
-        <Typo>{name}</Typo>
-        <Chip>{role}</Chip>
-      </Card.Content>
-      <Card.Footer>
-        <Button onClick={onEdit}>Edit</Button>
-      </Card.Footer>
-    </Card.Root>
-  );
-}
-```
-
-No query hook, no store access, no route awareness — the component renders what it's given and reports events upward. Local
-UI state (`isOpen`, a draft value) is allowed; anything whose truth lives elsewhere is not ([react.md](react.md)).
-
-## Grouping
-
-`components/` groups by kind — a layout component under `layouts/`, not beside a domain widget. Flat is fine while there are
-few; let the grouping follow what the project actually has rather than imposing it up front. The kinds worth separating are
-the component roles in [react.md](react.md).
-
-## One file or a folder
-
-A component gets a folder once it has more than one file — sub-components, styles, tests — with an `index.ts` that only
-re-exports:
-
-```
-components/data-table/
-  data-table.tsx
-  data-table-row.tsx
-  data-table.module.css
-  index.ts
-```
-
-Imports then read `#/components/data-table` and the inside can be restructured without touching call sites. Single-file
-components stay single files, directly in their group.
-
-## Colocation
-
-The stylesheet is colocated as `<component>.module.css` next to the component, and only dumb components have one — a
-container that wants CSS is asking for a layout component instead ([react.md](react.md)). Tests and local types sit next to
-their subject too. A file you have to hunt for in a parallel tree gets edited less carefully.