@hirobius/design-system 0.19.0 → 0.20.0

package/CONSUMING.md

@@ -43,7 +43,7 @@ Available subpaths:
 
 | Import                               | What                                                                                                                                                                                                                                        |
 | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@hirobius/design-system`            | All components (primitives, patterns, templates)                                                                                                                                                                                            |
+| `@hirobius/design-system`            | The core components and templates (the `pattern` tier is only in `/patterns`)                                                                                                                                                               |
 | `@hirobius/design-system/tokens.css` | Token CSS variables (import once at app root)                                                                                                                                                                                               |
 | `@hirobius/design-system/tokens`     | Token values as TS constants                                                                                                                                                                                                                |
 | `@hirobius/design-system/cn`         | `cn()` class-merge helper                                                                                                                                                                                                                   |
@@ -51,8 +51,8 @@ Available subpaths:
 | `@hirobius/design-system/contexts`   | Theme / language / tenant / font providers                                                                                                                                                                                                  |
 | `@hirobius/design-system/brand`      | Palette → HDS-semantic overlay bridge (static / SSR / Astro; see [`docs/CONSUMING.md` §12](docs/CONSUMING.md#12-static-astro-sites--the-brand-overlay-bridge))                                                                              |
 | `@hirobius/design-system/scroll`     | Opt-in scroll-motion primitives — `SmoothScroll` (Lenis), `useScrollProgress` (Motion). Requires the optional peer `lenis`. See [`docs/CONSUMING.md` §13](docs/CONSUMING.md#13-scroll-motion-the-scroll-subpath)                            |
-| `@hirobius/design-system/patterns`   | The 22 `pattern`-tier components (nav shells, feeds, rails, pickers — see hds#254). Also still re-exported from the root for one minor (`@deprecated`, removed at the next major) — prefer this subpath in new code.                        |
-| `@hirobius/design-system/icons`      | Curated Lucide icon set for `IconButton` / `Icon` (`Ellipsis`, `Pencil`, `Trash2`, `X`, …). Names listed in the manifest `iconSet`.                                                                                                         |
+| `@hirobius/design-system/patterns`   | The `pattern`-tier components (nav shells, feeds, rails, pickers — see hds#254). The only entry that exports them: 0.20.0 removed their root re-exports (the `hds-patterns-subpath` codemod, see MIGRATIONS.md).                            |
+| `@hirobius/design-system/icons`      | Curated Lucide icon set for `Icon`, and so for `Button iconOnly` (`Ellipsis`, `Pencil`, `Trash2`, `X`, …). Names listed in the manifest `iconSet`.                                                                                          |
 | `@hirobius/design-system/static.css` | CSS-only static-primitive layer — `.hds-badge`/`.hds-card`/`.hds-alert`/`.hds-divider`/`.hds-tag` classes, no React. See [`docs/CONSUMING.md` §14](docs/CONSUMING.md#14-css-only-static-primitives--badgecardalertdividertag-with-no-react) |
 
 The package is **ESM-only**, so consume it with a modern bundler (Vite, Next.js,
@@ -113,8 +113,11 @@ Releases follow [semver](https://semver.org/) and are tracked in
 pnpm update @hirobius/design-system   # latest within your version range
 ```
 
-For a major (breaking) release, bump the version explicitly and review the
-CHANGELOG entry. Token or export changes are released as majors.
+For a breaking release, bump the version explicitly and review the CHANGELOG
+entry. Before 1.0 a breaking change (a removed export or token) ships in a 0.x
+minor, which a caret range such as `^0.19` never picks up; from 1.0 on it ships
+in a major. Each removal is listed in [MIGRATIONS.md](MIGRATIONS.md) with its
+replacement and, where one applies, a codemod (ADR-014).
 
 ---
 
@@ -122,7 +125,7 @@ CHANGELOG entry. Token or export changes are released as majors.
 
 ```bash
 pnpm changeset add        # record a patch/minor/major bump + notes
-pnpm changeset:version    # apply bumps + regenerate CHANGELOG.md
+pnpm changeset:version    # apply bumps + regenerate CHANGELOG.md + refresh docs/api/api-baseline.json
 # commit + push to main → the Release workflow publishes to public npm
 ```
 

package/DESIGN.md

@@ -90,7 +90,7 @@ Depth is communicated through 4 elevation roles bundled by `semantic.elevation.*
 
 Cards default to `flat`. They lift to `raised` only on interactive hover or when explicitly elevated above siblings. Never combine `raised` with a border — depth is one mechanism (border OR shadow), not both stacked.
 
-Overlays (Dialog, AlertDialog, Menu, ContextMenu, Popover, Select, HoverCard, Tooltip) portal into the nearest `data-hds` scope, so they inherit its theme (for example `<div data-hds data-theme="dark">`); pass `container` on the Content part to override.
+Overlays (Dialog, AlertDialog, Menu, Popover, Select, Tooltip) portal into the nearest `data-hds` scope, so they inherit its theme (for example `<div data-hds data-theme="dark">`); pass `container` on the Content part to override.
 
 ## Motion
 
@@ -121,7 +121,7 @@ Default most interactive feedback to `productive` (150ms, decelerate). Reserve `
 
 | Token | Value | Purpose |
 | --- | --- | --- |
-| `semantic.motion.distance` | `24px` | Travel distance for a scroll-reveal translateY offset. Coincides in value with semantic.space.scale.md today, but names a motion travel distance rather than a spacing tier (hds#242). |
+| `semantic.motion.distance` | `24px` | Scroll-reveal translateY travel distance. Equals semantic.space.scale.md today, but names motion travel, not a spacing tier (hds#242). |
 <!-- auto:end:motion -->
 
 ## Components
@@ -129,7 +129,7 @@ Default most interactive feedback to `productive` (150ms, decelerate). Reserve `
 <!-- auto:start:components -->
 | Component | Radius | States | Guidance |
 | --- | --- | --- | --- |
-| **Buttons** (`Button`) | `8px` (`semantic.radius.action`) | default · hover · focus · active · disabled · loading | Three variants: primary (accent-filled), secondary (outline), tertiary (ghost). Primary uses `semantic.accent.*` ramp per state. Icon buttons (`IconButton`) follow the same token surface. Icon-only actions use `IconButton` with an icon from `@hirobius/design-system/icons`. |
+| **Buttons** (`Button`) | `8px` (`semantic.radius.action`) | default · hover · focus · active · disabled · loading | Three variants: primary (accent-filled), secondary (outline), tertiary (ghost). Primary uses `semantic.accent.*` ramp per state. Pressed is a 5% `semantic.color.state.pressed.overlay` wash over the fill (`role.pressed-overlay`: black in light, white in dark), not a brightness filter. Icon-only buttons (`iconOnly`) follow the same token surface. Icon-only actions use `Button iconOnly` with a `label` and an `Icon` from `@hirobius/design-system/icons` in `iconLeft`. |
 | **Inputs** (`Input`) | `8px` (`semantic.radius.action`) | default · focus · filled · error · disabled · loading | Border-driven treatment; no filled background by default. Focus uses `semantic.color.border.accent` plus a 2px outline offset. Error swaps to `component.input.borderError`. |
 | **Cards** (`Card`) | `12px` (`rounded-lg`, role radius + 4px) | default · hover (optional parallax) · pressed (when interactive) | Cards default to `elevation.flat` (1px border `border.subtle`, no shadow). Interactive cards lift to `elevation.raised` (shadow.subtle, no border) on hover. Bind via `semantic.elevation.{role}` — never raw box-shadow values. Radius: `rounded-lg` (role radius + 4 px, follows the tenant knob) — never a hard-coded value. Padding: `var(--semantic-space-surface-padding)`. Title: `heading3`. Meta: `caption` + `var(--semantic-color-content-secondary)`. Hover (interactive): `scale(1.02)` transform + lift to raised. Never: gradients, glow, frosted glass, tinted surfaces, decorative overlays, or inner shadows. |
 | **Badges** (`Badge`) | `8px` (`primitive.radius.4`) | neutral · accent · feedback (error/success/warning/info) | Single-line status markers. Feedback colors come from `semantic.color.feedback.*`. Never used as decorative chrome. |
@@ -176,11 +176,13 @@ Pick by what the thing is. The first four rows are for a headline number or a st
 | `Stat`               | An inline number inside prose or a dense list.                                | `MetricTiles` when the number stands alone in a row of its own.              |
 | `Card.Metric`        | A metric inside an existing `Card` only.                                      | `MetricTiles` when there is no enclosing `Card`.                             |
 | `StatusTile`         | State with notes and a trailing badge, never a number.                        | `MetricTiles` when the tile is a number; `StatusTile` never carries a value. |
-| `Card`               | A titled or interactive content object (header, body, footer, or selectable). | `Surface` when there is no title and nothing to press.                       |
+| `Card`               | A titled or interactive content object (header, body, footer, `selectable`).  | `Surface` when there is no title and nothing to press.                       |
 | `Surface`            | A plain padded background around content that has no header of its own.       | `Card` when the content is titled or interactive.                            |
 | `DestructiveSection` | The one irreversible action on a screen, with an explanation and a confirm.   | `FormActions` `destructive` slot for a delete beside a form's own buttons.   |
 | `DataTableSection`   | A titled table with a toolbar, row actions and an empty state.                | `Table` alone when there is no heading, toolbar or empty state to show.      |
 
+Three more needs are props on an existing component, not components of their own. A card people pick from a set is a `Card` with `selectable`, `selected` and `onSelectedChange`, announced as a checkbox. A wrapping row of equal tiles that are not headline numbers is a `Grid` with `layout="auto-fill"` and `minItemWidth`. A state shown only as a colored marker, with no notes, is a `Badge` with `dot` and a `label` that names the state.
+
 `Card` and `Surface` share one container radius, `rounded-lg` (`role.radius` + 4 px: 12 px by default, 4 px under `brutalist-demo`). Dialogs and alert dialogs use it too. Never read `--component-card-radius` for a container; it ignores the tenant.
 
 `MetricTiles` has `min(tiles, 4)` columns, so a row never leaves an empty column, and every tile has one fixed min-height with the value in `heading2`, the label as an eyebrow and the sub line in `caption`. Its tone comes from the fixed feedback vocabulary: `neutral | success | warning | danger | info`.
@@ -215,6 +217,6 @@ Unresolved rules that the live repo cannot yet answer confidently are tracked in
 <!-- auto:start:build-meta -->
 ---
 
-> Generated from `hirobius.tokens.json` (381 tokens) and `public/hds-manifest.json` by `scripts/build-design-md.mjs`.
+> Generated from `hirobius.tokens.json` (385 tokens) and `public/hds-manifest.json` by `scripts/build-design-md.mjs`.
 > Hand-edit `DESIGN.source.md`; this file (`DESIGN.md`) is overwritten by `pnpm tokens`.
 <!-- auto:end:build-meta -->

package/README.md

@@ -12,9 +12,9 @@ pnpm add @hirobius/design-system
 
 <!-- auto:start:front-door-counts -->
 
-- **109** public component modules, exported from `src/index.ts`
-- **381** DTCG tokens in `hirobius.tokens.json`, compiled to CSS variables and TypeScript constants
-- **484** Storybook stories in **121** story files
+- **54** public component modules, exported from `src/index.ts`
+- **385** DTCG tokens in `hirobius.tokens.json`, compiled to CSS variables and TypeScript constants
+- **340** Storybook stories in **71** story files
 
 <!-- auto:end:front-door-counts -->
 
@@ -29,9 +29,12 @@ Agents: install the consumer skill with `npx skills add hirobius/hds --skill hds
 
 <!-- auto:start:consumer-usage -->
 
-The Ops dashboard (`hirobius/ops`) is the only verified component-level consumer: **35** of its source files import from `@hirobius/design-system`, using **25** distinct components. The two screenshots below are Ops pages rendered from its `main` (measured at commit `01fce2f`).
+The Ops dashboard (`hirobius/ops`) is the only product app that uses components: **33** of its source files import from `@hirobius/design-system`, using **25** distinct components. The two screenshots below are Ops pages rendered from its `main` (measured at commit `76ef65e`).
 
-Other consumers: the split into product apps and token-level sites is not yet confirmed, so it is not stated here.
+| Consumer kind     | Count | How it uses HDS                           |
+| ----------------- | ----- | ----------------------------------------- |
+| Product apps      | 1     | Components and tokens                     |
+| Token-level sites | 4     | Tokens and CSS only, no component imports |
 
 [![Ops library page](docs/images/ops-library.png)](docs/images/ops-library.png)
 
@@ -39,7 +42,7 @@ Other consumers: the split into product apps and token-level sites is not yet co
 
 <!-- auto:end:consumer-usage -->
 
-The numbers come from `pnpm consumer:usage --root <ops checkout>`, which measures that checkout and records its commit in `docs/data/consumer-usage.json`; without a root it reuses the committed snapshot. `scripts/__tests__/consumer-usage.test.mjs` fails if this section drifts from that snapshot. The product-app and token-level-site split is a declared figure in that file and stays out of this section until `consumersConfirmed` there is set to true.
+The numbers come from `pnpm consumer:usage --root <ops checkout>`, which measures that checkout's `src/` and records its commit in `docs/data/consumer-usage.json` (pass `--commit <sha>` when the root is a `git archive` export); without a root it reuses the committed snapshot. A deprecated alias counts as the component it points to (`HdsCheckbox` as `Checkbox`). The components that Ops's page- and video-clone prompts tell generated code to import are listed there as `promptContracts` and are not counted here. `scripts/__tests__/consumer-usage.test.mjs` fails if this section drifts from that snapshot. The product-app and token-level-site split is a declared figure in that file, not a measurement. It was confirmed on 2026-10-01 (hds#389: there is no second product app), so `consumersConfirmed` there is true and the table above shows it.
 
 ## Using the published package
 
@@ -51,7 +54,7 @@ guide: **[docs/CONSUMING.md](docs/CONSUMING.md)**.
 > `@hirobius/design-system` entry under GitHub Packages
 > (`/pkgs/npm/design-system`). That listing is **frozen and no longer updated** —
 > publishing moved to the public npm registry in
-> [#39](https://github.com/hirobius/hirobius-design-system/pull/39). Always
+> [#39](https://github.com/hirobius/hds/pull/39). Always
 > install from npm:
 > **[npmjs.com/package/@hirobius/design-system](https://www.npmjs.com/package/@hirobius/design-system)**.
 
@@ -153,7 +156,7 @@ pnpm build-storybook
 
 HDS is built around three structural rules:
 
-- **Strict semantics** — public surfaces prefer system primitives such as `Stack`, `Grid`, `Surface`, and `TextLockup` instead of raw layout divs or ad hoc CSS.
+- **Strict semantics** — public surfaces prefer system primitives such as `Stack`, `Grid`, `Surface`, and `Text` instead of raw layout divs or ad hoc CSS.
 - **Polymorphism** — primitives preserve semantic HTML while staying composable through governed APIs such as `forwardRef`, `as`, and layout slots.
 - **12-column grid** — page structure follows a consistent editorial grid: readable center columns, intentional breakout zones, and explicit `gap` ownership rather than one-off spacing math.
 
@@ -173,10 +176,10 @@ What CI and the hooks check today, and nothing more:
 
 - **Contrast:** `scripts/check-contrast.mjs` enforces WCAG AA contrast on the core token pairs, in light and dark. It runs in CI and the pre-commit hook.
 - **Lint:** `jsx-a11y` rules run inside ESLint with zero warnings allowed.
-- **Focus:** `scripts/check-focus-states.mjs` (`pnpm check:focus`) audits focus styles on interactive components. It runs in the agent gate and on demand, not in the main CI workflow, and currently reports 1 violation (`src/app/components/asset-img.tsx`).
-- **Storybook:** the `addon-a11y` panel shows axe results for each story while you review it. It reports; it does not gate.
+- **Focus:** `scripts/check-focus-states.mjs` (`pnpm check:focus`) audits focus styles on interactive components. It runs in `pretest` under `pnpm test`, so in the pre-push hook and in CI, and passes with 0 violations.
+- **Storybook:** the `addon-a11y` panel shows axe results for each story while you review it. The gate is `scripts/check-storybook-axe.mjs`: CI scans every built story in light and dark, including the open Select and Combobox, and fails on serious or critical violations outside its allowlist (`scripts/axe-allowlist.json`). The allowlist has one entry: `aria-hidden-focus` on the open Select story, where Radix Select hides the page around its listbox while focus stays trapped inside it (hds#407).
 
-There is no automated screen-reader testing.
+Screen-reader output is checked by `tests/primitive-contracts/screen-reader.contract.test.tsx`, which runs in `pnpm test` and walks Dialog, Menu, Select, Combobox, Table and Alert with a virtual screen-reader (`@guidepup/virtual-screen-reader`) under jsdom, asserting the role, name and state phrases it reads and the alert's live-region announcement; it reads the jsdom accessibility tree, not what a desktop or mobile screen-reader says.
 
 ## Visual direction: Editorial Enterprise
 

package/codemods/hds-prefix.mjs

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+/**
+ * hds-prefix codemod (hds#389 R1, follows hds#315)
+ *
+ * 0.20.0 removed the six `Hds*` aliases from the package root: HdsCheckbox,
+ * HdsRadio, HdsSelect, HdsSlider, HdsToggle and HdsTooltip. Each is the same
+ * component under its bare name. This rewrites the import specifier only, and
+ * keeps the name the file already uses:
+ *
+ *   - `import { HdsCheckbox } from '@hirobius/design-system'` becomes
+ *     `import { Checkbox as HdsCheckbox } from '@hirobius/design-system'`;
+ *   - `HdsSelect as Pick` becomes `Select as Pick`; `type` modifiers stay;
+ *   - `export { HdsToggle } from '…'` becomes `export { Toggle as HdsToggle } from '…'`,
+ *     so the file's own export name does not change.
+ *
+ * No other text in the file changes: JSX, values, `typeof`, spreads, string
+ * keys, comments (including comments inside the import braces) and imports from
+ * any other module stay as written, so every reference still resolves to the
+ * same component. Renaming the local binding to the bare name afterwards is
+ * optional and a manual edit. Only named imports and re-exports whose source is
+ * exactly the package root are rewritten, and running it twice changes nothing.
+ *
+ *   node codemods/hds-prefix.mjs [--root <dir>] [--check] [--dry-run]
+ *
+ *   --root <dir>  directory to scan (default: current directory)
+ *   --check       write nothing; exit 1 when a rewrite is needed, or when a root
+ *                 star re-export, or a namespace import or dynamic `import()`,
+ *                 `require()` or `vi.mock`/`jest.mock` of the root that reads an
+ *                 Hds* name off the module, or a file that cannot be read to its
+ *                 end (codemods/unrewritable.mjs), needs a manual look
+ *   --dry-run     write nothing; print each changed line before (-) and after (+), exit 0
+ */
+import { readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { relative, resolve, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findUnrewritable as findHidden, maskSource } from './unrewritable.mjs';
+
+const ROOT_PKG = '@hirobius/design-system';
+const EXTS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts']);
+const SKIP_DIRS = new Set([
+  'node_modules',
+  'dist',
+  'build',
+  '.git',
+  '.next',
+  '.vercel',
+  'coverage',
+  'storybook-static',
+]);
+
+/** The aliases 0.19.1 exported from the root, and the bare name each pointed at. */
+export const RENAMES = Object.freeze({
+  HdsCheckbox: 'Checkbox',
+  HdsRadio: 'Radio',
+  HdsSelect: 'Select',
+  HdsSlider: 'Slider',
+  HdsToggle: 'Toggle',
+  HdsTooltip: 'Tooltip',
+});
+
+const ID = '[A-Za-z_$][\\w$]*';
+// Matched on the masked source (codemods/unrewritable.mjs), where comments are
+// blank and the specifier is a run of spaces between its quotes:
+// at a line start or after `;`: import|export, type?, default?, { body }, from, quote.
+const namedRe = () =>
+  new RegExp(
+    `(?:^|(?<=;))[ \\t]*(?:import|export)(?:\\s+type)?\\s*(?:${ID}\\s*,\\s*)?\\{([^}]*)\\}\\s*from\\s*(['"]) {${ROOT_PKG.length}}\\2`,
+    'gm',
+  );
+// One specifier, between commas: `type`? name, then `as alias`?
+const specRe = new RegExp(`^(\\s*(?:type\\s+)?)(${ID})(\\s+as\\s+${ID})?\\s*$`);
+
+/**
+ * Pure transform of one file's source: rewrites the Hds* specifiers of each
+ * named import or re-export from the package root, and nothing else.
+ * @param {string} source
+ * @param {Record<string, string>} [renames]
+ * @returns {{ source: string, changed: boolean, sites: number, renamed: string[],
+ *   edits: { line: number, before: string, after: string }[] }}
+ */
+export function transformSource(source, renames = RENAMES) {
+  const { code } = maskSource(source);
+  const renamed = new Set();
+  const changes = [];
+  let sites = 0;
+
+  for (const m of code.matchAll(namedRe())) {
+    const quoteAt = m.index + m[0].length - ROOT_PKG.length - 2;
+    if (!source.startsWith(ROOT_PKG, quoteAt + 1)) continue;
+    const bodyAt = m.index + m[0].indexOf('{') + 1;
+    let touched = false;
+    let at = bodyAt;
+    for (const spec of m[1].split(',')) {
+      const s = specRe.exec(spec);
+      const bare = s && Object.hasOwn(renames, s[2]) ? renames[s[2]] : undefined;
+      if (bare) {
+        const name = s[2];
+        const nameAt = at + s[1].length;
+        // Keep the name the file uses: `HdsCheckbox` -> `Checkbox as HdsCheckbox`.
+        changes.push({
+          start: nameAt,
+          end: nameAt + name.length,
+          text: s[3] ? bare : `${bare} as ${name}`,
+        });
+        renamed.add(name);
+        touched = true;
+      }
+      at += spec.length + 1;
+    }
+    if (touched) sites++;
+  }
+
+  let out = source;
+  for (const r of changes.sort((a, b) => b.start - a.start))
+    out = out.slice(0, r.start) + r.text + out.slice(r.end);
+
+  if (out === source) return { source, changed: false, sites: 0, renamed: [], edits: [] };
+  const before = source.split('\n');
+  const after = out.split('\n');
+  const edits = [];
+  before.forEach((line, i) => {
+    if (line !== after[i]) edits.push({ line: i + 1, before: line, after: after[i] });
+  });
+  return { source: out, changed: true, sites, renamed: [...renamed].sort(), edits };
+}
+
+/**
+ * What the codemod cannot rewrite (codemods/unrewritable.mjs): a star re-export
+ * of the root, whose importers are in other files; and a namespace import or a
+ * dynamic `import()`, `require()`, `vi.mock` or `jest.mock` of the root in a file
+ * that reads an Hds* name off something (`HDS.HdsSlider`, `m['HdsToggle']`,
+ * `const { HdsRadio } = …`). The alias binding the codemod writes is not a read.
+ */
+export function findUnrewritable(source, renames = RENAMES) {
+  return findHidden(source, ROOT_PKG, Object.keys(renames));
+}
+
+function* walk(dir) {
+  for (const entry of readdirSync(dir)) {
+    if (SKIP_DIRS.has(entry)) continue;
+    const full = join(dir, entry);
+    const st = statSync(full);
+    if (st.isDirectory()) yield* walk(full);
+    else if (EXTS.has(full.slice(full.lastIndexOf('.')))) yield full;
+  }
+}
+
+/** Scan a directory. Writes only when `write` is true. */
+export function runCodemod({ root, write = false, renames = RENAMES }) {
+  const files = [];
+  const manual = [];
+  const renamed = new Set();
+  let sites = 0;
+  for (const file of walk(root)) {
+    const src = readFileSync(file, 'utf8');
+    if (!src.includes(ROOT_PKG)) continue;
+    const r = transformSource(src, renames);
+    for (const stmt of findUnrewritable(r.source, renames))
+      manual.push({ file: relative(root, file), stmt });
+    if (!r.changed) continue;
+    files.push({ file: relative(root, file), sites: r.sites, renamed: r.renamed, edits: r.edits });
+    r.renamed.forEach((n) => renamed.add(n));
+    sites += r.sites;
+    if (write) writeFileSync(file, r.source);
+  }
+  return { files, sites, manual, names: [...renamed].sort() };
+}
+
+function main(argv) {
+  const args = { root: process.cwd(), check: false, dryRun: false };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--root') args.root = resolve(argv[++i] ?? '');
+    else if (argv[i] === '--check') args.check = true;
+    else if (argv[i] === '--dry-run') args.dryRun = true;
+    else {
+      console.error(
+        `unknown argument: ${argv[i]}\nusage: hds-prefix [--root <dir>] [--check] [--dry-run]`,
+      );
+      return 2;
+    }
+  }
+  const write = !args.check && !args.dryRun;
+  const res = runCodemod({ root: args.root, write });
+  const names = res.names.map((n) => `${n} -> ${RENAMES[n]}`).join(', ') || 'none';
+  const summary = `${res.files.length} files, ${res.sites} import sites, ${res.names.length} names (${names})`;
+  // An unreadable file names its own fix; the rest need the bare names by hand.
+  const manualLines = res.manual.map(
+    (m) =>
+      `  ${m.file}: ${m.stmt}${m.stmt.startsWith('unreadable ') ? '' : ' (use the bare names by hand)'}`,
+  );
+  if (args.check) {
+    if (res.files.length > 0 || res.manual.length > 0) {
+      console.error(`hds-prefix: rewrite needed: ${summary}`);
+      for (const f of res.files) console.error(`  ${f.file}: ${f.renamed.join(', ')}`);
+      for (const l of manualLines) console.error(l);
+      return 1;
+    }
+    console.log('hds-prefix: nothing to rewrite');
+    return 0;
+  }
+  console.log(`hds-prefix: ${write ? 'rewrote' : 'would rewrite'} ${summary}`);
+  for (const f of res.files) {
+    console.log(`  ${f.file}: ${f.renamed.join(', ')}`);
+    if (args.dryRun)
+      for (const e of f.edits) {
+        console.log(`- ${e.before}`);
+        console.log(`+ ${e.after}`);
+      }
+  }
+  if (res.manual.length > 0) {
+    console.warn('hds-prefix: cannot rewrite these, do them by hand:');
+    for (const l of manualLines) console.warn(l);
+  }
+  return 0;
+}
+
+// Compare real paths: npm/yarn link the bin and pnpm links the package directory, so
+// argv[1] is a symlink while import.meta.url is already resolved.
+const isEntry = (() => {
+  try {
+    return (
+      !!process.argv[1] &&
+      realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))
+    );
+  } catch {
+    return false;
+  }
+})();
+if (isEntry) {
+  process.exit(main(process.argv.slice(2)));
+}