@openpresentation/opf 0.13.0 → 0.14.0

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.10.0 installs all six skills into your project with `npx @openpresentation/cli@0.10.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.12.1, renderer 0.12.0, editor 0.11.2, PPTX 0.12.3 and CLI 0.10.0.\n2. **Author, lint, paginate, preview and export.** Copy [`docs/quickstart/developer-quickstart.opf.json`](./docs/quickstart/developer-quickstart.opf.json) and run the commands in that guide. `validatePresentation` / `opf validate` is local schema checking, 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 bundled catalog records from [`spec/`](./spec)\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\nIt does not render `.pptx`, parse `.pptx`, 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\nThe local toolkit lives 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| `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 {\n  presentation,\n  audiences,\n  purposes,\n  tones,\n  validatePresentation,\n} from "@openpresentation/opf";\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 result = validatePresentation(deck);\nconsole.log(result.valid); // schema correctness\nconsole.log(result.warnings); // advisory issues, e.g. unknown catalog ids\nconsole.log(audiences.length, purposes.length, tones.length);\n```\n\nUse focused imports when you only need one surface:\n\n```ts\nimport { presentation } from "@openpresentation/opf/schemas";\nimport { audiences, purposes } from "@openpresentation/opf/catalogs";\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 from-md`, `opf to-md`) that reads and writes a whole deck as text.\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/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) | Canonical bundled catalog records. |\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.11.0 installs all six skills into your project with `npx @openpresentation/cli@0.11.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.13.0, renderer 0.13.1, editor 0.12.1, PPTX 0.13.2 and CLI 0.11.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. `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 bundled catalog records from [`spec/`](./spec)\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\nIt does not render `.pptx`, parse `.pptx`, 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\nThe local toolkit lives 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| `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 {\n  presentation,\n  audiences,\n  purposes,\n  tones,\n  validate,\n} from "@openpresentation/opf";\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\nconsole.log(audiences.length, purposes.length, tones.length);\n```\n\nUse focused imports when you only need one surface:\n\n```ts\nimport { presentation } from "@openpresentation/opf/schemas";\nimport { audiences, purposes } from "@openpresentation/opf/catalogs";\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 from-md`, `opf to-md`) 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 from-yaml`, `opf to-yaml`, `.opf.yaml` files in every command, editor autocomplete); JSON stays the canonical form.\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/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) | Canonical bundled catalog records. |\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-BbPonsTz.d.ts → schemas-DDpqAgyS.d.ts}

@@ -3,7 +3,6 @@ type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
 interface JsonObject {
     readonly [key: string]: JsonValue;
 }
-type JsonSchema = JsonObject;
 /**
  * Structural shape of a bundled JSON Schema document (the schema itself, not
  * data validated against it). Kept intentionally loose — `$id`/`$schema` are
@@ -28,13 +27,11 @@ declare const presentation: JsonSchemaDocument & {
         readonly "Organization": JsonObject;
         readonly "Speaker": JsonObject;
         readonly "Socials": JsonObject;
-        readonly "Narrative": JsonObject;
-        readonly "NarrativeBeat": JsonObject;
         readonly "Design": JsonObject;
         readonly "Theme": JsonObject;
         readonly "ColorScheme": JsonObject;
         readonly "FontScheme": JsonObject;
-        readonly "Font": JsonObject;
+        readonly "SlideDesign": JsonObject;
         readonly "DimensionPreset": JsonObject;
         readonly "Dimensions": JsonObject;
         readonly "ThemeBackgroundSlot": JsonObject;
@@ -78,6 +75,7 @@ declare const presentation: JsonSchemaDocument & {
         readonly "Reference": JsonObject;
         readonly "Chart": JsonObject;
         readonly "ChartAxisTitles": JsonObject;
+        readonly "ChartHighlight": JsonObject;
         readonly "ChartDataLabels": JsonObject;
         readonly "Table": JsonObject;
         readonly "ChartData": JsonObject;
@@ -89,7 +87,6 @@ declare const presentation: JsonSchemaDocument & {
         readonly "Dataset": JsonObject;
         readonly "DatasetRef": JsonObject;
         readonly "ChartMapping": JsonObject;
-        readonly "ChartDataSource": JsonObject;
         readonly "ChartDataCell": JsonObject;
         readonly "TableCell": JsonObject;
         readonly "TableCellValue": JsonObject;
@@ -115,6 +112,7 @@ declare const theme: JsonSchemaDocument & {
 declare const layout: JsonSchemaDocument & {
     readonly $defs: {
         readonly "Placeholder": JsonObject;
+        readonly "DesignHints": JsonObject;
         readonly "Composition": JsonObject;
     };
 };
@@ -123,8 +121,6 @@ declare const chartType: JsonSchemaDocument & {
         readonly "ChartTypeDeprecation": JsonObject;
         readonly "ChartTypeMappings": JsonObject;
         readonly "OpenXmlChartMapping": JsonObject;
-        readonly "ChartDataColumn": JsonObject;
-        readonly "ChartSampleData": JsonObject;
     };
 };
 declare const narrative: JsonSchemaDocument & {
@@ -134,7 +130,11 @@ declare const narrative: JsonSchemaDocument & {
 };
 declare const socialPlatform: JsonSchemaDocument;
 declare const language: JsonSchemaDocument;
-declare const colorScheme: JsonSchemaDocument;
+declare const colorScheme: JsonSchemaDocument & {
+    readonly $defs: {
+        readonly "HexColor": JsonObject;
+    };
+};
 declare const fontScheme: JsonSchemaDocument;
 declare const schemas: {
     readonly presentation: JsonSchemaDocument & {
@@ -148,13 +148,11 @@ declare const schemas: {
             readonly "Organization": JsonObject;
             readonly "Speaker": JsonObject;
             readonly "Socials": JsonObject;
-            readonly "Narrative": JsonObject;
-            readonly "NarrativeBeat": JsonObject;
             readonly "Design": JsonObject;
             readonly "Theme": JsonObject;
             readonly "ColorScheme": JsonObject;
             readonly "FontScheme": JsonObject;
-            readonly "Font": JsonObject;
+            readonly "SlideDesign": JsonObject;
             readonly "DimensionPreset": JsonObject;
             readonly "Dimensions": JsonObject;
             readonly "ThemeBackgroundSlot": JsonObject;
@@ -198,6 +196,7 @@ declare const schemas: {
             readonly "Reference": JsonObject;
             readonly "Chart": JsonObject;
             readonly "ChartAxisTitles": JsonObject;
+            readonly "ChartHighlight": JsonObject;
             readonly "ChartDataLabels": JsonObject;
             readonly "Table": JsonObject;
             readonly "ChartData": JsonObject;
@@ -209,7 +208,6 @@ declare const schemas: {
             readonly "Dataset": JsonObject;
             readonly "DatasetRef": JsonObject;
             readonly "ChartMapping": JsonObject;
-            readonly "ChartDataSource": JsonObject;
             readonly "ChartDataCell": JsonObject;
             readonly "TableCell": JsonObject;
             readonly "TableCellValue": JsonObject;
@@ -235,6 +233,7 @@ declare const schemas: {
     readonly layout: JsonSchemaDocument & {
         readonly $defs: {
             readonly "Placeholder": JsonObject;
+            readonly "DesignHints": JsonObject;
             readonly "Composition": JsonObject;
         };
     };
@@ -243,8 +242,6 @@ declare const schemas: {
             readonly "ChartTypeDeprecation": JsonObject;
             readonly "ChartTypeMappings": JsonObject;
             readonly "OpenXmlChartMapping": JsonObject;
-            readonly "ChartDataColumn": JsonObject;
-            readonly "ChartSampleData": JsonObject;
         };
     };
     readonly narrative: JsonSchemaDocument & {
@@ -254,10 +251,27 @@ declare const schemas: {
     };
     readonly socialPlatform: JsonSchemaDocument;
     readonly language: JsonSchemaDocument;
-    readonly colorScheme: JsonSchemaDocument;
+    readonly colorScheme: JsonSchemaDocument & {
+        readonly $defs: {
+            readonly "HexColor": JsonObject;
+        };
+    };
     readonly fontScheme: JsonSchemaDocument;
+    readonly finding: JsonSchemaDocument & {
+        readonly $defs: {
+            readonly "FindingSeverity": JsonObject;
+            readonly "FindingCategory": JsonObject;
+            readonly "FindingLocation": JsonObject;
+            readonly "JsonPatchOperation": JsonObject;
+            readonly "FindingFocus": JsonObject;
+            readonly "FindingFix": JsonObject;
+            readonly "FindingSuggestion": JsonObject;
+            readonly "ValidationIssue": JsonObject;
+            readonly "Finding": JsonObject;
+        };
+    };
 };
-declare const schemaNames: readonly ["presentation", "audience", "purpose", "tone", "theme", "layout", "chartType", "narrative", "socialPlatform", "language", "colorScheme", "fontScheme"];
+declare const schemaNames: readonly ["presentation", "audience", "purpose", "tone", "theme", "layout", "chartType", "narrative", "socialPlatform", "language", "colorScheme", "fontScheme", "finding"];
 type SchemaName = keyof typeof schemas;
 /** One entry per bundled schema: its name, spec-relative file path, and parsed document. */
 interface SchemaEntry {
@@ -267,4 +281,4 @@ interface SchemaEntry {
 }
 declare const schemaEntries: readonly SchemaEntry[];
 
-export { type JsonPrimitive as J, type SchemaEntry as S, type SchemaName as a, audience as b, chartType as c, colorScheme as d, layout as e, fontScheme as f, purpose as g, schemaNames as h, schemas as i, socialPlatform as j, tone as k, language as l, type JsonSchema as m, narrative as n, presentation as p, schemaEntries as s, theme as t };
+export { type JsonPrimitive as J, type SchemaName as S, type SchemaEntry as a, audience as b, chartType as c, colorScheme as d, layout as e, fontScheme as f, purpose as g, schemaNames as h, schemas as i, socialPlatform as j, tone as k, language as l, narrative as n, presentation as p, schemaEntries as s, theme as t };

package/dist/schemas.d.ts

@@ -1 +1 @@
-export { S as SchemaEntry, a as SchemaName, b as audience, c as chartType, d as colorScheme, f as fontScheme, l as language, e as layout, n as narrative, p as presentation, g as purpose, s as schemaEntries, h as schemaNames, i as schemas, j as socialPlatform, t as theme, k as tone } from './schemas-BbPonsTz.js';
+export { a as SchemaEntry, S as SchemaName, b as audience, c as chartType, d as colorScheme, f as fontScheme, l as language, e as layout, n as narrative, p as presentation, g as purpose, s as schemaEntries, h as schemaNames, i as schemas, j as socialPlatform, t as theme, k as tone } from './schemas-DDpqAgyS.js';

package/dist/schemas.js

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

package/dist/spec/README.md

@@ -10,6 +10,7 @@ New to the format? Read [`docs/how-opf-works.md`](../docs/how-opf-works.md) firs
 |---|---|
 | [`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/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)). |
 | [`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`). |
@@ -36,12 +37,12 @@ Without that sibling checkout, treat `spec/previews/layouts/*.html` and `index.j
 Validate a document and load catalog records without touching the files directly:
 
 ```ts
-import { validatePresentation, narratives } from "@openpresentation/opf";
+import { validate, narratives } from "@openpresentation/opf";
 
-const result = validatePresentation(deck);
-// result.valid    — schema correctness
-// result.errors   — structural problems
-// result.warnings — advisory issues such as unknown catalog ids
+const report = validate(deck);
+// 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 }
 ```
 
 Import the raw files when an engine, resolver, or non-JavaScript toolchain needs them:
@@ -53,6 +54,10 @@ import qbr from "@openpresentation/opf/spec/catalogs/narratives/qbr.json" with {
 
 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.
 
+## YAML
+
+JSON is the canonical form of an OPF document. A `.opf.yaml` file is an authoring serialization of the same data: JSON-compatible YAML 1.2 (one document, no tags or duplicate keys, finite numbers) whose parsed data is the document, and the schema validates that parsed data exactly as it validates JSON; YAML adds no field. A first line `# yaml-language-server: $schema=https://openpresentation.org/schema/opf/v1` gives editors validation and completion. See [`docs/yaml.md`](../docs/yaml.md).
+
 ## Stability
 
 The presentation schema `$id` is pinned to `/v1` and the package is pre-stable (0.x): expect breaking changes between minor versions until 1.0, tracked in [`CHANGELOG.md`](../CHANGELOG.md) with migration notes under [`docs/migrations/`](../docs/migrations).

package/dist/spec/catalogs/audiences/index.json

@@ -2,17 +2,9 @@
   "$schema": "https://openpresentation.org/schema/opf-catalog-index/v1",
   "kind": "audiences",
   "version": "1",
-  "description": "Catalog of presentation audiences available in the openpresentation.org catalog. Each entry is a lightweight summary; full audience records (seniority, technical fluency, decision power, attention budget, recommended narratives and tones) live in the per-id JSON files alongside this index. Audiences are referenced from OPF documents via audience. The singular ids from executive onward match the audience pages on pptx.gallery and carry its recommendations. The older plural ids (executives, investors, customers, sales-team, marketing-team, regulators) are deprecated aliases: they stay resolvable for existing documents, point at their singular replacement through replacedBy, and are excluded from default listings.",
-  "contentSha256": "bfb44226b533a2da04c92077eb39c689dde43181e0b9979fb15c247dfaba1f98",
+  "description": "Catalog of presentation audiences available in the openpresentation.org catalog. Each entry is a lightweight summary; full audience records (seniority, technical fluency, decision power, attention budget, recommended narratives and tones) live in the per-id JSON files alongside this index. Audiences are referenced from OPF documents via audience. The singular ids from executive onward match the audience pages on pptx.gallery and carry its recommendations.",
+  "contentSha256": "7d09863ea2357493b038341aabeea9aa7648b7062205249a0d6726aa5e362314",
   "records": [
-    {
-      "id": "executives",
-      "name": "Executives",
-      "summary": "Senior leaders who need the recommendation up front, the evidence behind it, and the ask.",
-      "file": "executives.json",
-      "deprecated": true,
-      "replacedBy": "executive"
-    },
     {
       "id": "board",
       "name": "Board of Directors",
@@ -25,38 +17,6 @@
       "summary": "Practitioners building the system; they want depth, mechanism, and tradeoffs.",
       "file": "engineering-team.json"
     },
-    {
-      "id": "investors",
-      "name": "Investors",
-      "summary": "Capital allocators evaluating fit, traction, and risk-adjusted return.",
-      "file": "investors.json",
-      "deprecated": true,
-      "replacedBy": "investor"
-    },
-    {
-      "id": "customers",
-      "name": "Customers",
-      "summary": "Buyers and users — outcome-focused, allergic to jargon, sensitive to time.",
-      "file": "customers.json",
-      "deprecated": true,
-      "replacedBy": "customer"
-    },
-    {
-      "id": "sales-team",
-      "name": "Sales Team",
-      "summary": "Quota-carrying reps who want talk tracks, objection handling, and crisp proof.",
-      "file": "sales-team.json",
-      "deprecated": true,
-      "replacedBy": "sales"
-    },
-    {
-      "id": "marketing-team",
-      "name": "Marketing Team",
-      "summary": "Brand and demand-gen practitioners aligning on positioning, messaging, and campaigns.",
-      "file": "marketing-team.json",
-      "deprecated": true,
-      "replacedBy": "marketing"
-    },
     {
       "id": "all-hands",
       "name": "All Hands",
@@ -69,14 +29,6 @@
       "summary": "Potential hires evaluating company, role, and people.",
       "file": "candidates.json"
     },
-    {
-      "id": "regulators",
-      "name": "Regulators",
-      "summary": "Government, agency, and policy reviewers evaluating compliance, risk, and impact.",
-      "file": "regulators.json",
-      "deprecated": true,
-      "replacedBy": "regulatory"
-    },
     {
       "id": "executive",
       "name": "Executive",

package/dist/spec/catalogs/chart-types/100pct-stacked-area.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://openpresentation.org/schema/opf-chart-type/v1",
+  "id": "100pct-stacked-area",
+  "name": "100% Stacked Area",
+  "mappings": {
+    "openxml": {
+      "element": "areaChart",
+      "grouping": "percentStacked",
+      "composition": "single"
+    },
+    "renderers": {
+      "aspose-slides": {
+        "chartType": "PercentsStackedArea"
+      }
+    }
+  },
+  "group": "Area",
+  "groupSort": 5,
+  "series": 2,
+  "complexity": "simple"
+}

package/dist/spec/catalogs/chart-types/100pct-stacked-bar.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://openpresentation.org/schema/opf-chart-type/v1",
+  "id": "100pct-stacked-bar",
+  "name": "100% Stacked Bar",
+  "mappings": {
+    "openxml": {
+      "element": "barChart",
+      "barDir": "bar",
+      "grouping": "percentStacked",
+      "composition": "single"
+    },
+    "renderers": {
+      "aspose-slides": {
+        "chartType": "PercentsStackedBar"
+      }
+    }
+  },
+  "group": "Bar",
+  "groupSort": 4,
+  "series": 2,
+  "complexity": "simple"
+}

package/dist/spec/catalogs/chart-types/100pct-stacked-column.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://openpresentation.org/schema/opf-chart-type/v1",
+  "id": "100pct-stacked-column",
+  "name": "100% Stacked Column",
+  "mappings": {
+    "openxml": {
+      "element": "barChart",
+      "barDir": "col",
+      "grouping": "percentStacked",
+      "composition": "single"
+    },
+    "renderers": {
+      "aspose-slides": {
+        "chartType": "PercentsStackedColumn"
+      }
+    }
+  },
+  "group": "Column",
+  "groupSort": 1,
+  "series": 2,
+  "complexity": "simple"
+}

package/dist/spec/catalogs/chart-types/area.json

@@ -1,8 +1,7 @@
 {
   "$schema": "https://openpresentation.org/schema/opf-chart-type/v1",
   "id": "area",
-  "name": "AREA",
-  "label": "Area",
+  "name": "Area",
   "mappings": {
     "openxml": {
       "element": "areaChart",
@@ -14,65 +13,8 @@
       }
     }
   },
-  "categories": 12,
-  "columns": [
-    "Series 1",
-    "Value"
-  ],
   "group": "Area",
   "groupSort": 5,
   "series": 1,
-  "seriesGroups": 1,
-  "slideNumber": 28,
-  "useSecondaryCategories": false,
-  "workbookRange": "Sheet1!$A$1:$M$2",
-  "complexity": "simple",
-  "dataColumns": [
-    {
-      "name": "Series 1",
-      "role": "categoryLabel",
-      "type": "string",
-      "position": "row0_col0"
-    },
-    {
-      "name": "Value",
-      "role": "series",
-      "type": "number",
-      "position": "row1_col0"
-    }
-  ],
-  "sampleData": {
-    "headers": [
-      "Series 1",
-      "Q1 2024",
-      "Q2 2024",
-      "Q3 2024",
-      "Q4 2024",
-      "Q1 2025",
-      "Q2 2025",
-      "Q3 2025",
-      "Q4 2025",
-      "Q1 2026",
-      "Q2 2026",
-      "Q3 2026",
-      "Q4 2026"
-    ],
-    "rows": [
-      [
-        "Value",
-        90676,
-        84593,
-        49446,
-        63225,
-        81819,
-        10053,
-        49829,
-        47606,
-        37549,
-        66346,
-        86019,
-        89516
-      ]
-    ]
-  }
+  "complexity": "simple"
 }

package/dist/spec/catalogs/chart-types/bar.json

@@ -1,8 +1,7 @@
 {
   "$schema": "https://openpresentation.org/schema/opf-chart-type/v1",
   "id": "bar",
-  "name": "BAR",
-  "label": "Bar",
+  "name": "Bar",
   "mappings": {
     "openxml": {
       "element": "barChart",
@@ -16,53 +15,8 @@
       }
     }
   },
-  "categories": 6,
-  "columns": [
-    "Series 1",
-    "Value"
-  ],
   "group": "Bar",
   "groupSort": 4,
   "series": 1,
-  "seriesGroups": 1,
-  "slideNumber": 21,
-  "useSecondaryCategories": false,
-  "workbookRange": "Sheet1!$A$1:$G$2",
-  "complexity": "simple",
-  "dataColumns": [
-    {
-      "name": "Series 1",
-      "role": "categoryLabel",
-      "type": "string",
-      "position": "row0_col0"
-    },
-    {
-      "name": "Value",
-      "role": "series",
-      "type": "number",
-      "position": "row1_col0"
-    }
-  ],
-  "sampleData": {
-    "headers": [
-      "Series 1",
-      "Q1 2024",
-      "Q2 2024",
-      "Q3 2024",
-      "Q4 2024",
-      "Q1 2025",
-      "Q2 2025"
-    ],
-    "rows": [
-      [
-        "Value",
-        30257,
-        41029,
-        31299,
-        33206,
-        64040,
-        13248
-      ]
-    ]
-  }
+  "complexity": "simple"
 }