@agent-native/core-corpus 0.214.0 → 0.216.0

package/corpus/templates/design/actions/_native-render-contexts.ts

@@ -1,8 +1,9 @@
 import { fail } from "@agent-native/core/action";
 import {
-  compareAndSetAppState,
+  compareAndSetManyAppState,
   getCurrentRequestBrowserTabId,
   readAppState,
+  type AppStateCompareAndSetOperation,
 } from "@agent-native/core/application-state";
 import { assertAccess } from "@agent-native/core/sharing";
 
@@ -10,13 +11,18 @@ import {
   NATIVE_RENDER_CONTEXT_LEDGER_KEY,
   NATIVE_RENDER_CONTEXT_LIMIT,
   NATIVE_RENDER_CONTEXT_TTL_MS,
+  nativeLocalExportRevisionKey,
+  nativeLocalExportStateKey,
   nativeRenderContextLedgerSchema,
   nativeRenderContextSchema,
   type NativeRenderContext,
 } from "../shared/native-local-export.js";
 import {
   classifyNativeLocalExportNavigation,
-  markNativeLocalExportDocumentReplaced,
+  expireNativeLocalExportState,
+  planNativeLocalExportDocumentRegistration,
+  readNativeLocalExportRevision,
+  readNativeLocalExportState,
 } from "./_native-local-export-server.js";
 
 function readLedger(raw: Record<string, unknown> | null): {
@@ -79,6 +85,7 @@ export async function registerNativeRenderContext(
     const context: NativeRenderContext = {
       tabId: parsedTabId.data,
       designId,
+      documentId,
       expiresAt: now + NATIVE_RENDER_CONTEXT_TTL_MS,
     };
     const contexts = [
@@ -93,16 +100,39 @@ export async function registerNativeRenderContext(
         statusCode: 409,
       });
     const next = { schemaVersion: 1 as const, contexts };
-    if (
-      await compareAndSetAppState(NATIVE_RENDER_CONTEXT_LEDGER_KEY, raw, next)
-    ) {
-      await markNativeLocalExportDocumentReplaced(
-        designId,
-        parsedTabId.data,
-        documentId,
-      );
-      return context;
-    }
+    const revision = await readNativeLocalExportRevision(
+      designId,
+      parsedTabId.data,
+    );
+    const exportRaw = await readNativeLocalExportState(
+      designId,
+      parsedTabId.data,
+    );
+    const exportCurrent = exportRaw
+      ? await expireNativeLocalExportState(exportRaw)
+      : null;
+    const exportNext = exportCurrent
+      ? planNativeLocalExportDocumentRegistration(exportCurrent, documentId)
+      : null;
+    const operations: AppStateCompareAndSetOperation[] = [
+      {
+        key: NATIVE_RENDER_CONTEXT_LEDGER_KEY,
+        expectedValue: raw,
+        nextValue: next,
+      },
+      {
+        key: nativeLocalExportRevisionKey(designId, parsedTabId.data),
+        expectedValue: revision,
+        nextValue: { schemaVersion: 1, revision: crypto.randomUUID() },
+      },
+    ];
+    if (exportCurrent && exportNext !== exportCurrent)
+      operations.push({
+        key: nativeLocalExportStateKey(designId, parsedTabId.data),
+        expectedValue: exportCurrent,
+        nextValue: exportNext,
+      });
+    if (await compareAndSetManyAppState(operations)) return context;
   }
   fail("Native editor context changed concurrently. Retry.", {
     errorCode: "native_export_context_conflict",
@@ -112,27 +142,49 @@ export async function registerNativeRenderContext(
 
 export async function listNativeRenderContexts(
   designId: string,
+  targetTabId?: string,
 ): Promise<NativeRenderContext[]> {
+  return (await readNativeRenderContextSnapshot(designId, targetTabId))
+    .contexts;
+}
+
+export async function readNativeRenderContextSnapshot(
+  designId: string,
+  targetTabId?: string,
+): Promise<{
+  contexts: NativeRenderContext[];
+  rawLedger: Record<string, unknown> | null;
+}> {
   await assertAccess("design", designId, "viewer");
-  const ledger = readLedger(
-    await readAppState(NATIVE_RENDER_CONTEXT_LEDGER_KEY),
-  );
+  const rawLedger = await readAppState(NATIVE_RENDER_CONTEXT_LEDGER_KEY);
+  const ledger = readLedger(rawLedger);
   const now = Date.now();
   const candidates = ledger.contexts.filter(
-    (entry) => entry.designId === designId && entry.expiresAt > now,
+    (entry) =>
+      entry.designId === designId &&
+      entry.expiresAt > now &&
+      (!targetTabId || entry.tabId === targetTabId),
   );
   const active = await Promise.all(
     candidates.map(async (entry) =>
       (await navigationMatches(designId, entry.tabId)) ? entry : null,
     ),
   );
-  return active.filter((entry): entry is NativeRenderContext => entry !== null);
+  return {
+    contexts: active.filter(
+      (entry): entry is NativeRenderContext => entry !== null,
+    ),
+    rawLedger,
+  };
 }
 
 export async function resolveNativeRenderContextTarget(
   designId: string,
   targetTabId: string,
-): Promise<string> {
+): Promise<{
+  context: NativeRenderContext;
+  rawLedger: Record<string, unknown>;
+}> {
   const parsedTabId =
     nativeRenderContextSchema.shape.tabId.safeParse(targetTabId);
   if (!parsedTabId.success)
@@ -140,11 +192,14 @@ export async function resolveNativeRenderContextTarget(
       errorCode: "native_export_context_not_found",
       statusCode: 404,
     });
-  const active = await listNativeRenderContexts(designId);
-  if (!active.some((entry) => entry.tabId === targetTabId))
+  const snapshot = await readNativeRenderContextSnapshot(designId, targetTabId);
+  const context = snapshot.contexts.find(
+    (entry) => entry.tabId === targetTabId,
+  );
+  if (!context || !snapshot.rawLedger)
     fail("No live matching Design editor context was found.", {
       errorCode: "native_export_context_not_found",
       statusCode: 404,
     });
-  return targetTabId;
+  return { context, rawLedger: snapshot.rawLedger };
 }

package/corpus/templates/design/actions/claim-native-local-export.ts

@@ -40,6 +40,11 @@ export default defineAction({
         errorCode: "native_export_request_not_pending",
         statusCode: 409,
       });
+    if (current.targetDocumentId && current.targetDocumentId !== documentId)
+      fail("This editor document no longer owns the local export.", {
+        errorCode: "native_export_document_replaced",
+        statusCode: 409,
+      });
     const liveSource = await readNativeLocalExportVersion(
       designId,
       current.fileId,

package/corpus/templates/design/actions/finish-native-local-export.ts

@@ -57,12 +57,22 @@ export default defineAction({
         statusCode: 404,
       });
     const current = await expireNativeLocalExportState(currentRaw);
-    if (current.ownerDocumentId !== documentId)
+    const pendingClaimFailure =
+      current.status === "pending" &&
+      current.ownerDocumentId === undefined &&
+      current.targetDocumentId === documentId &&
+      result.status === "failed" &&
+      result.code === "client-unavailable";
+    if (!pendingClaimFailure && current.ownerDocumentId !== documentId)
       fail("This editor document no longer owns the local export.", {
         errorCode: "native_export_document_replaced",
         statusCode: 409,
       });
-    if (current.status !== "running" && current.status !== "cancel-requested")
+    if (
+      !pendingClaimFailure &&
+      current.status !== "running" &&
+      current.status !== "cancel-requested"
+    )
       fail("The local export request is not running.", {
         errorCode: "native_export_request_not_running",
         statusCode: 409,
@@ -128,6 +138,7 @@ export default defineAction({
     }
     const completed: NativeLocalExportState = {
       ...current,
+      ...(pendingClaimFailure ? { ownerDocumentId: documentId } : {}),
       status:
         result.status === "failed" && result.code === "canceled"
           ? "canceled"

package/corpus/templates/design/actions/get-native-shader-approvals.ts

@@ -0,0 +1,35 @@
+import { defineAction, fail } from "@agent-native/core/action";
+import { readAppState } from "@agent-native/core/application-state";
+import { resolveAccess } from "@agent-native/core/sharing";
+import { z } from "zod";
+
+import "../server/db/index.js";
+import {
+  NativeEffectApprovalStateError,
+  nativeEffectApprovalKey,
+  parseNativeEffectApprovalState,
+} from "../shared/native-effect-trust.js";
+
+export default defineAction({
+  description:
+    "Read the current viewer's exact native effect approvals for an accessible Design.",
+  schema: z.object({ designId: z.string().min(1) }),
+  readOnly: true,
+  http: { method: "GET" },
+  run: async ({ designId }) => {
+    if (!(await resolveAccess("design", designId)))
+      fail("Design not found", { errorCode: "not_found", statusCode: 404 });
+    try {
+      const approvals = parseNativeEffectApprovalState(
+        await readAppState(nativeEffectApprovalKey(designId)),
+      );
+      return { designId, approvedDefinitionHashes: approvals.hashes };
+    } catch (error) {
+      if (!(error instanceof NativeEffectApprovalStateError)) throw error;
+      fail("Native effect approval state is unreadable.", {
+        errorCode: "native_effect_approvals_unreadable",
+        statusCode: 422,
+      });
+    }
+  },
+});

package/corpus/templates/design/actions/get-shader.ts

@@ -27,11 +27,6 @@ import {
   inspectNativeEffectHtml,
   type EffectDefinition,
 } from "../shared/native-effects.js";
-import {
-  SHADER_PRESET_MAP,
-  SHADER_PRESETS,
-  type ShaderPresetName,
-} from "../shared/shader-presets.js";
 
 async function summarizeNativeDefinition(definition: EffectDefinition) {
   return {
@@ -59,10 +54,10 @@ async function summarizeNativeDefinition(definition: EffectDefinition) {
 
 export default defineAction({
   description:
-    "List exact registered native GPU shader definitions with editable properties and defaults, or inspect a selected inline Design file's saved native effect manifest. Use the returned versionHash with edit-native-shader for compare-and-set changes. format=legacy returns read-only historical shader descriptors.",
+    "List exact registered native GPU shader definitions with editable properties and defaults, or inspect a selected inline Design file's saved native effect manifest. Use the returned versionHash with edit-native-shader for compare-and-set changes.",
   http: { method: "GET" },
   schema: z.object({
-    format: z.enum(["native-v2", "legacy"]).default("native-v2"),
+    format: z.literal("native-v2").default("native-v2"),
     definitionId: z.string().optional(),
     definitionVersion: z.coerce.number().int().positive().optional(),
     includeSource: z
@@ -101,230 +96,150 @@ export default defineAction({
     source,
     target,
   }) => {
-    if (format === "native-v2") {
-      if (
-        source?.kind === "inline-html" ||
-        (source && (!source.designId || (!source.fileId && !source.path)))
-      )
-        fail("Native effect inspection needs a Design file ID or path.", {
-          errorCode: "native_effect_source_required",
+    if (
+      source?.kind === "inline-html" ||
+      (source && (!source.designId || (!source.fileId && !source.path)))
+    )
+      fail("Native effect inspection needs a Design file ID or path.", {
+        errorCode: "native_effect_source_required",
+        statusCode: 400,
+      });
+    let document: ReturnType<typeof inspectNativeEffectHtml>["document"] = null;
+    let file: { id: string; filename: string } | null = null;
+    let versionHash: string | null = null;
+    let targetNodeState: "not-requested" | "present" = "not-requested";
+    let approvedDefinitionHashes: string[] = [];
+    if (source) {
+      const designId = source.designId!;
+      const workspace = await resolveSourceWorkspace(designId, {
+        includeContent: false,
+        includeBoard: true,
+      });
+      const selectedFile = workspace.files.find((candidate) =>
+        source.fileId
+          ? candidate.id === source.fileId
+          : candidate.filename === source.path,
+      );
+      if (!selectedFile)
+        fail("Design source file not found.", {
+          errorCode: "native_effect_file_not_found",
+          statusCode: 404,
+        });
+      if (selectedFile.fileType !== "html")
+        fail("Native effects require an inline HTML file.", {
+          errorCode: "native_effect_non_html",
           statusCode: 400,
         });
-      let document: ReturnType<typeof inspectNativeEffectHtml>["document"] =
-        null;
-      let file: { id: string; filename: string } | null = null;
-      let versionHash: string | null = null;
-      let targetNodeState: "not-requested" | "present" = "not-requested";
-      let approvedDefinitionHashes: string[] = [];
-      if (source) {
-        const designId = source.designId!;
-        const workspace = await resolveSourceWorkspace(designId, {
-          includeContent: false,
-          includeBoard: true,
+      const selectedWithContent =
+        await loadSelectedSourceWorkspaceFile(selectedFile);
+      if (!selectedWithContent)
+        fail("Design source file not found.", {
+          errorCode: "native_effect_file_not_found",
+          statusCode: 404,
         });
-        const selectedFile = workspace.files.find((candidate) =>
-          source.fileId
-            ? candidate.id === source.fileId
-            : candidate.filename === source.path,
+      const live = await readLiveSourceFile(selectedWithContent);
+      const parsed = inspectNativeEffectHtml(live.content, target?.nodeId);
+      if (parsed.errors.length)
+        fail(
+          `Native effect manifest is unreadable: ${parsed.errors.join("; ")}`,
+          {
+            errorCode: "native_effect_manifest_unreadable",
+            statusCode: 422,
+            details: { errors: parsed.errors },
+          },
         );
-        if (!selectedFile)
-          fail("Design source file not found.", {
-            errorCode: "native_effect_file_not_found",
-            statusCode: 404,
-          });
-        if (selectedFile.fileType !== "html")
-          fail("Native effects require an inline HTML file.", {
-            errorCode: "native_effect_non_html",
-            statusCode: 400,
-          });
-        const selectedWithContent =
-          await loadSelectedSourceWorkspaceFile(selectedFile);
-        if (!selectedWithContent)
-          fail("Design source file not found.", {
-            errorCode: "native_effect_file_not_found",
-            statusCode: 404,
-          });
-        const live = await readLiveSourceFile(selectedWithContent);
-        const parsed = inspectNativeEffectHtml(live.content, target?.nodeId);
-        if (parsed.errors.length)
+      if (target?.nodeId) {
+        if (parsed.target.activeCount !== 1)
           fail(
-            `Native effect manifest is unreadable: ${parsed.errors.join("; ")}`,
+            `Expected one authored node ${target.nodeId}, found ${parsed.target.activeCount}.`,
             {
-              errorCode: "native_effect_manifest_unreadable",
-              statusCode: 422,
-              details: { errors: parsed.errors },
+              errorCode: parsed.target.activeCount
+                ? "native_effect_target_ambiguous"
+                : "native_effect_target_not_found",
+              statusCode: parsed.target.activeCount ? 422 : 404,
             },
           );
-        if (target?.nodeId) {
-          if (parsed.target.activeCount !== 1)
-            fail(
-              `Expected one authored node ${target.nodeId}, found ${parsed.target.activeCount}.`,
-              {
-                errorCode: parsed.target.activeCount
-                  ? "native_effect_target_ambiguous"
-                  : "native_effect_target_not_found",
-                statusCode: parsed.target.activeCount ? 422 : 404,
-              },
-            );
-          targetNodeState = "present";
-        }
-        document = parsed.document;
-        file = selectedFile;
-        versionHash = live.versionHash;
-        try {
-          approvedDefinitionHashes = parseNativeEffectApprovalState(
-            await readAppState(nativeEffectApprovalKey(designId)),
-          ).hashes;
-        } catch (error) {
-          if (!(error instanceof NativeEffectApprovalStateError)) throw error;
-          fail("Native effect approval state is unreadable.", {
-            errorCode: "native_effect_approvals_unreadable",
-            statusCode: 422,
-          });
-        }
+        targetNodeState = "present";
       }
-      const definitions = new Map<string, EffectDefinition>();
-      for (const definition of [
-        ...(definitionVersion === undefined
-          ? NATIVE_EFFECT_DEFINITION_CATALOG
-          : NATIVE_EFFECT_BUILTIN_VERSIONS),
-        ...(document?.definitions ?? []),
-      ])
-        definitions.set(
-          `${definition.id}\u0000${definition.version}`,
-          definition,
-        );
-      const catalog = [...definitions.values()].filter(
-        (definition) =>
-          (!definitionId || definition.id === definitionId) &&
-          (!definitionVersion || definition.version === definitionVersion),
-      );
-      if (definitionId && catalog.length === 0)
-        fail("Native effect definition version not found.", {
-          errorCode: "native_effect_definition_not_found",
-          statusCode: 404,
+      document = parsed.document;
+      file = selectedFile;
+      versionHash = live.versionHash;
+      try {
+        approvedDefinitionHashes = parseNativeEffectApprovalState(
+          await readAppState(nativeEffectApprovalKey(designId)),
+        ).hashes;
+      } catch (error) {
+        if (!(error instanceof NativeEffectApprovalStateError)) throw error;
+        fail("Native effect approval state is unreadable.", {
+          errorCode: "native_effect_approvals_unreadable",
+          statusCode: 422,
         });
-      return {
-        format,
-        parameterValueSpace: "canonical" as const,
-        instancePresentation: {
-          opacity: {
-            ...NATIVE_OPACITY_PRESENTATION,
-            default: 100,
-            min: 0,
-            max: 100,
-          },
-          timing: {
-            speed: { ...NATIVE_SPEED_PRESENTATION, default: 100, min: 0 },
-          },
-        },
-        manifestState: !source
-          ? ("not-requested" as const)
-          : document
-            ? ("present" as const)
-            : ("absent" as const),
-        designId: source?.designId ?? null,
-        fileId: file?.id ?? null,
-        path: file?.filename ?? null,
-        versionHash,
-        targetNodeState,
-        approvedDefinitionHashes,
-        document: document
-          ? {
-              schemaVersion: document.schemaVersion,
-              definitions: await Promise.all(
-                document.definitions.map(summarizeNativeDefinition),
-              ),
-              instances: document.instances,
-              presets: document.presets ?? [],
-              preview: document.preview ?? null,
-            }
-          : null,
-        targetInstances: target?.nodeId
-          ? (document?.instances ?? []).filter(
-              (instance) => instance.nodeId === target.nodeId,
-            )
-          : (document?.instances ?? []),
-        definitions: await Promise.all(catalog.map(summarizeNativeDefinition)),
-        selectedDefinition: includeSource ? (catalog[0] ?? null) : null,
-      };
+      }
     }
-    const sourceKind = source?.kind ?? "design-file";
-    const targetDescription = target?.nodeId
-      ? `element with id="${target.nodeId}"`
-      : target?.selector
-        ? `element matching "${target.selector}"`
-        : "any element";
-
-    const availablePresets = (
-      Object.keys(SHADER_PRESET_MAP) as ShaderPresetName[]
-    ).map((name) => {
-      const def = SHADER_PRESET_MAP[name];
-      return {
-        name,
-        label: def.label,
-        description: def.description,
-        isEffect: def.isEffect ?? false,
-        maxColorCount: def.maxColorCount,
-        paramKeys: def.params.map((p) => p.key),
-      };
-    });
-
-    const presetSummaryLines = SHADER_PRESETS.map((p) => {
-      const paramKeys = p.params.map((param) => param.key).join(", ");
-      return `  ${p.name} (${p.label}): ${p.description}${paramKeys ? ` — params: ${paramKeys}` : ""}`;
-    });
-
-    const inspectionStepsFramework = [
-      `1. Call get-code-layer-projection with the design source to retrieve the rendered HTML or JSX.`,
-      `2. Look for any import from "@paper-design/shaders-react".`,
-      `   If found, note the imported component name — that is the active preset.`,
-      `3. Read the component's JSX props: colors, colorBack, colorFront, speed, frame, fit, scale,`,
-      `   rotation, offsetX, offsetY, and any shader-specific params (distortion, swirl, shape, etc.).`,
-      `4. The zIndex prop (or style.zIndex) tells you whether it's a fill (0) or effect (2).`,
-      `5. Reconstruct the ShaderDescriptor from those props to pass back to apply-shader if editing.`,
-    ];
-
-    const inspectionStepsInline = [
-      `1. Call get-code-layer-projection with the design source to retrieve the rendered HTML.`,
-      `2. Look for <canvas data-shader='...'> elements${target ? ` inside ${targetDescription}` : ""}.`,
-      `3. Parse the data-shader JSON attribute — it is a ShaderDescriptor object with`,
-      `   { preset, params, colors?, speed?, frame?, fit?, scale?, rotation?, offsetX?, offsetY? }.`,
-      `4. The canvas element's inline style z-index tells you whether it's a fill (0) or effect (2).`,
-      `5. To update the shader, modify the data-shader attribute value via apply-visual-edit`,
-      `   with a style or attribute intent, or use apply-shader to regenerate the canvas element.`,
-    ];
-
-    const inspectionSteps =
-      sourceKind === "inline-html"
-        ? inspectionStepsInline
-        : inspectionStepsFramework;
-
-    const hint =
-      sourceKind === "inline-html"
-        ? `Search the HTML for data-shader attributes. The value is a JSON ShaderDescriptor. ` +
-          `Example: data-shader='{"preset":"MeshGradient","params":{"distortion":0.8},"colors":["#e0eaff","#241d9a"]}'.`
-        : `Search the JSX for imports from "@paper-design/shaders-react" and look for the component ` +
-          `(e.g. <MeshGradient colors={[...]} distortion={0.8} style={{...}} />). ` +
-          `The component name is the preset name.`;
-
-    const instructions = [
-      `To read the current shader state on ${targetDescription}:`,
-      "",
-      ...inspectionSteps,
-      "",
-      `Hint: ${hint}`,
-      "",
-      `To apply or change a shader, call apply-shader with the desired descriptor.`,
-      `apply-shader validates params and returns the exact JSX or HTML to insert.`,
-    ].join("\n");
-
+    const definitions = new Map<string, EffectDefinition>();
+    for (const definition of [
+      ...(definitionVersion === undefined
+        ? NATIVE_EFFECT_DEFINITION_CATALOG
+        : NATIVE_EFFECT_BUILTIN_VERSIONS),
+      ...(document?.definitions ?? []),
+    ])
+      definitions.set(
+        `${definition.id}\u0000${definition.version}`,
+        definition,
+      );
+    const catalog = [...definitions.values()].filter(
+      (definition) =>
+        (!definitionId || definition.id === definitionId) &&
+        (!definitionVersion || definition.version === definitionVersion),
+    );
+    if (definitionId && catalog.length === 0)
+      fail("Native effect definition version not found.", {
+        errorCode: "native_effect_definition_not_found",
+        statusCode: 404,
+      });
     return {
-      availablePresets,
-      presetNames: availablePresets.map((p) => p.name),
-      presetSummary: presetSummaryLines.join("\n"),
-      instructions,
-      hint,
+      format,
+      parameterValueSpace: "canonical" as const,
+      instancePresentation: {
+        opacity: {
+          ...NATIVE_OPACITY_PRESENTATION,
+          default: 100,
+          min: 0,
+          max: 100,
+        },
+        timing: {
+          speed: { ...NATIVE_SPEED_PRESENTATION, default: 100, min: 0 },
+        },
+      },
+      manifestState: !source
+        ? ("not-requested" as const)
+        : document
+          ? ("present" as const)
+          : ("absent" as const),
+      designId: source?.designId ?? null,
+      fileId: file?.id ?? null,
+      path: file?.filename ?? null,
+      versionHash,
+      targetNodeState,
+      approvedDefinitionHashes,
+      document: document
+        ? {
+            schemaVersion: document.schemaVersion,
+            definitions: await Promise.all(
+              document.definitions.map(summarizeNativeDefinition),
+            ),
+            instances: document.instances,
+            presets: document.presets ?? [],
+            preview: document.preview ?? null,
+          }
+        : null,
+      targetInstances: target?.nodeId
+        ? (document?.instances ?? []).filter(
+            (instance) => instance.nodeId === target.nodeId,
+          )
+        : (document?.instances ?? []),
+      definitions: await Promise.all(catalog.map(summarizeNativeDefinition)),
+      selectedDefinition: includeSource ? (catalog[0] ?? null) : null,
     };
   },
 });