@assure-one/design-system 1.31.0 → 1.33.0

package/codemods/README.md

@@ -0,0 +1,365 @@
+# @assure-one/design-system codemods
+
+Migration tooling shipped inside the package: every codemod of the program in
+implementation plan §29 runs from the installed copy in a consumer project, so
+a consumer never installs a second tool and always runs the codemods that match
+its design-system version.
+
+## Running a codemod
+
+```bash
+# What is available, and what this project has not applied yet
+node node_modules/@assure-one/design-system/codemods/run.mjs list
+
+# Preview: report only, no file is written
+node node_modules/@assure-one/design-system/codemods/run.mjs CM-15 src --dry --print
+
+# Apply, and write a JSON + Markdown report next to the run
+node node_modules/@assure-one/design-system/codemods/run.mjs CM-05 src --report reports/cm-05
+
+# Everything this project is missing, in program order
+node node_modules/@assure-one/design-system/codemods/run.mjs upgrade --dry
+```
+
+There is deliberately **no** `bin` entry and **no** `exports` entry for the
+codemods: `exports` is locked (L-ENTRIES) and a `bin` would put a command on
+consumers' `PATH` that has nothing to do with using the design system. The file
+path above is the documented interface. Inside this repository the same runner
+is `pnpm codemods <id> <paths>`.
+
+| Option                          | Effect                                                                         |
+| ------------------------------- | ------------------------------------------------------------------------------ |
+| `--dry`                         | report what would happen; write neither files nor the ledger                   |
+| `--root <dir>`                  | project root (default: the nearest `package.json` above the working directory) |
+| `--report <prefix>`             | write `<prefix>.json` and `<prefix>.md`                                        |
+| `--json <file>` / `--md <file>` | write one of the two                                                           |
+| `--print`                       | print the full Markdown report                                                 |
+| `--quiet`                       | print nothing but errors                                                       |
+| `--fail-on-findings`            | exit 1 when a finding maps to a compatibility contract (for CI gates)          |
+
+Exit codes: `0` done · `1` findings with `--fail-on-findings` · `2` usage error
+· `3` refused by a guard.
+
+Paths are files or directories; with none, the whole project root is scanned.
+`node_modules`, `dist`, `.next`, `build`, `coverage`, `public/` and the other
+generated directories are always skipped, and test files are read only by
+codemods that ask for them.
+
+## Classes
+
+| Class | Meaning                                                |
+| ----- | ------------------------------------------------------ |
+| **A** | safely automatic                                       |
+| **R** | automatic, plus a report a human reviews               |
+| **X** | report-only; the runner refuses to let it write a file |
+
+Nothing that changes submitted form data, business mappings, copy, colour
+_meaning_ or e-sign flow logic is ever automated.
+
+## The ledger — `.ds-migrations.json`
+
+Applying a transforming codemod appends an entry to `.ds-migrations.json` in
+the consumer project root:
+
+```json
+{
+  "schema": 1,
+  "applied": [
+    {
+      "id": "CM-05",
+      "appliedAt": "2026-09-17T09:12:44.001Z",
+      "dsVersion": "1.31.0",
+      "filesChanged": 12
+    }
+  ]
+}
+```
+
+Commit it with the codemod's changes. It is what makes
+
+- **one-shot codemods safe** — a codemod declaring `oneShot` refuses to run a
+  second time (a `--dry` preview is still allowed, with a warning);
+- **prerequisites enforceable** — `requires.codemods` refuses to run before the
+  codemods it builds on, and `requires.dsVersion` before the release that ships
+  the replacement API;
+- **`upgrade` exact** — a consumer several versions behind gets precisely the
+  codemods it is missing, in program order.
+
+Report-only codemods and dry runs never touch it. The consumer scanner reads
+the file and the migration dashboard shows the applied ids
+(`migration-status/<app>.json` → `codemodLedger`).
+
+## Reports
+
+Every run produces the same report: a JSON document (`schema`, the codemod, the
+design-system version, a summary, the findings, the files changed, what could
+**not** be transformed and parse errors) and a Markdown rendering of it. "Could
+not be transformed" is the part that matters for class A and R codemods: it is
+the list a human has to pick up — spread props, dynamic expressions, conflicting
+`classNames` objects.
+
+## Codemods
+
+| Id    | Class | What it does                                                                                                                        |
+| ----- | ----- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| CM-14 | X     | hidden-input mirror finder: hidden `<input name>` a consumer added because a design-system control posts nothing                    |
+| CM-15 | X     | DOM-selector finder: consumer code that depends on the internal DOM of design-system components, mapped to registry `C-DOM-*` ids   |
+| CM-16 | X     | `globals.css` analyser: `@source` into the package, duplicate preflight, colliding `@theme` keys, unlayered globals, legacy `var()` |
+| CM-20 | X     | Select sentinel finder: option values standing in for "no value", and the line where each is converted back                         |
+
+The remaining ids of plan §29 land with the waves that ship their replacement
+APIs.
+
+### CM-14 — hidden-input mirror finder
+
+Report-only, **for ever**: deleting a mirror changes what the server receives,
+and plan §29 never automates that. It is the input to W4-04 (native form
+participation) and to the registry contract `C-HIDDEN-MIRRORS`.
+
+The applications do not put a mirror next to its control — they collect the
+mirrors at the top of the `<form>` and bind the control far below ([CU §18]).
+"Next to" is therefore read as _bound to the same state_:
+
+| Rule                        | Contract         | Found                                                                          |
+| --------------------------- | ---------------- | ------------------------------------------------------------------------------ |
+| `mirror-shared-binding`     | C-HIDDEN-MIRRORS | the hidden input's `value` reads a binding a design-system control is bound to |
+| `mirror-in-form`            | C-HIDDEN-MIRRORS | same `<form>` as a control that posts nothing today; nothing ties the two      |
+| `unregistered-hidden-input` | (unregistered)   | no control to mirror — a value the server supplied (a token, an id)            |
+
+Each finding names the control, the field name and whether that control takes
+`name` **today** (`yes`) or only after Wave 4 (`planned`); severity is `high`
+when the control takes `name` and the call site already passes it, because the
+form then posts the field twice.
+
+The third rule is why the report reconciles with the audit's census of every
+hidden `<input>` ([CU §24]): CM-14 reports the same population, classified,
+rather than a smaller number with no explanation. It does not look across
+files — a mirror whose control lives elsewhere lands in `mirror-in-form` or
+`unregistered-hidden-input` and says so. An `<input type={expr}>` whose type is
+computed appears in "could not be transformed".
+
+The `name` capability table lives in the transform, and
+`tests/codemods/cm-14.test.mjs` checks it against the design system's own
+sources so it cannot describe components this version does not ship.
+
+### CM-20 — Select sentinel finder
+
+Report-only, **for ever**: replacing a sentinel with `null` changes what the
+server receives. It is the input to W4-08 (`Select value: string | null`) and
+to the registry contract `C-SELECT-EMPTY`.
+
+The spellings are **found, not assumed**. The registry names `"none"` and
+`"__unassigned__"`; the applications use far more, and `"none"` is also a real
+domain value. CM-20 reports a spelling only where the file itself proves it
+stands in for nothing:
+
+| Rule                  | Contract       | Found                                                             |
+| --------------------- | -------------- | ----------------------------------------------------------------- |
+| `empty-string-value`  | C-SELECT-EMPTY | `value=""` on a Select-family control or an option                |
+| `sentinel-dunder`     | C-SELECT-EMPTY | a `__…__` spelling used as a Select value                         |
+| `sentinel-constant`   | C-SELECT-EMPTY | a no-value-named constant used as a Select value                  |
+| `sentinel-word`       | C-SELECT-EMPTY | `none`/`all`/… **with** a no-value label or a round trip          |
+| `sentinel-discovered` | C-SELECT-EMPTY | any other spelling the file converts to nothing                   |
+| `sentinel-conversion` | C-SELECT-EMPTY | the line that maps a reported sentinel to `null`/`undefined`/`""` |
+
+A known word with no evidence at all is **not** reported: CM-20 would rather
+miss a sentinel than invite someone to change a value the backend depends on.
+Sentinels outside the Select family — grouping keys, tab ids, route segments —
+are out of scope even when the spelling matches, and nothing is followed across
+files.
+
+### CM-15 — DOM-selector finder
+
+Report-only. It never modifies a file; the runner throws if it tries. What it
+looks for:
+
+- **class tokens that reach into a component's children** on a design-system
+  tag — arbitrary variants with a descendant, child or sibling combinator, the
+  `*` / `**` child variants, `has-[…]` — and the same tokens on a wrapper
+  element whose subtree holds a design-system component;
+- **group references the design system provides** (`group-data-[labels…]`,
+  `…/sidebar`, `…/row`);
+- **DOM queries** — `querySelector(All)`, `closest`, `matches`, Playwright
+  `locator` — whose selector names design-system internals, including
+  selectors held in a file-level constant;
+- **text matching on copy the design system renders** ("Next", "Notifications",
+  "Next page", "Clear search", "Back") through `getByText`-style queries,
+  `getByRole({ name })` or `textContent` comparisons;
+- **tests that parse the built bundle** (`…/design-system/dist/index.js`);
+- **global CSS selectors** that name design-system internals.
+
+Self-only variants (`[&[data-state=open]]:…`, `[&:hover]:…`), Radix
+`data-state`/`data-side`/`data-align` attributes, ARIA roles and cmdk
+attributes are **not** reported: they are permanent contracts (P-DATA-STATE,
+P-ROLES, C-CMDK-ATTR).
+
+Findings carry a `registryId` when they match a contract and
+`rule: "unregistered-…"` when they are DOM coupling the registry does not track
+yet — those are the candidates for new registry entries. `confidence` is `high`
+for a token on the component itself, `medium` for a wrapper or a heuristic,
+`low` for an unmapped wrapper.
+
+CM-15 feeds 2.0 gate G7 (`consumerSelectors = 0` for the freezes with removal
+target 2.0). Use `--fail-on-findings` to gate on it. The committed findings for
+the four consumer apps are in `docs/codemods/`.
+
+### CM-16 — `globals.css` analyser
+
+Report-only, and the input to the consumer compatibility presets (plan §12).
+It finds, with a line number and a severity, the mechanisms by which an
+application restyles design-system components today:
+
+| Rule                      | Contract        | Gate | Found                                                                    |
+| ------------------------- | --------------- | ---- | ------------------------------------------------------------------------ |
+| `source-into-ds`          | C-CSS-SOURCE    | G2   | `@source` pointing into the design-system package                        |
+| `ds-styles-import`        | C-CSS-STYLES    | G1   | `@assure-one/design-system/styles.css` imported (from CSS or from code)  |
+| `duplicate-preflight`     | C-CSS-STYLES    | G1   | the app compiles a Tailwind preflight while the DS sheet ships one too   |
+| `theme-collision-differs` | C-TOKENS-LEGACY | —    | an `@theme` key that shadows a DS token **with a different value**       |
+| `theme-collision-equal`   | C-TOKENS-LEGACY | —    | the same name with the same value today                                  |
+| `legacy-var-write`        | C-TOKENS-WRITE  | —    | a DS token name declared outside `@theme` — a deliberate override        |
+| `legacy-var-read`         | C-TOKENS-LEGACY | —    | `var(--<ds token>)` read by app CSS                                      |
+| `brand-scope-spelling`    | C-CSS-DARKCLASS | —    | DS tokens re-declared under `.dark` or `[data-brand="…"]`                |
+| `dark-variant-mismatch`   | C-CSS-DARKCLASS | —    | an app `dark` variant that cannot match the `.dark` element itself       |
+| `unlayered-ds-dom`        | (unregistered)  | —    | an unlayered app rule that styles DS markup (`button`, `*`, `.shadow-…`) |
+| `layered-ds-dom`          | (unregistered)  | —    | the same, inside the app's own `base`/`components` layer                 |
+
+Severity is `high` for anything that blocks G1/G2 or changes what a DS
+component renders, `medium` for coupling that a rename has to carry, `low` for
+what is only fragile today.
+
+Boundary with CM-15: selectors that name design-system **internals**
+(`[data-radix-…]`, `[data-esign-…]`, `[data-labels]`, `[cmdk-…]`, the toast
+region) are the `C-DOM-*` contracts and belong to CM-15, which already reports
+them from CSS. CM-16 skips them, so the two finders never count the same rule
+twice.
+
+CM-16 reads the **authored** stylesheets; `scripts/derive-consumer-preset`
+(W1-18) reads the **compiled** ones with a full cascade. The two therefore
+count different things on purpose — `docs/codemods/cm-16-globals-css.md` puts
+the numbers side by side and explains every difference. Both call two values
+"different" through the same normalisation (`codemods/lib/css-values.mjs`),
+which is why the value-level counts can be compared at all.
+
+It parses CSS with the project's own `postcss` (borrowed exactly as
+`typescript` is, see "Packaging"), and compares against the design system's
+own `dist/styles.css` from the installed package.
+
+## Writing a codemod
+
+A codemod is one module in `codemods/transforms/`, registered in
+`codemods/lib/registry.mjs` (the registry order is the program order that
+`upgrade` follows):
+
+```js
+export const meta = {
+  id: "CM-07",
+  title: "inputSize → size on Input, Textarea and SearchInput",
+  class: "A",
+  oneShot: false,
+  requires: { codemods: [], dsVersion: "1.32.0" },
+  parses: ["code"], // "code" and/or "css"
+  includeTests: false,
+  usesTypeScript: true,
+  usesPostcss: false,
+  registryIds: ["C-INPUT-SIZE"],
+};
+
+export function transform(file, { ts, postcss }) {
+  // file: { rel, path, source, kind, test }
+  return { output, findings, notTransformed, parseErrors };
+}
+```
+
+`usesTypeScript` and `usesPostcss` ask the runner to resolve that parser from
+the project and inject it; a codemod never imports one itself.
+
+The runner owns everything else: the guards, which files are read, writing
+files and the ledger, the report, and the rule that a class X codemod may not
+change anything.
+
+Fixtures live in `codemods/__test__/<id>/*.snap` — one file per case, holding a
+small project and the expected findings (and, for transforming codemods, the
+expected output):
+
+```
+=== file: src/thing.tsx
+<source>
+=== expect
+{ "findings": [ ["src/thing.tsx:12", "C-DOM-03", "class-on-component", "<class token>"] ] }
+```
+
+`codemods/__test__/harness.mjs` materialises a fixture in a temporary
+directory, runs the codemod **twice** and asserts that the second run finds the
+same things and changes nothing — the idempotency requirement of plan §29.
+`tests/codemods/*.test.mjs` runs all of it as part of `pnpm test:contracts`.
+
+Fixtures are `.snap` on purpose: Tailwind scans every other repository file for
+class names, and a fixture full of consumer classes would change
+`dist/styles.css`. `tests/codemods/tailwind-inert.test.mjs` proves the codemod
+sources, fixtures and findings stay invisible to that scan — which is also why
+class-like text in a `.mjs` or `.md` file here is assembled from parts.
+
+## Packaging
+
+`codemods` is part of the published tarball (`package.json` → `files`);
+`codemods/__test__` is not. The codemods need `typescript` at run time and
+resolve it from the consumer project, so the published package gains no
+dependency. See `docs/codemods/README.md` for that decision.
+
+## Legacy: 0.2.0-radix-migration.mjs
+
+The pre-program codemod, written before the runner existed. It is a
+jscodeshift transform and is run with `npx jscodeshift`, not with `run.mjs`.
+
+### Run it
+
+From the consumer repo (firm or portal), with `@assure-one/design-system@0.2.0` installed:
+
+```bash
+# Dry-run first to preview
+npx jscodeshift -t node_modules/@assure-one/design-system/codemods/0.2.0-radix-migration.mjs \
+  --extensions=tsx,ts,jsx,js --parser=tsx --dry --print 'src/**/*.{ts,tsx}'
+
+# Apply
+VERBOSE=1 npx jscodeshift -t node_modules/@assure-one/design-system/codemods/0.2.0-radix-migration.mjs \
+  --extensions=tsx,ts,jsx,js --parser=tsx 'src/**/*.{ts,tsx}'
+```
+
+### What it changes
+
+1. `Slider` value props become `number[]` (Radix range convention)
+   - `<Slider value={50} />` becomes `<Slider value={[50]} />`
+   - `<Slider defaultValue={75} />` becomes `<Slider defaultValue={[75]} />`
+   - Adds a `// TODO 0.2.0: onValueChange now receives number[]` comment above any `<Slider>` with `onValueChange` so you review the callback body.
+   - Identifier expressions (`value={vol}`) get a TODO instead of being auto-wrapped — we can't tell from AST if the variable is already `number[]`. Tsc will catch the rest.
+
+2. `Avatar` no longer accepts a `next/image` child
+   - `<Avatar><Image src=".." alt=".." /></Avatar>` becomes `<Avatar src=".." alt=".." />`
+   - Inner non-`next/image` children are left alone.
+   - If the `Avatar` already has `src`, the inner `<Image>` is left and a TODO is emitted.
+
+### Explicit no-ops (documented for completeness)
+
+- `useToast` — fully back-compat. `useToast()` returned `{ toast }` in 0.1.x; 0.2.0 returns `{ toast, dismiss }`. Existing destructures keep working; `dismiss` is just newly available.
+- `TeamMemberSelect` — the `value: ""` (unassigned) consumer contract is preserved. The `__unassigned__` sentinel is internal.
+
+### Scoping
+
+The transform only rewrites `Slider`/`Avatar` JSX whose name is imported from `@assure-one/design-system` in the same file. Local components named `Slider` or `Avatar` from other paths are left alone.
+
+### Idempotency
+
+Running twice produces zero further changes. Already-array Slider props and already-flattened Avatars are detected and skipped.
+
+### Validate the output
+
+Test fixtures live in `codemods/__test__/*.input.tsx`. To smoke-test against them:
+
+```bash
+cp codemods/__test__/slider.input.tsx /tmp/slider.tsx
+VERBOSE=1 npx jscodeshift -t codemods/0.2.0-radix-migration.mjs \
+  --extensions=tsx --parser=tsx /tmp/slider.tsx
+diff codemods/__test__/slider.input.tsx /tmp/slider.tsx
+```
+
+After running on your codebase, run `tsc --noEmit` to catch any leftover number-vs-`number[]` mismatches the TODO comments flagged.

package/codemods/lib/css-selectors.mjs

@@ -0,0 +1,33 @@
+/**
+ * Rule selectors of a CSS file with their line numbers, without a CSS
+ * parser dependency. Comments and strings are blanked (keeping offsets), then
+ * every `prelude {` whose prelude is not an at-rule is a selector. Good
+ * enough for finding selectors; not a validator.
+ */
+export function cssSelectors(text) {
+  const blank = (s) => s.replace(/[^\n]/g, " ");
+  const clean = text
+    .replace(/\/\*[\s\S]*?\*\//g, blank)
+    .replace(
+      /"(?:\\.|[^"\\\n])*"|'(?:\\.|[^'\\\n])*'/g,
+      (m) => m[0] + blank(m.slice(1, -1)) + m[0],
+    );
+  const out = [];
+  let start = 0;
+  for (let i = 0; i < clean.length; i += 1) {
+    const ch = clean[i];
+    if (ch === "{" || ch === "}" || ch === ";") {
+      if (ch === "{") {
+        const prelude = clean.slice(start, i);
+        const offset = start + (prelude.length - prelude.trimStart().length);
+        const selector = text.slice(offset, i).trim();
+        if (selector && !selector.startsWith("@") && !/^[\d.%,\s]+$|^(?:from|to)$/.test(selector)) {
+          const line = text.slice(0, offset).split("\n").length;
+          out.push({ selector: selector.replace(/\s+/g, " "), line });
+        }
+      }
+      start = i + 1;
+    }
+  }
+  return out;
+}

package/codemods/lib/css-values.mjs

@@ -0,0 +1,223 @@
+/**
+ * Custom-property values: normalisation for comparison, and `var()`
+ * resolution. Dependency-free and pure — no file system, no CSS parser — so
+ * it can ship inside the package and run from a consumer project.
+ *
+ * It is the single implementation shared by
+ * `scripts/derive-consumer-preset` (W1-18) and CM-16: the two tools must
+ * agree on when two declarations of the same token "differ", or their counts
+ * cannot be compared. `scripts/derive-consumer-preset/lib/normalize.mjs` and
+ * `…/lib/cascade.mjs` re-export from here.
+ *
+ * Two values are "the same" when their normalised text is equal. The
+ * normalisation is conservative: it only removes differences that cannot
+ * change rendering (case of hex colours and keywords, short hex, whitespace,
+ * quotes around font names, `calc()` over px/rem only, trailing zeros). It
+ * does not convert between colour spaces: `#6c42f8` and an `oklab(...)`
+ * spelling of the same colour stay different, and the report shows both.
+ */
+
+const ROOT_FONT_SIZE_PX = 16;
+
+export function normalizeValue(value) {
+  if (value == null) return value;
+  let v = String(value).trim().replace(/\s+/g, " ");
+  v = v
+    .replace(/\s*,\s*/g, ",")
+    .replace(/\(\s+/g, "(")
+    .replace(/\s+\)/g, ")");
+  // Minifiers drop optional whitespace: `…) infinite` -> `…)infinite`, `16 / 9` -> `16/9`.
+  v = v.replace(/\)\s*(?=[\w#.-])/g, ") ").replace(/\s*\/\s*/g, "/");
+  v = v.replace(/#([0-9a-f]{3,8})\b/gi, (_, hex) => `#${expandHex(hex.toLowerCase())}`);
+  v = v.replace(/["']([^"',]+)["']/g, "$1");
+  v = evaluateCalcs(v);
+  v = v.replace(/(\d*\.\d*?)0+(?=[a-z%]|\b)/gi, (m, num) =>
+    num.endsWith(".") ? num.slice(0, -1) : num,
+  );
+  v = v.replace(/(^|[\s(,])0\.(\d)/g, "$1.$2");
+  if (/^[A-Za-z-]+$/.test(v)) v = v.toLowerCase();
+  if (/^-?\d*\.?\d+rem$/.test(v)) v = `${lengthToPx(v)}px`;
+  return v;
+}
+
+function expandHex(hex) {
+  if (hex.length === 3 || hex.length === 4) return [...hex].map((c) => c + c).join("");
+  return hex;
+}
+
+/** Evaluate innermost calc() expressions made only of px/rem/unitless terms. */
+export function evaluateCalcs(value) {
+  let prev;
+  let v = value;
+  do {
+    prev = v;
+    v = v.replace(/calc\(([^()]*)\)/g, (whole, expr) => {
+      const result = evaluateLength(expr);
+      return result === null ? whole : result;
+    });
+  } while (v !== prev);
+  return v;
+}
+
+/**
+ * Evaluate `a op b op c` where terms are px, rem or unitless numbers.
+ * Returns a px string ("8px") or a unitless number string, or null.
+ */
+export function evaluateLength(expr) {
+  const tokens = expr.match(/-?\d*\.?\d+(?:px|rem)?|[+\-*/]/g);
+  if (!tokens || tokens.join("").replace(/\s/g, "") !== expr.replace(/\s/g, "")) return null;
+  // Terms: { n: number, unit: "px" | "" }
+  const terms = [];
+  const ops = [];
+  let expectTerm = true;
+  for (const t of tokens) {
+    if (expectTerm) {
+      const m = /^(-?\d*\.?\d+)(px|rem)?$/.exec(t);
+      if (!m) return null;
+      const n = Number(m[1]) * (m[2] === "rem" ? ROOT_FONT_SIZE_PX : 1);
+      terms.push({ n, unit: m[2] ? "px" : "" });
+      expectTerm = false;
+    } else {
+      if (!/^[+\-*/]$/.test(t)) return null;
+      ops.push(t);
+      expectTerm = true;
+    }
+  }
+  if (expectTerm) return null;
+  // * and / first
+  for (let i = 0; i < ops.length; ) {
+    if (ops[i] === "*" || ops[i] === "/") {
+      const a = terms[i];
+      const b = terms[i + 1];
+      let r;
+      if (ops[i] === "*") {
+        if (a.unit && b.unit) return null;
+        r = { n: a.n * b.n, unit: a.unit || b.unit };
+      } else {
+        if (b.unit || b.n === 0) return null;
+        r = { n: a.n / b.n, unit: a.unit };
+      }
+      terms.splice(i, 2, r);
+      ops.splice(i, 1);
+    } else i++;
+  }
+  let acc = terms[0];
+  for (let i = 0; i < ops.length; i++) {
+    const b = terms[i + 1];
+    if (acc.unit !== b.unit) return null;
+    acc = { n: ops[i] === "+" ? acc.n + b.n : acc.n - b.n, unit: acc.unit };
+  }
+  const n = Math.round(acc.n * 10000) / 10000;
+  return `${n}${acc.unit}`;
+}
+
+/** Normalise a length-ish value to px when it is a plain rem/px value. */
+export function lengthToPx(value) {
+  const m = /^(-?\d*\.?\d+)(px|rem)$/.exec(String(value).trim());
+  if (!m) return null;
+  return Number(m[1]) * (m[2] === "rem" ? ROOT_FONT_SIZE_PX : 1);
+}
+
+export function sameValue(a, b) {
+  if (a === undefined || b === undefined) return a === b;
+  const na = normalizeValue(a);
+  const nb = normalizeValue(b);
+  if (na === nb) return true;
+  const pa = lengthToPx(na);
+  const pb = lengthToPx(nb);
+  return pa !== null && pa === pb;
+}
+
+/** Names referenced through `var(--name…)` in a value, in order. */
+export function referencedVars(value) {
+  return [...String(value).matchAll(/var\(\s*(--[\w-]+)/g)].map((m) => m[1]);
+}
+
+const INVALID = Symbol("invalid");
+
+/**
+ * Compute custom-property values for one element.
+ * @param {Map<string, {value: string}>} winners own declarations
+ * @param {Map<string, string>} inherited parent's (or, for CM-16, the design
+ *   system sheet's) computed values
+ * @returns {Map<string, string>} computed values (invalid ones omitted)
+ */
+export function computeCustomProperties(winners, inherited = new Map()) {
+  const computed = new Map();
+  const state = new Map(); // prop -> "visiting" | "done"
+  const visit = (prop) => {
+    if (!winners.has(prop)) return inherited.has(prop) ? inherited.get(prop) : undefined;
+    if (state.get(prop) === "done") return computed.has(prop) ? computed.get(prop) : INVALID;
+    if (state.get(prop) === "visiting") return INVALID;
+    state.set(prop, "visiting");
+    const value = substitute(winners.get(prop).value, visit);
+    state.set(prop, "done");
+    if (value === INVALID) computed.delete(prop);
+    else computed.set(prop, value);
+    return value;
+  };
+  for (const prop of winners.keys()) visit(prop);
+  const out = new Map(inherited);
+  for (const prop of winners.keys()) {
+    if (computed.has(prop)) out.set(prop, computed.get(prop));
+    else out.delete(prop); // guaranteed-invalid: behaves as unset for custom props
+  }
+  return out;
+}
+
+/** Replace every var() in `value`; returns INVALID when a cycle is hit. */
+function substitute(value, lookup) {
+  let out = "";
+  let i = 0;
+  while (i < value.length) {
+    const start = value.indexOf("var(", i);
+    if (start === -1 || (start > 0 && /[\w-]/.test(value[start - 1]))) {
+      if (start === -1) {
+        out += value.slice(i);
+        break;
+      }
+      out += value.slice(i, start + 4);
+      i = start + 4;
+      continue;
+    }
+    out += value.slice(i, start);
+    const end = matchParen(value, start + 3);
+    if (end === -1) {
+      out += value.slice(start);
+      break;
+    }
+    const inner = value.slice(start + 4, end);
+    const comma = topLevelComma(inner);
+    const name = (comma === -1 ? inner : inner.slice(0, comma)).trim();
+    const fallback = comma === -1 ? null : inner.slice(comma + 1).trim();
+    const resolved = lookup(name);
+    if (resolved === INVALID) return INVALID;
+    if (resolved !== undefined) out += resolved;
+    else if (fallback !== null) {
+      const fb = substitute(fallback, lookup);
+      if (fb === INVALID) return INVALID;
+      out += fb;
+    } else out += `var(${name})`; // external: keep it visible
+    i = end + 1;
+  }
+  return out;
+}
+
+function matchParen(s, open) {
+  let depth = 0;
+  for (let i = open; i < s.length; i++) {
+    if (s[i] === "(") depth++;
+    else if (s[i] === ")" && --depth === 0) return i;
+  }
+  return -1;
+}
+
+function topLevelComma(s) {
+  let depth = 0;
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === "(") depth++;
+    else if (s[i] === ")") depth--;
+    else if (s[i] === "," && depth === 0) return i;
+  }
+  return -1;
+}