@agent-native/core 0.80.9 → 0.80.10

package/corpus/templates/design/shared/component-model.ts

@@ -0,0 +1,239 @@
+/**
+ * Component model — pure helpers for detecting and describing component
+ * instances from code-layer node data.
+ *
+ * Two detection strategies:
+ *
+ * 1. **Alpine / annotated inline** — the design HTML carries
+ *    `data-agent-native-component="Name"` attributes stamped directly on the
+ *    DOM element that acts as the component root.  Optional sibling attributes
+ *    `data-agent-native-prop-*` carry prop name/value pairs.
+ *
+ * 2. **Real-app (localhost / fusion)** — a Vite/Babel transform injects
+ *    `data-agent-native-component` plus `data-agent-native-prop-*` at
+ *    build time so instances are discoverable from the rendered HTML.  In
+ *    addition, the `component_index` table holds richer metadata (TS prop
+ *    types, cva variants, Storybook stories) indexed by `index-components`.
+ *
+ * This module is **pure** — no DB, no IO.  It operates on `CodeLayerNode`
+ * objects returned by `buildCodeLayerProjection`.
+ *
+ * See DESIGN-STUDIO-PLAN.md §6.1 for context.
+ */
+
+import type { CodeLayerNode } from "./code-layer";
+
+// ─── Component detection attributes ───────────────────────────────────────────
+
+/** The HTML attribute that marks a DOM node as a component root. */
+export const COMPONENT_NAME_ATTR = "data-agent-native-component";
+
+/** Prefix for simple prop attributes stamped next to the component root. */
+export const COMPONENT_PROP_PREFIX = "data-agent-native-prop-";
+
+// ─── Extracted prop value ─────────────────────────────────────────────────────
+
+export interface ComponentPropValue {
+  /** Prop name derived from the attribute (e.g. `"variant"` from `data-agent-native-prop-variant`). */
+  name: string;
+  /** Raw attribute value string as found in the HTML. */
+  value: string;
+}
+
+// ─── Component instance ───────────────────────────────────────────────────────
+
+/**
+ * A component instance detected in the rendered HTML.
+ *
+ * For Alpine / annotated designs this is the authoritative shape.  For
+ * real-app sources the `componentIndexId` ties back to the `component_index`
+ * row, which carries prop types, variants, and Storybook stories.
+ */
+export interface ComponentInstance {
+  /**
+   * Stable instance id — the `data-agent-native-node-id` of the root node
+   * (or the node's `id` field when the node id attribute is absent).
+   */
+  instanceId: string;
+
+  /**
+   * Component name as declared in `data-agent-native-component`.
+   * E.g. `"PrimaryButton"`, `"HeroCard"`.
+   */
+  name: string;
+
+  /**
+   * Simple prop values extracted from `data-agent-native-prop-*` attributes.
+   * Present on annotated Alpine nodes and on real-app nodes instrumented by
+   * the Vite/Babel transform.
+   */
+  props: ComponentPropValue[];
+
+  /**
+   * The `x-data` Alpine expression on the node, when present.  Used by the
+   * Alpine editor to show variant/state controls inline.
+   */
+  alpineData?: string;
+
+  /**
+   * CSS selector that uniquely addresses this instance on the canvas.
+   * Derived from the node's primary selector.
+   */
+  selector: string;
+
+  /**
+   * The `data-agent-native-node-id` value (same as `instanceId` for annotated
+   * nodes; provided separately so callers can pass it as a stable handle to
+   * other code-layer APIs even when `instanceId` is constructed from a
+   * different attribute).
+   */
+  nodeId: string;
+
+  /**
+   * `component_index.id` of the matching persisted component row, when
+   * available.  Populated by `index-components` for real-app sources and used
+   * by `get-component-details` to load prop types and variants.
+   */
+  componentIndexId?: string;
+}
+
+// ─── Detection ────────────────────────────────────────────────────────────────
+
+/**
+ * Return `true` when the node carries a `data-agent-native-component`
+ * annotation — i.e. it is the root of an Alpine or real-app component
+ * instance.
+ */
+export function isComponentInstance(node: CodeLayerNode): boolean {
+  return typeof node.dataAttributes[COMPONENT_NAME_ATTR] === "string";
+}
+
+/**
+ * Return the component name declared on the node, or `null` when the node is
+ * not a component root.
+ */
+export function componentNameFor(node: CodeLayerNode): string | null {
+  const raw = node.dataAttributes[COMPONENT_NAME_ATTR];
+  if (typeof raw !== "string" || !raw.trim()) return null;
+  return raw.trim();
+}
+
+/**
+ * Extract simple prop values from `data-agent-native-prop-*` attributes on a
+ * code-layer node.
+ *
+ * The attribute names are lower-cased by the HTML parser so we convert
+ * `data-agent-native-prop-variant` → `{ name: "variant", value: "..." }`.
+ */
+export function extractProps(node: CodeLayerNode): ComponentPropValue[] {
+  const props: ComponentPropValue[] = [];
+  for (const [attr, value] of Object.entries(node.dataAttributes)) {
+    if (!attr.startsWith(COMPONENT_PROP_PREFIX)) continue;
+    const rawName = attr.slice(COMPONENT_PROP_PREFIX.length);
+    // Convert kebab-case attribute suffix to camelCase prop name.
+    const name = rawName.replace(/-([a-z])/g, (_, c: string) =>
+      c.toUpperCase(),
+    );
+    if (name) props.push({ name, value });
+  }
+  return props;
+}
+
+/**
+ * Build a `ComponentInstance` from a `CodeLayerNode` that carries a
+ * `data-agent-native-component` attribute.
+ *
+ * Returns `null` when the node is not a component root.
+ */
+export function instanceFromNode(
+  node: CodeLayerNode,
+  componentIndexId?: string,
+): ComponentInstance | null {
+  const name = componentNameFor(node);
+  if (!name) return null;
+
+  // `x-data` is stored as a plain attribute (not a data-* attribute) so we
+  // look in `node.attributes` rather than `node.dataAttributes`.
+  const alpineDataRaw = node.attributes["x-data"];
+  const alpineData =
+    typeof alpineDataRaw === "string" ? alpineDataRaw : undefined;
+
+  return {
+    instanceId: node.id,
+    name,
+    props: extractProps(node),
+    alpineData,
+    selector: node.selector,
+    nodeId: node.id,
+    componentIndexId,
+  };
+}
+
+/**
+ * Scan a flat list of `CodeLayerNode` objects and return all component
+ * instances, preserving document order.
+ *
+ * Accepts an optional `indexMap` — a `Map<name, componentIndexId>` — which is
+ * populated by `index-components` after writing to `component_index` and used
+ * to correlate instances with their persisted metadata.
+ */
+export function detectInstances(
+  nodes: CodeLayerNode[],
+  indexMap?: Map<string, string>,
+): ComponentInstance[] {
+  const instances: ComponentInstance[] = [];
+  for (const node of nodes) {
+    if (!isComponentInstance(node)) continue;
+    const name = componentNameFor(node);
+    if (!name) continue;
+    const componentIndexId = indexMap?.get(name);
+    const instance = instanceFromNode(node, componentIndexId);
+    if (instance) instances.push(instance);
+  }
+  return instances;
+}
+
+// ─── Unique component definitions ────────────────────────────────────────────
+
+/**
+ * A distinct component definition derived by collapsing all instances of the
+ * same name into one entry.
+ */
+export interface ComponentDefinition {
+  name: string;
+  /** All instance node ids for this component. */
+  instanceNodeIds: string[];
+  /** Union of all prop names seen across all instances. */
+  observedPropNames: string[];
+}
+
+/**
+ * Collapse a flat list of `ComponentInstance` objects into one
+ * `ComponentDefinition` per unique component name.
+ */
+export function buildDefinitions(
+  instances: ComponentInstance[],
+): ComponentDefinition[] {
+  const map = new Map<
+    string,
+    { instanceNodeIds: string[]; propNames: Set<string> }
+  >();
+
+  for (const instance of instances) {
+    let entry = map.get(instance.name);
+    if (!entry) {
+      entry = { instanceNodeIds: [], propNames: new Set() };
+      map.set(instance.name, entry);
+    }
+    entry.instanceNodeIds.push(instance.nodeId);
+    for (const prop of instance.props) {
+      entry.propNames.add(prop.name);
+    }
+  }
+
+  return Array.from(map.entries()).map(([name, entry]) => ({
+    name,
+    instanceNodeIds: entry.instanceNodeIds,
+    observedPropNames: Array.from(entry.propNames),
+  }));
+}

package/corpus/templates/design/shared/design-review.ts

@@ -0,0 +1,275 @@
+/**
+ * Accessibility audit and visual-diff review types for the Design Studio
+ * Review panel (§6.5 + §4.3).
+ *
+ * Results are produced by `run-design-audit` over the rendered DOM and cached
+ * in `design_review_snapshot` rows. Fix actions are capability-gated (semantic
+ * code fixes are real-app only).
+ */
+
+// ---------------------------------------------------------------------------
+// Accessibility findings
+// ---------------------------------------------------------------------------
+
+export const A11Y_FINDING_SEVERITIES = ["error", "warning", "info"] as const;
+
+export type A11ySeverity = (typeof A11Y_FINDING_SEVERITIES)[number];
+
+export const A11Y_FINDING_CATEGORIES = [
+  "contrast",
+  "tap-target",
+  "focus-visibility",
+  "missing-label",
+  "missing-alt",
+  "reduced-motion",
+  "role",
+  "other",
+] as const;
+
+export type A11yFindingCategory = (typeof A11Y_FINDING_CATEGORIES)[number];
+
+export interface A11yFinding {
+  /** Stable identifier for deduplication and navigation (e.g. `"contrast:node-42"`). */
+  id: string;
+  severity: A11ySeverity;
+  category: A11yFindingCategory;
+  /** Short human-readable summary (e.g. "Contrast ratio 2.1:1 — minimum is 4.5:1"). */
+  message: string;
+  /** Optional longer description or remediation guidance. */
+  detail?: string;
+  /**
+   * The `data-agent-native-node-id` of the offending element, when available.
+   * Used to navigate the canvas to the affected layer.
+   */
+  nodeId?: string;
+  /** CSS selector as a fallback when `nodeId` is absent. */
+  selector?: string;
+  /** WCAG success criterion reference (e.g. "1.4.3"). */
+  wcag?: string;
+  /**
+   * Whether a fix action is available for this finding.
+   * Semantic code fixes are real-app only; contrast/alt fixes may be available
+   * in Alpine via the deterministic write path.
+   */
+  fixAvailable: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Inline auto-fix mapping
+// ---------------------------------------------------------------------------
+//
+// Some a11y findings can be repaired inline against the SQL-backed HTML design
+// content using the same deterministic edit primitives the visual editor uses
+// (`apply-visual-edit`: style / class / textContent). Those primitives can set
+// an inline style value, add/remove/replace a class token, or rewrite leaf text
+// — so the fixes we can apply purely inline are the ones that reduce to one of
+// those operations on a *targeted* node:
+//
+//   - contrast / color   → set an inline `color` (style edit) or swap a text
+//                           color class, raising the foreground contrast.
+//   - tap-target         → add a min-size utility class (e.g. `min-h-[44px]`).
+//   - focus-visibility   → add a `focus-visible:ring-2` utility class.
+//
+// Fixes that require writing a *new attribute* (alt, aria-label,
+// aria-labelledby) or semantic/structural code changes are NOT expressible
+// through the deterministic edit engine's exported intents, so they remain
+// "real-app only" and are surfaced as informational findings (no inline Fix).
+// `a11yFindingToEdit` returns `null` for those.
+
+/**
+ * A single deterministic edit that repairs an a11y finding inline. The shape is
+ * a strict subset of the `apply-visual-edit` `EditIntent` union — only the kinds
+ * the inline (SQL HTML) edit engine can apply without escalating: `style`,
+ * `class`, and `textContent`. The `apply-a11y-fix` action forwards this verbatim
+ * to the shared `applyVisualEdit` primitive.
+ */
+export type A11yFixEdit =
+  | {
+      kind: "style";
+      target: { nodeId?: string; selector?: string };
+      property: string;
+      value: string;
+    }
+  | {
+      kind: "class";
+      target: { nodeId?: string; selector?: string };
+      operation: "add" | "remove" | "replace";
+      className?: string;
+      classNames?: string[];
+      from?: string;
+      to?: string;
+    }
+  | {
+      kind: "textContent";
+      target: { nodeId?: string; selector?: string };
+      value: string;
+    };
+
+/**
+ * A planned inline fix for a finding: the deterministic edit to apply plus a
+ * short human-readable label for the UI / agent.
+ */
+export interface A11yFixPlan {
+  finding: A11yFinding;
+  edit: A11yFixEdit;
+  /** Short human summary, e.g. "Raise text contrast" or "Enlarge tap target". */
+  label: string;
+}
+
+/**
+ * A high-contrast foreground color used as the default contrast remediation
+ * when a finding does not carry an explicit replacement color. Near-black keeps
+ * ≥ 4.5:1 against typical light backgrounds; the agent can refine afterward.
+ */
+const DEFAULT_CONTRAST_COLOR = "#111827";
+
+/** Categories whose default inline fix is a class addition, with the utility. */
+const CLASS_ADD_FIX: Partial<Record<A11yFindingCategory, string>> = {
+  "tap-target": "min-h-[44px] min-w-[44px]",
+  "focus-visibility": "focus-visible:ring-2",
+};
+
+/**
+ * Map an {@link A11yFinding} to a deterministic inline {@link A11yFixPlan}, or
+ * `null` when the finding is not auto-fixable through the inline edit engine.
+ *
+ * Pure and dependency-free so both the Review panel (to decide whether to show
+ * a "Fix" affordance) and the `apply-a11y-fix` action (to compute the edit)
+ * share one source of truth.
+ *
+ * @param finding   The audit finding.
+ * @param overrides Optional caller-supplied values — e.g. a chosen replacement
+ *                  `color` for contrast fixes — that win over the defaults.
+ */
+export function a11yFindingToEdit(
+  finding: A11yFinding,
+  overrides?: { color?: string },
+): A11yFixPlan | null {
+  // A target is required for every inline edit — without a node id or selector
+  // there is nothing to anchor the deterministic patch to.
+  const target =
+    finding.nodeId || finding.selector
+      ? { nodeId: finding.nodeId, selector: finding.selector }
+      : null;
+  if (!target) return null;
+
+  if (finding.category === "contrast") {
+    const color = (overrides?.color ?? "").trim() || DEFAULT_CONTRAST_COLOR;
+    return {
+      finding,
+      label: "Raise text contrast",
+      edit: { kind: "style", target, property: "color", value: color },
+    };
+  }
+
+  const classToAdd = CLASS_ADD_FIX[finding.category];
+  if (classToAdd) {
+    return {
+      finding,
+      label:
+        finding.category === "tap-target"
+          ? "Enlarge tap target"
+          : "Add focus-visible ring",
+      edit: {
+        kind: "class",
+        target,
+        operation: "add",
+        classNames: classToAdd.split(/\s+/).filter(Boolean),
+      },
+    };
+  }
+
+  // missing-alt, missing-label, reduced-motion, role, other → require new
+  // attributes or semantic/structural rewrites the inline engine can't express.
+  return null;
+}
+
+/**
+ * Whether a finding can be auto-fixed inline (i.e. {@link a11yFindingToEdit}
+ * returns a plan). Convenience wrapper for UI gating.
+ */
+export function isA11yFindingAutoFixable(finding: A11yFinding): boolean {
+  return a11yFindingToEdit(finding) !== null;
+}
+
+// ---------------------------------------------------------------------------
+// Visual diff
+// ---------------------------------------------------------------------------
+
+export const VISUAL_DIFF_CHANGE_KINDS = [
+  "added",
+  "removed",
+  "modified",
+  "moved",
+] as const;
+
+export type VisualDiffChangeKind = (typeof VISUAL_DIFF_CHANGE_KINDS)[number];
+
+/**
+ * One changed surface between two design versions.
+ */
+export interface VisualDiffEntry {
+  id: string;
+  kind: VisualDiffChangeKind;
+  /**
+   * The `data-agent-native-node-id` of the changed element, when resolvable.
+   */
+  nodeId?: string;
+  /** CSS selector fallback when `nodeId` is absent. */
+  selector?: string;
+  /** Human-readable description of the change (e.g. "Background color changed"). */
+  description?: string;
+  /**
+   * Bounding box of the changed region in the before/after screenshot,
+   * expressed as fractions [0, 1] of the frame dimensions.
+   */
+  region?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+  /** Before screenshot crop URL or data URL, when available. */
+  beforeImageUrl?: string;
+  /** After screenshot crop URL or data URL, when available. */
+  afterImageUrl?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Review snapshot
+// ---------------------------------------------------------------------------
+
+export const DESIGN_REVIEW_STATUSES = [
+  "pending",
+  "running",
+  "done",
+  "error",
+] as const;
+
+export type DesignReviewStatus = (typeof DESIGN_REVIEW_STATUSES)[number];
+
+/**
+ * Cached accessibility + visual-diff results for a design, optionally scoped
+ * to a base/compare version pair. Stored in `design_review_snapshot` rows.
+ */
+export interface DesignReviewSnapshot {
+  id: string;
+  designId: string;
+  /**
+   * Opaque source reference identifying the screen or file this snapshot
+   * covers (fileId for inline, routeId for localhost/fusion).
+   * `null` when the snapshot covers the entire design.
+   */
+  sourceRef: string | null;
+  /** The older `design_versions` id used as the diff base. `null` for a11y-only runs. */
+  baseVersionId: string | null;
+  /** The newer `design_versions` id being compared against `baseVersionId`. */
+  compareVersionId: string | null;
+  a11yFindings: A11yFinding[];
+  visualDiff: VisualDiffEntry[];
+  status: DesignReviewStatus;
+  /** Error message when `status` is `"error"`. */
+  errorMessage?: string;
+  createdAt: string;
+  updatedAt: string;
+}