@open-press/cli 0.7.0 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-press/cli",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "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,25 @@
 # @open-press/core
 
+## 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/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/react/document-export.mjs

@@ -92,6 +92,21 @@ export async function exportReactDocument(root = ".", { syncAssets = true } = {}
         blockHeights: measurement.blockHeights,
         sources,
       });
+      if (process.env.OPENPRESS_DEBUG_ALLOC) {
+        const sample = measurement.mdxAreas
+          .slice(0, 5)
+          .map((a) => `${a.frameKey}#${a.indexInFrame} cap=${a.capacity.toFixed(0)} raw=${(a.rawHeight ?? 0).toFixed(0)}`);
+        const blocks = measurement.blockHeights
+          .slice(0, 8)
+          .map((b) => `${b.id} h=${b.height.toFixed(0)}`);
+        process.stderr.write(`[allocator iter ${iteration}]\n`);
+        process.stderr.write(`  mdxAreas[0..4]: ${sample.join(" | ")}\n`);
+        process.stderr.write(`  blocks[0..7]:   ${blocks.join(" | ")}\n`);
+        process.stderr.write(`  hints:          ${JSON.stringify(alloc.hints.totalPagesPerChain)}\n`);
+        if (alloc.warnings.length > 0) {
+          process.stderr.write(`  warnings:       ${JSON.stringify(alloc.warnings)}\n`);
+        }
+      }
       if (hintsEqual(hints, alloc.hints)) {
         allocation = alloc.allocation;
         warnings = alloc.warnings;

package/template/core/engine/react/mdx-compile.mjs

@@ -99,6 +99,16 @@ export function rehypeBlockIds(options = {}) {
           includeBlockIds,
         });
       }
+      if (block.name === "ul" || block.name === "ol") {
+        return applyListItemBlocks({
+          node,
+          id,
+          blocks,
+          filePath,
+          chapterSlug,
+          includeBlockIds,
+        });
+      }
       if (includeBlockIds && !includeBlockIds.has(id)) return false;
 
       setDataAttribute(node, "data-openpress-block-id", id);
@@ -314,6 +324,87 @@ function blockInfo(node) {
   return null;
 }
 
+function applyListItemBlocks({
+  node,
+  id,
+  blocks,
+  filePath,
+  chapterSlug,
+  includeBlockIds,
+}) {
+  const items = listItems(node);
+  if (items.length === 0) {
+    if (includeBlockIds && !includeBlockIds.has(id)) return false;
+    setDataAttribute(node, "data-openpress-block-id", id);
+    blocks.push({
+      id,
+      kind: "element",
+      name: node.tagName,
+      text: textContent(node).trim() || undefined,
+      filePath,
+      chapterSlug,
+      source: sourcePosition(node.position),
+    });
+    return "skip";
+  }
+
+  const itemRecords = items.map((item, index) => ({
+    id: `${id}-i${index}`,
+    node: item,
+    index,
+  }));
+  const selected = includeBlockIds
+    ? itemRecords.filter((item) => includeBlockIds.has(item.id))
+    : itemRecords;
+  if (selected.length === 0) return false;
+
+  setDataAttribute(node, "data-openpress-list-id", id);
+
+  // For ordered lists, continuation pages must keep numbering picking up
+  // from the first surviving item. `start` is the 1-based number of the
+  // first `<li>` rendered, so if the original list had `start="5"` and we
+  // dropped the first three items, continuation starts at 5 + 3 = 8.
+  if (node.tagName === "ol" && selected[0]?.index > 0) {
+    const baseStart = Number(node.properties?.start ?? 1);
+    const continuationStart = baseStart + selected[0].index;
+    node.properties = { ...node.properties, start: continuationStart };
+  }
+
+  const selectedNodes = new Set(selected.map((item) => item.node));
+  pruneUnselectedListItems(node, new Set(itemRecords.map((item) => item.node)), selectedNodes);
+
+  for (const item of selected) {
+    setDataAttribute(item.node, "data-openpress-block-id", item.id);
+    blocks.push({
+      id: item.id,
+      kind: "list-item",
+      name: "list-item",
+      text: textContent(item.node).trim() || undefined,
+      filePath,
+      chapterSlug,
+      listId: id,
+      listTag: node.tagName,
+      itemIndex: item.index,
+      source: sourcePosition(item.node.position ?? node.position),
+    });
+  }
+  return "skip";
+}
+
+function listItems(list) {
+  if (list?.type !== "element") return [];
+  if (list.tagName !== "ul" && list.tagName !== "ol") return [];
+  return (list.children ?? []).filter((child) => child?.type === "element" && child.tagName === "li");
+}
+
+function pruneUnselectedListItems(node, itemNodes, selectedNodes) {
+  if (!Array.isArray(node?.children)) return;
+  node.children = node.children.filter((child) => {
+    if (!itemNodes.has(child)) return true;
+    return selectedNodes.has(child);
+  });
+}
+
 function tableBodyRows(table) {
   if (table?.type !== "element" || table.tagName !== "table") return [];
   const rows = [];

package/template/core/engine/react/pipeline/frame-measurement.mjs

@@ -135,15 +135,30 @@ async function runChromiumMeasurement(html, viewport) {
   try {
     const page = await browser.newPage({ viewport });
     await page.setContent(html, { waitUntil: "load" });
+    // Match the print-ready settle: fonts first (font metrics affect image
+    // alt-text fallback boxes), then await every image's `complete` AND
+    // `decode()` so intrinsic sizes are committed before layout, then two
+    // animation frames so the chromium layout pass observes the final box
+    // model. Without this, `getBoundingClientRect()` on figures that hold
+    // images can race the decode and return collapsed heights, causing the
+    // allocator to pack too many blocks per page.
     await page.evaluate(async () => {
-      await Promise.all(Array.from(document.images).map((img) => {
-        if (img.complete) return Promise.resolve();
-        return new Promise((resolve) => {
-          img.addEventListener("load", resolve, { once: true });
-          img.addEventListener("error", resolve, { once: true });
-        });
-      }));
       if (document.fonts?.ready) 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(undefined);
+            };
+            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 mdxAreas = await page.evaluate((safety) => {
@@ -232,13 +247,27 @@ async function inlineMeasurementMediaUrls(html, mediaDir) {
   if (!mediaDir || !html) return html;
   let out = String(html);
   const matches = new Set();
-  for (const match of out.matchAll(/\/openpress\/media\/([^"')\s>]+)/g)) {
-    matches.add(match[1]);
+  for (const match of out.matchAll(/\bsrc=(['"])([^\1]*?)\1/g)) {
+    const src = match[2];
+    if (!src) continue;
+    if (src.startsWith('/openpress/media/')) {
+      matches.add(src.slice('/openpress/media/'.length));
+      continue;
+    }
+    if (src.startsWith('media/')) {
+      matches.add(src.slice('media/'.length));
+      continue;
+    }
+    if (src.startsWith('./media/')) {
+      matches.add(src.slice('./media/'.length));
+    }
   }
   for (const rawName of matches) {
     const dataUrl = await mediaDataUrl(mediaDir, rawName);
     if (!dataUrl) continue;
     out = out.replaceAll(`/openpress/media/${rawName}`, dataUrl);
+    out = out.replaceAll(`media/${rawName}`, dataUrl);
+    out = out.replaceAll(`./media/${rawName}`, dataUrl);
   }
   return out;
 }

package/template/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-press/core",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "type": "module",
   "description": "open-press core — runtime primitives, CLI, and render pipeline for AI-first fixed-layout documents.",
   "license": "MIT",

package/template/packs/academic-paper/document/chapters/01-introduction/content/01-introduction.mdx

@@ -1,21 +1,35 @@
 ## Introduction
 
-This document is a model and starting point for an academic paper drafted in open-press. The structure follows the IEEE conference template conventions where they make sense for screen-first reading: numbered sections, italic sub-sections, an abstract block, and a numbered references list. The two-column body of IEEEtran is not yet supported — single-column will land as the v0.8 paged.js migration arrives.
+The purpose of this paper template is to provide a compact, readable structure for a
+machine-learning research manuscript written in a formal journal style.
 
-Use this pack for **drafting, iteration, and preprint distribution**. When the paper is ready for venue submission, export the prose into the publisher's required LaTeX class (`IEEEtran`, `acmart`, etc.). The pack does not replace LaTeX for camera-ready submission; it replaces the awkward iteration loop *before* submission.
+### Background and Motivation
 
-### Where to start
+Recent studies have shown that modern experiments produce larger datasets and richer
+artifact pipelines, but the writing process is often bottlenecked by repeated formatting
+adjustments. A lightweight drafting layer can decouple scientific reasoning from
+typesetting concerns and let the author focus on experimental validity first.
 
-Each chapter directory under `document/chapters/` is one paper section:
+### Problem Statement
 
-- `01-introduction/` — motivate the work, state the contribution, summarise the structure.
-- `02-methods/` — describe what you did, with enough detail to reproduce.
-- `03-results-and-discussion/` — present results with figures and tables; interpret what they mean.
-- `04-acknowledgment/` — acknowledge funding, collaborators, reviewers.
-- `05-references/` — numbered `[1]`, `[2]` references.
+The key challenge addressed in this draft is to keep the manuscript internally
+consistent while moving from scratch notes to a submission-ready narrative. The
+workflow should preserve section hierarchy, citation order, and figure/table integrity
+without requiring manual renumbering.
 
-Replace each chapter's MDX content with your own. The skeleton text below each `##` heading is illustrative — overwrite it.
+### Contribution
 
-### Abstract and Index Terms
+This demo paper includes the following contributions:
 
-Edit the abstract and index terms inside `document/index.tsx` (the `cover` JSX export). They render on the title page above the body. Keep the abstract under 250 words and avoid abbreviations, symbols, or math in it.
+- A reproducible chapter flow (`Introduction → Methods → Results and Discussion →
+  Conclusion`),
+- Consistent heading levels for major and minor sections,
+- Placeholder media and tables that can be swapped with real results,
+- A reference block and placeholder metadata for a clean handoff to final publication
+  tooling.
+
+### Paper Organization
+
+The paper is organized as follows: Section 2 details the methodology,
+Section 3 reports results and discusses representative scenarios,
+Section 4 summarizes conclusions and practical recommendations.

package/template/packs/academic-paper/document/chapters/02-methods/content/01-methods.mdx

@@ -1,30 +1,50 @@
 ## Methods
 
-Describe the materials, instruments, datasets, models, or procedures you used. Anyone familiar with the field should be able to reproduce your work from this section.
+This section describes a hypothetical experimental design suitable for an applied
+machine-learning paper.
 
-### Apparatus and Materials
+### Data and Problem Setup
 
-Specify hardware, software versions, datasets, and any pre-processing. Cite reused work using `[N]` numeric references (e.g. "we trained the encoder following the procedure of [3]").
+We assume a synthetic dataset with 3,200 anonymized samples collected under three
+operational conditions. Each sample includes paired feature vectors, timestamped
+metadata, and a binary outcome label. The baseline split is 70/15/15 for training,
+validation, and held-out test sets.
 
-### Procedure
+### Core Pipeline
 
-Describe the experimental procedure as steps a reader could follow:
+The pipeline has three stages:
 
-1. State the input data and pre-processing.
-2. State the model / algorithm / instrument settings.
-3. State the evaluation metric(s) and any held-out splits.
-4. State randomness control (seeds, repeats, confidence reporting).
+1. **Preprocessing**: normalization, missing-value handling, and feature screening.
+2. **Modeling**: training a compact baseline model and a comparison ablation set.
+3. **Evaluation**: calibration-aware scoring and bootstrapped confidence intervals.
 
-### Notation
+For this draft, preprocessing includes clipping extreme values and aligning all
+continuous fields to SI-style unit notation.
 
-Define notation early. Italicise Roman symbols for quantities and variables, but not Greek symbols. Use a long dash rather than a hyphen for a minus sign. Number equations consecutively:
+### Equations
 
-$$a + b = \gamma \tag{1}$$
+The main objective is written as:
 
-Refer to equations by `(1)`, not `Eq. (1)` or `equation (1)`, except at the start of a sentence: "Equation (1) shows ...".
+$$
+\mathcal{L}(\theta) = \sum_{i=1}^{N}\left(\hat{y}_{i}(\theta)-y_{i}\right)^2
+$$
 
-### Reporting Units
+where $\theta$ are trainable parameters and the objective is minimized on the
+training subset.
 
-- Use SI (MKS) as primary units; English units only as secondary (in parentheses).
-- Don't mix complete spellings and abbreviations: "Wb/m²" or "webers per square meter", not "webers/m²".
-- Use a zero before decimal points: `0.25`, not `.25`.
+### Evaluation Protocol
+
+Model quality is measured by macro-averaged F1, AUROC, and an uncertainty-aware
+calibration score. Reproducibility is ensured by fixing the random seed and logging
+all preprocessing parameters.
+
+### Implementation Notes
+
+- All runs were executed on a dual-socket compute node with two GPUs.
+- Checkpoints were stored every 5 epochs.
+- Logging followed a single JSON schema shared across all experiments.
+
+### Validation and Quality Control
+
+Validation is automated through a script that checks missing captions, file path
+consistency, and reference formatting before final export.

package/template/packs/academic-paper/document/chapters/03-results-and-discussion/content/01-results.mdx

@@ -1,29 +1,47 @@
 ## Results and Discussion
 
-Present the findings of your study, then interpret what they mean for the research question stated in the introduction.
+### Benchmark Results
 
-### Quantitative Results
+The synthetic experiment yields a consistent improvement trend across three datasets.
+Performance gains are modest but stable after hyperparameter tuning.
 
-Use a table to summarise results across conditions. Caption above the table.
+| Metric | Baseline | Proposed | Improvement |
+| --- | --- | --- | --- |
+| Macro-F1 | 0.61 | 0.67 | +9.8% |
+| AUROC | 0.74 | 0.81 | +9.5% |
+| Calibration Error | 0.082 | 0.043 | -47.6% |
 
-<TableCaption>Sample comparison of conditions.</TableCaption>
+The proposed model retains a similar variance profile while improving score
+stability in low-sample conditions.
 
-| Condition | Metric A | Metric B | Notes |
-| --- | --- | --- | --- |
-| Baseline | 0.71 | 0.65 | Prior work [3] |
-| Ours (v1) | 0.78 | 0.69 | This work |
-| Ours (v2) | **0.83** | **0.72** | Best |
+### Representative Visualization
+
+<img
+  src="media/figure-placeholder.svg"
+  alt="Example of a figure placeholder"
+  style={{ maxWidth: "420px", width: "100%", height: "auto" }}
+/>
+
+Figure 1. Example of a result trend visualization (placeholder image).
+
+### Error Analysis
 
-Cite figures and tables in the text the first time they appear: "Fig. 1 shows the architecture", "Table I summarises the conditions". Use `Fig.` even at the start of a sentence; spell out `Figure` only when it is the subject.
+Some error cases cluster around edge classes with incomplete metadata. These cases
+benefit from better augmentation and a revised class-balanced loss.
 
-### Qualitative Discussion
+### Sensitivity Study
 
-Discuss what the results mean. State the limitations honestly — if the experiment doesn't cover a case you'd like to claim, say so. Avoid the word "essentially" when you mean "approximately" or "effectively".
+- Training set size below 40% causes a steeper drop in recall.
+- Early stopping thresholds above 3 epochs reduce overfitting in our setting.
+- Calibrated post-processing improves confidence robustness.
 
-### Threats to Validity
+### Discussion
 
-Briefly list what could invalidate the results: small sample size, single dataset, environmental drift, evaluator bias, etc. Reviewers will look for this section; pre-empt it.
+The most practical takeaway is that small engineering changes in preprocessing and
+evaluation discipline can produce measurable gains even when architecture changes are
+minimal.
 
-### Future Work
+### Limitations
 
-Indicate where the work goes next. Keep this to one short paragraph — over-claiming future scope hurts more than it helps in review.
+This section reports synthetic results only; real-world deployment would require
+cross-domain validation, privacy checks, and a stronger external benchmark suite.