@starklab/stark-mcp 0.2.0 → 0.3.0

package/src/whisperer.js

@@ -0,0 +1,814 @@
+/**
+ * Whisperer — the design-system facts an answer is allowed to be built on,
+ * and the instructions they are handed to a model under.
+ *
+ * Whisperer answers questions about *this* design system, so the model is
+ * never asked to recall one. Everything it may assert is assembled here from
+ * the same generated files the rest of the toolchain validates against. This
+ * module is pure: it takes those files as data and returns the grounding
+ * functions, so the one code path serves every surface — the MCP tool and the
+ * CLI load the files from the installed `@starklab/stk` (see data.js), and
+ * Dominion's chat panel hands in the JSON its bundler already carries.
+ *
+ *  - `catalog.json`         — *which symbols exist*, on which platform, and
+ *                             what kind each one is. This is the existence
+ *                             authority; the manifest is built from it too,
+ *                             and the union below is kept so that a component
+ *                             the manifest has not yet been regenerated for
+ *                             still exists here.
+ *  - `manifest.json`        — the prose usage docs (dos/donts), per platform:
+ *                             `usage` is the web file, and `nativeUsage` the
+ *                             React Native one, which is its own document —
+ *                             its own rules, a typed prop table and a code
+ *                             example — because the RN port's props differ
+ *                             from web's for most components.
+ *  - `component-props.json` — the *real* React signatures, generated from the
+ *                             component sources; the prop mapping files are a
+ *                             Figma contract and drift from the signature on
+ *                             purpose.
+ *  - `json-meta`            — every token: its resolved value, the layer its
+ *                             source file sits in, the token it aliases, the
+ *                             sentence written beside it and the name React
+ *                             Native exports it under.
+ *  - `json-dark`            — the value a token takes in dark mode, for the
+ *                             tokens the dark overlay redefines.
+ *
+ * Three rules hold this together, and all three are load-bearing:
+ *
+ *  1. **The full catalog always goes in, the detail never does.** Every name,
+ *     its one-line description and its prop names cost ~20 KB and are what
+ *     stop the model inventing a component or a prop that does not exist — or
+ *     denying one that does. The per-component detail — usage, props, tokens
+ *     — averages 4.5 KB each, so only the components the conversation is
+ *     about are expanded — the ones the question names, then the most
+ *     recently discussed — capped at MAX_DETAIL.
+ *  2. **The semantic layer and the scales are listed; the colour primitives
+ *     are not.** The layer comes from the token's source directory, not from
+ *     a list of family names kept here — a family added to `tokens/semantic/`
+ *     is in the next build's list without anyone remembering this file (the
+ *     chart palette was missing for exactly that reason). The 192
+ *     `color-shade-*` primitives are deliberately withheld: CLAUDE.md's layer
+ *     hierarchy says a component token must alias a semantic token and never
+ *     a primitive, and a list the model can read from is a list it will
+ *     suggest from. The twelve `color-brand-palette-*` primitives are the
+ *     exception, listed under their own heading with the same warning,
+ *     because "what is the exact brand colour?" deserves its real answer.
+ *     Every primitive is still *resolved* when a question names it outright,
+ *     so "what is `--stk-color-shade-palette-1-8`?" gets one too.
+ *  3. **Nothing here reads the questioner's code.** This module is the design
+ *     system, not the workspace; what a consumer knows about its own code is
+ *     its own business (Dominion's Whisperer knows nothing of it, by decision
+ *     #23; an editor agent holding the MCP tool knows all of it).
+ */
+
+/**
+ * @typedef {{ dos?: string[], donts?: string[], codeExample?: string }} UsageDoc
+ *
+ * @typedef {object} NativeUsageProp
+ * One row of a React Native usage file's prop table. The RN files enumerate
+ * their props (the web files do not — web's values come from the mapping
+ * file), and `type` there is the TypeScript-ish shape the author wrote:
+ * `'sm' | 'md' | 'lg'`, `ReactNode`, `(id: string) => void`.
+ * @property {string} name
+ * @property {string} type
+ * @property {string} [default]
+ * @property {boolean | string} [required]  `true`, or the condition under which it is required.
+ * @property {string} [description]
+ *
+ * @typedef {UsageDoc & { props?: NativeUsageProp[] }} NativeUsageDoc
+ *
+ * @typedef {object} PropMapEntry
+ * One entry of a prop-mapping file's `propMap`, as the manifest republishes
+ * it. `values` is the whole point: for an enum it is every value the prop
+ * accepts, and it exists nowhere else the grounding reads — the React
+ * signature only carries a name and a default.
+ * @property {string} react
+ * @property {string} [type]
+ * @property {Record<string, string>} [values]
+ * @property {string} [transform]  `presence`: the Figma boolean is derived from a React node being passed.
+ * @property {string} [description]
+ * @property {boolean} [componentProp]  `false` when the Figma property has no React prop of that name.
+ *
+ * @typedef {object} ManifestComponent
+ * @property {string} name
+ * @property {string} slug
+ * @property {string} status
+ * @property {string} description
+ * @property {string[]} [platforms]
+ * @property {UsageDoc | null} [usage]
+ * @property {NativeUsageDoc | null} [nativeUsage]
+ * @property {{ web?: { propMap?: PropMapEntry[] } | null } | null} [props]
+ * @property {Record<string, unknown> | null} [tokens]
+ *
+ * @typedef {{ name: string, hasDefault?: boolean, defaultSource?: string, rest?: boolean }} PropEntry
+ * @typedef {{ package?: string, components?: Record<string, { props?: PropEntry[] }> }} SignaturePlatform
+ *
+ * @typedef {object} TokenMeta
+ * @property {unknown} value
+ * @property {string} type
+ * @property {'primitive' | 'semantic' | 'component' | null} layer
+ * @property {string | null} alias
+ * @property {string | null} description
+ * @property {{ name: string, module: string } | null} rn
+ *
+ * @typedef {object} WhispererData
+ * @property {{ components: ManifestComponent[] }} manifest
+ * @property {{ platforms: Record<string, { exports: Record<string, { kind: string }> }> }} catalog
+ * @property {{ platforms: { web?: SignaturePlatform, native?: SignaturePlatform } }} componentProps
+ * @property {Record<string, TokenMeta>} tokenMeta
+ * @property {Record<string, unknown>} tokenDark
+ *
+ * @typedef {object} Known
+ * @property {string} name
+ * @property {ManifestComponent | null} doc
+ * @property {string} kind
+ * @property {string} status
+ * @property {string[]} platforms
+ * @property {string | null} description
+ *
+ * @typedef {object} Grounding
+ * @property {string} text  The grounding block, ready to sit under the system prompt.
+ * @property {string[]} components  The components whose full detail the block carries.
+ * @property {string[]} named  The subset the question itself named.
+ * @property {string[]} tokens  The tokens the question named outright.
+ */
+
+/** Kinds a question can legitimately be about. `hook` is not one of them. */
+const LISTED_KINDS = new Set(['component', 'primitive', 'subpart']);
+
+/** At most this many components get their full detail block. */
+const MAX_DETAIL = 4;
+
+/**
+ * A token value as it is written in an answer: a string as-is, a composite
+ * (the text styles) as its parts.
+ * @param {unknown} v
+ */
+function valueText(v) {
+  if (v && typeof v === 'object') {
+    return Object.entries(v)
+      .map(([k, x]) => `${k} ${String(x)}`)
+      .join(', ');
+  }
+  return String(v);
+}
+
+/**
+ * The first sentence of a description, for the always-on list. A few of them
+ * run to a paragraph — the chart palette explains its CVD checks,
+ * `text.subtle` its contrast ratios — and that text is worth having, but
+ * once, next to the token when a question names it, not on every turn.
+ * @param {string} description
+ */
+function brief(description) {
+  const first = description.split(/(?<=\.)\s+/)[0] ?? description;
+  return first.length > 140 ? `${first.slice(0, 137).trimEnd()}…` : first;
+}
+
+/** @param {string | undefined} ch */
+const isWordChar = (ch) => !!ch && /[a-z0-9]/.test(ch);
+
+/**
+ * Where a name first appears in the text as a whole word, or -1. Every
+ * occurrence is tried rather than only the first, because the first is often
+ * the one inside a longer name: in "SelectionCard and Card", `Card`'s first
+ * hit sits inside `SelectionCard` and is rejected, and stopping there would
+ * lose the standalone mention that follows it.
+ * @param {string} hay
+ * @param {string} needle
+ */
+function wordIndexOf(hay, needle) {
+  let at = hay.indexOf(needle);
+  while (at !== -1) {
+    if (!isWordChar(hay[at - 1]) && !isWordChar(hay[at + needle.length])) return at;
+    at = hay.indexOf(needle, at + 1);
+  }
+  return -1;
+}
+
+/**
+ * Whether anything placed between the component's tags is rendered. Derived
+ * from the signature, never assumed: 8 of the 75 web components accept
+ * `children`, and the other 67 render nothing from it — a
+ * `<Button>Save</Button>` is an empty button, because the text goes through
+ * `label`.
+ * @param {string} name
+ * @param {PropEntry[]} props
+ */
+function childrenRule(name, props) {
+  if (props.some((p) => p.name === 'children')) {
+    return `${name} accepts \`children\`: content between its tags is rendered.`;
+  }
+  const slots = props
+    .filter((p) => /^(label|title|text|content|description|value)$/.test(p.name))
+    .map((p) => `\`${p.name}\``);
+  const via = slots.length ? ` Its text goes through ${slots.join(', ')}.` : '';
+  return (
+    `${name} does not accept \`children\`: anything placed between its tags is not rendered, ` +
+    `and no prop outside the list above exists.${via}`
+  );
+}
+
+/**
+ * The grounding functions, built over one set of generated files.
+ * @param {WhispererData} data
+ */
+export function createWhisperer({ manifest, catalog, componentProps, tokenMeta, tokenDark }) {
+  const DOCUMENTED = manifest.components;
+  const META = tokenMeta;
+  const DARK = tokenDark;
+
+  /** @param {string} platform */
+  function catalogNames(platform) {
+    const exports = catalog.platforms[platform]?.exports ?? {};
+    return new Set(
+      Object.entries(exports)
+        .filter(([, entry]) => LISTED_KINDS.has(entry?.kind))
+        .map(([name]) => name),
+    );
+  }
+
+  /**
+   * Everything a question may name, and what is known about it. Names are
+   * the union of the catalog and the manifest, and so are the platforms: the
+   * catalog says where a component is exported, the manifest repeats the
+   * mapping file's claim, and a mapping file that says `web` for a component
+   * the RN barrel also exports (DropdownMenu, once) must not turn into
+   * "web-only" in the index — that tag is what the answer to "does it exist
+   * on React Native?" is read from.
+   * @type {Known[]}
+   */
+  const KNOWN = (() => {
+    const web = catalogNames('web');
+    const rn = catalogNames('rn');
+    const documented = new Map(DOCUMENTED.map((c) => [c.name, c]));
+    const names = [...new Set([...web, ...rn, ...documented.keys()])].sort();
+    return names.map((name) => {
+      const doc = documented.get(name) ?? null;
+      const declared = new Set(doc?.platforms ?? []);
+      const platforms = /** @type {string[]} */ (
+        [
+          web.has(name) || declared.has('web') ? 'web' : null,
+          rn.has(name) || declared.has('native') ? 'native' : null,
+        ].filter(Boolean)
+      );
+      const kind =
+        catalog.platforms.web?.exports?.[name]?.kind ??
+        catalog.platforms.rn?.exports?.[name]?.kind ??
+        'component';
+      // The manifest writes `status: "unknown"` for the layout primitives,
+      // which is a fact about the manifest, not about the component. Say what
+      // it is instead of quoting a status nobody set.
+      const status = doc?.status && doc.status !== 'unknown' ? doc.status : kind;
+      return {
+        name,
+        doc,
+        kind,
+        status,
+        platforms: platforms.length ? platforms : ['web'],
+        description: doc?.description ?? null,
+      };
+    });
+  })();
+
+  const SIGNATURES = componentProps.platforms;
+  const REACT_PROPS = SIGNATURES.web?.components ?? {};
+  const NATIVE_PROPS = SIGNATURES.native?.components ?? {};
+
+  /**
+   * Where each platform's components are imported from. Read from the
+   * signature file, which records the package it was generated from, because
+   * the manifest's own `package` field names the token package — and an
+   * import line is the one fact a model will most confidently make up when
+   * it is not in front of it.
+   */
+  const PACKAGES = {
+    web: SIGNATURES.web?.package ?? null,
+    native: SIGNATURES.native?.package ?? null,
+  };
+
+  /** Every token, the same order the build writes them in. */
+  const TOKEN_NAMES = Object.keys(META);
+
+  /**
+   * The tokens the always-on list carries: the whole semantic layer and every
+   * primitive scale that is not a colour — spacing, radius, type, opacity,
+   * motion, elevation, breakpoints. The colour primitives are the shades
+   * (withheld, rule 2 above) and the brand palette (listed apart). Component
+   * tokens reach the model through their own component's detail block.
+   * @param {string} name
+   */
+  function inScaleList(name) {
+    const t = META[name];
+    return t.layer === 'semantic' || (t.layer === 'primitive' && t.type !== 'color');
+  }
+
+  /** @param {string} name */
+  function isBrandPrimitive(name) {
+    return name.startsWith('stk-color-brand-');
+  }
+
+  /**
+   * One token, one line. Always: the name, the light value, the dark value
+   * when the dark overlay changes it, and `→` the token it aliases — that
+   * arrow is what answers "what does the button's background *really* point
+   * at". The description follows. `full` gives the whole description and the
+   * React Native export; the list gives the first sentence and leaves RN to
+   * the rule under its heading.
+   * @param {string} name
+   * @param {boolean} [full]
+   */
+  function tokenLine(name, full = false) {
+    const t = META[name];
+    let line = `--${name}: ${valueText(t.value)}`;
+    if (DARK[name] !== undefined && valueText(DARK[name]) !== valueText(t.value)) {
+      line += ` (dark: ${valueText(DARK[name])})`;
+    }
+    if (t.alias) line += ` → --${t.alias}`;
+    if (t.description) line += ` — ${full ? t.description : brief(t.description)}`;
+    if (full) {
+      line += t.rn
+        ? `\n  React Native: \`${t.rn.name}\` from \`${t.rn.module}\``
+        : '\n  React Native: not exported — web only';
+    }
+    return line;
+  }
+
+  /** @type {string | null} */
+  let catalogCache = null;
+
+  /**
+   * Every component, one line each — the answer to "does this exist?" — and,
+   * under it, the names of its web props. The names cost ~9 KB for the whole
+   * catalog and buy the closed list for components an answer *composes with*
+   * rather than asks about: a question about `Card` expands `Card` alone, and
+   * the example then reaches for `Stack` — which, without this line, got a
+   * `padding` prop it has never had. Values stay in the detail blocks.
+   */
+  function catalogIndex() {
+    if (catalogCache) return catalogCache;
+    catalogCache = KNOWN.map((k) => {
+      const description = k.description ?? 'Exported and usable; no description reached this index.';
+      const names = (REACT_PROPS[k.name]?.props ?? []).filter((p) => !p.rest).map((p) => p.name);
+      const props = names.length ? `\n  props: ${names.join(', ')}` : '';
+      return `${k.name} [${k.status}, ${k.platforms.join('/')}] — ${description}${props}`;
+    }).join('\n');
+    return catalogCache;
+  }
+
+  /** @type {string | null} */
+  let tokenListCache = null;
+
+  /**
+   * The always-on token list, with the rules for reading it said once at the
+   * top rather than on every line: what the arrow means, what dark means, and
+   * how a name becomes its React Native export. The RN rule is stated instead
+   * of listed because it holds for every line here — the exceptions are the
+   * colour primitives, which are not exported on RN and are not in this list.
+   */
+  function tokenList() {
+    if (tokenListCache) return tokenListCache;
+    const scale = TOKEN_NAMES.filter(inScaleList).map((n) => tokenLine(n));
+    const brand = TOKEN_NAMES.filter(isBrandPrimitive).map((n) => tokenLine(n));
+    tokenListCache = [
+      'How to read a line: `--name: light value (dark: value in dark mode) → the token it aliases — what it is for`.',
+      'A token with no `(dark: …)` keeps its light value in dark mode. A token with no `→` holds a raw value: it is',
+      'the end of the chain. Component tokens (listed under their component) alias these; these alias the primitives.',
+      'React Native exports every token below under its camelCase name, from `@starklab/stk/rn`:',
+      '`--stk-border-default` is `stkBorderDefault`, `--stk-spacing-md` is `stkSpacingMd`. Easing tokens come from',
+      '`@starklab/stk/rn-easing` instead, and the per-platform spacing, type-size and shadow steps are folded into one',
+      'Platform.select() export each (`stkSpacingMd` from `@starklab/stk/rn-spacing`, `stkTypographySizeMd` from',
+      '`@starklab/stk/rn-typography`, `stkShadowMd` from `@starklab/stk/rn-shadows`).',
+      '',
+      `### Semantic tokens and scales (${scale.length})`,
+      '',
+      ...scale,
+      '',
+      `### Brand colour primitives (${brand.length})`,
+      '',
+      'The exact brand colours. Reference only: a component or a screen takes its colour from a semantic surface,',
+      'text, border or icon token above, never from these directly, and they are not exported on React Native.',
+      '',
+      ...brand,
+    ].join('\n');
+    return tokenListCache;
+  }
+
+  /**
+   * Which components the question names, in the order it names them. Matched
+   * on word boundaries against the catalog's own names, so "card" hits `Card`
+   * but "discard" does not.
+   * @param {string} text
+   * @returns {{ entry: Known, at: number }[]}
+   */
+  function namedInQuestion(text) {
+    const hay = text.toLowerCase();
+    return KNOWN.map((entry) => ({ entry, at: wordIndexOf(hay, entry.name.toLowerCase()) }))
+      .filter((hit) => hit.at !== -1)
+      .sort((a, b) => a.at - b.at);
+  }
+
+  /**
+   * The components whose full detail block goes into the grounding. Longer
+   * names win first (`DataTable` before `Table`-like substrings) because a
+   * longer name is the more specific thing to expand when the cap bites.
+   * @param {string} text
+   */
+  function componentsInQuestion(text) {
+    const hits = namedInQuestion(text).map((h) => h.entry);
+    hits.sort((a, b) => b.name.length - a.name.length);
+    return hits.slice(0, MAX_DETAIL);
+  }
+
+  /**
+   * The question's own components first, then — while there is room under
+   * MAX_DETAIL — the ones the conversation was most recently about. A
+   * follow-up rarely repeats the name: "tell me the sizes" names nothing, and
+   * grounded on itself alone it carried no `Button` block at all, so the
+   * answer to it came from the model's memory of some other design system.
+   * `context` is the prior turns, newest first; the newest mention wins the
+   * last slot.
+   * @param {string} question
+   * @param {string[]} context
+   */
+  function componentsToExpand(question, context) {
+    const picked = componentsInQuestion(question);
+    for (const text of context) {
+      if (picked.length >= MAX_DETAIL) break;
+      for (const hit of componentsInQuestion(text)) {
+        if (picked.length >= MAX_DETAIL) break;
+        if (!picked.includes(hit)) picked.push(hit);
+      }
+    }
+    return picked;
+  }
+
+  /**
+   * The same matches, in reading order and uncapped — what "which component
+   * is this question about?" means to a reader, and what a consumer that
+   * counts asks per component classifies against. Exposed so such a count is
+   * built from the same catalog the answer was grounded in, never from a
+   * second list.
+   * @param {string} text
+   * @returns {{ name: string, platforms: string[] }[]}
+   */
+  function componentsNamedIn(text) {
+    return namedInQuestion(text).map((h) => ({ name: h.entry.name, platforms: h.entry.platforms }));
+  }
+
+  /**
+   * Every component name the catalog knows — the closed set, for validation.
+   * @param {string} name
+   */
+  function isKnownComponent(name) {
+    return KNOWN.some((k) => k.name === name);
+  }
+
+  /**
+   * Whether a token name (without its leading `--`) exists in the token build.
+   * @param {string} name
+   */
+  function isKnownToken(name) {
+    return META[name.replace(/^--/, '').toLowerCase()] !== undefined;
+  }
+
+  /**
+   * React Native export name → token name, for questions asked in RN terms. A
+   * Platform.select() export stands for several tokens; the first wins.
+   */
+  const RN_NAMES = (() => {
+    /** @type {Map<string, string>} */
+    const map = new Map();
+    for (const name of TOKEN_NAMES) {
+      const rn = META[name].rn;
+      if (rn && !map.has(rn.name)) map.set(rn.name, name);
+    }
+    return map;
+  })();
+
+  /**
+   * Any token the question names outright, primitives included, in either
+   * spelling: the CSS name (`--stk-border-default`, with or without the
+   * dashes) or the React Native export (`stkBorderDefault`).
+   * @param {string} text
+   * @returns {string[]}
+   */
+  function tokensInQuestion(text) {
+    /** @type {Set<string>} */
+    const seen = new Set();
+    for (const raw of text.match(/(?:--)?\bstk-[a-z0-9-]+/gi) ?? []) {
+      const name = raw.replace(/^--/, '').toLowerCase();
+      if (META[name] !== undefined) seen.add(name);
+    }
+    for (const raw of text.match(/\bstk[A-Z][A-Za-z0-9]*/g) ?? []) {
+      const name = RN_NAMES.get(raw);
+      if (name) seen.add(name);
+    }
+    return [...seen];
+  }
+
+  /**
+   * One line per prop, and every enum's values on it. The list itself comes
+   * from the React signature — that is the closed set, and a prop the source
+   * never destructures is not a prop however the mapping file describes it.
+   * The mapping file adds what the signature cannot say: the values an enum
+   * accepts, whether a prop is a slot, and the sentence the author wrote
+   * about it.
+   *
+   * The values matter more than anything else here. "Button has 3 sizes" is
+   * in the usage prose; `sm | md | lg` is in the mapping file and nowhere
+   * else, and a model told the count but not the names answers "what sizes
+   * are there?" with a guess dressed as a fact.
+   * @param {Known} k
+   * @param {PropEntry[]} props
+   */
+  function propLines(k, props) {
+    /** @type {Map<string, PropMapEntry>} */
+    const mapped = new Map();
+    for (const entry of k.doc?.props?.web?.propMap ?? []) {
+      if (entry.componentProp !== false) mapped.set(entry.react, entry);
+    }
+    const lines = props
+      .filter((p) => !p.rest)
+      .map((p) => {
+        const m = mapped.get(p.name);
+        const values = m?.values ? Object.keys(m.values) : [];
+        const isBool = values.length === 2 && values.includes('true') && values.includes('false');
+        let shape;
+        if (values.length && !isBool) shape = values.join(' | ');
+        else if (m?.type === 'instance' || m?.transform === 'presence') shape = 'a React element (slot)';
+        else if (m?.type === 'function') shape = 'callback';
+        else if (m?.type === 'boolean' || isBool) shape = 'boolean';
+        else if (m?.type === 'text') shape = 'text';
+        else shape = '';
+        const dflt = p.hasDefault ? `default ${p.defaultSource}` : 'no default';
+        const note = m?.description ? ` — ${m.description}` : '';
+        return `- ${p.name}${shape ? `: ${shape}` : ''} (${dflt})${note}`;
+      });
+    if (props.some((p) => p.rest)) {
+      lines.push(
+        '- …rest: any other attribute (aria-*, data-*, id, event handlers) is passed through to the underlying element',
+      );
+    }
+    return lines.join('\n');
+  }
+
+  /**
+   * The React Native half of a component's detail, or the one line that says
+   * there is none. The closed list is the RN signature (component-props.json,
+   * generated from `packages/stk-react-native/src`); the RN usage file adds
+   * what a signature cannot say — the type, whether it is required, and the
+   * sentence the author wrote — the way the mapping file does for web. Then
+   * the RN children rule, the RN Do/Don't and the RN code example, each its
+   * own set: `Button` on RN has no `href`, `Card` has `onPress`, and a rule
+   * written for the DOM ("pair it with a focus ring") is not a rule on a
+   * phone.
+   * @param {Known} k
+   * @returns {string[]}
+   */
+  function nativeSection(k) {
+    /** @type {string[]} */
+    const parts = [];
+    const sig = NATIVE_PROPS[k.name]?.props ?? [];
+    const nu = k.doc?.nativeUsage ?? null;
+    if (!k.platforms.includes('native') && !sig.length && !nu) {
+      parts.push(`${k.name} has no React Native version: it exists on web only.`);
+      return parts;
+    }
+
+    /** @type {Map<string, NativeUsageProp>} */
+    const documented = new Map();
+    for (const p of nu?.props ?? []) documented.set(p.name, p);
+
+    /**
+     * @param {string} name
+     * @param {NativeUsageProp | undefined} p
+     * @param {string | null} sigDefault
+     */
+    const describe = (name, p, sigDefault) => {
+      const shape = p?.type ? `: ${p.type}` : '';
+      const dflt = sigDefault ?? (p?.default ? p.default : null);
+      const required =
+        p?.required === true ? 'required' : typeof p?.required === 'string' ? `required ${p.required}` : null;
+      const state = [dflt ? `default ${dflt}` : null, required].filter(Boolean).join(', ') || 'no default';
+      const note = p?.description ? ` — ${p.description}` : '';
+      return `- ${name}${shape} (${state})${note}`;
+    };
+
+    /** @type {string[]} */
+    const lines = [];
+    /** @type {Set<string>} */
+    const listed = new Set();
+    for (const p of sig) {
+      if (p.rest) continue;
+      listed.add(p.name);
+      lines.push(describe(p.name, documented.get(p.name), p.hasDefault ? (p.defaultSource ?? null) : null));
+    }
+    if (sig.some((p) => p.rest)) {
+      lines.push('- …rest: any other prop (style, testID, accessibility*) is passed through to the underlying view');
+    }
+    // What the RN usage file documents beyond the signature is a compound
+    // part's prop (`DropdownMenu.Item.label`), never a prop of the component
+    // itself.
+    const extra = [...documented.values()].filter((p) => !listed.has(p.name));
+    for (const p of extra) lines.push(describe(p.name, p, null));
+
+    if (lines.length) {
+      const differs = (REACT_PROPS[k.name]?.props ?? []).length
+        ? ' (a different list from web — answer for the platform asked)'
+        : '';
+      parts.push(`React Native props — the complete list for that platform${differs}:\n${lines.join('\n')}`);
+      if (sig.length) parts.push(`On React Native, ${childrenRule(k.name, sig)}`);
+    }
+
+    if (nu?.dos?.length) parts.push(`React Native — Do:\n${nu.dos.map((d) => `- ${d}`).join('\n')}`);
+    if (nu?.donts?.length) parts.push(`React Native — Don't:\n${nu.donts.map((d) => `- ${d}`).join('\n')}`);
+    if (nu?.codeExample) {
+      parts.push(`React Native example (from the usage docs):\n\`\`\`jsx\n${nu.codeExample}\n\`\`\``);
+    }
+    return parts;
+  }
+
+  /** @param {Known} k */
+  function detailFor(k) {
+    const c = k.doc;
+    /** @type {string[]} */
+    const parts = [`### ${k.name} (${k.status})`];
+    if (k.description) parts.push(k.description);
+    else
+      parts.push(
+        'Exported and usable, but no usage guidance reached this index. Answer from its props, ' +
+          'and say that the written guidance for it is not in front of you rather than inventing any.',
+      );
+
+    const imports = [
+      PACKAGES.web && REACT_PROPS[k.name] ? `import { ${k.name} } from '${PACKAGES.web}'` : null,
+      PACKAGES.native && NATIVE_PROPS[k.name]
+        ? `import { ${k.name} } from '${PACKAGES.native}'  (React Native)`
+        : null,
+    ].filter(Boolean);
+    if (imports.length) parts.push(`Import:\n${imports.join('\n')}`);
+
+    const props = REACT_PROPS[k.name]?.props ?? [];
+    if (props.length) {
+      parts.push(`Web props — the complete list (from the component source):\n${propLines(k, props)}`);
+      parts.push(childrenRule(k.name, props));
+    }
+
+    if (c?.usage?.codeExample) {
+      parts.push(`Web example (from the usage docs):\n\`\`\`jsx\n${c.usage.codeExample}\n\`\`\``);
+    }
+
+    // The usage files are written for layout authoring as much as for React,
+    // and a dozen of them speak in that vocabulary — `heading(title-4)`,
+    // `Stack(padding:'sm')` — which names nodes and keys the React components
+    // do not have. Said once, next to the lines that do it, rather than left
+    // for the model to reconcile against the prop list on its own.
+    if (c?.usage?.dos?.length || c?.usage?.donts?.length) {
+      parts.push(
+        'Usage guidance (written for layout authoring too: a `heading`, `text` or `spacer` it names is ' +
+          'a layout node, not a component, and a key like `padding` on another component is a layout ' +
+          'key, not a prop — the prop lists are the only source of props):',
+      );
+    }
+    if (c?.usage?.dos?.length) {
+      parts.push(`Web — Do:\n${c.usage.dos.map((d) => `- ${d}`).join('\n')}`);
+    }
+    if (c?.usage?.donts?.length) {
+      parts.push(`Web — Don't:\n${c.usage.donts.map((d) => `- ${d}`).join('\n')}`);
+    }
+
+    parts.push(...nativeSection(k));
+
+    const tokenNames = TOKEN_NAMES.filter((name) =>
+      name.startsWith(`stk-${k.name.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()}-`),
+    );
+    if (tokenNames.length) {
+      parts.push(
+        `Its own component tokens — each one aliases a semantic token (→), and that is the token to name when ` +
+          `asked what colour, size or radius the component uses; override the component token to change it:\n` +
+          tokenNames.map((n) => tokenLine(n, true)).join('\n'),
+      );
+    }
+
+    return parts.join('\n\n');
+  }
+
+  /** @type {string | null} */
+  let packagesCache = null;
+
+  /** The one import fact per platform, so no answer has to guess a package name. */
+  function packagesSection() {
+    if (packagesCache) return packagesCache;
+    packagesCache = [
+      PACKAGES.web ? `Web (React): components are imported from \`${PACKAGES.web}\`.` : null,
+      PACKAGES.native ? `React Native: components are imported from \`${PACKAGES.native}\`.` : null,
+    ]
+      .filter(Boolean)
+      .join('\n');
+    return packagesCache;
+  }
+
+  /**
+   * The grounding block for one question. `context` is the prior turns of the
+   * conversation, newest first, so a follow-up that names no component keeps
+   * the detail of the one it is about. Returns the text, the components it
+   * expanded, the subset the question itself named and the tokens it named,
+   * so the caller can say what the answer was built on without re-deriving
+   * it.
+   * @param {string} question
+   * @param {string[]} [context]
+   * @returns {Grounding}
+   */
+  function buildGrounding(question, context = []) {
+    const named = componentsInQuestion(question);
+    const picked = componentsToExpand(question, context);
+    const namedTokens = tokensInQuestion(question);
+
+    const sections = [
+      `## Every component in the system (${KNOWN.length})\n\n${catalogIndex()}`,
+      `## Packages\n\n${packagesSection()}`,
+      `## Tokens\n\n${tokenList()}`,
+    ];
+
+    if (picked.length) {
+      sections.push(`## The components this conversation is about\n\n${picked.map(detailFor).join('\n\n')}`);
+    }
+
+    if (namedTokens.length) {
+      sections.push(
+        `## The tokens this question names\n\n${namedTokens.map((n) => tokenLine(n, true)).join('\n')}`,
+      );
+    }
+
+    return {
+      text: sections.join('\n\n'),
+      components: picked.map((k) => k.name),
+      named: named.map((k) => k.name),
+      tokens: namedTokens,
+    };
+  }
+
+  return { PACKAGES, buildGrounding, componentsNamedIn, isKnownComponent, isKnownToken, tokensInQuestion };
+}
+
+/**
+ * The instructions the grounding is handed to the model under. Kept beside
+ * the grounding because the two only make sense together: the "every name
+ * must appear in the facts" rule is only honest while `buildGrounding` really
+ * does put the whole catalog in. These are the rules about the design system;
+ * a surface adds its own — how its panel renders, what it can and cannot see.
+ */
+export const WHISPERER_SYSTEM_PROMPT = [
+  'You are Whisperer, the customization assistant for the Stark design system.',
+  'You answer questions about what a component can express, which token to reach for,',
+  'and what to do when neither fits.',
+  '',
+  'Rules:',
+  '- Answer only from the design system facts below. They are generated from the',
+  '  system itself and are current; your own recollection of any design system is not.',
+  '- Every component, prop and token name you write must appear in those facts.',
+  '  If the thing being asked for does not exist, say so plainly and name the',
+  '  closest thing that does — that gap is the most useful answer you can give.',
+  "- A component's prop list in the facts is complete. A prop that is not on it",
+  '  does not exist, `children` included: when the list says a component does',
+  '  not accept `children`, nothing between its tags is rendered and its text',
+  '  goes through the prop the list names. Never write a code example that',
+  '  passes a prop, or places content, the list does not allow.',
+  '- Where a prop lists its values, those are all of them. Name them; never',
+  '  answer with a count when the values are in front of you.',
+  '- The system has two platforms, web (React) and React Native, and the tag on',
+  '  each index line says where a component exists: `web/native` is both,',
+  '  `web` alone means there is no React Native version — say so plainly when',
+  '  asked, and name the closest thing that does exist there. A component that',
+  '  exists on both has two prop lists, and they differ: answer for the platform',
+  "  the question asks about, from that platform's list and that platform's",
+  "  Do/Don't. When the question does not say, answer for web and say that you",
+  '  did.',
+  '- Import lines come from the facts too: the package under "Packages", the',
+  '  import under the component. Never write a package name from memory.',
+  '- A code example may only use components from the index, with props from',
+  '  their lists — never a placeholder component, not even with a comment',
+  '  saying to assume it. For plain text inside a slot, use an HTML element',
+  '  and say the system has no component for it.',
+  '- If the question uses a word you do not find in the facts — a product, a',
+  '  platform, a tool, a component — do not guess what it means and do not answer',
+  '  around it. Say you do not recognise it and ask what it refers to.',
+  '- Tokens are three layers: primitives (shades, the spacing and radius scales),',
+  '  semantic tokens that alias them (`surface.*`, `text.*`, `border.*`, `icon.*`,',
+  '  `state.*`, `chart.*`), and component tokens that alias the semantic ones.',
+  '  Component tokens alias semantic tokens, never primitive shades. Never suggest',
+  '  a raw hex, px value or a `color-shade-*` token where a semantic one exists.',
+  '  When asked what a token "is", give the chain the facts show: its value, the',
+  '  token it aliases (the `→` on its line), and what it is for.',
+  "- A token's line carries its dark-mode value when it has one; a line without",
+  '  `(dark: …)` keeps the same value in both themes. Say which when asked.',
+  '- On React Native a token is the camelCase export named on its line or by the',
+  '  rule at the top of the token list, imported from the `@starklab/stk` module',
+  '  the line names — never a CSS custom property. Colour primitives have no',
+  '  React Native export.',
+  '- Chart colours are the `chart.*` tokens — categorical, sequential, diverging',
+  '  and de-emphasis, each validated for colour-vision deficiency. Never build a',
+  '  chart palette from surface or brand tokens.',
+  '- Be short. Two or three sentences and a small code example beat an essay.',
+].join('\n');