@open-press/cli 0.7.0 → 0.8.0

package/README.md

@@ -2,6 +2,10 @@
 
 Scaffolder for [open-press](https://github.com/quan0715/open-press) — an AI-first fixed-layout document workspace.
 
+## Prerequisite
+
+Node.js 20 or newer with `npm` / `npx`.
+
 ## Quick start
 
 ```bash
@@ -20,7 +24,7 @@ npx @open-press/cli init <target> [flags]
 
 | Flag                 | Description                                                                 |
 | -------------------- | --------------------------------------------------------------------------- |
-| `--pack <name>`      | Style pack starter: `editorial-monograph` or `claude-document`              |
+| `--pack <name>`      | Style pack starter: `editorial-monograph`, `claude-document`, or `academic-paper` |
 | `--title <s>`        | Document title (written to `openpress.config.mjs`)                          |
 | `--subtitle <s>`     | Document subtitle                                                           |
 | `--organization <s>` | Organization name                                                           |
@@ -46,6 +50,7 @@ Workspace commands (run via `npm run` or `node engine/cli.mjs`):
 
 ```
 npm run dev         # start workbench
+npm run openpress:export   # refresh public/openpress/document.json
 npm run build       # render production output (dist-react/)
 npm run preview     # preview production build
 npm run openpress:validate   # structural checks

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-press/cli",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "description": "Scaffolder for open-press — AI-first fixed-layout document workspaces.",
   "license": "MIT",

package/template/core/AGENTS.md

@@ -0,0 +1,126 @@
+# Working on this open-press workspace
+
+This directory is an **open-press workspace** scaffolded by
+`@open-press/cli`. You (the agent) own:
+
+- `document/` — chapters (MDX), components, theme, media. The actual content.
+- `package.json` / `openpress.config.mjs` — project metadata + build config.
+- `.agents/skills/` — agent skills installed by `npx skills` (auto-refreshed via `npx open-press upgrade`).
+
+The rest of the tree is the open-press framework copied at scaffold time
+(`engine/`, `src/`, `vite.config.ts`, etc). Treat it as vendored — don't
+hand-edit unless the user explicitly asks; the next `npx open-press upgrade`
+will rewrite it.
+
+## Quick reference
+
+```bash
+npm run dev                  # workbench at http://127.0.0.1:5173/?dev=1
+npm run openpress:validate   # structural checks
+npm run openpress:render     # full render through chromium
+npm run openpress:pdf        # write document.pdf
+npm run openpress:export     # write public/openpress/document.json
+npm run openpress:deploy     # deploy via the configured adapter
+npx open-press doctor        # current vs latest version + pending migrations
+npx open-press upgrade       # apply the upgrade flow (see below)
+```
+
+## When the user asks to upgrade
+
+Triggers: "升級 / 套件更新 / upgrade open-press / apply latest design /
+update to vX.Y.Z" etc.
+
+**Follow the upgrade SOP, do NOT manually diff template versions:**
+
+1. `npx open-press doctor` — confirm current vs latest, count pending
+   migrations.
+2. Ask the user "go ahead?" — briefly mention what will change (deps,
+   skills, migrations to read).
+3. `npx open-press upgrade` — refreshes `@open-press/core`, refreshes
+   installed skills, **fetches migration notes for each pending version
+   into `.openpress/migrations/<version>.md`** and lists the paths.
+4. For each migration file listed, read it fully. Each has a
+   `Document-level changes` section with `rg` find + rewrite rules.
+   Apply to `document/` with user confirmation.
+5. Verify:
+   ```bash
+   npm run openpress:validate
+   npm run openpress:render
+   ```
+   Fix anything broken using the migration notes.
+6. Report to the user: starting version → ending version, what was
+   applied, anything that needed manual judgement.
+
+**Anti-pattern**: running `npx @open-press/cli@latest init` somewhere
+and manually diffing against the workspace. The migration notes are the
+authoritative source for what changed; fresh templates ship default
+content that does not apply to a customised workspace.
+
+## When the user says "I changed X but the page didn't update"
+
+Common cause: **the reader renders from a static `public/openpress/document.json`,
+not from your live MDX / theme files.** Vite Hot Reload covers React UI
+chrome (workbench panels, inspector, navigation) but it does **not**
+regenerate `document.json`. So edits to:
+
+- `document/chapters/**/*.mdx` (prose)
+- `document/index.tsx` (Press tree, Cover/BackCover JSX)
+- `document/components/**/*.tsx` (Page, openers, custom components)
+- `document/theme/**` style files that affect pagination capacity
+- `openpress.config.mjs` metadata (title, captionNumbering, …)
+
+…all need a re-export before the workbench / public viewer reflect
+the change:
+
+```bash
+npm run openpress:export   # regenerate public/openpress/document.json
+# then refresh the browser
+```
+
+Quick rules of thumb:
+
+- Pure CSS edits under `document/theme/` that don't move blocks → HMR
+  is enough (CSS is hot-replaced).
+- Anything that affects content, pagination, or metadata → re-export.
+- `npm run openpress:render` is `export` + extra asset sync; either
+  works to refresh the JSON.
+
+**Agent SOP**: after applying any non-CSS edit to `document/`, run
+`npm run openpress:export` before telling the user "done". If they ask
+"why didn't my change show up?", check whether `document.json` was
+regenerated since the edit.
+
+## When the user reports a render / paginate issue
+
+Press Tree paginates at build time. Common things to check:
+
+1. `npm run openpress:export` then inspect
+   `public/openpress/document.json` for `source.warnings` (chain
+   overflow, missing chains, etc.).
+2. `npm run openpress:validate` for structural issues
+   (missing entries, broken anchors).
+3. `npm run dev` and use the workbench inspector to find which MDX
+   block / Frame element is misbehaving — comments and inline
+   annotations work directly from there.
+
+## Skills
+
+This workspace ships agent skills under `.agents/skills/`. If your
+platform supports skills (Claude Code, Cursor, Codex, Cline, Gemini
+CLI, …), prefer invoking them over re-reading this file:
+
+- `openpress` — operate the workspace (CLI, validate, export, render,
+  PDF, deploy, search/replace, comments, upgrades, routing).
+- `openpress-writing` — writing-time rules for MDX prose.
+- `openpress-design` — theme tokens, layout, page surfaces.
+- `openpress-deploy` — deployment workflows.
+- `openpress-init` — scaffolding new workspaces.
+- Plus any style-pack-specific skills installed by the user.
+
+Skills are kept in sync by `npx skills upgrade` (run automatically
+inside `npx open-press upgrade`).
+
+## Reporting issues
+
+- Issues / questions: https://github.com/quan0715/open-press/issues
+- Source: https://github.com/quan0715/open-press

package/template/core/CHANGELOG.md

@@ -1,5 +1,70 @@
 # @open-press/core
 
+## 0.8.0
+
+### Minor Changes
+
+- **Workbench architecture**: the monolithic `workbench.tsx` is split into a modular structure under `workbench/{shell,panels,actions,inspector,mentions,project,document}/`. New panels: `DeploymentControl`, `SearchControl`, `PendingCommentsPanel`, `DocumentPanel`, `ProjectEntryPanel`, plus `WorkbenchShell` and `InlineInspectorLayer`.
+- **Module reorganization**: source tree split into typed subdirectories:
+  - `app/`: `OpenPressApp`, `OpenPressRuntime` (replaces the old `App.tsx` + `renderer.tsx`)
+  - `document-model/`: `anchorMap`, `documentIndexes`, `documentTypes`, `objectEntityModel`, `projectIdentity`, `reactDocumentMetadata`
+  - `reader/`: `PublicReaderPage`, `ReaderNavigationPanel`, `useReaderRuntime`, registry/route/scroll/state helpers
+  - `shared/`: `frameScheduler`, `runtimeMode`, `Panel`, `numberUtils`
+- **Object-entity model**: `Frame` and `MdxArea` now expose `data-openpress-object-id`. New `document-model/objectEntityModel` defines the id format.
+- **`MediaFigure` / `ImageFigure`**: new core primitives that accept `src/alt/caption` and resolve relative paths to `/openpress/media/...` automatically.
+- **`<Sections>` default page**: `page` prop becomes optional; when omitted the built-in `DefaultSectionPage` renders the standard manuscript frame.
+- **Engine helpers**: new `engine/react/{http-json,object-entities,source-edit-endpoint}.mjs` and `engine/runtime/{file-walk,path-utils}.mjs` runtime helpers. `engine/runtime/source-text-tools` exports TypeScript definitions.
+- **Dev endpoints**: vite plugin wires `/__openpress/search` and `/__openpress/source-edit` middlewares for the new workbench search + inline editing flows.
+- **Inline source editor**: ships the `InlineSourceEditorLayer` UI on top of `useInlineDocumentEditor` + `/__openpress/source-edit`. The hook now uses a `MutationObserver` so newly inserted blocks become editable, and routes mouse clicks through `focus()` to preserve selection on `contenteditable` boundaries. Workbench wires `sourceEditorTarget` state into the layer.
+- **Table editing in the source pipeline**: table captions are emitted as standalone source blocks (`kind=element`, `name=caption`, `layout="attached"`) with `data-openpress-block-id`/`data-openpress-object-id` markers and preserved source positions; the allocator treats `layout="attached"` blocks as non-paginable. `applySourceBlockTableCellEditToText` (in `engine/runtime/source-text-tools`) accepts a `cellIndex` so the inline source editor can target a single `<td>`.
+- **Reader pagination**: arrow-key pagination now defers to the user's active text selection. Shift-arrow / mouse-drag selections no longer get swallowed by the page-turn shortcut.
+- **Page zoom + spread layout**: new `reader/pageViewportScaleModel` + `usePageViewportScale` hook drive a `--openpress-page-viewport-scale` CSS variable on the page container; the workbench toolbar exposes a `PageZoomControl` dropdown with fit-width / fit-page / fixed percentages plus a one-page / two-page spread toggle.
+- **Inspector cell-precision comments**: `CommentDraft` gains an optional `targetObjectId` so a comment can point at a sub-block (e.g. a single table cell) while still attributing the source position to its enclosing block. `formatInspectorHint` carries the value through to the wire hint.
+- **Shared `WorkbenchDialog` shell**: portal + backdrop + header (eyebrow / title / title-meta / close) + optional footer. `DeploymentControl`, `SearchControl`, and `ProjectPreviewDialog` all render through this shell now, replacing the prior per-dialog scaffolding under `openpress-deploy-dialog-*` / `openpress-search-dialog-*` / `openpress-project-preview-dialog__*`.
+- **`WorkbenchControlPanel` registry**: `HtmlWorkbench` now accepts an `extraControlPanels?: WorkbenchPanel[]` prop and renders the right-side panel from a `{ id, render }` registry. Built-in panels (pending comments, project entry) ship as the first entries.
+- **Workbench state hooks**: extract `useDeploymentWorkbench` and `useInspectorComments` from `HtmlWorkbench`; `useReaderRuntime` is split into focused sub-hooks (`usePanelState`, `useReaderScrollAnchor`, `useReaderHashSync`, `useReaderKeyboardNav`).
+- **`InlineInspectorLayer` memoization**: now wrapped in `React.memo` with a stable `geometryVersion` prop so the geometry / event listeners no longer rebuild on every parent render.
+- **Panels open lazily**: `usePanelState` now defaults both panels closed, so the reader opens with a clean stage; resize never auto-opens them.
+
+### Patch Changes
+
+- Inspector: fix comment-marker count and multi-target marker rendering.
+- Inspector: object-entity id helpers consolidate in `document-model/objectEntityModel` instead of being duplicated inside `Frame`, `MdxArea`, manuscript `TocArea`, and `PublicReaderPage`.
+- Inline editor: `useInlineDocumentEditor` exposes `onDocumentEdited`; `OpenPressApp` re-loads `/openpress/document.json` after a successful inline edit so derived indexes stay in sync.
+- Dev: reset Vite optimizer cache so workspace-side dependencies are picked up.
+- Workbench dialog: viewport-aware width + max-height so a big media preview doesn't blow up the dialog to full screen.
+- Project composer: add `/apply-comments` to the skill mention list so pending comment resolution can be invoked from the workbench.
+- Carries forward the 0.7.1 measurement + pagination fixes (font/image readiness, relative media src inlining, list-per-item paging, `OPENPRESS_DEBUG_ALLOC`, academic-paper starter body overflow).
+
+### Breaking Changes
+
+- `FrameContext.consumeArea(chainId)` return type changes from `ReactNode | null` to `{ indexInFrame: number; blocks: ReactNode | null }`. Custom `Frame` consumers must read `.blocks`.
+- `App` export is renamed to `OpenPressApp` and now lives under `@open-press/core/app`. The old `renderer.tsx` is replaced by `OpenPressRuntime`.
+- `data-openpress-mdx-area-empty` is now always emitted (`"true"` / `"false"`). Selectors that relied on the attribute being absent need updating.
+- Reader `ViewMode` collapses to `"paged"` only — the legacy `"reading"` flow mode is removed. Use `usePageViewportScale` for free-scaling instead.
+- Several internal module paths moved into subdirectories (`document-model/`, `reader/`, `shared/`, `workbench/...`). Consumers that deep-imported from the openpress source must switch to the new barrels.
+- Shared dialog scaffolding (backdrop, container, header, close button) moved from per-dialog class families (`openpress-deploy-dialog-backdrop`, `__panel`, `__panel header`, `__close`, etc.) to the shared `openpress-workbench-dialog*` family. Per-dialog modifier classes (`openpress-deploy-dialog`, `openpress-search-dialog`, `openpress-project-preview-dialog`) are still applied for dialog-specific styling. Selectors that targeted the old scaffolding names (notably `*-backdrop` and `__panel`) need updating; selectors that combine the modifier class with new `__heading` / `__footer` / `__close` modifiers continue to work.
+
+## 0.7.1
+
+### Patch Changes
+
+- Measurement pipeline + pagination fixes:
+
+  - **Measurement**: wait on `document.fonts.ready`, image `load`/`error` + `decode()`,
+    and two `requestAnimationFrame` ticks before sampling block heights so figures
+    no longer under-measure on cold loads.
+  - **Measurement**: inline relative `media/`, `./media/`, and `/openpress/media/`
+    image sources during the SSR measurement pass (previously only the absolute
+    `/openpress/media/...` form was rewritten, leaving relative refs as broken).
+  - **MDX compile**: split bullet/numbered lists into per-item paginable blocks
+    so long lists can break across pages without losing ordered numbering.
+  - **Debug**: new `OPENPRESS_DEBUG_ALLOC` env var prints per-iteration allocator
+    state (mdxArea capacities, block heights, pagination hints, warnings).
+  - **Academic-paper starter**: `<MdxArea overflow="extend">` on the body and the
+    single-column `.reader-page--content .page-body` override removed so content
+    paginates naturally with the new allocator.
+
 ## 0.7.0
 
 ### Minor Changes

package/template/core/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/template/core/engine/commands/upgrade.mjs

@@ -1,9 +1,15 @@
 import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { diagnose } from "./doctor.mjs";
 import { runCommand } from "./_shared.mjs";
 
+// Migration notes live in the framework repo, not in scaffolded workspaces.
+// `npx open-press upgrade` fetches the notes for each pending version and
+// caches them under `.openpress/migrations/` so agents can read locally.
+const MIGRATION_REMOTE_BASE = "https://raw.githubusercontent.com/quan0715/open-press/main/docs/migrations";
+const MIGRATION_CACHE_DIR = path.join(".openpress", "migrations");
+
 export async function run({ root, options }) {
   const dryRun = Boolean(options?.dryRun);
   const skipSkills = Boolean(options?.noSkills);
@@ -85,7 +91,11 @@ export async function run({ root, options }) {
     process.stdout.write("  (no migration docs in this version range)\n\n");
   } else {
     for (const m of migrationContents) {
-      process.stdout.write(`  ─ ${m.path}\n`);
+      if (m.path) {
+        process.stdout.write(`  ─ ${m.path}${m.fetched ? "  (fetched from github)" : ""}\n`);
+      } else {
+        process.stdout.write(`  ─ ${m.version}.md  (not found locally or on github — check the repo manually)\n`);
+      }
     }
     process.stdout.write(
       "\nAgent: open each file, identify document-level changes, grep document/ for affected patterns, propose edits before applying.\n",
@@ -107,11 +117,43 @@ async function hasCoreDep(root) {
 
 async function loadMigrations(root, versions) {
   const results = [];
+  const cacheDir = path.join(root, MIGRATION_CACHE_DIR);
+  await mkdir(cacheDir, { recursive: true });
+
   for (const v of versions) {
-    const p = path.join(root, "docs", "migrations", `${v}.md`);
-    if (existsSync(p)) {
-      results.push({ version: v, path: path.relative(root, p) });
+    // Framework repo has docs/migrations/ at root — prefer local if present
+    // (covers the open-press framework repo itself acting as a workspace).
+    const localDocsPath = path.join(root, "docs", "migrations", `${v}.md`);
+    if (existsSync(localDocsPath)) {
+      results.push({ version: v, path: path.relative(root, localDocsPath), fetched: false });
+      continue;
+    }
+
+    // Otherwise fetch from GitHub raw and cache to .openpress/migrations/.
+    const cachedPath = path.join(cacheDir, `${v}.md`);
+    if (existsSync(cachedPath)) {
+      results.push({ version: v, path: path.relative(root, cachedPath), fetched: false });
+      continue;
+    }
+
+    const body = await fetchMigration(v);
+    if (body) {
+      await writeFile(cachedPath, body, "utf8");
+      results.push({ version: v, path: path.relative(root, cachedPath), fetched: true });
+    } else {
+      results.push({ version: v, path: null, fetched: false });
     }
   }
   return results;
 }
+
+async function fetchMigration(version) {
+  const url = `${MIGRATION_REMOTE_BASE}/${version}.md`;
+  try {
+    const res = await fetch(url, { headers: { Accept: "text/plain" } });
+    if (!res.ok) return null;
+    return await res.text();
+  } catch {
+    return null;
+  }
+}

package/template/core/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/template/core/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/template/core/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/template/core/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/template/core/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: {