@agent-native/core 0.75.2 → 0.75.5

package/corpus/core/src/deploy/workspace-deploy.ts

@@ -696,24 +696,30 @@ function isDurableBackgroundDeployEnabled(): boolean {
 /**
  * Emit a SECOND Netlify function for `app` whose name ends in `-background`,
  * re-exporting the SAME `main.mjs` handler bundle. Netlify invokes any function
- * whose deployed name ends in `-background` asynchronously (202 immediately, up
- * to 15-min budget), which is exactly what the durable-background chat
- * dispatch (`fireInternalDispatch` → AGENT_CHAT_PROCESS_RUN_PATH) needs.
+ * with `config.background: true` asynchronously (202 immediately, up to 15-min
+ * budget), which is exactly what the durable-background chat dispatch
+ * (`fireInternalDispatch` → the function's default url) needs.
  *
- * The function is given a `config.path` of the chat process-run route so
- * Netlify routes that POST to this async function instead of the synchronous
- * `<app>-server` function. It shares the same bundle (`includedFiles: ["**"]`)
- * so `A2A_SECRET`, the DB URL, and the rest of the env/bundle are present.
+ * DOC-CORRECT DEFAULT-URL APPROACH (mirrors the single-template emit in
+ * deploy/build.ts): the function declares NO custom `config.path`, so it keeps
+ * its DEFAULT url `/.netlify/functions/<app>-agent-background`. The `<app>-server`
+ * function's catch-all already excludes `/.netlify/*`, so that default-url
+ * namespace is NEVER shadowed by the synchronous function — no overlapping
+ * `config.path` and no catch-all patch are needed. The foreground dispatches to
+ * that default url (`resolveAgentChatProcessRunDispatchPath` resolves the per-app
+ * name from `AGENT_NATIVE_WORKSPACE_APP_ID`); `fireInternalDispatch` strips the
+ * app base path for `/.netlify/*` targets so the request reaches the host-root
+ * function url. The entry then REWRITES the incoming pathname to the
+ * base-path-prefixed `_process-run` route before delegating to the Nitro router.
  *
- * ⚠️ REAL-DEPLOY VERIFICATION REQUIRED. The exact Netlify routing/precedence
- * between this `-background` function's `config.path` and the synchronous
- * `<app>-server` function's broader `config.path` (which also matches
- * `/_agent-native/*` for the dispatch app, or `/<app>/*` otherwise) cannot be
- * verified in this environment. It is emitted additively and only under the
- * flag; if Netlify resolves the overlap to the wrong function, the dispatch
- * would land on the synchronous function (no 15-min budget) — the run would
- * still work via the existing 40s soft-timeout path, just without the durable
- * win. See packages/core/docs/design/durable-agent-runs.md.
+ * It shares the same bundle (`includedFiles: ["**"]`) so `A2A_SECRET`, the DB
+ * URL, and the rest of the env/bundle are present. A prior attempt gave the
+ * function a custom `config.path` (the framework route) that overlapped the
+ * synchronous `<app>-server` catch-all; that path was not honored as a route in
+ * prod (probe → 404). The default url is the doc-correct fix.
+ *
+ * Safety net: if the dispatch fast-fails the foreground degrades to an inline
+ * 40s synchronous run (see production-agent.ts).
  */
 function emitNetlifyBackgroundFunction(
   workspaceRoot: string,
@@ -721,7 +727,9 @@ function emitNetlifyBackgroundFunction(
   srcServerDir: string,
   workspaceApps: WorkspaceAppManifestEntry[],
 ): void {
-  // Name MUST end in `-background` for Netlify async invocation.
+  // Name MUST end in `-background` (Netlify async convention + the runtime guard
+  // reads the -background Lambda-name suffix as a fallback). It is reached at its
+  // DEFAULT url /.netlify/functions/<app>-agent-background.
   const backgroundName = `${app}-agent-background`;
   const dest = path.join(netlifyFunctionsDir(workspaceRoot), backgroundName);
   fs.rmSync(dest, { recursive: true, force: true });
@@ -733,14 +741,20 @@ function emitNetlifyBackgroundFunction(
     workspaceApps,
     app,
   );
-  // Only the chat process-run route needs the async function. Keeping the path
-  // narrow avoids stealing any other traffic from the synchronous function.
-  // The dispatch URL is app-base-path-prefixed (same as the agent-teams
-  // processor dispatch), so the route Netlify must map to this async function
-  // is `/<app>/_agent-native/agent-chat/_process-run`.
+  // The Nitro router for this app expects the base-path-prefixed framework route.
+  // The function is reached at its default url, so the entry rewrites the
+  // incoming pathname to `/<app>/_agent-native/agent-chat/_process-run`.
   const processRunPath = `${basePath}${AGENT_CHAT_PROCESS_RUN_PATH}`;
-  const pathConfig = [processRunPath];
-  const server = `const basePath = ${JSON.stringify(basePath)};
+  const server = `// Mark this isolate as the durable background runtime BEFORE the handler bundle
+// is imported, so isInBackgroundFunctionRuntime() reliably returns true in this
+// function (the deployed Lambda name is not guaranteed to end in -background). A
+// globalThis flag (NOT process.env) avoids the no-env-mutation guard and carries
+// no cross-request state.
+globalThis.__AGENT_NATIVE_BACKGROUND_RUNTIME__ = true;
+
+const basePath = ${JSON.stringify(basePath)};
+// The base-path-prefixed framework route the Nitro router dispatches to.
+const PROCESS_RUN_PATH = ${JSON.stringify(processRunPath)};
 
 function setBasePathEnv() {
   const processRef = globalThis.process ??= { env: {} };
@@ -767,16 +781,33 @@ setBasePathEnv();
 
 let cachedHandler;
 
-export default async function handler(...args) {
+// Reached at the DEFAULT url /.netlify/functions/${backgroundName}; REWRITE the
+// incoming pathname to the base-path-prefixed _process-run route so the Nitro
+// router runs the plugin. Method, ALL headers (the HMAC Authorization: Bearer
+// MUST survive) and the body are preserved.
+export default async function handler(request) {
   setBasePathEnv();
   cachedHandler ??= (await import("./main.mjs")).default;
-  return cachedHandler(...args);
+  const url = new URL(request.url);
+  url.pathname = PROCESS_RUN_PATH;
+  const method = request.method || "POST";
+  const hasBody = method !== "GET" && method !== "HEAD";
+  const body = hasBody ? await request.text() : undefined;
+  const rewritten = new Request(url.toString(), {
+    method,
+    headers: request.headers,
+    body,
+  });
+  return cachedHandler(rewritten);
 }
 
 export const config = {
   name: ${JSON.stringify(`${app} agent background handler`)},
   generator: "agent-native workspace deploy",
-  path: ${JSON.stringify(pathConfig)},
+  // background: true → async invoke (202, 15-min budget). NO custom path: the
+  // function keeps its default url /.netlify/functions/${backgroundName}, which
+  // the <app>-server catch-all never shadows (it excludes /.netlify/*).
+  background: true,
   nodeBundler: "none",
   includedFiles: ["**"],
   preferStatic: false,
@@ -788,9 +819,10 @@ export const config = {
   fs.writeFileSync(path.join(dest, `${backgroundName}.mjs`), server);
   console.log(
     `[workspace-deploy] Emitted durable-background function "${backgroundName}" ` +
-      `for app "${app}" (path ${processRunPath}). ` +
-      `REQUIRES real-deploy verification of Netlify async routing — see ` +
-      `docs/design/durable-agent-runs.md.`,
+      `for app "${app}" with config { background:true } and NO custom path — ` +
+      `reachable at its default url /.netlify/functions/${backgroundName} ` +
+      `(rewrites to ${processRunPath}). REQUIRES real-deploy verification of ` +
+      `Netlify async (202) invocation — see docs/design/durable-agent-runs.md.`,
   );
 }
 

package/corpus/core/src/server/self-dispatch.ts

@@ -20,7 +20,10 @@
  * A2A, integration webhooks, and Agent Teams sub-agents share one tested
  * implementation.
  */
-import { withConfiguredAppBasePath } from "./app-base-path.js";
+import {
+  getConfiguredAppBasePath,
+  withConfiguredAppBasePath,
+} from "./app-base-path.js";
 import { isLocalDatabase } from "../db/client.js";
 import { signInternalToken } from "../integrations/internal-token.js";
 
@@ -119,11 +122,35 @@ async function dispatchResponseError(
  * processor accepts unsigned dispatches in dev and relies on the SQL atomic
  * claim for double-processing protection, mirroring the A2A/webhook flow.
  */
+/**
+ * For host-root dispatch targets (`/.netlify/functions/*`), strip the configured
+ * app base path suffix from the resolved base url so the request reaches the
+ * function at the host root rather than under the workspace app base path. For
+ * every other (framework-route) path the base-path-prefixed base url is returned
+ * unchanged, preserving the existing self-dispatch behavior.
+ */
+function rootBaseUrlForPath(baseUrl: string, path: string): string {
+  if (!path.startsWith("/.netlify/")) return baseUrl;
+  const basePath = getConfiguredAppBasePath();
+  if (!basePath) return baseUrl;
+  const trimmed = baseUrl.replace(/\/$/, "");
+  if (trimmed.endsWith(basePath)) {
+    return trimmed.slice(0, trimmed.length - basePath.length);
+  }
+  return trimmed;
+}
+
 export async function fireInternalDispatch(
   options: FireInternalDispatchOptions,
 ): Promise<void> {
   const baseUrl = options.baseUrl ?? resolveSelfDispatchBaseUrl(options.event);
-  const url = `${baseUrl}${options.path}`;
+  // Netlify function default urls (`/.netlify/functions/<name>`) live at the
+  // HOST ROOT, not under the workspace app base path. `resolveSelfDispatchBaseUrl`
+  // appends the configured base path (e.g. `https://host/starter`) so framework
+  // routes land on the right app; for a host-root function url we must dispatch
+  // to `https://host/.netlify/functions/<name>` instead. Strip the base path
+  // suffix from the resolved base url for `/.netlify/*` dispatch targets only.
+  const url = `${rootBaseUrlForPath(baseUrl, options.path)}${options.path}`;
   const headers: Record<string, string> = {
     "Content-Type": "application/json",
   };

package/corpus/templates/clips/changelog/2026-06-24-chrome-extension-setup-now-shows-a-clear-all-done-confirmati.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-06-24
+---
+
+Chrome extension setup now shows a clear all-done confirmation when permissions are ready.

package/corpus/templates/clips/chrome-extension/src/permission.html

@@ -52,6 +52,9 @@
       * {
         box-sizing: border-box;
       }
+      [hidden] {
+        display: none !important;
+      }
       body {
         margin: 0;
         min-height: 100vh;
@@ -143,6 +146,45 @@
         color: var(--fg-subtle);
         font-size: 12px;
       }
+      .success-state {
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        gap: 10px;
+        margin-top: -4px;
+        padding: 18px 16px;
+        border: 1px solid var(--status-ok);
+        border-radius: var(--radius-sm);
+        background: rgba(34, 197, 94, 0.1);
+        text-align: center;
+      }
+      .success-icon {
+        display: inline-flex;
+        width: 58px;
+        height: 58px;
+        align-items: center;
+        justify-content: center;
+        border: 2px solid var(--status-ok);
+        border-radius: 50%;
+        background: var(--bg);
+        color: var(--status-ok);
+      }
+      .success-icon svg {
+        width: 32px;
+        height: 32px;
+      }
+      .success-title {
+        margin: 0;
+        color: var(--fg);
+        font-size: 18px;
+        font-weight: 700;
+        line-height: 1.2;
+      }
+      .success-copy {
+        margin: 0;
+        color: var(--fg-muted);
+        font-size: 13.5px;
+      }
       button {
         font: inherit;
         appearance: none;
@@ -219,6 +261,24 @@
           >
         </div>
       </div>
+      <div class="success-state" id="success-state" role="status" hidden>
+        <div class="success-icon" aria-hidden="true">
+          <svg
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2.4"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+          >
+            <path d="M20 6 9 17l-5-5" />
+          </svg>
+        </div>
+        <div class="success-title" id="success-title">You're all done</div>
+        <p class="success-copy" id="success-copy">
+          You can close this tab and start recording from the Clips icon.
+        </p>
+      </div>
       <button id="enable">Enable camera &amp; microphone</button>
       <div class="status" id="status"></div>
     </div>

package/corpus/templates/clips/chrome-extension/src/permission.ts

@@ -7,6 +7,11 @@
 
 const enableBtn = document.getElementById("enable") as HTMLButtonElement;
 const statusEl = document.getElementById("status") as HTMLDivElement;
+const successEl = document.getElementById("success-state") as HTMLDivElement;
+const successTitle = document.getElementById("success-title") as HTMLDivElement;
+const successCopy = document.getElementById(
+  "success-copy",
+) as HTMLParagraphElement;
 const rowMic = document.getElementById("row-mic") as HTMLDivElement;
 const rowCam = document.getElementById("row-cam") as HTMLDivElement;
 const checkMic = document.getElementById("check-mic") as HTMLSpanElement;
@@ -20,6 +25,25 @@ function setStatus(text: string, isError = false): void {
   statusEl.classList.toggle("error", isError);
 }
 
+function showEnableButton(text: string, disabled: boolean): void {
+  enableBtn.hidden = false;
+  enableBtn.textContent = text;
+  enableBtn.disabled = disabled;
+  successEl.hidden = true;
+}
+
+function showSuccess(title: string): void {
+  enableBtn.hidden = true;
+  enableBtn.disabled = true;
+  successTitle.textContent = title;
+  successCopy.textContent =
+    "You can close this tab and start recording from the Clips icon.";
+  successEl.hidden = false;
+  setStatus(
+    "Chrome still asks you what to share before each recording starts.",
+  );
+}
+
 function markRow(kind: "mic" | "cam", granted: boolean): void {
   const row = kind === "mic" ? rowMic : rowCam;
   const check = kind === "mic" ? checkMic : checkCam;
@@ -59,16 +83,9 @@ function finish(camOk: boolean, micOk: boolean): void {
   markRow("mic", micOk);
   markRow("cam", camOk);
   if (camOk || micOk) {
-    enableBtn.textContent = "All set — you can close this tab";
-    enableBtn.disabled = true;
-    setStatus(
-      camOk && micOk
-        ? "Camera and microphone are ready. Click the Clips icon to record."
-        : "Saved. Click the Clips icon to record.",
-    );
+    showSuccess(camOk && micOk ? "You're all done" : "Saved");
   } else {
-    enableBtn.disabled = false;
-    enableBtn.textContent = "Try again";
+    showEnableButton("Try again", false);
     setStatus(
       "Access was blocked. Click the camera icon in Chrome's address bar to allow it, then try again.",
       true,
@@ -77,7 +94,7 @@ function finish(camOk: boolean, micOk: boolean): void {
 }
 
 async function enable(): Promise<void> {
-  enableBtn.disabled = true;
+  showEnableButton(enableBtn.textContent ?? "Enable camera & microphone", true);
   setStatus("Waiting for Chrome's permission prompt…");
   // Request separately so a camera denial doesn't also block the microphone.
   const micOk = await requestOne("mic");
@@ -96,10 +113,6 @@ void (async () => {
   markRow("mic", mic === "granted");
   markRow("cam", cam === "granted");
   if (cam === "granted" && mic === "granted") {
-    enableBtn.textContent = "Already enabled — you can close this tab";
-    enableBtn.disabled = true;
-    setStatus(
-      "Camera and microphone are ready. Click the Clips icon to record.",
-    );
+    showSuccess("You're all done");
   }
 })();

package/corpus/templates/content/app/components/editor/DocumentProperties.tsx

@@ -2349,7 +2349,6 @@ export function AddProperty({
     },
   });
   const [open, setOpen] = useState(false);
-  const [name, setName] = useState("");
   const [typeQuery, setTypeQuery] = useState("");
   const filteredPropertyTypes = filterDocumentPropertyTypes(typeQuery);
   const firstFilteredPropertyType = filteredPropertyTypes[0] ?? null;
@@ -2377,19 +2376,18 @@ export function AddProperty({
         }),
     }))
     .filter((group) => group.fields.length > 0);
-  const addPropertyNameInputRef = useRef<HTMLInputElement>(null);
+  const addPropertySearchInputRef = useRef<HTMLInputElement>(null);
 
   useEffect(() => {
     if (!open) return;
     const frame = requestAnimationFrame(() => {
-      addPropertyNameInputRef.current?.focus();
-      addPropertyNameInputRef.current?.select();
+      addPropertySearchInputRef.current?.focus();
+      addPropertySearchInputRef.current?.select();
     });
     return () => cancelAnimationFrame(frame);
   }, [open]);
 
   function closeAddPropertyPicker() {
-    setName("");
     setTypeQuery("");
     setOpen(false);
   }
@@ -2398,7 +2396,7 @@ export function AddProperty({
     const label = DOCUMENT_PROPERTY_TYPE_LABELS[type];
     await configure.mutateAsync({
       documentId,
-      name: name.trim() || label,
+      name: label,
       type,
       options: defaultPropertyOptions(type),
     });
@@ -2445,23 +2443,11 @@ export function AddProperty({
         className="w-80 p-2"
       >
         <div className="grid gap-2">
-          <Input
-            ref={addPropertyNameInputRef}
-            aria-label="New property name"
-            autoFocus
-            value={name}
-            placeholder="Property name"
-            onChange={(event) => setName(event.target.value)}
-            onKeyDown={(event) => {
-              if (event.key === "Escape") {
-                event.preventDefault();
-                closeAddPropertyPicker();
-              }
-            }}
-          />
           <div className="flex h-8 items-center gap-1 rounded border border-border bg-background px-2">
             <IconSearch className="size-3.5 shrink-0 text-muted-foreground" />
             <Input
+              ref={addPropertySearchInputRef}
+              autoFocus
               value={typeQuery}
               placeholder="Search property types"
               aria-label="Search property types"

package/corpus/templates/plan/.agents/skills/visual-plan/references/wireframe.md

@@ -64,6 +64,13 @@ themes. For any inline border, background, or text color, reference a token:
 and `--wf-radius`. Never hard-code a hex color and never set `font-family` — the
 renderer owns the sketch/clean font.
 
+**Use literal CSS lengths for spacing.** The `--wf-*` tokens are for colors and
+renderer-owned visual styling, not layout spacing. Do not use guessed spacing
+tokens such as `var(--wf-space-4)`, Tailwind spacing classes, or theme spacing
+variables inside wireframe HTML; if a token is unavailable in the Plan renderer,
+padding collapses and content hugs the border. Use explicit CSS lengths for
+layout: `padding:16px`, `gap:12px`, `margin-top:18px`, `minmax(0,1fr)`.
+
 **Lay out with inline `style` flex/grid.** You write the real layout —
 `display:flex; flex-direction:column; gap:10px; padding:16px` and so on — and the
 renderer never repositions anything. Compose the actual product: reproduce the
@@ -148,10 +155,21 @@ check/serve or verify command for `<plan-dir>`.
 **Treat the wireframe border as part of the visible design.** Always wrap HTML
 wireframe content in a root container with real inner padding before drawing
 cards, fields, pills, labels, or controls. Use at least 14-16px of padding,
-`box-sizing: border-box`, `height: 100%`, and `gap` between child rows so the
-first row never sits flush against the screen border. Keep text away from
-borders: every container, field, button, menu item, and annotation needs enough
-padding and line-height to read cleanly in the rendered Plan view.
+`box-sizing: border-box`, `height: 100%`, and `gap` between child rows on the
+root node itself so the first row never sits flush against the screen border. Do
+not rely on padding on a nested page section as the first visible inset; the
+outermost element must create the breathing room. Keep text away from borders:
+every container, field, button, menu item, and annotation needs enough padding
+and line-height to read cleanly in the rendered Plan view.
+
+**For feature-cloud or abundance visuals, optimize the composition over line-by-line
+reading.** Some marketing/product sections need to feel like a large surface area
+of capability rather than a precise app workflow. In those cases, use one padded
+root with a short headline and a dense, aesthetic cloud of short feature labels,
+chips, rings, or columns. Vary scale and opacity with tokens, cluster by meaning,
+and let many labels be glanceable rather than individually essential. Do not
+force dozens of features into equal cards with long wrapped sentences; that
+usually creates a messy unreadable mockup.
 
 **Lay out children safely so they never collide.** Use HTML flex/grid with
 `gap`, `min-width: 0`, and sensible overflow. Avoid negative margins, absolute

package/corpus/templates/plan/.agents/skills/visual-recap/references/wireframe.md

@@ -64,6 +64,13 @@ themes. For any inline border, background, or text color, reference a token:
 and `--wf-radius`. Never hard-code a hex color and never set `font-family` — the
 renderer owns the sketch/clean font.
 
+**Use literal CSS lengths for spacing.** The `--wf-*` tokens are for colors and
+renderer-owned visual styling, not layout spacing. Do not use guessed spacing
+tokens such as `var(--wf-space-4)`, Tailwind spacing classes, or theme spacing
+variables inside wireframe HTML; if a token is unavailable in the Plan renderer,
+padding collapses and content hugs the border. Use explicit CSS lengths for
+layout: `padding:16px`, `gap:12px`, `margin-top:18px`, `minmax(0,1fr)`.
+
 **Lay out with inline `style` flex/grid.** You write the real layout —
 `display:flex; flex-direction:column; gap:10px; padding:16px` and so on — and the
 renderer never repositions anything. Compose the actual product: reproduce the
@@ -148,10 +155,21 @@ check/serve or verify command for `<plan-dir>`.
 **Treat the wireframe border as part of the visible design.** Always wrap HTML
 wireframe content in a root container with real inner padding before drawing
 cards, fields, pills, labels, or controls. Use at least 14-16px of padding,
-`box-sizing: border-box`, `height: 100%`, and `gap` between child rows so the
-first row never sits flush against the screen border. Keep text away from
-borders: every container, field, button, menu item, and annotation needs enough
-padding and line-height to read cleanly in the rendered Plan view.
+`box-sizing: border-box`, `height: 100%`, and `gap` between child rows on the
+root node itself so the first row never sits flush against the screen border. Do
+not rely on padding on a nested page section as the first visible inset; the
+outermost element must create the breathing room. Keep text away from borders:
+every container, field, button, menu item, and annotation needs enough padding
+and line-height to read cleanly in the rendered Plan view.
+
+**For feature-cloud or abundance visuals, optimize the composition over line-by-line
+reading.** Some marketing/product sections need to feel like a large surface area
+of capability rather than a precise app workflow. In those cases, use one padded
+root with a short headline and a dense, aesthetic cloud of short feature labels,
+chips, rings, or columns. Vary scale and opacity with tokens, cluster by meaning,
+and let many labels be glanceable rather than individually essential. Do not
+force dozens of features into equal cards with long wrapped sentences; that
+usually creates a messy unreadable mockup.
 
 **Lay out children safely so they never collide.** Use HTML flex/grid with
 `gap`, `min-width: 0`, and sensible overflow. Avoid negative margins, absolute

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

@@ -43,8 +43,8 @@ const LazyPlanMarkdownEditor = lazy(() =>
 /**
  * Marker prefix embedded in salvaged "unknown-block" callout bodies by the
  * server-side per-block salvage path in parsePlanContent. The renderer detects
- * this prefix and shows a "Unsupported block" placeholder card rather than a
- * generic callout.
+ * this prefix and shows an invalid-block warning card rather than a generic
+ * callout.
  *
  * Format: `__unknown_block__:<originalType>\n<errorSummary>`
  */
@@ -87,7 +87,7 @@ class BlockErrorBoundary extends Component<
   }
 }
 
-/** Muted "Unsupported block" card for unknown/salvaged/errored blocks. */
+/** Muted warning card for unknown/salvaged/errored blocks. */
 function UnknownBlockPlaceholder({
   blockId,
   originalType,
@@ -103,26 +103,43 @@ function UnknownBlockPlaceholder({
       data-block-id={blockId}
       data-unknown-block-type={originalType}
     >
-      <div className="flex items-start gap-2 rounded-lg border border-plan-line bg-plan-block/40 px-3 py-2.5 text-plan-muted">
+      <div className="flex items-start gap-3 rounded-lg border border-amber-500/30 bg-amber-500/5 px-3.5 py-3 text-plan-muted">
         <IconAlertTriangle className="mt-0.5 size-4 shrink-0 text-amber-500" />
-        <span className="min-w-0 text-sm">
-          <span className="font-medium text-plan-text">
-            Unsupported block: {originalType}
-          </span>
-          <details className="mt-1">
-            <summary className="cursor-pointer text-xs opacity-60 hover:opacity-80">
-              Show details
-            </summary>
-            <pre className="mt-1 max-h-40 overflow-auto whitespace-pre-wrap break-all font-mono text-xs opacity-70">
-              {errorSummary}
-            </pre>
-          </details>
-        </span>
+        <div className="min-w-0 text-sm">
+          <div className="font-medium text-plan-text">
+            Invalid {originalType} block
+          </div>
+          <p className="mt-1 leading-5">
+            This generated block did not match the Plan schema, so it was left
+            out while the rest of the recap stayed visible.
+          </p>
+          {errorSummary && (
+            <details className="mt-2">
+              <summary className="cursor-pointer text-xs opacity-70 hover:opacity-90">
+                Validation details
+              </summary>
+              <pre className="mt-1 max-h-40 overflow-auto whitespace-pre-wrap break-words rounded border border-plan-line bg-plan-bg/60 p-2 font-mono text-xs opacity-80">
+                {errorSummary}
+              </pre>
+            </details>
+          )}
+        </div>
       </div>
     </section>
   );
 }
 
+function parseUnknownBlockMarker(block: PlanBlock) {
+  if (block.type !== "callout") return null;
+  if (!block.data.body.startsWith(UNKNOWN_BLOCK_MARKER)) return null;
+  const rest = block.data.body.slice(UNKNOWN_BLOCK_MARKER.length);
+  const newline = rest.indexOf("\n");
+  return {
+    originalType: newline >= 0 ? rest.slice(0, newline) : rest,
+    errorSummary: newline >= 0 ? rest.slice(newline + 1) : "",
+  };
+}
+
 type PlanBlockViewProps = {
   block: PlanBlock;
   onChange?: (block: PlanBlock) => Promise<void> | void;
@@ -163,6 +180,17 @@ function PlanBlockViewInner({
   planId,
   collabUser,
 }: PlanBlockViewProps) {
+  const unknownBlock = parseUnknownBlockMarker(block);
+  if (unknownBlock) {
+    return (
+      <UnknownBlockPlaceholder
+        blockId={block.id}
+        originalType={unknownBlock.originalType}
+        errorSummary={unknownBlock.errorSummary}
+      />
+    );
+  }
+
   // Registry-first dispatch. If the block type is registered, render through the
   // block registry (`BlockView` → spec `Read`, or in edit mode the spec `Edit`
   // or the schema-driven auto-editor). Unregistered types fall through to the
@@ -230,22 +258,6 @@ function PlanBlockViewInner({
     );
   }
   if (block.type === "callout") {
-    // Detect the server-side per-block salvage marker. The marker starts with a
-    // zero-width-space followed by `__unknown_block__:<type>` to avoid collision
-    // with real callout content (real callouts never start with a ZWSP).
-    if (block.data.body.startsWith(UNKNOWN_BLOCK_MARKER)) {
-      const rest = block.data.body.slice(UNKNOWN_BLOCK_MARKER.length);
-      const newline = rest.indexOf("\n");
-      const originalType = newline >= 0 ? rest.slice(0, newline) : rest;
-      const errorSummary = newline >= 0 ? rest.slice(newline + 1) : "";
-      return (
-        <UnknownBlockPlaceholder
-          blockId={block.id}
-          originalType={originalType}
-          errorSummary={errorSummary}
-        />
-      );
-    }
     return (
       <section className="plan-block plan-callout" data-block-id={block.id}>
         {block.title && <div className="plan-block-label">{block.title}</div>}

package/corpus/templates/plan/changelog/2026-06-24-invalid-generated-recap-blocks-now-show-a-clear-warning-with.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-06-24
+---
+
+Invalid generated recap blocks now show a clear warning with validation details instead of raw block markers.