@open-press/core 0.7.1 → 0.8.0

package/engine/commands/dev.mjs

@@ -16,7 +16,7 @@ export async function run({ root, options }) {
     if (!options.noBuild) {
       console.log(`Command: ${formatNodeScriptCommand(root, CLI_ENTRY)} export .`);
     }
-    console.log(`Command: npx vite --config vite.config.ts --host ${host} --port ${port}`);
+    console.log(`Command: npx vite --force --config vite.config.ts --host ${host} --port ${port}`);
     return 0;
   }
   if (!options.noBuild) {
@@ -27,7 +27,7 @@ export async function run({ root, options }) {
   await printDoctorNoticeIfStale(root);
 
   console.log(`OpenPress dev: ${url}`);
-  return runCommand("npx", ["vite", "--config", "vite.config.ts", "--host", host, "--port", port], root);
+  return runCommand("npx", ["vite", "--force", "--config", "vite.config.ts", "--host", host, "--port", port], root);
 }
 
 async function printDoctorNoticeIfStale(root) {

package/engine/output/chrome-pdf.mjs

@@ -91,6 +91,13 @@ const DEFAULT_PRINT_OPTIONS = {
   marginLeft: 0,
 };
 
+export const DEFAULT_PRINT_VIEWPORT = Object.freeze({
+  width: 1200,
+  height: 1698,
+  deviceScaleFactor: 1,
+  mobile: false,
+});
+
 export async function printUrlToPdf({
   root,
   url,
@@ -98,6 +105,7 @@ export async function printUrlToPdf({
   chrome,
   waitForReady = waitForPrintReady,
   printOptions = {},
+  viewport = DEFAULT_PRINT_VIEWPORT,
   debuggingPortBase = 9600,
   debuggingPortRange = 300,
   profilePrefix = "chrome-pdf",
@@ -126,9 +134,7 @@ export async function printUrlToPdf({
     const tab = await waitForChromeTab(debuggingPort);
     const client = await connectChromeDevTools(tab.webSocketDebuggerUrl);
     try {
-      await client.send("Page.enable");
-      await client.send("Runtime.enable");
-      await client.send("Emulation.setEmulatedMedia", { media: "print" });
+      await preparePdfPage(client, { viewport });
       await client.send("Page.navigate", { url });
       const readyResult = await waitForReady(client);
       const result = await client.send("Page.printToPDF", {
@@ -146,6 +152,15 @@ export async function printUrlToPdf({
   }
 }
 
+export async function preparePdfPage(client, { viewport = DEFAULT_PRINT_VIEWPORT } = {}) {
+  await client.send("Page.enable");
+  await client.send("Runtime.enable");
+  if (viewport) {
+    await client.send("Emulation.setDeviceMetricsOverride", viewport);
+  }
+  await client.send("Emulation.setEmulatedMedia", { media: "print" });
+}
+
 export async function evaluateUrlWithChrome({
   root,
   url,

package/engine/output/static-server.mjs

@@ -3,7 +3,9 @@ import http from "node:http";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { loadConfig, publicPdfHref } from "../runtime/config.mjs";
+import { searchSourceText } from "../runtime/source-text-tools.mjs";
 import { handleProjectAssetRequest } from "../react/project-asset-endpoint.mjs";
+import { handleSourceEditRequest } from "../react/source-edit-endpoint.mjs";
 
 const [rootArg = "dist", ...rest] = process.argv.slice(2);
 const host = valueAfter(rest, "--host") ?? "127.0.0.1";
@@ -32,6 +34,14 @@ const server = http.createServer(async (req, res) => {
       await handleStatusRequest(req, res);
       return;
     }
+    if (url.pathname === "/__openpress/search") {
+      await handleSearchRequest(req, res, url);
+      return;
+    }
+    if (url.pathname === "/__openpress/source-edit") {
+      await handleSourceEditRequest(req, res, { root: workspace });
+      return;
+    }
     if (url.pathname === "/__openpress/local-pdf-export") {
       await handleLocalPdfExportRequest(req, res);
       return;
@@ -103,6 +113,35 @@ async function handleStatusRequest(req, res) {
   });
 }
 
+async function handleSearchRequest(req, res, url) {
+  if (req.method !== "GET") {
+    writeJson(res, 405, { ok: false, message: "Search endpoint requires GET." });
+    return;
+  }
+
+  const query = (url.searchParams.get("q") ?? "").trim();
+  if (!query) {
+    writeJson(res, 400, { ok: false, message: "Search query is required." });
+    return;
+  }
+
+  try {
+    const report = await searchSourceText({
+      config,
+      query,
+      scope: searchScopeFrom(url),
+      caseSensitive: url.searchParams.get("caseSensitive") === "true",
+    });
+    writeJson(res, 200, { ok: true, ...report });
+  } catch (error) {
+    writeJson(res, 500, { ok: false, message: error instanceof Error ? error.message : String(error) });
+  }
+}
+
+function searchScopeFrom(url) {
+  return url.searchParams.get("scope") === "all" ? "all" : "content";
+}
+
 function valueAfter(args, flag) {
   const index = args.indexOf(flag);
   return index >= 0 ? args[index + 1] : undefined;

package/engine/react/comment-endpoint.mjs

@@ -4,8 +4,7 @@ import {
   listCommentMarkers,
   updateCommentMarker,
 } from "./comment-marker.mjs";
-
-const MAX_COMMENT_BODY_BYTES = 64 * 1024;
+import { readJsonBody, writeJson } from "./http-json.mjs";
 
 export async function handleCommentRequest(req, res, {
   root = ".",
@@ -16,17 +15,14 @@ export async function handleCommentRequest(req, res, {
     try {
       writeJson(res, 200, { ok: true, comments: await listCommentMarkers({ root }) });
     } catch (error) {
-      writeJson(res, 400, {
-        ok: false,
-        message: error instanceof Error ? error.message : String(error),
-      });
+      writeErrorJson(res, error);
     }
     return;
   }
 
   if (req.method === "DELETE") {
     try {
-      const body = await readJsonBody(req);
+      const body = await readJsonBody(req, { bodyLabel: "OpenPress comment request" });
       const result = await clearCommentMarkers({
         root,
         id: body?.id,
@@ -34,17 +30,14 @@ export async function handleCommentRequest(req, res, {
       });
       writeJson(res, 200, { ok: true, ...result });
     } catch (error) {
-      writeJson(res, 400, {
-        ok: false,
-        message: error instanceof Error ? error.message : String(error),
-      });
+      writeErrorJson(res, error);
     }
     return;
   }
 
   if (req.method === "PATCH") {
     try {
-      const body = await readJsonBody(req);
+      const body = await readJsonBody(req, { bodyLabel: "OpenPress comment request" });
       const result = await updateCommentMarker({
         root,
         id: body?.id,
@@ -64,10 +57,7 @@ export async function handleCommentRequest(req, res, {
         },
       });
     } catch (error) {
-      writeJson(res, 400, {
-        ok: false,
-        message: error instanceof Error ? error.message : String(error),
-      });
+      writeErrorJson(res, error);
     }
     return;
   }
@@ -78,7 +68,7 @@ export async function handleCommentRequest(req, res, {
   }
 
   try {
-    const body = await readJsonBody(req);
+    const body = await readJsonBody(req, { bodyLabel: "OpenPress comment request" });
     const target = body?.target ?? {};
     const result = await insertCommentMarker({
       root,
@@ -100,29 +90,13 @@ export async function handleCommentRequest(req, res, {
       },
     });
   } catch (error) {
-    writeJson(res, 400, {
-      ok: false,
-      message: error instanceof Error ? error.message : String(error),
-    });
-  }
-}
-
-async function readJsonBody(req) {
-  let body = "";
-  for await (const chunk of req) {
-    body += String(chunk);
-    if (Buffer.byteLength(body, "utf8") > MAX_COMMENT_BODY_BYTES) {
-      throw new Error("OpenPress comment request body is too large.");
-    }
-  }
-  try {
-    return JSON.parse(body || "{}");
-  } catch {
-    throw new Error("OpenPress comment request body must be valid JSON.");
+    writeErrorJson(res, error);
   }
 }
 
-function writeJson(res, status, body) {
-  res.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
-  res.end(`${JSON.stringify(body, null, 2)}\n`);
+function writeErrorJson(res, error) {
+  writeJson(res, 400, {
+    ok: false,
+    message: error instanceof Error ? error.message : String(error),
+  });
 }

package/engine/react/comment-marker.mjs

@@ -14,8 +14,8 @@ const EDITABLE_COMMENT_SOURCE_PATTERNS = [
   /^document\/.+\.mdx$/,
   /^document\/.+\.tsx$/,
 ];
-const COMMENT_MARKER_RE = /\{\/\*\s*@openpress-comment\b(?<attrs>[^*]*)\*\/\}/g;
-const COMMENT_LINE_RE = /^\s*\{\/\*\s*@openpress-comment\b[^*]*\*\/\}\s*$/;
+const COMMENT_MARKER_RE = /(?:\{\/\*|\/\*)\s*@openpress-comment\b(?<attrs>[^*]*)\*\/\}?/g;
+const COMMENT_LINE_RE = /^\s*(?:\{\/\*|\/\*)\s*@openpress-comment\b[^*]*\*\/\}?\s*$/;
 
 export async function insertCommentMarker({
   root = ".",
@@ -35,9 +35,15 @@ export async function insertCommentMarker({
   }
 
   const noteText = normalizedNote(note);
-  const marker = createCommentMarker({ id, timestamp, note: noteText, hint });
   const line = normalizeLineNumber(source?.line);
   const text = await fs.readFile(absolutePath, "utf8");
+  const marker = createCommentMarker({
+    id,
+    timestamp,
+    note: noteText,
+    hint,
+    syntax: commentMarkerSyntaxForInsert(text, line, relativePath),
+  });
   const nextText = insertLineBefore(text, line, marker);
   await fs.writeFile(absolutePath, nextText, "utf8");
 
@@ -51,9 +57,10 @@ export async function insertCommentMarker({
   };
 }
 
-export function createCommentMarker({ id = createCommentId(), timestamp = new Date().toISOString(), note, hint } = {}) {
+export function createCommentMarker({ id = createCommentId(), timestamp = new Date().toISOString(), note, hint, syntax = "jsx" } = {}) {
   const payload = { note: normalizedNote(note), ...(typeof hint === "string" && hint.trim() ? { hint: hint.trim() } : {}) };
-  return `{/* @openpress-comment id="${escapeMarkerAttribute(id)}" ts="${escapeMarkerAttribute(timestamp)}" text="${encodeCommentPayload(payload)}" */}`;
+  const body = `@openpress-comment id="${escapeMarkerAttribute(id)}" ts="${escapeMarkerAttribute(timestamp)}" text="${encodeCommentPayload(payload)}"`;
+  return syntax === "block" ? `/* ${body} */` : `{/* ${body} */}`;
 }
 
 export function decodeCommentMarkerText(marker) {
@@ -285,7 +292,7 @@ function replaceCommentMarkerLine(text, { id, note, hint, timestamp }) {
     if (!COMMENT_LINE_RE.test(line)) continue;
     const attrs = parseMarkerAttributes(line);
     if (attrs.id !== id) continue;
-    const marker = createCommentMarker({ id, timestamp, note, hint });
+    const marker = createCommentMarker({ id, timestamp, note, hint, syntax: commentMarkerSyntaxForLine(line) });
     lines[index] = `${line.match(/^\s*/)?.[0] ?? ""}${marker}`;
     return {
       text: `${lines.join(newline)}${hasTrailingNewline ? newline : ""}`,
@@ -311,6 +318,23 @@ function parseMarkerAttributes(value) {
   return attrs;
 }
 
+function commentMarkerSyntaxForInsert(text, line, relativePath) {
+  if (!String(relativePath).endsWith(".tsx")) return "jsx";
+  const lines = String(text ?? "").split(/\r?\n/);
+  const index = Math.min(Math.max(line - 1, 0), lines.length);
+  const priorContent = lines.slice(0, index).some((entry) => entry.trim().length > 0);
+  if (!priorContent) return "block";
+  const targetLine = lines[index] ?? "";
+  if (/^\s*(import\b|export\b|function\b|const\b|let\b|var\b|type\b|interface\b|return\b)/.test(targetLine)) {
+    return "block";
+  }
+  return "jsx";
+}
+
+function commentMarkerSyntaxForLine(line) {
+  return /^\s*\/\*/.test(line) ? "block" : "jsx";
+}
+
 function lineStartOffsets(text) {
   const starts = [0];
   for (let index = 0; index < text.length; index += 1) {

package/engine/react/document-entry.mjs

@@ -68,6 +68,7 @@ export async function createReactSsrServer(workspaceRoot = ".") {
   return createViteServer({
     configFile: false,
     root: FRAMEWORK_ROOT,
+    cacheDir: path.join(resolvedWorkspaceRoot, ".openpress", "vite-ssr"),
     appType: "custom",
     logLevel: "silent",
     plugins: [reactRuntimePlugin(), react()],
@@ -82,6 +83,16 @@ export async function createReactSsrServer(workspaceRoot = ".") {
         { find: "@/components", replacement: path.join(resolvedWorkspaceRoot, "document", "components") },
       ],
     },
+    optimizeDeps: {
+      include: [
+        "@mdx-js/react",
+        "react",
+        "react-dom",
+        "react-dom/server",
+        "react/jsx-dev-runtime",
+        "react/jsx-runtime",
+      ],
+    },
     server: {
       middlewareMode: true,
       fs: {

package/engine/react/document-export.mjs

@@ -12,6 +12,7 @@ import { createCaptionNumberingState, numberCaptionsInHtml } from "./caption-num
 import { buildSectionScopedCss } from "./section-css.mjs";
 import { CORE_ENTRY, createReactSsrServer, loadReactDocumentEntry } from "./document-entry.mjs";
 import { buildReactMeasurementCss } from "./measurement-css.mjs";
+import { buildObjectEntities } from "./object-entities.mjs";
 import { allocateChains } from "./pipeline/allocate.mjs";
 import { measureFrames } from "./pipeline/frame-measurement.mjs";
 import { renderFinalPress } from "./pipeline/final-render.mjs";
@@ -50,7 +51,14 @@ export async function exportReactDocument(root = ".", { syncAssets = true } = {}
 
     // Discover workspace for component scope and chapter-scoped style files.
     const workspace = await discoverSectionStyles(workspaceRoot, entry.config);
-    const globalComponents = await loadComponentModules(server, workspace.globalComponents ?? []);
+    const coreAuthorComponents = {};
+    for (const name of ["MediaFigure", "ImageFigure"]) {
+      if (typeof coreModule[name] === "function") coreAuthorComponents[name] = coreModule[name];
+    }
+    const globalComponents = {
+      ...coreAuthorComponents,
+      ...(await loadComponentModules(server, workspace.globalComponents ?? [])),
+    };
 
     // Resolve sources.
     const documentRoot = entry.config.paths.documentRoot;
@@ -153,9 +161,6 @@ export async function exportReactDocument(root = ".", { syncAssets = true } = {}
     const blockMap = {};
     const captionState = createCaptionNumberingState();
     const blocks = final.frames.map((frame, index) => {
-      for (const id of frame.blockIds) {
-        blockMap[id] = { id, pageIndex: index, pageNumber: index + 1 };
-      }
       const source = {
         file: "index.tsx",
         path: "document/index.tsx",
@@ -164,6 +169,9 @@ export async function exportReactDocument(root = ".", { syncAssets = true } = {}
         sectionIndex: index + 1,
       };
       const html = numberCaptionsInHtml(frame.html, entry.config.captionNumbering, captionState);
+      for (const id of collectFrameBlockIds(frame.blockIds, html)) {
+        blockMap[id] = { id, pageIndex: index, pageNumber: index + 1, frameKey: frame.frameKey };
+      }
       const block = pageToBlock(index, html, source, entry.config, {
         idPrefix: "openpress-page",
         anchorPrefix: "page",
@@ -196,12 +204,18 @@ export async function exportReactDocument(root = ".", { syncAssets = true } = {}
       }
     }
 
+    const objectEntities = buildObjectEntities({
+      frames: final.frames.map((frame, index) => ({ ...frame, pageIndex: index })),
+      blocks,
+      blockMap,
+    });
+
     const readerDocument = {
       meta: {
         title: trimmedString(entry.config.title) ?? "Untitled Document",
         subtitle: trimmedString(entry.config.subtitle) ?? "",
         organization: trimmedString(entry.config.organization) ?? "",
-        workspaceLabel: trimmedString(entry.config.workspaceLabel) ?? trimmedString(entry.config.title) ?? "Untitled Document",
+        workspaceLabel: trimmedString(entry.config.workspaceLabel) ?? "",
         version: "openpress-press-tree-v1",
       },
       source: {
@@ -211,6 +225,7 @@ export async function exportReactDocument(root = ".", { syncAssets = true } = {}
         editMode: "source-mdx",
         styles,
         blockMap,
+        objectEntities,
         frames: final.frames.map((frame, index) => ({
           frameKey: frame.frameKey,
           role: frame.role ?? null,
@@ -296,6 +311,16 @@ function buildSourceBlockIndex(sources) {
   return index;
 }
 
+function collectFrameBlockIds(allocatedIds, html) {
+  const ids = new Set(allocatedIds ?? []);
+  const pattern = /\sdata-openpress-block-id="([^"]+)"/g;
+  let match;
+  while ((match = pattern.exec(String(html ?? "")))) {
+    if (match[1]) ids.add(match[1]);
+  }
+  return ids;
+}
+
 function buildTocContext({ sources, frames, allocation }) {
   const toc = {};
   for (const source of Object.values(sources)) {

package/engine/react/http-json.mjs

@@ -0,0 +1,24 @@
+const DEFAULT_MAX_BODY_BYTES = 64 * 1024;
+
+export async function readJsonBody(req, {
+  maxBytes = DEFAULT_MAX_BODY_BYTES,
+  bodyLabel = "Request",
+} = {}) {
+  let body = "";
+  for await (const chunk of req) {
+    body += String(chunk);
+    if (Buffer.byteLength(body, "utf8") > maxBytes) {
+      throw new Error(`${bodyLabel} body is too large.`);
+    }
+  }
+  try {
+    return JSON.parse(body || "{}");
+  } catch {
+    throw new Error(`${bodyLabel} body must be valid JSON.`);
+  }
+}
+
+export function writeJson(res, status, body) {
+  res.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
+  res.end(`${JSON.stringify(body, null, 2)}\n`);
+}

package/engine/react/mdx-compile.mjs

@@ -112,6 +112,7 @@ export function rehypeBlockIds(options = {}) {
       if (includeBlockIds && !includeBlockIds.has(id)) return false;
 
       setDataAttribute(node, "data-openpress-block-id", id);
+      setDataAttribute(node, "data-openpress-object-id", createBlockObjectEntityId(id));
       const extraAttributes = blockAttributes.get(id);
       if (extraAttributes) {
         for (const [name, value] of Object.entries(extraAttributes)) {
@@ -142,9 +143,19 @@ function applyTableRowBlocks({
   includeBlockIds,
 }) {
   const rows = tableBodyRows(node);
+  const header = tableHeaderRow(node);
+  const caption = tableCaption(node);
+  const captionRecord = caption ? { id: `${id}-caption`, node: caption } : null;
+  const headerRecord = header ? { id: `${id}-h0`, node: header } : null;
+  const selectedCaption = captionRecord && (!includeBlockIds || includeBlockIds.has(captionRecord.id));
+  const selectedHeader = headerRecord && (!includeBlockIds || includeBlockIds.has(headerRecord.id));
+  const firstSelectedRowIndex = selectedFirstTableRowIndex(rows, includeBlockIds, id);
+  const renderCaption = selectedCaption || (captionRecord && includeBlockIds && firstSelectedRowIndex === 0);
+  const renderHeader = Boolean(headerRecord && (!includeBlockIds || firstSelectedRowIndex === 0 || selectedHeader));
   if (rows.length === 0) {
     if (includeBlockIds && !includeBlockIds.has(id)) return false;
     setDataAttribute(node, "data-openpress-block-id", id);
+    setDataAttribute(node, "data-openpress-object-id", createBlockObjectEntityId(id));
     blocks.push({
       id,
       kind: "element",
@@ -165,15 +176,56 @@ function applyTableRowBlocks({
   const selected = includeBlockIds
     ? rowRecords.filter((row) => includeBlockIds.has(row.id))
     : rowRecords;
-  if (selected.length === 0) return false;
+  if (selected.length === 0 && !selectedCaption && !selectedHeader) return false;
 
   setDataAttribute(node, "data-openpress-table-id", id);
+  if (headerRecord && renderHeader) {
+    setDataAttribute(headerRecord.node, "data-openpress-block-id", headerRecord.id);
+    setDataAttribute(headerRecord.node, "data-openpress-object-id", createBlockObjectEntityId(headerRecord.id));
+    setDataAttribute(headerRecord.node, "data-openpress-block-layout", "attached");
+  }
+  if (captionRecord) {
+    if (renderCaption) {
+      setDataAttribute(captionRecord.node, "data-openpress-block-id", captionRecord.id);
+      setDataAttribute(captionRecord.node, "data-openpress-object-id", createBlockObjectEntityId(captionRecord.id));
+      if (selectedCaption) {
+        blocks.push({
+          id: captionRecord.id,
+          kind: "element",
+          name: "caption",
+          text: textContent(captionRecord.node).trim() || undefined,
+          filePath,
+          chapterSlug,
+          tableId: id,
+          layout: "attached",
+          source: sourcePosition(captionRecord.node.position ?? node.position),
+        });
+      }
+    } else {
+      removeTableCaption(node);
+    }
+  }
+  if (headerRecord && selectedHeader) {
+    blocks.push({
+      id: headerRecord.id,
+      kind: "table-row",
+      name: "table-header-row",
+      text: textContent(headerRecord.node).trim() || undefined,
+      filePath,
+      chapterSlug,
+      tableId: id,
+      rowIndex: -1,
+      layout: "attached",
+      source: sourcePosition(headerRecord.node.position ?? node.position),
+    });
+  }
   const selectedNodes = new Set(selected.map((row) => row.node));
   pruneUnselectedTableRows(node, new Set(rowRecords.map((row) => row.node)), selectedNodes);
-  if (selected[0]?.index > 0) stripTableHeader(node);
+  if (!renderHeader) stripTableHeader(node);
 
   for (const row of selected) {
     setDataAttribute(row.node, "data-openpress-block-id", row.id);
+    setDataAttribute(row.node, "data-openpress-object-id", createBlockObjectEntityId(row.id));
     blocks.push({
       id: row.id,
       kind: "table-row",
@@ -229,6 +281,7 @@ function normalizeTableCaptions(node) {
         type: "element",
         tagName: "caption",
         properties: {},
+        position: child.position,
         children: [{ type: "text", value: captionText }],
       });
     }
@@ -272,8 +325,10 @@ function wrapMdxComponents(components) {
     if (typeof Component !== "function") continue;
     wrapped[name] = function ComponentBlock(props = {}) {
       const blockId = props["data-openpress-block-id"];
+      const objectId = props["data-openpress-object-id"] || (blockId ? createBlockObjectEntityId(blockId) : undefined);
       const rest = { ...props };
       delete rest["data-openpress-block-id"];
+      delete rest["data-openpress-object-id"];
 
       if (!blockId) return React.createElement(Component, rest);
 
@@ -281,6 +336,7 @@ function wrapMdxComponents(components) {
         "div",
         {
           "data-openpress-block-id": blockId,
+          "data-openpress-object-id": objectId,
           "data-openpress-component-block": name,
         },
         React.createElement(Component, rest),
@@ -336,6 +392,7 @@ function applyListItemBlocks({
   if (items.length === 0) {
     if (includeBlockIds && !includeBlockIds.has(id)) return false;
     setDataAttribute(node, "data-openpress-block-id", id);
+    setDataAttribute(node, "data-openpress-object-id", createBlockObjectEntityId(id));
     blocks.push({
       id,
       kind: "element",
@@ -375,6 +432,7 @@ function applyListItemBlocks({
 
   for (const item of selected) {
     setDataAttribute(item.node, "data-openpress-block-id", item.id);
+    setDataAttribute(item.node, "data-openpress-object-id", createBlockObjectEntityId(item.id));
     blocks.push({
       id: item.id,
       kind: "list-item",
@@ -419,6 +477,28 @@ function tableBodyRows(table) {
   return (table.children ?? []).filter((child) => child?.type === "element" && child.tagName === "tr");
 }
 
+function tableHeaderRow(table) {
+  if (table?.type !== "element" || table.tagName !== "table") return null;
+  for (const child of table.children ?? []) {
+    if (child?.type !== "element" || child.tagName !== "thead") continue;
+    return (child.children ?? []).find((row) => row?.type === "element" && row.tagName === "tr") ?? null;
+  }
+  return null;
+}
+
+function selectedFirstTableRowIndex(rows, includeBlockIds, tableId) {
+  if (!includeBlockIds) return 0;
+  for (let index = 0; index < rows.length; index += 1) {
+    if (includeBlockIds.has(`${tableId}-r${index}`)) return index;
+  }
+  return -1;
+}
+
+function tableCaption(table) {
+  if (table?.type !== "element" || table.tagName !== "table") return null;
+  return (table.children ?? []).find((child) => child?.type === "element" && child.tagName === "caption") ?? null;
+}
+
 function pruneUnselectedTableRows(node, rowNodes, selectedNodes) {
   if (!Array.isArray(node?.children)) return;
   node.children = node.children.filter((child) => {
@@ -432,10 +512,15 @@ function stripTableHeader(table) {
   if (!Array.isArray(table?.children)) return;
   table.children = table.children.filter((child) => {
     if (child?.type !== "element") return true;
-    return child.tagName !== "caption" && child.tagName !== "thead";
+    return child.tagName !== "thead";
   });
 }
 
+function removeTableCaption(table) {
+  if (!Array.isArray(table?.children)) return;
+  table.children = table.children.filter((child) => child?.type !== "element" || child.tagName !== "caption");
+}
+
 function headingText(node) {
   if (!/^h[1-6]$/.test(String(node?.tagName ?? ""))) return undefined;
   return textContent(node).trim() || undefined;
@@ -470,6 +555,14 @@ function setDataAttribute(node, name, value) {
   node.properties[name] = value;
 }
 
+function createObjectEntityId(kind, ...parts) {
+  return [kind, ...parts.map((part) => encodeURIComponent(String(part)))].join(":");
+}
+
+function createBlockObjectEntityId(blockId) {
+  return createObjectEntityId("mdx-block", blockId);
+}
+
 function visit(node, visitor) {
   visitor(node);
   if (!Array.isArray(node?.children)) return;