@openpresentation/opf 0.18.4 → 0.20.1

package/dist/repo-readme.js

@@ -1,5 +1,5 @@
 // src/generated/repo-readme.ts
-var repoReadmeRaw = '# Open Presentation Format (OPF)\n\n[![npm version](https://img.shields.io/npm/v/@openpresentation/opf?label=npm)](https://www.npmjs.com/package/@openpresentation/opf)\n[![npm downloads](https://img.shields.io/npm/dw/@openpresentation/opf)](https://www.npmjs.com/package/@openpresentation/opf)\n[![license](https://img.shields.io/npm/l/@openpresentation/opf)](./LICENSE)\n\nPublic npm package: [`@openpresentation/opf`](https://www.npmjs.com/package/@openpresentation/opf) (`npm install @openpresentation/opf`).\n\nOpen Presentation Format is the portable, human-readable JSON document format for slide decks.\n\nThis repository is the canonical home for the OPF **spec**, **JSON Schemas**, **catalog presets**, examples, generated developer types, local validation tooling, and integration docs for the render/edit/convert toolkit. OpenPresentation publishes open-source code and documentation only; it does not provide hosted APIs, hosted rendering functions, queues, storage, authentication, jobs, previews, SLAs, telemetry, or managed infrastructure.\n\nFor AI agents, use the [OPF skill set](docs/agent-skills.md) for authoring, layout, presets, editing, export, and schema inspection.\n\nPublished CLI 0.18.0 installs all six skills into your project with `npx @openpresentation/cli@0.18.0 skills install`. It uses local copies, preserves existing instructions and refuses to overwrite customized skills. See the [installation and update guide](docs/agent-skills.md) for personal or agent-specific targets and source development.\n\nFor a fresh Node 24 project that installs **published** packages (not this\ncheckout), follow the [developer quickstart](docs/quickstart.md) and the\n[compatibility matrix](docs/compatibility-matrix.md).\n\nFor LLM authoring, start with [the authoring guide](docs/llm-authoring.md), [dynamic composition](docs/dynamic-composition.md), and [local ecosystem verification](docs/ecosystem-development.md).\n\n## File naming\n\nOpen Presentation Format documents are JSON files. Use `*.opf.json` for complete OPF presentation documents, for example `board-review.opf.json` or `deck.opf.json`.\n\nAvoid using bare `*.opf` for OPF JSON. The `.opf` extension is already used by other document and project formats, while `.opf.json` keeps the OPF identity and still makes the underlying JSON format clear to editors, validators, agents, and version-control tooling.\n\n## Naming and reuse\n\nThe format name is **Open Presentation Format**. The schemas, catalogs, packages, and local tooling in this repository are free and open source under the MIT license, so third-party tools may read, write, validate, render, convert, and describe support for Open Presentation Format without adopting any product-specific branding.\n\n## Why OPF\n\n`.pptx` is a zipped bundle of XML. Humans can\'t diff it, LLMs can\'t read or write it reliably, and git can\'t track it meaningfully. Every change looks like a binary blob.\n\nOPF is plain JSON. A human can open it in an editor. A model can read and write it without guessing at schema-by-example. Decks live in git like the rest of your work.\n\nThat\'s the shift that lets LLMs actually *author* decks. When the format stops fighting them, models can do the work that matters \u2014 narrative structure, persuasive framing, data analysis, chart recommendations, ruthless revision passes \u2014 instead of wrestling with `<p:sp>` tags.\n\nAnd they don\'t start from a blank canvas. [pptx.gallery](https://pptx.gallery) is the human-browsable reference for OPF catalog presets: layouts, themes, color schemes, font schemes, chart types, narratives, audiences, purposes, tones, languages, and social platforms.\n\n## Start in three steps\n\n1. **Install the coordinated published packages** on Node 24. See [the developer quickstart](docs/quickstart.md) for the current pin set: core 0.18.1, renderer 0.18.0, editor 0.18.0, PPTX 0.18.0 and CLI 0.18.0.\n2. **Author, validate, paginate, preview and export.** Copy [`docs/quickstart/developer-quickstart.opf.json`](./docs/quickstart/developer-quickstart.opf.json) and run the commands in that guide. From code, `convert("deck.opf.md", "deck.pdf")` of `@openpresentation/opf` is the simple path to a PDF, PNG, SVG or PPTX file. `validate` / `opf validate` is one local checker for format, references, accessibility, layout and content ([guide](docs/validate.md)), not visual verification.\n3. **Know the limits.** The [compatibility matrix](docs/compatibility-matrix.md) lists shipped APIs versus renderer issue 24, native PowerPoint issue 87, and other deferred work. Browse presets at [pptx.gallery](https://pptx.gallery).\n\nYour deck can live in git from the first commit. After installing dependencies and supplying referenced assets, these commands run locally without a model provider, account or hosted OPF API.\n\n## JavaScript and TypeScript\n\nThe canonical JavaScript/TypeScript package is published at [`packages/javascript`](./packages/javascript) as [`@openpresentation/opf`](https://www.npmjs.com/package/@openpresentation/opf). The schema is pre-stable (0.x \u2014 expect breaking changes between minor versions until 1.0). Its responsibility is local and format-level only:\n\n- export the canonical schemas from [`spec/`](./spec)\n- export the pinned default catalog (the pptx.gallery snapshot in [`spec/catalogs/`](./spec/catalogs)) as the opt-in `@openpresentation/opf/catalog`, for hosts to register\n- export a typed raw spec file manifest for package-addressable `spec/` content\n- generate TypeScript types, with `Presentation` as the top-level type\n- validate OPF JSON and catalog records locally\n\nIn Node (and Bun and Deno) its root also reads and writes files (`convert`, `open`, `save`) and draws them through the optional engines below; in a browser or a worker the same import is a browser-safe build with the same names, where those three reject with `node-only`. Every other entry runs in a browser. It does not generate content with AI, fetch remote catalogs, call hosted APIs, or provide managed services. Render/edit/convert packages live in separate MIT repos that depend on `@openpresentation/opf`. The format package also exposes pure composition geometry so those packages share layout behavior.\n\n## Toolkit libraries\n\nOPF is five packages. **Core** (`@openpresentation/opf`) is the format and its API: it reads and writes the text formats (JSON, YAML, Markdown) and validates, and in Node reads and writes files, through the same import. **The CLI** (`@openpresentation/cli`) is the `opf` command. **Render** (`opf-render`), **PPTX** (`opf-pptx`) and **the editor** (`opf-editor`) are the engines: drawing, PowerPoint and editing, installed as needed. The engines and the editor live in sibling repositories. See [ecosystem development](docs/ecosystem-development.md) for coordinated builds and verification, and [dynamic composition](docs/dynamic-composition.md) for portable layout rules.\n\n| Repo | Role | Boundary |\n|---|---|---|\n| `cli` (`@openpresentation/cli`, this repository) | `opf` command | Runs core\'s Node engine: reads and writes files and calls the engines below as optional peers |\n| `opf-render` | OPF to SVG/PNG/PDF | Local and embeddable rendering library |\n| `opf-editor` | WYSIWYG bindings/components | Headless editor primitives plus optional UI components |\n| `opf-pptx` | OPF to PPTX and PPTX to OPF | Pure local import/export library for browser and server use where supported |\n\nThese repos provide OSS primitives only. Downstream applications own hosting, auth, storage, collaboration, queues, previews, analytics, support, and workflow UX.\n\n## Usage\n\nInstall from npm:\n\n```sh\npnpm add @openpresentation/opf\n# or: npm install @openpresentation/opf\n```\n\nTo work on the package itself, clone this repo and build the workspace:\n\n```sh\npnpm install\npnpm build\n```\n\nUse the format package from JavaScript or TypeScript:\n\n```ts\nimport { presentation, validate } from "@openpresentation/opf";\nimport { defaultCatalog } from "@openpresentation/opf/catalog";\n\nimport type { Presentation } from "@openpresentation/opf";\n\nconst deck: Presentation = {\n  name: "Quarterly Review",\n  slides: [{ title: "Quarterly Review", items: ["Revenue", "Product", "Hiring"] }],\n};\n\nconst report = validate(deck);\nconsole.log(report.valid); // no finding has severity "error"\nconsole.log(report.findings); // every finding: rule id, severity, category, JSON Pointer path, message, fixes\n// Core ships no catalog records in its main entry; a host registers the catalogs it trusts.\nconsole.log(validate({ ...deck, design: { theme: "classic" } }, { catalogs: [defaultCatalog] }).valid);\nconsole.log(Object.keys(defaultCatalog.audiences).length);\n```\n\nConvert, open and save files in Node with `@openpresentation/opf`, the same import a browser uses (the engines `@openpresentation/opf-render` and `@openpresentation/opf-pptx` are optional peers, installed as needed; see [OPF files in Node](docs/node.md)):\n\n```ts\nimport * as opf from "@openpresentation/opf";\n\nawait opf.convert("deck.opf.md", "deck.pdf");\nconst deck = await opf.open("deck.opf.md");\ndeck.slides.push({ title: "Q4" });\nawait opf.save(deck, "deck.opf.md");\nconst { files } = await opf.convert(deck, { format: "pptx" }); // bytes, nothing written\n```\n\nUse focused imports when you only need one surface:\n\n```ts\nimport { presentation } from "@openpresentation/opf/schemas";\nimport { defaultCatalog } from "@openpresentation/opf/catalog";\nimport { specFileEntries } from "@openpresentation/opf/spec-files";\nimport { validate } from "@openpresentation/opf/validator";\nimport type { Presentation } from "@openpresentation/opf/types";\n```\n\nUse raw JSON when an engine or resolver needs package-addressable files:\n\n```ts\nimport presentationSchema from "@openpresentation/opf/spec/schemas/opf.schema.json" with {\n  type: "json",\n};\n```\n\nUse the [installable OPF CLI](./packages/cli/README.md) to create, validate, and edit files locally:\n\n```sh\npnpm --filter @openpresentation/cli build\nnode packages/cli/dist/index.js create deck.opf.json --title "Decision brief"\nnode packages/cli/dist/index.js validate deck.opf.json\nnode packages/cli/dist/index.js edit deck.opf.json --patch changes.json --in-place\n```\n\nSee [CSV and JSON data import](./docs/data-import.md) for editable tables and charts in the editor, CLI, and package API, and [content conversions](./docs/conversions.md) for the pure converters (`@openpresentation/opf/convert`) that change a block\'s kind, nest list items, restructure a slide and split or merge slides, and [Markdown and outlines](./docs/markdown.md) for the deterministic Markdown dialect (`@openpresentation/opf/markdown`, `opf convert deck.md deck.opf.json`) that reads and writes a whole deck as text.\n\n[OPF as YAML](./docs/yaml.md) describes the strict YAML form of a deck (`@openpresentation/opf/yaml`, `opf convert deck.opf.json deck.opf.yaml`, `.opf.yaml` files in every command, editor autocomplete); JSON stays the canonical form. A deck can equally be a Markdown file, `deck.opf.md`: every command reads and writes it (see [Markdown decks in every command](./docs/markdown.md#markdown-decks-in-every-command)), and `parse` / `stringify` read and write a deck in JSON, YAML or Markdown with one call.\n\nSee [Templates and variables](./docs/templates-and-variables.md) for fillable OPF templates: typed variables, `{{id}}` tokens, `opf fill` and `resolveVariables`.\n\n## Layout\n\n| Path | Contents |\n|---|---|\n| [`spec/schemas/opf.schema.json`](./spec/schemas/opf.schema.json) | Canonical JSON Schema for top-level OPF `Presentation` documents. |\n| [`docs/how-opf-works.md`](./docs/how-opf-works.md) | Conceptual introduction: the document model, content shapes, catalog resolution, and the validation philosophy. Start here. |\n| [`docs/design-resolution.md`](./docs/design-resolution.md) | The design precedence algorithm (slide design \u2192 deck design \u2192 resolved theme \u2192 engine defaults) with worked examples. |\n| [`docs/schema-reference.md`](./docs/schema-reference.md) | Author-facing reference for top-level OPF fields and every presentation schema `$defs` object/type. |\n| [`docs/slide-sizes.md`](./docs/slide-sizes.md) | OPF\'s slide-size presets in inches, points and EMU, how they compare with PowerPoint\'s presets, and what PPTX export and import do with them. |\n| [`docs/catalog-schema-reference.md`](./docs/catalog-schema-reference.md) | Author-facing reference for every companion catalog schema. |\n| [`docs/content-payloads.md`](./docs/content-payloads.md) | Author-facing notes for slide and region content payloads, including chart and table object shapes. |\n| [`docs/footnotes-citations-captions.md`](./docs/footnotes-citations-captions.md) | Citations (`cite`), inline footnotes, the deck `references` list, captions on images, charts, tables and videos, and how every engine draws them. |\n| [`docs/examples.md`](./docs/examples.md) | Guide to the expanded scenario-oriented examples under `examples/gallery/`. |\n| [`docs/live-editor.md`](./docs/live-editor.md) | Browser canvas, live OPF editing, font loading, published packages, and current fidelity limits. |\n| [`docs/release-process.md`](./docs/release-process.md) | Maintainer runbook for tagging, trusted npm publishing, verification, and GitHub release notes. |\n| [`spec/schemas/*.schema.json`](./spec/schemas) | Companion schemas for catalog records and sub-objects. |\n| [`spec/catalogs/<catalog-kind>/`](./spec/catalogs) | The pinned snapshot of the default catalog pptx.gallery publishes (shipped as `@openpresentation/opf/catalog`). |\n| [`spec/openapi.yaml`](./spec/openapi.yaml) | Optional reference OpenAPI contract for downstream services that choose to expose OPF over HTTP. OpenPresentation does not host this API. |\n| [`examples/technical/`](./examples/technical) | Focused OPF fixtures for validator, renderer, catalog-resolution, design, content-payload, and region behavior. |\n| [`examples/gallery/`](./examples/gallery) | Broader OPF example decks organized by industry, function, education, government, presentation type, international, and design/media scenarios. |\n| [`packages/javascript/`](./packages/javascript) | Public pre-stable source for `@openpresentation/opf`. |\n| [`packages/cli/`](./packages/cli) | Installable local CLI for creating, validating, editing, and inspecting OPF. |\n| [`legacy/`](./legacy) | Tombstone for service-specific clients, CLIs, tool integrations, and workflows removed from the OpenPresentation OSS repo. |\n\n## OpenPresentation Boundary\n\nOpenPresentation defines the format, bundled presets, local validation, examples, docs, and planned local render/edit/convert libraries. It does not provide hosted functions or managed product surfaces.\n\nFuture non-JavaScript OPF packages should follow the same local-first boundary: Python and Go packages should expose schemas, types/models, catalogs, validation, and package-addressable assets. Future toolkit packages should expose embeddable library APIs with no required network calls, hosted callbacks, hidden telemetry, or managed infrastructure assumptions.\n\nThe published JavaScript package copies package-addressable OPF schemas, catalogs, reference assets, and the optional reference `spec/openapi.yaml` from `spec/`. It intentionally remains `@openpresentation/opf` instead of introducing a separate `@openpresentation/opf-spec` package so downstream imports can advance by semver-pinning one canonical package.\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n';
+var repoReadmeRaw = '# Open Presentation Format (OPF)\n\n[![npm version](https://img.shields.io/npm/v/@openpresentation/opf?label=npm)](https://www.npmjs.com/package/@openpresentation/opf)\n[![npm downloads](https://img.shields.io/npm/dw/@openpresentation/opf)](https://www.npmjs.com/package/@openpresentation/opf)\n[![license](https://img.shields.io/npm/l/@openpresentation/opf)](./LICENSE)\n\nPublic npm package: [`@openpresentation/opf`](https://www.npmjs.com/package/@openpresentation/opf) (`npm install @openpresentation/opf`).\n\nOpen Presentation Format is the portable, human-readable JSON document format for slide decks.\n\nThis repository is the canonical home for the OPF **spec**, **JSON Schemas**, **catalog presets**, examples, generated developer types, local validation tooling, and integration docs for the render/edit/convert toolkit. OpenPresentation publishes open-source code and documentation only; it does not provide hosted APIs, hosted rendering functions, queues, storage, authentication, jobs, previews, SLAs, telemetry, or managed infrastructure.\n\nFor AI agents, use the [OPF skill set](docs/agent-skills.md) for authoring, layout, presets, editing, export, and schema inspection.\n\nPublished CLI 0.18.0 installs all six skills into your project with `npx @openpresentation/cli@0.18.0 skills install`. It uses local copies, preserves existing instructions and refuses to overwrite customized skills. See the [installation and update guide](docs/agent-skills.md) for personal or agent-specific targets and source development.\n\nFor a fresh Node 24 project that installs **published** packages (not this\ncheckout), follow the [developer quickstart](docs/quickstart.md) and the\n[compatibility matrix](docs/compatibility-matrix.md).\n\nFor LLM authoring, start with [the authoring guide](docs/llm-authoring.md), [dynamic composition](docs/dynamic-composition.md), and [local ecosystem verification](docs/ecosystem-development.md).\n\n## File naming\n\nOpen Presentation Format documents are JSON files. Use `*.opf.json` for complete OPF presentation documents, for example `board-review.opf.json` or `deck.opf.json`.\n\nAvoid using bare `*.opf` for OPF JSON. The `.opf` extension is already used by other document and project formats, while `.opf.json` keeps the OPF identity and still makes the underlying JSON format clear to editors, validators, agents, and version-control tooling.\n\n## Naming and reuse\n\nThe format name is **Open Presentation Format**. The schemas, catalogs, packages, and local tooling in this repository are free and open source under the MIT license, so third-party tools may read, write, validate, render, convert, and describe support for Open Presentation Format without adopting any product-specific branding.\n\n## Why OPF\n\n`.pptx` is a zipped bundle of XML. Humans can\'t diff it, LLMs can\'t read or write it reliably, and git can\'t track it meaningfully. Every change looks like a binary blob.\n\nOPF is plain JSON. A human can open it in an editor. A model can read and write it without guessing at schema-by-example. Decks live in git like the rest of your work.\n\nThat\'s the shift that lets LLMs actually *author* decks. When the format stops fighting them, models can do the work that matters \u2014 narrative structure, persuasive framing, data analysis, chart recommendations, ruthless revision passes \u2014 instead of wrestling with `<p:sp>` tags.\n\nAnd they don\'t start from a blank canvas. [pptx.gallery](https://pptx.gallery) is the human-browsable reference for OPF catalog presets: layouts, themes, color schemes, font schemes, chart types, narratives, audiences, purposes, tones, languages, and social platforms.\n\n## Start in three steps\n\n1. **Install the coordinated published packages** on Node 24. See [the developer quickstart](docs/quickstart.md) for the currently recorded registry pin set: core 0.19.0, renderer 0.19.1, PPTX/editor/CLI 0.19.0 and Gallery 2.0.0. The default catalog is supplied by `@openpresentation/gallery@2.0.0`; see the [compatibility matrix](docs/compatibility-matrix.md) for feature and native limits.\n2. **Author, validate, paginate, preview and export.** Copy [`docs/quickstart/developer-quickstart.opf.json`](./docs/quickstart/developer-quickstart.opf.json) and run the commands in that guide. From code, `convert("deck.opf.md", "deck.pdf")` of `@openpresentation/opf` is the simple path to a PDF, PNG, SVG or PPTX file. `validate` / `opf validate` is one local checker for format, references, accessibility, layout and content ([guide](docs/validate.md)), not visual verification.\n3. **Know the limits.** The [compatibility matrix](docs/compatibility-matrix.md) lists shipped APIs versus renderer issue 24, native PowerPoint issue 87, and other deferred work. Browse presets at [pptx.gallery](https://pptx.gallery).\n\nYour deck can live in git from the first commit. After installing dependencies and supplying referenced assets, these commands run locally without a model provider, account or hosted OPF API.\n\n## JavaScript and TypeScript\n\nThe canonical JavaScript/TypeScript package is published at [`packages/javascript`](./packages/javascript) as [`@openpresentation/opf`](https://www.npmjs.com/package/@openpresentation/opf). The schema is pre-stable (0.x \u2014 expect breaking changes between minor versions until 1.0). Its responsibility is local and format-level only:\n\n- export the canonical schemas from [`spec/`](./spec)\n- register the pptx.gallery catalog of [`@openpresentation/gallery`](https://github.com/OpenPresentation/gallery) (a dependency, released on its own version line) as the Node defaults, as the CLI does; a browser host registers it itself\n- export a typed raw spec file manifest for package-addressable `spec/` content\n- generate TypeScript types, with `Presentation` as the top-level type\n- validate OPF JSON and catalog records locally\n\nIn Node (and Bun and Deno) its root also reads and writes files (`convert`, `open`, `save`) and draws them through the optional engines below; in a browser or a worker the same import is a browser-safe build with the same names, where those three reject with `node-only`. Every other entry runs in a browser. It does not generate content with AI, fetch remote catalogs, call hosted APIs, or provide managed services. Render/edit/convert packages live in separate MIT repos that depend on `@openpresentation/opf`. The format package also exposes pure composition geometry so those packages share layout behavior.\n\n## Toolkit libraries\n\nOPF is six packages. **Core** (`@openpresentation/opf`) is the format and its API: it reads and writes the text formats (JSON, YAML, Markdown) and validates, and in Node reads and writes files, through the same import. **The gallery** (`@openpresentation/gallery`) is the pptx.gallery catalog of layouts, themes, colour and font schemes and the other records, released on its own version line; core depends on it and registers it in Node. **The CLI** (`@openpresentation/cli`) is the `opf` command. **Render** (`opf-render`), **PPTX** (`opf-pptx`) and **the editor** (`opf-editor`) are the engines: drawing, PowerPoint and editing, installed as needed. The engines and the editor live in sibling repositories. See [ecosystem development](docs/ecosystem-development.md) for coordinated builds and verification, and [dynamic composition](docs/dynamic-composition.md) for portable layout rules.\n\n| Repo | Role | Boundary |\n|---|---|---|\n| `gallery` (`@openpresentation/gallery`, this repository) | The pptx.gallery catalog | Catalog records only, no runtime dependency; minor releases add records, a changed or removed record is a major release |\n| `cli` (`@openpresentation/cli`, this repository) | `opf` command | Runs core\'s Node engine: reads and writes files and calls the engines below as optional peers |\n| `opf-render` | OPF to SVG/PNG/PDF | Local and embeddable rendering library |\n| `opf-editor` | WYSIWYG bindings/components | Headless editor primitives plus optional UI components |\n| `opf-pptx` | OPF to PPTX and PPTX to OPF | Pure local import/export library for browser and server use where supported |\n\nThese repos provide OSS primitives only. Downstream applications own hosting, auth, storage, collaboration, queues, previews, analytics, support, and workflow UX.\n\n## Usage\n\nInstall from npm:\n\n```sh\npnpm add @openpresentation/opf\n# or: npm install @openpresentation/opf\n```\n\nTo work on the package itself, clone this repo and build the workspace:\n\n```sh\npnpm install\npnpm build\n```\n\nUse the format package from JavaScript or TypeScript:\n\n```ts\nimport { presentation, validate } from "@openpresentation/opf";\nimport { gallery } from "@openpresentation/gallery";\n\nimport type { Presentation } from "@openpresentation/opf";\n\nconst deck: Presentation = {\n  name: "Quarterly Review",\n  slides: [{ title: "Quarterly Review", items: ["Revenue", "Product", "Hiring"] }],\n};\n\nconst report = validate(deck);\nconsole.log(report.valid); // no finding has severity "error"\nconsole.log(report.findings); // every finding: rule id, severity, category, JSON Pointer path, message, fixes\n// Core ships no catalog records; in Node, validate registers the gallery when a call names no catalogs, and a host may name its own.\nconsole.log(validate({ ...deck, design: { theme: "classic" } }, { catalogs: [gallery] }).valid);\nconsole.log(Object.keys(gallery.audiences).length);\n```\n\nConvert, open and save files in Node with `@openpresentation/opf`, the same import a browser uses (the engines `@openpresentation/opf-render` and `@openpresentation/opf-pptx` are optional peers, installed as needed; see [OPF files in Node](docs/node.md)):\n\n```ts\nimport * as opf from "@openpresentation/opf";\n\nawait opf.convert("deck.opf.md", "deck.pdf");\nconst deck = await opf.open("deck.opf.md");\ndeck.slides.push({ title: "Q4" });\nawait opf.save(deck, "deck.opf.md");\nconst { files } = await opf.convert(deck, { format: "pptx" }); // bytes, nothing written\n```\n\nUse focused imports when you only need one surface:\n\n```ts\nimport { presentation } from "@openpresentation/opf/schemas";\nimport { specFileEntries } from "@openpresentation/opf/spec-files";\nimport { validate } from "@openpresentation/opf/validator";\nimport type { Presentation } from "@openpresentation/opf/types";\n```\n\nUse raw JSON when an engine or resolver needs package-addressable files:\n\n```ts\nimport presentationSchema from "@openpresentation/opf/spec/schemas/opf.schema.json" with {\n  type: "json",\n};\n```\n\nUse the [installable OPF CLI](./packages/cli/README.md) to create, validate, and edit files locally:\n\n```sh\npnpm --filter @openpresentation/cli build\nnode packages/cli/dist/index.js create deck.opf.json --title "Decision brief"\nnode packages/cli/dist/index.js validate deck.opf.json\nnode packages/cli/dist/index.js edit deck.opf.json --patch changes.json --in-place\n```\n\nSee [CSV and JSON data import](./docs/data-import.md) for editable tables and charts in the editor, CLI, and package API, and [content conversions](./docs/conversions.md) for the pure converters (`@openpresentation/opf/convert`) that change a block\'s kind, nest list items, restructure a slide and split or merge slides, and [Markdown and outlines](./docs/markdown.md) for the deterministic Markdown dialect (`@openpresentation/opf/markdown`, `opf convert deck.md deck.opf.json`) that reads and writes a whole deck as text.\n\n[OPF as YAML](./docs/yaml.md) describes the strict YAML form of a deck (`@openpresentation/opf/yaml`, `opf convert deck.opf.json deck.opf.yaml`, `.opf.yaml` files in every command, editor autocomplete); JSON stays the canonical form. A deck can equally be a Markdown file, `deck.opf.md`: every command reads and writes it (see [Markdown decks in every command](./docs/markdown.md#markdown-decks-in-every-command)), and `parse` / `stringify` read and write a deck in JSON, YAML or Markdown with one call.\n\nSee [Templates and variables](./docs/templates-and-variables.md) for fillable OPF templates: typed variables, `{{id}}` tokens, `opf fill` and `resolveVariables`.\n\n## Layout\n\n| Path | Contents |\n|---|---|\n| [`spec/schemas/opf.schema.json`](./spec/schemas/opf.schema.json) | Canonical JSON Schema for top-level OPF `Presentation` documents. |\n| [`docs/how-opf-works.md`](./docs/how-opf-works.md) | Conceptual introduction: the document model, content shapes, catalog resolution, and the validation philosophy. Start here. |\n| [`docs/design-resolution.md`](./docs/design-resolution.md) | The design precedence algorithm (slide design \u2192 deck design \u2192 resolved theme \u2192 engine defaults) with worked examples. |\n| [`docs/schema-reference.md`](./docs/schema-reference.md) | Author-facing reference for top-level OPF fields and every presentation schema `$defs` object/type. |\n| [`docs/slide-sizes.md`](./docs/slide-sizes.md) | OPF\'s slide-size presets in inches, points and EMU, how they compare with PowerPoint\'s presets, and what PPTX export and import do with them. |\n| [`docs/catalog-schema-reference.md`](./docs/catalog-schema-reference.md) | Author-facing reference for every companion catalog schema. |\n| [`docs/content-payloads.md`](./docs/content-payloads.md) | Author-facing notes for slide and region content payloads, including chart and table object shapes. |\n| [`docs/footnotes-citations-captions.md`](./docs/footnotes-citations-captions.md) | Citations (`cite`), inline footnotes, the deck `references` list, captions on images, charts, tables and videos, and how every engine draws them. |\n| [`docs/examples.md`](./docs/examples.md) | Guide to the expanded scenario-oriented examples under `examples/gallery/`. |\n| [`docs/live-editor.md`](./docs/live-editor.md) | Browser canvas, live OPF editing, font loading, published packages, and current fidelity limits. |\n| [`docs/release-process.md`](./docs/release-process.md) | Maintainer runbook for tagging, trusted npm publishing, verification, and GitHub release notes. |\n| [`spec/schemas/*.schema.json`](./spec/schemas) | Companion schemas for catalog records and sub-objects. |\n| [`@openpresentation/gallery`](https://github.com/OpenPresentation/gallery) | The independently published default catalog and layout previews. |\n| [`spec/openapi.yaml`](./spec/openapi.yaml) | Optional reference OpenAPI contract for downstream services that choose to expose OPF over HTTP. OpenPresentation does not host this API. |\n| [`examples/technical/`](./examples/technical) | Focused OPF fixtures for validator, renderer, catalog-resolution, design, content-payload, and region behavior. |\n| [`examples/gallery/`](./examples/gallery) | Broader OPF example decks organized by industry, function, education, government, presentation type, international, and design/media scenarios. |\n| [`packages/javascript/`](./packages/javascript) | Public pre-stable source for `@openpresentation/opf`. |\n| [`packages/cli/`](./packages/cli) | Installable local CLI for creating, validating, editing, and inspecting OPF. |\n| [`legacy/`](./legacy) | Tombstone for service-specific clients, CLIs, tool integrations, and workflows removed from the OpenPresentation OSS repo. |\n\n## OpenPresentation Boundary\n\nOpenPresentation defines the format, bundled presets, local validation, examples, docs, and planned local render/edit/convert libraries. It does not provide hosted functions or managed product surfaces.\n\nFuture non-JavaScript OPF packages should follow the same local-first boundary: Python and Go packages should expose schemas, types/models, catalogs, validation, and package-addressable assets. Future toolkit packages should expose embeddable library APIs with no required network calls, hosted callbacks, hidden telemetry, or managed infrastructure assumptions.\n\nThe published JavaScript package copies package-addressable OPF schemas, catalogs, reference assets, and the optional reference `spec/openapi.yaml` from `spec/`. It intentionally remains `@openpresentation/opf` instead of introducing a separate `@openpresentation/opf-spec` package so downstream imports can advance by semver-pinning one canonical package.\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n';
 
 // src/repo-readme.ts
 var repoReadme = repoReadmeRaw;

package/dist/schemas.d.ts

@@ -104,15 +104,7 @@ declare const theme: JsonSchemaDocument & {
 };
 declare const layout: JsonSchemaDocument & {
     readonly $defs: {
-        readonly "PlaceholderEntry": JsonObject;
-        readonly "PlaceholderGroup": JsonObject;
-        readonly "PlaceholderGroupEntry2": JsonObject;
-        readonly "PlaceholderGroup2": JsonObject;
-        readonly "PlaceholderGroupEntry3": JsonObject;
-        readonly "PlaceholderGroup3": JsonObject;
-        readonly "GroupedPlaceholder": JsonObject;
-        readonly "Placeholder": JsonObject;
-        readonly "ImagePlacement": JsonObject;
+        readonly "Region": JsonObject;
         readonly "DesignHints": JsonObject;
         readonly "Composition": JsonObject;
     };
@@ -241,15 +233,7 @@ declare const schemas: {
     };
     readonly layout: JsonSchemaDocument & {
         readonly $defs: {
-            readonly "PlaceholderEntry": JsonObject;
-            readonly "PlaceholderGroup": JsonObject;
-            readonly "PlaceholderGroupEntry2": JsonObject;
-            readonly "PlaceholderGroup2": JsonObject;
-            readonly "PlaceholderGroupEntry3": JsonObject;
-            readonly "PlaceholderGroup3": JsonObject;
-            readonly "GroupedPlaceholder": JsonObject;
-            readonly "Placeholder": JsonObject;
-            readonly "ImagePlacement": JsonObject;
+            readonly "Region": JsonObject;
             readonly "DesignHints": JsonObject;
             readonly "Composition": JsonObject;
         };

package/dist/schemas.js

@@ -1 +1 @@
-export { audience, chartType, colorScheme, fontScheme, language, layout, narrative, presentation, purpose, schemaEntries, schemaNames, schemas, socialPlatform, theme, tone } from './chunk-2PEWUUBR.js';
+export { audience, chartType, colorScheme, fontScheme, language, layout, narrative, presentation, purpose, schemaEntries, schemaNames, schemas, socialPlatform, theme, tone } from './chunk-VEHLQVGQ.js';

package/dist/spec/README.md

@@ -9,37 +9,30 @@ New to the format? Read [`docs/how-opf-works.md`](../docs/how-opf-works.md) firs
 | Path | Contents |
 |---|---|
 | [`schemas/opf.schema.json`](./schemas/opf.schema.json) | Canonical JSON Schema for top-level OPF `Presentation` documents (`$id: https://openpresentation.org/schema/opf/v1`). |
-| [`schemas/*.schema.json`](./schemas) | Companion schemas for catalog records. Each has a stable `$id` of the form `https://openpresentation.org/schema/opf-<kind>/v1` (e.g. `opf-narrative`, `opf-theme`, `opf-chart-type`). Three schemas in this directory — `catalog-index.schema.json`, `catalog-manifest.schema.json`, and `layout-preview-index.schema.json` — describe repo-internal index and manifest files instead (see rows below); they are not OPF document or catalog-record schemas and are intentionally excluded from the package's published/typed schema surface (`schemaNames` / generated types). |
+| [`schemas/*.schema.json`](./schemas) | Companion schemas for catalog records. Layouts use `https://openpresentation.org/schema/opf-layout/v2`; other companion schemas retain `$id`s of the form `https://openpresentation.org/schema/opf-<kind>/v1` (e.g. `opf-narrative`, `opf-theme`, `opf-chart-type`). Three schemas in this directory — `catalog-index.schema.json`, `catalog-manifest.schema.json`, and `layout-preview-index.schema.json` — describe repo-internal index and manifest files instead (see rows below); they are not OPF document or catalog-record schemas and are intentionally excluded from the package's published/typed schema surface (`schemaNames` / generated types). |
 | [`schemas/finding.schema.json`](./schemas/finding.schema.json) | The report format every OPF tool shares (`$id: https://openpresentation.org/schema/opf-finding/v1`): a finding is one thing a checker found at one place in a presentation, and a report lists them. `validate`, the Markdown and YAML converters, the editor's Review panel and hosted reviewers produce it. It is not a catalog-record schema, but unlike the three index schemas it is part of the published, typed schema surface (`schemaNames`, `Finding`, `FindingReport`). See [`docs/validate.md`](../docs/validate.md). |
-| [`catalogs/<kind>/`](./catalogs) | Bundled catalog records, one JSON file per record plus an `index.json` per kind. They are a pinned snapshot of the default catalog that pptx.gallery publishes at `https://www.pptx.gallery/<kind>/index.json`: engines resolve the default catalog from these files and never fetch it at run time. Every `index.json` validates against `schemas/catalog-index.schema.json` (`$id: https://openpresentation.org/schema/opf-catalog-index/v1`), a generic shape shared across all 11 kinds, and carries a `contentSha256` of its records. Do not edit these files by hand; change the gallery and run `scripts/sync-gallery-catalog.mjs` (see [`docs/default-catalog.md`](../docs/default-catalog.md)). RR-78: the same records are published as `@openpresentation/gallery` from [OpenPresentation/gallery](https://github.com/OpenPresentation/gallery); from OPF 0.19 core depends on that package and this directory and `previews/layouts/` go away. |
-| [`catalogs/manifest.json`](./catalogs/manifest.json) | Pins the snapshot: the pptx-gallery commit it came from and, per kind, `mirror`/`subset` mode, record count and content hash. Validates against `schemas/catalog-manifest.schema.json` (`$id: https://openpresentation.org/schema/opf-catalog-manifest/v1`). `check:spec` fails when the bundled records no longer match it. |
-| [`previews/layouts/`](./previews/layouts) | Vendored HTML previews for the **slide archetype gallery** (e.g. `swot-analysis`, `agenda`, `org-chart`) — see "Preview gallery vs. layout catalog" below. Its `index.json` validates against `schemas/layout-preview-index.schema.json` (`$id: https://openpresentation.org/schema/opf-layout-preview-index/v1`). |
+| Catalog records (not in this directory) | Since OPF 0.19 (RR-78) the catalog records, their `manifest.json` and the layout previews are the `@openpresentation/gallery` package ([OpenPresentation/gallery](https://github.com/OpenPresentation/gallery)): a pinned snapshot of the default catalog pptx.gallery publishes at `https://www.pptx.gallery/<kind>/index.json`, which hosts register with `catalogs: [gallery]` and engines never fetch. Every `index.json` validates against `schemas/catalog-index.schema.json` (`$id: https://openpresentation.org/schema/opf-catalog-index/v1`), the manifest against `schemas/catalog-manifest.schema.json` and the preview index against `schemas/layout-preview-index.schema.json`; `check:spec` fails when the records no longer match the manifest. Do not edit the records by hand; change pptx.gallery and synchronize the gallery repository (see [`docs/default-catalog.md`](../docs/default-catalog.md)). |
 | [`reference/engine-defaults.json`](./reference/engine-defaults.json) | Reference example of engine-side defaults. Engine configuration, not part of the OPF document contract; it has no JSON Schema. |
 | [`openapi.yaml`](./openapi.yaml) | Optional reference OpenAPI 3.1 contract for downstream services that choose to expose OPF operations (validate, parse, convert, generate, render) over HTTP. OpenPresentation does not host this API; implementers can use it as a starting point for their own hosted or internal services. Local format tooling never needs it. |
 
-## Preview gallery vs. layout catalog
+## Layout templates and previews
 
-`spec/catalogs/layouts/` and `spec/previews/layouts/` are two unrelated taxonomies that happen to share a directory name. Do not assume a preview id corresponds to a layout catalog id — none of them do.
+The gallery package's `catalog/layouts/` contains the 28 v2 intent templates that `Slide.layout` resolves against. They define named grid areas and content regions; examples include `cover`, `text`, `chart` and `two-column`.
 
-- **`spec/catalogs/layouts/`** is the **structural layout catalog**: 28 records (`title`, `title-subtitle`, `text-1x`…`text-3x`, `list-1x`…`list-6x`, `chart-1x`…`chart-3x`, `image-1x`…`image-3x`, `blank`, …) that `Slide.layout` resolves against. These describe placeholder structure — how many regions a slide has and what kind of content goes where — independent of subject matter.
-- **`spec/previews/layouts/`** is the **slide archetype preview gallery**: 70 self-contained HTML snippets keyed by subject-matter archetype (`swot-analysis`, `agenda`, `org-chart`, `pricing-table`, `roadmap`, …), used to render picker thumbnails. These ids describe *what a slide is about*, not its structural layout, and are never used as a `Slide.layout` value.
+`previews/layouts/` contains one self-contained SVG preview for each template, keyed by the same layout id. Its version-2 index names the SVG filename and exact UTF-8 byte length. Picker thumbnails therefore show the template the slide will use.
 
-The preview HTML files are **vendored, generated artifacts**, not hand-authored spec content. They're produced by rendering React/Tailwind components from `lib/layout-previews.tsx` in the sibling `pptx-gallery` repo via `packages/javascript/scripts/render-layout-previews.mjs`, which requires a local `../pptx-gallery` checkout (a sibling directory to this repo) to run:
-
-```sh
-node --import tsx packages/javascript/scripts/render-layout-previews.mjs
-```
-
-Without that sibling checkout, treat `spec/previews/layouts/*.html` and `index.json` as read-only committed output — edit the source components in `pptx-gallery` and re-render, rather than hand-editing the generated HTML here.
+The gallery repository owns both records and SVG previews. `pnpm install` materializes ignored copies from the installed package under `packages/gallery/` for schema and tracker checks.
 
 ## Consuming this directory
 
 Validate a document and load catalog records without touching the files directly:
 
 ```ts
-import { validate, narratives } from "@openpresentation/opf";
+import { validate } from "@openpresentation/opf";
+import { gallery } from "@openpresentation/gallery";
 
-const report = validate(deck);
+const report = validate(deck, { catalogs: [gallery] }); // in Node, validate(deck) registers the gallery too
+const qbr = gallery.narratives.qbr;
 // report.valid    — no finding has severity "error"
 // report.findings — every finding: rule id, severity, category, JSON Pointer path, message, fixes
 // report.counts   — { error, warning, info }
@@ -49,10 +42,10 @@ Import the raw files when an engine, resolver, or non-JavaScript toolchain needs
 
 ```ts
 import presentationSchema from "@openpresentation/opf/spec/schemas/opf.schema.json" with { type: "json" };
-import qbr from "@openpresentation/opf/spec/catalogs/narratives/qbr.json" with { type: "json" };
+import narrativeSchema from "@openpresentation/opf/spec/schemas/narrative.schema.json" with { type: "json" };
 ```
 
-The same paths work for any validator in any language: point a JSON Schema draft 2020-12 implementation at `schemas/opf.schema.json` and validate `.opf.json` files against it. Catalog records validate against their kind's companion schema.
+The same paths work for any validator in any language: point a JSON Schema draft 2020-12 implementation at `schemas/opf.schema.json` and validate `.opf.json` files against it. Catalog records (pptx.gallery serves each one at `https://www.pptx.gallery/<kind>/<id>.json`) validate against their kind's companion schema.
 
 ## YAML
 

package/dist/spec/reference/engine-vocabularies.json

@@ -1,5 +1,5 @@
 {
-  "description": "Engine vocabularies of OPF 0.15: the values an engine must understand to draw, validated directly with no catalog lookup. chartTypes are the values of chart.type; socialPlatforms are the keys of Organization.socials and Speaker.socials with the URL patterns engines link a handle with; languages are the BCP-47 tags engines know the script, base direction, OOXML language tag and default script fonts of (any other well-formed tag is accepted, with its script inferred). Labels, descriptions, icons and brand colours are catalog display metadata, published by pptx.gallery and shipped in @openpresentation/opf/catalog. Core compiles this file into its engine code (scripts/generate.mjs).",
+  "description": "Engine vocabularies of OPF 0.15: the values an engine must understand to draw, validated directly with no catalog lookup. chartTypes are the values of chart.type; socialPlatforms are the keys of Organization.socials and Speaker.socials with the URL patterns engines link a handle with; languages are the BCP-47 tags engines know the script, base direction, OOXML language tag and default script fonts of (any other well-formed tag is accepted, with its script inferred). Labels, descriptions, icons and brand colours are catalog display metadata, published by pptx.gallery and shipped in @openpresentation/gallery. Core compiles this file into its engine code (scripts/generate.mjs).",
   "chartTypes": [
     "100pct-stacked-area",
     "100pct-stacked-bar",

package/dist/spec/schemas/catalog-index.schema.json

@@ -2,13 +2,13 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-catalog-index/v1",
   "title": "Catalog Index",
-  "description": "Generic shape shared by every `spec/catalogs/<kind>/index.json` file in the OPF repo and by the default-catalog index that pptx.gallery publishes at `https://www.pptx.gallery/<kind>/index.json` (spec/catalogs is a pinned snapshot of that catalog; see docs/default-catalog.md). An index is a lightweight, ordered summary of the full-record JSON files that live alongside it: each entry names the record's stable id, a human-readable name, and the record's filename, plus whatever extra summary fields are useful for picker UIs (e.g. `summary`, `tags`, `bcp47`, `duration`). This schema describes catalog index files themselves, not OPF documents or individual catalog records — it is not part of the OPF document contract and is intentionally excluded from the package's published/typed schema surface.",
+  "description": "Generic shape shared by every `<kind>/index.json` file of the @openpresentation/gallery package (packages/gallery/catalog in the OPF repo) and by the default-catalog index that pptx.gallery publishes at `https://www.pptx.gallery/<kind>/index.json` (the gallery package is a pinned snapshot of that catalog; see docs/default-catalog.md). An index is a lightweight, ordered summary of the full-record JSON files that live alongside it: each entry names the record's stable id, a human-readable name, and the record's filename, plus whatever extra summary fields are useful for picker UIs (e.g. `summary`, `tags`, `bcp47`, `duration`). This schema describes catalog index files themselves, not OPF documents or individual catalog records — it is not part of the OPF document contract and is intentionally excluded from the package's published/typed schema surface.",
   "type": "object",
   "required": ["$schema", "version", "description", "records"],
   "additionalProperties": false,
   "patternProperties": {
     "^x-": {
-      "description": "Publisher extension member, such as pptx.gallery's `x-gallery` reconciliation status. Consumers ignore top-level `x-*` members, and the pinned snapshot in spec/catalogs never carries them."
+      "description": "Publisher extension member, such as pptx.gallery's `x-gallery` reconciliation status. Consumers ignore top-level `x-*` members, and the pinned snapshot in @openpresentation/gallery never carries them."
     }
   },
   "properties": {
@@ -18,7 +18,7 @@
     },
     "kind": {
       "type": "string",
-      "description": "Catalog kind, as the URL segment of the default catalog (`https://www.pptx.gallery/<kind>`) and the `spec/catalogs/<kind>` directory name.",
+      "description": "Catalog kind, as the URL segment of the default catalog (`https://www.pptx.gallery/<kind>`) and the `packages/gallery/catalog/<kind>` directory name.",
       "enum": [
         "audiences",
         "chart-types",

package/dist/spec/schemas/catalog-manifest.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-catalog-manifest/v1",
   "title": "Catalog Snapshot Manifest",
-  "description": "Shape of `spec/catalogs/manifest.json`, which pins the snapshot of the default OPF catalog published by pptx.gallery (shipped as @openpresentation/opf/catalog). It records the gallery commit the snapshot came from and, per kind, how the snapshot relates to the published catalog plus a content hash of the bundled records. Written by scripts/sync-gallery-catalog.mjs and checked by scripts/check-spec-integrity.mjs; see docs/default-catalog.md. This schema describes a repo-internal file, not an OPF document or a catalog record; it is intentionally excluded from the package's published/typed schema surface.",
+  "description": "Shape of the `manifest.json` of the @openpresentation/gallery package (packages/gallery/catalog/manifest.json), which pins the snapshot of the default OPF catalog published by pptx.gallery. It records the gallery commit the snapshot came from and, per kind, how the snapshot relates to the published catalog plus a content hash of the bundled records. Written by scripts/sync-gallery-catalog.mjs and checked by scripts/check-spec-integrity.mjs; see docs/default-catalog.md. This schema describes a repo-internal file, not an OPF document or a catalog record; it is intentionally excluded from the package's published/typed schema surface.",
   "type": "object",
   "required": ["$schema", "description", "publisher", "source", "kinds"],
   "additionalProperties": false,

package/dist/spec/schemas/chart-type.schema.json

@@ -2,12 +2,12 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-chart-type/v1",
   "title": "Chart Type",
-  "description": "Schema for chart-type records: display metadata for chart pickers (name, group, expected series, complexity) and the Open XML mapping a picker can describe. One record per chart type that Aspose.Slides officially supports (see mappings.renderers[\"aspose-slides\"].chartType), plus the column-and-line combination 'combo'. A document's chart.type is an engine vocabulary validated directly; engines never look a chart-type record up. pptx.gallery publishes these records and @openpresentation/opf/catalog ships them as catalogDisplay.chartTypes.",
+  "description": "Schema for chart-type records: display metadata for chart pickers (name, group, expected series, complexity) and the Open XML mapping a picker can describe. One record per chart type that Aspose.Slides officially supports (see mappings.renderers[\"aspose-slides\"].chartType), plus the column-and-line combination 'combo'. A document's chart.type is an engine vocabulary validated directly; engines never look a chart-type record up. pptx.gallery publishes these records and @openpresentation/gallery ships them as catalogDisplay.chartTypes.",
   "type": "object",
   "additionalProperties": false,
   "patternProperties": {
     "^x-": {
-      "description": "Publisher extension member, such as the `x-gallery` presentation metadata that pptx.gallery adds to the records it publishes. Engines and validators ignore top-level `x-*` members, and the pinned snapshot in spec/catalogs never carries them."
+      "description": "Publisher extension member, such as the `x-gallery` presentation metadata that pptx.gallery adds to the records it publishes. Engines and validators ignore top-level `x-*` members, and the pinned snapshot in @openpresentation/gallery never carries them."
     }
   },
   "required": [

package/dist/spec/schemas/language.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-language/v1",
   "title": "Language",
-  "description": "Schema for language records: display metadata for the language pickers of authoring tools (name, ISO code, the default font schemes a picker suggests). The document's 'language' is an engine vocabulary, a BCP-47 tag validated directly; engines never look a language record up, and their script, direction, OOXML tag and default script fonts come from spec/reference/engine-vocabularies.json. pptx.gallery publishes these records and @openpresentation/opf/catalog ships them as catalogDisplay.languages.",
+  "description": "Schema for language records: display metadata for the language pickers of authoring tools (name, ISO code, the default font schemes a picker suggests). The document's 'language' is an engine vocabulary, a BCP-47 tag validated directly; engines never look a language record up, and their script, direction, OOXML tag and default script fonts come from spec/reference/engine-vocabularies.json. pptx.gallery publishes these records and @openpresentation/gallery ships them as catalogDisplay.languages.",
   "type": "object",
   "required": [
     "$schema",

package/dist/spec/schemas/layout-preview-index.schema.json

@@ -2,9 +2,14 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-layout-preview-index/v1",
   "title": "Layout Preview Index",
-  "description": "Shape of `spec/previews/layouts/index.json`, the manifest for the vendored slide-archetype preview gallery under `spec/previews/layouts/`. Each record names a preview id, its self-contained HTML file, and the file's exact UTF-8 byte length. These preview ids are an archetype taxonomy (e.g. 'swot-analysis', 'org-chart') distinct from the structural layout catalog at spec/catalogs/layouts/ (e.g. 'title', 'chart-2x') — see spec/README.md. This schema describes a repo-internal index file, not an OPF document or a catalog record; it is intentionally excluded from the package's published/typed schema surface.",
+  "description": "Shape of previews/layouts/index.json in @openpresentation/gallery 2: one self-contained SVG preview per v2 intent layout, keyed by the matching catalog layout id. Each record names its SVG file and exact UTF-8 byte length. The gallery package owns the files; this checkout materializes ignored copies under packages/gallery/previews/layouts/. This internal index schema is excluded from the package's published/typed schema surface.",
   "type": "object",
-  "required": ["$schema", "version", "description", "records"],
+  "required": [
+    "$schema",
+    "version",
+    "description",
+    "records"
+  ],
   "additionalProperties": false,
   "properties": {
     "$schema": {
@@ -14,7 +19,10 @@
     "version": {
       "type": "string",
       "description": "Index format version, as a string.",
-      "examples": ["1"]
+      "examples": [
+        "2"
+      ],
+      "const": "2"
     },
     "description": {
       "type": "string",
@@ -22,31 +30,37 @@
     },
     "records": {
       "type": "array",
-      "description": "One entry per vendored preview HTML file.",
-      "items": { "$ref": "#/$defs/PreviewRecord" }
+      "description": "One entry per v2 layout and its SVG preview.",
+      "items": {
+        "$ref": "#/$defs/PreviewRecord"
+      }
     }
   },
   "$defs": {
     "PreviewRecord": {
       "type": "object",
-      "description": "Summary of one vendored preview HTML file.",
-      "required": ["id", "file", "bytes"],
+      "description": "One layout template preview.",
+      "required": [
+        "id",
+        "file",
+        "bytes"
+      ],
       "additionalProperties": false,
       "properties": {
         "id": {
           "type": "string",
-          "description": "Slide-archetype preview id (e.g. 'swot-analysis', 'agenda', 'org-chart'). Does not correspond to a spec/catalogs/layouts/ record id.",
+          "description": "The matching layout record id, such as cover, chart or two-column.",
           "pattern": "^[a-z][a-z0-9-]*$"
         },
         "file": {
           "type": "string",
-          "description": "HTML filename, relative to this index file's directory.",
-          "pattern": "^[^/]+\\.html$"
+          "description": "SVG filename, relative to this index directory, using the matching layout id.",
+          "pattern": "^[a-z][a-z0-9-]*\\.svg$"
         },
         "bytes": {
           "type": "integer",
           "minimum": 0,
-          "description": "Exact UTF-8 byte length of the referenced HTML file's contents."
+          "description": "Exact UTF-8 byte length of the referenced SVG file."
         }
       }
     }