@radicool/throughline 0.16.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@radicool/throughline",
-  "version": "0.16.0",
+  "version": "0.17.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

@@ -52,7 +52,15 @@ consumer's repo.
 
 ```js
 import { readFileSync } from 'node:fs';
-import { flattenDtcg, resolveValue, findModeCollisions } from './dtcg.mjs';
+import {
+  flattenDtcg,
+  resolveValue,
+  findModeCollisions,
+  TEXT_UNIT_NAMES,
+  TEXT_ROLE_UNIT,
+  EXT_NS,
+  textRoleGraph,
+} from './dtcg.mjs';
 import { isValidLiteral, GRAMMAR, CSS_CONSTRUCT } from './native-literal.mjs';
 ```
 
@@ -295,11 +303,16 @@ function hoistDualNodes(node, collisions, prefix = [], groupType = undefined) {
 // sibling tokens in a group. Reading them there mirrors the spec's vocabulary;
 // it is not a guarantee the spec makes. A source naming its font size
 // typography.body.size sets $extensions itself and is honoured below.
-const TEXT_UNIT_NAMES = new Set(['fontSize', 'letterSpacing', 'lineHeight']);
+//
+// Defined in lib/dtcg.mjs and imported above, so textRoleGraph applies the
+// identical set. Two definitions of this set would drift.
 
 // Reverse-DNS, per DTCG's $extensions convention. Exported because the
 // transforms and their tests address the same key.
-export const EXT_NS = 'com.radicool.throughline';
+//
+// Defined in lib/dtcg.mjs and re-exported here: the transforms and their tests
+// address this key through sd-native.mjs, and that surface does not move.
+export { EXT_NS };
 
 // px and rem only. magnitude() reads a bare number as an unscaled ratio, so a
 // lineHeight authored "1.5" would otherwise be stamped and emit 1.50.sp —
@@ -313,7 +326,9 @@ export const EXT_NS = 'com.radicool.throughline';
 // em-valued letterSpacing is a text-role dimension like any other. It is still
 // a unit — the gate's job is to exclude the UNITLESS value, whose role the
 // source never stated.
-const TEXT_ROLE_UNIT = /^-?(?:\d+(?:\.\d+)?|\.\d+)(?:px|rem|em)$/;
+//
+// Defined in lib/dtcg.mjs and imported above, for the same reason as
+// TEXT_UNIT_NAMES: textRoleGraph gates on it too.
 
 // Runs AFTER resolveInPlace and BEFORE hoistDualNodes. Both halves matter.
 //
@@ -352,10 +367,47 @@ function classifyTextUnits(node) {
   return node;
 }
 
+// Runs AFTER classifyTextUnits and BEFORE hoistDualNodes, on the SAME two
+// grounds that pass gives: after, so a role the source or the member name
+// already stated wins; before, because the hoist rewrites text.xs.lineHeight to
+// text.xsLineHeight and the graph's paths are written in pre-hoist names.
+//
+// The three gates are classifyTextUnits's, verbatim — a dimension, a value with
+// a unit, and no role already recorded. A unitless value is never stamped: no
+// size transform claims one since #52, and stamping a ratio as text would still
+// be a claim the source never made.
+//
+// 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.
+function applyTextRoleGraph(node, typographic) {
+  for (const path of typographic) {
+    let target = node;
+    for (const segment of path.split('.')) {
+      target = target && typeof target === 'object' ? target[segment] : undefined;
+    }
+    if (!target || typeof target !== 'object' || !('$value' in target)) continue;
+    if (target.$type !== 'dimension') continue;
+    if (!TEXT_ROLE_UNIT.test(String(target.$value).trim())) continue;
+    target.$extensions ??= {};
+    target.$extensions[EXT_NS] ??= {};
+    const ns = target.$extensions[EXT_NS];
+    if (!('nativeUnit' in ns)) ns.nativeUnit = 'text';
+  }
+  return node;
+}
+
 export function preprocess(dict) {
   const collisions = [];
+  // Read from the UNRESOLVED dict, before resolveInPlace flattens the aliases
+  // the graph is made of.
+  const { typographic } = textRoleGraph(dict);
   const out = hoistDualNodes(
-    classifyTextUnits(resolveInPlace(structuredClone(dict), flattenDtcg(dict))),
+    applyTextRoleGraph(
+      classifyTextUnits(resolveInPlace(structuredClone(dict), flattenDtcg(dict))),
+      typographic,
+    ),
     collisions,
   );
   if (collisions.length) {
@@ -400,10 +452,14 @@ now emit `sp`, with the Swift output byte-identical.
 
 What remains:
 
-- **A bare scale primitive emits as `dp`.** `text.base: "16px"` is a font size
-  only to a human — no nominal or structural signal marks it — so it is not
-  stamped. The semantic tokens that reference it are, and those are what a
-  consumer should reach for.
+- **A scale primitive nothing references emits as `dp`.** `text.base: "16px"`
+  is a font size only to a human, so #63 takes the role from the reference
+  graph instead: a dimension referenced only by `fontSize`, `letterSpacing` or
+  `lineHeight` members is stamped typographic too. That is structural rather
+  than nominal, so it needs no path convention. A primitive **nothing**
+  references has no signal at all and is not inferred —
+  `tokens:validate-output` names it with an `unreferenced-text-sibling`
+  advisory, and a source-side `nativeUnit` stamp settles it.
 - **An `em` letter spacing reaches Compose but not Swift.** `size/unit-aware/compose-em`
   emits it as a real `.em` TextUnit, parenthesised — `(-0.03).em` — because
   `-0.03.em` parses as `-(0.03.em)` and needs an `unaryMinus` operator, while
@@ -448,14 +504,24 @@ dependency on it.
 // That last one is fixed for tokens whose role a DTCG source actually states:
 // classifyTextUnits stamps fontSize, letterSpacing and lineHeight members, and
 // the sp transform gates on the stamp rather than on a $type DTCG never emits.
-// Two limits remain, both Android-only and both measured rather than
-// theoretical — see docs/superpowers/notes/2026-08-21-native-config-e2e-results.md:
-//
-//   - A scale primitive carries no role. text.base: "16px" is a font size only
-//     to a human, so it emits as dp. The semantic tokens referencing it are
-//     correct, and those are what a consumer should reach for.
-//   - An em-valued letterSpacing is filtered out of native output entirely,
-//     rather than emitted as Compose's .em TextUnit.
+// Two limits remain, one Android-only and one affecting both platforms, both
+// measured rather than theoretical — see
+// docs/superpowers/notes/2026-08-28-text-role-inference-e2e.md:
+//
+//   - A scale primitive states no role, so #63 infers one from the reference
+//     graph: a dimension referenced only by fontSize, letterSpacing or
+//     lineHeight members is itself typographic. text.base: "16px" is stamped
+//     because a fontSize references it. A primitive NOTHING references stays
+//     dp on Android — no structural signal exists for it, so it is not
+//     inferred, and tokens:validate-output raises an unreferenced-text-sibling
+//     advisory naming it rather than leaving the gap silent. This is not the
+//     complete list of remaining limits (spec §8 names five more); the one a
+//     consumer is likeliest to hit is mode dependence — the same token can
+//     emit sp in one build and dp in another, because the graph only sees the
+//     files that build includes.
+//   - An em-valued letterSpacing reaches Compose as a real .em TextUnit since
+//     #64, but only where the text role is stamped. A role-less em value is
+//     still filtered out of native output entirely, on both platforms.
 //
 // The third — a unitless ratio emitting as dp — is fixed by #52: no size
 // transform claims a unitless value, so it emits bare on both platforms, and

package/references/sync-adapters.md

@@ -70,6 +70,13 @@ no native form at all — a CSS `linear-gradient(...)` — is filtered out of na
 output rather than emitted broken. That drop is reported as an unemitted token,
 not hidden.
 
+Since 0.17.0 that gap is measured rather than assumed on ThroughLine's side:
+this project's end-to-end runs compile what they generate — `kotlinc` typechecks
+`Tokens.kt` against Compose stubs, `swiftc -parse` checks `Tokens.swift` —
+against a real 322-token system. That is evidence about the adapter shipped to
+you, not a gate on your build, and it does not widen what the badge asserts
+about your output.
+
 `android-kotlin` uses the same module and stays Tier 2: its remaining unknowns
 are on the consumption side — Compose `dp`/`sp` behaviour against a real Compose
 app, resource-qualifier conventions, package layout — which building tokens does
@@ -77,9 +84,12 @@ not exercise. The `dp`/`sp` split itself is no longer among them: font sizes and
 line heights whose role a DTCG source states — the `fontSize`, `letterSpacing`
 and `lineHeight` member names of §9.8's typography composite — now emit as
 `sp`. What remains is narrower and documented in
-`${CLAUDE_PLUGIN_ROOT}/references/native-adapter-config.md`: a bare scale
-primitive carries no role and stays `dp`, and an `em` letterSpacing is
-filtered out rather than emitted as `.em`.
+`${CLAUDE_PLUGIN_ROOT}/references/native-adapter-config.md`: a scale primitive
+**nothing references** carries no role and stays `dp`, named by a
+`tokens:validate-output` `unreferenced-text-sibling` advisory; and an `em`
+letterSpacing reaches Compose as a real `.em` TextUnit but is excluded from
+Swift deliberately, since letter spacing there needs a font size no constant
+Swift value could carry.
 `tokens:validate-output` remains what decides whether any adapter can be
 trusted, and re-promotion is available to any adapter that passes it against a
 real source.

package/scripts/build-native-adapter-config.mjs

@@ -123,10 +123,14 @@ now emit \`sp\`, with the Swift output byte-identical.
 
 What remains:
 
-- **A bare scale primitive emits as \`dp\`.** \`text.base: "16px"\` is a font size
-  only to a human — no nominal or structural signal marks it — so it is not
-  stamped. The semantic tokens that reference it are, and those are what a
-  consumer should reach for.
+- **A scale primitive nothing references emits as \`dp\`.** \`text.base: "16px"\`
+  is a font size only to a human, so #63 takes the role from the reference
+  graph instead: a dimension referenced only by \`fontSize\`, \`letterSpacing\` or
+  \`lineHeight\` members is stamped typographic too. That is structural rather
+  than nominal, so it needs no path convention. A primitive **nothing**
+  references has no signal at all and is not inferred —
+  \`tokens:validate-output\` names it with an \`unreferenced-text-sibling\`
+  advisory, and a source-side \`nativeUnit\` stamp settles it.
 - **An \`em\` letter spacing reaches Compose but not Swift.** \`size/unit-aware/compose-em\`
   emits it as a real \`.em\` TextUnit, parenthesised — \`(-0.03).em\` — because
   \`-0.03.em\` parses as \`-(0.03.em)\` and needs an \`unaryMinus\` operator, while

package/scripts/lib/dtcg.mjs

@@ -4,6 +4,18 @@
 
 const REF = /^\{([^}]+)\}$/;
 
+// 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.
+//
+// They live here rather than in sd-native.mjs because textRoleGraph below and
+// sd-native.mjs's preprocess apply the identical rules, and sd-native.mjs
+// already imports this file — so the reverse import would be a cycle. Their
+// full rationale stays at the point of use in sd-native.mjs, which is what the
+// generated references/native-adapter-config.md renders.
+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';
+
 // 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
@@ -85,3 +97,107 @@ export function findModeCollisions(sources) {
   }
   return collisions;
 }
+
+// Deep merge in list order, later source winning — the same later-wins rule
+// validate-token-output.mjs already applies when it flattens a source list, and
+// what Style Dictionary hands preprocess as one dict.
+//
+// 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)) {
+    if (isPlainObject(val) && isPlainObject(target[key])) mergeInto(target[key], val);
+    else target[key] = val;
+  }
+  return target;
+}
+
+export function mergeDtcg(dicts) {
+  const out = {};
+  for (const dict of dicts) mergeInto(out, structuredClone(dict));
+  return out;
+}
+
+// A dimension primitive states no typographic role: text.base: "16px" is a font
+// size only to a human, so it emitted as dp, and an em letterSpacing primitive
+// was dropped from native output entirely. #51 sources the role from the member
+// names DTCG §9.8 fixes, which reaches the semantic tokens and not the
+// primitives they reference. This reaches the primitives, structurally.
+//
+// Reads the UNRESOLVED tree: preprocess resolves aliases in place, so by
+// transform time the graph is gone. Nothing needs carrying, because the
+// inference is applied during preprocessing and only the $extensions stamp
+// survives — see sd-native.mjs's applyTextRoleGraph.
+//
+// A referrer whose leaf name is NOT typographic is counter-evidence, not
+// neutral. A dimension referenced by something that is not a typographic member
+// is a length, which is exactly what the dp default already asserts about it.
+// Treating it as neutral would let one stray fontSize reference convert a whole
+// spacing ramp.
+//
+// Single-pass and deliberately not transitive: a chain through an intermediate
+// whose own leaf name states no role is declined at the second hop, because
+// that intermediate is itself counter-evidence. Only whole-value references
+// count; a reference embedded in an expression is resolved by resolveInPlace
+// but is not evidence of a role.
+export function textRoleGraph(dict) {
+  const edges = [];
+  (function walk(node, prefix) {
+    for (const [key, val] of Object.entries(node)) {
+      if (key.startsWith('$') || !isPlainObject(val)) continue;
+      const path = [...prefix, key];
+      if (typeof val.$value === 'string') {
+        const m = REF.exec(val.$value.trim());
+        if (m) edges.push({ to: m[1], leaf: key });
+      }
+      walk(val, path);
+    }
+  })(dict, []);
+
+  const referrers = new Map();
+  for (const edge of edges) {
+    if (!referrers.has(edge.to)) referrers.set(edge.to, []);
+    referrers.get(edge.to).push(edge);
+  }
+
+  const typographic = new Set();
+  const ambiguous = [];
+  for (const [path, rs] of referrers) {
+    const textLeaves = [...new Set(rs.filter((r) => TEXT_UNIT_NAMES.has(r.leaf)).map((r) => r.leaf))];
+    if (textLeaves.length === 0) continue;
+    const otherLeaves = [...new Set(rs.filter((r) => !TEXT_UNIT_NAMES.has(r.leaf)).map((r) => r.leaf))];
+    if (otherLeaves.length) ambiguous.push({ path, textLeaves, otherLeaves });
+    else typographic.add(path);
+  }
+
+  // A primitive nothing references has no structural signal at all, so it is
+  // never inferred. Reported instead, where its group holds one that was: that
+  // is the strongest hint available without guessing, and a silent gap is the
+  // failure this module exists to prevent. A token whose source already stamps
+  // nativeUnit is closed and is not reported.
+  const inferredGroups = new Set([...typographic].map((p) => p.split('.').slice(0, -1).join('.')));
+  const unreferencedSiblings = [];
+  (function walk(node, prefix) {
+    for (const [key, val] of Object.entries(node)) {
+      if (key.startsWith('$') || !isPlainObject(val)) continue;
+      const path = [...prefix, key];
+      const dotted = path.join('.');
+      const group = prefix.join('.');
+      if (
+        '$value' in val &&
+        val.$type === 'dimension' &&
+        TEXT_ROLE_UNIT.test(String(val.$value).trim()) &&
+        !referrers.has(dotted) &&
+        !('nativeUnit' in (val.$extensions?.[EXT_NS] ?? {})) &&
+        inferredGroups.has(group)
+      ) {
+        unreferencedSiblings.push({ path: dotted, group });
+      }
+      walk(val, path);
+    }
+  })(dict, []);
+
+  return { typographic, ambiguous, unreferencedSiblings };
+}

package/scripts/lib/sd-native.mjs

@@ -10,7 +10,15 @@
 // scripts/build-native-adapter-config.mjs. Edit the code here, then regenerate.
 // @doc-section imports
 import { readFileSync } from 'node:fs';
-import { flattenDtcg, resolveValue, findModeCollisions } from './dtcg.mjs';
+import {
+  flattenDtcg,
+  resolveValue,
+  findModeCollisions,
+  TEXT_UNIT_NAMES,
+  TEXT_ROLE_UNIT,
+  EXT_NS,
+  textRoleGraph,
+} from './dtcg.mjs';
 import { isValidLiteral, GRAMMAR, CSS_CONSTRUCT } from './native-literal.mjs';
 // @doc-section-end imports
 
@@ -226,11 +234,16 @@ function hoistDualNodes(node, collisions, prefix = [], groupType = undefined) {
 // sibling tokens in a group. Reading them there mirrors the spec's vocabulary;
 // it is not a guarantee the spec makes. A source naming its font size
 // typography.body.size sets $extensions itself and is honoured below.
-const TEXT_UNIT_NAMES = new Set(['fontSize', 'letterSpacing', 'lineHeight']);
+//
+// Defined in lib/dtcg.mjs and imported above, so textRoleGraph applies the
+// identical set. Two definitions of this set would drift.
 
 // Reverse-DNS, per DTCG's $extensions convention. Exported because the
 // transforms and their tests address the same key.
-export const EXT_NS = 'com.radicool.throughline';
+//
+// Defined in lib/dtcg.mjs and re-exported here: the transforms and their tests
+// address this key through sd-native.mjs, and that surface does not move.
+export { EXT_NS };
 
 // px and rem only. magnitude() reads a bare number as an unscaled ratio, so a
 // lineHeight authored "1.5" would otherwise be stamped and emit 1.50.sp —
@@ -244,7 +257,9 @@ export const EXT_NS = 'com.radicool.throughline';
 // em-valued letterSpacing is a text-role dimension like any other. It is still
 // a unit — the gate's job is to exclude the UNITLESS value, whose role the
 // source never stated.
-const TEXT_ROLE_UNIT = /^-?(?:\d+(?:\.\d+)?|\.\d+)(?:px|rem|em)$/;
+//
+// Defined in lib/dtcg.mjs and imported above, for the same reason as
+// TEXT_UNIT_NAMES: textRoleGraph gates on it too.
 
 // Runs AFTER resolveInPlace and BEFORE hoistDualNodes. Both halves matter.
 //
@@ -283,10 +298,47 @@ function classifyTextUnits(node) {
   return node;
 }
 
+// Runs AFTER classifyTextUnits and BEFORE hoistDualNodes, on the SAME two
+// grounds that pass gives: after, so a role the source or the member name
+// already stated wins; before, because the hoist rewrites text.xs.lineHeight to
+// text.xsLineHeight and the graph's paths are written in pre-hoist names.
+//
+// The three gates are classifyTextUnits's, verbatim — a dimension, a value with
+// a unit, and no role already recorded. A unitless value is never stamped: no
+// size transform claims one since #52, and stamping a ratio as text would still
+// be a claim the source never made.
+//
+// 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.
+function applyTextRoleGraph(node, typographic) {
+  for (const path of typographic) {
+    let target = node;
+    for (const segment of path.split('.')) {
+      target = target && typeof target === 'object' ? target[segment] : undefined;
+    }
+    if (!target || typeof target !== 'object' || !('$value' in target)) continue;
+    if (target.$type !== 'dimension') continue;
+    if (!TEXT_ROLE_UNIT.test(String(target.$value).trim())) continue;
+    target.$extensions ??= {};
+    target.$extensions[EXT_NS] ??= {};
+    const ns = target.$extensions[EXT_NS];
+    if (!('nativeUnit' in ns)) ns.nativeUnit = 'text';
+  }
+  return node;
+}
+
 export function preprocess(dict) {
   const collisions = [];
+  // Read from the UNRESOLVED dict, before resolveInPlace flattens the aliases
+  // the graph is made of.
+  const { typographic } = textRoleGraph(dict);
   const out = hoistDualNodes(
-    classifyTextUnits(resolveInPlace(structuredClone(dict), flattenDtcg(dict))),
+    applyTextRoleGraph(
+      classifyTextUnits(resolveInPlace(structuredClone(dict), flattenDtcg(dict))),
+      typographic,
+    ),
     collisions,
   );
   if (collisions.length) {
@@ -324,14 +376,24 @@ export function preprocess(dict) {
 // That last one is fixed for tokens whose role a DTCG source actually states:
 // classifyTextUnits stamps fontSize, letterSpacing and lineHeight members, and
 // the sp transform gates on the stamp rather than on a $type DTCG never emits.
-// Two limits remain, both Android-only and both measured rather than
-// theoretical — see docs/superpowers/notes/2026-08-21-native-config-e2e-results.md:
-//
-//   - A scale primitive carries no role. text.base: "16px" is a font size only
-//     to a human, so it emits as dp. The semantic tokens referencing it are
-//     correct, and those are what a consumer should reach for.
-//   - An em-valued letterSpacing is filtered out of native output entirely,
-//     rather than emitted as Compose's .em TextUnit.
+// Two limits remain, one Android-only and one affecting both platforms, both
+// measured rather than theoretical — see
+// docs/superpowers/notes/2026-08-28-text-role-inference-e2e.md:
+//
+//   - A scale primitive states no role, so #63 infers one from the reference
+//     graph: a dimension referenced only by fontSize, letterSpacing or
+//     lineHeight members is itself typographic. text.base: "16px" is stamped
+//     because a fontSize references it. A primitive NOTHING references stays
+//     dp on Android — no structural signal exists for it, so it is not
+//     inferred, and tokens:validate-output raises an unreferenced-text-sibling
+//     advisory naming it rather than leaving the gap silent. This is not the
+//     complete list of remaining limits (spec §8 names five more); the one a
+//     consumer is likeliest to hit is mode dependence — the same token can
+//     emit sp in one build and dp in another, because the graph only sees the
+//     files that build includes.
+//   - An em-valued letterSpacing reaches Compose as a real .em TextUnit since
+//     #64, but only where the text role is stamped. A role-less em value is
+//     still filtered out of native output entirely, on both platforms.
 //
 // The third — a unitless ratio emitting as dp — is fixed by #52: no size
 // transform claims a unitless value, so it emits bare on both platforms, and

package/scripts/validate-token-output.mjs

@@ -7,7 +7,15 @@
 import { readFileSync } from 'node:fs';
 import { parseArgs } from 'node:util';
 import { pathToFileURL } from 'node:url';
-import { flattenDtcg, flattenDtcgTypes, resolveValue, findModeCollisions } from './lib/dtcg.mjs';
+import {
+  flattenDtcg,
+  flattenDtcgTypes,
+  resolveValue,
+  findModeCollisions,
+  textRoleGraph,
+  mergeDtcg,
+  EXT_NS,
+} from './lib/dtcg.mjs';
 import { parseLiteral, isValidLiteral, GRAMMAR } from './lib/native-literal.mjs';
 
 // Re-exported so consumers (and the test file) keep one import surface.
@@ -209,6 +217,24 @@ export function validate({ sources, output, platform, minMatch = 0.5 }) {
     }
   }
 
+  // A SOURCE-side pass, deliberately not part of the loop above. That loop
+  // iterates emitted declarations, and the token this advisory exists for is
+  // the one that was never emitted at all — an em letterSpacing whose role
+  // nothing states is filtered out of native output, so it has no symbol to
+  // hang a note on.
+  //
+  // Merged rather than unioned across sources: the graph must describe the
+  // 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.
+  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 });
+  }
+  for (const { path, textLeaves, otherLeaves } of graph.ambiguous) {
+    advisories.push({ rule: 'ambiguous-text-role', token: path, textLeaves, otherLeaves });
+  }
+
   const matchRate = decls.length ? matched / decls.length : 0;
   const ok = failures.length === 0 && collisions.length === 0 && matched > 0 && matchRate >= minMatch;
 
@@ -260,6 +286,18 @@ export function formatReport(r) {
   if (r.advisories?.length) {
     lines.push(`\n${r.advisories.length} advisory note(s) — reported, not gating:`);
     for (const a of r.advisories) {
+      if (a.rule === 'unreferenced-text-sibling') {
+        lines.push(
+          `  - [${a.rule}] ${a.token}: nothing references it, so no typographic role could be inferred — but tokens in "${a.group}" were. It emits as a length, or is dropped entirely if its unit is em. On Compose, stamping $extensions["${EXT_NS}"].nativeUnit = "text" on it in source settles it; on Swift there is no sp/dp distinction to settle, and a stamped em still would not emit there. Leave it as is if it is not a text value.`,
+        );
+        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.`,
+        );
+        continue;
+      }
       lines.push(
         `  - [${a.rule}] ${a.symbol}: source ${JSON.stringify(a.source)} for ${a.token} is a dimension with no unit, which DTCG §8.2.1 does not permit. It emitted ${a.emitted}, read as a ratio. If it is a ratio, type it "number" (§8.7); if it is a measurement, add the unit you meant.`,
       );