@open-press/core 1.1.2 → 1.1.4

package/engine/cli.mjs

@@ -85,7 +85,7 @@ Commands:
   preview --renderer react [--host 127.0.0.1] [--port 5173] [--no-build] [--dry-run]
   dev --renderer react [--host 127.0.0.1] [--port 5173] [--no-build] [--dry-run]
   typecheck
-  image [--output <outputDir>] [--no-build] [--dry-run]
+  image [--output <outputDir>] [--pages <selector>] [--no-build] [--dry-run]
   pdf [--output <outputDir>/<pdf.filename>] [--no-build] [--dry-run]
   deploy --confirm [--dry-run]
   doctor [--json] [--no-cache]                          # version + skill staleness check

package/engine/commands/_shared.mjs

@@ -40,6 +40,7 @@ export function parseOptions(argv) {
     else if (value === "--scope") options.scope = argv[++i];
     else if (value === "--source") options.source = argv[++i];
     else if (value === "--output") options.output = argv[++i];
+    else if (value === "--pages") options.pages = argv[++i];
     else if (value.startsWith("--")) throw new Error(`Unknown option: ${value}`);
     else positional.push(value);
   }
@@ -145,6 +146,7 @@ export async function buildReactImages({
   port = "5186",
   noBuild = false,
   recurse,
+  pageSelector = null,
 }) {
   config ??= await loadConfig(root);
   outDir ??= path.join(config.paths.outputDir, "images");
@@ -162,9 +164,18 @@ export async function buildReactImages({
       debuggingPortBase: 9700,
       debuggingPortRange: 600,
       profilePrefix: "chrome-image",
+      pageSelector,
     });
-    console.log(`${result.files.length} OpenPress pages exported to PNG`);
-    return { outDir, files: result.files, pageCount: result.pageCount };
+    const label = pageSelector
+      ? `${result.files.length}/${result.pageCount} OpenPress pages exported to PNG`
+      : `${result.files.length} OpenPress pages exported to PNG`;
+    console.log(label);
+    return {
+      outDir,
+      files: result.files,
+      pageCount: result.pageCount,
+      selectedPageNumbers: result.selectedPageNumbers,
+    };
   } finally {
     await stopChildProcess(server);
   }

package/engine/commands/image.mjs

@@ -1,15 +1,21 @@
 import path from "node:path";
 import { STATIC_SERVER, buildReactImages, formatNodeScriptCommand, formatOpenPressCommand } from "./_shared.mjs";
+import { parsePageSelector } from "../runtime/page-selector.mjs";
 
 export async function run({ root, config, options, recurse }) {
   const outputDir = options.output ? path.resolve(root, options.output) : path.join(config.paths.outputDir, "images");
   const host = options.host ?? "127.0.0.1";
   const port = options.port ?? "5186";
 
+  const pageSelector = options.pages ? parsePageSelector(options.pages) : null;
+
   if (options.dryRun) {
     console.log(`Command: ${formatOpenPressCommand(["render", ".", "--renderer", "react"])}`);
     console.log(`Command: ${formatNodeScriptCommand(root, STATIC_SERVER)} ${config.outputDir} --host ${host} --port ${port} --workspace .`);
     console.log(`Chrome image export URL: http://${host}:${port}/?print=1`);
+    if (pageSelector) {
+      console.log(`Page selector: ${options.pages} (resolved at capture time against the rendered page count)`);
+    }
     console.log(`Output: ${path.relative(root, path.join(outputDir, "page-001.png"))}`);
     return 0;
   }
@@ -22,8 +28,12 @@ export async function run({ root, config, options, recurse }) {
     port,
     noBuild: options.noBuild,
     recurse,
+    pageSelector,
   });
 
-  console.log(`OpenPress images: ${path.relative(root, result.outDir)} (${result.files.length} pages)`);
+  const suffix = pageSelector
+    ? ` (${result.files.length}/${result.pageCount} pages)`
+    : ` (${result.files.length} pages)`;
+  console.log(`OpenPress images: ${path.relative(root, result.outDir)}${suffix}`);
   return 0;
 }

package/engine/output/chrome-pdf.mjs

@@ -2,6 +2,9 @@ import { spawn, spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { resolvePageSelector } from "../runtime/page-selector.mjs";
+
+const defaultResolveSelector = resolvePageSelector;
 
 const CHROME_CANDIDATE_PATHS = {
   darwin: [
@@ -137,6 +140,7 @@ export async function printUrlToPdf({
       await preparePdfPage(client, { viewport });
       await client.send("Page.navigate", { url });
       const readyResult = await waitForReady(client);
+      warnAboutOverflowingPages("PDF", readyResult);
       const result = await client.send("Page.printToPDF", {
         ...DEFAULT_PRINT_OPTIONS,
         ...printOptions,
@@ -152,6 +156,16 @@ export async function printUrlToPdf({
   }
 }
 
+function warnAboutOverflowingPages(label, readyResult) {
+  const overflowing = Array.isArray(readyResult?.overflowingPageNumbers) ? readyResult.overflowingPageNumbers : [];
+  if (overflowing.length === 0) return;
+  const preview = overflowing.slice(0, 12).join(", ") + (overflowing.length > 12 ? `, … (+${overflowing.length - 12} more)` : "");
+  console.warn(
+    `OpenPress ${label}: ${overflowing.length} page(s) exceed the page body bounds (pages ${preview}). ` +
+    `Output will still be generated but those pages may clip; run \`openpress inspect\` to locate the overflowing elements.`,
+  );
+}
+
 export async function captureUrlPagesToPng({
   root,
   url,
@@ -162,6 +176,8 @@ export async function captureUrlPagesToPng({
   debuggingPortBase = 9700,
   debuggingPortRange = 300,
   profilePrefix = "chrome-image",
+  pageSelector = null,
+  resolveSelector = null,
 }) {
   chrome ??= resolveChromePath();
   await fs.mkdir(outDir, { recursive: true });
@@ -189,14 +205,25 @@ export async function captureUrlPagesToPng({
     try {
       await preparePdfPage(client, { viewport });
       await client.send("Page.navigate", { url });
-      const pageCount = await waitForReady(client);
+      const readyResult = await waitForReady(client);
+      warnAboutOverflowingPages("image", readyResult);
+      const pageCount = readyResult?.pageCount ?? 0;
       const rects = await getPrintPageRects(client);
       if (rects.length === 0) throw new Error("No OpenPress pages found for image export.");
 
+      const selectedPageNumbers = pageSelector
+        ? (resolveSelector ?? defaultResolveSelector)(pageSelector, rects.length)
+        : rects.map((_, index) => index + 1);
+      if (selectedPageNumbers.length === 0) {
+        throw new Error("Page selector resolved to zero pages; nothing to export.");
+      }
+
       const padWidth = Math.max(3, String(rects.length).length);
       const files = [];
-      for (const [index, rect] of rects.entries()) {
-        const filename = `page-${String(index + 1).padStart(padWidth, "0")}.png`;
+      for (const pageNumber of selectedPageNumbers) {
+        const rect = rects[pageNumber - 1];
+        if (!rect) continue;
+        const filename = `page-${String(pageNumber).padStart(padWidth, "0")}.png`;
         const filePath = path.join(outDir, filename);
         const result = await client.send("Page.captureScreenshot", {
           format: "png",
@@ -214,7 +241,7 @@ export async function captureUrlPagesToPng({
         files.push(filePath);
       }
 
-      return { pageCount, files };
+      return { pageCount, files, selectedPageNumbers };
     } finally {
       client.close();
     }
@@ -282,59 +309,135 @@ export async function evaluateUrlWithChrome({
   }
 }
 
-export async function waitForPrintReady(client) {
-  const deadline = Date.now() + 30000;
-  while (Date.now() < deadline) {
+export const PRINT_READY_DEFAULTS = Object.freeze({
+  totalTimeoutMs: 300_000,
+  idleTimeoutMs: 30_000,
+  pollIntervalMs: 100,
+  stableMs: 300,
+});
+
+export function resolvePrintReadyTiming(env = process.env) {
+  const total = Number(env.OPENPRESS_PRINT_READY_TIMEOUT_MS);
+  const idle = Number(env.OPENPRESS_PRINT_READY_IDLE_MS);
+  const stable = Number(env.OPENPRESS_PRINT_READY_STABLE_MS);
+  return {
+    totalTimeoutMs: Number.isFinite(total) && total > 0 ? total : PRINT_READY_DEFAULTS.totalTimeoutMs,
+    idleTimeoutMs: Number.isFinite(idle) && idle > 0 ? idle : PRINT_READY_DEFAULTS.idleTimeoutMs,
+    stableMs: Number.isFinite(stable) && stable >= 0 ? stable : PRINT_READY_DEFAULTS.stableMs,
+    pollIntervalMs: PRINT_READY_DEFAULTS.pollIntervalMs,
+  };
+}
+
+export function printReadinessExpression() {
+  return `Promise.resolve().then(async () => {
+    const root = document.querySelector('[data-openpress-print-document="true"]');
+    if (!root) return { pageCount: 0, overflowingPages: 0, overflowingPageNumbers: [] };
+    const candidates = root.querySelectorAll('.openpress-html-page');
+    if (candidates.length === 0) return { pageCount: 0, overflowingPages: 0, overflowingPageNumbers: [] };
+
+    await document.fonts?.ready;
+    await Promise.all(Array.from(document.images).map(async (img) => {
+      if (!img.complete) {
+        await new Promise((resolve) => {
+          const settle = () => {
+            img.removeEventListener('load', settle);
+            img.removeEventListener('error', settle);
+            resolve();
+          };
+          img.addEventListener('load', settle, { once: true });
+          img.addEventListener('error', settle, { once: true });
+        });
+      }
+      await img.decode?.().catch(() => undefined);
+    }));
+
+    await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+
+    const pages = Array.from(document.querySelectorAll('.openpress-public-page > .openpress-html-page'));
+    const contentFitsPageBody = (body) => {
+      const bodyBottom = body.getBoundingClientRect().bottom;
+      const contentBottom = Array.from(body.children).reduce((bottom, child) => {
+        if (getComputedStyle(child).display === 'none') return bottom;
+        const marginBottom = Number.parseFloat(getComputedStyle(child).marginBottom) || 0;
+        return Math.max(bottom, child.getBoundingClientRect().bottom + marginBottom);
+      }, body.getBoundingClientRect().top);
+      return contentBottom <= bodyBottom + 1;
+    };
+    const overflowingPageNumbers = pages.reduce((nums, page, index) => {
+      const body = page.querySelector('.page-body');
+      if (body && !contentFitsPageBody(body)) nums.push(index + 1);
+      return nums;
+    }, []);
+
+    return {
+      pageCount: pages.length,
+      overflowingPages: overflowingPageNumbers.length,
+      overflowingPageNumbers,
+    };
+  })`;
+}
+
+function formatPrintReadyTimeoutMessage(reason, snapshot, timing, elapsedMs) {
+  const seconds = Math.round(elapsedMs / 1000);
+  const observed = `(observed ${snapshot.pageCount} page(s), ${snapshot.overflowingPages} overflowing)`;
+  if (reason === "idle") {
+    return (
+      `Timed out waiting for OpenPress pagination before PDF export. ` +
+      `No progress for ${seconds}s ${observed}. ` +
+      `Raise OPENPRESS_PRINT_READY_IDLE_MS (currently ${timing.idleTimeoutMs}ms) to extend the idle window.`
+    );
+  }
+  return (
+    `Timed out waiting for OpenPress pagination before PDF export. ` +
+    `Total ${seconds}s exceeded ${observed}. ` +
+    `Raise OPENPRESS_PRINT_READY_TIMEOUT_MS (currently ${timing.totalTimeoutMs}ms) to extend the hard cap.`
+  );
+}
+
+export async function waitForPrintReady(client, timing = resolvePrintReadyTiming()) {
+  const startedAt = Date.now();
+  let lastSignature = "";
+  let lastProgressAt = startedAt;
+  let stableSince = startedAt;
+  let lastSnapshot = { pageCount: 0, overflowingPages: 0, overflowingPageNumbers: [] };
+
+  while (true) {
+    const totalElapsed = Date.now() - startedAt;
+    if (totalElapsed > timing.totalTimeoutMs) {
+      throw new Error(formatPrintReadyTimeoutMessage("total", lastSnapshot, timing, totalElapsed));
+    }
+
     const result = await client.send("Runtime.evaluate", {
       returnByValue: true,
       awaitPromise: true,
-      expression: `Promise.resolve().then(async () => {
-        const root = document.querySelector('[data-openpress-print-document="true"]');
-        if (!root || root.querySelectorAll('.openpress-html-page').length === 0) return 0;
-
-        await document.fonts?.ready;
-        await Promise.all(Array.from(document.images).map(async (img) => {
-          if (!img.complete) {
-            await new Promise((resolve) => {
-              const settle = () => {
-                img.removeEventListener('load', settle);
-                img.removeEventListener('error', settle);
-                resolve();
-              };
-
-              img.addEventListener('load', settle, { once: true });
-              img.addEventListener('error', settle, { once: true });
-            });
-          }
-
-          await img.decode?.().catch(() => undefined);
-        }));
-
-        await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)));
-
-        const pages = Array.from(document.querySelectorAll('.openpress-public-page > .openpress-html-page'));
-        const contentFitsPageBody = (body) => {
-          const bodyBottom = body.getBoundingClientRect().bottom;
-          const contentBottom = Array.from(body.children).reduce((bottom, child) => {
-            if (getComputedStyle(child).display === 'none') return bottom;
-            const marginBottom = Number.parseFloat(getComputedStyle(child).marginBottom) || 0;
-            return Math.max(bottom, child.getBoundingClientRect().bottom + marginBottom);
-          }, body.getBoundingClientRect().top);
-          return contentBottom <= bodyBottom + 1;
-        };
-        const bodyOverflowSafe = pages.every((page) => {
-          const body = page.querySelector('.page-body');
-          return !body || contentFitsPageBody(body);
-        });
-
-        return pages.length > 0 && bodyOverflowSafe ? pages.length : 0;
-      })`,
+      expression: printReadinessExpression(),
     });
-    const count = Number(result.result?.value ?? 0);
-    if (count > 0) return count;
-    await delay(100);
+    const value = result.result?.value ?? {};
+    const pageCount = Number.isFinite(Number(value.pageCount)) ? Number(value.pageCount) : 0;
+    const overflowingPages = Number.isFinite(Number(value.overflowingPages)) ? Number(value.overflowingPages) : 0;
+    const overflowingPageNumbers = Array.isArray(value.overflowingPageNumbers)
+      ? value.overflowingPageNumbers.map(Number).filter(Number.isFinite)
+      : [];
+    lastSnapshot = { pageCount, overflowingPages, overflowingPageNumbers };
+
+    const signature = `${pageCount}:${overflowingPages}`;
+    if (signature !== lastSignature) {
+      lastSignature = signature;
+      stableSince = Date.now();
+      lastProgressAt = Date.now();
+    }
+
+    if (pageCount > 0 && Date.now() - stableSince >= timing.stableMs) {
+      return { pageCount, overflowingPageNumbers };
+    }
+
+    const idleElapsed = Date.now() - lastProgressAt;
+    if (idleElapsed > timing.idleTimeoutMs) {
+      throw new Error(formatPrintReadyTimeoutMessage("idle", lastSnapshot, timing, idleElapsed));
+    }
+
+    await delay(timing.pollIntervalMs);
   }
-  throw new Error("Timed out waiting for OpenPress pagination before PDF export.");
 }
 
 async function getPrintPageRects(client) {

package/engine/react/document-entry.mjs

@@ -14,6 +14,7 @@ import ts from "typescript";
 import { createServer as createViteServer } from "vite";
 import { loadConfig } from "../runtime/config.mjs";
 import { inspectPressTree } from "./press-tree-inspection.mjs";
+import { textSourceTransformPlugin } from "./text-source-transform.mjs";
 
 const ENGINE_REACT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const FRAMEWORK_ROOT = path.resolve(ENGINE_REACT_DIR, "..", "..");
@@ -95,7 +96,14 @@ export async function createReactSsrServer(workspaceRoot = ".") {
     cacheDir: path.join(resolvedWorkspaceRoot, ".openpress", "vite-ssr"),
     appType: "custom",
     logLevel: "silent",
-    plugins: [reactRuntimePlugin(), react()],
+    plugins: [
+      textSourceTransformPlugin({
+        workspaceRoot: resolvedWorkspaceRoot,
+        documentRoot: path.join(resolvedWorkspaceRoot, "press"),
+      }),
+      reactRuntimePlugin(),
+      react(),
+    ],
     resolve: {
       alias: [
         // ORDER MATTERS: subpath aliases must precede the base alias so that

package/engine/react/document-export.mjs

@@ -24,6 +24,7 @@ import { resolveAllSources } from "./sources/mdx-resolver.mjs";
 import { discoverSectionStyles } from "./style-discovery.mjs";
 
 const MAX_ITERATIONS = 20;
+const PRESS_TYPES = new Set(["pages", "slides"]);
 
 export async function exportReactDocument(root = ".", { syncAssets = true } = {}) {
   const workspaceRoot = path.resolve(root);
@@ -115,6 +116,7 @@ export async function exportReactDocument(root = ".", { syncAssets = true } = {}
       presses: pressResults.map((r) => ({
         slug: r.slug,
         title: r.readerDocument.meta.title,
+        type: r.pressType,
         page: r.readerDocument.theme ?? null,
         pageCount: r.pageCount,
         documentUrl: r.documentUrl,
@@ -158,6 +160,7 @@ async function exportSinglePress({
   const slug = typeof press.metadata?.slug === "string" && press.metadata.slug.trim()
     ? press.metadata.slug.trim()
     : "";
+  const pressType = normalizePressType(press.metadata?.type);
 
   // Effective config for this press: workspace config with per-press
   // metadata overlaid. Press JSX page prop wins over the workspace page.
@@ -308,6 +311,7 @@ async function exportSinglePress({
   const readerDocument = {
     meta: {
       title: trimmedString(effectiveConfig.title) ?? "Untitled Document",
+      type: pressType,
       subtitle: trimmedString(effectiveConfig.subtitle) ?? "",
       organization: trimmedString(effectiveConfig.organization) ?? "",
       workspaceLabel: trimmedString(effectiveConfig.workspaceLabel) ?? "",
@@ -349,6 +353,7 @@ async function exportSinglePress({
 
   return {
     slug,
+    pressType,
     documentPath,
     documentUrl: slug ? `/openpress/${slug}/document.json` : "/openpress/document.json",
     readerDocument,
@@ -356,6 +361,14 @@ async function exportSinglePress({
   };
 }
 
+function normalizePressType(value) {
+  if (value === undefined || value === null || value === "") return "pages";
+  if (PRESS_TYPES.has(value)) return value;
+  throw new Error(
+    `Unsupported Press type "${value}". Supported types: ${[...PRESS_TYPES].join(", ")}.`,
+  );
+}
+
 // Apply per-Press JSX prop overrides onto the workspace-level config.
 // Returns a new config object — the original is untouched so other
 // presses in the same workspace get a clean base.
@@ -509,4 +522,3 @@ function collectSectionRoots(presses, documentRoot) {
   }
   return [...roots];
 }
-

package/engine/react/press-tree-inspection.mjs

@@ -31,6 +31,7 @@ import React from "react";
  *     props: Record<string, unknown>,           // Press JSX props (no children)
  *     metadata: {
  *       title?: string,
+ *       type?: "pages" | "slides",
  *       page?: unknown,
  *       slug?: string,
  *       theme?: string,
@@ -144,6 +145,7 @@ function collectPressElements(root, PRESS_MARKER) {
 function pickPressMetadata(pressProps) {
   const out = {};
   if (typeof pressProps.title === "string") out.title = pressProps.title;
+  if (typeof pressProps.type === "string") out.type = pressProps.type;
   if (pressProps.page !== undefined) out.page = pressProps.page;
   if (typeof pressProps.slug === "string") out.slug = pressProps.slug;
   if (typeof pressProps.theme === "string") out.theme = pressProps.theme;

package/engine/react/text-source-transform.mjs

@@ -0,0 +1,175 @@
+import fs from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+
+const TEXT_SOURCE_FILE_RE = /\.[jt]sx$/;
+
+export function textSourceTransformPlugin({ workspaceRoot, documentRoot }) {
+  const resolvedWorkspaceRoot = realpathIfExists(path.resolve(workspaceRoot));
+  const resolvedDocumentRoot = realpathIfExists(path.resolve(documentRoot));
+
+  return {
+    name: "openpress-text-source-transform",
+    enforce: "pre",
+    transform(code, id) {
+      const filePath = cleanViteId(id);
+      if (!TEXT_SOURCE_FILE_RE.test(filePath)) return null;
+      if (!isInsidePath(filePath, resolvedDocumentRoot)) return null;
+
+      const relativePath = path.relative(resolvedWorkspaceRoot, filePath).replaceAll(path.sep, "/");
+      if (!relativePath || relativePath.startsWith("..")) return null;
+
+      const nextCode = addLiteralTextSourceProps(code, {
+        filePath,
+        sourcePath: relativePath,
+      });
+      if (nextCode === code) return null;
+      return { code: nextCode, map: null };
+    },
+  };
+}
+
+export function addLiteralTextSourceProps(code, { filePath = "index.tsx", sourcePath = "press/index.tsx" } = {}) {
+  const sourceFile = ts.createSourceFile(filePath, code, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  const textRefs = collectOpenPressTextRefs(sourceFile);
+  if (textRefs.identifiers.size === 0 && textRefs.namespaces.size === 0) return code;
+
+  const insertions = [];
+
+  const visit = (node) => {
+    if (ts.isJsxElement(node) && isTextElementName(node.openingElement.tagName, textRefs)) {
+      const opening = node.openingElement;
+      if (!hasJsxAttribute(opening, "source")) {
+        const literal = literalTextChildRange(node, sourceFile, code);
+        if (literal) {
+          insertions.push({
+            offset: opening.end - 1,
+            text: ` source={${sourcePropExpression({
+              sourcePath,
+              objectId: stringLiteralAttribute(opening, "objectId"),
+              range: literal.range,
+            })}}`,
+          });
+        }
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+
+  if (insertions.length === 0) return code;
+  let out = code;
+  for (const insertion of insertions.sort((a, b) => b.offset - a.offset)) {
+    out = `${out.slice(0, insertion.offset)}${insertion.text}${out.slice(insertion.offset)}`;
+  }
+  return out;
+}
+
+function collectOpenPressTextRefs(sourceFile) {
+  const identifiers = new Set();
+  const namespaces = new Set();
+
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement)) continue;
+    if (!statement.importClause) continue;
+    if (!ts.isStringLiteral(statement.moduleSpecifier)) continue;
+    if (statement.moduleSpecifier.text !== "@open-press/core") continue;
+
+    const bindings = statement.importClause.namedBindings;
+    if (!bindings) continue;
+    if (ts.isNamespaceImport(bindings)) {
+      namespaces.add(bindings.name.text);
+      continue;
+    }
+    if (!ts.isNamedImports(bindings)) continue;
+
+    for (const element of bindings.elements) {
+      const importedName = element.propertyName?.text ?? element.name.text;
+      if (importedName === "Text") identifiers.add(element.name.text);
+    }
+  }
+
+  return { identifiers, namespaces };
+}
+
+function literalTextChildRange(node, sourceFile, code) {
+  const textChildren = [];
+  for (const child of node.children) {
+    if (ts.isJsxText(child)) {
+      const raw = code.slice(child.pos, child.end);
+      if (raw.trim()) textChildren.push({ child, raw });
+      continue;
+    }
+    if (ts.isJsxExpression(child) && !child.expression && code.slice(child.pos, child.end).trim() === "{}") continue;
+    if (code.slice(child.pos, child.end).trim()) return null;
+  }
+  if (textChildren.length !== 1) return null;
+
+  const { child, raw } = textChildren[0];
+  const text = raw.trim();
+  const startInRaw = raw.indexOf(text);
+  const startOffset = child.pos + startInRaw;
+  const endOffset = startOffset + text.length;
+  const start = sourceFile.getLineAndCharacterOfPosition(startOffset);
+  const end = sourceFile.getLineAndCharacterOfPosition(endOffset);
+  return {
+    text,
+    range: {
+      line: start.line + 1,
+      column: start.character + 1,
+      endLine: end.line + 1,
+      endColumn: end.character + 1,
+    },
+  };
+}
+
+function sourcePropExpression({ sourcePath, objectId, range }) {
+  const props = [
+    `path: ${JSON.stringify(sourcePath)}`,
+    `kind: "tsx-text"`,
+    `source: { line: ${range.line}, column: ${range.column}, endLine: ${range.endLine}, endColumn: ${range.endColumn} }`,
+  ];
+  if (objectId) props.splice(2, 0, `objectId: ${JSON.stringify(objectId)}`);
+  return `{ ${props.join(", ")} }`;
+}
+
+function isTextElementName(name, refs) {
+  if (ts.isIdentifier(name)) return refs.identifiers.has(name.text);
+  if (!ts.isJsxMemberExpression(name)) return false;
+  if (name.name.text !== "Text") return false;
+  return ts.isIdentifier(name.expression) && refs.namespaces.has(name.expression.text);
+}
+
+function hasJsxAttribute(opening, name) {
+  return opening.attributes.properties.some((prop) =>
+    ts.isJsxAttribute(prop) && prop.name.text === name
+  );
+}
+
+function stringLiteralAttribute(opening, name) {
+  const attr = opening.attributes.properties.find((prop) =>
+    ts.isJsxAttribute(prop) && prop.name.text === name
+  );
+  if (!attr || !ts.isJsxAttribute(attr) || !attr.initializer) return undefined;
+  if (ts.isStringLiteral(attr.initializer)) return attr.initializer.text;
+  return undefined;
+}
+
+function cleanViteId(id) {
+  const withoutQuery = String(id ?? "").split("?")[0];
+  const fsPath = withoutQuery.startsWith("/@fs/") ? withoutQuery.slice("/@fs".length) : withoutQuery;
+  return realpathIfExists(path.resolve(fsPath));
+}
+
+function realpathIfExists(filePath) {
+  try {
+    return fs.realpathSync.native(filePath);
+  } catch {
+    return filePath;
+  }
+}
+
+function isInsidePath(filePath, parentPath) {
+  const relative = path.relative(parentPath, filePath);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}