@open-press/core 1.2.0 → 1.3.1

package/engine/react/project-asset-endpoint.mjs

@@ -75,9 +75,10 @@ async function renameProjectAsset({ config, kind, name, nextName }) {
     throw new Error("Rename requires a different valid name.");
   }
 
-  const currentPath = resolveAssetPath(config, kind, normalizedCurrentName);
-  const nextPath = resolveAssetPath(config, kind, normalizedNextName);
-  await assertPathExists(currentPath, `${kind} asset not found: ${normalizedCurrentName}`);
+  const current = await resolveExistingAssetPath(config, kind, normalizedCurrentName);
+  if (!current) throw new Error(`${kind} asset not found: ${normalizedCurrentName}`);
+  const currentPath = current.path;
+  const nextPath = resolveAssetPathInRoot(current.root, kind, normalizedNextName);
   if (await fileExists(nextPath)) throw new Error(`${kind} asset already exists: ${normalizedNextName}`);
 
   await fs.rename(currentPath, nextPath);
@@ -113,8 +114,9 @@ async function deleteProjectAsset({ config, kind, name }) {
     };
   }
 
-  const targetPath = resolveAssetPath(config, kind, normalizedName);
-  await assertPathExists(targetPath, `${kind} asset not found: ${normalizedName}`);
+  const target = await resolveExistingAssetPath(config, kind, normalizedName);
+  if (!target) throw new Error(`${kind} asset not found: ${normalizedName}`);
+  const targetPath = target.path;
   await fs.rm(targetPath, { recursive: true, force: true });
 
   return {
@@ -242,8 +244,15 @@ async function findProjectAssetReferences({ config, kind, name }) {
   return references;
 }
 
-function resolveAssetPath(config, kind, name) {
-  const root = kind === "media" ? config.paths.mediaDir : config.paths.componentsDir;
+async function resolveExistingAssetPath(config, kind, name) {
+  for (const root of await assetRoots(config, kind)) {
+    const target = resolveAssetPathInRoot(root, kind, name);
+    if (await fileExists(target)) return { root, path: target };
+  }
+  return null;
+}
+
+function resolveAssetPathInRoot(root, kind, name) {
   const target = path.resolve(root, name);
   const resolvedRoot = path.resolve(root);
   if (!target.startsWith(`${resolvedRoot}${path.sep}`) && target !== resolvedRoot) {
@@ -252,6 +261,35 @@ function resolveAssetPath(config, kind, name) {
   return target;
 }
 
+async function assetRoots(config, kind) {
+  const childName = kind === "media" ? "media" : "components";
+  const roots = [
+    kind === "media" ? config.paths.mediaDir : config.paths.componentsDir,
+  ];
+  try {
+    const entries = await fs.readdir(config.paths.documentRoot, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name.startsWith(".") || entry.name === "shared") continue;
+      roots.push(path.join(config.paths.documentRoot, entry.name, childName));
+    }
+  } catch {
+    // Missing press/ is reported by workspace validation/export.
+  }
+  return uniquePaths(roots);
+}
+
+function uniquePaths(paths) {
+  const out = [];
+  const seen = new Set();
+  for (const candidate of paths) {
+    const normalized = path.resolve(candidate);
+    if (seen.has(normalized)) continue;
+    seen.add(normalized);
+    out.push(normalized);
+  }
+  return out;
+}
+
 function normalizeAssetName(kind, value, currentName = "") {
   if (kind === "media") return sanitizeMediaFileName(value, currentName);
   return sanitizeComponentName(value);
@@ -347,10 +385,6 @@ function normalizePositiveInteger(value) {
   return Number.isInteger(number) && number > 0 ? number : null;
 }
 
-async function assertPathExists(filePath, message) {
-  if (!(await fileExists(filePath))) throw new Error(message);
-}
-
 async function fileExists(filePath) {
   try {
     await fs.access(filePath);

package/engine/react/sources/heading-numbering.mjs

@@ -113,11 +113,11 @@ export function headingAttributesForBlock({
 }
 
 /**
- * Build a fallback single-entry outline when a section has no h2/h3 headings
+ * Build a section-title outline row when a section has no h2/h3 headings
  * the resolver could pick up. The outline still needs one row so the TOC
  * doesn't lose the section.
  */
-export function fallbackOutlineItems({ sourceId, section, chapterLabel, title, blocks }) {
+export function sectionTitleOutlineItems({ sourceId, section, chapterLabel, title, blocks }) {
   const targetBlock = blocks[0];
   return [{
     id: `${sourceId}:${section.slug}`,

package/engine/react/sources/mdx-resolver.mjs

@@ -12,12 +12,12 @@ import path from "node:path";
 import React from "react";
 import { documentRelativePath, resolveDocumentRelativePath } from "../../runtime/path-utils.mjs";
 import { compileMdx } from "../mdx-compile.mjs";
-import { createHeadingState, fallbackOutlineItems, headingAttributesForBlock } from "./heading-numbering.mjs";
+import { createHeadingState, headingAttributesForBlock, sectionTitleOutlineItems } from "./heading-numbering.mjs";
 
 const MDX_EXT = ".mdx";
 
 /**
- * Resolve all sources registered in `press/index.tsx`.
+ * Resolve all sources registered in `press/<slug>/press.tsx`.
  *
  * @param {object} opts
  * @param {Record<string, object>} opts.sources         The raw `sources` export.
@@ -141,7 +141,7 @@ async function resolveSource({ sourceId, descriptor, documentRoot, globalCompone
       title: resolvedSectionTitle,
       meta: section.meta ?? {},
     });
-    outline.push(...(outlineItems.length > 0 ? outlineItems : fallbackOutlineItems({
+    outline.push(...(outlineItems.length > 0 ? outlineItems : sectionTitleOutlineItems({
       sourceId,
       section,
       chapterLabel,

package/engine/react/style-discovery.mjs

@@ -12,18 +12,19 @@ const COMPONENT_EXT = ".tsx";
 export async function discoverSectionStyles(root = ".", config = {}, { sectionRoots } = {}) {
   const workspaceRoot = path.resolve(root);
   const documentRoot = config.paths?.documentRoot ?? path.join(workspaceRoot, "press");
-  const componentsRoot = config.paths?.componentsDir ?? path.join(documentRoot, "components");
-  const globalComponents = await discoverComponents(componentsRoot, documentRoot, "global");
-
-  // Multi-Press workspaces can place their chapters under per-Press
-  // subfolders (e.g. press/userstory/chapters/, press/slidepack/chapters/).
-  // The caller passes each Press's resolved section-folders root; we
-  // discover sections in every root and merge. Duplicate paths are
-  // de-duplicated by absolutePath. Falls back to the workspace-default
-  // root (press/chapters/) when no roots are passed in.
+  const componentsRoot = config.paths?.componentsDir ?? path.join(documentRoot, "shared", "components");
+  const globalComponents = await discoverComponentsInRoots(
+    [componentsRoot],
+    documentRoot,
+    "global",
+  );
+
+  // The caller usually passes each Press's resolved section-folders root.
+  // When it does not, discover conventional `press/<slug>/chapters` roots.
+  // Duplicate paths are de-duplicated by absolutePath.
   const effectiveRoots = sectionRoots && sectionRoots.length > 0
     ? sectionRoots
-    : [config.paths?.chaptersDir ?? config.paths?.sourceDir ?? path.join(documentRoot, "chapters")];
+    : await discoverConventionalChapterRoots(documentRoot);
   const seen = new Set();
   const sections = [];
   for (const sectionsRoot of effectiveRoots) {
@@ -40,11 +41,46 @@ export async function discoverSectionStyles(root = ".", config = {}, { sectionRo
     documentRoot,
     globalComponents,
     sections,
-    // Back-compat: `chapters` alias for callers that still expect the old shape.
     chapters: sections,
   };
 }
 
+async function discoverConventionalChapterRoots(documentRoot) {
+  const roots = [];
+  let entries = [];
+  try {
+    entries = await fs.readdir(documentRoot, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT") return roots;
+    throw error;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name === "shared" || entry.name.startsWith(".")) continue;
+    const chaptersRoot = path.join(documentRoot, entry.name, "chapters");
+    try {
+      const stat = await fs.stat(chaptersRoot);
+      if (stat.isDirectory()) roots.push(chaptersRoot);
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+  }
+  return roots;
+}
+
+export async function discoverComponentsInRoots(componentRoots, documentRoot, scope = "global") {
+  const components = [];
+  const seenPaths = new Set();
+  for (const componentsDir of uniquePaths(componentRoots)) {
+    const found = await discoverComponents(componentsDir, documentRoot, scope);
+    for (const component of found) {
+      if (seenPaths.has(component.absolutePath)) continue;
+      seenPaths.add(component.absolutePath);
+      components.push(component);
+    }
+  }
+  return components;
+}
+
 async function discoverSections(documentRoot, sectionsDir) {
   const entries = await readDirectoryEntries(sectionsDir);
   const sectionDirs = entries.filter((entry) => entry.isDirectory()).sort(compareSectionDirectories);
@@ -149,6 +185,19 @@ async function readDirectoryEntries(directory) {
   }
 }
 
+function uniquePaths(paths) {
+  const out = [];
+  const seen = new Set();
+  for (const candidate of paths ?? []) {
+    if (!candidate) continue;
+    const normalized = path.resolve(candidate);
+    if (seen.has(normalized)) continue;
+    seen.add(normalized);
+    out.push(normalized);
+  }
+  return out;
+}
+
 async function fileExists(filePath) {
   try {
     const stat = await fs.stat(filePath);

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

@@ -29,15 +29,14 @@ export function textSourceTransformPlugin({ workspaceRoot, documentRoot }) {
   };
 }
 
-export function addLiteralTextSourceProps(code, { filePath = "index.tsx", sourcePath = "press/index.tsx" } = {}) {
+export function addLiteralTextSourceProps(code, { filePath = "press/press.tsx", sourcePath = "press/<name>/press.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)) {
+    if (ts.isJsxElement(node) && isSourceBackedTextElement(node.openingElement, textRefs)) {
       const opening = node.openingElement;
       if (!hasJsxAttribute(opening, "source")) {
         const literal = literalTextChildRange(node, sourceFile, code);
@@ -133,13 +132,28 @@ function sourcePropExpression({ sourcePath, objectId, range }) {
   return `{ ${props.join(", ")} }`;
 }
 
+function isSourceBackedTextElement(opening, refs) {
+  if (isTextElementName(opening.tagName, refs)) return true;
+  return hasJsxAttribute(opening, "objectId") && isComponentElementName(opening.tagName);
+}
+
 function isTextElementName(name, refs) {
   if (ts.isIdentifier(name)) return refs.identifiers.has(name.text);
-  if (!ts.isJsxMemberExpression(name)) return false;
+  if (!isJsxMemberExpression(name)) return false;
   if (name.name.text !== "Text") return false;
   return ts.isIdentifier(name.expression) && refs.namespaces.has(name.expression.text);
 }
 
+function isComponentElementName(name) {
+  if (ts.isIdentifier(name)) return /^[A-Z]/.test(name.text);
+  if (isJsxMemberExpression(name)) return isComponentElementName(name.expression);
+  return false;
+}
+
+function isJsxMemberExpression(node) {
+  return ts.isPropertyAccessExpression(node) || node?.kind === ts.SyntaxKind.JsxMemberExpression;
+}
+
 function hasJsxAttribute(opening, name) {
   return opening.attributes.properties.some((prop) =>
     ts.isJsxAttribute(prop) && prop.name.text === name

package/engine/runtime/config.mjs

@@ -8,11 +8,11 @@ const DEFAULT_CONFIG = {
   organization: "",
   workspaceLabel: "",
   documentDir: ".",
-  sourceDir: "content",
-  mediaDir: "media",
-  themeDir: "theme",
+  sourceDir: ".",
+  mediaDir: "shared/media",
+  themeDir: "shared/theme",
   designDoc: "design.md",
-  componentsDir: "components",
+  componentsDir: "shared/components",
   publicDir: "public/openpress",
   outputDir: "dist",
   captionNumbering: {
@@ -66,10 +66,10 @@ async function readPackageOpenpressField(workspaceRoot) {
 // project isn't an OpenPress workspace.
 const CONVENTION = {
   documentDir: "press",
-  sourceDir: "chapters",
-  mediaDir: "media",
-  themeDir: "theme",
-  componentsDir: "components",
+  sourceDir: ".",
+  mediaDir: "shared/media",
+  themeDir: "shared/theme",
+  componentsDir: "shared/components",
   designDoc: "design.md",
   publicDir: "public/openpress",
   outputDir: "dist-react",
@@ -130,39 +130,39 @@ export function publicPdfHref(config) {
   return `/${config.pdf.filename}`;
 }
 
-function stringValue(value, fallback) {
-  return typeof value === "string" && value.trim() ? value.trim() : fallback;
+function stringValue(value, defaultValue) {
+  return typeof value === "string" && value.trim() ? value.trim() : defaultValue;
 }
 
-function optionalStringValue(value, fallback) {
+function optionalStringValue(value, defaultValue) {
   if (value === null) return null;
   if (typeof value === "string" && value.trim()) return value.trim();
-  return fallback;
+  return defaultValue;
 }
 
-function captionNumberingValue(value, fallback) {
+function captionNumberingValue(value, defaults) {
   const input = value && typeof value === "object" && !Array.isArray(value) ? value : {};
   return {
-    figure: optionalStringValue(input.figure, fallback.figure) ?? fallback.figure,
-    table: optionalStringValue(input.table, fallback.table) ?? fallback.table,
-    separator: typeof input.separator === "string" ? input.separator : fallback.separator,
+    figure: optionalStringValue(input.figure, defaults.figure) ?? defaults.figure,
+    table: optionalStringValue(input.table, defaults.table) ?? defaults.table,
+    separator: typeof input.separator === "string" ? input.separator : defaults.separator,
   };
 }
 
-function booleanValue(value, fallback) {
-  return typeof value === "boolean" ? value : fallback;
+function booleanValue(value, defaultValue) {
+  return typeof value === "boolean" ? value : defaultValue;
 }
 
-function fileNameValue(value, fallback) {
-  const fileName = stringValue(value, fallback);
+function fileNameValue(value, defaultValue) {
+  const fileName = stringValue(value, defaultValue);
   if (fileName.includes("/") || fileName.includes("\\") || fileName === "." || fileName === "..") {
     throw new Error(`OpenPress config pdf.filename must be a file name, got: ${fileName}`);
   }
   return fileName;
 }
 
-function relativePathValue(value, fallback) {
-  const raw = stringValue(value, fallback).replaceAll("\\", "/");
+function relativePathValue(value, defaultValue) {
+  const raw = stringValue(value, defaultValue).replaceAll("\\", "/");
   if (path.isAbsolute(raw)) throw new Error(`OpenPress config paths must be relative, got: ${raw}`);
   const normalized = path.posix.normalize(raw).replace(/^\.\//, "");
   if (!normalized || normalized === "." || normalized === ".." || normalized.startsWith("../")) {

package/engine/runtime/file-utils.mjs

@@ -21,55 +21,69 @@ export async function copyDirectory(src, dst) {
   await fs.cp(src, dst, { recursive: true });
 }
 
-export async function writeContentCss(root, targetDir, config) {
+export async function writeContentCss(root, targetDir, config, options = {}) {
   config ??= await loadConfig(root);
-  const css = await buildContentCss(root, config);
+  const css = await buildContentCss(root, config, options);
   await fs.mkdir(targetDir, { recursive: true });
   await fs.writeFile(path.join(targetDir, "content.css"), css, "utf8");
 }
 
-export async function buildContentCss(root, config) {
+export async function buildContentCss(root, config, options = {}) {
   config ??= await loadConfig(root);
-  const contentAssetsDir = config.paths.themeDir;
+  const sharedThemeDir = config.paths.themeDir;
   const parts = [];
   for (const layer of CONTENT_CSS_LAYERS) {
     if (typeof layer !== "string" && layer.type === "directory") {
-      await appendCssDirectory(parts, path.join(contentAssetsDir, layer.path), layer.path, {
+      await appendCssDirectory(parts, path.join(sharedThemeDir, layer.path), layer.path, {
         exclude: new Set(layer.exclude ?? []),
       });
       continue;
     }
     const relativePath = typeof layer === "string" ? layer : layer.path;
-    const cssPath = path.join(contentAssetsDir, relativePath);
+    const cssPath = path.join(sharedThemeDir, relativePath);
     let css;
     try {
       css = await fs.readFile(cssPath, "utf8");
     } catch (error) {
-      if (typeof layer !== "string" && layer.optional && error.code === "ENOENT") continue;
+      if (error.code === "ENOENT") continue;
       throw error;
     }
     parts.push(`/* === ${relativePath} === */\n`);
     parts.push(css.trimEnd());
     parts.push("\n\n");
   }
+  const themeRoots = uniquePaths([
+    ...(await discoverPressChildRoots(config.paths.documentRoot, "theme")),
+    ...(options.themeRoots ?? []),
+  ]);
+  for (const themeRoot of themeRoots) {
+    await appendCssDirectory(parts, themeRoot, documentRelativeLabel(themeRoot, config.paths.documentRoot));
+  }
   parts.push("/* === engine/katex.css === */\n");
   parts.push((await readKatexCss()).trimEnd());
   parts.push("\n\n");
   return parts.join("");
 }
 
-export async function writeComponentsCss(root, targetDir, config) {
+export async function writeComponentsCss(root, targetDir, config, options = {}) {
   config ??= await loadConfig(root);
-  const css = await buildComponentsCss(root, config);
+  const css = await buildComponentsCss(root, config, options);
   await fs.mkdir(targetDir, { recursive: true });
   await fs.writeFile(path.join(targetDir, "components.css"), css, "utf8");
 }
 
-export async function buildComponentsCss(root, config) {
+export async function buildComponentsCss(root, config, options = {}) {
   config ??= await loadConfig(root);
   const parts = [];
   await appendCssDirectory(parts, path.join(config.paths.themeDir, "patterns"), "theme/patterns");
-  await appendComponentScopedCss(parts, config.paths.componentsDir);
+  const componentRoots = uniquePaths([
+    config.paths.componentsDir,
+    ...(await discoverPressChildRoots(config.paths.documentRoot, "components")),
+    ...(options.componentRoots ?? []),
+  ]);
+  for (const componentsDir of componentRoots) {
+    await appendComponentScopedCss(parts, componentsDir, documentRelativeLabel(componentsDir, config.paths.documentRoot));
+  }
   return parts.join("");
 }
 
@@ -88,7 +102,7 @@ async function appendCssDirectory(parts, directory, labelPrefix, options = {}) {
   }
 }
 
-async function appendComponentScopedCss(parts, componentsDir) {
+async function appendComponentScopedCss(parts, componentsDir, labelPrefix = "components") {
   let entries;
   try {
     entries = await fs.readdir(componentsDir, { withFileTypes: true });
@@ -107,8 +121,38 @@ async function appendComponentScopedCss(parts, componentsDir) {
       }
       throw error;
     }
-    parts.push(`/* === components/${entry.name}/style.css === */\n`);
+    parts.push(`/* === ${labelPrefix}/${entry.name}/style.css === */\n`);
     parts.push(css.trimEnd());
     parts.push("\n\n");
   }
 }
+
+async function discoverPressChildRoots(documentRoot, childName) {
+  let entries;
+  try {
+    entries = await fs.readdir(documentRoot, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((entry) => entry.isDirectory() && entry.name !== "shared" && !entry.name.startsWith("."))
+    .map((entry) => path.join(documentRoot, entry.name, childName));
+}
+
+function uniquePaths(paths) {
+  const out = [];
+  const seen = new Set();
+  for (const candidate of paths ?? []) {
+    if (!candidate) continue;
+    const normalized = path.resolve(candidate);
+    if (seen.has(normalized)) continue;
+    seen.add(normalized);
+    out.push(normalized);
+  }
+  return out;
+}
+
+function documentRelativeLabel(filePath, documentRoot) {
+  const relative = path.relative(documentRoot, filePath).split(path.sep).join("/");
+  return relative && !relative.startsWith("..") ? relative : path.basename(filePath);
+}

package/engine/runtime/inspection.mjs

@@ -5,6 +5,7 @@ import { buildReactStatic, startStaticServer } from "../commands/_shared.mjs";
 import { walkFiles } from "./file-walk.mjs";
 import { createIssue, createIssueReport } from "./issue-report.mjs";
 import { collectActiveContentFiles, resolveActiveSourceWorkspace } from "./source-workspace.mjs";
+import { collectSourceTextFiles } from "./source-text-tools.mjs";
 
 const MEDIA_EXTENSIONS = new Set([".avif", ".gif", ".jpeg", ".jpg", ".png", ".svg", ".webp"]);
 const SOURCE_EXTENSIONS = new Set([".css", ".html", ".js", ".json", ".md", ".mjs", ".ts", ".tsx"]);
@@ -27,7 +28,7 @@ export async function inspectWorkspace({ root, config, options = {}, recurse = n
   });
 
   checked.push("media");
-  const mediaFiles = await readMediaFiles(sourceScan.config.paths.mediaDir);
+  const mediaFiles = await readMediaFiles(await collectInspectionMediaRoots(sourceScan.config));
   const sourceText = sourceScan.sourceFiles.map((file) => file.text).join("\n");
   const unusedMedia = mediaFiles.filter((file) => !sourceText.includes(file.name) && !sourceText.includes(file.relativePath));
   unusedMedia.forEach((file) => {
@@ -99,11 +100,7 @@ export async function collectInspectionSources(config) {
   const sourceWorkspace = await resolveActiveSourceWorkspace(config);
   const sourceConfig = sourceWorkspace.config;
   const contentFiles = await collectActiveContentFiles(sourceWorkspace);
-  const sourceFiles = [
-    ...contentFiles,
-    ...await readSourceFiles(sourceConfig.paths.componentsDir),
-    ...await readSingleFile(sourceConfig.paths.designDoc),
-  ];
+  const sourceFiles = await collectSourceTextFiles(sourceConfig, { scope: "all" });
   const componentUsage = summarizeComponentUsage(contentFiles);
 
   return {
@@ -260,20 +257,48 @@ async function readSingleFile(absolutePath) {
   }
 }
 
-async function readMediaFiles(directory) {
+async function readMediaFiles(directories) {
   const files = [];
-  await walkFiles(directory, async (absolutePath) => {
-    if (!MEDIA_EXTENSIONS.has(path.extname(absolutePath).toLowerCase())) return;
-    files.push({
-      absolutePath,
-      name: path.basename(absolutePath),
-      relativePath: path.relative(directory, absolutePath).replaceAll("\\", "/"),
+  for (const directory of directories) {
+    await walkFiles(directory, async (absolutePath) => {
+      if (!MEDIA_EXTENSIONS.has(path.extname(absolutePath).toLowerCase())) return;
+      files.push({
+        absolutePath,
+        name: path.basename(absolutePath),
+        relativePath: path.relative(directory, absolutePath).replaceAll("\\", "/"),
+      });
     });
-  });
+  }
   files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
   return files;
 }
 
+async function collectInspectionMediaRoots(config) {
+  const roots = [config.paths.mediaDir];
+  try {
+    const entries = await fs.readdir(config.paths.documentRoot, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name.startsWith(".") || entry.name === "shared") continue;
+      roots.push(path.join(config.paths.documentRoot, entry.name, "media"));
+    }
+  } catch {
+    // Missing press/ is reported by validation/export.
+  }
+  return uniquePaths(roots);
+}
+
+function uniquePaths(paths) {
+  const out = [];
+  const seen = new Set();
+  for (const candidate of paths) {
+    const normalized = path.resolve(candidate);
+    if (seen.has(normalized)) continue;
+    seen.add(normalized);
+    out.push(normalized);
+  }
+  return out;
+}
+
 function summarizeComponentUsage(contentFiles) {
   const usages = new Map();
   for (const file of contentFiles) {
@@ -373,7 +398,7 @@ function inspectionExpression() {
       });
       return {
         pageNumber: index + 1,
-        title: page.getAttribute('data-page-title') || wrapper.getAttribute('aria-label') || '',
+        title: page.getAttribute('data-page-title') || page.getAttribute('data-openpress-frame-key') || wrapper.getAttribute('aria-label') || '',
         source: sourcePath ? { file: sourceFile, path: sourcePath } : undefined,
         overflows,
       };

package/engine/runtime/page-geometry.mjs

@@ -85,8 +85,8 @@ function pageGeometry({ id, label, width, height }) {
   };
 }
 
-function cssLengthValue(value, fallback) {
-  if (value == null) return fallback ?? null;
+function cssLengthValue(value, defaultValue) {
+  if (value == null) return defaultValue ?? null;
   if (typeof value !== "string" || !value.trim()) {
     throw new Error("OpenPress page width/height must be CSS length strings.");
   }
@@ -97,16 +97,16 @@ function cssLengthValue(value, fallback) {
   return trimmed;
 }
 
-function optionalId(value, fallback) {
-  if (value == null) return fallback;
+function optionalId(value, defaultValue) {
+  if (value == null) return defaultValue;
   if (typeof value !== "string" || !/^[a-z0-9][a-z0-9-]*$/i.test(value)) {
     throw new Error("OpenPress page id must be a simple slug.");
   }
   return value;
 }
 
-function optionalLabel(value, fallback) {
-  if (value == null) return fallback;
+function optionalLabel(value, defaultValue) {
+  if (value == null) return defaultValue;
   if (typeof value !== "string" || !value.trim()) {
     throw new Error("OpenPress page label must be a non-empty string.");
   }