@radicool/throughline 0.18.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@radicool/throughline",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Build a complete design system end to end — author in Figma, sync tokens to code, generate Storybook. Usable from Claude Code, Cursor, Codex, or any AGENTS.md agent.",
   "type": "module",
   "bin": {

package/references/native-adapter-config.md

@@ -54,7 +54,8 @@ consumer's repo.
 import { readFileSync } from 'node:fs';
 import {
   flattenDtcg,
-  flattenDtcgTypes,
+  flattenPipelineTypes,
+  extNamespace,
   resolveValue,
   findModeCollisions,
   TEXT_UNIT_NAMES,
@@ -152,10 +153,25 @@ Both are fixed before Style Dictionary sees the tree.
 // Marks a node whose AUTHORED $value was a whole-value reference, so the hoist
 // can decline to override the type DTCG 5.2.2 rule 1 already determined from the
 // referent. A WeakSet keyed on the node object, rather than a property written
-// onto it, holds structural idempotency exactly: structuredClone drops the
-// membership along with the rest of the identity, so preprocess(preprocess(x))
-// is deepEqual to preprocess(x) with no leak question to manage.
+// onto it, keeps this mechanism from leaking across calls: structuredClone
+// drops the membership along with the rest of the identity, so a second pass
+// starts clean rather than inheriting the first pass's marks. That is exactly
+// what a property written onto the node would get wrong. It is not on its own a
+// guarantee that preprocess is idempotent — see the limit recorded at
+// nativePlatform's preprocessors line (#90).
 const WAS_REF = new WeakSet();
+
+// The path the AUTHOR wrote for a node the hoist has moved. hoistDualNodes
+// recurses depth-first, so by the time an outer frame takes Object.entries it
+// already contains names the inner frame synthesised — and a collision reported
+// from that frame named a path appearing nowhere in the source (#61). Recording
+// the authored path when a node is hoisted lets the outer frame report what the
+// author can actually search for.
+//
+// Keyed on node identity, like WAS_REF, and safe across calls for the same
+// reason: preprocess structuredClones its input, so every call works on fresh
+// objects.
+const AUTHORED_PATH = new WeakMap();
 const WHOLE_REF = /^\{[^}]+\}$/;
 
 function interpolate(value, flat) {
@@ -228,20 +244,27 @@ function hoistDualNodes(node, collisions, prefix = [], groupType = undefined) {
       for (const [childKey, childVal] of Object.entries(val)) {
         if (childKey.startsWith('$') || !childVal || typeof childVal !== 'object') continue;
         const hoisted = key + childKey[0].toUpperCase() + childKey.slice(1);
-        const from = [...prefix, key, childKey].join('.');
+        const from = AUTHORED_PATH.get(childVal) ?? [...prefix, key, childKey].join('.');
         if (Object.hasOwn(node, hoisted)) {
           const existingNode = node[hoisted];
-          const isGroup = existingNode !== null && typeof existingNode === 'object' && !('$value' in existingNode);
+          // An array has no $value either, and was therefore labelled "(a group)"
+          // (#61). It is neither — an array at this position is malformed DTCG.
+          // Say so, rather than naming a shape the author will go looking for.
+          const isArray = Array.isArray(existingNode);
+          const isGroup =
+            existingNode !== null && typeof existingNode === 'object' && !isArray && !('$value' in existingNode);
           collisions.push({
             from,
             onto: [...prefix, hoisted].join('.'),
             isGroup,
+            isArray,
             claimant: claimedBy.get(hoisted),
-            existing: isGroup
-              ? undefined
-              : existingNode && typeof existingNode === 'object'
-                ? existingNode.$value
-                : existingNode,
+            existing:
+              isGroup || isArray
+                ? undefined
+                : existingNode && typeof existingNode === 'object'
+                  ? existingNode.$value
+                  : existingNode,
           });
           continue;
         }
@@ -264,8 +287,17 @@ function hoistDualNodes(node, collisions, prefix = [], groupType = undefined) {
         // type suits the child badly, because the hoist is not entitled to
         // improve on what the source says; but the carry firing at all is the
         // hoist saying something the source did not.
+        //
+        // A GROUP child is excluded (#67). The carry's premise is that the dual
+        // node was the child's closest $type-bearing ancestor as authored, and
+        // the hoist took that away. For a group child the premise never held:
+        // 5.2.2 inherits from the closest parent GROUP, the dual node is not
+        // one, so it was never that group's inheritance source and the hoist
+        // removed nothing. Carrying there does not repair, it invents — and it
+        // invents for every token beneath the group, not just one node.
         if (
           !('$type' in childVal) &&
+          '$value' in childVal &&
           '$type' in val &&
           !WAS_REF.has(childVal) &&
           inherited === undefined
@@ -273,6 +305,7 @@ function hoistDualNodes(node, collisions, prefix = [], groupType = undefined) {
           childVal.$type = val.$type;
         }
         node[hoisted] = childVal;
+        AUTHORED_PATH.set(childVal, from);
         delete val[childKey];
         claimedBy.set(hoisted, from);
       }
@@ -371,6 +404,9 @@ function classifyTextUnits(node, types, prefix = []) {
       types[path.join('.')] === 'dimension' &&
       TEXT_ROLE_UNIT.test(String(val.$value).trim())
     ) {
+      // extNamespace throws with the token path if the source authored either
+      // level as a primitive — legal DTCG this module does not handle (#62).
+      extNamespace(val, path.join('.'));
       val.$extensions ??= {};
       val.$extensions[EXT_NS] ??= {};
       const ns = val.$extensions[EXT_NS];
@@ -379,7 +415,9 @@ function classifyTextUnits(node, types, prefix = []) {
       // one, so a unitless value is declined by every size transform regardless
       // of what is stamped here (see isRatio, #52). Declining to overwrite IS
       // the feature: it costs no configuration parameter, and it is what makes
-      // the pass idempotent.
+      // STAMPING idempotent — a second pass never rewrites a role a first pass
+      // set. What it does not settle is whether a second pass finds the same
+      // candidates; the hoist can rename a node between the two (#90).
       if (!('nativeUnit' in ns)) ns.nativeUnit = 'text';
     }
     classifyTextUnits(val, types, path);
@@ -402,7 +440,8 @@ function classifyTextUnits(node, types, prefix = []) {
 // A path may name no node at all. resolveInPlace deliberately leaves an
 // unresolvable reference in place for Style Dictionary to report, so the graph
 // can hold an edge to a token that does not exist. Skip it. This is also what
-// keeps the second preprocess pass from throwing, and idempotency with it.
+// keeps the second preprocess pass from throwing — which is a precondition for
+// idempotency, not the whole of it (#90).
 function applyTextRoleGraph(node, typographic, types) {
   for (const path of typographic) {
     let target = node;
@@ -412,6 +451,7 @@ function applyTextRoleGraph(node, typographic, types) {
     if (!target || typeof target !== 'object' || !('$value' in target)) continue;
     if (types[path] !== 'dimension') continue;
     if (!TEXT_ROLE_UNIT.test(String(target.$value).trim())) continue;
+    extNamespace(target, path);
     target.$extensions ??= {};
     target.$extensions[EXT_NS] ??= {};
     const ns = target.$extensions[EXT_NS];
@@ -426,14 +466,16 @@ export function preprocess(dict) {
   // the graph is made of.
   const { typographic } = textRoleGraph(dict);
   const resolved = resolveInPlace(structuredClone(dict), flattenDtcg(dict));
-  // DTCG 5.2.2 types for the whole tree, walked once and shared by both passes
-  // below. Neither writes $type or moves a node, so one map is correct for
-  // both, and sharing it is what makes them agree by construction rather than
-  // by two copies of the same rule staying in step (#85).
+  // Types for the whole tree, walked once and shared by both passes below.
+  // Neither writes $type or moves a node, so one map is correct for both, and
+  // sharing it is what makes them agree by construction rather than by two
+  // copies of the same rule staying in step (#85).
   //
-  // Computed on the RESOLVED clone, which is the tree both passes read.
-  // resolveInPlace rewrites $value strings only, so the types are the source's.
-  const types = flattenDtcgTypes(resolved);
+  // Computed on the RAW dict, not the resolved clone. resolveInPlace only
+  // rewrites $value strings, so paths and types are identical between the two —
+  // except for the carry, whose rule asks whether a value WAS a whole-value
+  // reference, and resolution has already destroyed that (#89).
+  const types = flattenPipelineTypes(dict);
   const out = hoistDualNodes(
     applyTextRoleGraph(classifyTextUnits(resolved, types), typographic, types),
     collisions,
@@ -443,6 +485,9 @@ export function preprocess(dict) {
       .slice(0, 5)
       .map((c) => {
         const line = `  ${c.from} -> ${c.onto}`;
+        if (c.isArray) {
+          return line + ' (an array — neither a token nor a group, and not valid DTCG here)';
+        }
         if (c.isGroup) {
           return line + (c.claimant ? ` (a group, already claimed by the hoist of ${c.claimant})` : ' (a group)');
         }
@@ -629,7 +674,14 @@ const DECLINED_STOCK_TRANSFORMS = {
 // Order is never compared: our lists are hand-ordered for our own reasons and
 // do not inherit stock order. Removals are never reported: a declined name
 // disappearing is a non-event.
-export function auditStockGroups(transformGroups) {
+// `platforms` and `declined` are parameters with the shipped config as their
+// default, so the contradiction branch below is reachable from a test. The
+// single caller passes neither; the audit's contract is unchanged.
+export function auditStockGroups(
+  transformGroups,
+  platforms = PLATFORMS,
+  declined = DECLINED_STOCK_TRANSFORMS,
+) {
   if (typeof transformGroups !== 'object' || transformGroups === null) {
     return [
       "throughline: could not read Style Dictionary's stock transform groups " +
@@ -638,7 +690,29 @@ export function auditStockGroups(transformGroups) {
     ];
   }
   const warnings = [];
-  for (const [platform, preset] of Object.entries(PLATFORMS)) {
+  for (const [platform, preset] of Object.entries(platforms)) {
+    // A name in BOTH lists is a contradiction the unaccounted filter below
+    // cannot see, because either membership alone suppresses the warning (#75).
+    // The config would be saying "we run this" and "we deliberately do not" at
+    // once, and whichever is wrong is silently the loser: if the decline is
+    // right the transform still runs, and if the run is right the decline is a
+    // lie the next maintainer will read as settled. Reported here rather than
+    // guarded at the definition, so it travels with the rest of the audit.
+    //
+    // Checked before stockGroup, because this is wrong regardless of whether
+    // Style Dictionary still has the group to compare against.
+    if (Array.isArray(preset.transforms)) {
+      const contradictory = preset.transforms.filter((name) => Object.hasOwn(declined, name));
+      if (contradictory.length) {
+        warnings.push(
+          `throughline: PLATFORMS['${platform}'] both runs and declines ` +
+            `${contradictory.join(', ')}. A transform cannot be in transforms and in ` +
+            'DECLINED_STOCK_TRANSFORMS at once — one of the two is wrong, and the ' +
+            'audit cannot tell which. This is a throughline packaging defect — ' +
+            'please report it.',
+        );
+      }
+    }
     const group = preset.stockGroup;
     if (!group || !Array.isArray(preset.transforms)) {
       warnings.push(
@@ -662,7 +736,7 @@ export function auditStockGroups(transformGroups) {
     const unaccounted = stock.filter(
       (name) =>
         !preset.transforms.includes(name) &&
-        !Object.hasOwn(DECLINED_STOCK_TRANSFORMS, name),
+        !Object.hasOwn(declined, name),
     );
     if (unaccounted.length) {
       const n = unaccounted.length;
@@ -764,8 +838,21 @@ export function nativePlatform({ platform, buildPath, className = 'Tokens', pack
     // Carried here, not left to the caller: authored() reads the ORIGINAL
     // $value, so without this preprocessor every aliased dimension still holds
     // an unresolved {spacing.space.4}, no size transform fires, and the build
-    // emits bare px literals. preprocess is idempotent, so a project that also
-    // declares it at top level is harmless.
+    // emits bare px literals.
+    //
+    // A project that ALSO declares this preprocessor at top level runs it twice,
+    // which is harmless in every shape measured — and is the wiring our own
+    // usage snippet shows, so it is the common case rather than a corner.
+    //
+    // Stated no wider than it holds (#90): preprocess is idempotent except where
+    // the hoist invents a name the second pass then classifies. `a.font` with a
+    // child `size` camel-joins to `a.fontSize`; the first pass correctly declines
+    // `size`, and the second sees a typographic member name the source never
+    // authored. It changes no emitted output — Style Dictionary runs
+    // typeDtcgDelegate between the two passes and types that child anyway, so
+    // both passes reach the same file — and the repair belongs with the hoist,
+    // which has no way to record the names it invented. Pinned by test rather
+    // than papered over.
     preprocessors: ['dtcg/resolve-dual-node'],
     buildPath,
     options: { outputReferences: false },

package/scripts/lib/dtcg.mjs

@@ -4,6 +4,8 @@
 
 const REF = /^\{([^}]+)\}$/;
 
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
 // The typographic member names DTCG §9.8 fixes at MUST level, the unit gate a
 // text-role dimension must pass, and this project's $extensions namespace.
 //
@@ -16,6 +18,42 @@ export const TEXT_UNIT_NAMES = new Set(['fontSize', 'letterSpacing', 'lineHeight
 export const TEXT_ROLE_UNIT = /^-?(?:\d+(?:\.\d+)?|\.\d+)(?:px|rem|em)$/;
 export const EXT_NS = 'com.radicool.throughline';
 
+// Read this project's $extensions namespace off a node, refusing a shape that
+// cannot hold one.
+//
+// A DTCG $extensions namespace key may hold ANY JSON value, so a source that
+// authored ours as a string is CONFORMANT input this module does not handle —
+// not malformed input. That distinction is why it gets a diagnostic rather than
+// a shrug: the module's contract is that it consumes conformant DTCG.
+//
+// Before #62 the three places that read this namespace all hit the `in`
+// operator on a primitive and threw a bare TypeError naming no token, no path
+// and no value — out of step with every other diagnostic here. nativeSources
+// names the colliding path and both files; the hoist-collision throw names both
+// paths and the value it would overwrite; nativePlatform names the unknown
+// platform and the expected set.
+export function extNamespace(node, path) {
+  const ext = node.$extensions;
+  if (ext === undefined) return undefined;
+  if (!isPlainObject(ext)) {
+    throw new Error(
+      `token "${path}" has a $extensions that is ${JSON.stringify(ext)}, not an object.\n` +
+        'DTCG 5.4 makes $extensions a map of namespace keys. Remove it, or give it the shape ' +
+        `{ "${EXT_NS}": { "nativeUnit": "text" } }.`,
+    );
+  }
+  const ns = ext[EXT_NS];
+  if (ns === undefined) return undefined;
+  if (!isPlainObject(ns)) {
+    throw new Error(
+      `token "${path}" has $extensions["${EXT_NS}"] set to ${JSON.stringify(ns)}, not an object.\n` +
+        `The namespace holds named settings, so a bare value cannot be read. Write ` +
+        `{ "nativeUnit": ${JSON.stringify(ns)} } if that is the setting you meant.`,
+    );
+  }
+  return ns;
+}
+
 // Flatten nested DTCG groups into { "dot.path": rawValue }. Skips $-prefixed meta keys.
 //
 // A node carrying BOTH a $value and children yields its own value AND is descended
@@ -63,6 +101,87 @@ export function flattenDtcgTypes(obj, prefix = [], out = {}, groupType = undefin
   return out;
 }
 
+// DTCG 5.2.2 PLUS the one repair this pipeline applies on top of it, so that
+// anything reasoning about what the build emits reads the same types the build
+// used. flattenDtcgTypes is the spec; this is the spec as this build resolves it.
+//
+// The repair is hoistDualNodes' $type carry. A dual node is a token, not a group
+// (DTCG 6.1), so it is not its children's inheritance source and 5.2.2 gives an
+// untyped child of one no type at all. The hoist then makes that child a sibling
+// of the dual node, which destroys the last relationship it had — so where NO
+// enclosing group supplies a type, the hoist stamps the dual node's own. That is
+// a repair for what the hoist broke, not a reading of the source, which is why
+// it does not belong in flattenDtcgTypes.
+//
+// It has to be modelled somewhere, though, because two things that reason about
+// types could not see it: classification, which runs before the hoist and so
+// declined a child the pipeline goes on to type (#89), and the unitless-dimension
+// advisory, which reads the raw source (#71). Both were silent on shapes the
+// build handles.
+//
+// The conditions mirror hoistDualNodes exactly — an untyped TOKEN child (#67
+// restricted it to those), a dual node that has a $type, no enclosing group type,
+// and a value that is not a whole-value reference. That last one is why this must
+// run on the RAW tree: resolveInPlace rewrites a reference to its literal, and
+// the WeakSet the hoist consults for it does not survive into a fresh call.
+//
+// Keyed on pre-hoist paths, like flattenDtcgTypes, because every consumer of this
+// map runs before the hoist or reports against source paths.
+export function flattenPipelineTypes(dict) {
+  const types = flattenDtcgTypes(dict);
+  (function walk(node, prefix, groupType) {
+    const inherited = '$value' in node ? groupType : (node.$type ?? groupType);
+    for (const [key, val] of Object.entries(node)) {
+      if (key.startsWith('$') || !isPlainObject(val)) continue;
+      const path = [...prefix, key];
+      if ('$value' in val && '$type' in val && inherited === undefined) {
+        for (const [childKey, childVal] of Object.entries(val)) {
+          if (childKey.startsWith('$') || !isPlainObject(childVal)) continue;
+          if ('$value' in childVal && !('$type' in childVal) && !REF.test(String(childVal.$value).trim())) {
+            types[[...path, childKey].join('.')] = val.$type;
+          }
+        }
+      }
+      walk(val, path, inherited);
+    }
+  })(dict, [], undefined);
+  return types;
+}
+
+// Collect nodes carrying BOTH a $value and child tokens or groups.
+//
+// This shape is invalid DTCG. Format Module, Draft Community Group Report of
+// 30 July 2026, §6.1: "The presence of a $value property definitively identifies
+// an object as a token. If an object contains both $value and child
+// tokens/groups, this creates an invalid structure where the object cannot be
+// both a token and a group simultaneously. Tools MUST report this as an error."
+// The prohibition is deliberate rather than an oversight — §6.2 defines $root as
+// the sanctioned way for a group to carry a base value alongside children, which
+// is exactly what a dual node is reaching for.
+//
+// Collecting them is NOT a step towards rejecting them. Figma-derived sources
+// emit dual nodes by the dozen, hoistDualNodes exists precisely to handle them,
+// and refusing them would make this tool useless against the sources it targets.
+// That behaviour is unchanged. What was missing is telling the author their
+// source is non-conforming, which nothing did — so someone hand-authoring
+// text.sm with both a value and a lineHeight child had no way to learn that
+// $root is the blessed spelling.
+//
+// Lives here because flattenDtcg already walks this tree and already descends
+// into dual nodes on purpose, so the knowledge is present and only the reporting
+// was absent.
+export function findDualNodes(obj, prefix = [], out = []) {
+  for (const [key, val] of Object.entries(obj)) {
+    if (key.startsWith('$') || !isPlainObject(val)) continue;
+    const path = [...prefix, key];
+    if ('$value' in val && Object.entries(val).some(([k, v]) => !k.startsWith('$') && isPlainObject(v))) {
+      out.push(path.join('.'));
+    }
+    findDualNodes(val, path, out);
+  }
+  return out;
+}
+
 // Follow {alias} chains to a leaf literal. Throws on missing or circular refs.
 export function resolveValue(name, flat, seen = new Set()) {
   if (!(name in flat)) throw new Error(`token "${name}" not found in DTCG source`);
@@ -104,7 +223,6 @@ export function findModeCollisions(sources) {
 //
 // Each source is cloned on the way in. Merging the caller's own objects would
 // mutate the token trees it still holds, and the validator reads them again.
-const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
 
 function mergeInto(target, src) {
   for (const [key, val] of Object.entries(src)) {
@@ -196,7 +314,7 @@ export function textRoleGraph(dict) {
         types[dotted] === 'dimension' &&
         TEXT_ROLE_UNIT.test(String(val.$value).trim()) &&
         !referrers.has(dotted) &&
-        !('nativeUnit' in (val.$extensions?.[EXT_NS] ?? {})) &&
+        !('nativeUnit' in (extNamespace(val, dotted) ?? {})) &&
         inferredGroups.has(group)
       ) {
         unreferencedSiblings.push({ path: dotted, group });

package/scripts/lib/native-literal.mjs

@@ -64,8 +64,28 @@ export const GRAMMAR = {
 // `var` are valid identifiers, and `color-mix` has a rescue in sd-native.mjs
 // that merely did not match this variant. So they must reach the output and
 // fail loudly under no-foreign-syntax, never be silently dropped by a filter.
-// Kept here, beside the grammar, so the build and the gate cannot drift apart.
-export const CSS_CONSTRUCT = /^(?:color-mix|calc|var)\s*\(/;
+// Kept here, beside the grammar, so the build and the gate cannot drift apart —
+// which until #57 was a promise this file made and did not keep. The gate
+// defined its own independent copy of the same alternation, so adding a fourth
+// name here would have taught the filter to keep a construct the gate had never
+// been taught to name. One list now, two anchorings derived from it.
+//
+// The BUILD anchors: only a construct that LEADS the value is exempt from the
+// output filter, because only then is the whole value the unimplemented rescue.
+// The GATE does not anchor: it names the construct wherever it appears.
+//
+// The asymmetry is deliberate and it is a stated limit, not a closed class.
+// `rgba(var(--brand), 0.5)` is dropped by the filter rather than kept, because
+// the module cannot tell an unimplemented rescue nested inside a rescuable
+// function from one nested inside `linear-gradient(...)`, which has no native
+// form at any depth. Closing that needs a notion of which outer functions are
+// rescuable, which does not exist here. What #57 does instead is make the drop
+// NAMED rather than counted — see the unemitted-token report in
+// validate-token-output.mjs.
+export const CSS_CONSTRUCT_NAMES = ['color-mix', 'calc', 'var'];
+const CSS_CONSTRUCT_ALT = CSS_CONSTRUCT_NAMES.join('|');
+export const CSS_CONSTRUCT = new RegExp(`^(?:${CSS_CONSTRUCT_ALT})\\s*\\(`);
+export const CSS_CONSTRUCT_ANYWHERE = new RegExp(`(?:${CSS_CONSTRUCT_ALT})\\s*\\(`);
 
 export function parseLiteral(value, grammar = {}) {
   const s = String(value);

package/scripts/lib/sd-native.mjs

@@ -12,7 +12,8 @@
 import { readFileSync } from 'node:fs';
 import {
   flattenDtcg,
-  flattenDtcgTypes,
+  flattenPipelineTypes,
+  extNamespace,
   resolveValue,
   findModeCollisions,
   TEXT_UNIT_NAMES,
@@ -83,10 +84,25 @@ export function colorMixToHex8(value) {
 // Marks a node whose AUTHORED $value was a whole-value reference, so the hoist
 // can decline to override the type DTCG 5.2.2 rule 1 already determined from the
 // referent. A WeakSet keyed on the node object, rather than a property written
-// onto it, holds structural idempotency exactly: structuredClone drops the
-// membership along with the rest of the identity, so preprocess(preprocess(x))
-// is deepEqual to preprocess(x) with no leak question to manage.
+// onto it, keeps this mechanism from leaking across calls: structuredClone
+// drops the membership along with the rest of the identity, so a second pass
+// starts clean rather than inheriting the first pass's marks. That is exactly
+// what a property written onto the node would get wrong. It is not on its own a
+// guarantee that preprocess is idempotent — see the limit recorded at
+// nativePlatform's preprocessors line (#90).
 const WAS_REF = new WeakSet();
+
+// The path the AUTHOR wrote for a node the hoist has moved. hoistDualNodes
+// recurses depth-first, so by the time an outer frame takes Object.entries it
+// already contains names the inner frame synthesised — and a collision reported
+// from that frame named a path appearing nowhere in the source (#61). Recording
+// the authored path when a node is hoisted lets the outer frame report what the
+// author can actually search for.
+//
+// Keyed on node identity, like WAS_REF, and safe across calls for the same
+// reason: preprocess structuredClones its input, so every call works on fresh
+// objects.
+const AUTHORED_PATH = new WeakMap();
 const WHOLE_REF = /^\{[^}]+\}$/;
 
 function interpolate(value, flat) {
@@ -159,20 +175,27 @@ function hoistDualNodes(node, collisions, prefix = [], groupType = undefined) {
       for (const [childKey, childVal] of Object.entries(val)) {
         if (childKey.startsWith('$') || !childVal || typeof childVal !== 'object') continue;
         const hoisted = key + childKey[0].toUpperCase() + childKey.slice(1);
-        const from = [...prefix, key, childKey].join('.');
+        const from = AUTHORED_PATH.get(childVal) ?? [...prefix, key, childKey].join('.');
         if (Object.hasOwn(node, hoisted)) {
           const existingNode = node[hoisted];
-          const isGroup = existingNode !== null && typeof existingNode === 'object' && !('$value' in existingNode);
+          // An array has no $value either, and was therefore labelled "(a group)"
+          // (#61). It is neither — an array at this position is malformed DTCG.
+          // Say so, rather than naming a shape the author will go looking for.
+          const isArray = Array.isArray(existingNode);
+          const isGroup =
+            existingNode !== null && typeof existingNode === 'object' && !isArray && !('$value' in existingNode);
           collisions.push({
             from,
             onto: [...prefix, hoisted].join('.'),
             isGroup,
+            isArray,
             claimant: claimedBy.get(hoisted),
-            existing: isGroup
-              ? undefined
-              : existingNode && typeof existingNode === 'object'
-                ? existingNode.$value
-                : existingNode,
+            existing:
+              isGroup || isArray
+                ? undefined
+                : existingNode && typeof existingNode === 'object'
+                  ? existingNode.$value
+                  : existingNode,
           });
           continue;
         }
@@ -195,8 +218,17 @@ function hoistDualNodes(node, collisions, prefix = [], groupType = undefined) {
         // type suits the child badly, because the hoist is not entitled to
         // improve on what the source says; but the carry firing at all is the
         // hoist saying something the source did not.
+        //
+        // A GROUP child is excluded (#67). The carry's premise is that the dual
+        // node was the child's closest $type-bearing ancestor as authored, and
+        // the hoist took that away. For a group child the premise never held:
+        // 5.2.2 inherits from the closest parent GROUP, the dual node is not
+        // one, so it was never that group's inheritance source and the hoist
+        // removed nothing. Carrying there does not repair, it invents — and it
+        // invents for every token beneath the group, not just one node.
         if (
           !('$type' in childVal) &&
+          '$value' in childVal &&
           '$type' in val &&
           !WAS_REF.has(childVal) &&
           inherited === undefined
@@ -204,6 +236,7 @@ function hoistDualNodes(node, collisions, prefix = [], groupType = undefined) {
           childVal.$type = val.$type;
         }
         node[hoisted] = childVal;
+        AUTHORED_PATH.set(childVal, from);
         delete val[childKey];
         claimedBy.set(hoisted, from);
       }
@@ -302,6 +335,9 @@ function classifyTextUnits(node, types, prefix = []) {
       types[path.join('.')] === 'dimension' &&
       TEXT_ROLE_UNIT.test(String(val.$value).trim())
     ) {
+      // extNamespace throws with the token path if the source authored either
+      // level as a primitive — legal DTCG this module does not handle (#62).
+      extNamespace(val, path.join('.'));
       val.$extensions ??= {};
       val.$extensions[EXT_NS] ??= {};
       const ns = val.$extensions[EXT_NS];
@@ -310,7 +346,9 @@ function classifyTextUnits(node, types, prefix = []) {
       // one, so a unitless value is declined by every size transform regardless
       // of what is stamped here (see isRatio, #52). Declining to overwrite IS
       // the feature: it costs no configuration parameter, and it is what makes
-      // the pass idempotent.
+      // STAMPING idempotent — a second pass never rewrites a role a first pass
+      // set. What it does not settle is whether a second pass finds the same
+      // candidates; the hoist can rename a node between the two (#90).
       if (!('nativeUnit' in ns)) ns.nativeUnit = 'text';
     }
     classifyTextUnits(val, types, path);
@@ -333,7 +371,8 @@ function classifyTextUnits(node, types, prefix = []) {
 // A path may name no node at all. resolveInPlace deliberately leaves an
 // unresolvable reference in place for Style Dictionary to report, so the graph
 // can hold an edge to a token that does not exist. Skip it. This is also what
-// keeps the second preprocess pass from throwing, and idempotency with it.
+// keeps the second preprocess pass from throwing — which is a precondition for
+// idempotency, not the whole of it (#90).
 function applyTextRoleGraph(node, typographic, types) {
   for (const path of typographic) {
     let target = node;
@@ -343,6 +382,7 @@ function applyTextRoleGraph(node, typographic, types) {
     if (!target || typeof target !== 'object' || !('$value' in target)) continue;
     if (types[path] !== 'dimension') continue;
     if (!TEXT_ROLE_UNIT.test(String(target.$value).trim())) continue;
+    extNamespace(target, path);
     target.$extensions ??= {};
     target.$extensions[EXT_NS] ??= {};
     const ns = target.$extensions[EXT_NS];
@@ -357,14 +397,16 @@ export function preprocess(dict) {
   // the graph is made of.
   const { typographic } = textRoleGraph(dict);
   const resolved = resolveInPlace(structuredClone(dict), flattenDtcg(dict));
-  // DTCG 5.2.2 types for the whole tree, walked once and shared by both passes
-  // below. Neither writes $type or moves a node, so one map is correct for
-  // both, and sharing it is what makes them agree by construction rather than
-  // by two copies of the same rule staying in step (#85).
+  // Types for the whole tree, walked once and shared by both passes below.
+  // Neither writes $type or moves a node, so one map is correct for both, and
+  // sharing it is what makes them agree by construction rather than by two
+  // copies of the same rule staying in step (#85).
   //
-  // Computed on the RESOLVED clone, which is the tree both passes read.
-  // resolveInPlace rewrites $value strings only, so the types are the source's.
-  const types = flattenDtcgTypes(resolved);
+  // Computed on the RAW dict, not the resolved clone. resolveInPlace only
+  // rewrites $value strings, so paths and types are identical between the two —
+  // except for the carry, whose rule asks whether a value WAS a whole-value
+  // reference, and resolution has already destroyed that (#89).
+  const types = flattenPipelineTypes(dict);
   const out = hoistDualNodes(
     applyTextRoleGraph(classifyTextUnits(resolved, types), typographic, types),
     collisions,
@@ -374,6 +416,9 @@ export function preprocess(dict) {
       .slice(0, 5)
       .map((c) => {
         const line = `  ${c.from} -> ${c.onto}`;
+        if (c.isArray) {
+          return line + ' (an array — neither a token nor a group, and not valid DTCG here)';
+        }
         if (c.isGroup) {
           return line + (c.claimant ? ` (a group, already claimed by the hoist of ${c.claimant})` : ' (a group)');
         }
@@ -501,7 +546,14 @@ const DECLINED_STOCK_TRANSFORMS = {
 // Order is never compared: our lists are hand-ordered for our own reasons and
 // do not inherit stock order. Removals are never reported: a declined name
 // disappearing is a non-event.
-export function auditStockGroups(transformGroups) {
+// `platforms` and `declined` are parameters with the shipped config as their
+// default, so the contradiction branch below is reachable from a test. The
+// single caller passes neither; the audit's contract is unchanged.
+export function auditStockGroups(
+  transformGroups,
+  platforms = PLATFORMS,
+  declined = DECLINED_STOCK_TRANSFORMS,
+) {
   if (typeof transformGroups !== 'object' || transformGroups === null) {
     return [
       "throughline: could not read Style Dictionary's stock transform groups " +
@@ -510,7 +562,29 @@ export function auditStockGroups(transformGroups) {
     ];
   }
   const warnings = [];
-  for (const [platform, preset] of Object.entries(PLATFORMS)) {
+  for (const [platform, preset] of Object.entries(platforms)) {
+    // A name in BOTH lists is a contradiction the unaccounted filter below
+    // cannot see, because either membership alone suppresses the warning (#75).
+    // The config would be saying "we run this" and "we deliberately do not" at
+    // once, and whichever is wrong is silently the loser: if the decline is
+    // right the transform still runs, and if the run is right the decline is a
+    // lie the next maintainer will read as settled. Reported here rather than
+    // guarded at the definition, so it travels with the rest of the audit.
+    //
+    // Checked before stockGroup, because this is wrong regardless of whether
+    // Style Dictionary still has the group to compare against.
+    if (Array.isArray(preset.transforms)) {
+      const contradictory = preset.transforms.filter((name) => Object.hasOwn(declined, name));
+      if (contradictory.length) {
+        warnings.push(
+          `throughline: PLATFORMS['${platform}'] both runs and declines ` +
+            `${contradictory.join(', ')}. A transform cannot be in transforms and in ` +
+            'DECLINED_STOCK_TRANSFORMS at once — one of the two is wrong, and the ' +
+            'audit cannot tell which. This is a throughline packaging defect — ' +
+            'please report it.',
+        );
+      }
+    }
     const group = preset.stockGroup;
     if (!group || !Array.isArray(preset.transforms)) {
       warnings.push(
@@ -534,7 +608,7 @@ export function auditStockGroups(transformGroups) {
     const unaccounted = stock.filter(
       (name) =>
         !preset.transforms.includes(name) &&
-        !Object.hasOwn(DECLINED_STOCK_TRANSFORMS, name),
+        !Object.hasOwn(declined, name),
     );
     if (unaccounted.length) {
       const n = unaccounted.length;
@@ -636,8 +710,21 @@ export function nativePlatform({ platform, buildPath, className = 'Tokens', pack
     // Carried here, not left to the caller: authored() reads the ORIGINAL
     // $value, so without this preprocessor every aliased dimension still holds
     // an unresolved {spacing.space.4}, no size transform fires, and the build
-    // emits bare px literals. preprocess is idempotent, so a project that also
-    // declares it at top level is harmless.
+    // emits bare px literals.
+    //
+    // A project that ALSO declares this preprocessor at top level runs it twice,
+    // which is harmless in every shape measured — and is the wiring our own
+    // usage snippet shows, so it is the common case rather than a corner.
+    //
+    // Stated no wider than it holds (#90): preprocess is idempotent except where
+    // the hoist invents a name the second pass then classifies. `a.font` with a
+    // child `size` camel-joins to `a.fontSize`; the first pass correctly declines
+    // `size`, and the second sees a typographic member name the source never
+    // authored. It changes no emitted output — Style Dictionary runs
+    // typeDtcgDelegate between the two passes and types that child anyway, so
+    // both passes reach the same file — and the repair belongs with the hoist,
+    // which has no way to record the names it invented. Pinned by test rather
+    // than papered over.
     preprocessors: ['dtcg/resolve-dual-node'],
     buildPath,
     options: { outputReferences: false },

package/scripts/validate-token-output.mjs

@@ -10,13 +10,15 @@ import { pathToFileURL } from 'node:url';
 import {
   flattenDtcg,
   flattenDtcgTypes,
+  flattenPipelineTypes,
+  findDualNodes,
   resolveValue,
   findModeCollisions,
   textRoleGraph,
   mergeDtcg,
   EXT_NS,
 } from './lib/dtcg.mjs';
-import { parseLiteral, isValidLiteral, GRAMMAR } from './lib/native-literal.mjs';
+import { parseLiteral, isValidLiteral, GRAMMAR, CSS_CONSTRUCT_ANYWHERE } from './lib/native-literal.mjs';
 
 // Re-exported so consumers (and the test file) keep one import surface.
 export { flattenDtcg, flattenDtcgTypes, resolveValue, findModeCollisions };
@@ -68,6 +70,34 @@ export function normalizeKey(s) {
   return String(s).toLowerCase().replace(/[^a-z0-9]/g, '');
 }
 
+// Two source paths that normalize to one key, e.g. color.bg.canvas and
+// colorBg.canvas -> colorbgcanvas. Same map-and-compare shape as
+// findModeCollisions, keyed on the normalized form instead of the raw path.
+//
+// This is not only a matching problem, which is why it gates rather than
+// advises. Measured through Style Dictionary on that exact pair: the build
+// emits `val colorBgCanvas` TWICE and kotlinc rejects the file with
+// "conflicting declarations". The source is ambiguous for native output, and
+// the emitted file does not compile.
+//
+// Before this, the second path silently overwrote the first in byKey, with a
+// consequence in each direction: the loser was never checked at all, and every
+// emitted symbol sharing the key was compared against whichever path happened
+// to sort last — which reported a unit-fidelity failure naming a token that was
+// correct. A wrong diagnosis is worse than none, because it sends the author to
+// the wrong file.
+export function findNormalizationCollisions(paths) {
+  const byKey = new Map();
+  for (const path of paths) {
+    const key = normalizeKey(path);
+    if (!byKey.has(key)) byKey.set(key, []);
+    byKey.get(key).push(path);
+  }
+  return [...byKey]
+    .filter(([, ps]) => ps.length > 1)
+    .map(([key, ps]) => ({ key, paths: ps }));
+}
+
 const UNIT = /^(-?(?:\d+(?:\.\d+)?|\.\d+))([a-z%]*)$/;
 
 // Expected native magnitude for an authored source value. iOS points and Android
@@ -101,7 +131,21 @@ export function expectedMagnitude(sourceValue) {
 // "var(" (e.g. a $type: string value describing CSS) would also match. The
 // isValidLiteral gate below is what tells those apart: a value the grammar
 // accepts as a literal is not foreign syntax, whatever text it contains.
-const FOREIGN = /(?:color-mix|calc|var)\s*\(/;
+//
+// That holds for Swift. It does NOT hold unconditionally for Kotlin (#57):
+// `${...}` inside a Kotlin string is executable code, and the grammar accepts an
+// unescaped `$`, so `"${calc(1)}"` parses as a valid literal and is exempted
+// here. The exemption also covers a small set of values that are well-formed
+// literals AND named-foreign — calc(2), var(1), and on Kotlin calc(2.dp) — which
+// are kept, pass every rule, and do not compile. None is producible CSS, and
+// this was shipped knowingly when the gate was added; it is written down so the
+// next person meets it as a decision rather than a surprise.
+// Imported, not redeclared (#57). This was an independent copy of the same
+// alternation, while native-literal.mjs's comment promised the build and the
+// gate could not drift apart. Adding a fourth construct name there would have
+// taught the output filter to keep something this rule had never been taught to
+// name — recreating exactly the unreachable-rule defect #56 fixed.
+const FOREIGN = CSS_CONSTRUCT_ANYWHERE;
 const BARE_UNIT = /^-?(?:\d+(?:\.\d+)?|\.\d+)(?:px|rem|em|%)$/;
 
 // #52. A unitless value is a ratio, not a measurement: DTCG 8.2.1 requires a
@@ -117,6 +161,18 @@ const DIMENSIONAL = new Set(['dimension', 'fontSize']);
 // alone would flag both the alias and its referent for the same problem.
 const WHOLE_REF = /^\{[^}]+\}$/;
 
+// Follow whole-value references to the token an advisory's fix belongs on.
+// Stops at the first path that is not a whole-value reference, at an
+// unresolvable one, and on a cycle — this reports, so it must never throw.
+function referentOf(path, flat, seen = new Set()) {
+  const raw = String(flat[path] ?? '').trim();
+  if (!WHOLE_REF.test(raw)) return path;
+  const next = raw.slice(1, -1);
+  if (seen.has(path) || !(next in flat)) return path;
+  seen.add(path);
+  return referentOf(next, flat, seen);
+}
+
 // Lines that are obviously not a would-be token declaration: braces-only,
 // comments, imports/package/annotations, or the container declarations
 // (enum/object/class) themselves. Anything else that DECL failed to match is
@@ -149,10 +205,33 @@ export function validate({ sources, output, platform, minMatch = 0.5 }) {
   for (const { dtcg } of sources) Object.assign(flat, flattenDtcg(dtcg));
 
   const types = {};
-  for (const { dtcg } of sources) Object.assign(types, flattenDtcgTypes(dtcg));
+  // The PIPELINE's types, not the spec's alone (#71). flattenDtcgTypes reads the
+  // raw source, where hoistDualNodes' $type carry has not run — so a unitless,
+  // untyped child of a dimension-typed dual node was a dimension to the build
+  // and a nothing to this gate, which is the silent case this rule most exists
+  // to catch.
+  //
+  // The issue framed the only fix as running this gate against the PREPROCESSED
+  // tree, and rejected it, because the gate would stop checking emitted output
+  // against what the author actually wrote. flattenPipelineTypes is a third
+  // option that keeps that property: it reads the raw source and MODELS the
+  // carry rather than applying it. The gate still reads what the author wrote.
+  for (const { dtcg } of sources) Object.assign(types, flattenPipelineTypes(dtcg));
+
+  // Collided keys are deliberately LEFT OUT of byKey. A symbol whose key is
+  // ambiguous then matches nothing, so it falls through to `continue` before any
+  // source comparison and is not counted as matched — which is the truth: it did
+  // not match a determinate token. That removes the false unit-fidelity failure
+  // without a special case in the loop below. The literal, foreign-syntax and
+  // bare-unit rules still run on it, because none of them reads the source.
+  const normalizationCollisions = findNormalizationCollisions(Object.keys(flat));
+  const collided = new Set(normalizationCollisions.map((c) => c.key));
 
   const byKey = new Map();
-  for (const path of Object.keys(flat)) byKey.set(normalizeKey(path), path);
+  for (const path of Object.keys(flat)) {
+    const key = normalizeKey(path);
+    if (!collided.has(key)) byKey.set(key, path);
+  }
 
   const decls = extractDeclarations(output, platform);
   const failures = [];
@@ -197,19 +276,35 @@ export function validate({ sources, output, platform, minMatch = 0.5 }) {
     // Advisory, not a failure: the emitted value is correct under the ratio
     // reading this build applies, so it compiles and its magnitude matches.
     // What is wrong is the SOURCE's $type, which only the author can settle.
+    //
+    // An alias is skipped only when its REFERENT is itself dimension-typed, so
+    // the referent's own symbol reports it — that is #69's de-duplication, kept.
+    // A blanket skip on any whole-value reference (#72) meant an untyped base
+    // behind a typed alias was reported nowhere: the base is not dimension-typed
+    // so it never fires, and the alias was skipped for being a reference. The
+    // advisory is attributed to the referent either way, because that is the
+    // token whose $type or unit the author has to change.
+    const aliased = WHOLE_REF.test(String(flat[path]).trim());
+    const target = aliased ? referentOf(path, flat) : path;
     if (
       UNITLESS.test(String(source).trim()) &&
       DIMENSIONAL.has(types[path]) &&
-      !WHOLE_REF.test(String(flat[path]).trim())
+      !(aliased && DIMENSIONAL.has(types[target]))
     ) {
-      advisories.push({ rule: 'unitless-dimension', symbol, token: path, source, emitted: value });
+      advisories.push({ rule: 'unitless-dimension', symbol, token: target, source, emitted: value });
     }
 
     const expected = expectedMagnitude(source);
     if (expected.skip) continue;
     const actual = magnitudeOf(value);
     if (actual === null) {
-      failures.push({ rule: 'unverifiable-dimension', symbol, token: path, source, emitted: value });
+      // no-foreign-syntax already explains why the magnitude could not be read,
+      // and names the actual cause. "The token was never actually compared" beside
+      // it is a red herring pointing at the symptom (#57). Same suppression the
+      // three literal rules already apply to each other.
+      if (!foreign) {
+        failures.push({ rule: 'unverifiable-dimension', symbol, token: path, source, emitted: value });
+      }
       continue;
     }
     if (Math.abs(actual - expected.magnitude) > 0.001) {
@@ -227,6 +322,24 @@ export function validate({ sources, output, platform, minMatch = 0.5 }) {
   // build that actually ran, and a build merges with the later source winning.
   // A union would call a token referenced when this build did not reach it,
   // under-reporting the gap in the one direction that matters.
+  // #58. A node carrying both a $value and children is invalid DTCG (§6.1, and
+  // §6.2 defines $root as the sanctioned spelling), and nothing told the author
+  // so. ADVISORY, not a failure, and deliberately: every Figma-derived source
+  // has dozens — the real one this is validated against has 13 — so failing on
+  // it would make the gate useless on day one for exactly the people this tool
+  // targets. The build keeps handling them; the author now learns the shape is
+  // non-conforming and what to write instead.
+  //
+  // One advisory for the whole finding rather than one per node. It is a single
+  // structural fact about the source, and thirteen near-identical lines would
+  // bury the rest of the report.
+  //
+  // Read per source file, not from the merged dict: a merge can conceal a dual
+  // node whose children come from one file and whose $value comes from another,
+  // and the author fixes this file by file.
+  const dualNodes = [...new Set(sources.flatMap((s) => findDualNodes(s.dtcg)))];
+  if (dualNodes.length) advisories.push({ rule: 'dual-node', paths: dualNodes });
+
   const graph = textRoleGraph(mergeDtcg(sources.map((s) => s.dtcg)));
   for (const { path, group } of graph.unreferencedSiblings) {
     advisories.push({ rule: 'unreferenced-text-sibling', token: path, group });
@@ -236,14 +349,26 @@ export function validate({ sources, output, platform, minMatch = 0.5 }) {
   }
 
   const matchRate = decls.length ? matched / decls.length : 0;
-  const ok = failures.length === 0 && collisions.length === 0 && matched > 0 && matchRate >= minMatch;
+  const ok =
+    failures.length === 0 &&
+    collisions.length === 0 &&
+    normalizationCollisions.length === 0 &&
+    matched > 0 &&
+    matchRate >= minMatch;
 
   const unparsedLines = countUnparsedLines(output, DECL[platform]);
+  // NAMED, not just counted (#57). A token with no native form is filtered out
+  // of native output, and a nested construct like rgba(var(--brand), 0.5) is one
+  // of them — the filter's exemption is anchored, deliberately, because the
+  // module cannot tell a rescuable outer function from linear-gradient(). Before
+  // this the only trace such a token left was a number, which is the same
+  // silence this release exists to remove everywhere else.
   const emittedKeys = new Set(decls.map((d) => normalizeKey(d.symbol)));
-  let unemittedTokens = 0;
-  for (const key of byKey.keys()) if (!emittedKeys.has(key)) unemittedTokens += 1;
+  const unemittedPaths = [];
+  for (const [key, path] of byKey) if (!emittedKeys.has(key)) unemittedPaths.push(path);
+  const unemittedTokens = unemittedPaths.length;
 
-  return { total: decls.length, matched, matchRate, failures, advisories, collisions, minMatch, ok, unparsedLines, unemittedTokens };
+  return { total: decls.length, matched, matchRate, failures, advisories, collisions, normalizationCollisions, minMatch, ok, unparsedLines, unemittedTokens, unemittedPaths };
 }
 
 export function formatReport(r) {
@@ -256,6 +381,17 @@ export function formatReport(r) {
       lines.push(`  - ${c.path}: ${c.defs.map((d) => `${d.file}=${JSON.stringify(d.value)}`).join(', ')}`);
     }
   }
+  if (r.normalizationCollisions?.length) {
+    lines.push(
+      `\n${r.normalizationCollisions.length} name collision(s) — distinct source paths that reduce to one symbol name:`,
+    );
+    for (const c of r.normalizationCollisions) {
+      lines.push(`  - ${c.key}: ${c.paths.join(' vs ')}`);
+    }
+    lines.push(
+      `\nThese emit the same symbol name, so the generated file declares it more than once and will not compile. They are also excluded from matching above, because there is no way to tell which source token an emitted symbol came from. Rename one side in source.`,
+    );
+  }
   if (r.failures.length) {
     lines.push(`\n${r.failures.length} rule failure(s):`);
     for (const f of r.failures) {
@@ -275,10 +411,20 @@ export function formatReport(r) {
       );
     }
   }
+  // The naming-convention diagnosis is wrong when collisions are what removed
+  // the tokens, and a confident wrong cause sends the author to the wrong file.
+  // Name the collisions instead, and only then fall back to the convention.
+  const collisionNote = r.normalizationCollisions?.length
+    ? ` The ${r.normalizationCollisions.length} name collision(s) above were excluded from matching, which may be the whole of it — resolve those first.`
+    : '';
   if (r.matched === 0) {
-    lines.push(`\nNo emitted symbol matched any source token — the adapter's naming convention does not line up, so nothing was actually verified. A likely cause is a declaration form the DECL pattern does not match (e.g. a different accessControl such as "internal static let ...").`);
+    lines.push(
+      r.normalizationCollisions?.length
+        ? `\nNo emitted symbol matched any source token, so nothing was actually verified.${collisionNote}`
+        : `\nNo emitted symbol matched any source token — the adapter's naming convention does not line up, so nothing was actually verified. A likely cause is a declaration form the DECL pattern does not match (e.g. a different accessControl such as "internal static let ...").`,
+    );
   } else if (r.matchRate < r.minMatch) {
-    lines.push(`\nMatch rate ${pct}% is below the ${(r.minMatch * 100).toFixed(0)}% floor — most output went unchecked.`);
+    lines.push(`\nMatch rate ${pct}% is below the ${(r.minMatch * 100).toFixed(0)}% floor — most output went unchecked.${collisionNote}`);
   }
   if (r.unparsedLines) {
     lines.push(`\n${r.unparsedLines} unparsed line(s) — declaration-shaped lines the extractor could not read; they count in neither the numerator nor the denominator above.`);
@@ -292,6 +438,14 @@ export function formatReport(r) {
         );
         continue;
       }
+      if (a.rule === 'dual-node') {
+        const shown = a.paths.slice(0, 5).join(', ');
+        const more = a.paths.length > 5 ? `, ...and ${a.paths.length - 5} more` : '';
+        lines.push(
+          `  - [${a.rule}] ${a.paths.length} node(s) carry both a $value and child tokens: ${shown}${more}. DTCG §6.1 makes that invalid — an object cannot be both a token and a group — and §6.2 defines $root as the way a group carries a base value alongside children. The build handles this shape and will keep handling it; nothing here is broken. Rewrite them as $root only if you want the source to conform.`,
+        );
+        continue;
+      }
       if (a.rule === 'ambiguous-text-role') {
         lines.push(
           `  - [${a.rule}] ${a.token}: referenced both by typographic member(s) [${a.textLeaves.join(', ')}] and by [${a.otherLeaves.join(', ')}], so no role was inferred rather than a role being guessed. Stamp $extensions["${EXT_NS}"].nativeUnit in source to settle it.`,
@@ -304,7 +458,13 @@ export function formatReport(r) {
     }
   }
   if (r.unemittedTokens) {
-    lines.push(`\n${r.unemittedTokens} source token(s) had no matching emitted symbol.`);
+    const paths = r.unemittedPaths ?? [];
+    const shown = paths.slice(0, 10).join(', ');
+    const more = paths.length > 10 ? `, ...and ${paths.length - 10} more` : '';
+    lines.push(
+      `\n${r.unemittedTokens} source token(s) had no matching emitted symbol${paths.length ? `: ${shown}${more}` : ''}.` +
+        ' A value with no native form is filtered out of native output rather than emitted broken — a CSS construct nested inside another function is the common case.',
+    );
   }
   return lines;
 }