@open-press/cli 0.5.0 → 0.6.0

package/dist/cli.js

@@ -19,6 +19,41 @@ import path from "path";
 import { Readable } from "stream";
 import { pipeline } from "stream/promises";
 import { x as extract } from "tar";
+async function degit({ owner, repo, ref = "main", dest, subdir }) {
+  const url = `https://codeload.github.com/${owner}/${repo}/tar.gz/refs/heads/${ref}`;
+  const tmpDir = await mkdir(path.join(tmpdir(), `open-press-degit-${Date.now()}`), { recursive: true });
+  const tarballPath = path.join(tmpDir, "repo.tar.gz");
+  try {
+    await fetchTo(url, tarballPath);
+    await mkdir(dest, { recursive: true });
+    const subdirSegments = subdir ? subdir.split("/").filter(Boolean).length : 0;
+    const totalStrip = 1 + subdirSegments;
+    const filterPrefix = subdir ? subdir.replace(/\/$/, "") + "/" : null;
+    await extract({
+      file: tarballPath,
+      cwd: dest,
+      strip: totalStrip,
+      filter: (filePath) => {
+        const segments = filePath.split("/");
+        const inside = segments.slice(1).join("/");
+        if (filterPrefix) {
+          return inside.startsWith(filterPrefix);
+        }
+        return true;
+      }
+    });
+  } finally {
+    await rm(tmpDir, { recursive: true, force: true }).catch(() => {
+    });
+  }
+}
+async function fetchTo(url, destFile) {
+  const res = await fetch(url, { redirect: "follow" });
+  if (!res.ok || !res.body) {
+    throw new Error(`Failed to fetch ${url}: ${res.status} ${res.statusText}`);
+  }
+  await pipeline(Readable.fromWeb(res.body), createWriteStream(destFile));
+}
 async function pathIsEmpty(target) {
   try {
     const s = await stat(target);
@@ -80,14 +115,14 @@ async function patchPackageJsonName(packagePath, newName) {
 }
 
 // src/init.ts
-var KNOWN_PACKS = ["editorial-monograph", "claude-document"];
-var SKILLS_SOURCE = "quan0715/open-press";
+var BUNDLED_PACKS = ["editorial-monograph", "claude-document", "academic-paper"];
+var FRAMEWORK_SKILLS_SOURCE = "quan0715/open-press";
 var __dirname = path2.dirname(fileURLToPath(import.meta.url));
 var TEMPLATE_ROOT = path2.resolve(__dirname, "..", "template");
 var TEMPLATE_CORE = path2.join(TEMPLATE_ROOT, "core");
 var TEMPLATE_PACKS = path2.join(TEMPLATE_ROOT, "packs");
 async function init(options) {
-  validatePack(options.pack);
+  const packSpec = options.pack ? parsePackSpec(options.pack) : null;
   ensureTemplateBundled();
   const target = path2.resolve(process.cwd(), options.target);
   await ensureTarget(target, options.force);
@@ -95,17 +130,40 @@ async function init(options) {
   log("Copying framework (engine + runtime + config)\u2026");
   await cp(TEMPLATE_CORE, target, { recursive: true });
   const docDest = path2.join(target, "document");
-  if (options.pack) {
-    log(`Applying style pack: ${options.pack}`);
-    await rm2(docDest, { recursive: true, force: true });
-    await mkdir2(docDest, { recursive: true });
-    const packStarter = path2.join(TEMPLATE_PACKS, options.pack, "document");
+  await rm2(docDest, { recursive: true, force: true });
+  await mkdir2(docDest, { recursive: true });
+  if (packSpec?.kind === "bundled") {
+    log(`Applying bundled style pack: ${packSpec.name}`);
+    const packStarter = path2.join(TEMPLATE_PACKS, packSpec.name, "document");
     if (!existsSync(packStarter)) {
-      throw new Error(`Style pack starter not found in bundle: ${packStarter}`);
+      throw new Error(`Bundled style pack starter not found: ${packStarter}`);
     }
     await cp(packStarter, docDest, { recursive: true });
-  } else {
-    await mkdir2(docDest, { recursive: true });
+  } else if (packSpec?.kind === "github") {
+    log(`Fetching style pack from github:${packSpec.owner}/${packSpec.repo}${packSpec.ref ? `#${packSpec.ref}` : ""}\u2026`);
+    try {
+      await degit({
+        owner: packSpec.owner,
+        repo: packSpec.repo,
+        ref: packSpec.ref,
+        dest: docDest,
+        subdir: "starter/document"
+      });
+    } catch (err) {
+      throw new Error(
+        `Failed to fetch pack from github:${packSpec.owner}/${packSpec.repo}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    if (await pathIsEmpty(docDest)) {
+      throw new Error(
+        `github:${packSpec.owner}/${packSpec.repo} doesn't contain starter/document/ at the repo root.
+Third-party pack repos should follow this layout:
+  <repo>/
+  \u251C\u2500\u2500 starter/
+  \u2502   \u2514\u2500\u2500 document/   \u2190 cli copies this into your workspace's document/
+  \u2514\u2500\u2500 skills/<pack>/SKILL.md   \u2190 npx skills add picks this up`
+      );
+    }
   }
   const pkgPath = path2.join(target, "package.json");
   if (existsSync(pkgPath)) {
@@ -121,13 +179,23 @@ async function init(options) {
       author: options.author
     });
   }
-  log(`Installing agent skills via \`npx skills add ${SKILLS_SOURCE}\`\u2026`);
+  log(`Installing framework skills via \`npx skills add ${FRAMEWORK_SKILLS_SOURCE}\`\u2026`);
   try {
-    await runInTarget(target, "npx", ["-y", "skills@latest", "add", SKILLS_SOURCE]);
+    await runInTarget(target, "npx", ["-y", "skills@latest", "add", FRAMEWORK_SKILLS_SOURCE]);
   } catch (err) {
-    log(`(skills install failed; you can retry manually with \`npx skills add ${SKILLS_SOURCE}\`)`);
+    log(`(framework skills install failed; retry: npx skills add ${FRAMEWORK_SKILLS_SOURCE})`);
     log(`  reason: ${err instanceof Error ? err.message : String(err)}`);
   }
+  if (packSpec?.kind === "github") {
+    const packSource = `${packSpec.owner}/${packSpec.repo}`;
+    log(`Installing pack skills via \`npx skills add ${packSource}\`\u2026`);
+    try {
+      await runInTarget(target, "npx", ["-y", "skills@latest", "add", packSource]);
+    } catch (err) {
+      log(`(pack skills install failed; retry: npx skills add ${packSource})`);
+      log(`  reason: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
   if (options.install) {
     log("Installing dependencies (npm install)\u2026");
     await runInTarget(target, "npm", ["install"]);
@@ -148,6 +216,26 @@ async function init(options) {
   }
   printNextSteps(target, options);
 }
+function parsePackSpec(spec) {
+  if (spec.startsWith("github:")) {
+    const rest = spec.slice("github:".length);
+    const [pathPart, ref] = rest.split("#");
+    const segments = pathPart.split("/").filter(Boolean);
+    if (segments.length !== 2) {
+      throw new Error(
+        `Invalid --pack spec: "${spec}". Use github:owner/repo or github:owner/repo#ref.`
+      );
+    }
+    const [owner, repo] = segments;
+    return { kind: "github", owner, repo, ref: ref?.trim() || void 0 };
+  }
+  if (!BUNDLED_PACKS.includes(spec)) {
+    throw new Error(
+      `Unknown style pack: "${spec}". Bundled packs: ${BUNDLED_PACKS.join(", ")}. For third-party packs use github:owner/repo (e.g. github:quan0715/openpress-pack-nycu-thesis).`
+    );
+  }
+  return { kind: "bundled", name: spec };
+}
 function ensureTemplateBundled() {
   if (!existsSync(TEMPLATE_CORE) || !existsSync(TEMPLATE_PACKS)) {
     throw new Error(
@@ -155,12 +243,6 @@ function ensureTemplateBundled() {
     );
   }
 }
-function validatePack(pack) {
-  if (pack === void 0) return;
-  if (!KNOWN_PACKS.includes(pack)) {
-    throw new Error(`Unknown style pack: ${pack}. Known packs: ${KNOWN_PACKS.join(", ")}`);
-  }
-}
 async function ensureTarget(target, force) {
   if (existsSync(target)) {
     if (force) return;
@@ -228,19 +310,28 @@ Usage:
   npx @open-press/cli init <target> [flags]
 
 Flags:
-  --pack <name>            Style pack starter: editorial-monograph | claude-document
+  --pack <spec>            Style pack source. Either:
+                             \u2022 a bundled name \u2014 editorial-monograph | claude-document | academic-paper
+                             \u2022 github:owner/repo (third-party pack)
+                             \u2022 github:owner/repo#branch-or-tag
   --title <s>              Document title (written to openpress.config.mjs)
   --subtitle <s>           Document subtitle
   --organization <s>       Organization name
-  --author <s>             Author name (defaults to git user.name)
+  --author <s>             Author name
   --no-git                 Skip git init
   --no-install             Skip npm install
   --force                  Allow non-empty target
   --help                   Show this help
 
 Examples:
+  # Bundled
   npx @open-press/cli init my-doc --pack editorial-monograph
-  npx @open-press/cli init my-doc --pack claude-document --title "Q2 Brief" --author Quan
+  npx @open-press/cli init my-brief --pack claude-document --title "Q2 Brief" --author Quan
+  npx @open-press/cli init my-paper --pack academic-paper --title "Paper Title" --author "First Author"
+
+  # Third-party (any GitHub repo with starter/document/ at the root)
+  npx @open-press/cli init my-thesis --pack github:quan0715/openpress-pack-nycu-thesis
+  npx @open-press/cli init my-paper --pack github:foo/their-pack#v1.2
 `;
 async function main(argv) {
   if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {

package/package.json

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

package/template/core/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @open-press/core
 
+## 0.6.0
+
+### Minor Changes
+
+- f8fdecd: Third bundled pack: `academic-paper`.
+
+  A single-column A4 academic / research paper starter — serif title block, abstract band, index terms, numbered sections (I, II, III), italic sub-sections (A, B, C), `[N]` numeric references, sample chapters derived from the IEEE conference template structure (Introduction, Methods, Results & Discussion, Acknowledgment, References).
+
+  ```bash
+  npx @open-press/cli init my-paper --pack academic-paper
+  ```
+
+  Suitable for: draft / preprint / iteration. Not suitable for camera-ready IEEE / ACM submission — those still need LaTeX with the publisher's class file.
+
+  Two-column body and other paged-document features (footnotes, cross-references with page numbers, running headers) are intentionally **out of scope for this release**. They'll be designed as a self-maintained engine evolution + multi-mode architecture in a separate spec round, rather than depending on a third-party pagination polyfill.
+
+- c490653: `@open-press/cli init` accepts third-party style packs via `--pack github:owner/repo`.
+
+  ```bash
+  # bundled (unchanged)
+  npx @open-press/cli init my-doc --pack editorial-monograph
+
+  # third-party (new)
+  npx @open-press/cli init my-thesis --pack github:quan0715/openpress-pack-nycu-thesis
+  npx @open-press/cli init my-paper --pack github:foo/their-pack#v1.2
+  ```
+
+  The cli fetches `starter/document/` from the named repo (default branch, or `#ref` for a specific branch/tag) and copies it into the new workspace. If the pack repo also publishes SKILL files at `skills/<name>/`, they're installed via `npx skills add <owner>/<repo>` after the framework skills, so the agent picks them up automatically.
+
+  Repo layout convention for third-party packs is documented in `docs/style-pack-authoring.md`. Empty-result extraction (the named repo exists but has no `starter/document/` at root) fails with a clear error pointing at the expected layout.
+
+  The two bundled packs (`editorial-monograph`, `claude-document`) keep their current short-name behaviour; only the cli's validator widened to accept the `github:` prefix.
+
 ## 0.5.0
 
 ### Minor Changes
@@ -7,7 +40,6 @@
 - 0169cba: Agent-driven upgrade flow.
 
   **New commands:**
-
   - `npx open-press doctor` — diagnose workspace against latest framework state. Reports `@open-press/core` version vs npm latest, installed skill count, and any pending `docs/migrations/<version>.md` notes between current and latest. `--json` for machine-readable output, `--no-cache` to bypass the 24h cache. Always exits 0 (informational only).
 
   - `npx open-press upgrade` — orchestrate the upgrade. Runs `npm update @open-press/core` (when the workspace declares the dep) and `npx skills upgrade`, then surfaces the list of migration notes for the agent to read. **Does not auto-edit `document/` content** — the agent reads the surfaced `docs/migrations/<version>.md` notes and proposes edits to the user with confirmation. Use `--dry-run` to preview, `--no-deps` / `--no-skills` to target one layer.
@@ -17,7 +49,6 @@
   `open-press dev` now runs `doctor` before starting Vite. When the workspace is behind, a single line prints: `○ open-press: @open-press/core 0.4.0 → 0.5.0 · 1 migration note(s) — run npx open-press doctor for details.` Cached for 24h, network failure is silent, never blocks dev.
 
   **Migration docs:**
-
   - New `docs/migrations/_template.md` — each release with breaking changes ships a `docs/migrations/<version>.md` file with sections the agent reads.
   - New `docs/migrations/0.4.0.md` — backfilled. Documents the SKILL fold (no document or CLI changes).
 
@@ -34,7 +65,6 @@
 ### Minor Changes
 
 - 3cb4939: Consolidate internal skills (13 → 11).
-
   - `openpress-update` folded into `openpress` as an "Updating An Existing Workspace" section. The release-upgrade flow, pre-flight checks, breaking-change reference, and do-not list are now part of the system-operation skill where they naturally belong.
   - `openpress-document-hierarchy` folded into `openpress-writing` as a "Hierarchy" section. Hierarchy decisions (H2/H3/H4 model, TOC depth, appendix placement, H4 granularity) and prose decisions happen in the same workflow; one skill, one routing decision.
   - `references/data-structures-outline.md` moved from the hierarchy skill into `openpress-writing/references/`.

package/template/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-press/core",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "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

@@ -0,0 +1,21 @@
+## 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.
+
+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.
+
+### Where to start
+
+Each chapter directory under `document/chapters/` is one paper section:
+
+- `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.
+
+Replace each chapter's MDX content with your own. The skeleton text below each `##` heading is illustrative — overwrite it.
+
+### Abstract and Index Terms
+
+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.

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

@@ -0,0 +1,30 @@
+## 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.
+
+### Apparatus and Materials
+
+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]").
+
+### Procedure
+
+Describe the experimental procedure as steps a reader could follow:
+
+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).
+
+### 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:
+
+$$a + b = \gamma \tag{1}$$
+
+Refer to equations by `(1)`, not `Eq. (1)` or `equation (1)`, except at the start of a sentence: "Equation (1) shows ...".
+
+### Reporting Units
+
+- 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`.

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

@@ -0,0 +1,29 @@
+## Results and Discussion
+
+Present the findings of your study, then interpret what they mean for the research question stated in the introduction.
+
+### Quantitative Results
+
+Use a table to summarise results across conditions. Caption above the table.
+
+<TableCaption>Sample comparison of conditions.</TableCaption>
+
+| 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 |
+
+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.
+
+### Qualitative Discussion
+
+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".
+
+### Threats to Validity
+
+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.
+
+### Future Work
+
+Indicate where the work goes next. Keep this to one short paragraph — over-claiming future scope hurts more than it helps in review.

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

@@ -0,0 +1,12 @@
+## Acknowledgment
+
+The preferred American spelling is *acknowledgment* without an "e" after the "g". Avoid stilted constructions like "one of us (R. B. G.) thanks ...". Prefer "R. B. G. thanks ...".
+
+Acknowledge:
+
+- Funding sources (with grant numbers if applicable).
+- Collaborators who contributed materially but are not listed as authors.
+- Anonymous reviewers whose comments improved the paper.
+- Institutional or computational resources.
+
+Place sponsor acknowledgments in the unnumbered footnote on the first page of the published version. In this draft pack, keep them here until you migrate to a publisher's class file at submission time.

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

@@ -0,0 +1,27 @@
+## References
+
+Number citations consecutively within square brackets `[1]`. Sentence punctuation follows the bracket. Refer simply to the reference number, as in `[3]` — do not use `Ref. [3]` or `reference [3]` except at the start of a sentence: "Reference [3] was the first ...".
+
+Unless there are six authors or more, give all authors' names; do not use `et al.`. Papers not yet published should be cited as *unpublished*; accepted but not yet published as *in press*. Capitalize only the first word in a paper title, except for proper nouns and element symbols.
+
+For papers published in translation journals, give the English citation first, followed by the original foreign-language citation.
+
+---
+
+[1] G. Eason, B. Noble, and I. N. Sneddon, "On certain integrals of Lipschitz–Hankel type involving products of Bessel functions," *Phil. Trans. Roy. Soc. London*, vol. A247, pp. 529–551, April 1955.
+
+[2] J. Clerk Maxwell, *A Treatise on Electricity and Magnetism*, 3rd ed., vol. 2. Oxford: Clarendon, 1892, pp. 68–73.
+
+[3] I. S. Jacobs and C. P. Bean, "Fine particles, thin films and exchange anisotropy," in *Magnetism*, vol. III, G. T. Rado and H. Suhl, Eds. New York: Academic, 1963, pp. 271–350.
+
+[4] K. Elissa, "Title of paper if known," unpublished.
+
+[5] R. Nicole, "Title of paper with only first word capitalized," *J. Name Stand. Abbrev.*, in press.
+
+[6] Y. Yorozu, M. Hirano, K. Oka, and Y. Tagawa, "Electron spectroscopy studies on magneto-optical media and plastic substrate interface," *IEEE Transl. J. Magn. Japan*, vol. 2, pp. 740–741, August 1987.
+
+[7] M. Young, *The Technical Writer's Handbook*. Mill Valley, CA: University Science, 1989.
+
+---
+
+> **Reminder**: replace the seven placeholder references above with your own bibliography before circulating the draft. They are the IEEE conference template's example citations and have nothing to do with your paper.

package/template/packs/academic-paper/document/components/ChapterOpenerVisual/index.tsx

@@ -0,0 +1,76 @@
+const TONES = new Set(["sage", "lavender", "mint", "amber"]);
+
+const VISUALS = {
+  "linked-list": `<svg viewBox="0 0 520 330" focusable="false" aria-hidden="true">
+      <rect class="chapter-opener-illustration__paper" x="42" y="96" width="116" height="82" rx="4" />
+      <rect class="chapter-opener-illustration__paper" x="204" y="96" width="116" height="82" rx="4" />
+      <rect class="chapter-opener-illustration__paper" x="366" y="96" width="116" height="82" rx="4" />
+      <path class="chapter-opener-illustration__stroke" d="M158 137 H204" />
+      <path class="chapter-opener-illustration__stroke" d="M320 137 H366" />
+      <path class="chapter-opener-illustration__arrow" d="M190 122 206 137 190 152" />
+      <path class="chapter-opener-illustration__arrow" d="M352 122 368 137 352 152" />
+      <path class="chapter-opener-illustration__thin" d="M72 128 H118 M72 150 H128 M234 128 H280 M234 150 H286 M396 128 H442 M396 150 H452" />
+      <circle class="chapter-opener-illustration__node" cx="144" cy="137" r="13" />
+      <circle class="chapter-opener-illustration__node" cx="306" cy="137" r="13" />
+      <circle class="chapter-opener-illustration__node" cx="468" cy="137" r="13" />
+      <path class="chapter-opener-illustration__stroke" d="M262 178 C262 222 220 244 158 244 C98 244 68 222 68 190" />
+      <path class="chapter-opener-illustration__arrow" d="M52 204 68 188 84 204" />
+    </svg>`,
+  tree: `<svg viewBox="0 0 520 330" focusable="false" aria-hidden="true">
+      <path class="chapter-opener-illustration__paper" d="M232 40 316 40 352 86 330 132 218 132 194 86Z" />
+      <path class="chapter-opener-illustration__paper" d="M88 198 170 178 228 218 204 288 100 288 58 240Z" />
+      <path class="chapter-opener-illustration__paper" d="M314 198 400 176 466 224 450 292 328 292 282 238Z" />
+      <path class="chapter-opener-illustration__stroke" d="M262 118 160 214 M270 118 374 214" />
+      <path class="chapter-opener-illustration__stroke" d="M160 214 122 258 M160 214 204 258 M374 214 330 258 M374 214 420 258" />
+      <circle class="chapter-opener-illustration__node" cx="266" cy="100" r="24" />
+      <circle class="chapter-opener-illustration__node" cx="160" cy="214" r="22" />
+      <circle class="chapter-opener-illustration__node" cx="374" cy="214" r="22" />
+      <circle class="chapter-opener-illustration__dot" cx="122" cy="258" r="13" />
+      <circle class="chapter-opener-illustration__dot" cx="204" cy="258" r="13" />
+      <circle class="chapter-opener-illustration__dot" cx="330" cy="258" r="13" />
+      <circle class="chapter-opener-illustration__dot" cx="420" cy="258" r="13" />
+    </svg>`,
+  code: `<svg viewBox="0 0 520 330" focusable="false" aria-hidden="true">
+      <path class="chapter-opener-illustration__paper" d="M92 52 338 52 386 104 386 286 92 286Z" />
+      <path class="chapter-opener-illustration__paper" d="M348 82 438 82 476 122 452 226 356 226 326 154Z" />
+      <path class="chapter-opener-illustration__thin" d="M132 112 H250 M132 146 H292 M132 180 H238 M132 214 H276" />
+      <path class="chapter-opener-illustration__stroke" d="M308 114 C340 122 356 148 356 180 C356 220 332 244 292 250" />
+      <path class="chapter-opener-illustration__arrow" d="M304 226 288 250 316 260" />
+      <path class="chapter-opener-illustration__stroke" d="M406 124 V202" />
+      <circle class="chapter-opener-illustration__node" cx="406" cy="124" r="17" />
+      <circle class="chapter-opener-illustration__node" cx="406" cy="202" r="17" />
+    </svg>`,
+  answers: `<svg viewBox="0 0 520 330" focusable="false" aria-hidden="true">
+      <path class="chapter-opener-illustration__paper" d="M128 44 396 44 440 90 418 292 104 292 82 86Z" />
+      <path class="chapter-opener-illustration__thin" d="M178 116 H350 M178 168 H350 M178 220 H322" />
+      <path class="chapter-opener-illustration__stroke" d="M128 112 148 134 190 88" />
+      <path class="chapter-opener-illustration__stroke" d="M128 164 148 186 190 140" />
+      <path class="chapter-opener-illustration__stroke" d="M128 216 148 238 190 192" />
+      <circle class="chapter-opener-illustration__node" cx="386" cy="92" r="18" />
+      <path class="chapter-opener-illustration__stroke" d="M386 92 C420 126 424 172 394 208" />
+      <path class="chapter-opener-illustration__arrow" d="M380 186 394 210 420 200" />
+    </svg>`,
+};
+
+export type ChapterOpenerVisualVariant = keyof typeof VISUALS;
+
+export interface ChapterOpenerVisualProps {
+  variant?: ChapterOpenerVisualVariant;
+  tone?: string;
+}
+
+export default function ChapterOpenerVisual({
+  variant = "linked-list",
+  tone = "sage",
+}: ChapterOpenerVisualProps) {
+  const visual = VISUALS[variant] ?? VISUALS["linked-list"];
+  const safeTone = TONES.has(tone) ? tone : "sage";
+
+  return (
+    <figure
+      className={`chapter-opener-illustration chapter-opener-illustration--${variant} chapter-opener-tone--${safeTone}`}
+      aria-hidden="true"
+      dangerouslySetInnerHTML={{ __html: visual }}
+    />
+  );
+}

package/template/packs/academic-paper/document/components/Page.tsx

@@ -0,0 +1,27 @@
+import type { PageProps } from "@openpress/core";
+
+export default function Page({
+  pageIndex,
+  totalPages,
+  chapterSlug,
+  chapterTone,
+  children,
+}: PageProps) {
+  return (
+    <section
+      className="reader-page reader-page--content"
+      data-page-kind="content"
+      data-page-footer="true"
+      data-page-index={pageIndex}
+      data-total-pages={totalPages}
+      data-chapter-slug={chapterSlug}
+      data-chapter-tone={chapterTone}
+    >
+      <div className="page-frame">
+        <header className="page-header" aria-hidden="true" />
+        <main className="page-body">{children}</main>
+        <footer className="page-footer" aria-hidden="true" />
+      </div>
+    </section>
+  );
+}

package/template/packs/academic-paper/document/components/TokenSwatchGrid/index.tsx

@@ -0,0 +1,46 @@
+import type { CSSProperties } from "react";
+
+export interface TokenSwatch {
+  name: string;
+  hex: string;
+  summary: string;
+  swatchVar: string;
+  swatchBorderVar?: string;
+  dark?: boolean;
+}
+
+export interface TokenSwatchGridProps {
+  ariaLabel?: string;
+  swatches: TokenSwatch[];
+}
+
+export default function TokenSwatchGrid({
+  ariaLabel = "Color specimen",
+  swatches,
+}: TokenSwatchGridProps) {
+  return (
+    <section className="token-swatch-grid" data-openpress-component="TokenSwatchGrid" aria-label={ariaLabel}>
+      {swatches.map((swatch) => (
+        <article
+          key={swatch.name}
+          className={swatch.dark ? "token-swatch token-swatch--dark" : "token-swatch"}
+          style={swatchStyle(swatch)}
+        >
+          <div className="token-swatch__sample" />
+          <div className="token-swatch__body">
+            <h4>{swatch.name}</h4>
+            <code>{swatch.hex}</code>
+            <p>{swatch.summary}</p>
+          </div>
+        </article>
+      ))}
+    </section>
+  );
+}
+
+function swatchStyle(swatch: TokenSwatch): CSSProperties {
+  return {
+    "--swatch": swatch.swatchVar,
+    ...(swatch.swatchBorderVar ? { "--swatch-border": swatch.swatchBorderVar } : {}),
+  } as CSSProperties;
+}

package/template/packs/academic-paper/document/components/TokenSwatchGrid/style.css

@@ -0,0 +1,63 @@
+/* token-swatch-grid
+ * Color specimen grid referenced by design.md to display each color token with
+ * its sample, hex, and usage note.
+ */
+
+.token-swatch-grid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 3mm;
+  margin: var(--openpress-space-3) 0 var(--openpress-space-4);
+  break-inside: avoid;
+}
+
+.token-swatch {
+  min-height: 42mm;
+  overflow: hidden;
+  border: 1px solid var(--openpress-color-line);
+  border-radius: 6px;
+  background: var(--openpress-color-document);
+  box-sizing: border-box;
+  break-inside: avoid;
+}
+
+.token-swatch__sample {
+  height: 17mm;
+  background: var(--swatch);
+  border-bottom: 1px solid var(--swatch-border, var(--openpress-color-line));
+}
+
+.token-swatch__body {
+  padding: 3mm;
+}
+
+.token-swatch h4 {
+  margin: 0;
+  color: var(--openpress-color-ink);
+  font-family: var(--openpress-font-body);
+  font-size: 9pt;
+  font-weight: 600;
+  line-height: 1.25;
+  letter-spacing: 0;
+}
+
+.token-swatch code {
+  display: block;
+  margin-top: 1mm;
+  color: var(--openpress-color-muted);
+  font-size: 8pt;
+  line-height: 1.35;
+}
+
+.token-swatch p {
+  margin: 2mm 0 0;
+  color: #333333;
+  font-size: 8.4pt;
+  line-height: 1.45;
+}
+
+@media (max-width: 899px) {
+  .token-swatch-grid {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+}