@ingcreators/annot-product-docs-xlsx 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,104 @@
+# @ingcreators/annot-product-docs-xlsx
+
+## 0.2.0
+
+### Minor Changes
+
+- 2e92c97: First publish of the living-product-docs package family. Phases
+  1-5 + 7 of `docs/plans/living-product-docs.md` landed across
+  PRs 876-899; this entry flips the three packages from
+  `private: true` to publishable and stamps `0.1.0`.
+
+  ### `@ingcreators/annot-product-docs`
+  - MDX parser (`parseMdx` / `parseMdxFile`) — Remark / unified
+    pipeline that walks `.mdx` files with `annot:` frontmatter
+    and extracts `<Screen>` / `<Overlay>` / `<Transition>` /
+    `<HistoryEntry>` / `<ScreenList>` JSX components.
+  - Match resolver (`parseSnapshot` / `resolveMatch` /
+    `resolveOverlays`) for the Playwright `aria-snapshot`
+    YAML, honouring `match.under` disambiguation and emitting
+    `not-found` / `ambiguous` / `renamed` / `role-changed` /
+    `live-mismatch` diagnostics.
+  - `screen` fixture extending `@ingcreators/annot-playwright`
+    with `screen.capture({ id, mdxPath })` that re-syncs
+    `annot:snapshot` + `annot:attributes` MDX comment blocks
+    in place.
+  - Drift detector (`detectDrift` / `detectDriftFromYaml`) — six
+    finding kinds (added / removed / renamed / role-changed /
+    duplicated / attribute-drift) with severity buckets.
+  - `annot-docs` CLI (`init` / `sync` / `lint`) with `--json`
+    / `--ci` / `--fix` flags + a sample GitHub Actions workflow
+    emitting GitHub annotations on PR diff views.
+
+  ### `@ingcreators/annot-product-docs-astro`
+  - `productDocsIntegration()` Astro 5.x integration factory.
+  - 7 docs components: `<Screen>`, `<Overlay>`, `<Transition>`,
+    `<TransitionTable>`, `<HistoryEntry>`, `<ScreenList>`,
+    `<TransitionGraph>`. Shipped as `.astro` source under
+    `./components/*.astro` exports.
+  - Image Service (`renderAnnotatedScreen` + SHA-keyed
+    `createFileCache` / `createMemoryCache`) that composes the
+    base screenshot with overlay callouts at build time.
+
+  ### `@ingcreators/annot-product-docs-xlsx`
+  - MDX → normalised bundle extractor; per-role default layout
+    (cover / history / list / screen / reference); customer-
+    template support with `{var}` placeholder substitution
+    (including `{annot:date}` special vars + `{name:format}`
+    date formatting); Excel Named Range writers
+    (`annotImage` / `annotItemTable` / `annotHistory` /
+    `annotList` / `annotSnapshot` / `annotAttributes`).
+  - `annot-docs-xlsx render` CLI with multi-book emit + per-book
+    template config.
+
+### Patch Changes
+
+- 657a685: **Republish with `dist/` included.** The `0.1.0` tarballs of all
+  three packages shipped to npm without their `dist/` directory —
+  the `publish.yml` workflow's pre-pack `pnpm build` step had only
+  filtered four other packages, so `pnpm pack` packed the three
+  `product-docs*` packages against empty `dist/`s. The
+  `publishConfig.main` (`./dist/index.js`) consequently pointed at
+  a missing file, breaking `npm install` for every consumer.
+
+  The source fix landed in
+  [#947](https://github.com/ingcreators/annot/pull/947) with two
+  defences:
+  1. Three new `--filter` lines in the workflow's build step so
+     all seven publishable packages get built before pack.
+  2. A per-package `prepack` script (`pnpm run build`) so even a
+     misconfigured workflow (or a manual `pnpm pack` / `pnpm
+publish`) refreshes `dist/` before packing.
+
+  No source-code changes in any of the three packages — only the
+  packaging is fixed. This patch publish exists solely to deliver
+  working tarballs to the registry; the public API surface is
+  byte-identical to `0.1.0`.
+
+  Verified locally:
+
+  ```
+  $ pnpm --filter @ingcreators/annot-product-docs pack --dry-run
+  Tarball Contents
+    bin/annot-docs.mjs
+    dist/cli.d.ts
+    dist/config.d.ts
+    dist/drift.d.ts
+    dist/fixture.d.ts
+    dist/index.d.ts
+    dist/index.js
+    dist/mdx.d.ts
+    dist/resolver.d.ts
+    dist/types-config.d.ts
+    dist/types.d.ts
+    LICENSE
+    package.json
+    README.md
+  ```
+
+  Before the fix the same command produced 4 files (LICENSE +
+  README + package.json + bin/annot-docs.mjs), no compiled code.
+
+- Updated dependencies [2e92c97]
+- Updated dependencies [657a685]
+  - @ingcreators/annot-product-docs@0.2.0

package/README.md

@@ -9,12 +9,12 @@ files with `annot:` frontmatter, fills customer-supplied Excel
 templates via `{var}` placeholders + Excel Named Ranges, and
 emits one `.xlsx` per book.
 
-Targets the Japanese SI 画面設計書 use case where customers
-expect a specific corporate Excel template, populated from a
+Targets the corporate screen-specifications use case where
+customers expect a specific Excel template populated from a
 code-driven source of truth.
 
 Phase 3 of
-[`docs/plans/living-product-docs.md`](https://github.com/ingcreators/annot/blob/main/docs/plans/living-product-docs.md).
+[`docs/plans/_done/living-product-docs.md`](https://github.com/ingcreators/annot/blob/main/docs/plans/_done/living-product-docs.md).
 
 ## Install
 
@@ -26,7 +26,7 @@ pnpm add @ingcreators/annot-product-docs-xlsx
 
 ```sh
 annot-docs-xlsx render --root docs --out dist/xlsx
-annot-docs-xlsx render --book "Screen spec"
+annot-docs-xlsx render --book "Screen specifications"
 ```
 
 Reads `annot-docs.config.ts` from the project root; uses a
@@ -41,19 +41,19 @@ import { defineConfig } from "@ingcreators/annot-product-docs";
 
 export default defineConfig({
   meta: {
-    projectName: "顧客管理システム",
-    customerName: "株式会社XYZ",
+    projectName: "Customer management system",
+    customerName: "Acme Corp.",
   },
   xlsx: {
-    defaultBook: "画面設計書",
+    defaultBook: "Screen specifications",
     books: {
-      "画面設計書": {
+      "Screen specifications": {
         template: "./templates/customer-screen-spec.xlsx",
         templateSheets: {
-          cover: "表紙テンプレ",
-          history: "改訂履歴テンプレ",
-          list: "画面一覧テンプレ",
-          screen: "個別画面テンプレ",
+          cover: "Cover template",
+          history: "History template",
+          list: "Screen list template",
+          screen: "Per-screen template",
         },
       },
     },
@@ -71,7 +71,7 @@ In template cells:
 {meta.author}                         → frontmatter meta.author
 {projectName}                         → project meta.projectName
 {annot:date}                          → "2026-05-21"
-{annot:date:yyyy年MM月dd日}           → "2026年05月21日"
+{annot:date:yyyy-MM-dd}               → "2026-05-21"
 {meta.createdDate:yyyy/MM/dd}         → "2026/05/21"
 {annot:sheetIndex}/{annot:totalSheets} → "3/12"
 ```

package/dist/cli.d.ts

@@ -0,0 +1,11 @@
+export interface CliOptions {
+    cwd?: string;
+    stdout?: (line: string) => void;
+    stderr?: (line: string) => void;
+}
+/**
+ * `main(argv)` entrypoint. Returns the process exit code so the
+ * bin script can `process.exit(...)`. Also driveable from
+ * vitest via custom `stdout` / `stderr` / `cwd`.
+ */
+export declare function main(argv: string[], options?: CliOptions): Promise<number>;

package/dist/default-layout.d.ts

@@ -0,0 +1,28 @@
+import { default as ExcelJS } from 'exceljs';
+import { ExcelMdxBundle } from './extract.js';
+export interface ApplyDefaultLayoutInput {
+    workbook: ExcelJS.Workbook;
+    bundles: ExcelMdxBundle[];
+}
+/**
+ * Apply the default no-template layout. The workbook is
+ * mutated in place — every bundle contributes one sheet,
+ * ordered by role then by `xlsx.order` then by file path.
+ */
+export declare function applyDefaultLayout(input: ApplyDefaultLayoutInput): void;
+/**
+ * Sort bundles in the order they appear in the workbook.
+ * Documented in plan section "Open question 7":
+ *   1. Role-default order (cover → history → list → screen → reference)
+ *   2. Within same role: `order` field (default 100)
+ *   3. Tie-break: alphabetical by MDX file path.
+ *
+ * Exported so the template-path branch (PR 3) can reuse the
+ * same sort.
+ */
+export declare function sortBundlesForLayout(bundles: ExcelMdxBundle[]): ExcelMdxBundle[];
+/**
+ * Excel limits sheet names to 31 chars and forbids `: \ / ? * [ ]`.
+ * This is shared with the future template-path branch.
+ */
+export declare function sanitiseSheetName(name: string): string;

package/dist/extract.d.ts

@@ -0,0 +1,48 @@
+import { AnnotFrontmatter, HistoryEntrySpec, OverlaySpec, ParsedMdx } from '@ingcreators/annot-product-docs';
+export interface ExcelMdxBundle {
+    /** Absolute or cwd-relative path to the source `.mdx` file. */
+    mdxPath: string;
+    /** Verbatim source bytes — kept so downstream tools can hash. */
+    source: string;
+    /** The `annot:` frontmatter block. */
+    frontmatter: AnnotFrontmatter;
+    /** Flat per-screen rows (one entry per `<Screen>`). */
+    screens: NormalisedScreen[];
+    /** Flat per-overlay rows (one entry per `<Overlay>`, including its
+     *  parent screen's id + screen-relative number). */
+    overlays: NormalisedOverlay[];
+    /** Flat per-history-entry rows (only populated for `role: history` MDXs). */
+    history: HistoryEntrySpec[];
+    /** Verbatim aria-snapshot block as captured by the fixture. */
+    snapshotYaml: string;
+    /** Verbatim attributes block as captured by the fixture. */
+    attributesYaml: string;
+}
+export interface NormalisedScreen {
+    id: string;
+    src: string | undefined;
+    overlayCount: number;
+}
+export interface NormalisedOverlay {
+    screenId: string;
+    number: number;
+    intent: OverlaySpec["intent"];
+    /** `role + name` joined for one-cell rendering. */
+    matchLabel: string;
+    matchRole: string;
+    matchName: string;
+    /** Markdown body — caller renders to rich text. */
+    body: string;
+}
+/**
+ * Extract a normalised bundle from a parsed MDX. Used directly
+ * by `extractMdxFile` and re-exposed so tests can drive it
+ * without filesystem I/O.
+ */
+export declare function extractFromParsed(parsed: ParsedMdx, mdxPath: string): ExcelMdxBundle;
+/**
+ * Convenience: parse the MDX file and normalise. Returns `null`
+ * for files without `annot:` frontmatter so the bulk-extract
+ * caller can keep its glob noise-free.
+ */
+export declare function extractMdxFile(mdxPath: string): Promise<ExcelMdxBundle | null>;

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export type { CliOptions } from './cli.js';
+export { main, main as cliMain } from './cli.js';
+export type { ApplyDefaultLayoutInput } from './default-layout.js';
+export { applyDefaultLayout, sanitiseSheetName, sortBundlesForLayout, } from './default-layout.js';
+export type { ExcelMdxBundle, NormalisedOverlay, NormalisedScreen, } from './extract.js';
+export { extractFromParsed, extractMdxFile } from './extract.js';
+export type { NamedRangeWriteInput } from './named-range.js';
+export { applyNamedRanges } from './named-range.js';
+export type { SubstituteOptions } from './placeholder.js';
+export { applyPlaceholders, applyPlaceholdersToSheet, resolvePlaceholders, } from './placeholder.js';
+export type { ApplyTemplateInput } from './template.js';
+export { applyTemplateLayout, loadTemplateWorkbook } from './template.js';
+export type { BuildWorkbookInput } from './workbook.js';
+export { buildEmptyWorkbook, groupBundlesByBook, writeWorkbookToBytes, } from './workbook.js';

package/dist/index.js

@@ -0,0 +1,616 @@
+import { mkdir as e, readdir as t, writeFile as n } from "node:fs/promises";
+import { join as r, resolve as i } from "node:path";
+import { pathToFileURL as a } from "node:url";
+import { parseMdxFile as o } from "@ingcreators/annot-product-docs";
+import s from "exceljs";
+//#region src/default-layout.ts
+var c = {
+	cover: 1,
+	history: 2,
+	list: 3,
+	screen: 4,
+	reference: 5
+};
+function l(e) {
+	let t = u(e.bundles);
+	for (let n of t) {
+		let t = n.frontmatter.xlsx?.role ?? "screen", r = g(n, t), i = e.workbook.addWorksheet(r);
+		switch (t) {
+			case "cover":
+				d(i, n);
+				break;
+			case "history":
+				f(i, n);
+				break;
+			case "list":
+				p(i, e.bundles);
+				break;
+			case "reference":
+				h(i, n);
+				break;
+			default: m(i, n);
+		}
+	}
+}
+function u(e) {
+	return [...e].sort((e, t) => {
+		let n = c[e.frontmatter.xlsx?.role ?? "screen"] ?? 99, r = c[t.frontmatter.xlsx?.role ?? "screen"] ?? 99;
+		if (n !== r) return n - r;
+		let i = e.frontmatter.xlsx?.order ?? 100, a = t.frontmatter.xlsx?.order ?? 100;
+		return i === a ? e.mdxPath.localeCompare(t.mdxPath) : i - a;
+	});
+}
+function d(e, t) {
+	let n = t.frontmatter;
+	if (e.columns = [{
+		key: "label",
+		width: 24
+	}, {
+		key: "value",
+		width: 60
+	}], e.addRow({
+		label: "Title",
+		value: n.title ?? n.id
+	}), e.addRow({
+		label: "Document ID",
+		value: n.id
+	}), n.purpose && e.addRow({
+		label: "Purpose",
+		value: n.purpose
+	}), n.meta) for (let [t, r] of Object.entries(n.meta)) e.addRow({
+		label: `meta.${t}`,
+		value: String(r)
+	});
+	e.getColumn(1).font = { bold: !0 };
+}
+function f(e, t) {
+	e.columns = [
+		{
+			header: "Version",
+			key: "version",
+			width: 12
+		},
+		{
+			header: "Date",
+			key: "date",
+			width: 14
+		},
+		{
+			header: "Author",
+			key: "author",
+			width: 18
+		},
+		{
+			header: "Notes",
+			key: "body",
+			width: 60
+		}
+	];
+	for (let n of t.history) e.addRow({
+		version: n.version,
+		date: n.date,
+		author: n.author,
+		body: n.body
+	});
+	e.getRow(1).font = { bold: !0 };
+}
+function p(e, t) {
+	e.columns = [
+		{
+			header: "ID",
+			key: "id",
+			width: 14
+		},
+		{
+			header: "Title",
+			key: "title",
+			width: 36
+		},
+		{
+			header: "Screens",
+			key: "screens",
+			width: 10
+		},
+		{
+			header: "Overlays",
+			key: "overlays",
+			width: 10
+		}
+	];
+	for (let n of t) (n.frontmatter.xlsx?.role ?? "screen") === "screen" && e.addRow({
+		id: n.frontmatter.id,
+		title: n.frontmatter.title ?? n.frontmatter.id,
+		screens: n.screens.length,
+		overlays: n.overlays.length
+	});
+	e.getRow(1).font = { bold: !0 };
+}
+function m(e, t) {
+	let n = t.frontmatter;
+	e.addRow(["ID", n.id]), e.addRow(["Title", n.title ?? ""]), n.purpose && e.addRow(["Purpose", n.purpose]), e.addRow([]), e.addRow([
+		"#",
+		"Role",
+		"Name",
+		"Intent",
+		"Notes"
+	]);
+	let r = e.lastRow;
+	r.font = { bold: !0 };
+	for (let n of t.overlays) e.addRow([
+		n.number,
+		n.matchRole,
+		n.matchName,
+		n.intent ?? "",
+		n.body
+	]);
+	e.getColumn(1).width = 6, e.getColumn(2).width = 14, e.getColumn(3).width = 24, e.getColumn(4).width = 12, e.getColumn(5).width = 60, e.getColumn(1).font = { bold: !0 };
+}
+function h(e, t) {
+	e.addRow(["ID", t.frontmatter.id]), e.addRow(["Title", t.frontmatter.title ?? ""]), t.frontmatter.purpose && e.addRow(["Purpose", t.frontmatter.purpose]);
+}
+function g(e, t) {
+	let n = e.frontmatter.xlsx;
+	return typeof n?.sheet == "string" && n.sheet.length > 0 ? _(n.sheet) : t === "cover" ? "Cover" : t === "history" ? "Revision history" : t === "list" ? "Screen list" : _(t === "reference" ? e.frontmatter.id : e.frontmatter.title ?? e.frontmatter.id);
+}
+function _(e) {
+	let t = e.replace(/[\\/?*[\]:]/g, "_").slice(0, 31);
+	return t.length > 0 ? t : "Sheet";
+}
+//#endregion
+//#region src/extract.ts
+function v(e, t) {
+	let n = e.screens.map((e) => ({
+		id: e.id,
+		src: e.src,
+		overlayCount: e.overlays.length
+	})), r = [];
+	for (let t of e.screens) {
+		let e = 1;
+		for (let n of t.overlays) {
+			let i = n.number ?? e++;
+			r.push({
+				screenId: t.id,
+				number: i,
+				intent: n.intent,
+				matchLabel: ee(n),
+				matchRole: n.match.role,
+				matchName: n.match.name,
+				body: n.body
+			});
+		}
+	}
+	return {
+		mdxPath: t,
+		source: e.source,
+		frontmatter: e.frontmatter,
+		screens: n,
+		overlays: r,
+		history: e.history,
+		snapshotYaml: e.commentBlocks.snapshot ?? "",
+		attributesYaml: e.commentBlocks.attributes ?? ""
+	};
+}
+async function y(e) {
+	let t = await o(e);
+	return t ? v(t, e) : null;
+}
+function ee(e) {
+	let t = `${e.match.role} "${e.match.name}"`;
+	return e.match.under ? `${t} under ${e.match.under.role} "${e.match.under.name}"` : t;
+}
+//#endregion
+//#region src/placeholder.ts
+var te = /\{([^{}]+)\}/g, b = "annot:";
+function x(e, t, n = {}) {
+	let r = n.totalSheets ?? e.worksheets.length;
+	e.worksheets.forEach((e, i) => {
+		S(e, t, {
+			...n,
+			sheetIndex: n.sheetIndex ?? i + 1,
+			totalSheets: r
+		});
+	});
+}
+function S(e, t, n = {}) {
+	e.eachRow({ includeEmpty: !1 }, (e) => {
+		e.eachCell({ includeEmpty: !1 }, (e) => {
+			let r = e.value;
+			if (typeof r != "string") return;
+			let i = C(r, t, n);
+			i !== r && (e.value = i);
+		});
+	});
+}
+function C(e, t, n = {}) {
+	return e.replace(te, (e, r) => {
+		let { key: i, format: a } = w(r), o = T(i, t, n);
+		return o === void 0 ? e : a ? E(o, a) : o;
+	});
+}
+function w(e) {
+	let t = e.trim();
+	if (t.startsWith(b)) {
+		let e = t.slice(6), n = e.indexOf(":");
+		return n < 0 ? {
+			key: t,
+			format: void 0
+		} : {
+			key: b + e.slice(0, n),
+			format: e.slice(n + 1)
+		};
+	}
+	let n = t.indexOf(":");
+	return n < 0 ? {
+		key: t,
+		format: void 0
+	} : {
+		key: t.slice(0, n),
+		format: t.slice(n + 1)
+	};
+}
+function T(e, t, n) {
+	if (e.startsWith(b)) {
+		let t = e.slice(6), r = n.renderTime ?? /* @__PURE__ */ new Date();
+		switch (t) {
+			case "date": return O(r, "yyyy-MM-dd");
+			case "datetime": return r.toISOString();
+			case "sheetIndex": return n.sheetIndex === void 0 ? void 0 : String(n.sheetIndex);
+			case "totalSheets": return n.totalSheets === void 0 ? void 0 : String(n.totalSheets);
+		}
+		return;
+	}
+	if (e.startsWith("meta.")) {
+		let r = e.slice(5), i = t.frontmatter.meta?.[r] ?? n.projectMeta?.[r];
+		return i === void 0 ? void 0 : String(i);
+	}
+	if (e === "id") return t.frontmatter.id;
+	if (e === "title") return t.frontmatter.title;
+	if (e === "purpose") return t.frontmatter.purpose;
+	let r = n.projectMeta?.[e];
+	if (r !== void 0) return String(r);
+}
+function E(e, t) {
+	let n = D(e);
+	return n ? O(n, t) : e;
+}
+function D(e) {
+	let t = e.trim(), n = t.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+	if (n) return new Date(Number.parseInt(n[1], 10), Number.parseInt(n[2], 10) - 1, Number.parseInt(n[3], 10));
+	let r = new Date(t);
+	return Number.isNaN(r.getTime()) ? null : r;
+}
+function O(e, t) {
+	let n = String(e.getFullYear()).padStart(4, "0"), r = String(e.getMonth() + 1).padStart(2, "0"), i = String(e.getDate()).padStart(2, "0"), a = String(e.getHours()).padStart(2, "0"), o = String(e.getMinutes()).padStart(2, "0"), s = String(e.getSeconds()).padStart(2, "0");
+	return t.replace(/yyyy/g, n).replace(/MM/g, r).replace(/dd/g, i).replace(/HH/g, a).replace(/mm/g, o).replace(/ss/g, s);
+}
+//#endregion
+//#region src/template.ts
+function k(e) {
+	let t = u(e.bundles);
+	for (let n of t) {
+		let t = n.frontmatter.xlsx?.role ?? "screen", r = e.bookConfig.templateSheets?.[t];
+		if (!r) continue;
+		let i = e.template.getWorksheet(r);
+		if (!i) throw Error(`Template sheet "${r}" not found for role "${t}" in book template.`);
+		let a = n.frontmatter.xlsx?.sheets;
+		if (a) {
+			let t = Object.entries(a);
+			for (let [, r] of t) S(j(e.workbook, i, _(r)), n, e.substitute ?? {});
+			continue;
+		}
+		let o = _(n.frontmatter.xlsx?.sheet ?? n.frontmatter.title ?? n.frontmatter.id);
+		S(j(e.workbook, i, o), n, e.substitute ?? {});
+	}
+}
+async function A(e) {
+	let t = new s.Workbook();
+	return await t.xlsx.readFile(e), t;
+}
+function j(e, t, n) {
+	let r = e.addWorksheet(n);
+	r.columns = t.columns.map((e) => ({
+		header: e.header,
+		key: e.key,
+		width: e.width,
+		style: e.style
+	})), t.eachRow({ includeEmpty: !0 }, (e, t) => {
+		let n = r.getRow(t);
+		e.eachCell({ includeEmpty: !0 }, (e, t) => {
+			let r = n.getCell(t);
+			r.value = e.value, e.style && (r.style = e.style);
+		}), e.height !== void 0 && (n.height = e.height), n.commit();
+	});
+	for (let e of Object.values(M(t))) r.mergeCells(e);
+	return r;
+}
+function M(e) {
+	return e._merges ?? {};
+}
+//#endregion
+//#region src/workbook.ts
+function N(e) {
+	let t = new s.Workbook();
+	return t.creator = "@ingcreators/annot-product-docs-xlsx", t.created = /* @__PURE__ */ new Date(), t.title = e.book, t;
+}
+async function P(e) {
+	let t = await e.xlsx.writeBuffer();
+	return t instanceof Buffer ? new Uint8Array(t.buffer, t.byteOffset, t.byteLength) : new Uint8Array(t);
+}
+function F(e, t) {
+	let n = /* @__PURE__ */ new Map();
+	for (let r of e) {
+		let e = r.frontmatter.xlsx?.book ?? t;
+		if (!e) continue;
+		let i = n.get(e);
+		i || (i = [], n.set(e, i)), i.push(r);
+	}
+	return n;
+}
+//#endregion
+//#region src/cli.ts
+var I = [
+	"annot-docs-xlsx <command> [options]",
+	"",
+	"Commands:",
+	"  render              Walk MDXs and emit one .xlsx per book",
+	"",
+	"Options:",
+	"  --root <dir>        MDX search root (default: docs)",
+	"  --out <dir>         Output dir for .xlsx files (default: dist/xlsx)",
+	"  --book <name>       Restrict to a single book name",
+	"  --config <file>     Path to annot-docs.config.ts (default: ./annot-docs.config.ts)",
+	"  --help              Show this help"
+].join("\n");
+async function L(e, t = {}) {
+	let n = t.stdout ?? ((e) => process.stdout.write(`${e}\n`)), r = t.stderr ?? ((e) => process.stderr.write(`${e}\n`)), i = t.cwd ?? process.cwd(), [, , a, ...o] = e;
+	if (a !== "render") return r(I), +!!a;
+	let s = R(o);
+	try {
+		return await z(i, s, n);
+	} catch (e) {
+		return r(`annot-docs-xlsx render: ${e.message}`), 1;
+	}
+}
+function R(e) {
+	let t = "docs", n = "dist/xlsx", r, i = "annot-docs.config.ts";
+	for (let a = 0; a < e.length; a++) {
+		let o = e[a];
+		o === "--root" ? t = e[++a] ?? t : o === "--out" ? n = e[++a] ?? n : o === "--book" ? r = e[++a] : o === "--config" && (i = e[++a] ?? i);
+	}
+	return {
+		root: t,
+		out: n,
+		book: r,
+		config: i
+	};
+}
+async function z(t, a, o) {
+	let s = await B(i(t, a.config), o), c = await H(await V(i(t, a.root)));
+	if (c.length === 0) return o(`annot-docs-xlsx render: no MDX files with \`annot:\` frontmatter under ${a.root}.`), 0;
+	let u = F(c, s.xlsx?.defaultBook), d = i(t, a.out);
+	await e(d, { recursive: !0 });
+	let f = 0;
+	for (let [e, c] of u.entries()) {
+		if (a.book && e !== a.book) continue;
+		let u = N({
+			book: e,
+			bundles: c
+		}), p = s.xlsx?.books?.[e], m = p?.template;
+		m ? k({
+			workbook: u,
+			template: await A(i(t, m)),
+			bookConfig: p,
+			bundles: c,
+			substitute: {
+				projectMeta: s.meta,
+				renderTime: /* @__PURE__ */ new Date()
+			}
+		}) : l({
+			workbook: u,
+			bundles: c
+		});
+		let h = await P(u), g = r(d, `${U(e)}.xlsx`);
+		await n(g, h), o(`  wrote ${g} (${c.length} MDX file(s))`), f++;
+	}
+	return a.book && f === 0 ? (o(`annot-docs-xlsx render: book "${a.book}" not found (had: ${[...u.keys()].join(", ")}).`), 1) : (o(`annot-docs-xlsx render: emitted ${f} workbook(s) to ${a.out}`), 0);
+}
+async function B(e, t) {
+	try {
+		let t = await import(a(e).href);
+		return t.default ?? t;
+	} catch (n) {
+		if (n.code === "ERR_MODULE_NOT_FOUND") return t(`annot-docs-xlsx render: no config at ${e} — using defaults.`), {};
+		throw n;
+	}
+}
+async function V(e) {
+	let n = [], i = [e];
+	for (; i.length > 0;) {
+		let e = i.pop(), a;
+		try {
+			a = await t(e, { withFileTypes: !0 });
+		} catch (e) {
+			if (e.code === "ENOENT") continue;
+			throw e;
+		}
+		for (let t of a) {
+			let a = r(e, t.name);
+			if (t.isDirectory()) {
+				if (t.name === "node_modules" || t.name.startsWith(".")) continue;
+				i.push(a);
+			} else t.isFile() && t.name.endsWith(".mdx") && n.push(a);
+		}
+	}
+	return n.sort();
+}
+async function H(e) {
+	let t = [];
+	for (let n of e) try {
+		let e = await o(n);
+		e && t.push(v(e, n));
+	} catch {}
+	return t;
+}
+function U(e) {
+	return e.replace(/[\\/?*[\]:<>|"]/g, "_");
+}
+//#endregion
+//#region src/named-range.ts
+var W = "annot";
+function G(e) {
+	for (let t of ie(e.workbook)) K(e, t);
+}
+function K(e, t) {
+	let [n, r] = q(t.name.replace(/^annot/, ""));
+	switch (n) {
+		case "Image":
+			J(e, t, r);
+			return;
+		case "ItemTable":
+			X(t, e.bundle);
+			return;
+		case "Transitions":
+			Z(t, e.bundle);
+			return;
+		case "History":
+			ne(t, e.bundle);
+			return;
+		case "List":
+			re(t, e.allBundles ?? [e.bundle]);
+			return;
+		case "Snapshot":
+			Q(t, e.bundle.snapshotYaml);
+			return;
+		case "Attributes":
+			Q(t, e.bundle.attributesYaml);
+			return;
+	}
+}
+function q(e) {
+	let t = e.indexOf("_");
+	return t < 0 ? [e, void 0] : [e.slice(0, t), e.slice(t + 1)];
+}
+function J(e, t, n) {
+	let r = n ? e.imagesByScreenId?.[n] : e.defaultImage ?? e.imagesByScreenId?.[e.bundle.screens[0]?.id ?? ""];
+	if (!r) return;
+	let i = e.workbook.addImage({
+		buffer: Buffer.from(r),
+		extension: "png"
+	});
+	t.sheet.addImage(i, t.address);
+}
+function Y(e, t, n) {
+	let { sheet: r, box: i } = e;
+	for (let e = 0; e < t.length; e++) {
+		let n = r.getCell(i.startRow, i.startCol + e);
+		n.value = t[e] ?? "", n.font = { bold: !0 };
+	}
+	for (let e = 0; e < n.length; e++) {
+		let t = n[e], a = i.startRow + 1 + e;
+		if (a > i.endRow) break;
+		for (let e = 0; e < t.length; e++) r.getCell(a, i.startCol + e).value = t[e] ?? "";
+	}
+}
+function X(e, t) {
+	Y(e, [
+		"#",
+		"Role",
+		"Name",
+		"Intent",
+		"Notes"
+	], t.overlays.map((e) => [
+		e.number,
+		e.matchRole,
+		e.matchName,
+		e.intent ?? "",
+		e.body
+	]));
+}
+function Z(e, t) {
+	Y(e, [
+		"Trigger",
+		"Event",
+		"Target",
+		"Notes"
+	], []);
+}
+function ne(e, t) {
+	Y(e, [
+		"Version",
+		"Date",
+		"Author",
+		"Notes"
+	], t.history.map((e) => [
+		e.version,
+		e.date,
+		e.author,
+		e.body
+	]));
+}
+function re(e, t) {
+	Y(e, [
+		"ID",
+		"Title",
+		"Screens",
+		"Overlays"
+	], t.filter((e) => (e.frontmatter.xlsx?.role ?? "screen") === "screen").map((e) => [
+		e.frontmatter.id,
+		e.frontmatter.title ?? e.frontmatter.id,
+		e.screens.length,
+		e.overlays.length
+	]));
+}
+function Q(e, t) {
+	let n = e.sheet.getCell(e.box.startRow, e.box.startCol);
+	n.value = t, n.alignment = {
+		wrapText: !0,
+		vertical: "top"
+	};
+}
+function ie(e) {
+	let t = /* @__PURE__ */ new Map();
+	for (let n of e.worksheets) n.eachRow({ includeEmpty: !0 }, (e, r) => {
+		e.eachCell({ includeEmpty: !0 }, (e, i) => {
+			let a = ae(e);
+			for (let e of a) {
+				if (!e.startsWith(W)) continue;
+				let a = `${n.name}|${e}`, o = t.get(a);
+				o || (o = {
+					sheet: n,
+					name: e,
+					cells: []
+				}, t.set(a, o)), o.cells.push({
+					row: r,
+					col: i
+				});
+			}
+		});
+	});
+	return [...t.values()].map((e) => {
+		let t = e.cells.map((e) => e.row), n = e.cells.map((e) => e.col), r = {
+			startRow: Math.min(...t),
+			startCol: Math.min(...n),
+			endRow: Math.max(...t),
+			endCol: Math.max(...n)
+		};
+		return {
+			name: e.name,
+			sheet: e.sheet,
+			box: r,
+			address: `${$(r.startCol)}${r.startRow}:${$(r.endCol)}${r.endRow}`
+		};
+	});
+}
+function ae(e) {
+	return e.names ?? [];
+}
+function $(e) {
+	let t = e, n = "";
+	for (; t > 0;) {
+		let e = (t - 1) % 26;
+		n = String.fromCharCode(65 + e) + n, t = Math.floor((t - 1) / 26);
+	}
+	return n;
+}
+//#endregion
+export { l as applyDefaultLayout, G as applyNamedRanges, x as applyPlaceholders, S as applyPlaceholdersToSheet, k as applyTemplateLayout, N as buildEmptyWorkbook, L as cliMain, L as main, v as extractFromParsed, y as extractMdxFile, F as groupBundlesByBook, A as loadTemplateWorkbook, C as resolvePlaceholders, _ as sanitiseSheetName, u as sortBundlesForLayout, P as writeWorkbookToBytes };

package/dist/named-range.d.ts

@@ -0,0 +1,18 @@
+import { default as ExcelJS } from 'exceljs';
+import { ExcelMdxBundle } from './extract.js';
+export interface NamedRangeWriteInput {
+    workbook: ExcelJS.Workbook;
+    bundle: ExcelMdxBundle;
+    /** PNG bytes per `<Screen id>` (Phase 2 PR 2 Image Service). */
+    imagesByScreenId?: Record<string, Uint8Array>;
+    /** Fallback PNG when an `annotImage` (un-suffixed) range is
+     *  used and the MDX has exactly one screen. */
+    defaultImage?: Uint8Array;
+    /** All bundles in the same book — used by `annotList`. */
+    allBundles?: ExcelMdxBundle[];
+}
+/**
+ * Apply every recognised `annot*` named range in the workbook
+ * for one MDX bundle. Mutates the workbook in place.
+ */
+export declare function applyNamedRanges(input: NamedRangeWriteInput): void;

package/dist/placeholder.d.ts

@@ -0,0 +1,34 @@
+import { default as ExcelJS } from 'exceljs';
+import { ExcelMdxBundle } from './extract.js';
+export interface SubstituteOptions {
+    /** Project-level `meta` from `annot-docs.config.ts`. */
+    projectMeta?: Record<string, unknown>;
+    /** Used by `{annot:date}` / `{annot:datetime}`. Defaults to
+     *  `new Date()` per call but the pipeline can pin a single
+     *  `renderTime` across all substitutions so the workbook
+     *  has consistent timestamps. */
+    renderTime?: Date;
+    /** Used by `{annot:sheetIndex}` / `{annot:totalSheets}`. The
+     *  per-sheet wrapper passes the index of the sheet being
+     *  rendered + the total. */
+    sheetIndex?: number;
+    totalSheets?: number;
+}
+/**
+ * Walk every cell on every worksheet in the workbook and
+ * substitute `{var}` placeholders. Mutates in place.
+ */
+export declare function applyPlaceholders(workbook: ExcelJS.Workbook, bundle: ExcelMdxBundle, options?: SubstituteOptions): void;
+/**
+ * Single-sheet version — exposed so the template-driven path
+ * (which clones one template sheet per `<Screen>`) can call it
+ * after the clone.
+ */
+export declare function applyPlaceholdersToSheet(sheet: ExcelJS.Worksheet, bundle: ExcelMdxBundle, options?: SubstituteOptions): void;
+/**
+ * Pure string transform — replace every `{name}` or
+ * `{name:format}` token in a source string with its resolved
+ * value. Exposed for unit tests and for callers (sheet-name
+ * substitution, log messages, …).
+ */
+export declare function resolvePlaceholders(source: string, bundle: ExcelMdxBundle, options?: SubstituteOptions): string;

package/dist/template.d.ts

@@ -0,0 +1,28 @@
+import { BookConfig } from '@ingcreators/annot-product-docs';
+import { default as ExcelJS } from 'exceljs';
+import { ExcelMdxBundle } from './extract.js';
+import { SubstituteOptions } from './placeholder.js';
+export interface ApplyTemplateInput {
+    /** The empty workbook to populate. */
+    workbook: ExcelJS.Workbook;
+    /** Pre-loaded ExcelJS workbook from the customer template. */
+    template: ExcelJS.Workbook;
+    /** Per-book config from `annot-docs.config.ts`. */
+    bookConfig: BookConfig;
+    /** All bundles assigned to this book. */
+    bundles: ExcelMdxBundle[];
+    /** Substitution options forwarded to `applyPlaceholdersToSheet`. */
+    substitute?: SubstituteOptions;
+}
+/**
+ * Apply the customer template path. Mutates `workbook` in
+ * place: clones the configured template sheet for each role
+ * once per matching bundle, renames each clone, and runs
+ * placeholder substitution on every cloned cell.
+ */
+export declare function applyTemplateLayout(input: ApplyTemplateInput): void;
+/**
+ * Load a template workbook from disk. Thin wrapper around
+ * ExcelJS so the caller doesn't have to import it directly.
+ */
+export declare function loadTemplateWorkbook(path: string): Promise<ExcelJS.Workbook>;

package/dist/workbook.d.ts

@@ -0,0 +1,28 @@
+import { default as ExcelJS } from 'exceljs';
+import { ExcelMdxBundle } from './extract.js';
+export interface BuildWorkbookInput {
+    /** Book name from MDX frontmatter (`xlsx.book`). All MDXs for
+     *  this book end up in the same workbook. */
+    book: string;
+    /** All MDX bundles assigned to this book. */
+    bundles: ExcelMdxBundle[];
+}
+/**
+ * Produce an `ExcelJS.Workbook` with the book name set as the
+ * workbook title but no sheets yet. PR 2 of Phase 3 fills it
+ * with the default layout; PR 3 adds template support.
+ */
+export declare function buildEmptyWorkbook(input: BuildWorkbookInput): ExcelJS.Workbook;
+/**
+ * Serialise a workbook to PNG bytes. Wrapper around ExcelJS's
+ * `xlsx.writeBuffer` that normalises the return type to
+ * `Uint8Array` — ExcelJS uses Node `Buffer` natively.
+ */
+export declare function writeWorkbookToBytes(wb: ExcelJS.Workbook): Promise<Uint8Array>;
+/**
+ * Group a list of `ExcelMdxBundle`s by their `xlsx.book` value.
+ * MDXs without a book fall under the optional `defaultBook`
+ * key (typically wired from the project config); MDXs without
+ * either get filtered out.
+ */
+export declare function groupBundlesByBook(bundles: ExcelMdxBundle[], defaultBook?: string): Map<string, ExcelMdxBundle[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ingcreators/annot-product-docs-xlsx",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Excel adapter for `@ingcreators/annot-product-docs`. Walks MDX files with `annot:` frontmatter, fills customer-supplied Excel templates via `{var}` placeholders + named ranges, and emits one `.xlsx` per book. Phase 3 of docs/plans/living-product-docs.md.",
   "license": "Apache-2.0",
   "author": "ingcreators",
@@ -22,7 +22,7 @@
     "mdx",
     "docs",
     "screen-spec",
-    "画面設計書"
+    "screen-specifications"
   ],
   "type": "module",
   "main": "./dist/index.js",
@@ -47,12 +47,12 @@
   },
   "devDependencies": {
     "typescript": "^6.0.3",
-    "vite": "^6.4.2",
-    "vite-plugin-dts": "^5.0.0"
+    "vite": "^8.0.13",
+    "vite-plugin-dts": "^5.0.1"
   },
   "dependencies": {
     "exceljs": "^4.4.0",
-    "@ingcreators/annot-product-docs": "0.1.0"
+    "@ingcreators/annot-product-docs": "0.2.0"
   },
   "scripts": {
     "build": "vite build",