@variance-authority/core 0.1.0

package/dist/attribute/boundary.js

@@ -0,0 +1,328 @@
+/**
+ * Where one component's nodes stop and the next component's begin.
+ *
+ * Two relations run upward out of a rendered node and they are not the same
+ * relation. **Parent** is what is above it — React's `return` chain, the boxes
+ * it ended up inside. **Owner** is what rendered it — React's `_debugOwner`, the
+ * code that wrote the element. A layout wrapper is the parent of everything
+ * handed to it and the owner of none of it.
+ *
+ * Both are needed here, for different halves of the same answer:
+ *
+ * - **Parent decides nesting.** A boundary owns a contiguous region of the
+ *   document, and what encloses that region is a fact about the tree. Reading
+ *   the owner for this would produce a boundary set that is not a partition.
+ * - **Owner decides membership and naming.** A component's own content is what
+ *   *it* wrote. Content it was handed is a hole in its output — present, sized,
+ *   positioned by it, and authored somewhere else.
+ *
+ * Reading the parent for both — which is what a walk over `owners[0]` does — has
+ * two consequences, and they are the two shapes a design system is made of:
+ *
+ * - **A component that renders only components disappears.** It authors no host
+ *   node, so it is never any node's nearest enclosing composite, so it is a
+ *   boundary nowhere. That is every variant wrapper (`DangerButton` returning a
+ *   `Button`) and every page-level assembly. The information is not missing —
+ *   the composite is in the chain, one rung up — it is discarded by reading only
+ *   the head of it. {@link boundaries} enters every rung the chain crosses.
+ * - **A container absorbs its caller's content.** `Card` renders one `div` and
+ *   whatever it was given; hashed by enclosure, its digest moves whenever a
+ *   caller passes something else, while its props digest — which excludes
+ *   `children` — says its inputs held. {@link shapeOf} names a child boundary
+ *   only when this component placed it, and leaves an anonymous hole otherwise.
+ *
+ * The owner half is a development-build artefact: React populates `_debugOwner`
+ * from `element._owner`, and a production bundle does not. Absent, both rules
+ * degrade to naming everything, which is the enclosure answer — coarser, never
+ * wrong in a new direction.
+ *
+ * Nothing here is exported from the package. The callers are siblings.
+ */
+/** A node whose provenance chain broke. Not a filler category; see `RootKind`. */
+export const UNATTRIBUTED = '(unattributed)';
+/**
+ * Properties whose *computed* value is layout output rather than authored input.
+ *
+ * The distinction this list exists for is not stylistic. Under a profile with a
+ * layout engine the snapshot carries the engine's resolved values, so a block
+ * element's computed `height` is whatever its contents made it — and a button
+ * two levels down growing by six pixels moves the computed height of every
+ * ancestor. Hashed as *style*, that reports every enclosing component as having
+ * changed, which is precisely the "area ranks the displaced above the displacer"
+ * failure the cause hashes exist to fix, arriving through a different door.
+ *
+ * Measured on `cases/storybook-case`: one padding edit inside `Button` made
+ * `Tokens`, `Stack`, `Card` and the unattributed root all report a moved style
+ * hash, so *every* component in every affected story was named a cause.
+ *
+ * They are folded into `geometry` instead, where "this component's box is a
+ * different size" already belongs and where it correctly does not make a cause.
+ * Under a profile *without* layout there are no computed values, so these are
+ * authored declarations like any other and stay in `style` — that tier has no
+ * `geometry` digest to move them to, and a declared `width: 100px` really is the
+ * component's own content.
+ */
+export const LAYOUT_OUTPUT = new Set([
+    'width',
+    'height',
+    'min-width',
+    'min-height',
+    'max-width',
+    'max-height',
+    // The one nobody guesses, and the one that was actually doing the damage.
+    // `transform-origin` computes to half the border box — `512px 41px` — so it
+    // moves whenever the box does, on every element, including ones that declare
+    // no transform at all. Removing `width` and `height` changed nothing on the
+    // case measurement; removing this is what made a padding edit inside `Button`
+    // stop naming `Tokens`, `Stack`, `Card` and the root as causes.
+    'transform-origin',
+    // Chromium returns *used* track sizes here — `"70.39px 953.61px"` — never the
+    // author's `auto 1fr`, so nothing declared survives to be lost. That is what
+    // makes these two safe on a list, and it is exactly what is not true of the
+    // properties named below.
+    'grid-template-columns',
+    'grid-template-rows',
+]);
+function ownershipOf(node) {
+    const owners = node.provenance?.owners;
+    if (owners === undefined || owners.length === 0) {
+        return { stack: [UNATTRIBUTED], placedBy: [undefined], props: [undefined] };
+    }
+    const stack = [];
+    const placedBy = [];
+    const props = [];
+    for (let index = owners.length - 1; index >= 0; index -= 1) {
+        const frame = owners[index];
+        stack.push(frame.name);
+        placedBy.push(frame.createdBy);
+        props.push(frame.propsDigest);
+    }
+    // FIXME: what should this name when the author is a slot?
+    //
+    // Radix `Slot` under `asChild` merges the caller's className onto the child's
+    // own host node, so `<Button asChild><Link/></Button>` renders one `<a>` whose
+    // author is next/link's `LinkComponent` and whose every styling decision came
+    // from `Button`. The owner rule then reports a name out of `node_modules` for a
+    // region an edit to `button.tsx` moved, and both halves are individually
+    // correct: `Button` really did author no host node, and `LinkComponent` really
+    // did write the one that moved.
+    //
+    // Open, because the naive fix is worse. Preferring the nearest caller whenever
+    // the author is unfamiliar would credit every container with its children's
+    // changes, which is exactly the enclosure answer the owner rule exists to
+    // refuse. Whether a slot is distinguishable from an ordinary hand-off at this
+    // rung has not been read — `Slot` is a component like any other from here.
+    const author = node.provenance?.createdBy;
+    if (author !== undefined && author !== stack.at(-1)) {
+        // A slotted region received no props of its own: it is markup, handed over
+        // whole. Absent rather than the container's digest, which would claim the
+        // author was called with inputs it never saw.
+        stack.push(author);
+        placedBy.push(author);
+        props.push(undefined);
+    }
+    return { stack, placedBy, props };
+}
+/** How many rungs two stacks agree on, from the outside in. */
+function sharedRungs(a, b) {
+    const limit = Math.min(a.length, b.length);
+    let shared = 0;
+    while (shared < limit && a[shared] === b[shared])
+        shared += 1;
+    return shared;
+}
+/** Whether a node's own content belongs to this boundary rather than one below. */
+export function holds(boundary, node) {
+    const { stack } = ownershipOf(node);
+    return stack.length === boundary.rung + 1 && stack[boundary.rung] === boundary.component;
+}
+/**
+ * Every boundary root in the subject, in document order.
+ *
+ * A boundary opens at each rung a node's ownership stack adds to its parent's,
+ * plus the subject root. Several can open at one node — a page assembly, the
+ * card it returns and the stack inside that card all begin at the same element —
+ * which is what makes a component that renders only components visible.
+ *
+ * Collected in a separate pre-order pass rather than discovered during hashing,
+ * so that instance order is document order exactly. Discovering them while
+ * walking would order them by boundary depth instead, and "the second instance"
+ * would mean something different in a nested tree.
+ */
+export function boundaries(root) {
+    const found = [];
+    const visit = (node, parent, enclosing, depth) => {
+        const { stack, placedBy, props } = ownershipOf(node);
+        const opened = parent === null ? 0 : sharedRungs(parent, stack);
+        let within = enclosing;
+        let below = depth;
+        for (let rung = opened; rung < stack.length; rung += 1) {
+            const digest = props[rung];
+            const placer = placedBy[rung];
+            found.push({
+                node,
+                component: stack[rung],
+                ...(within === null ? {} : { within }),
+                depth: below,
+                rung,
+                ...(digest === undefined ? {} : { props: digest }),
+                ...(placer === undefined ? {} : { placedBy: placer }),
+            });
+            within = stack[rung];
+            below += 1;
+        }
+        for (const child of node.children)
+            visit(child, stack, within, below);
+    };
+    visit(root, null, null, 0);
+    return found;
+}
+/**
+ * One boundary's content, stopping at nested boundaries.
+ *
+ * Where a child belongs to another component, this records a placeholder rather
+ * than descending. That is the whole design: a component's hash moves when *its
+ * own* code changes, and what a child renders internally is not that. Hashing
+ * whole subtrees instead would move every ancestor on any leaf edit, and the
+ * page root would change on every commit.
+ *
+ * **The placeholder names the child only when this component placed it.** A
+ * component that wrote `<Stack>` owns that choice, and swapping it for a `<Card>`
+ * is its own change; a container that was handed a `<Stack>` chose nothing, and
+ * naming it would make the container's digest a function of its callers. So a
+ * slot is anonymous, and `Card` renders the same bytes on every page that uses
+ * it, whatever it was given. The cost is stated in ADR-0035: the *number* of
+ * slotted children still reaches the digest, so a caller passing three where it
+ * passed two moves the container.
+ *
+ * Falls back to naming every child where `_debugOwner` is absent, which is the
+ * enclosure answer this replaced.
+ *
+ * Paths are not hashed. A path is an address that shifts when an unrelated
+ * sibling is inserted, so hashing one reports a change nobody made.
+ */
+export function shapeOf(boundary, layout, rename) {
+    const { node, component, rung } = boundary;
+    const style = [];
+    const geometry = [];
+    const semantics = [];
+    const text = [];
+    const wiring = [];
+    const renders = [];
+    const tokens = new Set();
+    let nodes = 0;
+    const walk = (current) => {
+        nodes += 1;
+        for (const token of Object.keys(current.tokens ?? {}))
+            tokens.add(token);
+        const declared = {};
+        const measured = {};
+        for (const [property, value] of Object.entries(current.style)) {
+            const resolved = rename === undefined ? value : rename.style(value);
+            if (layout && LAYOUT_OUTPUT.has(property))
+                measured[property] = resolved;
+            else
+                declared[property] = resolved;
+        }
+        style.push({ style: declared, tokens: renamedTokens(current, rename) });
+        // An entry per node, always. `null` for a node with no rect keeps position in
+        // the list meaningful: dropping the entry would let two different trees agree
+        // by coincidence.
+        geometry.push({
+            rect: current.rect ? { ...current.rect } : null,
+            // Beside the rect, not instead of it. A computed `max-height` that changed
+            // while the box did not is still a fact about this element's geometry, and
+            // dropping it would make the two digests disagree about what a box is.
+            ...(Object.keys(measured).length > 0 ? { measured } : {}),
+        });
+        // One entry per node in each list, always — `null` rather than omitted, for
+        // the reason the geometry list gives: dropping an entry lets two different
+        // trees agree by coincidence, and here it would let a heading losing its
+        // name look like a heading that never had one.
+        semantics.push({
+            role: current.role ?? null,
+            name: current.name ?? null,
+            state: (current.state ?? null),
+        });
+        text.push(current.text ?? null);
+        // `null` for a node that reports none, for the reason every list here gives:
+        // an omitted entry lets two different trees agree by coincidence. Most nodes
+        // report `null` — wiring attaches to a component's root node and not to the
+        // elements beneath it (see `wiringOf`), so a boundary's band is a short
+        // signal in a long run of nulls, and the nulls are what make its position
+        // mean anything.
+        wiring.push((current.wiring ?? null));
+        return {
+            tag: current.tag,
+            alias: renamedAlias(current, rename),
+            portalled: current.portalled,
+            attributes: renamedAttributes(current, rename),
+            children: current.children.map((child) => entry(child)),
+        };
+    };
+    /**
+     * Every node inside one boundary carries the same stack, by construction.
+     *
+     * So the comparison a child is measured against is fixed for the whole walk,
+     * and a zero-node boundary — a component that renders only components, whose
+     * root node already belongs to the boundary below it — measures against the
+     * same thing.
+     */
+    const home = ownershipOf(node).stack.slice(0, rung + 1);
+    /**
+     * A node's contribution: its own content, or a stand-in for what is beneath.
+     *
+     * The rung a child leaves at is where its stack stops agreeing with `home` —
+     * normally the next rung down, and shallower wherever a subject root carries
+     * no provenance and the application starts again inside it.
+     */
+    const entry = (child) => {
+        if (holds(boundary, child))
+            return walk(child);
+        const own = ownershipOf(child);
+        const left = sharedRungs(home, own.stack);
+        const beneath = own.stack[left] ?? own.stack.at(-1) ?? UNATTRIBUTED;
+        // Kept whichever way the digest goes: the edge is a true fact about the
+        // document, and the graph wants it even where the hash must not carry it.
+        renders.push(beneath);
+        const placer = own.placedBy[left];
+        return placer === undefined || placer === component ? { boundary: beneath } : { slot: null };
+    };
+    const structure = entry(node);
+    return {
+        structure,
+        semantics,
+        text,
+        style,
+        geometry,
+        wiring,
+        box: node.rect ?? null,
+        renders,
+        nodes,
+        tokens: [...tokens].sort(),
+    };
+}
+function renamedAlias(node, rename) {
+    if (rename === undefined || node.alias === undefined)
+        return node.alias;
+    return rename.alias(node.alias);
+}
+function renamedAttributes(node, rename) {
+    if (rename === undefined)
+        return node.attributes;
+    const renamed = {};
+    for (const [name, value] of Object.entries(node.attributes)) {
+        renamed[name] = rename.attribute(name, value);
+    }
+    return renamed;
+}
+function renamedTokens(node, rename) {
+    if (rename === undefined || node.tokens === undefined)
+        return node.tokens;
+    const renamed = {};
+    for (const [name, value] of Object.entries(node.tokens)) {
+        renamed[name] = rename.style(value);
+    }
+    return renamed;
+}
+//# sourceMappingURL=boundary.js.map

package/dist/attribute/boundary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundary.js","sourceRoot":"","sources":["../../src/attribute/boundary.ts"],"names":[],"mappings":"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","sourcesContent":["import type { CanonicalValue } from '../format/canonical.js';\nimport type { Rect } from '../format/capture.js';\nimport type { Digest } from '../format/hash.js';\nimport type { SemanticNode } from '../format/snapshot.js';\n\n/**\n * Where one component's nodes stop and the next component's begin.\n *\n * Two relations run upward out of a rendered node and they are not the same\n * relation. **Parent** is what is above it — React's `return` chain, the boxes\n * it ended up inside. **Owner** is what rendered it — React's `_debugOwner`, the\n * code that wrote the element. A layout wrapper is the parent of everything\n * handed to it and the owner of none of it.\n *\n * Both are needed here, for different halves of the same answer:\n *\n * - **Parent decides nesting.** A boundary owns a contiguous region of the\n *   document, and what encloses that region is a fact about the tree. Reading\n *   the owner for this would produce a boundary set that is not a partition.\n * - **Owner decides membership and naming.** A component's own content is what\n *   *it* wrote. Content it was handed is a hole in its output — present, sized,\n *   positioned by it, and authored somewhere else.\n *\n * Reading the parent for both — which is what a walk over `owners[0]` does — has\n * two consequences, and they are the two shapes a design system is made of:\n *\n * - **A component that renders only components disappears.** It authors no host\n *   node, so it is never any node's nearest enclosing composite, so it is a\n *   boundary nowhere. That is every variant wrapper (`DangerButton` returning a\n *   `Button`) and every page-level assembly. The information is not missing —\n *   the composite is in the chain, one rung up — it is discarded by reading only\n *   the head of it. {@link boundaries} enters every rung the chain crosses.\n * - **A container absorbs its caller's content.** `Card` renders one `div` and\n *   whatever it was given; hashed by enclosure, its digest moves whenever a\n *   caller passes something else, while its props digest — which excludes\n *   `children` — says its inputs held. {@link shapeOf} names a child boundary\n *   only when this component placed it, and leaves an anonymous hole otherwise.\n *\n * The owner half is a development-build artefact: React populates `_debugOwner`\n * from `element._owner`, and a production bundle does not. Absent, both rules\n * degrade to naming everything, which is the enclosure answer — coarser, never\n * wrong in a new direction.\n *\n * Nothing here is exported from the package. The callers are siblings.\n */\n\n/** A node whose provenance chain broke. Not a filler category; see `RootKind`. */\nexport const UNATTRIBUTED = '(unattributed)';\n\n/**\n * Properties whose *computed* value is layout output rather than authored input.\n *\n * The distinction this list exists for is not stylistic. Under a profile with a\n * layout engine the snapshot carries the engine's resolved values, so a block\n * element's computed `height` is whatever its contents made it — and a button\n * two levels down growing by six pixels moves the computed height of every\n * ancestor. Hashed as *style*, that reports every enclosing component as having\n * changed, which is precisely the \"area ranks the displaced above the displacer\"\n * failure the cause hashes exist to fix, arriving through a different door.\n *\n * Measured on `cases/storybook-case`: one padding edit inside `Button` made\n * `Tokens`, `Stack`, `Card` and the unattributed root all report a moved style\n * hash, so *every* component in every affected story was named a cause.\n *\n * They are folded into `geometry` instead, where \"this component's box is a\n * different size\" already belongs and where it correctly does not make a cause.\n * Under a profile *without* layout there are no computed values, so these are\n * authored declarations like any other and stay in `style` — that tier has no\n * `geometry` digest to move them to, and a declared `width: 100px` really is the\n * component's own content.\n */\nexport const LAYOUT_OUTPUT: ReadonlySet<string> = new Set([\n  'width',\n  'height',\n  'min-width',\n  'min-height',\n  'max-width',\n  'max-height',\n  // The one nobody guesses, and the one that was actually doing the damage.\n  // `transform-origin` computes to half the border box — `512px 41px` — so it\n  // moves whenever the box does, on every element, including ones that declare\n  // no transform at all. Removing `width` and `height` changed nothing on the\n  // case measurement; removing this is what made a padding edit inside `Button`\n  // stop naming `Tokens`, `Stack`, `Card` and the root as causes.\n  'transform-origin',\n  // Chromium returns *used* track sizes here — `\"70.39px 953.61px\"` — never the\n  // author's `auto 1fr`, so nothing declared survives to be lost. That is what\n  // makes these two safe on a list, and it is exactly what is not true of the\n  // properties named below.\n  'grid-template-columns',\n  'grid-template-rows',\n]);\n\n/**\n * Five more shapes leak, and a longer list is the wrong fix. Measured.\n *\n * Editing only a descendant's padding in a real Chromium moves the computed\n * value of an ancestor's `padding-*` (percentage padding in a shrink-to-fit\n * box), `margin-*` (an `auto` margin centring a `fit-content` block),\n * `top`/`right`/`bottom`/`left` (an absolutely positioned element anchored to an\n * edge that moved) and `transform` (a `translate(-50%,-50%)` matrix, the exact\n * sibling of the `transform-origin` case above). Each one makes an enclosing\n * component a false cause.\n *\n * Adding them here was tried and is worse than the disease: with `padding-*` on\n * the list, `causes.test.ts`'s headline case — a padding edit *inside* `Button`\n * — stops naming `Button` at all. For these properties the computed value **is**\n * the authored value in the ordinary case, and a property name cannot tell the\n * two apart. Only a *value* can, and the only place that knows is `resolveStyle`\n * in `rules/normalize/cascade.ts`, which sees both the cascade's winner and the\n * engine's override and currently keeps no record of which superseded which.\n *\n * So the limit is stated rather than half-fixed: a component whose own\n * declarations use percentage padding, auto margins, edge-anchored absolute\n * positioning or a percentage translate can be named a cause by a change that\n * was not its own. The failure is a *false* cause, never a missed one, which is\n * the direction that costs a reader attention rather than a regression.\n */\n\n/**\n * Every component holding a node, outermost first, and who placed each one.\n *\n * The whole chain, not its head. `TodoFooter` rendering nothing but a `Stack`\n * appears here at the rung below `Stack`, which is the only place it appears at\n * all — it authors no element, so no node has it as a nearest enclosing\n * composite, and a walk that reads `owners[0]` cannot see it.\n *\n * `placedBy[i]` is who wrote the element for `stack[i]`: `OwnerFrame.createdBy`,\n * which is the component that decided a `<Stack>` belongs at this point, as\n * distinct from `Stack` itself. Absent per rung on a production build.\n *\n * A host node whose author is not the innermost component is content that was\n * handed in: it sits inside the container's box and belongs to whoever wrote it,\n * so the author is pushed as a further rung. That keeps the boundary set a\n * partition of the document — the slotted region is nested inside the container\n * rather than lifted out of it — while attributing it to the code responsible.\n */\ninterface Ownership {\n  readonly stack: readonly string[];\n  readonly placedBy: readonly (string | undefined)[];\n  readonly props: readonly (Digest | undefined)[];\n}\n\nfunction ownershipOf(node: SemanticNode): Ownership {\n  const owners = node.provenance?.owners;\n  if (owners === undefined || owners.length === 0) {\n    return { stack: [UNATTRIBUTED], placedBy: [undefined], props: [undefined] };\n  }\n\n  const stack: string[] = [];\n  const placedBy: (string | undefined)[] = [];\n  const props: (Digest | undefined)[] = [];\n  for (let index = owners.length - 1; index >= 0; index -= 1) {\n    const frame = owners[index]!;\n    stack.push(frame.name);\n    placedBy.push(frame.createdBy);\n    props.push(frame.propsDigest);\n  }\n\n  // FIXME: what should this name when the author is a slot?\n  //\n  // Radix `Slot` under `asChild` merges the caller's className onto the child's\n  // own host node, so `<Button asChild><Link/></Button>` renders one `<a>` whose\n  // author is next/link's `LinkComponent` and whose every styling decision came\n  // from `Button`. The owner rule then reports a name out of `node_modules` for a\n  // region an edit to `button.tsx` moved, and both halves are individually\n  // correct: `Button` really did author no host node, and `LinkComponent` really\n  // did write the one that moved.\n  //\n  // Open, because the naive fix is worse. Preferring the nearest caller whenever\n  // the author is unfamiliar would credit every container with its children's\n  // changes, which is exactly the enclosure answer the owner rule exists to\n  // refuse. Whether a slot is distinguishable from an ordinary hand-off at this\n  // rung has not been read — `Slot` is a component like any other from here.\n  const author = node.provenance?.createdBy;\n  if (author !== undefined && author !== stack.at(-1)) {\n    // A slotted region received no props of its own: it is markup, handed over\n    // whole. Absent rather than the container's digest, which would claim the\n    // author was called with inputs it never saw.\n    stack.push(author);\n    placedBy.push(author);\n    props.push(undefined);\n  }\n\n  return { stack, placedBy, props };\n}\n\n/** How many rungs two stacks agree on, from the outside in. */\nfunction sharedRungs(a: readonly string[], b: readonly string[]): number {\n  const limit = Math.min(a.length, b.length);\n  let shared = 0;\n  while (shared < limit && a[shared] === b[shared]) shared += 1;\n  return shared;\n}\n\nexport interface Boundary {\n  readonly node: SemanticNode;\n  readonly component: string;\n  /** The enclosing boundary's component, absent on the subject root. */\n  readonly within?: string;\n  /** Boundaries between this one and the subject root. The root is `0`. */\n  readonly depth: number;\n  /**\n   * This component's rung in the node's ownership stack.\n   *\n   * Distinct from `depth`, which counts enclosing boundaries. They diverge\n   * wherever a subject root has no provenance: the `(unattributed)` container is\n   * a boundary at depth 0 holding a stack of one, and the application inside it\n   * starts again at rung 0 while sitting at depth 1.\n   */\n  readonly rung: number;\n  /**\n   * Digest of the props this boundary received, from its own `OwnerFrame`.\n   *\n   * Read at this rung rather than from `owners[0]`, which is the innermost\n   * component and belongs to whichever boundary is deepest at this node — the\n   * distinction only exists because several boundaries can share a root.\n   */\n  readonly props?: Digest;\n  /** The component whose JSX placed this one. Absent on a production build. */\n  readonly placedBy?: string;\n}\n\n/** Whether a node's own content belongs to this boundary rather than one below. */\nexport function holds(boundary: Boundary, node: SemanticNode): boolean {\n  const { stack } = ownershipOf(node);\n  return stack.length === boundary.rung + 1 && stack[boundary.rung] === boundary.component;\n}\n\n/**\n * Every boundary root in the subject, in document order.\n *\n * A boundary opens at each rung a node's ownership stack adds to its parent's,\n * plus the subject root. Several can open at one node — a page assembly, the\n * card it returns and the stack inside that card all begin at the same element —\n * which is what makes a component that renders only components visible.\n *\n * Collected in a separate pre-order pass rather than discovered during hashing,\n * so that instance order is document order exactly. Discovering them while\n * walking would order them by boundary depth instead, and \"the second instance\"\n * would mean something different in a nested tree.\n */\nexport function boundaries(root: SemanticNode): readonly Boundary[] {\n  const found: Boundary[] = [];\n\n  const visit = (\n    node: SemanticNode,\n    parent: readonly string[] | null,\n    enclosing: string | null,\n    depth: number,\n  ): void => {\n    const { stack, placedBy, props } = ownershipOf(node);\n    const opened = parent === null ? 0 : sharedRungs(parent, stack);\n\n    let within = enclosing;\n    let below = depth;\n    for (let rung = opened; rung < stack.length; rung += 1) {\n      const digest = props[rung];\n      const placer = placedBy[rung];\n      found.push({\n        node,\n        component: stack[rung]!,\n        ...(within === null ? {} : { within }),\n        depth: below,\n        rung,\n        ...(digest === undefined ? {} : { props: digest }),\n        ...(placer === undefined ? {} : { placedBy: placer }),\n      });\n      within = stack[rung]!;\n      below += 1;\n    }\n\n    for (const child of node.children) visit(child, stack, within, below);\n  };\n\n  visit(root, null, null, 0);\n  return found;\n}\n\nexport interface Shape {\n  readonly structure: CanonicalValue;\n  readonly semantics: CanonicalValue;\n  readonly text: CanonicalValue;\n  readonly style: CanonicalValue;\n  readonly geometry: CanonicalValue;\n\n  /**\n   * How the framework holds this boundary, per node that reports it.\n   *\n   * Its own band because it answers its own question. `structure` through\n   * `geometry` all read what the renderer produced; this reads what the\n   * component *is* — its hook shape, its wrappers, the contexts it subscribes\n   * to, the keys it is reconciled under. Two components can agree on all five\n   * content bands and disagree here, and when they do, they behave differently\n   * under every change that follows.\n   */\n  readonly wiring: CanonicalValue;\n\n  /**\n   * The box this boundary's root node occupies. Not part of any digest.\n   *\n   * Beside the digests rather than inside `geometry`, which is the whole subtree:\n   * this is the only thing on the record that can say a control grew eight pixels\n   * rather than merely stopped being what it was. `null` where nothing was laid out.\n   */\n  readonly box: Rect | null;\n\n  /** Child boundaries encountered, in document order. Not part of any digest. */\n  readonly renders: readonly string[];\n  /** Nodes this boundary owns, counting its own root. Not part of any digest. */\n  readonly nodes: number;\n  /**\n   * Custom properties this boundary's own nodes resolved through, sorted.\n   *\n   * Not part of any digest — the *values* are already inside `style`, and the\n   * names are carried beside it so a token that moved can be joined to the\n   * components that read it. Off the boundary rather than off the subject on\n   * purpose: every subject on a themed page resolves through every token in the\n   * theme, so a subject-level list names them all and explains nothing.\n   */\n  readonly tokens: readonly string[];\n}\n\n/**\n * How a value that may carry a structural alias is rewritten before hashing.\n *\n * `undefined` for the per-name hashes, which have always hashed the alias the\n * normalizer assigned and must keep doing so byte for byte. Supplied by the\n * per-instance hashes, which need a boundary-local alias space — see\n * {@link ./instances.js}, where the argument for it lives.\n */\nexport interface Rename {\n  readonly attribute: (name: string, value: string) => string;\n  readonly style: (value: string) => string;\n  readonly alias: (alias: string) => string;\n}\n\n/**\n * One boundary's content, stopping at nested boundaries.\n *\n * Where a child belongs to another component, this records a placeholder rather\n * than descending. That is the whole design: a component's hash moves when *its\n * own* code changes, and what a child renders internally is not that. Hashing\n * whole subtrees instead would move every ancestor on any leaf edit, and the\n * page root would change on every commit.\n *\n * **The placeholder names the child only when this component placed it.** A\n * component that wrote `<Stack>` owns that choice, and swapping it for a `<Card>`\n * is its own change; a container that was handed a `<Stack>` chose nothing, and\n * naming it would make the container's digest a function of its callers. So a\n * slot is anonymous, and `Card` renders the same bytes on every page that uses\n * it, whatever it was given. The cost is stated in ADR-0035: the *number* of\n * slotted children still reaches the digest, so a caller passing three where it\n * passed two moves the container.\n *\n * Falls back to naming every child where `_debugOwner` is absent, which is the\n * enclosure answer this replaced.\n *\n * Paths are not hashed. A path is an address that shifts when an unrelated\n * sibling is inserted, so hashing one reports a change nobody made.\n */\nexport function shapeOf(boundary: Boundary, layout: boolean, rename?: Rename): Shape {\n  const { node, component, rung } = boundary;\n  const style: CanonicalValue[] = [];\n  const geometry: CanonicalValue[] = [];\n  const semantics: CanonicalValue[] = [];\n  const text: CanonicalValue[] = [];\n  const wiring: CanonicalValue[] = [];\n  const renders: string[] = [];\n  const tokens = new Set<string>();\n  let nodes = 0;\n\n  const walk = (current: SemanticNode): CanonicalValue => {\n    nodes += 1;\n    for (const token of Object.keys(current.tokens ?? {})) tokens.add(token);\n    const declared: Record<string, string> = {};\n    const measured: Record<string, string> = {};\n\n    for (const [property, value] of Object.entries(current.style)) {\n      const resolved = rename === undefined ? value : rename.style(value);\n      if (layout && LAYOUT_OUTPUT.has(property)) measured[property] = resolved;\n      else declared[property] = resolved;\n    }\n\n    style.push({ style: declared, tokens: renamedTokens(current, rename) });\n    // An entry per node, always. `null` for a node with no rect keeps position in\n    // the list meaningful: dropping the entry would let two different trees agree\n    // by coincidence.\n    geometry.push({\n      rect: current.rect ? { ...current.rect } : null,\n      // Beside the rect, not instead of it. A computed `max-height` that changed\n      // while the box did not is still a fact about this element's geometry, and\n      // dropping it would make the two digests disagree about what a box is.\n      ...(Object.keys(measured).length > 0 ? { measured } : {}),\n    });\n\n    // One entry per node in each list, always — `null` rather than omitted, for\n    // the reason the geometry list gives: dropping an entry lets two different\n    // trees agree by coincidence, and here it would let a heading losing its\n    // name look like a heading that never had one.\n    semantics.push({\n      role: current.role ?? null,\n      name: current.name ?? null,\n      state: (current.state ?? null) as CanonicalValue,\n    });\n    text.push(current.text ?? null);\n    // `null` for a node that reports none, for the reason every list here gives:\n    // an omitted entry lets two different trees agree by coincidence. Most nodes\n    // report `null` — wiring attaches to a component's root node and not to the\n    // elements beneath it (see `wiringOf`), so a boundary's band is a short\n    // signal in a long run of nulls, and the nulls are what make its position\n    // mean anything.\n    wiring.push((current.wiring ?? null) as CanonicalValue);\n\n    return {\n      tag: current.tag,\n      alias: renamedAlias(current, rename),\n      portalled: current.portalled,\n      attributes: renamedAttributes(current, rename),\n      children: current.children.map((child) => entry(child)),\n    };\n  };\n\n  /**\n   * Every node inside one boundary carries the same stack, by construction.\n   *\n   * So the comparison a child is measured against is fixed for the whole walk,\n   * and a zero-node boundary — a component that renders only components, whose\n   * root node already belongs to the boundary below it — measures against the\n   * same thing.\n   */\n  const home = ownershipOf(node).stack.slice(0, rung + 1);\n\n  /**\n   * A node's contribution: its own content, or a stand-in for what is beneath.\n   *\n   * The rung a child leaves at is where its stack stops agreeing with `home` —\n   * normally the next rung down, and shallower wherever a subject root carries\n   * no provenance and the application starts again inside it.\n   */\n  const entry = (child: SemanticNode): CanonicalValue => {\n    if (holds(boundary, child)) return walk(child);\n\n    const own = ownershipOf(child);\n    const left = sharedRungs(home, own.stack);\n    const beneath = own.stack[left] ?? own.stack.at(-1) ?? UNATTRIBUTED;\n    // Kept whichever way the digest goes: the edge is a true fact about the\n    // document, and the graph wants it even where the hash must not carry it.\n    renders.push(beneath);\n\n    const placer = own.placedBy[left];\n    return placer === undefined || placer === component ? { boundary: beneath } : { slot: null };\n  };\n\n  const structure = entry(node);\n  return {\n    structure,\n    semantics,\n    text,\n    style,\n    geometry,\n    wiring,\n    box: node.rect ?? null,\n    renders,\n    nodes,\n    tokens: [...tokens].sort(),\n  };\n}\n\nfunction renamedAlias(node: SemanticNode, rename?: Rename): string | undefined {\n  if (rename === undefined || node.alias === undefined) return node.alias;\n  return rename.alias(node.alias);\n}\n\nfunction renamedAttributes(\n  node: SemanticNode,\n  rename?: Rename,\n): Readonly<Record<string, string>> {\n  if (rename === undefined) return node.attributes;\n\n  const renamed: Record<string, string> = {};\n  for (const [name, value] of Object.entries(node.attributes)) {\n    renamed[name] = rename.attribute(name, value);\n  }\n  return renamed;\n}\n\nfunction renamedTokens(\n  node: SemanticNode,\n  rename?: Rename,\n): Readonly<Record<string, string>> | undefined {\n  if (rename === undefined || node.tokens === undefined) return node.tokens;\n\n  const renamed: Record<string, string> = {};\n  for (const [name, value] of Object.entries(node.tokens)) {\n    renamed[name] = rename.style(value);\n  }\n  return renamed;\n}\n"]}

package/dist/attribute/call-site.d.ts

@@ -0,0 +1,96 @@
+import type { Provenance, SourceLocation, StackFrame } from '../format/provenance.js';
+import type { NodePath, SemanticSnapshot } from '../format/snapshot.js';
+/**
+ * Spending the frames a page read, to get the file a reviewer opens.
+ *
+ * This is the half of the zero-install path that cannot happen in the page. A
+ * frame names the module the browser was *served*, and turning that into a line
+ * in the repository means fetching that module and reading the source map the
+ * build already emitted beside it. Fetching is not something a page agent should
+ * do — it runs inside somebody else's application, on a budget measured against
+ * their render loop — and it is exactly what the collector is for.
+ *
+ * **The economics are what make this worth doing rather than clever.** Measured
+ * on a 4211-node document: every fiber carried a stack, and between them they
+ * held **14 distinct call sites**. A hundred-row table writes two thousand cells
+ * from one line of JSX. So the work is per *call site*, not per node, and the
+ * cache below is not an optimization but the thing that makes the cost bounded —
+ * a handful of module fetches for a whole page.
+ *
+ * **And it is asked on a signal rather than on every capture.** Fourteen sites is
+ * a bounded cost, not a free one, and a run that settles every subject on its
+ * document digest has nobody to hand a location to: no region was drawn, no
+ * finding was raised, and the fetches would answer a question nothing asked. So
+ * frames ride the snapshot — they are provenance, and no hash projects
+ * provenance — and {@link locateSites} spends them for the handful of nodes a
+ * report is about to name. A page whose only change is one button resolves one
+ * call site, not fourteen; a page that did not change resolves none.
+ *
+ * `fetchModule` is injected because `core` may not assume a network (ADR-0013),
+ * and because the right way to fetch differs by caller: a browser-driving
+ * collector should fetch from the page's own context, where the origin, the
+ * cookies and the dev server's module graph are already correct.
+ */
+/** Fetch a module's text, or answer that it cannot be had. Never throws. */
+export type FetchModule = (url: string) => Promise<string | null>;
+export interface CallSiteResolver {
+    /** The location that wrote an element, from the frames its fiber carried. */
+    locate(frames: readonly StackFrame[]): Promise<SourceLocation | null>;
+    /** How many modules were fetched, and how many call sites they answered. */
+    readonly stats: CallSiteStats;
+}
+export interface CallSiteStats {
+    /** Distinct modules fetched. The number that costs anything. */
+    readonly modules: number;
+    /** Distinct call sites asked about — the ratio to `modules` is the point. */
+    readonly sites: number;
+    /** Call sites that resolved to a file. */
+    readonly located: number;
+}
+export declare function createCallSiteResolver(fetchModule: FetchModule): CallSiteResolver;
+/**
+ * Provenance with its frames spent: `source` filled in, `stack` gone.
+ *
+ * Returned unchanged when there is nothing to do — which is the common case once
+ * a project installs `jsx-source`, and the case a production build is always in.
+ * Never throws: a report that names a location for most of its nodes is the
+ * normal outcome, and one node's unreachable module must not take the run down.
+ */
+export declare function locateProvenance(provenance: Provenance, resolver: CallSiteResolver): Promise<Provenance>;
+/**
+ * Anything a report points at: it names a node, and may already know its line.
+ *
+ * An `AttributedRegion` and a `Finding` are both this, arrived at from opposite
+ * directions — one from a mask, one from an inspection — and both are the *few*.
+ * That is the whole reason this shape is worth having rather than two functions:
+ * what makes resolution affordable is being asked about a handful of nodes, and
+ * a handful is what a region list and a finding list are.
+ */
+export interface LocatableSite {
+    readonly path?: NodePath;
+    readonly source?: SourceLocation;
+}
+/**
+ * The line for each site a report is about to name, and for nothing else.
+ *
+ * This is the demand side of the zero-install path. The page reads frames off
+ * every fiber because reading them is nearly free; turning one into a file is
+ * not, and this is the only place that spends it.
+ *
+ * Three ways a site costs nothing, all of them the common case:
+ *
+ * - **It has no `path`.** A region no box contains names no node.
+ * - **It already has a `source`.** React ≤18 and `@variance-authority/jsx-source`
+ *   both record the location outright, so there is nothing to resolve. Only
+ *   React 19, which throws its location away and captures an `Error` instead,
+ *   reaches the map.
+ * - **Its node carried no frames.** A production build captures nothing.
+ *
+ * And a subject that settled on its document digest never calls this at all,
+ * which is the point: no region, no finding, no fetch.
+ *
+ * Sites are resolved concurrently. The resolver's own cache collapses them onto
+ * the modules they share, so two regions in one component cost one fetch.
+ */
+export declare function locateSites<T extends LocatableSite>(sites: readonly T[], snapshot: SemanticSnapshot, resolver: CallSiteResolver): Promise<readonly T[]>;
+//# sourceMappingURL=call-site.d.ts.map