@agent-native/core 0.139.0 → 0.140.0

package/corpus/templates/design/shared/authored-color-styles.ts

@@ -0,0 +1,401 @@
+/**
+ * Read the colour each property was authored with, walking the cascade. A
+ * generated design styles through classes, so `el.style` is empty and computed
+ * has already flattened `var()`. Dependency-free: bundled into the bridge.
+ */
+
+const AUTHORED_COLOR_PROPERTIES = [
+  "color",
+  "backgroundColor",
+  "borderColor",
+  "outlineColor",
+  // Not colours themselves, but the only place a shadow's colour keeps its name.
+  "boxShadow",
+  "textShadow",
+] as const;
+
+/**
+ * A shorthand holding `var()` cannot be expanded, so CSSOM serialises its
+ * longhands as "" — indistinguishable from unset.
+ */
+const SHORTHAND_FALLBACK: Record<string, string> = {
+  backgroundColor: "background",
+  borderColor: "border",
+  outlineColor: "outline",
+};
+
+/** Colours these inherit from an ancestor when no rule targets the element. */
+const INHERITED_PROPERTIES = ["color"];
+
+/**
+ * Expanding a shorthand emits these for the longhands it resets, so treating
+ * them as authored would print "initial" in the fill row.
+ */
+const RESET_KEYWORDS = new Set([
+  "initial",
+  "inherit",
+  "unset",
+  "revert",
+  "revert-layer",
+]);
+
+function isAuthoredColor(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    value !== "" &&
+    !RESET_KEYWORDS.has(value.trim().toLowerCase())
+  );
+}
+
+const LINE_STYLE_KEYWORDS = new Set([
+  "none",
+  "hidden",
+  "solid",
+  "dashed",
+  "dotted",
+  "double",
+  "groove",
+  "ridge",
+  "inset",
+  "outset",
+]);
+
+const LINE_WIDTH = /^(thin|medium|thick|-?\d*\.?\d+[a-z%]*)$/i;
+
+/** Split on spaces outside parentheses, so a `var()` fallback stays intact. */
+function splitTopLevel(value: string): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let current = "";
+  for (const char of value) {
+    if (char === "(") depth += 1;
+    else if (char === ")") depth -= 1;
+    if (depth === 0 && /\s/.test(char)) {
+      if (current) parts.push(current);
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+  if (current) parts.push(current);
+  return parts;
+}
+
+/**
+ * The colour component of a `border`/`outline` shorthand. Width and style are
+ * a closed keyword set, so whatever single value is left over is the colour —
+ * without this, `border: 1px solid var(--x)` loses its token name.
+ */
+function lineShorthandColor(value: string): string | null {
+  const rest = splitTopLevel(value).filter((part) => {
+    const lower = part.toLowerCase();
+    return !LINE_STYLE_KEYWORDS.has(lower) && !LINE_WIDTH.test(part);
+  });
+  return rest.length === 1 ? rest[0] : null;
+}
+
+/**
+ * A shorthand only stands in for the colour when it isolates one. Exported for
+ * tests: a real engine leaves the longhand empty here, which happy-dom does not
+ * reproduce, so the wiring alone cannot exercise this.
+ */
+export function shorthandColorValue(
+  shorthand: string,
+  value: string,
+): string | null {
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  if (/url\(|gradient\(/i.test(trimmed)) return null;
+  // A single `var()` may contain spaces (its fallback); anything else with a
+  // space is a layered shorthand, not a colour.
+  if (/^var\(.*\)$/.test(trimmed)) return trimmed;
+  if (shorthand === "border" || shorthand === "outline") {
+    return lineShorthandColor(trimmed);
+  }
+  return /\s/.test(trimmed) ? null : trimmed;
+}
+
+type StyleRuleLike = {
+  selectorText?: string;
+  style?: Record<string, string> & {
+    getPropertyPriority?: (property: string) => string;
+  };
+  conditionText?: string;
+  cssRules?: ArrayLike<unknown>;
+};
+
+/**
+ * Approximate CSS specificity as one comparable number. Approximate is safe:
+ * it only orders selectors that already match, and `authoredMatchesPainted`
+ * still discards a winner that is not what paints. `:is()`/`:not()` inner
+ * specificity is not counted.
+ */
+function selectorSpecificity(selector: string): number {
+  const cleaned = selector
+    .replace(/\\./g, "")
+    .replace(/\[[^\]]*\]/g, " :attr ")
+    .replace(/\(([^()]*)\)/g, " ");
+  const count = (pattern: RegExp) => (cleaned.match(pattern) ?? []).length;
+  const ids = count(/#[\w-]+/g);
+  const classes = count(/\.[\w-]+/g) + count(/:(?!:)[\w-]+/g);
+  const types = count(/(?:^|[\s>+~])[a-zA-Z][\w-]*/g) + count(/::[\w-]+/g);
+  return ids * 10000 + classes * 100 + types;
+}
+
+/** Specificity of the selector in a comma list that actually matches. */
+function matchedSpecificity(element: Element, selectorText: string): number {
+  let best = -1;
+  for (const selector of selectorText.split(",")) {
+    const trimmed = selector.trim();
+    if (!trimmed) continue;
+    try {
+      if (!element.matches(trimmed)) continue;
+    } catch {
+      continue;
+    }
+    best = Math.max(best, selectorSpecificity(trimmed));
+  }
+  return best;
+}
+
+/** Above any selector: only importance can outrank an inline declaration. */
+const INLINE_SPECIFICITY = Number.MAX_SAFE_INTEGER;
+
+interface Candidate {
+  value: string;
+  important: boolean;
+  specificity: number;
+  order: number;
+}
+
+/** Cascade order for declarations that all match: important, then specificity. */
+function beats(next: Candidate, current: Candidate | undefined): boolean {
+  if (!current) return true;
+  if (next.important !== current.important) return next.important;
+  if (next.specificity !== current.specificity) {
+    return next.specificity > current.specificity;
+  }
+  return next.order >= current.order;
+}
+
+function readRules(
+  element: Element,
+  rules: ArrayLike<unknown> | undefined,
+  out: Record<string, Candidate>,
+  counter: { order: number },
+): void {
+  if (!rules) return;
+  for (let index = 0; index < rules.length; index += 1) {
+    const rule = rules[index] as StyleRuleLike | undefined;
+    if (!rule) continue;
+
+    // Tested before `cssRules`: a style rule carries one too (CSS nesting), so
+    // treating anything with `cssRules` as a group skips every declaration.
+    const declaresOwnStyles = Boolean(rule.selectorText && rule.style);
+
+    if (!declaresOwnStyles) {
+      if (!rule.cssRules) continue;
+      // Any grouping rule, not just conditional ones: an `@layer` block holds
+      // cssRules with no conditionText, and Tailwind puts its utilities there.
+      // Layer precedence is not modelled, only membership.
+      if (rule.conditionText === undefined) {
+        readRules(element, rule.cssRules, out, counter);
+        continue;
+      }
+      // A conditional group counts only while it applies, so the walk matches
+      // what the canvas paints.
+      let applies = false;
+      try {
+        applies =
+          typeof window !== "undefined" &&
+          typeof window.matchMedia === "function"
+            ? window.matchMedia(rule.conditionText).matches
+            : false;
+      } catch {
+        applies = false;
+      }
+      if (applies) readRules(element, rule.cssRules, out, counter);
+      continue;
+    }
+
+    if (rule.cssRules?.length) {
+      readRules(element, rule.cssRules, out, counter);
+    }
+
+    if (!rule.selectorText || !rule.style) continue;
+    const specificity = matchedSpecificity(element, rule.selectorText);
+    if (specificity < 0) continue;
+    const order = counter.order++;
+    const style = rule.style;
+    const priority = (name: string) =>
+      style.getPropertyPriority?.(name) === "important";
+
+    const offer = (property: string, value: string, cssName: string) => {
+      const candidate: Candidate = {
+        value,
+        important: priority(cssName),
+        specificity,
+        order,
+      };
+      if (beats(candidate, out[property])) out[property] = candidate;
+    };
+
+    for (const property of AUTHORED_COLOR_PROPERTIES) {
+      const declared = style[property];
+      if (isAuthoredColor(declared)) {
+        offer(property, declared, cssPropertyName(property));
+        continue;
+      }
+      const shorthand = SHORTHAND_FALLBACK[property];
+      if (!shorthand) continue;
+      const shorthandValue = style[shorthand];
+      if (typeof shorthandValue !== "string") continue;
+      const colorOnly = shorthandColorValue(shorthand, shorthandValue);
+      if (colorOnly) offer(property, colorOnly, shorthand);
+    }
+  }
+}
+
+function cssPropertyName(property: string): string {
+  return property.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+}
+
+/**
+ * Whether `authored` actually resolves to the colour the element paints.
+ *
+ * Without this an ancestor's `color: var(--color-text)` gets reported for a
+ * child painted green by its own utility class — a confidently wrong token name,
+ * which is worse than showing the hex. Resolved via a probe child so var()
+ * chains and shorthands are evaluated in the element's own scope.
+ */
+export function authoredMatchesPainted(
+  element: Element,
+  property: string,
+  authored: string,
+): boolean {
+  const view = element.ownerDocument?.defaultView;
+  if (!view || typeof view.getComputedStyle !== "function") return true;
+
+  let painted = "";
+  try {
+    painted =
+      (view.getComputedStyle(element) as unknown as Record<string, string>)[
+        property
+      ] ?? "";
+  } catch {
+    return true;
+  }
+  if (!painted) return true;
+
+  const probe = element.ownerDocument!.createElement("span");
+  const name = cssPropertyName(property);
+  probe.style.setProperty("display", "none");
+  probe.style.setProperty(name, authored);
+  // An unparseable value never lands, and the probe would then just inherit the
+  // element's own colour and compare equal.
+  if (!probe.style.getPropertyValue(name)) return false;
+
+  element.appendChild(probe);
+  let resolved = "";
+  try {
+    resolved =
+      (view.getComputedStyle(probe) as unknown as Record<string, string>)[
+        property
+      ] ?? "";
+  } catch {
+    resolved = "";
+  }
+  probe.remove();
+
+  return resolved === "" || resolved === painted;
+}
+
+function collectForElement(element: Element): Record<string, string> {
+  const ranked: Record<string, Candidate> = {};
+  const counter = { order: 0 };
+
+  try {
+    const doc = element.ownerDocument;
+    // Adopted sheets are not in `styleSheets`, and a runtime CSS injector (the
+    // Tailwind CDN) puts every utility rule there.
+    const sheets = [
+      ...Array.from(doc?.styleSheets ?? []),
+      ...Array.from(
+        (doc as unknown as { adoptedStyleSheets?: ArrayLike<CSSStyleSheet> })
+          ?.adoptedStyleSheets ?? [],
+      ),
+    ];
+    for (const sheet of sheets) {
+      let rules: ArrayLike<unknown> | undefined;
+      try {
+        rules = sheet.cssRules as unknown as ArrayLike<unknown>;
+      } catch {
+        // A cross-origin sheet cannot be read; skip it.
+        continue;
+      }
+      readRules(element, rules, ranked, counter);
+    }
+  } catch (error) {
+    // Silently losing the walk downgrades every token colour to a hex.
+    console.warn(
+      "[design] could not read stylesheets for authored colours; token names will fall back to resolved values",
+      error,
+    );
+  }
+
+  // Inline outranks any selector, but a normal inline declaration still loses
+  // to an `!important` stylesheet one — so it competes rather than overwrites.
+  const inline = (element as HTMLElement).style;
+  if (inline) {
+    const order = counter.order++;
+    for (const property of AUTHORED_COLOR_PROPERTIES) {
+      const value = inline[property as never] as unknown as string;
+      if (!isAuthoredColor(value)) continue;
+      const candidate: Candidate = {
+        value,
+        important:
+          inline.getPropertyPriority?.(cssPropertyName(property)) ===
+          "important",
+        specificity: INLINE_SPECIFICITY,
+        order,
+      };
+      if (beats(candidate, ranked[property])) ranked[property] = candidate;
+    }
+  }
+
+  const out: Record<string, string> = {};
+  for (const [property, candidate] of Object.entries(ranked)) {
+    out[property] = candidate.value;
+  }
+
+  return out;
+}
+
+export function collectAuthoredColorStyles(
+  element: Element,
+): Record<string, string> {
+  const out = collectForElement(element);
+  for (const property of Object.keys(out)) {
+    if (!authoredMatchesPainted(element, property, out[property])) {
+      delete out[property];
+    }
+  }
+
+  // `color` is inherited: a heading with no rule of its own still has a token.
+  for (const property of INHERITED_PROPERTIES) {
+    if (out[property]) continue;
+    let ancestor = element.parentElement;
+    while (ancestor) {
+      const inherited = collectForElement(ancestor)[property];
+      if (inherited) {
+        if (authoredMatchesPainted(element, property, inherited)) {
+          out[property] = inherited;
+        }
+        break;
+      }
+      ancestor = ancestor.parentElement;
+    }
+  }
+
+  return out;
+}

package/corpus/templates/design/shared/resolve-tweaks.ts

@@ -11,13 +11,21 @@
  *  - the snapshot / coding-handoff actions inject so an external agent
  *    continues from the *tuned* design, not the original generated tokens.
  *
- * Keep it pure and dependency-free so the UI and the server actions produce
- * byte-identical output.
+ * Keep it pure so the UI and the server actions produce byte-identical
+ * output. The CSS-safety predicates are re-exported from core so a Brand Kit
+ * token and a tweak value can never be validated by two drifting copies.
  */
 
+import {
+  isSafeCssTokenValue,
+  isSafeCssVarName,
+} from "@agent-native/core/brand-kit/tokens";
+
 import type { TweakDefinition } from "./api.js";
 import { sourceContentHash } from "./source-workspace.js";
 
+export { isSafeCssTokenValue, isSafeCssVarName };
+
 export type TweakSelections = Record<string, string | number | boolean>;
 
 /**
@@ -49,22 +57,6 @@ export function tweakSelectionsHash(
  * emitted directly, which lets token edits persist vars that were not part of
  * the generated tweak definition list.
  */
-const CSS_CUSTOM_PROPERTY_NAME = /^--[-_a-zA-Z0-9]+$/;
-
-export function isSafeCssVarName(value: string): boolean {
-  return CSS_CUSTOM_PROPERTY_NAME.test(value);
-}
-
-export function isSafeCssTokenValue(value: string): boolean {
-  return (
-    value.length > 0 &&
-    value.length <= 300 &&
-    !/[;{}<>]/.test(value) &&
-    !/\/\*/.test(value) &&
-    !/[\u0000-\u001f\u007f]/.test(value)
-  );
-}
-
 export function resolveTweaksToCssVars(
   tweaks: TweakDefinition[],
   selections: TweakSelections,

package/dist/brand-kit/index.d.ts

@@ -16,6 +16,7 @@
  */
 export * from "./types.js";
 export * from "./brand-signals.js";
+export * from "./tokens.js";
 export { extractDesignTokensFromUrl, validateUrl, parseOwnerRepo, fetchGitHubJson, fetchGitHubJsonResult, fetchGitHubRaw, parseTailwindConfig, parseCss, detectStylingFramework, createCodeAnalysisState, analyzeCodeFile, analyzeCssFile, analyzeTailwindConfig, analyzeJsonTheme, analyzePackageJson, analyzeThemeSourceFile, addFont, extractCssVars, extractCodeColors, extractCodeFonts, extractDocumentColors, extractDocumentFonts, classifyFile, suggestionsForType, unique, MAX_FILES, MAX_FILE_SIZE, FETCH_TIMEOUT, ROOT_PATTERNS, SECONDARY_PATHS, CODE_MAX_FILES, CODE_MAX_TOTAL_BYTES, } from "../server/design-token-utils.js";
 export type { ContentType, ParsedCss, ParsedTailwindConfig, CodeAnalysisState, UrlExtractionResult, GitHubFetchOptions, GitHubJsonResult, } from "../server/design-token-utils.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/brand-kit/index.js

@@ -16,6 +16,7 @@
  */
 export * from "./types.js";
 export * from "./brand-signals.js";
+export * from "./tokens.js";
 // Import-source parsing + token extraction (Tailwind/CSS/GitHub/URL/document/
 // code analysis). These already power the import-* actions across templates.
 export { 

package/dist/brand-kit/tokens.d.ts

@@ -0,0 +1,92 @@
+/**
+ * `@agent-native/core/brand-kit/tokens`
+ *
+ * Pure helpers for the named-token vocabulary a Brand Kit stores alongside its
+ * seven color roles. Kept on its own subpath (no `design-token-utils` re-export)
+ * so browser code can import the CSS-safety predicates without pulling the
+ * server-side extraction stack into the bundle.
+ */
+import type { BrandKitToken, BrandKitTokenType } from "./types.js";
+/**
+ * Upper bound on a single kit's stored vocabulary. Large systems legitimately
+ * define hundreds of tokens; this only stops an unbounded scrape landing in SQL.
+ */
+export declare const MAX_BRAND_KIT_TOKENS = 500;
+export declare function isSafeCssVarName(value: string): boolean;
+/**
+ * Token values are spliced raw into `:root { … }` declarations, so anything that
+ * could terminate a declaration or break out of a `<style>` element is unsafe.
+ */
+export declare function isSafeCssTokenValue(value: string): boolean;
+export declare function isColorTokenValue(value: string): boolean;
+/**
+ * Bucket a token, trusting the value's shape over the name's keywords.
+ *
+ * Name-first classification called Primer's `--text-body-size-medium: 1rem` a
+ * color because the name contains "text", which then rendered a swatch with
+ * `background: 1rem`. A dimension is never a color however the token is named.
+ */
+export declare function classifyBrandKitToken(name: string, value: string): BrandKitTokenType;
+/** Title-case display name derived from a CSS var, e.g. `--primary-color`. */
+export declare function friendlyTokenName(cssVar: string): string;
+export type BrandKitTokenRejectionReason = "malformed" | "unsafe-css-var" | "unsafe-value" | "over-limit";
+export interface BrandKitTokenRejection {
+    reason: BrandKitTokenRejectionReason;
+    /** Best-effort identifier for the offending entry, for error messages. */
+    label: string;
+}
+export interface NormalizedBrandKitTokens {
+    tokens: BrandKitToken[];
+    /**
+     * Entries that could not be stored. Callers must surface these — a kit that
+     * silently kept 4 of 40 tokens reads downstream as a 4-token design system.
+     */
+    rejected: BrandKitTokenRejection[];
+}
+/**
+ * Coerce untrusted token JSON into storable tokens, reporting every entry it
+ * could not accept. Later duplicates of a `cssVar` win, matching the overlay
+ * order importers use.
+ */
+export declare function normalizeBrandKitTokens(input: unknown): NormalizedBrandKitTokens;
+/** Human-readable summary of why tokens were refused, for thrown errors. */
+export declare function describeBrandKitTokenRejections(rejected: readonly BrandKitTokenRejection[]): string;
+/**
+ * The seven colour roles plus radius/spacing, as tokens. Derived from a kit's
+ * summary fields rather than named by the source system, so they carry no
+ * `group`.
+ */
+export declare function brandKitRoleTokens(data: {
+    colors?: object | null;
+    borders?: {
+        radius?: string;
+    } | null;
+    spacing?: object | null;
+} | null | undefined, source?: string): BrandKitToken[];
+/**
+ * Read a kit's named tokens out of a raw CSS block. A kit's `customCSS` already
+ * spells out the source system's real token names. Declaration order wins on
+ * duplicates, matching the cascade.
+ */
+export declare function parseBrandKitTokensFromCss(css: string, source?: string): BrandKitToken[];
+/**
+ * The kit's named vocabulary: its stored `tokens` when it has them, else the
+ * names its `customCSS` declares. Kits predating `tokens` still carry real names
+ * in CSS, so reading only `tokens` would report them as having none.
+ */
+export declare function resolveBrandKitTokens(data: {
+    tokens?: unknown;
+    customCSS?: unknown;
+} | null | undefined, cssSource?: string): BrandKitToken[];
+export interface BrandKitTokenGroup {
+    /** The source's own group path when it has one, else the token type. */
+    label: string;
+    type: BrandKitTokenType;
+    tokens: BrandKitToken[];
+}
+/**
+ * Group tokens for display, preserving the source's collection paths. Groups sort
+ * by token type so colors lead, then alphabetically within a type.
+ */
+export declare function groupBrandKitTokens(tokens: readonly BrandKitToken[]): BrandKitTokenGroup[];
+//# sourceMappingURL=tokens.d.ts.map