@agent-native/core 0.80.9 → 0.80.11

package/corpus/templates/design/actions/remove-motion-timeline.ts

@@ -0,0 +1,196 @@
+/**
+ * remove-motion-timeline — ATOMIC delete of a motion timeline row and its
+ * managed `<style data-agent-native-motion>` block (§6.3).
+ *
+ * Steps performed atomically:
+ * 1. Verify the timeline belongs to this design and the caller has editor access.
+ * 2. Delete the `motion_timeline` row.
+ * 3. Remove the managed CSS block from the design's HTML content.
+ * 4. Persist the cleaned HTML via the same Yjs/collab + SQL path used by
+ *    apply-visual-edit.
+ */
+
+import { defineAction } from "@agent-native/core";
+import {
+  agentEnterDocument,
+  agentLeaveDocument,
+  applyText,
+  getText,
+  hasCollabState,
+  seedFromText,
+} from "@agent-native/core/collab";
+import { accessFilter, assertAccess } from "@agent-native/core/sharing";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import "../server/db/index.js"; // ensure registerShareableResource runs
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+const MOTION_STYLE_OPEN = "<style data-agent-native-motion>";
+const MOTION_STYLE_CLOSE = "</style>";
+
+function removeMotionStyleBlock(html: string): string {
+  const openIdx = html.indexOf(MOTION_STYLE_OPEN);
+  if (openIdx === -1) return html;
+  const closeIdx = html.indexOf(
+    MOTION_STYLE_CLOSE,
+    openIdx + MOTION_STYLE_OPEN.length,
+  );
+  if (closeIdx === -1) return html;
+  // Also trim the optional newline that injectMotionStyle adds after the block.
+  const end = closeIdx + MOTION_STYLE_CLOSE.length;
+  const tail = html[end] === "\n" ? end + 1 : end;
+  return html.slice(0, openIdx) + html.slice(tail);
+}
+
+async function liveFileContent(
+  fileId: string,
+  storedContent: string,
+): Promise<string> {
+  try {
+    if (await hasCollabState(fileId)) {
+      const live = await getText(fileId, "content");
+      if (typeof live === "string") return live;
+    }
+  } catch {
+    // Best-effort; SQL is the fallback.
+  }
+  return storedContent;
+}
+
+// ─── Action ───────────────────────────────────────────────────────────────────
+
+export default defineAction({
+  description:
+    "Atomically delete a motion timeline row and remove the managed " +
+    "<style data-agent-native-motion> block from the design's HTML. " +
+    "This is the inverse of apply-motion-edit. The HTML is persisted via " +
+    "the same Yjs/collab path so live editors see the change immediately.",
+  schema: z.object({
+    designId: z.string().describe("Design project ID."),
+    timelineId: z.string().describe("motion_timeline.id to delete."),
+    fileId: z
+      .string()
+      .optional()
+      .describe(
+        "Target design_files.id. Defaults to the design's primary index.html " +
+          "when omitted.",
+      ),
+  }),
+  run: async ({ designId, timelineId, fileId: fileIdInput }) => {
+    await assertAccess("design", designId, "editor");
+
+    const db = getDb();
+    const now = new Date().toISOString();
+
+    // ── 1. Verify timeline exists and belongs to this design ────────────────
+    const [timeline] = await db
+      .select({ id: schema.motionTimeline.id })
+      .from(schema.motionTimeline)
+      .where(
+        and(
+          eq(schema.motionTimeline.id, timelineId),
+          eq(schema.motionTimeline.designId, designId),
+        ),
+      )
+      .limit(1);
+
+    if (!timeline) {
+      throw new Error(
+        `motion_timeline not found for this design: ${timelineId}`,
+      );
+    }
+
+    // ── 2. Resolve the target HTML file ─────────────────────────────────────
+    const fileConditions = [
+      accessFilter(schema.designs, schema.designShares),
+      eq(schema.designFiles.designId, designId),
+    ];
+    if (fileIdInput) {
+      fileConditions.push(eq(schema.designFiles.id, fileIdInput));
+    } else {
+      fileConditions.push(eq(schema.designFiles.filename, "index.html"));
+    }
+
+    const [file] = await db
+      .select({
+        id: schema.designFiles.id,
+        content: schema.designFiles.content,
+      })
+      .from(schema.designFiles)
+      .innerJoin(
+        schema.designs,
+        eq(schema.designFiles.designId, schema.designs.id),
+      )
+      .where(and(...fileConditions))
+      .limit(1);
+
+    if (!file) {
+      // The timeline row can still be deleted even if the file is gone.
+      await db
+        .delete(schema.motionTimeline)
+        .where(eq(schema.motionTimeline.id, timelineId));
+      return {
+        timelineId,
+        designId,
+        deleted: true,
+        htmlPatched: false,
+        reason: "File not found — timeline row deleted without HTML cleanup.",
+      };
+    }
+
+    // ── 3. Remove the managed CSS block from the HTML ───────────────────────
+    const currentContent = await liveFileContent(file.id, file.content ?? "");
+    const bytesBefore = currentContent.length;
+    const cleanedContent = removeMotionStyleBlock(currentContent);
+    const bytesAfter = cleanedContent.length;
+    const htmlChanged = cleanedContent !== currentContent;
+
+    // ── 4. Clean the HTML/style block FIRST, then delete the row LAST ───────
+    // Ordering matters: if the HTML cleanup persists but the row delete fails,
+    // re-running this action is idempotent (the block is already gone, the row
+    // is still deletable). The reverse order could leave an orphaned managed
+    // <style> block with no row to track it.
+    if (htmlChanged) {
+      agentEnterDocument(file.id);
+      try {
+        await db
+          .update(schema.designFiles)
+          .set({ content: cleanedContent, updatedAt: now })
+          .where(eq(schema.designFiles.id, file.id));
+
+        if (await hasCollabState(file.id)) {
+          await applyText(file.id, cleanedContent, "content", "agent");
+        } else {
+          await seedFromText(file.id, cleanedContent);
+        }
+
+        await db
+          .update(schema.designs)
+          .set({ updatedAt: now })
+          .where(eq(schema.designs.id, designId));
+      } finally {
+        agentLeaveDocument(file.id);
+      }
+    }
+
+    // ── 5. Delete the motion_timeline row LAST (so a failure leaves no
+    //        orphaned row pointing at HTML that was already cleaned). ────────
+    await db
+      .delete(schema.motionTimeline)
+      .where(eq(schema.motionTimeline.id, timelineId));
+
+    return {
+      timelineId,
+      designId,
+      fileId: file.id,
+      deleted: true,
+      htmlPatched: htmlChanged,
+      bytesBefore,
+      bytesAfter,
+      bytesDelta: bytesAfter - bytesBefore,
+    };
+  },
+});

package/corpus/templates/design/actions/run-design-audit.ts

@@ -0,0 +1,436 @@
+/**
+ * run-design-audit — read-only a11y audit over a design's rendered HTML/DOM.
+ *
+ * Checks contrast ratios, tap-target sizes, missing alt/labels, focus
+ * visibility, and reduced-motion concerns by static analysis of the stored
+ * HTML.  Does NOT perform writes.  Results are returned as `A11yFinding[]`
+ * and may be persisted by the caller via `create-design-review-snapshot`.
+ *
+ * See DESIGN-STUDIO-PLAN.md §6.5 + §7 (Review surface).
+ */
+
+import { defineAction } from "@agent-native/core";
+import { getText, hasCollabState } from "@agent-native/core/collab";
+import { accessFilter } from "@agent-native/core/sharing";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import "../server/db/index.js"; // ensure registerShareableResource runs
+import type {
+  A11yFinding,
+  A11yFindingCategory,
+  A11ySeverity,
+} from "../shared/design-review.js";
+
+// ---------------------------------------------------------------------------
+// HTML helpers (static analysis — no DOM runtime available server-side)
+// ---------------------------------------------------------------------------
+
+/** Extract all attribute values matching a simple regex over raw HTML. */
+function extractAttrs(
+  html: string,
+  tagPattern: RegExp,
+  attrName: string,
+): string[] {
+  const attrRegex = new RegExp(
+    `${attrName}\\s*=\\s*(?:"([^"]*?)"|'([^']*?)')`,
+    "gi",
+  );
+  const results: string[] = [];
+  let match: RegExpExecArray | null;
+  const tagMatches = [...html.matchAll(tagPattern)];
+  for (const tm of tagMatches) {
+    attrRegex.lastIndex = 0;
+    while ((match = attrRegex.exec(tm[0])) !== null) {
+      results.push(match[1] ?? match[2] ?? "");
+    }
+  }
+  return results;
+}
+
+/** Pull a node id from a raw tag string (data-agent-native-node-id attr). */
+function extractNodeId(tagHtml: string): string | undefined {
+  const m = tagHtml.match(
+    /data-agent-native-node-id\s*=\s*(?:"([^"]*?)"|'([^']*?)')/i,
+  );
+  return m ? (m[1] ?? m[2] ?? undefined) : undefined;
+}
+
+/** Pull a CSS selector hint from a raw tag string (id or class). */
+function extractSelector(tagHtml: string, tagName: string): string | undefined {
+  const idMatch = tagHtml.match(/\bid\s*=\s*(?:"([^"]*?)"|'([^']*?)')/i);
+  if (idMatch) return `#${idMatch[1] ?? idMatch[2]}`;
+  const classMatch = tagHtml.match(/\bclass\s*=\s*(?:"([^"]*?)"|'([^']*?)')/i);
+  if (classMatch) {
+    const first = (classMatch[1] ?? classMatch[2] ?? "").trim().split(/\s+/)[0];
+    if (first) return `${tagName.toLowerCase()}.${first}`;
+  }
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Individual audit checks
+// ---------------------------------------------------------------------------
+
+/** Check <img> tags without a meaningful alt attribute. */
+function checkMissingAlt(html: string): A11yFinding[] {
+  const findings: A11yFinding[] = [];
+  const imgPattern = /<img\b[^>]*>/gi;
+  let idx = 0;
+  for (const m of html.matchAll(imgPattern)) {
+    const tag = m[0];
+    // Missing alt entirely, or empty alt on a non-decorative image (heuristic)
+    const altMatch = tag.match(/\balt\s*=\s*(?:"([^"]*?)"|'([^']*?)')/i);
+    if (!altMatch) {
+      findings.push({
+        id: `missing-alt:img-${idx}`,
+        severity: "error" as A11ySeverity,
+        category: "missing-alt" as A11yFindingCategory,
+        message: "<img> is missing an alt attribute.",
+        detail:
+          'Add alt="" for decorative images or a descriptive alt for informative images.',
+        nodeId: extractNodeId(tag),
+        selector: extractSelector(tag, "img"),
+        wcag: "1.1.1",
+        fixAvailable: false,
+      });
+    }
+    idx++;
+  }
+  return findings;
+}
+
+/** Check form inputs without an associated <label> or aria-label/aria-labelledby. */
+function checkMissingLabels(html: string): A11yFinding[] {
+  const findings: A11yFinding[] = [];
+  const inputPattern = /<(?:input|select|textarea)\b[^>]*(?:\/>|>)/gi;
+  let idx = 0;
+  for (const m of html.matchAll(inputPattern)) {
+    const tag = m[0];
+    const typeMatch = tag.match(/\btype\s*=\s*(?:"([^"]*?)"|'([^']*?)')/i);
+    const type = (typeMatch?.[1] ?? typeMatch?.[2] ?? "text").toLowerCase();
+    // Hidden and submit/button/image inputs don't need visible labels
+    if (["hidden", "submit", "button", "image", "reset"].includes(type))
+      continue;
+
+    const hasAriaLabel =
+      /\baria-label\s*=/i.test(tag) ||
+      /\baria-labelledby\s*=/i.test(tag) ||
+      /\btitle\s*=/i.test(tag);
+    const idMatch = tag.match(/\bid\s*=\s*(?:"([^"]*?)"|'([^']*?)')/i);
+    const inputId = idMatch?.[1] ?? idMatch?.[2];
+    const hasExplicitLabel = inputId
+      ? new RegExp(`for\\s*=\\s*(?:"${inputId}"|'${inputId}')`, "i").test(html)
+      : false;
+
+    if (!hasAriaLabel && !hasExplicitLabel) {
+      findings.push({
+        id: `missing-label:input-${idx}`,
+        severity: "error" as A11ySeverity,
+        category: "missing-label" as A11yFindingCategory,
+        message: "Form control is missing an accessible label.",
+        detail:
+          "Associate a <label for> or add aria-label / aria-labelledby to identify this field.",
+        nodeId: extractNodeId(tag),
+        selector: extractSelector(tag, "input"),
+        wcag: "1.3.1",
+        fixAvailable: false,
+      });
+    }
+    idx++;
+  }
+  return findings;
+}
+
+/** Check interactive elements that are likely too small for touch targets (< ~44px heuristic via Tailwind class). */
+function checkTapTargets(html: string): A11yFinding[] {
+  const findings: A11yFinding[] = [];
+  // Heuristic: buttons/links with explicit tiny size classes (h-4, h-5, w-4, w-5, size-4, size-5)
+  // and no explicit larger override or sr-only are flagged.
+  const interactivePattern = /<(?:button|a)\b[^>]*>/gi;
+  const tinyPattern = /\b(?:h|w|size)-[345]\b/;
+  const largePattern = /\b(?:h|w|size)-(?:[6-9]|[1-9]\d)/;
+  const srOnlyPattern = /\bsr-only\b/;
+  let idx = 0;
+  for (const m of html.matchAll(interactivePattern)) {
+    const tag = m[0];
+    if (
+      tinyPattern.test(tag) &&
+      !largePattern.test(tag) &&
+      !srOnlyPattern.test(tag)
+    ) {
+      findings.push({
+        id: `tap-target:interactive-${idx}`,
+        severity: "warning" as A11ySeverity,
+        category: "tap-target" as A11yFindingCategory,
+        message: "Interactive element may be too small for a touch target.",
+        detail:
+          "Minimum recommended tap target size is 44×44 px (WCAG 2.5.5). Consider increasing padding or size.",
+        nodeId: extractNodeId(tag),
+        selector: extractSelector(tag, "button"),
+        wcag: "2.5.5",
+        fixAvailable: true,
+      });
+    }
+    idx++;
+  }
+  return findings;
+}
+
+/** Check for animations/transitions without a prefers-reduced-motion guard. */
+function checkReducedMotion(html: string): A11yFinding[] {
+  const findings: A11yFinding[] = [];
+  // Look for <style> blocks that animate but don't include @media (prefers-reduced-motion)
+  const stylePattern = /<style\b[^>]*>([\s\S]*?)<\/style>/gi;
+  let styleIdx = 0;
+  for (const m of html.matchAll(stylePattern)) {
+    const css = m[1] ?? "";
+    const hasAnimation =
+      /\banimation\b/i.test(css) || /\btransition\b/i.test(css);
+    const hasReducedMotionGuard = /prefers-reduced-motion/i.test(css);
+    if (hasAnimation && !hasReducedMotionGuard) {
+      findings.push({
+        id: `reduced-motion:style-${styleIdx}`,
+        severity: "warning" as A11ySeverity,
+        category: "reduced-motion" as A11yFindingCategory,
+        message:
+          "CSS animations or transitions are present without a prefers-reduced-motion media query.",
+        detail:
+          "Wrap animation declarations in @media (prefers-reduced-motion: no-preference) { … } to respect user motion preferences.",
+        wcag: "2.3.3",
+        fixAvailable: false,
+      });
+    }
+    styleIdx++;
+  }
+  // Also check inline style attrs with animation/transition
+  const inlineAnimPattern =
+    /style\s*=\s*(?:"[^"]*(?:animation|transition)[^"]*"|'[^']*(?:animation|transition)[^']*')/gi;
+  const allTags = [...html.matchAll(/<[a-z][^>]*>/gi)];
+  for (const m of allTags) {
+    if (inlineAnimPattern.test(m[0])) {
+      findings.push({
+        id: `reduced-motion:inline-${findings.length}`,
+        severity: "info" as A11ySeverity,
+        category: "reduced-motion" as A11yFindingCategory,
+        message:
+          "Inline style contains animation or transition. Verify it respects prefers-reduced-motion.",
+        nodeId: extractNodeId(m[0]),
+        selector: extractSelector(m[0], m[0].match(/^<([a-z]+)/i)?.[1] ?? "*"),
+        wcag: "2.3.3",
+        fixAvailable: false,
+      });
+    }
+    inlineAnimPattern.lastIndex = 0;
+  }
+  return findings;
+}
+
+/** Check for focus-visibility — elements with outline:none/outline:0 and no :focus-visible alternative. */
+function checkFocusVisibility(html: string): A11yFinding[] {
+  const findings: A11yFinding[] = [];
+  const stylePattern = /<style\b[^>]*>([\s\S]*?)<\/style>/gi;
+  let idx = 0;
+  for (const m of html.matchAll(stylePattern)) {
+    const css = m[1] ?? "";
+    const hasFocusOutlineRemoval =
+      /:focus\s*\{[^}]*outline\s*:\s*(?:none|0)/i.test(css) ||
+      /:focus-within\s*\{[^}]*outline\s*:\s*(?:none|0)/i.test(css);
+    const hasFocusVisibleReplacement = /:focus-visible/i.test(css);
+    if (hasFocusOutlineRemoval && !hasFocusVisibleReplacement) {
+      findings.push({
+        id: `focus-visibility:style-${idx}`,
+        severity: "warning" as A11ySeverity,
+        category: "focus-visibility" as A11yFindingCategory,
+        message:
+          "outline:none on :focus detected without a :focus-visible alternative.",
+        detail:
+          "Remove the outline only for pointer users via :focus:not(:focus-visible), and supply a visible style on :focus-visible.",
+        wcag: "2.4.7",
+        fixAvailable: false,
+      });
+    }
+    idx++;
+  }
+  // Tailwind outline-none/ring-0 on interactive elements (heuristic)
+  const outlineNonePattern =
+    /<(?:button|a|input|select|textarea)\b[^>]*\boutline-none\b[^>]*>/gi;
+  let inlineIdx = 0;
+  for (const m of html.matchAll(outlineNonePattern)) {
+    const tag = m[0];
+    // Check it's also not carrying a focus-visible ring class
+    if (!/\bfocus-visible:/i.test(tag)) {
+      findings.push({
+        id: `focus-visibility:inline-${inlineIdx}`,
+        severity: "info" as A11ySeverity,
+        category: "focus-visibility" as A11yFindingCategory,
+        message:
+          "Interactive element uses outline-none without a focus-visible ring.",
+        detail:
+          "Add a focus-visible:ring-* class so keyboard users can see which element is focused.",
+        nodeId: extractNodeId(tag),
+        selector: extractSelector(tag, tag.match(/^<([a-z]+)/i)?.[1] ?? "*"),
+        wcag: "2.4.7",
+        fixAvailable: true,
+      });
+    }
+    inlineIdx++;
+  }
+  return findings;
+}
+
+/** Check for inline style color declarations that are opaque but very low-contrast (rough heuristic). */
+function checkContrastHint(html: string): A11yFinding[] {
+  const findings: A11yFinding[] = [];
+  // Static analysis cannot compute real contrast ratios without a DOM/CSS
+  // cascade resolver. We flag the presence of explicit low-opacity text colors
+  // as a human-review hint — the UI will show these as "info" prompts.
+  const tagPattern = /<([a-z][a-z0-9:-]*)\b[^>]*>/gi;
+  const textColorPattern = /\btext-(?:white|black|gray-\d+)\b/i;
+  const lowOpacityPattern = /\b(?:opacity-[0-3]\d|text-opacity-[0-3]\d)\b/i;
+  let idx = 0;
+  for (const m of html.matchAll(tagPattern)) {
+    const tag = m[0];
+    const classMatch = tag.match(/\bclass\s*=\s*(?:"([^"]*?)"|'([^']*?)')/i);
+    const className = classMatch?.[1] ?? classMatch?.[2] ?? "";
+    if (
+      !textColorPattern.test(className) ||
+      !lowOpacityPattern.test(className)
+    ) {
+      continue;
+    }
+    const tagName = m[1] ?? "*";
+    const nodeId = extractNodeId(tag);
+    const selector = extractSelector(tag, tagName);
+    findings.push({
+      id: `contrast:low-opacity-${idx}`,
+      severity: "info" as A11ySeverity,
+      category: "contrast" as A11yFindingCategory,
+      message:
+        "Text element has a low-opacity modifier — verify contrast ratio meets 4.5:1 minimum.",
+      detail:
+        "Low-opacity text can fail WCAG 1.4.3. Run a live contrast check in the browser.",
+      nodeId,
+      selector,
+      wcag: "1.4.3",
+      fixAvailable: false,
+    });
+    idx++;
+  }
+  return findings;
+}
+
+// ---------------------------------------------------------------------------
+// Live-content helper (matches the pattern in other actions)
+// ---------------------------------------------------------------------------
+
+async function liveContent(
+  fileId: string,
+  storedContent: string,
+): Promise<string> {
+  try {
+    if (await hasCollabState(fileId)) {
+      const live = await getText(fileId, "content");
+      if (typeof live === "string") return live;
+    }
+  } catch {
+    // SQL content is the deterministic fallback.
+  }
+  return storedContent;
+}
+
+// ---------------------------------------------------------------------------
+// Action definition
+// ---------------------------------------------------------------------------
+
+export default defineAction({
+  description:
+    "Run a read-only accessibility audit over a design's rendered HTML. " +
+    "Checks contrast hints, tap-target sizes, missing alt attributes, missing " +
+    "form labels, focus-visibility gaps, and reduced-motion coverage. " +
+    "Returns A11yFinding[] that can be shown in the Review panel or persisted " +
+    "via create-design-review-snapshot. No writes are performed.",
+  schema: z.object({
+    designId: z.string().describe("Design project ID to audit"),
+    fileId: z
+      .string()
+      .optional()
+      .describe(
+        "Specific design_files.id to audit. Defaults to the primary index.html when omitted.",
+      ),
+    filename: z
+      .string()
+      .optional()
+      .default("index.html")
+      .describe(
+        "Filename to audit when fileId is not provided. Defaults to index.html.",
+      ),
+  }),
+  readOnly: true,
+  http: { method: "POST" },
+  run: async ({ designId, fileId, filename }) => {
+    const db = getDb();
+
+    const conditions = [
+      accessFilter(schema.designs, schema.designShares),
+      eq(schema.designFiles.designId, designId),
+      ...(fileId
+        ? [eq(schema.designFiles.id, fileId)]
+        : [eq(schema.designFiles.filename, filename ?? "index.html")]),
+    ];
+
+    const [file] = await db
+      .select({
+        id: schema.designFiles.id,
+        designId: schema.designFiles.designId,
+        filename: schema.designFiles.filename,
+        fileType: schema.designFiles.fileType,
+        content: schema.designFiles.content,
+      })
+      .from(schema.designFiles)
+      .innerJoin(
+        schema.designs,
+        eq(schema.designFiles.designId, schema.designs.id),
+      )
+      .where(and(...conditions))
+      .limit(1);
+
+    if (!file) {
+      const err = new Error("Design file not found") as Error & {
+        statusCode: number;
+      };
+      err.statusCode = 404;
+      throw err;
+    }
+
+    const html = await liveContent(file.id, file.content ?? "");
+
+    // Run all audit checks over the static HTML.
+    const findings: A11yFinding[] = [
+      ...checkMissingAlt(html),
+      ...checkMissingLabels(html),
+      ...checkTapTargets(html),
+      ...checkReducedMotion(html),
+      ...checkFocusVisibility(html),
+      ...checkContrastHint(html),
+    ];
+
+    // Summarise by severity for the agent context.
+    const summary = {
+      errors: findings.filter((f) => f.severity === "error").length,
+      warnings: findings.filter((f) => f.severity === "warning").length,
+      info: findings.filter((f) => f.severity === "info").length,
+      total: findings.length,
+    };
+
+    return {
+      designId,
+      fileId: file.id,
+      filename: file.filename,
+      auditedAt: new Date().toISOString(),
+      findings,
+      summary,
+    };
+  },
+});