@agent-native/core-corpus 0.214.0 → 0.216.0

package/corpus/templates/content/shared/suggestion-diff.ts

@@ -973,6 +973,19 @@ export function markdownSuggestionOperationsForFindReplaceEdits(input: {
   );
 }
 
+/**
+ * The summary suggest-document-edit records when the agent gives none. The
+ * comments sidebar compares against it so it never shows this as a reason.
+ */
+export function findReplaceSuggestionSummary(
+  find: string,
+  replace: string,
+): string {
+  return replace
+    ? `Replace "${find.slice(0, 80)}" with "${replace.slice(0, 80)}"`
+    : `Delete "${find.slice(0, 80)}"`;
+}
+
 /** A one-line review label for a single operation's change. */
 export function markdownSuggestionOperationSummary(
   operation: MarkdownSuggestionOperation,

package/corpus/templates/content/shared/suggestion-formatting.ts

@@ -1,7 +1,10 @@
 import {
   canonicalizeNfm,
   docToNfm,
+  longestRun,
+  nfmContextualSpellings,
   nfmToDoc,
+  pushAll,
   serializeInlineTextNodeWithOffsets,
   type PMNode,
 } from "./nfm";
@@ -12,6 +15,8 @@ type TextRun = {
   markValues: PMNode["marks"];
   serialized: string;
   textOffsets: number[];
+  /** L7 bridge: offsets past a reopened delimiter, each a text boundary. */
+  reopened?: Map<number, number>;
   from: number;
   to: number;
   sourceFrom: number;
@@ -19,6 +24,10 @@ type TextRun = {
   nonTextBefore: boolean;
   verbatim?: boolean;
   emptyCell?: boolean;
+  /** The writer puts a `\` before this run, which belongs to the syntax gap. */
+  escapedBlockMarker?: boolean;
+  /** Its placeholder starts with a digit, as the run's bytes do. */
+  digitLead?: boolean;
 };
 type TextRange = { from: number; to: number };
 
@@ -55,20 +64,41 @@ function withoutMarks(node: PMNode): PMNode {
 }
 
 function longestBacktickRun(text: string): number {
-  return Math.max(0, ...(text.match(/`+/g) ?? []).map((run) => run.length));
+  return longestRun(text, /`+/g);
 }
 
-function formattingRuns(
-  source: string,
-  anchorEmptyCells = false,
-): {
+type FormattingRuns = {
   runs: TextRun[];
   nonTextAfter: boolean;
   restored: string;
   spans: Array<Record<SourceSide, SourceSpan>>;
   emptyCells: Array<{ sourceOffset: number; textOffset: number }>;
-} | null {
+};
+
+// Every suggestion on a Page maps its range through the same Page source, so
+// recent results are kept rather than reparsing the Page per suggestion.
+const recentFormattingRuns = new Map<string, FormattingRuns | null>();
+
+function formattingRuns(
+  source: string,
+  anchorEmptyCells = false,
+): FormattingRuns | null {
+  const key = `${anchorEmptyCells ? 1 : 0}${source}`;
+  if (recentFormattingRuns.has(key))
+    return recentFormattingRuns.get(key) as FormattingRuns | null;
+  const mapped = computeFormattingRuns(source, anchorEmptyCells);
+  if (recentFormattingRuns.size >= 8)
+    recentFormattingRuns.delete(recentFormattingRuns.keys().next().value!);
+  recentFormattingRuns.set(key, mapped);
+  return mapped;
+}
+
+function computeFormattingRuns(
+  source: string,
+  anchorEmptyCells: boolean,
+): FormattingRuns | null {
   const doc = nfmToDoc(source);
+  const spellings = nfmContextualSpellings(doc);
   let markerPrefix = "suggestiontextboundary";
   while (source.includes(markerPrefix)) markerPrefix += "z";
   const runs: TextRun[] = [];
@@ -140,15 +170,20 @@ function formattingRuns(
     }
     if (node.type === "text" && node.text) {
       const index = runs.length;
-      const marker = `${markerPrefix}${index}x`;
       const serialized = serializeInlineTextNodeWithOffsets(
         node,
+        spellings.escapedUnderscores.has(node),
+        spellings.escapedTrailingBang.has(node),
         position === 0,
       );
       if (!serialized) {
         nonTextPending = true;
         return node;
       }
+      // Inline math before a digit is written in another form, so the
+      // placeholder after it must start with a digit too.
+      const digitLead = /^\d/.test(serialized.source);
+      const marker = `${digitLead ? "0" : ""}${markerPrefix}${index}x`;
       runs.push({
         text: node.text,
         marks: JSON.stringify(node.marks ?? []),
@@ -160,6 +195,8 @@ function formattingRuns(
         sourceFrom: -1,
         sourceTo: -1,
         nonTextBefore: nonTextPending,
+        escapedBlockMarker: spellings.escapedBlockMarker.has(node),
+        digitLead,
       });
       nonTextPending = false;
       offset += node.text.length;
@@ -183,17 +220,19 @@ function formattingRuns(
   let delta = 0;
   const markers: string[] = [];
   const restored = withPlaceholders.replace(
-    new RegExp(`${markerPrefix}(\\d+)\`*x`, "g"),
-    (token, rawIndex: string, position: number) => {
+    new RegExp(`(0?)${markerPrefix}(\\d+)\`*x`, "g"),
+    (token, lead: string, rawIndex: string, position: number) => {
       const index = Number(rawIndex);
       const run = runs[index]!;
       markers[index] = token;
+      if (Boolean(lead) !== Boolean(run.digitLead)) unmappable = true;
       if (run.verbatim && !resolveVerbatimRun(run, withPlaceholders, position))
         unmappable = true;
-      run.sourceFrom = position + delta;
+      const escape = run.escapedBlockMarker ? "\\" : "";
+      run.sourceFrom = position + delta + escape.length;
       run.sourceTo = run.sourceFrom + run.serialized.length;
-      delta += run.serialized.length - token.length;
-      return run.serialized;
+      delta += escape.length + run.serialized.length - token.length;
+      return escape + run.serialized;
     },
   );
   if (unmappable || runs.some((run) => run.sourceFrom < 0)) return null;
@@ -220,12 +259,16 @@ function formattingRuns(
         from: run.sourceFrom,
         to: run.sourceTo,
         textOffsets: run.textOffsets,
+        reopened: run.reopened, // L7 bridge
       },
     })),
   };
 }
 
-type SourceSpan = TextRange & { textOffsets: number[] };
+type SourceSpan = TextRange & {
+  textOffsets: number[];
+  reopened?: Map<number, number>; // L7 bridge
+};
 type SourceSide = "canonical" | "stored";
 
 export type SuggestionSourceAlignment = {
@@ -266,6 +309,30 @@ function sourceAlignment(source: string): SuggestionSourceAlignment | null {
       map: (offset) => (inside(offset, source) ? offset : null),
       atTextEdge: (offset) => inside(offset, source),
     };
+  // L7 bridge: canonical Markdown drops the editor's trailing empty paragraph,
+  // which a stored page may still hold on its last line; that line has no
+  // image.
+  const lastLine = source.trimEnd().lastIndexOf("\n");
+  const kept = source.slice(0, lastLine).replace(/\r$/, "");
+  if (
+    lastLine >= 0 &&
+    canonicalizeNfm(source.slice(lastLine)) === "<empty-block/>" &&
+    canonicalizeNfm(kept) === canonical
+  ) {
+    const alignment = sourceAlignment(kept);
+    return (
+      alignment && {
+        canonical,
+        map: (offset, from) =>
+          from === "stored" && offset > kept.length
+            ? null
+            : alignment.map(offset, from),
+        atTextEdge: (offset, from) =>
+          !(from === "stored" && offset > kept.length) &&
+          alignment.atTextEdge(offset, from),
+      }
+    );
+  }
   const mapped = formattingRuns(source, true) ?? formattingRuns(source, false);
   if (!mapped || mapped.restored !== canonical) return null;
   const texts = { canonical, stored: source };
@@ -312,7 +379,11 @@ function sourceAlignment(source: string): SuggestionSourceAlignment | null {
           if (offset === own.from) return other.from;
           if (offset === own.to) return other.to;
           const index = own.textOffsets.indexOf(offset - own.from);
-          return index < 0 ? null : other.from + other.textOffsets[index]!;
+          const boundary =
+            index < 0 ? own.reopened?.get(offset - own.from) : index; // L7 bridge
+          return boundary === undefined
+            ? null
+            : other.from + other.textOffsets[boundary]!;
         }
         previous = { canonical: span.canonical.to, stored: span.stored.to };
       }
@@ -340,6 +411,8 @@ function normalizedSourceGap(source: string, from: number, to: number): string {
 
 const TABLE_TAG = /<\/?(?:table|tr|td|th)\b[^>]*>/;
 
+const ASCII_PUNCTUATION = /^[!-/:-@[-`{-~]$/; // L7 bridge
+
 // Canonical NFM writes a stored pipe table as an HTML table. Both reduce to
 // "|" between cells and a newline between rows, with or without the stored
 // rows' optional outer pipes; the final reparse proves the cells.
@@ -376,6 +449,17 @@ function mapStoredSourceRuns(
     }
     return true;
   };
+  // L7 bridge: agents spell emphasis with underscores where the writer uses
+  // stars; the final parse check proves the delimiters pair up the same way.
+  const matchesDelimiters = (token: string, position: number) => {
+    for (let index = 0; index < token.length; index += 1) {
+      if (remainingWork-- <= 0) return false;
+      const stored = source[position + index];
+      if (stored !== token[index] && !(token[index] === "*" && stored === "_"))
+        return false;
+    }
+    return true;
+  };
   const gapMatches = (
     from: number,
     to: number,
@@ -445,6 +529,10 @@ function mapStoredSourceRuns(
     }
     const prefix = run.serialized.slice(0, run.textOffsets[0]);
     const suffix = run.serialized.slice(run.textOffsets[run.text.length]);
+    // L7 bridge: adjacent runs with the same formatting read as one, so the
+    // stored source may close and reopen the run's delimiters between two
+    // characters.
+    const reopen = prefix && suffix ? suffix + prefix : "";
     const tokens = run.text
       .split("")
       .map((_character, characterIndex) =>
@@ -456,9 +544,10 @@ function mapStoredSourceRuns(
     let found = false;
     for (let start = cursor; start < source.length; start += 1) {
       if (remainingWork < 0) return false;
-      if (!matches(prefix, start)) continue;
+      if (!matchesDelimiters(prefix, start)) continue; // L7 bridge
       let position = start + prefix.length;
       const textOffsets = [prefix.length];
+      let reopened: Map<number, number> | undefined; // L7 bridge
       let valid = true;
       for (
         let characterIndex = 0;
@@ -467,9 +556,35 @@ function mapStoredSourceRuns(
       ) {
         const token = tokens[characterIndex]!;
         const character = run.text[characterIndex]!;
+        // L7 bridge
+        if (
+          characterIndex > 0 &&
+          reopen &&
+          !matches(token, position) &&
+          matchesDelimiters(reopen, position)
+        ) {
+          position += reopen.length;
+          // The boundary before this character sits on both sides of the
+          // reopened delimiters.
+          (reopened ??= new Map()).set(position - start, characterIndex);
+        }
         if (matches(token, position)) position += token.length;
-        // Inline math is an atom, so a dollar in a parsed text run is literal.
-        else if (token === "\\$" && matches("$", position)) position += 1;
+        else if (
+          ASCII_PUNCTUATION.test(character) &&
+          // Emphasis must match as delimiters, not as escaped literal text.
+          !"*_~".includes(character) &&
+          token === `\\${character}` &&
+          matches(character, position)
+        )
+          position += 1;
+        // L7 bridge: a backslash before any punctuation reads as that
+        // punctuation.
+        else if (
+          ASCII_PUNCTUATION.test(character) &&
+          token === character &&
+          matches(`\\${character}`, position)
+        )
+          position += 2;
         else if (character === "\n" && token.startsWith("\n")) {
           const indent = token.slice(1);
           if (matches(`\r\n${indent}`, position)) position += 2 + indent.length;
@@ -486,7 +601,7 @@ function mapStoredSourceRuns(
         if (!valid) break;
         textOffsets.push(position - start);
       }
-      if (!valid || !matches(suffix, position)) continue;
+      if (!valid || !matchesDelimiters(suffix, position)) continue; // L7 bridge
       position += suffix.length;
       if (!gapMatches(cursor, start, canonicalCursor, run.sourceFrom))
         return false;
@@ -496,6 +611,7 @@ function mapStoredSourceRuns(
       run.sourceFrom = start;
       run.sourceTo = position;
       run.textOffsets = textOffsets;
+      run.reopened = reopened; // L7 bridge
       found = true;
       break;
     }
@@ -595,7 +711,7 @@ export function suggestionFormattingSourceSlice(
   const appendStructuralGap = (gapFrom: number, gapTo: number) => {
     const gapParts = structuralGapParts(source, gapFrom, gapTo);
     if (!gapParts) return false;
-    parts.push(...gapParts);
+    pushAll(parts, gapParts);
     return true;
   };
   for (const run of mapped.runs) {
@@ -613,7 +729,7 @@ export function suggestionFormattingSourceSlice(
       for (let index = 0; index <= run.text.length; index += 1) {
         if (textBoundarySourceOffset(run, index) === offset) return index;
       }
-      return null;
+      return run.reopened?.get(offset - run.sourceFrom) ?? null; // L7 bridge
     };
     const start = textIndex(overlapFrom);
     const end = textIndex(overlapTo);
@@ -835,6 +951,13 @@ export function suggestionFormattingSourceRange(
             affinity: preferredAffinity,
           });
       }
+      // L7 bridge
+      const reopened = run.reopened?.get(offset - run.sourceFrom);
+      if (reopened !== undefined)
+        candidates.push({
+          offset: run.from + reopened,
+          affinity: preferredAffinity,
+        });
     }
     for (const gap of gaps) {
       if (offset < gap.sourceFrom || offset > gap.sourceTo) continue;

package/corpus/templates/content/shared/suggestion-text.ts

@@ -172,9 +172,48 @@ export function suggestionTextPresentation(
   return nodes;
 }
 
+// Each suggestion is presented from its own copy of the Page, and the editor
+// asks again on every highlight rebuild, so recent Pages keep their results.
+// Each Page keeps its 256 most recent ranges: while a suggestion is being
+// drafted its Page stays the same and its range keeps changing.
+const presentationsBySource = new Map<
+  string,
+  Map<string, SuggestionPresentationNode[] | null>
+>();
+
 export function suggestionTextPresentationForSource(
   content: string,
   context: SuggestionPresentationContext,
+): SuggestionPresentationNode[] | null {
+  const key = `${context.from}:${context.to}:${content}`;
+  let known = presentationsBySource.get(context.source);
+  if (known) {
+    presentationsBySource.delete(context.source);
+    presentationsBySource.set(context.source, known);
+    if (known.has(key)) {
+      const presentation = known.get(key)!;
+      known.delete(key);
+      known.set(key, presentation);
+      return presentation;
+    }
+  } else {
+    if (presentationsBySource.size >= 128)
+      presentationsBySource.delete(presentationsBySource.keys().next().value!);
+    known = new Map();
+    presentationsBySource.set(context.source, known);
+  }
+  const presentation = computeSuggestionTextPresentationForSource(
+    content,
+    context,
+  );
+  if (known.size >= 256) known.delete(known.keys().next().value!);
+  known.set(key, presentation);
+  return presentation;
+}
+
+function computeSuggestionTextPresentationForSource(
+  content: string,
+  context: SuggestionPresentationContext,
 ): SuggestionPresentationNode[] | null {
   if (context.source.slice(context.from, context.to) !== content) return null;
   if (content.length === 0 && context.from === context.to) return [];

package/corpus/templates/content/vitest.config.ts

@@ -6,6 +6,8 @@ import baseConfig, {
 import react from "@vitejs/plugin-react-swc";
 import { defineConfig, mergeConfig } from "vitest/config";
 
+import { KNOWN_LOSS_TAG } from "./acceptance/known-loss";
+
 export default mergeConfig(
   baseConfig,
   defineConfig({
@@ -29,6 +31,14 @@ export default mergeConfig(
       // index backlog before answering, so tests take the indexed path unless
       // they force the fallback scan.
       env: { AGENT_NATIVE_SEARCH_DRAIN_BUDGET_MS: "60000" },
+      globalSetup: ["./acceptance/generate-action-registry.ts"],
+      tags: [
+        {
+          name: KNOWN_LOSS_TAG,
+          description:
+            "Main fails this today; its meta names the lane whose fix flips it. CI reports it without failing the PR.",
+        },
+      ],
       hookTimeout: 60_000,
       testTimeout: 60_000,
       maxWorkers: process.env.CONTENT_MIGRATION_POSTGRES_URL

package/corpus/templates/crm/.agents/skills/actions/references/action-fields.md

@@ -140,6 +140,6 @@ export default defineAction({
 
 When the gate is truthy and the call isn't yet approved, the loop emits an `approval_required` event and **stops the turn — `run()` never executes**. A predicate gates conditionally (e.g. only external recipients) and **fails closed**: a throw is treated as "approval required". It receives its own copy of the prepared snapshot of the validated arguments, defaults applied, and the approval binds to the snapshot's hash, so an approved call runs only with the arguments that were approved (a Date binds by its time). The human approves via the chat UI's Approve affordance, which re-issues the turn with the call's `approvalKey`, and only then does the action run.
 
-Approval is given in the app, so HTTP never grants it. The HTTP action route and the generated Workers entry run a gated call only for the proven app UI (a frontend call from the signed-in user, same origin, holding the short-lived UI capability; `isProvenUiRequest`, the proof `uiOnly` uses) or the app's MCP directory widget. Every other HTTP caller (bearer or API key, MCP OAuth token, org service token, A2A, extension iframe, mobile app) gets `409 approval_required`, and a service identity can never approve. The shared client presents the capability with every write from a signed-in session (minted once per user, reused for nine minutes, never for reads or public pages), so a gated button works on its first request. A call without proof gets `403 ui_capability_required`; the client then re-mints and retries once, which is only the fallback for an expired or rejected capability. Every surface evaluates the gate through `preparedCallNeedsApproval`, so a throwing predicate asks there too. A caller that must run unattended needs a different action, never a bypass of the gate.
+Approval is given in the app, so HTTP never grants it. The HTTP action route and the generated Workers entry run a gated call only for the proven app UI (a frontend call from the signed-in user, same origin, holding the short-lived UI capability; `isProvenUiRequest`, the proof `uiOnly` uses) or the app's MCP directory widget. Every other direct HTTP caller (bearer or API key, MCP OAuth token, org service token, extension iframe, or mobile app) gets `409 approval_required`, and a service identity can never approve. A2A tasks use their separate approval flow. The task pauses until its owner approves, then replays the approved tool call under its approval lease. The shared client presents the capability with every write from a signed-in session (minted once per user, reused for nine minutes, never for reads or public pages), so a gated button works on its first request. A call without proof gets `403 ui_capability_required`; the client then re-mints and retries once, which is only the fallback for an expired or rejected capability. The agent loop, plan mode registry, HTTP action route, generated Workers entry, and MCP dispatch evaluate the gate through `preparedCallNeedsApproval`, so a throwing predicate asks there too. The local `pnpm action ...` CLI calls `handler.run()` directly and does not evaluate `needsApproval`. Treat it as a local development tool, not an approval boundary. A caller that must run unattended needs a different action, never a bypass of the gate.
 
 **Keep approvals rare** — the default is off and almost every action should leave it off. The canonical example is Mail's `send-email` (`needsApproval: true`). See the `security` skill and the Human Approval doc.

package/corpus/templates/design/.agents/skills/actions/references/action-fields.md

@@ -140,6 +140,6 @@ export default defineAction({
 
 When the gate is truthy and the call isn't yet approved, the loop emits an `approval_required` event and **stops the turn — `run()` never executes**. A predicate gates conditionally (e.g. only external recipients) and **fails closed**: a throw is treated as "approval required". It receives its own copy of the prepared snapshot of the validated arguments, defaults applied, and the approval binds to the snapshot's hash, so an approved call runs only with the arguments that were approved (a Date binds by its time). The human approves via the chat UI's Approve affordance, which re-issues the turn with the call's `approvalKey`, and only then does the action run.
 
-Approval is given in the app, so HTTP never grants it. The HTTP action route and the generated Workers entry run a gated call only for the proven app UI (a frontend call from the signed-in user, same origin, holding the short-lived UI capability; `isProvenUiRequest`, the proof `uiOnly` uses) or the app's MCP directory widget. Every other HTTP caller (bearer or API key, MCP OAuth token, org service token, A2A, extension iframe, mobile app) gets `409 approval_required`, and a service identity can never approve. The shared client presents the capability with every write from a signed-in session (minted once per user, reused for nine minutes, never for reads or public pages), so a gated button works on its first request. A call without proof gets `403 ui_capability_required`; the client then re-mints and retries once, which is only the fallback for an expired or rejected capability. Every surface evaluates the gate through `preparedCallNeedsApproval`, so a throwing predicate asks there too. A caller that must run unattended needs a different action, never a bypass of the gate.
+Approval is given in the app, so HTTP never grants it. The HTTP action route and the generated Workers entry run a gated call only for the proven app UI (a frontend call from the signed-in user, same origin, holding the short-lived UI capability; `isProvenUiRequest`, the proof `uiOnly` uses) or the app's MCP directory widget. Every other direct HTTP caller (bearer or API key, MCP OAuth token, org service token, extension iframe, or mobile app) gets `409 approval_required`, and a service identity can never approve. A2A tasks use their separate approval flow. The task pauses until its owner approves, then replays the approved tool call under its approval lease. The shared client presents the capability with every write from a signed-in session (minted once per user, reused for nine minutes, never for reads or public pages), so a gated button works on its first request. A call without proof gets `403 ui_capability_required`; the client then re-mints and retries once, which is only the fallback for an expired or rejected capability. The agent loop, plan mode registry, HTTP action route, generated Workers entry, and MCP dispatch evaluate the gate through `preparedCallNeedsApproval`, so a throwing predicate asks there too. The local `pnpm action ...` CLI calls `handler.run()` directly and does not evaluate `needsApproval`. Treat it as a local development tool, not an approval boundary. A caller that must run unattended needs a different action, never a bypass of the gate.
 
 **Keep approvals rare** — the default is off and almost every action should leave it off. The canonical example is Mail's `send-email` (`needsApproval: true`). See the `security` skill and the Human Approval doc.

package/corpus/templates/design/.agents/skills/native-effects/SKILL.md

@@ -6,20 +6,27 @@ description: >-
 
 # Native WebGPU effects
 
-The native shader catalog returned by `get-shader` (`format: "native-v2"`) contains the exact definition versions available in Design. Each entry is one original shader with useful default properties the user can customize; do not create visual variants as preset entries. Historical GLSL shaders use the separate `shader-fills` workflow.
+The native shader catalog returned by `get-shader` (`format: "native-v2"`) contains the exact definition versions available in Design. Each entry is one original shader with useful default properties the user can customize; do not create visual variants as preset entries. Previously saved GLSL blocks remain renderable and removable; new shader authoring uses native WGSL.
 
 Read the definitions and their full property schemas with `get-shader`, then read the selected file with `get-shader` or `read-source-file`. Keep its `versionHash` and call `edit-native-shader` with `expectedVersionHash`. Apply a definition by its exact `definitionId` and `definitionVersion`; omit `params` to use all declared defaults or pass property-keyed overrides. For example, `an-native-mesh-anchors` version `5` has a `palette` color-ramp property. To shift it from blue to teal, apply with `params: { palette: [{ position: 0, color: { space: "srgb", components: [0.145, 0.388, 0.922], alpha: 1 } }, { position: 1, color: { space: "srgb", components: [0.078, 0.722, 0.651], alpha: 1 } }] }`. Stop positions run from 0 to 1; color components are normalized sRGB values from 0 to 1. For a selected element without a stable authored `data-agent-native-node-id`, pass a unique same-file `targetSelector`; the action stamps its stable ID and applies the effect in one guarded write. Do not copy generated runtime scripts into source. Fill apply appends another native Fill on the same authored layer, preserving existing Fill instances and CSS paints. Target authored `nodeId` values from the source or projection, rather than layer display names. The manifest `instances` array orders native Fills from bottom to top; the inspector lists the frontmost first. Only one enabled native Layer can be newly applied per target; Backdrop uses its own placement.
 
 ## Create with AI
 
-The Shader fill and effect pickers open the existing AgentSidebar with a draft request. Let the user describe the appearance, then use the supplied designId, fileId, authored nodeId or targetSelector, and placement. Create native WebGPU WGSL with declared editable properties; this workflow does not use the historical GLSL shader blocks. Read `get-shader` and the selected source first so the definition uses the current native manifest, uniform, pass, and resource contracts.
+The Shader fill and effect pickers open the existing AgentSidebar with a draft request. Let the user describe the appearance, then use the supplied designId, fileId, authored nodeId or targetSelector, and placement. Create native WebGPU WGSL with declared editable properties; this workflow creates native WGSL rather than historical GLSL blocks. Read `get-shader` and the selected source first so the definition uses the current native manifest, uniform, pass, and resource contracts.
 
 Save the validated custom definition with `edit-native-shader` operation `define-definition` and the current `expectedVersionHash`. Read back with `get-shader` to obtain the saved definition's exact execution hash, approve that version with `approve-definition` and `expectedExecutionHash`, then apply its ID/version to the selected target. Re-read the source hash after each write. Approval is scoped to the current Design and caller; changed executable content needs its own exact-hash approval. Preserve built-in IDs and versions. For a revision, save a new version, approve its execution hash, and use `revise-definition` for the intended instances.
 
+Folded Mesh uses the native indexed-mesh render contract: set `mesh: { columns, rows }` on the render pass, with safe-integer dimensions from 16 to 256 and at most 32,768 cells; omit `draw` and `dispatch` on that pass. WGSL vertex stages address the runtime's shared grid with `@builtin(vertex_index)`. Version `3` retains the 28 numeric controls from version `2` and adds up to four editable lights and four noise bands through shared record-array controls. Light records contain normalized position and direction, color, intensity, amount, and normalized focus; noise-band records contain left/right/top/bottom bounds, feather, strength, frequency, color fade, and normalized focus. Child field units and display scales are part of the returned schema; frequency is cycles per UV axis and displays with `×`. The native record-array contract uses ordered rows, exact field keys, and at most four rows. Angles display in degrees, time offset in seconds, and normalized values in percent; line density displays as a count. Compact packing places scalar properties in consecutive float lanes, aligns `vec2` values to two lanes, and aligns structured paint/color blocks to `vec4`. Folded Mesh versions `1` and `2` use the legacy 128-float (32-`vec4`) capacity; version `3` opts into 256 floats (64 `vec4`s). Read `get-shader` for exact property keys, defaults, units, and WGSL before creating or editing a definition.
+
 Custom definitions saved in the file appear in the existing picker for their supported Fill, Layer, or Backdrop placement, and their declared properties use the shared controls. Verify the actual GPU preview and persistence after reload before reporting a created shader working; schema validation and a thumbnail alone do not establish the user's requested appearance.
 
 Liquid Metal version `12` has independent `tint` and `fill` properties. Tint is a normalized RGBA color. Fill defaults to a solid gray paint: `{ kind: "solid", color: { space: "srgb", components: [0.667, 0.667, 0.675], alpha: 1 } }`. A gradient Fill has `kind` (`linear`, `radial`, `angular`, or `diamond`), a CSS-degree `angle`, and 2–8 `stops` with normalized `position` and `color` values. Gradients use the shared picker’s centered geometry and may include `opacity` from 0 to 1. Supported `interpolation` values are `in srgb`, `in srgb-linear`, `in oklab`, and `in display-p3`; omitted or empty interpolation uses sRGB for all-sRGB stops and Oklab when a stop uses Display P3. The internal reflection profile is independent of Fill. Liquid Metal wraps its reflections around painted SVG shapes and uses the element box on HTML layers.
 
 Liquid Glass version `3` (`an-native-liquid-glass`) is the current Backdrop material. It refracts content behind an HTML element or an outer SVG logo with edge falloff that tapers into the center. Apply it through the existing Effects picker or `edit-native-shader`; its declared properties use the shared controls and color picker. HTML receivers inherit their authored corner radii. SVG receivers follow their complete painted silhouette, including holes and transparent paint. Target the outer SVG with an HTML parent, or the whole editable SVG group created by a new file drop. Imported groups retain their painted silhouette and holes. Existing ordinary frames retain box coverage. Standalone child paths, SVG child groups, nested SVG targets, text clipping, and SVG content rejected by the native source serializer remain unsupported. Versions `1` and `2` remain executable for existing designs. Liquid Metal remains a separate Fill/Layer material.
 
+Pulsing Border version `5` (`an-native-pulsing-border`) supports Fill and Layer placement; versions `3` and `4` remain executable for existing designs. It follows authored HTML corner radii or painted SVG silhouettes, including holes; its Fill is transparent beyond the contour and its Layer preserves the receiver's center. Default roundness `.25` preserves the authored outline; other values adjust corner curvature through a bounded symmetric distance-field kernel while keeping straight edges anchored. Colors is a spatial Linear or Angular paint with up to eight editable stops in the standard gradient picker; moving light stations illuminate that paint. Background remains a separate color. Thickness controls the bright edge width, Softness feathers that edge, Bloom controls glow brightness, and Glow spread controls glow radius independently. Intensity, pulse, smoke, and sizing controls remain editable; `get-shader` exposes the full property schema and defaults. The shared `margin` supplies each side's value unless that side has an explicit override, including an explicit zero. Playback speed and frame use the ordinary native instance controls. The light and smoke patterns are generated in WGSL without an image input.
+
+Editor, presentation, board overview, template, and catalog previews use the shared native preview surface and runtime. Interactive surfaces follow the document's 60 or 120 fps target. Compact thumbnails animate at 15 fps while visible and pause when offscreen; they retain the same shader execution, geometry, and input assets.
+Board live, static, and over-screen previews share one host animation epoch across iframe remounts, so panning or zooming does not restart the effect phase. Capped over-screen previews use a bounded logical viewport while retaining the authored board transform.
+
 `set-params` updates only the supplied properties on the selected stable `instanceId`. Use `set-instance` with that ID for independent `enabled` visibility, `opacity`, and other instance settings. `playback`, `duplicate`, `reorder`, and `remove` use the same action and current source hash. `remove` deletes only the addressed instance. For native Fill ordering, use same-node Fill instance IDs: `reorder` puts an instance before `beforeInstanceId` in the bottom-to-top manifest, or at the top with `beforeInstanceId: null`. Native Fill ordering does not interleave with CSS paint rows. On a stale-source error, re-read before retrying. A CPU-valid action result does not prove a GPU frame; inspect the Design preview. PNG preparation pins the saved file, unchanged layout viewport, and optional output region. Selected-region PNG rerenders at the pinned live clock and requested density, isolating the selected authored subtrees while preserving full backdrop sampling context. Capture without an output region retains the last committed native-frame path. External agents can call `get-native-render-contexts`, request a local foreground PNG with `request-native-local-export` and the exact source version, then poll `get-native-local-export`. After the editor claims the request, it captures the requested frame or isolated region, stores an owner-scoped PNG attachment, and marks the request completed. `get-native-local-export` then returns a protected same-origin download URL and opaque attachment reference. A pending request or browser download initiation is not completion. `export-png` rejects enabled native effects rather than returning headless pixels without them. A source mismatch, missing frame, or unsupported definition is a failure, not a blank export.