@agent-native/core 0.88.0 → 0.90.1

package/corpus/templates/content/server/lib/notion.ts

@@ -11,7 +11,7 @@ import {
   runWithRequestContext,
 } from "@agent-native/core/server";
 import { assertAccess } from "@agent-native/core/sharing";
-import { createError, type H3Event } from "h3";
+import { createError, getHeader, setCookie, type H3Event } from "h3";
 
 import { canonicalizeNfm } from "../../shared/nfm.js";
 
@@ -19,6 +19,13 @@ export const NOTION_PROVIDER = "notion";
 export const NOTION_API_BASE = "https://api.notion.com/v1";
 export const NOTION_API_VERSION = "2026-03-11";
 
+// Name of the short-lived HttpOnly cookie that binds an in-flight OAuth
+// flow to the browser session that started it. The callback compares this
+// value against the `n` nonce embedded in `state` (see `encodeState`) and
+// refuses to save tokens on any mismatch or absence — this is the CSRF
+// binding the bare `state` nonce alone did not provide.
+export const NOTION_OAUTH_STATE_COOKIE = "notion_oauth_state";
+
 type NotionTokens = {
   access_token?: string;
   workspace_id?: string;
@@ -77,18 +84,51 @@ function getOrigin(event: H3Event): string {
   return `${proto}://${host}`;
 }
 
-function encodeState(data: Record<string, string>): string {
-  const payload = { ...data, n: crypto.randomBytes(8).toString("hex") };
-  return Buffer.from(JSON.stringify(payload)).toString("base64url");
+/**
+ * Mirrors the `isSecureRequest`/proto-sniffing convention used elsewhere in
+ * this app (see `public-documents.ts`, and `plan`'s `public-plans.ts`):
+ * prefer `x-forwarded-proto` (set by the hosting proxy in production), then
+ * fall back to the `origin` header's scheme, defaulting to insecure. A
+ * hardcoded `secure: true` here would make browsers silently drop the
+ * cookie on any plain-http origin (Safari does this even for
+ * `http://localhost`), making `buildNotionAuthUrl`'s CSRF-binding cookie
+ * never arrive and Connect Notion permanently fail in http dev.
+ */
+function isSecureRequest(event: H3Event): boolean {
+  const proto =
+    getHeader(event, "x-forwarded-proto") ??
+    (getHeader(event, "origin")?.startsWith("https://") ? "https" : "http");
+  return proto === "https";
+}
+
+function getStateSecret(): string | null {
+  return (
+    process.env.NOTION_STATE_SECRET ||
+    process.env.BETTER_AUTH_SECRET ||
+    process.env.AUTH_SECRET ||
+    null
+  );
 }
 
-function decodeState(stateParam: string | undefined): Record<string, string> {
-  if (!stateParam) return {};
-  try {
-    return JSON.parse(Buffer.from(stateParam, "base64url").toString());
-  } catch {
-    return {};
-  }
+/**
+ * Sign `redirectPath` the same way `callback.get.ts`'s `verifyStateSignature`
+ * expects: HMAC-SHA256 over `redirectPath:${redirectPath}`, base64url-encoded.
+ * Without this, the callback's signature check always fails and every OAuth
+ * connect silently drops the user on `/` regardless of where they started —
+ * the `redirect` query param threaded through `auth-url.get.ts` was a no-op.
+ */
+function signRedirectPath(redirectPath: string): string | null {
+  const secret = getStateSecret();
+  if (!secret) return null;
+  return crypto
+    .createHmac("sha256", secret)
+    .update(`redirectPath:${redirectPath}`)
+    .digest("base64url");
+}
+
+function encodeState(data: Record<string, string>, nonce: string): string {
+  const payload = { ...data, n: nonce };
+  return Buffer.from(JSON.stringify(payload)).toString("base64url");
 }
 
 async function resolveNotionOAuthCredentials(event: H3Event): Promise<{
@@ -114,9 +154,11 @@ async function notionBasicAuthHeader(event: H3Event): Promise<string> {
   const clientId = credentials?.clientId;
   const clientSecret = credentials?.clientSecret;
   if (!clientId || !clientSecret) {
-    throw new Error(
-      "Notion OAuth credentials are not configured. Save NOTION_CLIENT_ID and NOTION_CLIENT_SECRET in settings.",
-    );
+    throw createError({
+      statusCode: 400,
+      statusMessage:
+        "Notion OAuth credentials are not configured. Save NOTION_CLIENT_ID and NOTION_CLIENT_SECRET in settings.",
+    });
   }
   return `Basic ${Buffer.from(`${clientId}:${clientSecret}`).toString("base64")}`;
 }
@@ -291,6 +333,14 @@ export function normalizeNotionPageId(input: string): string {
   throw new Error("Invalid Notion page ID or URL.");
 }
 
+const NOTION_FETCH_TIMEOUT_MS = 15_000;
+// Cap how long we'll sleep in-process honoring a Notion Retry-After header.
+// Notion can legally send arbitrarily large values (e.g. during an outage);
+// sleeping for them would stall a request handler well past the hosted run's
+// wall-clock budget. Anything above the cap surfaces as a normal 429 error
+// instead of blocking.
+const NOTION_RETRY_AFTER_CAP_SECONDS = 5;
+
 export async function notionFetch<T>(
   path: string,
   accessToken: string,
@@ -300,6 +350,7 @@ export async function notionFetch<T>(
   for (let attempt = 0; ; attempt++) {
     const response = await fetch(`${NOTION_API_BASE}${path}`, {
       ...init,
+      signal: init?.signal ?? AbortSignal.timeout(NOTION_FETCH_TIMEOUT_MS),
       headers: {
         Authorization: `Bearer ${accessToken}`,
         "Notion-Version": NOTION_API_VERSION,
@@ -308,9 +359,16 @@ export async function notionFetch<T>(
       },
     });
     if (response.status === 429 && attempt < MAX_RETRIES) {
-      const retryAfter = Number(response.headers.get("retry-after")) || 1;
-      await new Promise((r) => setTimeout(r, Math.max(retryAfter, 1) * 1000));
-      continue;
+      const rawRetryAfter = Number(response.headers.get("retry-after"));
+      const retryAfterSeconds =
+        Number.isFinite(rawRetryAfter) && rawRetryAfter > 0 ? rawRetryAfter : 1;
+      if (retryAfterSeconds <= NOTION_RETRY_AFTER_CAP_SECONDS) {
+        await new Promise((r) => setTimeout(r, retryAfterSeconds * 1000));
+        continue;
+      }
+      // Retry-After exceeds what we're willing to block a request for —
+      // surface the 429 immediately so the caller can record lastError
+      // instead of stalling the handler.
     }
     const body = await response.json().catch(() => null);
     if (!response.ok) {
@@ -521,12 +579,33 @@ export async function buildNotionAuthUrl(
 ): Promise<string> {
   const credentials = await resolveNotionOAuthCredentials(event);
   if (!credentials?.clientId) {
-    throw new Error(
-      "Notion OAuth credentials are not configured. Save NOTION_CLIENT_ID and NOTION_CLIENT_SECRET in settings.",
-    );
+    throw createError({
+      statusCode: 400,
+      statusMessage:
+        "Notion OAuth credentials are not configured. Save NOTION_CLIENT_ID and NOTION_CLIENT_SECRET in settings.",
+    });
   }
   const redirectUri = `${getOrigin(event)}/api/notion/callback`;
-  const state = encodeState({ redirectPath });
+  const nonce = crypto.randomBytes(16).toString("hex");
+  const sig = signRedirectPath(redirectPath);
+  const state = encodeState(
+    sig ? { redirectPath, sig } : { redirectPath },
+    nonce,
+  );
+
+  // Bind this OAuth flow to the browser session that started it. The
+  // callback compares this cookie against the `n` nonce carried in `state`
+  // and refuses to save tokens on any mismatch or absence, closing the CSRF
+  // hole where an attacker could otherwise send a victim their own
+  // completed-but-unfinished OAuth callback URL.
+  setCookie(event, NOTION_OAUTH_STATE_COOKIE, nonce, {
+    httpOnly: true,
+    sameSite: "lax",
+    secure: isSecureRequest(event),
+    path: "/",
+    maxAge: 600,
+  });
+
   const params = new URLSearchParams({
     owner: "user",
     client_id: credentials.clientId,
@@ -537,11 +616,6 @@ export async function buildNotionAuthUrl(
   return `https://api.notion.com/v1/oauth/authorize?${params.toString()}`;
 }
 
-export function getNotionRedirectPath(stateParam: string | undefined): string {
-  const state = decodeState(stateParam);
-  return state.redirectPath || "/";
-}
-
 export async function exchangeNotionCodeForTokens(
   event: H3Event,
   code: string,
@@ -549,6 +623,7 @@ export async function exchangeNotionCodeForTokens(
   const redirectUri = `${getOrigin(event)}/api/notion/callback`;
   const response = await fetch(`${NOTION_API_BASE}/oauth/token`, {
     method: "POST",
+    signal: AbortSignal.timeout(NOTION_FETCH_TIMEOUT_MS),
     headers: {
       Authorization: await notionBasicAuthHeader(event),
       "Content-Type": "application/json",
@@ -580,6 +655,20 @@ export async function saveNotionTokensForOwner(
     tokens as Record<string, unknown>,
     owner,
   );
+
+  // Enforce single-connection semantics: the UI/action model (and
+  // getNotionConnectionForOwner below) assume one Notion workspace per
+  // owner. Without this, connecting a second workspace leaves two rows and
+  // getNotionConnectionForOwner's `accounts[0]` pick becomes arbitrary DB row
+  // order instead of "most recently connected". Clean up any other Notion
+  // accounts this owner holds so the one just saved is unambiguously active.
+  const accounts = await listOAuthAccountsByOwner(NOTION_PROVIDER, owner);
+  await Promise.all(
+    accounts
+      .filter((account) => account.accountId !== accountId)
+      .map((account) => deleteOAuthTokens(NOTION_PROVIDER, account.accountId)),
+  );
+
   return accountId;
 }
 
@@ -590,40 +679,115 @@ export interface NotionComment {
   rich_text: Array<{ plain_text: string }>;
   created_time: string;
   created_by: { id: string };
-}
-
-/** List open comments on a Notion page. */
+  // Notion groups a top-level comment and all of its replies under the same
+  // discussion_id. Creating a comment WITH this id (instead of a `parent`
+  // page reference) appends it as a reply to that thread rather than
+  // starting a new unrelated top-level comment — this is what
+  // sync-notion-comments uses to preserve reply threading in both
+  // directions.
+  discussion_id?: string;
+}
+
+const MAX_COMMENT_PAGES = 20;
+
+/**
+ * List open comments on a Notion page. The endpoint is cursor-paginated
+ * (max 100 results per page); this follows `has_more`/`next_cursor` until
+ * exhausted (capped at MAX_COMMENT_PAGES as a safety bound) so pages with
+ * more than one page of comments don't silently lose the remainder.
+ *
+ * Auth/permission/rate-limit failures (401/403/404/429) are rethrown rather
+ * than swallowed into an empty array — callers (sync-notion-comments) need
+ * to distinguish "no comments" from "the API call failed" so they don't
+ * report a broken sync as a successful no-op.
+ */
 export async function listNotionComments(
   pageId: string,
   accessToken: string,
 ): Promise<NotionComment[]> {
-  try {
-    const data = await notionFetch<{ results?: NotionComment[] }>(
-      `/comments?block_id=${pageId}`,
-      accessToken,
-    );
-    return data.results ?? [];
-  } catch {
-    return [];
+  const results: NotionComment[] = [];
+  let cursor: string | undefined;
+  for (let page = 0; page < MAX_COMMENT_PAGES; page++) {
+    try {
+      const query = new URLSearchParams({ block_id: pageId, page_size: "100" });
+      if (cursor) query.set("start_cursor", cursor);
+      const data = await notionFetch<{
+        results?: NotionComment[];
+        has_more?: boolean;
+        next_cursor?: string | null;
+      }>(`/comments?${query.toString()}`, accessToken);
+      results.push(...(data.results ?? []));
+      if (!data.has_more || !data.next_cursor) break;
+      cursor = data.next_cursor;
+    } catch (error) {
+      if (
+        error instanceof NotionApiError &&
+        [401, 403, 404, 429].includes(error.status)
+      ) {
+        throw error;
+      }
+      // Unexpected shape on a page we've already partially fetched — return
+      // what we have rather than losing already-fetched comments.
+      if (results.length > 0) break;
+      throw error;
+    }
   }
+  return results;
 }
 
-/** Add a comment to a Notion page. */
+export type AddedNotionComment = {
+  id: string;
+  discussionId: string | null;
+};
+
+/**
+ * Add a comment to a Notion page, or a reply to an existing discussion
+ * thread when `discussionId` is provided. Passing `discussion_id` (instead
+ * of a `parent` page reference) is what makes Notion append the comment to
+ * that thread as a reply rather than starting a new, unrelated top-level
+ * comment — see sync-notion-comments.ts for how local comment replies map
+ * to a stored `notion_discussion_id`.
+ *
+ * Auth/permission/rate-limit failures (401/403/404/429) are rethrown so
+ * sync-notion-comments can surface a real error instead of silently
+ * reporting the comment as pushed.
+ */
 export async function addNotionComment(
   pageId: string,
   text: string,
   accessToken: string,
-): Promise<string | null> {
+  discussionId?: string | null,
+): Promise<AddedNotionComment | null> {
   try {
-    const data = await notionFetch<{ id?: string }>("/comments", accessToken, {
-      method: "POST",
-      body: JSON.stringify({
-        parent: { page_id: pageId },
-        rich_text: [{ text: { content: text } }],
-      }),
-    });
-    return data.id ?? null;
-  } catch {
+    const body = discussionId
+      ? {
+          discussion_id: discussionId,
+          rich_text: [{ text: { content: text } }],
+        }
+      : {
+          parent: { page_id: pageId },
+          rich_text: [{ text: { content: text } }],
+        };
+    const data = await notionFetch<{ id?: string; discussion_id?: string }>(
+      "/comments",
+      accessToken,
+      {
+        method: "POST",
+        body: JSON.stringify(body),
+      },
+    );
+    if (!data.id) return null;
+    return {
+      id: data.id,
+      discussionId: data.discussion_id ?? discussionId ?? null,
+    };
+  } catch (error) {
+    if (
+      error instanceof NotionApiError &&
+      [401, 403, 404, 429].includes(error.status)
+    ) {
+      throw error;
+    }
     return null;
   }
 }

package/corpus/templates/content/server/plugins/db.ts

@@ -596,6 +596,26 @@ const runContentMigrations = runMigrations(
         CREATE UNIQUE INDEX IF NOT EXISTS content_database_body_hydration_queue_item_idx ON content_database_body_hydration_queue (database_item_id);
         CREATE INDEX IF NOT EXISTS content_database_items_body_hydration_idx ON content_database_items (database_id, body_hydration_status)`,
     },
+    {
+      version: 61,
+      name: "document-sync-links-claim-column",
+      // Best-effort cross-instance serialization for Notion pull/push: a
+      // conditional UPDATE claims this column before making Notion API calls
+      // so two concurrent syncs for the same document (different tabs,
+      // different serverless instances) don't race Notion mutations against
+      // each other. See server/lib/notion-sync.ts's use of this column.
+      sql: `ALTER TABLE document_sync_links ADD COLUMN IF NOT EXISTS sync_claimed_at TEXT`,
+    },
+    {
+      version: 62,
+      name: "document-comments-notion-discussion-id-column",
+      // Notion groups a top-level comment and its replies under one
+      // discussion_id. Storing it locally lets sync-notion-comments create
+      // replies with `discussion_id` (instead of `parent`) so they thread
+      // under the existing Notion discussion in both directions instead of
+      // becoming unrelated top-level comments. See actions/sync-notion-comments.ts.
+      sql: `ALTER TABLE document_comments ADD COLUMN IF NOT EXISTS notion_discussion_id TEXT`,
+    },
   ],
   { table: "content_migrations" },
 );

package/corpus/templates/content/server/routes/api/documents/[id]/notion/resolve.post.ts

@@ -1,5 +1,5 @@
 import { readBody } from "@agent-native/core/server";
-import { defineEventHandler } from "h3";
+import { createError, defineEventHandler } from "h3";
 
 import { resolveDocumentSyncConflict } from "../../../../../lib/notion-sync.js";
 import { getDocumentOwnerEmail } from "../../../../../lib/notion.js";
@@ -7,6 +7,18 @@ import { getDocumentOwnerEmail } from "../../../../../lib/notion.js";
 export default defineEventHandler(async (event) => {
   const id = event.context.params!.id;
   const body = await readBody(event);
+  const direction = body?.direction;
+  // resolveDocumentSyncConflict treats anything other than the literal
+  // "pull" as "push" (a destructive force-push). Validate here so a missing
+  // or misspelled field (e.g. `{ dir: "pull" }`) 400s instead of silently
+  // overwriting the Notion page. The action counterpart already enforces
+  // this via z.enum(["pull", "push"]).
+  if (direction !== "pull" && direction !== "push") {
+    throw createError({
+      statusCode: 400,
+      statusMessage: "direction must be 'pull' or 'push'",
+    });
+  }
   const owner = await getDocumentOwnerEmail(event, id);
-  return resolveDocumentSyncConflict(owner, id, body.direction);
+  return resolveDocumentSyncConflict(owner, id, direction);
 });

package/corpus/templates/content/server/routes/api/notion/callback.get.ts

@@ -18,11 +18,23 @@
  *      through a same-origin path-only check (modeled on
  *      `safeReturnPath`) before being passed to `sendRedirect` — so a
  *      protocol-relative URL like `//host/evil` falls back to `/`.
+ *
+ * Separately, before ANY token exchange/save happens, this handler verifies
+ * the `notion_oauth_state` HttpOnly cookie set by `buildNotionAuthUrl`
+ * matches the `n` nonce carried in `state`. Without this check the random
+ * nonce in `state.n` is generated but never verified against anything, so
+ * an attacker can start their own OAuth flow, capture the resulting
+ * callback URL, and get a logged-in victim to visit it — silently binding
+ * the victim's account to the attacker's Notion workspace. A missing or
+ * mismatched cookie aborts before exchanging the code or saving tokens.
  */
 import crypto from "node:crypto";
 
+import { OAuthAccountOwnedByOtherUserError } from "@agent-native/core/oauth-tokens";
 import {
   defineEventHandler,
+  deleteCookie,
+  getCookie,
   getQuery,
   sendRedirect,
   setResponseStatus,
@@ -31,6 +43,7 @@ import {
 import {
   exchangeNotionCodeForTokens,
   getDocumentOwnerEmail,
+  NOTION_OAUTH_STATE_COOKIE,
   saveNotionTokensForOwner,
 } from "../../../lib/notion.js";
 
@@ -124,14 +137,49 @@ export default defineEventHandler(async (event) => {
     return { error: "Missing authorization code" };
   }
 
-  const owner = await getDocumentOwnerEmail(event);
-  const tokens = await exchangeNotionCodeForTokens(event, code);
-  await saveNotionTokensForOwner(owner, tokens);
-
-  // Decide where to redirect AFTER the token swap. Default to `/` on any
-  // signature failure so a forged state never produces an open redirect.
+  // Decode state up front so we know the (verified, if signed) redirect
+  // target regardless of how the rest of the handler exits.
   const state = decodeStateJson(stateParam);
   const verified = verifyStateSignature(state);
   const target = verified.ok ? safeReturnPathLocal(verified.redirectPath) : "/";
+
+  // CSRF binding: the nonce in `state.n` must match the HttpOnly cookie set
+  // by buildNotionAuthUrl for the session that started this flow. Reject
+  // (without exchanging the code or saving any token) on a missing or
+  // mismatched cookie — do NOT fall back to accepting when the cookie is
+  // absent, that would reopen the hole entirely.
+  const cookieNonce = getCookie(event, NOTION_OAUTH_STATE_COOKIE);
+  const stateNonce = typeof state.n === "string" ? state.n : null;
+  deleteCookie(event, NOTION_OAUTH_STATE_COOKIE, { path: "/" });
+  if (!cookieNonce || !stateNonce) {
+    setResponseStatus(event, 400);
+    return { error: "Invalid OAuth state" };
+  }
+  const cookieBuf = Buffer.from(cookieNonce);
+  const stateBuf = Buffer.from(stateNonce);
+  if (
+    cookieBuf.length !== stateBuf.length ||
+    !crypto.timingSafeEqual(cookieBuf, stateBuf)
+  ) {
+    setResponseStatus(event, 400);
+    return { error: "Invalid OAuth state" };
+  }
+
+  const owner = await getDocumentOwnerEmail(event);
+  const tokens = await exchangeNotionCodeForTokens(event, code);
+  try {
+    await saveNotionTokensForOwner(owner, tokens);
+  } catch (err) {
+    if (err instanceof OAuthAccountOwnedByOtherUserError) {
+      const separator = target.includes("?") ? "&" : "?";
+      return sendRedirect(
+        event,
+        `${target}${separator}notionError=account_linked_to_other_user`,
+        302,
+      );
+    }
+    throw err;
+  }
+
   return sendRedirect(event, target, 302);
 });

package/corpus/templates/content/shared/builder-mdx.ts

@@ -7,6 +7,11 @@ import type {
   BuilderTabbedContentData,
   BuilderTextData,
 } from "./builder-docs-blocks";
+import {
+  builderSourceComponentMappingFor,
+  type BuilderSourceComponentMapping,
+  unknownBuilderSourceComponentMappingFor,
+} from "./builder-source-component-registry";
 import {
   parseRegistryBlockData,
   serializeRegistryBlockToMdx,
@@ -386,6 +391,12 @@ function childBlocks(block: unknown): unknown[] {
   return Array.isArray(block.children) ? block.children : [];
 }
 
+function shouldReadThroughBuilderChildren(componentName: string | null) {
+  return (
+    builderSourceComponentMappingFor(componentName).mappingStatus === "unknown"
+  );
+}
+
 function isReadableUnsupportedBuilderPlaceholder(value: string) {
   const trimmed = value.trim();
   return (
@@ -504,7 +515,7 @@ async function expectedReadableLayoutFingerprint(blocks: unknown[]) {
       continue;
     }
     const children = childBlocks(block);
-    if (children.length && children.some(builderBlockHasReadableOutput)) {
+    if (shouldReadThroughBuilderChildren(name) && children.length) {
       fingerprint.push(...(await expectedReadableLayoutFingerprint(children)));
       continue;
     }
@@ -786,6 +797,7 @@ function pluralize(count: number, singular: string) {
 
 function builderSourceComponentPreview(
   block: unknown,
+  mapping: BuilderSourceComponentMapping,
 ): Pick<
   SourceComponentData,
   "previewKind" | "previewUrl" | "previewItems" | "preview" | "summary"
@@ -830,7 +842,7 @@ function builderSourceComponentPreview(
       summary,
     };
   }
-  if (name === "Table" || name?.toLowerCase().includes("table")) {
+  if (mapping.id === "builder-table-preserved") {
     const shape = tableShapeFromOptions(options);
     const items = shape
       ? [pluralize(shape.rows, "row"), pluralize(shape.columns, "column")]
@@ -883,12 +895,14 @@ function builderSourceComponentPreview(
     };
   }
   const summary = blockSummary(block);
+  const previewStatus =
+    mapping.mappingStatus === "unknown" ? "warning" : "available";
   return {
     previewKind: "component",
     preview: {
-      status: name ? "available" : "unavailable",
+      status: name ? previewStatus : "unavailable",
       kind: "component",
-      label: name ? `Builder ${name}` : "Builder component",
+      label: mapping.label,
       summary,
     },
     summary,
@@ -1075,6 +1089,23 @@ async function builderBlockToMdx(
     });
   }
 
+  const mapping = builderSourceComponentMappingFor(name);
+  if (mapping.mappingStatus === "preserved") {
+    const data: BuilderRawBlockData = {
+      ...raw,
+      summary: blockSummary(block),
+    };
+    if (childBlocks(block).length) {
+      ctx.warnings.push(
+        `${mapping.label} has child blocks that are preserved only in the raw sidecar.`,
+      );
+    }
+    return serializeRegistryBlockToMdx("builder-raw-block", {
+      id,
+      data,
+    });
+  }
+
   const children = childBlocks(block);
   if (children.length) {
     const childBody = await builderBlocksToMdxBody(children, ctx);
@@ -1104,6 +1135,7 @@ async function builderBlockToReadableMdx(
 ) {
   const name = componentName(block);
   const options = componentOptions(block);
+  const mapping = builderSourceComponentMappingFor(name);
 
   if (name === "Text") {
     return htmlToMarkdown(String(options.text ?? "")).trim();
@@ -1140,14 +1172,19 @@ async function builderBlockToReadableMdx(
   }
 
   const children = childBlocks(block);
-  if (children.length) {
+  if (shouldReadThroughBuilderChildren(name) && children.length) {
     const childBody = await builderBlocksToReadableMdxBody(children, ctx);
     if (childBody) return childBody;
   }
 
+  const markerMapping =
+    mapping.readableMode === "editable-markdown"
+      ? unknownBuilderSourceComponentMappingFor(name)
+      : mapping;
+
   if (name) {
     ctx.warnings.push(
-      `${name} is preserved in the Builder raw sidecar and shown as a read-only source component.`,
+      `${markerMapping.label} is preserved in the Builder raw sidecar and shown as a read-only source component.`,
     );
   }
   const data: SourceComponentData = {
@@ -1156,9 +1193,20 @@ async function builderBlockToReadableMdx(
     rawRef,
     rawHash: stableHash(block),
     sourceLabel: "Builder body",
-    previewStatus: name ? "available" : "unavailable",
-    title: name ? `Builder ${name}` : "Builder component",
-    ...builderSourceComponentPreview(block),
+    mappingId: markerMapping.id,
+    mappingStatus: markerMapping.mappingStatus,
+    mappingReason: markerMapping.reason,
+    sourceEditState: markerMapping.sourceEditState,
+    previewStatus:
+      markerMapping.mappingStatus === "unknown"
+        ? name
+          ? "warning"
+          : "unavailable"
+        : name
+          ? "available"
+          : "unavailable",
+    title: markerMapping.label,
+    ...builderSourceComponentPreview(block, markerMapping),
   };
   const id = sourceComponentMarkerIdForBlock(block);
   return serializeRegistryBlockToMdx("source-component", { id, data });
@@ -1262,7 +1310,9 @@ function collectReadableEditableSegments(
       }
       continue;
     }
-    collectReadableEditableSegments(childBlocks(block), segments);
+    if (shouldReadThroughBuilderChildren(name)) {
+      collectReadableEditableSegments(childBlocks(block), segments);
+    }
   }
   return segments;
 }
@@ -1289,7 +1339,9 @@ function builderBlockHasReadableOutput(block: unknown): boolean {
     });
   }
   const children = childBlocks(block);
-  return children.length ? children.some(builderBlockHasReadableOutput) : true;
+  return shouldReadThroughBuilderChildren(name) && children.length
+    ? children.some(builderBlockHasReadableOutput)
+    : true;
 }
 
 function countExpectedReadableSourceComponentMarkers(
@@ -1318,7 +1370,11 @@ function countExpectedReadableSourceComponentMarkers(
       continue;
     }
     const children = childBlocks(block);
-    if (children.length && children.some(builderBlockHasReadableOutput)) {
+    if (
+      shouldReadThroughBuilderChildren(name) &&
+      children.length &&
+      children.some(builderBlockHasReadableOutput)
+    ) {
       count += countExpectedReadableSourceComponentMarkers(children);
       continue;
     }