inkbridge 0.1.0-beta.21 → 0.1.0-beta.23

package/src/text/inline-text.ts

@@ -1,6 +1,6 @@
 import { type RGB, parseColor } from '../tokens';
 import { resolveTextColorValue, extractTextColorToken } from '../tokens';
-import { getLineHeightFromClasses, TAG_TYPOGRAPHY, createTextNode, type CreateTextOptions } from './text-builder';
+import { getLineHeightFromClasses, TAG_TYPOGRAPHY, createTextNode, queueFontLoad, type CreateTextOptions } from './text-builder';
 import { tailwindClassesToStyle, type TailwindStyle } from '../tailwind';
 import { type NodeIR, type NodeIRElement } from '../tailwind';
 import type { RenderContext } from '../design-system';
@@ -8,13 +8,59 @@ import { type NodeLayoutComputed } from '../layout';
 import { INLINE_TEXT_TAGS } from './text-builder';
 import { TOKENS, getThemeFontFamily } from '../tokens';
 import { getFontStyleCandidatesForFamily, inferFontWeight } from './font-style-resolver';
+import { applyTruncation, getTruncateFromClasses, markForTruncation } from './text-truncate';
+
+/**
+ * Find a `truncate` / `line-clamp-N` class anywhere in an inline
+ * collapse tree. The collapse merges multiple elements into one
+ * TextNode, so a truncate on any participating element (the wrapping
+ * `<td>` OR an inner `<span>`) should mark the resulting node.
+ *
+ * Walk order: the outer node's own classes first, then descend into
+ * each child (or `childrenOverride` when caller has pre-filtered).
+ * First match wins — mirrors `getTruncateFromClasses` precedence.
+ */
+export function findTruncateInInlineTree(
+  node: NodeIR,
+  childrenOverride?: NodeIR[]
+): { maxLines: number } | null {
+  if (node.kind === 'element') {
+    const own = getTruncateFromClasses(node.classes);
+    if (own) return own;
+  }
+  const kids = childrenOverride
+    ?? ((node.kind === 'element' || node.kind === 'fragment') ? node.children : []);
+  for (let i = 0; i < kids.length; i++) {
+    const child = kids[i];
+    if (child.kind === 'element') {
+      const found = getTruncateFromClasses(child.classes);
+      if (found) return found;
+    }
+    if (child.kind === 'element' || child.kind === 'fragment') {
+      const nested = findTruncateInInlineTree(child);
+      if (nested) return nested;
+    }
+  }
+  return null;
+}
 
 export type InlineTextSegment = {
   text: string;
   fill?: RGB | null;
   fontStyle?: string;
+  // Per-segment font family override. Used for inline mono-family tags
+  // (`<code>`, `<kbd>`, `<samp>`, `<var>`) so their runs render in the
+  // theme's mono font while the surrounding paragraph stays in sans —
+  // matching browser default styling without breaking paragraph flow.
+  fontFamily?: string;
 };
 
+// Inline tags whose runs should render with the theme's mono font family.
+// Keep aligned with INLINE_TEXT_TAGS in text-builder.ts — adding a tag here
+// without listing it there means the run gets isolated into its own block
+// frame and the mono override is never applied.
+const MONO_INLINE_TAGS = new Set(['code', 'kbd', 'samp', 'var']);
+
 const BLOCK_TEXT_TAGS = new Set(['h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'p', 'li']);
 const FONT_WEIGHT_TO_STYLE: Record<string, string> = {
   'font-thin': 'Thin',
@@ -100,12 +146,17 @@ function normalizeInlineSegments(segments: InlineTextSegment[]): InlineTextSegme
 
 function collectInlineSegments(
   node: NodeIR,
-  parentStyle: { fill?: RGB | null; fontStyle?: string },
+  parentStyle: { fill?: RGB | null; fontStyle?: string; fontFamily?: string },
   colorGroup: Record<string, string>,
   theme: string
 ): InlineTextSegment[] {
   if (node.kind === 'text') {
-    return [{ text: node.text, fill: parentStyle.fill, fontStyle: parentStyle.fontStyle }];
+    return [{
+      text: node.text,
+      fill: parentStyle.fill,
+      fontStyle: parentStyle.fontStyle,
+      fontFamily: parentStyle.fontFamily,
+    }];
   }
   if (node.kind === 'fragment') {
     const parts: InlineTextSegment[] = [];
@@ -123,7 +174,19 @@ function collectInlineSegments(
     if (node.tagLower === 'strong' || node.tagLower === 'b') {
       fontStyle = ensureAtLeastBold(fontStyle);
     }
-    const nextStyle = { fill: fill, fontStyle: fontStyle };
+    let fontFamily = parentStyle.fontFamily;
+    if (MONO_INLINE_TAGS.has(node.tagLower)) {
+      const mono = getThemeFontFamily(TOKENS, theme, 'mono');
+      if (mono) {
+        fontFamily = mono;
+        // Pre-queue the mono variant so the setRangeFontName call later
+        // doesn't silently no-op on a not-yet-loaded font. Queue both
+        // Regular and Bold — `<strong><code>` chains the styles.
+        queueFontLoad(mono, 'Regular');
+        queueFontLoad(mono, 'Bold');
+      }
+    }
+    const nextStyle = { fill: fill, fontStyle: fontStyle, fontFamily: fontFamily };
     const parts: InlineTextSegment[] = [];
     for (const child of node.children || []) {
       parts.push.apply(parts, collectInlineSegments(child, nextStyle, colorGroup, theme));
@@ -146,7 +209,8 @@ export function createInlineTextNode(
   context: RenderContext,
   colorGroup: Record<string, string>,
   theme: string,
-  layoutComputed: NodeLayoutComputed
+  layoutComputed: NodeLayoutComputed,
+  childrenOverride?: NodeIR[]
 ): TextNode | null {
   const baseFillValue = resolveTextColorValue(
     textStyle.text || context.textColor,
@@ -159,9 +223,22 @@ export function createInlineTextNode(
     node.classes,
     context.textFontStyle || (context.textBold ? 'Bold' : undefined)
   );
-  const segments = normalizeInlineSegments(
-    collectInlineSegments(node, { fill: baseFill, fontStyle: baseFontStyle }, colorGroup, theme)
-  );
+  // The caller can hand us a pre-filtered child list (e.g. after the
+  // responsive-hidden filter in ui-builder). If given, iterate it directly
+  // so hidden spans don't sneak back in via collectInlineSegments walking
+  // the raw node.children.
+  const inheritedStyle = { fill: baseFill, fontStyle: baseFontStyle };
+  let rawSegments: InlineTextSegment[];
+  if (childrenOverride) {
+    rawSegments = [];
+    for (let i = 0; i < childrenOverride.length; i++) {
+      const parts = collectInlineSegments(childrenOverride[i], inheritedStyle, colorGroup, theme);
+      rawSegments.push.apply(rawSegments, parts);
+    }
+  } else {
+    rawSegments = collectInlineSegments(node, inheritedStyle, colorGroup, theme);
+  }
+  const segments = normalizeInlineSegments(rawSegments);
   if (segments.length === 0) return null;
   const textValue = segments.map(seg => seg.text).join('');
 
@@ -217,11 +294,20 @@ export function createInlineTextNode(
         // ignore
       }
     }
-    if (seg.fontStyle && seg.fontStyle !== baseStyle) {
-      const styleCandidates = getFontStyleCandidatesForFamily(fontFamily, seg.fontStyle);
+    // Resolve effective family + style for this segment. A per-segment
+    // `fontFamily` override (mono inline tags like `<code>`) takes precedence
+    // over the paragraph's base family. When the family changes we must
+    // setRangeFontName even if the style matches the base, otherwise the run
+    // stays in the surrounding sans family.
+    const segFamily = seg.fontFamily || fontFamily;
+    const segStyle = seg.fontStyle || baseStyle;
+    const familyChanged = seg.fontFamily && seg.fontFamily !== fontFamily;
+    const styleChanged = seg.fontStyle && seg.fontStyle !== baseStyle;
+    if (familyChanged || styleChanged) {
+      const styleCandidates = getFontStyleCandidatesForFamily(segFamily, segStyle);
       for (const candidate of styleCandidates) {
         try {
-          textNode.setRangeFontName(start, end, { family: fontFamily, style: candidate });
+          textNode.setRangeFontName(start, end, { family: segFamily, style: candidate });
           break;
         } catch (_err) {
           // try next candidate
@@ -258,7 +344,21 @@ export function createInlineTextNode(
     || node.classes.includes('w-full')
     || shouldInheritContainerWidth;
 
-  if (shouldConstrain && constrainWidth) {
+  // Text truncation: the inline-collapse merges multiple elements
+  // into one TextNode, so `truncate` / `line-clamp-N` on any
+  // participating element (the outer container OR an inner span)
+  // must mark the resulting node. Mark unconditionally so the
+  // deferred truncation pass (e.g. table-layout's per-cell apply)
+  // can re-truncate once a final width is known.
+  const inlineTruncate = findTruncateInInlineTree(node, childrenOverride);
+  if (inlineTruncate) {
+    markForTruncation(textNode, inlineTruncate.maxLines);
+    if (constrainWidth) {
+      const fs = typeof textNode.fontSize === 'number' ? textNode.fontSize : undefined;
+      const lh = getLineHeightFromClasses(node.classes, fs ?? 14) ?? undefined;
+      applyTruncation(textNode, constrainWidth, inlineTruncate.maxLines, lh);
+    }
+  } else if (shouldConstrain && constrainWidth) {
     try {
       textNode.textAutoResize = 'HEIGHT';
       textNode.resize(constrainWidth, textNode.height);

package/src/text/text-builder.ts

@@ -26,7 +26,7 @@ export function waitForAllFonts(): Promise<void> {
   return Promise.all(FONT_LOAD_PROMISES).then(() => undefined);
 }
 
-export const INLINE_TEXT_TAGS = new Set(['span', 'a', 'label', 'small', 'strong', 'em', 'b', 'i']);
+export const INLINE_TEXT_TAGS = new Set(['span', 'a', 'label', 'small', 'strong', 'em', 'b', 'i', 'code', 'kbd', 'samp', 'var', 'mark', 'sub', 'sup', 'u', 'q', 'cite']);
 
 export const TAG_TYPOGRAPHY: Record<string, { fontSize: number; bold?: boolean; lineHeight?: number }> = {
   h1: { fontSize: 32, bold: true, lineHeight: 40 },
@@ -43,7 +43,7 @@ export const TAG_TYPOGRAPHY: Record<string, { fontSize: number; bold?: boolean;
   small: { fontSize: 12 },
 };
 
-function queueFontLoad(family: string, style: string): void {
+export function queueFontLoad(family: string, style: string): void {
   const key = family + ':' + style;
   if (FONT_LOAD_STATE[key]) return;
   FONT_LOAD_STATE[key] = 'loading';

package/src/text/text-truncate.ts

@@ -0,0 +1,101 @@
+/**
+ * Text-truncation primitives shared by the immediate (render-time) and
+ * deferred (post-layout) truncation paths.
+ *
+ * The renderer marks every TextNode that came from a `truncate` /
+ * `line-clamp-N` source — even when the parent's width isn't yet
+ * known. Later passes (the table column-alignment pass, any other
+ * deferred-layout step) can then find marked nodes and apply the
+ * truncation once a final width is available.
+ *
+ * Keep this file self-contained: no React/Tailwind imports, no
+ * `RenderContext` coupling. Anything calling `applyTruncation` already
+ * has the width and max-lines it needs.
+ */
+
+const MARK_KEY = 'inkbridge:truncate-max-lines';
+
+/**
+ * Parse `truncate` / `line-clamp-N` from a Tailwind class list. Returns
+ * `maxLines` for the matched utility, or `null` when neither is
+ * present. Centralised here so every site that creates a TextNode can
+ * use the same source of truth (avoid the recurring drift seen across
+ * the three text-rendering paths in `ui-builder.ts`).
+ */
+export function getTruncateFromClasses(classes: string[]): { maxLines: number } | null {
+  if (classes.includes('truncate')) return { maxLines: 1 };
+  for (const cls of classes) {
+    const m = cls.match(/^line-clamp-(\d+)$/);
+    if (m) {
+      const n = parseInt(m[1], 10);
+      if (Number.isFinite(n) && n > 0) return { maxLines: n };
+    }
+  }
+  return null;
+}
+
+/**
+ * Tag a TextNode as a truncation target. Idempotent. Stores `maxLines`
+ * so the deferred pass picks the same value the renderer would have
+ * applied immediately.
+ */
+export function markForTruncation(textNode: TextNode, maxLines: number): void {
+  if (!(maxLines > 0)) return;
+  try {
+    textNode.setPluginData(MARK_KEY, String(maxLines));
+  } catch (_err) {
+    // pluginData write can fail on certain node types in older Figma
+    // plugin sandbox versions — best effort only.
+  }
+}
+
+/**
+ * Returns the marked maxLines value, or `null` when the node was
+ * never marked (or the mark was cleared). Used by the deferred pass
+ * to decide whether to act on a TextNode it finds while walking.
+ */
+export function readTruncationMark(textNode: TextNode): number | null {
+  try {
+    const raw = textNode.getPluginData(MARK_KEY);
+    if (!raw) return null;
+    const n = parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : null;
+  } catch (_err) {
+    return null;
+  }
+}
+
+/**
+ * Apply CSS `text-overflow: ellipsis` semantics to a Figma TextNode.
+ * `maxWidth` is the cell/container content width the text must fit
+ * inside; `maxLines` controls how many lines are kept before the
+ * ellipsis (1 for `truncate`, N for `line-clamp-N`).
+ *
+ * `lineHeight` is optional — when omitted we derive a sensible value
+ * from the node's `fontSize` (×1.5, mirroring Tailwind's default
+ * `leading-normal`). Callers that have the resolved line-height from
+ * the original class list (e.g. when the source had explicit
+ * `leading-*`) should pass it explicitly so the height matches.
+ *
+ * Errors are swallowed: `textTruncation` is unavailable in older
+ * Figma plugin runtimes, and we'd rather render an untruncated cell
+ * than abort the whole table.
+ */
+export function applyTruncation(
+  textNode: TextNode,
+  maxWidth: number,
+  maxLines: number,
+  lineHeight?: number,
+): void {
+  if (!(maxWidth > 0) || !(maxLines > 0)) return;
+  try {
+    const fs = typeof textNode.fontSize === 'number' ? textNode.fontSize : 14;
+    const lh = lineHeight && lineHeight > 0 ? lineHeight : Math.ceil(fs * 1.5);
+    textNode.textTruncation = 'ENDING';
+    textNode.maxLines = maxLines;
+    textNode.resize(maxWidth, Math.max(lh, lh * maxLines));
+  } catch (_err) {
+    // truncation not supported / resize rejected; the cell will keep
+    // its untruncated text but rendering continues.
+  }
+}

package/src/tokens/tokens.ts

@@ -369,44 +369,135 @@ function cloneTokens<T>(value: T): T {
   return JSON.parse(JSON.stringify(value));
 }
 
-function buildTokensFromScanned(map: ScannedTokenMap, baseSnapshot: Tokens): Tokens {
+/**
+ * Build TOKENS from a successful CSS / DTCG scan. The result reflects
+ * the consumer's source files *exactly* — no merge with the embedded
+ * snapshot. The embedded snapshot is now used ONLY as a pre-scan
+ * placeholder (see `applyScannedTokens` below) so the design-tokens
+ * panel isn't blank during the brief window before the first scan
+ * completes.
+ *
+ * Previously this function deep-merged scanned tokens on top of the
+ * embedded snapshot, which leaked inkbridge-marketing-specific values
+ * (e.g. a `heading: Playfair Display` font role) into every other
+ * consumer's panel — confusing because consumers never wrote those
+ * tokens and the values were arbitrary defaults from this plugin's
+ * own marketing site.
+ *
+ * # Concern #2 — planned follow-up
+ *
+ * Designers also need access to the FULL Tailwind palette in Figma
+ * (blue-500, slate-200, etc.) as Figma variables, separate from the
+ * consumer's custom tokens. That should be a separate pipeline that
+ * reads Tailwind's actual built-in `@theme` (from the `tailwindcss`
+ * package, not from a frozen snapshot), exposes those values as Figma
+ * variables for designer convenience, and keeps the Design Tokens
+ * panel focused on the consumer's overrides only. Tracked in
+ * `tools/figma-plugin/.ai/architecture.md` § "Future work".
+ */
+function buildTokensFromScanned(map: ScannedTokenMap): Tokens {
   const scannedPatch = buildTokenPatchFromScanned(map);
   const out: Tokens = {};
 
-  // Keep core as-is (scanner currently maps fonts into theme blocks).
-  if (baseSnapshot.core) {
-    out.core = cloneTokens(baseSnapshot.core);
-  }
-
-  const basePrimary = (baseSnapshot.primary && typeof baseSnapshot.primary === 'object')
-    ? (baseSnapshot.primary as ThemeTokens)
-    : {};
   const scannedPrimary = (scannedPatch.primary && typeof scannedPatch.primary === 'object')
-    ? (scannedPatch.primary as ThemeTokens)
+    ? cloneTokens(scannedPatch.primary as ThemeTokens) as ThemeTokens
     : {};
-  const primaryTheme = mergeTokens(cloneTokens(basePrimary), scannedPrimary) as ThemeTokens;
-  out.primary = primaryTheme;
+  out.primary = scannedPrimary;
 
   const scannedThemeNames = Object.keys(map.themes || {}).filter((name) => name && name !== 'primary');
   for (let i = 0; i < scannedThemeNames.length; i++) {
     const themeName = scannedThemeNames[i];
     const scannedTheme = scannedPatch[themeName];
     if (!scannedTheme || typeof scannedTheme !== 'object') continue;
-    // CSS theme blocks are often overrides; inherit from primary and apply overrides.
-    out[themeName] = mergeTokens(cloneTokens(primaryTheme), scannedTheme as ThemeTokens) as ThemeTokens;
+    // Secondary themes are normally CSS overrides on top of primary —
+    // inherit primary's resolved values then apply per-key overrides.
+    // This is a CONSUMER-to-CONSUMER merge (no embedded values touched).
+    out[themeName] = mergeTokens(cloneTokens(scannedPrimary), scannedTheme as ThemeTokens) as ThemeTokens;
   }
 
   return out;
 }
 
 export function applyScannedTokens(map: ScannedTokenMap | null | undefined): void {
+  // Pre-scan placeholder OR consumer has no `globals.css` / DTCG file
+  // at all — fall back to the embedded snapshot so the panel renders
+  // SOMETHING. This is the only path that surfaces the embedded values
+  // post-refactor; once a real scan completes (`map.mode !== 'embedded'`)
+  // TOKENS reflects the consumer's CSS exclusively.
   if (!map || map.mode === 'embedded') {
     TOKENS = cloneTokens(EMBEDDED_TOKENS_SNAPSHOT);
     return;
   }
+  TOKENS = buildTokensFromScanned(map);
+}
+
+/**
+ * Per-theme / per-group set of token keys the consumer actually wrote in
+ * their own files. Distinct from TOKENS — which holds the FULL merged
+ * map (consumer overrides on top of imported Tailwind defaults) for
+ * runtime resolution. `CONSUMER_TOKEN_KEYS` exists so the Design Tokens
+ * panel can filter the display down to only what the consumer owns,
+ * avoiding noise like a leaked `serif: Cambria` or the lone Tailwind
+ * `spacing: 0.25rem` baseline that the consumer never wrote.
+ *
+ * Structure: `CONSUMER_TOKEN_KEYS[theme][group] = Set<key>`.
+ * Empty when no consumer-only scan is available (pre-scan, embedded
+ * fallback, DTCG mode where the file IS the consumer's source).
+ */
+export const CONSUMER_TOKEN_KEYS: Record<string, Record<string, Set<string>>> = {};
 
-  const base = cloneTokens(EMBEDDED_TOKENS_SNAPSHOT) as Tokens;
-  TOKENS = buildTokensFromScanned(map, base);
+/**
+ * Mirror of `applyScannedTokens` but for the consumer-only scan result
+ * coming from `readConsumerOwnedTokenMap`. Populates `CONSUMER_TOKEN_KEYS`
+ * so demoFrame* can filter displayed entries to consumer overrides only.
+ */
+export function applyConsumerOwnedTokens(map: ScannedTokenMap | null | undefined): void {
+  // Wipe — a re-scan replaces the previous run's set wholesale.
+  for (const k of Object.keys(CONSUMER_TOKEN_KEYS)) delete CONSUMER_TOKEN_KEYS[k];
+  if (!map || map.mode === 'embedded') return;
+  const patch = buildTokenPatchFromScanned(map);
+  for (const themeName of Object.keys(patch)) {
+    const themeBlock = patch[themeName];
+    if (!themeBlock || typeof themeBlock !== 'object') continue;
+    const perGroup: Record<string, Set<string>> = {};
+    for (const groupName of Object.keys(themeBlock)) {
+      const group = (themeBlock as Record<string, unknown>)[groupName];
+      if (!group || typeof group !== 'object') continue;
+      perGroup[groupName] = new Set(Object.keys(group as Record<string, unknown>));
+    }
+    CONSUMER_TOKEN_KEYS[themeName] = perGroup;
+  }
+}
+
+/**
+ * Returns true when the consumer-only scan has the given theme/group/key
+ * combination. Behaviour:
+ *
+ *   1. `CONSUMER_TOKEN_KEYS` is COMPLETELY empty (no themes at all) →
+ *      no consumer-only scan ran (pre-scan, embedded fallback, older
+ *      CLI output without `consumerTokens`). Graceful fallback: return
+ *      `true` for everything so the panel keeps its pre-Concern-#2
+ *      behaviour and shows whatever's in TOKENS.
+ *
+ *   2. A scan ran (at least one theme has entries) but THIS theme is
+ *      absent → consumer didn't write any tokens for this theme. Hide
+ *      everything for this theme.
+ *
+ *   3. A scan ran, the theme has entries, but THIS group is absent →
+ *      consumer didn't write anything in this group (e.g. greenhouse
+ *      defines fonts + colors but no `--spacing-*` / `--breakpoint-*`).
+ *      Hide everything for this group — that's the whole point of
+ *      Concern #2.
+ *
+ *   4. Group is present → check membership.
+ */
+export function isConsumerOwnedToken(theme: string, group: string, key: string): boolean {
+  if (Object.keys(CONSUMER_TOKEN_KEYS).length === 0) return true;
+  const themeKeys = CONSUMER_TOKEN_KEYS[theme];
+  if (!themeKeys) return false;
+  const groupKeys = themeKeys[group];
+  if (!groupKeys) return false;
+  return groupKeys.has(key);
 }
 
 export function maybeApplyVariableTokens(): boolean {