@agent-native/core 0.92.9 → 0.92.11

package/corpus/templates/design/shared/code-layer.ts

@@ -1007,7 +1007,11 @@ function getAttribute(
 
 function attributeValue(element: ParsedElement, name: string): string | null {
   const value = getAttribute(element, name)?.value;
-  if (typeof value === "string") return value;
+  // Parsed attributes contain source text, so quoted values may still carry
+  // entities emitted by an earlier deterministic patch. Decode before using
+  // them semantically or reserializing; otherwise sequential style edits turn
+  // `"` into `"` on every pass and corrupt quoted CSS url() values.
+  if (typeof value === "string") return decodeBasicHtmlEntities(value);
   if (value === true) return "";
   return null;
 }
@@ -3143,6 +3147,7 @@ function applyMoveNodeEdit(
   element: ParsedElement,
   anchor: ParsedElement,
   intent: MoveNodeEditIntent,
+  destinationParent?: ParsedElement,
 ): { content: string; capability: EditCapability } | PatchResultStatus {
   if (element.index === anchor.index) return "conflict";
   if (anchor.start >= element.start && anchor.end <= element.end) {
@@ -3152,7 +3157,14 @@ function applyMoveNodeEdit(
     return "unsupported";
   }
 
-  const fragment = html.slice(element.start, element.end);
+  const sourceParentIndex = element.parentIndex;
+  const entersNewParent =
+    destinationParent !== undefined &&
+    sourceParentIndex !== destinationParent.index;
+  const rawFragment = html.slice(element.start, element.end);
+  const fragment = entersNewParent
+    ? prepareMovedFragmentForParent(rawFragment, destinationParent)
+    : rawFragment;
   const withoutTarget = `${html.slice(0, element.start)}${html.slice(
     element.end,
   )}`;
@@ -3178,6 +3190,51 @@ function applyMoveNodeEdit(
   };
 }
 
+/**
+ * Whether children of this element participate in normal flex/grid flow.
+ * Inline style is authoritative for inspector-created auto layout; the class
+ * checks cover authored Tailwind/utility layouts in standalone Alpine files.
+ */
+function isFlowLayoutContainer(element: ParsedElement | undefined): boolean {
+  if (!element) return false;
+  const display = parseStyle(attributeValue(element, "style")).display;
+  if (
+    display === "flex" ||
+    display === "inline-flex" ||
+    display === "grid" ||
+    display === "inline-grid"
+  ) {
+    return true;
+  }
+  const classes = new Set(classList(element));
+  return (
+    classes.has("flex") ||
+    classes.has("inline-flex") ||
+    classes.has("grid") ||
+    classes.has("inline-grid")
+  );
+}
+
+/**
+ * A Figma auto-layout drop makes the moved layer a flow child. Carrying its
+ * former `position:absolute` offsets into the new flex/grid parent leaves it
+ * visually detached from ordering, gap, and alignment even though the layer
+ * tree says it was reparented. Normalize only the moved fragment's root; its
+ * descendants keep their own positioning contexts unchanged.
+ */
+function prepareMovedFragmentForParent(
+  fragment: string,
+  destinationParent: ParsedElement | undefined,
+): string {
+  if (!isFlowLayoutContainer(destinationParent)) return fragment;
+  const fragmentRoot = parseHtmlElements(fragment).find(
+    (element) => element.parentIndex === undefined,
+  );
+  return fragmentRoot
+    ? stripAbsolutePositioningFromChild(fragment, fragmentRoot)
+    : fragment;
+}
+
 /** Generate a fresh unique data-agent-native-node-id value not already in the set. */
 function freshNodeId(usedIds: Set<string>, basis: string): string {
   const base = `an-${hashStable(basis)}`;
@@ -3264,11 +3321,42 @@ function stripAbsolutePositioningFromChild(
   child: ParsedElement,
 ): string {
   const currentStyle = attributeValue(child, "style");
-  if (!currentStyle) return html;
-  const nextStyle = stripStyleProperties(currentStyle, [
-    ...AUTO_LAYOUT_STRIP_PROPS,
-  ]);
-  return replaceOrInsertAttribute(html, child, "style", nextStyle);
+  let nextHtml = currentStyle
+    ? replaceOrInsertAttribute(
+        html,
+        child,
+        "style",
+        stripStyleProperties(currentStyle, [...AUTO_LAYOUT_STRIP_PROPS]),
+      )
+    : html;
+
+  // Source-backed Alpine/Tailwind designs commonly express positioning as
+  // utility classes instead of inline CSS. Once the layer moves into a new
+  // flex/grid parent, those utilities would keep it out of flow even though
+  // the Layers tree shows it as a child. Remove only position-mode utilities;
+  // inset utilities can remain because they are inert for a statically
+  // positioned flex/grid item, and preserving them avoids needless source
+  // churn if the user later makes the layer absolute again.
+  const reparsedRoot = parseHtmlElements(nextHtml).find(
+    (element) => element.parentIndex === undefined,
+  );
+  if (!reparsedRoot) return nextHtml;
+  const classes = classList(reparsedRoot);
+  const flowClasses = classes.filter((token) => {
+    const variants = token.split(":");
+    const utility = variants[variants.length - 1]?.replace(/^!/, "");
+    return (
+      utility !== "absolute" && utility !== "fixed" && utility !== "sticky"
+    );
+  });
+  if (flowClasses.length === classes.length) return nextHtml;
+  nextHtml = replaceOrInsertAttribute(
+    nextHtml,
+    reparsedRoot,
+    "class",
+    flowClasses.join(" "),
+  );
+  return nextHtml;
 }
 
 /**
@@ -4018,7 +4106,19 @@ export function applyVisualEdit(
     const removedLength = element.end - element.start;
     moveInsertAt =
       element.start < rawInsertAt ? rawInsertAt - removedLength : rawInsertAt;
-    edit = applyMoveNodeEdit(html, element, anchorElement, intent);
+    const destinationParent =
+      intent.placement === "inside"
+        ? anchorElement
+        : anchorResolution.node.parentId
+          ? initial.elementByNodeId.get(anchorResolution.node.parentId)
+          : undefined;
+    edit = applyMoveNodeEdit(
+      html,
+      element,
+      anchorElement,
+      intent,
+      destinationParent,
+    );
   }
 
   if (typeof edit === "string") {
@@ -4265,6 +4365,13 @@ export function moveNodeBetweenDocuments(
         : destHtml.length;
       anchorRedirected = true;
     }
+    const destinationParent =
+      placement === "inside"
+        ? anchor
+        : anchor.parentIndex === undefined
+          ? undefined
+          : destElements[anchor.parentIndex];
+    fragment = prepareMovedFragmentForParent(fragment, destinationParent);
     nextDestHtml = `${destHtml.slice(0, insertAt)}${fragment}${destHtml.slice(insertAt)}`;
   } else {
     // Default: find <body> and append inside it, or append at end of doc.
@@ -4281,6 +4388,13 @@ export function moveNodeBetweenDocuments(
     if (isOffsetInsideTemplateInterior(destHtml, insertAt)) {
       insertAt = destHtml.length;
     }
+    // Appending inside <body> makes the moved node a flow child of the body,
+    // exactly like the anchored `placement: "inside"` branch above. When the
+    // destination body is a flex/grid container, carrying the fragment's
+    // former absolute offsets along would leave it visually detached from
+    // the body's ordering/gap/alignment, so run the same normalization
+    // (prepareMovedFragmentForParent no-ops for non-flow bodies).
+    fragment = prepareMovedFragmentForParent(fragment, bodyEl);
     nextDestHtml = `${destHtml.slice(0, insertAt)}${fragment}${destHtml.slice(insertAt)}`;
   }
 

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

@@ -0,0 +1,161 @@
+/**
+ * Component library scan — cross-file component instance discovery.
+ *
+ * `index-components` (and `get-component-details`) only ever look at ONE
+ * design file at a time (the active file, or an explicit `fileId`).
+ * `component_index` metadata is therefore scoped to whichever file was last
+ * indexed, and its `runtimeSelectors` do not reliably span every screen in a
+ * multi-file design.
+ *
+ * "Go to main component" and "Swap instance" both need to find OTHER
+ * instances of a component name that may live on a different screen (design
+ * file) than the one currently open. This module scans a caller-supplied set
+ * of already-fetched design files (any order the caller wants — typically
+ * `createdAt` ascending, oldest/"most original" first) and returns every
+ * component instance found across all of them, in that same order.
+ *
+ * Pure — no DB / IO. Callers fetch file rows (respecting `accessFilter`) and
+ * pass the rows in here.
+ */
+
+import {
+  buildCodeLayerProjection,
+  type CodeLayerSource,
+} from "./code-layer.js";
+import { componentNameFor, isComponentInstance } from "./component-model.js";
+
+export interface ComponentLibraryFile {
+  id: string;
+  designId: string;
+  filename: string;
+  content: string | null;
+}
+
+export interface ComponentLibraryEntry {
+  /** Component name from `data-agent-native-component`. */
+  name: string;
+  fileId: string;
+  filename: string;
+  /** `data-agent-native-node-id` (or fallback) of the instance root. */
+  nodeId: string;
+  /** CSS selector that addresses this instance on its screen. */
+  selector: string;
+}
+
+/**
+ * Scan every file for component instances, preserving the caller's file
+ * order and each file's document order. Files with empty/missing content are
+ * skipped rather than throwing.
+ */
+export function scanComponentLibrary(
+  files: ComponentLibraryFile[],
+): ComponentLibraryEntry[] {
+  const entries: ComponentLibraryEntry[] = [];
+
+  for (const file of files) {
+    const html = file.content ?? "";
+    if (!html) continue;
+
+    const codeLayerSource: CodeLayerSource = {
+      kind: "design-file",
+      designId: file.designId,
+      fileId: file.id,
+      filename: file.filename,
+    };
+
+    const projection = buildCodeLayerProjection(html, {
+      source: codeLayerSource,
+    });
+
+    for (const node of projection.nodes) {
+      if (!isComponentInstance(node)) continue;
+      const name = componentNameFor(node);
+      if (!name) continue;
+
+      // `node.id` is an ephemeral id scoped to this one projection call — it
+      // is NOT the same as the durable `data-agent-native-node-id` attribute
+      // stamped into the HTML (see `ensureCodeLayerNodeIdsInHtml`). Callers
+      // that navigate to / re-select this entry on a LATER read (a different
+      // projection call — e.g. after a `navigate` round-trip) need the stable
+      // attribute value, not this run's ephemeral id, so prefer it here and
+      // only fall back to `node.id` for the rare case a component-annotated
+      // node hasn't been stamped with a durable id yet.
+      const nodeId =
+        node.dataAttributes["data-agent-native-node-id"] ?? node.id;
+
+      entries.push({
+        name,
+        fileId: file.id,
+        filename: file.filename,
+        nodeId,
+        selector: node.selector,
+      });
+    }
+  }
+
+  return entries;
+}
+
+/**
+ * Filter a scanned library to instances of one component name, optionally
+ * excluding a specific (fileId, nodeId) — typically the instance the caller
+ * is acting on, so it doesn't get offered back as its own "main"/swap
+ * source.
+ */
+export function entriesForComponent(
+  entries: ComponentLibraryEntry[],
+  name: string,
+  exclude?: { fileId: string; nodeId: string },
+): ComponentLibraryEntry[] {
+  return entries.filter((entry) => {
+    if (entry.name !== name) return false;
+    if (
+      exclude &&
+      entry.fileId === exclude.fileId &&
+      entry.nodeId === exclude.nodeId
+    ) {
+      return false;
+    }
+    return true;
+  });
+}
+
+/**
+ * Aggregate scanned entries into one row per distinct component name — the
+ * shape the Swap Instance picker needs (a name to pick, a count, and a
+ * representative instance to source markup/props from).
+ */
+export interface ComponentLibrarySummary {
+  name: string;
+  instanceCount: number;
+  sampleFileId: string;
+  sampleFilename: string;
+  sampleNodeId: string;
+  sampleSelector: string;
+}
+
+export function summarizeComponentLibrary(
+  entries: ComponentLibraryEntry[],
+): ComponentLibrarySummary[] {
+  const byName = new Map<string, ComponentLibrarySummary>();
+
+  for (const entry of entries) {
+    const existing = byName.get(entry.name);
+    if (existing) {
+      existing.instanceCount += 1;
+      continue;
+    }
+    byName.set(entry.name, {
+      name: entry.name,
+      instanceCount: 1,
+      sampleFileId: entry.fileId,
+      sampleFilename: entry.filename,
+      sampleNodeId: entry.nodeId,
+      sampleSelector: entry.selector,
+    });
+  }
+
+  return Array.from(byName.values()).sort((a, b) =>
+    a.name.localeCompare(b.name),
+  );
+}

package/corpus/templates/design/shared/db-conflict.ts

@@ -0,0 +1,27 @@
+/**
+ * True when `err` is a UNIQUE / PRIMARY KEY constraint violation from either
+ * supported driver (Postgres 23505, SQLite SQLITE_CONSTRAINT_UNIQUE /
+ * _PRIMARYKEY). Shared by any action that inserts a row guarded by a
+ * best-effort unique index and needs to recover from a losing race instead of
+ * failing outright — see `design_files_design_filename_unique_idx` in
+ * `server/plugins/db.ts` for the index this is meant to catch a conflict
+ * against, and `add-localhost-screens.ts` / `present-design-variants.ts` for
+ * the adopt-the-winning-row recovery pattern built on top of this check.
+ */
+export function isUniqueConstraintViolation(err: unknown): boolean {
+  const e = err as { code?: unknown; message?: unknown } | null;
+  if (e?.code === "23505") return true;
+  const code = String(e?.code ?? "");
+  if (
+    code === "SQLITE_CONSTRAINT_PRIMARYKEY" ||
+    code === "SQLITE_CONSTRAINT_UNIQUE"
+  ) {
+    return true;
+  }
+  const msg = String(e?.message ?? "").toLowerCase();
+  return (
+    msg.includes("unique constraint") ||
+    msg.includes("primary key constraint") ||
+    msg.includes("duplicate key")
+  );
+}

package/corpus/templates/design/shared/design-source-capabilities.ts

@@ -7,7 +7,8 @@
  *
  * Relation to `source-mode.ts`:
  * - `DesignBridgeOperation` ("select" | "resolveNodeToFile" | "readFile" |
- *   "applyEdit" | "writeFile" | "captureSnapshot" | "captureState") describes
+ *   "applyEdit" | "writeFile" | "captureSnapshot" | "captureState" |
+ *   "listFiles") describes
  *   the low-level bridge RPC surface.
  * - `DesignCapabilityName` below is the *higher-level* capability vocabulary
  *   that UI panels and agent actions read.  Several capabilities build on one

package/corpus/templates/design/shared/figma-url.ts

@@ -0,0 +1,149 @@
+/**
+ * Shared Figma URL / node-id parsing helpers.
+ *
+ * Figma file URLs come in a few shapes:
+ *   https://www.figma.com/design/<fileKey>/<name>
+ *   https://www.figma.com/file/<fileKey>/<name>            (legacy)
+ *   https://www.figma.com/proto/<fileKey>/<name>            (prototype share link)
+ *   https://www.figma.com/design/<fileKey>/<name>/branch/<branchKey>/<name>
+ *
+ * The branch shape is the important gotcha: a branch is a *separate* file for
+ * REST API purposes. `/v1/files/:fileKey` etc. must be called with the
+ * **branch key**, not the parent file key that appears earlier in the path —
+ * calling with the parent key silently returns the parent file's content,
+ * not the branch the user is actually looking at. See
+ * https://developers.figma.com/docs/rest-api/ (branches share the same file
+ * shape as regular files once you have the branch's own key).
+ *
+ * `node-id` is carried as a query param and Figma writes it with dashes
+ * (`1-2`) even though the REST API's node ids use colons (`1:2`). Grouped /
+ * instance-swap node ids can look like `1:2;3:4` — only the plain
+ * `<number>-<number>` shape needs dash-to-colon conversion; anything already
+ * containing a colon is passed through untouched.
+ */
+
+const FIGMA_FILE_KEY_RE = /^[A-Za-z0-9_-]{8,}$/;
+const FILE_PATH_SEGMENTS = ["design", "file", "proto"] as const;
+
+export interface ParsedFigmaUrl {
+  /** Effective file key to use for REST API calls (branch key when present). */
+  fileKey: string | null;
+  /** Node id in REST API colon form (e.g. "1:2"), or null when absent. */
+  nodeId: string | null;
+  /** True when the URL pointed at a branch and fileKey is that branch's key. */
+  isBranch: boolean;
+}
+
+function candidateFileKey(value: string): string | null {
+  return FIGMA_FILE_KEY_RE.test(value) ? value : null;
+}
+
+/**
+ * Extract the effective Figma file key from a raw file key or a Figma URL.
+ * Resolves `/branch/:branchKey/` to the branch key when present, since a
+ * branch is a distinct file from the REST API's point of view.
+ */
+export function parseFigmaFileKey(input: string | undefined): string | null {
+  const value = input?.trim();
+  if (!value) return null;
+
+  const direct = candidateFileKey(value);
+  if (direct) return direct;
+
+  try {
+    const url = new URL(value);
+    const parts = url.pathname.split("/").filter(Boolean);
+
+    const branchIndex = parts.indexOf("branch");
+    if (branchIndex >= 0) {
+      const branchKey = candidateFileKey(parts[branchIndex + 1] ?? "");
+      if (branchKey) return branchKey;
+    }
+
+    for (const segment of FILE_PATH_SEGMENTS) {
+      const index = parts.indexOf(segment);
+      if (index >= 0) {
+        const key = candidateFileKey(parts[index + 1] ?? "");
+        if (key) return key;
+      }
+    }
+  } catch {
+    return null;
+  }
+
+  return null;
+}
+
+/** True when the given file URL points at a branch (not the main file). */
+export function isFigmaBranchUrl(input: string | undefined): boolean {
+  const value = input?.trim();
+  if (!value) return false;
+  try {
+    const url = new URL(value);
+    return url.pathname.split("/").filter(Boolean).includes("branch");
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Normalize a raw node-id-ish string to the REST API's colon form. Accepts:
+ *   "1:2"          -> "1:2"        (already normalized)
+ *   "1-2"          -> "1:2"        (dash form, as seen in `node-id` query params)
+ *   "1-2;3-4"      -> "1:2;3:4"    (instance-swap grouped ids)
+ *   "I1:2;3:4"     -> "I1:2;3:4"   (already normalized, leading instance marker)
+ */
+function normalizeNodeIdToken(token: string): string | null {
+  const trimmed = token.trim();
+  if (!trimmed) return null;
+  // Already colon form (optionally prefixed with "I" for instance overrides).
+  if (/^I?\d+:\d+$/.test(trimmed)) return trimmed;
+  // Dash form -> colon form.
+  if (/^I?\d+-\d+$/.test(trimmed)) return trimmed.replace("-", ":");
+  return null;
+}
+
+function normalizeNodeId(raw: string): string | null {
+  const decoded = (() => {
+    try {
+      return decodeURIComponent(raw);
+    } catch {
+      return raw;
+    }
+  })();
+  const parts = decoded
+    .split(";")
+    .map((part) => normalizeNodeIdToken(part))
+    .filter((part): part is string => part !== null);
+  return parts.length > 0 ? parts.join(";") : null;
+}
+
+/**
+ * Extract a Figma node id from a `node-id` query param or a raw id string,
+ * converting Figma's URL dash form (`1-2`) to the REST API's colon form
+ * (`1:2`).
+ */
+export function parseFigmaNodeId(input: string | undefined): string | null {
+  const value = input?.trim();
+  if (!value) return null;
+
+  const direct = normalizeNodeId(value);
+  if (direct) return direct;
+
+  try {
+    const url = new URL(value);
+    const nodeParam = url.searchParams.get("node-id");
+    if (nodeParam) return normalizeNodeId(nodeParam);
+  } catch {
+    return null;
+  }
+
+  return null;
+}
+
+/** Parse a Figma URL (or bare file key) into its effective file key and node id. */
+export function parseFigmaUrl(input: string | undefined): ParsedFigmaUrl {
+  const fileKey = parseFigmaFileKey(input);
+  const nodeId = parseFigmaNodeId(input);
+  return { fileKey, nodeId, isBranch: isFigmaBranchUrl(input) };
+}

package/corpus/templates/design/shared/pen-path.ts

@@ -115,13 +115,22 @@ export function snapPenAnchorPoint(
   path: PenPath | null,
   options: { hitRadius: number; zoom: number },
 ): PenPoint {
-  const existingAnchor = path?.nodes.find(
-    (node) =>
-      Math.hypot(node.point.x - point.x, node.point.y - point.y) <=
-      options.hitRadius,
-  );
-  if (existingAnchor) {
-    return { ...existingAnchor.point };
+  // Nearest anchor within radius wins (matching hitTestPenAnchor), not the
+  // first one found in node order — two anchors can easily both sit within
+  // the hit radius (e.g. a tightly drawn shape), and a "first match" scan
+  // would snap to whichever happens to have the lower node index rather than
+  // the one actually closest to the cursor.
+  let nearestAnchor: PenPoint | null = null;
+  let nearestDistance = Infinity;
+  for (const node of path?.nodes ?? []) {
+    const distance = Math.hypot(node.point.x - point.x, node.point.y - point.y);
+    if (distance <= options.hitRadius && distance < nearestDistance) {
+      nearestDistance = distance;
+      nearestAnchor = node.point;
+    }
+  }
+  if (nearestAnchor) {
+    return { ...nearestAnchor };
   }
 
   if (options.zoom >= 100) {

package/corpus/templates/design/shared/source-mode.ts

@@ -97,6 +97,7 @@ export const DESIGN_BRIDGE_OPERATIONS = [
   "writeFile",
   "captureSnapshot",
   "captureState",
+  "listFiles",
 ] as const;
 
 export type DesignBridgeOperation = (typeof DESIGN_BRIDGE_OPERATIONS)[number];

package/corpus/templates/plan/app/components/plan/CanvasArea.tsx

@@ -41,8 +41,6 @@ const useIsomorphicLayoutEffect =
 const DEFAULT_VIEW = { zoom: 0.72, pan: { x: 96, y: 64 } };
 const MIN_ZOOM = 0.18;
 const MAX_ZOOM = 2.4;
-/** Notched mouse-wheel fixed-ratio step (design-canvas.jsx feel). */
-const WHEEL_ZOOM_STEP = 0.16;
 /** Trackpad pinch sensitivity. */
 const PINCH_ZOOM_SENSITIVITY = 0.01;
 /** Base CSS grid cell, scaled by zoom. */
@@ -534,9 +532,11 @@ export function CanvasArea({
     [buildMarkupContext, onCanvasMarkupCreate, pendingMarkup],
   );
 
-  // Wheel: cursor-over-canvas never scrolls the page. Notched wheel zooms with
-  // a fixed ratio per click; ctrl/cmd/alt (or trackpad pinch) zoom at the
-  // cursor; everything else pans.
+  // Wheel: cursor-over-canvas never scrolls the page. Match Figma's input
+  // contract: unmodified wheel/trackpad gestures always pan, while an explicit
+  // ctrl/cmd modifier (including the ctrlKey emitted by trackpad pinch) zooms
+  // at the cursor. Never infer zoom intent from the delta shape — trackpad pan
+  // momentum can look exactly like a notched mouse wheel near a canvas edge.
   useEffect(() => {
     const element = viewportRef.current;
     if (!element) return;
@@ -559,24 +559,12 @@ export function CanvasArea({
       const deltaX = event.deltaX * lineScale;
       const deltaY = event.deltaY * lineScale;
 
-      // Notched mouse wheel: line-mode, or large integer pixel deltas with no
-      // horizontal component (Chrome/Safari). Fixed-ratio step per click.
-      const isNotchedWheel =
-        event.deltaMode !== 0 ||
-        (event.deltaX === 0 &&
-          Number.isInteger(event.deltaY) &&
-          Math.abs(event.deltaY) >= 40);
-
-      if (event.ctrlKey || event.metaKey || event.altKey) {
+      if (event.ctrlKey || event.metaKey) {
         // Trackpad pinch / explicit zoom modifier — smooth exponential.
         zoomByFactor(Math.exp(-deltaY * PINCH_ZOOM_SENSITIVITY), anchor);
         return;
       }
-      if (isNotchedWheel) {
-        zoomByFactor(Math.exp(-Math.sign(deltaY) * WHEEL_ZOOM_STEP), anchor);
-        return;
-      }
-      // Trackpad two-finger scroll → pan.
+      // Mouse wheel / trackpad two-finger scroll -> pan.
       updateView((current) => ({
         ...current,
         pan: {

package/corpus/templates/plan/changelog/2026-07-09-canvas-panning-now-keeps-zoom-fixed-even-at-the-edges.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-09
+---
+
+Canvas panning now keeps zoom fixed, even at the edges.

package/corpus/templates/slides/actions/index-design-system-with-builder.ts

@@ -13,8 +13,23 @@ import { upsertBuilderProxyDesignSystem } from "../server/lib/builder-design-sys
 
 const codeFileSchema = z.object({
   filename: z.string().trim().min(1).describe("File name or relative path"),
-  content: z.string().describe("Raw text content of the code/design file"),
+  content: z
+    .string()
+    .describe(
+      "File content. Text files (code, CSS, markdown, JSON, SVG): raw text. " +
+        "Binary files -- most importantly `.fig` (a zip/kiwi binary container, " +
+        'never valid text) -- MUST be base64-encoded with encoding: "base64"; ' +
+        "sending raw/binary-as-string content with the default utf8 encoding " +
+        "corrupts the file before it reaches Builder.",
+    ),
   mimeType: z.string().trim().optional().describe("Optional MIME type"),
+  encoding: z
+    .enum(["utf8", "base64"])
+    .optional()
+    .describe(
+      "Encoding of `content`. Defaults to utf8. Set to base64 for `.fig` and " +
+        "other binary files.",
+    ),
 });
 
 export default defineAction({