@openpresentation/opf 0.26.10 → 0.28.0

package/dist/{presentation-Bwo8Ko6D.d.ts → presentation-8jLSTFqL.d.ts}

@@ -500,7 +500,7 @@ type ContentPayload = {
         mediaType?: string;
     });
     /**
-     * Image payloads only. How the picture fills its frame: 'cover' fills it and crops what overflows around focus; 'contain' shows the whole picture centered; 'stretch' scales it to the frame exactly. Default: the effective design.imageFit, else 'cover'.
+     * Image payloads only. How the picture fills its frame: 'cover' fills it and crops what overflows around focus; 'contain' shows the whole picture, in a frame of its own proportions placed at the region's anchor (top by default); 'stretch' scales it to the frame exactly. Default: the effective design.imageFit, else 'cover' in a layout and 'contain' on a slide with no layout.
      */
     fit?: ("cover" | "contain" | "stretch");
     focus?: ImageFocus1;
@@ -1202,7 +1202,7 @@ interface Design {
      */
     titleAlignment?: ("left" | "center" | "right");
     /**
-     * Default horizontal alignment for body/content regions in resolved layouts. Effective value: the slide's design, then the deck's design, then the theme's design.contentAlignment, then the layout record's design.contentAlignment, then the engine default. The tag follows titleAlignment (and a cover's subtitle with it) unless the slide's own design sets contentAlignment.
+     * Default horizontal alignment for body/content regions in resolved layouts. Effective value: the slide's design, then the deck's design, then the theme's design.contentAlignment, then the layout record's design.contentAlignment, then the engine default. The tag follows titleAlignment (and so does a subtitle in the title area, as on a cover) unless the slide's own design sets contentAlignment.
      */
     contentAlignment?: ("left" | "center" | "right");
     /**
@@ -1218,13 +1218,13 @@ interface Design {
      */
     chartPrimary?: ("none" | "top" | "bottom" | "left" | "right");
     /**
-     * Default fit of image blocks (and Slide.image) that set no fit of their own: 'cover' fills the frame and crops what overflows around the block's focus, 'contain' shows the whole picture centered in the frame, 'stretch' scales it to the frame exactly. Effective value: the slide's design, then the deck's design, then the theme's design.imageFit, then the layout record's design.imageFit, then 'cover'. Backgrounds set their own fit.
+     * Default fit of image blocks (and Slide.image) that set no fit of their own: 'cover' fills the frame and crops what overflows around the block's focus, 'contain' shows the whole picture in a frame of its own proportions, centered across and placed down the cell by the region's anchor (top by default), 'stretch' scales it to the frame exactly. Effective value: the slide's design, then the deck's design, then the theme's design.imageFit, then the layout record's design.imageFit, then 'cover'; a slide composed with no layout shows its pictures whole ('contain') instead. Backgrounds set their own fit.
      */
     imageFit?: ("cover" | "contain" | "stretch");
     /**
-     * Marker style for items and bullets lists. Effective value: the slide's design, then the deck's design, then the theme's design.listBullet, then the layout record's design.listBullet, then 'character'. 'character' (the default) draws the glyph marker. 'image' draws the primary organization's icon logo (or the organization and shape design.logo names; the onDark value on dark backgrounds) as a picture bullet: a square with side 0.65 times the marker's font size whose bottom sits on the marker baseline, so list geometry does not change. Without a logo the glyph is drawn and the engine reports unresolved-content at this field.
+     * Marker style for items and bullets lists. Effective value: the slide's design, then the deck's design, then the theme's design.listBullet, then the layout record's design.listBullet, then 'character'. 'character' (the default) draws the glyph marker. 'image' draws the primary organization's icon logo (or the organization and shape design.logo names; the onDark value on dark backgrounds) as a picture bullet: a square with side 0.65 times the marker's font size whose bottom sits on the marker baseline, so list geometry does not change. Without a logo the glyph is drawn and the engine reports unresolved-content at this field. 'none' draws no marker and no hanging indent, so each entry's text (and its description) starts at the left edge of the list: use it for label-and-description lists such as pillars, team members and questions with answers. Nested levels keep their indent. A list that sets numbering still draws its numbers.
      */
-    listBullet?: ("character" | "image");
+    listBullet?: ("character" | "image" | "none");
     /**
      * Draw the slide's template layout mirrored (OPF 0.19): each row's cells and the column sizes reversed, so a 'beside' layout puts its picture, chart or table at the end. Logical: a right-to-left deck mirrors on top. Binding and reading order do not change. Effective value: the slide's design, then the deck's design, then the layout record's design.mirror, then false. Slides without a template layout ignore it.
      */
@@ -2393,7 +2393,7 @@ interface Chart {
     highlight?: ChartHighlight;
 }
 /**
- * Inline tabular data driving a chart. The first column usually supplies category/x-axis labels; subsequent columns are plotted measures unless 'chart.mapping' or a chart type maps them differently. Value cells are numbers; a string is read only in strict decimal syntax ('12', '-3.5', '1e6'), and anything else ('12%', '$5', '(5)', '1,234') is a gap and a 'chart-value-not-numeric' warning.
+ * Inline tabular data driving a chart, written as `{ "columns": ["Quarter", "Decks"], "rows": [["Q1", 3], ["Q2", 8]] }`: one column of labels plus one column per series, not separate `categories` and `series` lists. The first column usually supplies category/x-axis labels; subsequent columns are plotted measures unless 'chart.mapping' or a chart type maps them differently. Value cells are numbers; a string is read only in strict decimal syntax ('12', '-3.5', '1e6'), and anything else ('12%', '$5', '(5)', '1,234') is a gap and a 'chart-value-not-numeric' warning.
  *
  * This interface was referenced by `Presentation`'s JSON-Schema
  * via the `definition` "ChartData".
@@ -2634,7 +2634,7 @@ interface TableCellStyle {
     verticalAlign?: ("top" | "middle" | "bottom");
     padding?: TableCellPadding;
     /**
-     * Independent cell edges. Omitted edges retain the table theme border; width 0 removes an edge.
+     * Independent cell edges. An omitted edge keeps the table's default rule: a line under every row (and over the first row), none between columns. Width 0 removes an edge.
      */
     borders?: {
         top?: TableCellBorder;
@@ -3049,7 +3049,7 @@ interface Design1 {
      */
     titleAlignment?: ("left" | "center" | "right");
     /**
-     * Default horizontal alignment for body/content regions in resolved layouts. Effective value: the slide's design, then the deck's design, then the theme's design.contentAlignment, then the layout record's design.contentAlignment, then the engine default. The tag follows titleAlignment (and a cover's subtitle with it) unless the slide's own design sets contentAlignment.
+     * Default horizontal alignment for body/content regions in resolved layouts. Effective value: the slide's design, then the deck's design, then the theme's design.contentAlignment, then the layout record's design.contentAlignment, then the engine default. The tag follows titleAlignment (and so does a subtitle in the title area, as on a cover) unless the slide's own design sets contentAlignment.
      */
     contentAlignment?: ("left" | "center" | "right");
     /**
@@ -3065,13 +3065,13 @@ interface Design1 {
      */
     chartPrimary?: ("none" | "top" | "bottom" | "left" | "right");
     /**
-     * Default fit of image blocks (and Slide.image) that set no fit of their own: 'cover' fills the frame and crops what overflows around the block's focus, 'contain' shows the whole picture centered in the frame, 'stretch' scales it to the frame exactly. Effective value: the slide's design, then the deck's design, then the theme's design.imageFit, then the layout record's design.imageFit, then 'cover'. Backgrounds set their own fit.
+     * Default fit of image blocks (and Slide.image) that set no fit of their own: 'cover' fills the frame and crops what overflows around the block's focus, 'contain' shows the whole picture in a frame of its own proportions, centered across and placed down the cell by the region's anchor (top by default), 'stretch' scales it to the frame exactly. Effective value: the slide's design, then the deck's design, then the theme's design.imageFit, then the layout record's design.imageFit, then 'cover'; a slide composed with no layout shows its pictures whole ('contain') instead. Backgrounds set their own fit.
      */
     imageFit?: ("cover" | "contain" | "stretch");
     /**
-     * Marker style for items and bullets lists. Effective value: the slide's design, then the deck's design, then the theme's design.listBullet, then the layout record's design.listBullet, then 'character'. 'character' (the default) draws the glyph marker. 'image' draws the primary organization's icon logo (or the organization and shape design.logo names; the onDark value on dark backgrounds) as a picture bullet: a square with side 0.65 times the marker's font size whose bottom sits on the marker baseline, so list geometry does not change. Without a logo the glyph is drawn and the engine reports unresolved-content at this field.
+     * Marker style for items and bullets lists. Effective value: the slide's design, then the deck's design, then the theme's design.listBullet, then the layout record's design.listBullet, then 'character'. 'character' (the default) draws the glyph marker. 'image' draws the primary organization's icon logo (or the organization and shape design.logo names; the onDark value on dark backgrounds) as a picture bullet: a square with side 0.65 times the marker's font size whose bottom sits on the marker baseline, so list geometry does not change. Without a logo the glyph is drawn and the engine reports unresolved-content at this field. 'none' draws no marker and no hanging indent, so each entry's text (and its description) starts at the left edge of the list: use it for label-and-description lists such as pillars, team members and questions with answers. Nested levels keep their indent. A list that sets numbering still draws its numbers.
      */
-    listBullet?: ("character" | "image");
+    listBullet?: ("character" | "image" | "none");
     /**
      * Draw the slide's template layout mirrored (OPF 0.19): each row's cells and the column sizes reversed, so a 'beside' layout puts its picture, chart or table at the end. Logical: a right-to-left deck mirrors on top. Binding and reading order do not change. Effective value: the slide's design, then the deck's design, then the layout record's design.mirror, then false. Slides without a template layout ignore it.
      */

package/dist/repo-readme.js

@@ -1,5 +1,7 @@
+import './chunk-GM7WFPGG.js';
+
 // 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[![CI](https://github.com/OpenPresentation/opf/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/OpenPresentation/opf/actions/workflows/ci.yml)\n[![nightly](https://github.com/OpenPresentation/opf/actions/workflows/nightly.yml/badge.svg?branch=main)](https://github.com/OpenPresentation/opf/actions/workflows/nightly.yml)\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, renderer, PPTX, editor, CLI and Gallery, all at the shared version 0.26.1. The default catalog is supplied by `@openpresentation/gallery@0.26.1`; see the [compatibility matrix](docs/compatibility-matrix.md) for feature and native limits.\n2. **Author, validate, paginate, preview and export.** New to OPF? Run the [first deck](docs/first-deck/README.md) end to end first. 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.** PPTX export writes one text box per wrapped line, so text edited in PowerPoint or Keynote does not reflow (see [rich text](docs/rich-text.md)) unless you opt in to `--body-text native` (opf-pptx and CLI 0.22.0 or later), and fonts are named, not embedded. 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`](./packages/gallery) (a dependency, released with core at the same version) 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 this repository as separate MIT packages 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 with the other packages; 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. All six live in this repository (`packages/`) and are released together at one version. See [ecosystem development](docs/ecosystem-development.md) for local builds and verification, and [dynamic composition](docs/dynamic-composition.md) for portable layout rules.\n\n| Package | Role | Boundary |\n|---|---|---|\n| [`packages/javascript`](./packages/javascript) (`@openpresentation/opf`) | Core: format, schemas, validation, composition | The format and its API; reads and writes files in Node and draws through the optional engines |\n| [`packages/gallery`](./packages/gallery) (`@openpresentation/gallery`) | The pptx.gallery catalog | Catalog records only, no runtime dependency; records are authored by pull request here, and a changed drawing or a removed record needs a minor release |\n| [`packages/cli`](./packages/cli) (`@openpresentation/cli`) | `opf` command | Runs core\'s Node engine: reads and writes files and calls the engines below as optional peers |\n| [`packages/render`](./packages/render) (`@openpresentation/opf-render`) | OPF to SVG/PNG/PDF | Local and embeddable rendering library |\n| [`packages/editor`](./packages/editor) (`@openpresentation/opf-editor`) | WYSIWYG bindings/components | Headless editor primitives plus optional UI components |\n| [`packages/pptx`](./packages/pptx) (`@openpresentation/opf-pptx`) | OPF to PPTX and PPTX to OPF | Pure local import/export library for browser and server use where supported |\n\nThese packages 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 packages, clone this repo and build the workspace (all six packages are in `packages/`; see [CONTRIBUTING](./CONTRIBUTING.md)):\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/slide-design-principles.md`](./docs/slide-design-principles.md) | Timeless principles for slide layout, typography, spacing, visual balance, and reviewing layout defaults. |\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 the one-click release: gate, tag, trusted npm publishing of all six packages, verification, GitHub release notes, and the site bumps. |\n| [`spec/schemas/*.schema.json`](./spec/schemas) | Companion schemas for catalog records and sub-objects. |\n| [`packages/gallery`](./packages/gallery) (`@openpresentation/gallery`) | The default catalog and layout previews, released with the other packages. |\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 = '<p align="center">\n  <picture>\n    <source media="(prefers-color-scheme: dark)" srcset="docs/brand/opf-logo-dark.svg">\n    <img src="docs/brand/opf-logo.svg" alt="Open Presentation Format" width="64" height="64">\n  </picture>\n</p>\n\n# 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[![CI](https://github.com/OpenPresentation/opf/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/OpenPresentation/opf/actions/workflows/ci.yml)\n[![nightly](https://github.com/OpenPresentation/opf/actions/workflows/nightly.yml/badge.svg?branch=main)](https://github.com/OpenPresentation/opf/actions/workflows/nightly.yml)\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, renderer, PPTX, editor, CLI and Gallery, all at the shared version 0.26.1. The default catalog is supplied by `@openpresentation/gallery@0.26.1`; see the [compatibility matrix](docs/compatibility-matrix.md) for feature and native limits.\n2. **Author, validate, paginate, preview and export.** New to OPF? Run the [first deck](docs/first-deck/README.md) end to end first. 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.** PPTX export writes one text box per wrapped line, so text edited in PowerPoint or Keynote does not reflow (see [rich text](docs/rich-text.md)) unless you opt in to `--body-text native` (opf-pptx and CLI 0.22.0 or later), and fonts are named, not embedded. 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`](./packages/gallery) (a dependency, released with core at the same version) 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 this repository as separate MIT packages 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 seven 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 with the other packages; core depends on it and registers it in Node. **The CLI** (`@openpresentation/cli`) is the `opf` command. **The MCP server** (`@openpresentation/mcp`, `npx -y @openpresentation/mcp`) lets an MCP-native agent learn OPF (docs, schemas, catalog, examples and skills as resources) and validate and convert decks. **Render** (`opf-render`), **PPTX** (`opf-pptx`) and **the editor** (`opf-editor`) are the engines: drawing, PowerPoint and editing, installed as needed. All seven live in this repository (`packages/`) and are released together at one version. See [ecosystem development](docs/ecosystem-development.md) for local builds and verification, and [dynamic composition](docs/dynamic-composition.md) for portable layout rules.\n\n| Package | Role | Boundary |\n|---|---|---|\n| [`packages/javascript`](./packages/javascript) (`@openpresentation/opf`) | Core: format, schemas, validation, composition | The format and its API; reads and writes files in Node and draws through the optional engines |\n| [`packages/gallery`](./packages/gallery) (`@openpresentation/gallery`) | The pptx.gallery catalog | Catalog records only, no runtime dependency; records are authored by pull request here, and a changed drawing or a removed record needs a minor release |\n| [`packages/cli`](./packages/cli) (`@openpresentation/cli`) | `opf` command | Runs core\'s Node engine: reads and writes files and calls the engines below as optional peers |\n| [`packages/render`](./packages/render) (`@openpresentation/opf-render`) | OPF to SVG/PNG/PDF | Local and embeddable rendering library |\n| [`packages/editor`](./packages/editor) (`@openpresentation/opf-editor`) | WYSIWYG bindings/components | Headless editor primitives plus optional UI components |\n| [`packages/pptx`](./packages/pptx) (`@openpresentation/opf-pptx`) | OPF to PPTX and PPTX to OPF | Pure local import/export library for browser and server use where supported |\n\nThese packages 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 packages, clone this repo and build the workspace (all seven packages are in `packages/`; see [CONTRIBUTING](./CONTRIBUTING.md)):\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/slide-design-principles.md`](./docs/slide-design-principles.md) | Timeless principles for slide layout, typography, spacing, visual balance, and reviewing layout defaults. |\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 the one-click release: gate, tag, trusted npm publishing of all seven packages, verification, GitHub release notes, and the site bumps. |\n| [`spec/schemas/*.schema.json`](./spec/schemas) | Companion schemas for catalog records and sub-objects. |\n| [`packages/gallery`](./packages/gallery) (`@openpresentation/gallery`) | The default catalog and layout previews, released with the other packages. |\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/schema-engine-ajv.js

@@ -0,0 +1,37 @@
+import { installedSchemaEngine } from './chunk-43JWUIGF.js';
+import { qualifyBranch } from './chunk-JBARNYFR.js';
+import { schemas } from './chunk-5Q4IYLMW.js';
+import './chunk-GM7WFPGG.js';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+
+var ajv;
+var branches = /* @__PURE__ */ new WeakMap();
+function getAjv() {
+  if (ajv) return ajv;
+  const instance = new Ajv2020({ allErrors: true, verbose: true, strict: false, allowUnionTypes: true });
+  addFormats(instance);
+  for (const schema of Object.values(schemas)) instance.addSchema(schema);
+  ajv = instance;
+  return instance;
+}
+var engine = {
+  root(name) {
+    const schema = schemas[name];
+    return getAjv().getSchema(schema.$id) ?? getAjv().compile(schema);
+  },
+  definition(name, definition) {
+    return getAjv().getSchema(`${schemas[name].$id}#/$defs/${definition}`);
+  },
+  branch(branch, rootId) {
+    let validate = branches.get(branch);
+    if (!validate) {
+      validate = getAjv().compile(qualifyBranch(branch, rootId));
+      branches.set(branch, validate);
+    }
+    return validate;
+  }
+};
+var schemaEngine = () => installedSchemaEngine() ?? engine;
+
+export { schemaEngine };

package/dist/schema-engine-precompiled.js

@@ -0,0 +1,3 @@
+export { precompiledMarker, schemaEngine } from './chunk-ZROVYWGU.js';
+import './chunk-5Q4IYLMW.js';
+import './chunk-GM7WFPGG.js';

package/dist/schema.d.ts

@@ -1,6 +1,6 @@
-import { C as CatalogRecordKind } from './catalog-schemas-DoxA2BgY.js';
+import { C as CatalogRecordKind } from './catalog-schemas-CC1d_h8s.js';
 import { SchemaName } from './schemas.js';
-import './catalog-refs-BSfGELpt.js';
+import './catalog-refs-kAefsZWT.js';
 import './json-BFSdESOE.js';
 
 /**
@@ -162,4 +162,5 @@ declare function describeField(path: OpfPath, document?: unknown): FieldInfo;
  */
 declare function catalogKindAt(path: OpfPath, document?: unknown): CatalogRecordKind | undefined;
 
-export { COMMON_KEYS, CatalogRecordKind, type EnumValue, type FieldChild, type FieldInfo, type JsonSchema, type OpfPath, type SchemaField, type SchemaNodeKey, type SchemaRoot, UNRANKED_PRIORITY, type VariantInfo, activeSchema, catalogKindAt, createSchemaValue, describeField, isPromotedRegionKey, listSchemaFields, resolveSchema, schemaAtPath, schemaCatalogKinds, schemaLabel, schemaType, schemaVariants, splitOpfPath };
+export { COMMON_KEYS, CatalogRecordKind, UNRANKED_PRIORITY, activeSchema, catalogKindAt, createSchemaValue, describeField, isPromotedRegionKey, listSchemaFields, resolveSchema, schemaAtPath, schemaCatalogKinds, schemaLabel, schemaType, schemaVariants, splitOpfPath };
+export type { EnumValue, FieldChild, FieldInfo, JsonSchema, OpfPath, SchemaField, SchemaNodeKey, SchemaRoot, VariantInfo };

package/dist/schema.js

@@ -1,3 +1,5 @@
-export { COMMON_KEYS, UNRANKED_PRIORITY, activeSchema, catalogKindAt, createSchemaValue, describeField, isPromotedRegionKey, listSchemaFields, resolveSchema, schemaAtPath, schemaCatalogKinds, schemaLabel, schemaType, schemaVariants, splitOpfPath } from './chunk-IVPA6NG6.js';
-import './chunk-XRMV2GMB.js';
-import './chunk-F4HFDP6I.js';
+export { COMMON_KEYS, UNRANKED_PRIORITY, activeSchema, catalogKindAt, createSchemaValue, describeField, isPromotedRegionKey, listSchemaFields, resolveSchema, schemaAtPath, schemaCatalogKinds, schemaLabel, schemaType, schemaVariants, splitOpfPath } from './chunk-WPKCWQ6W.js';
+import './chunk-JBARNYFR.js';
+import './chunk-5Q4IYLMW.js';
+import './chunk-2CUCYENF.js';
+import './chunk-GM7WFPGG.js';

package/dist/schemas.d.ts

@@ -293,4 +293,5 @@ interface SchemaEntry {
 }
 declare const schemaEntries: readonly SchemaEntry[];
 
-export { type SchemaEntry, type SchemaName, audience, chartType, colorScheme, fontScheme, language, layout, narrative, presentation, purpose, schemaEntries, schemaNames, schemas, socialPlatform, theme, tone };
+export { audience, chartType, colorScheme, fontScheme, language, layout, narrative, presentation, purpose, schemaEntries, schemaNames, schemas, socialPlatform, theme, tone };
+export type { SchemaEntry, SchemaName };

package/dist/schemas.js

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

package/dist/source.d.ts

@@ -1,6 +1,6 @@
-import { b as FindingLocation, a as Finding } from './finding-l9dlQ2NF.js';
-import { F as FindingTextContext, a as FindingText } from './explain-JSuESV-Y.js';
-export { R as RuleExplanation, d as distance, e as explain, n as nearest, s as pointerSegments } from './explain-JSuESV-Y.js';
+import { FindingLocation, Finding } from './index.js';
+import { F as FindingTextContext, a as FindingText } from './explain-iZeNOUc6.js';
+export { R as RuleExplanation, d as distance, e as explain, n as nearest, s as pointerSegments } from './explain-iZeNOUc6.js';
 
 /** Keys of `<!-- slide: ... -->`. */
 declare const SLIDE_OPTION_KEYS: readonly ["id", "type", "layout", "section", "tag", "hidden", "beat"];
@@ -273,4 +273,5 @@ interface AnalyzeYamlOptions {
  */
 declare function analyzeYamlSyntax(text: string, options?: AnalyzeYamlOptions): YamlSyntaxProblem[];
 
-export { type AnalyzeOptions, type AnalyzeYamlOptions, BLOCK_AS_VALUES, BLOCK_OPTION_KEYS, FENCE_ATTRIBUTES, FENCE_KINDS, FindingText, FindingTextContext, LINE_KEYWORDS, type LocateOptions, type LocatePart, METRIC_KEYS, type MarkdownCommentScan, type MarkdownFenceScan, type MarkdownFrontMatter, type MarkdownNotesScan, type MarkdownScan, type MarkdownSlideScan, PATTERN_PHRASES, type PathAtResult, type PatternPhrase, SLIDE_OPTION_KEYS, SPAN_FLAGS, SPAN_VALUES, type ScanMarkdownOptions, type ScanRange, type SourceFormat, type SyntaxFix, type SyntaxProblem, type SyntaxProblemCode, type TextEdit, type TextRange, type YamlProblemCode, type YamlSyntaxProblem, analyzeJsonSyntax, analyzeYamlSyntax, applyTextEdits, describeFinding, locate, pathAt, scanMarkdown, starterValue };
+export { BLOCK_AS_VALUES, BLOCK_OPTION_KEYS, FENCE_ATTRIBUTES, FENCE_KINDS, FindingText, FindingTextContext, LINE_KEYWORDS, METRIC_KEYS, PATTERN_PHRASES, SLIDE_OPTION_KEYS, SPAN_FLAGS, SPAN_VALUES, analyzeJsonSyntax, analyzeYamlSyntax, applyTextEdits, describeFinding, locate, pathAt, scanMarkdown, starterValue };
+export type { AnalyzeOptions, AnalyzeYamlOptions, LocateOptions, LocatePart, MarkdownCommentScan, MarkdownFenceScan, MarkdownFrontMatter, MarkdownNotesScan, MarkdownScan, MarkdownSlideScan, PathAtResult, PatternPhrase, ScanMarkdownOptions, ScanRange, SourceFormat, SyntaxFix, SyntaxProblem, SyntaxProblemCode, TextEdit, TextRange, YamlProblemCode, YamlSyntaxProblem };

package/dist/source.js

@@ -1,13 +1,15 @@
-export { explain } from './chunk-G5WJMJV3.js';
-import { readMarkdown, frontMatter, splitSegments, isOutline, NOTES, fenceStart, fenceClose, COMMENT } from './chunk-H7XMO36O.js';
-import './chunk-PHP45MO7.js';
-import { splitLines } from './chunk-Y4TZCE7R.js';
-export { analyzeYamlSyntax } from './chunk-Y4TZCE7R.js';
-import './chunk-Y25DYRME.js';
-import { rememberByText, SLIDE_OPTION_KEYS, FENCE_KINDS, createLocator, parsePointer } from './chunk-IVPA6NG6.js';
-export { BLOCK_AS_VALUES, BLOCK_OPTION_KEYS, FENCE_ATTRIBUTES, FENCE_KINDS, LINE_KEYWORDS, METRIC_KEYS, PATTERN_PHRASES, SLIDE_OPTION_KEYS, SPAN_FLAGS, SPAN_VALUES, analyzeJsonSyntax, applyTextEdits, describeFinding, distance, nearest, segmentsOf as pointerSegments, starterValue } from './chunk-IVPA6NG6.js';
-import './chunk-XRMV2GMB.js';
-import './chunk-F4HFDP6I.js';
+export { explain } from './chunk-UOHWG4OS.js';
+import { readMarkdown, frontMatter, splitSegments, isOutline, NOTES, fenceStart, fenceClose, COMMENT } from './chunk-PCU4XGKV.js';
+import './chunk-P6PKYJTS.js';
+import { splitLines } from './chunk-SEZ4EPW6.js';
+export { analyzeYamlSyntax } from './chunk-SEZ4EPW6.js';
+import './chunk-TNUTRV6E.js';
+import { rememberByText, SLIDE_OPTION_KEYS, FENCE_KINDS, createLocator, parsePointer } from './chunk-WPKCWQ6W.js';
+export { BLOCK_AS_VALUES, BLOCK_OPTION_KEYS, FENCE_ATTRIBUTES, FENCE_KINDS, LINE_KEYWORDS, METRIC_KEYS, PATTERN_PHRASES, SLIDE_OPTION_KEYS, SPAN_FLAGS, SPAN_VALUES, analyzeJsonSyntax, applyTextEdits, describeFinding, distance, nearest, segmentsOf as pointerSegments, starterValue } from './chunk-WPKCWQ6W.js';
+import './chunk-JBARNYFR.js';
+import './chunk-5Q4IYLMW.js';
+import './chunk-2CUCYENF.js';
+import './chunk-GM7WFPGG.js';
 import { findNodeAtOffset, getNodePath, parseTree } from 'jsonc-parser';
 import { parseDocument, isMap, isSeq, isScalar, isAlias } from 'yaml';
 

package/dist/spec/README.md

@@ -17,7 +17,7 @@ New to the format? Read [`docs/how-opf-works.md`](../docs/how-opf-works.md) firs
 
 ## Layout templates and previews
 
-The gallery package's `catalog/layouts/` contains the 28 v2 intent templates that `Slide.layout` resolves against. They are ordered lists of regions with content rules, nested for two dimensions; examples include `cover`, `text`, `chart` and `two-column`.
+The gallery package's `catalog/layouts/` contains the 30 v2 intent templates that `Slide.layout` resolves against. They are ordered lists of regions with content rules, nested for two dimensions; examples include `cover`, `text`, `chart` and `two-column`.
 
 `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.
 

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

@@ -1,6 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-audience/v1",
+  "$comment": "The v1 in the $id is the pre-1.0 line, not a frozen contract: this schema may change in any 0.x minor release. The release that produced this copy is the version of the @openpresentation/opf package it came from (opf --version; opf schemas lists it next to each id). See docs/schema-versioning.md.",
   "title": "Audience",
   "description": "Schema for audience records. Each record names an audience archetype (e.g. 'executive', 'engineering-team', 'investor') and carries seniority, technical-fluency, decision-power, and attention-budget hints used by AI-driven generation. Documents reference an audience from 'audience', which also accepts free-form text.\n\nA document references a record as a bare id or 'name:id' and resolves it in its own catalogs groups first, then in the catalog the host registered for the group's source; engines never fetch a catalog. A published record file carries '$schema' and 'id'; the copy a document embeds under catalogs.<group>.<kind>.<id> carries neither (the key is the id) and no 'x-*' display metadata.",
   "type": "object",

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

@@ -1,6 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-catalog-index/v1",
+  "$comment": "The v1 in the $id is the pre-1.0 line, not a frozen contract: this schema may change in any 0.x minor release. The release that produced this copy is the version of the @openpresentation/opf package it came from (opf --version; opf schemas lists it next to each id). See docs/schema-versioning.md.",
   "title": "Catalog Index",
   "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",

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

@@ -1,6 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-catalog-manifest/v1",
+  "$comment": "The v1 in the $id is the pre-1.0 line, not a frozen contract: this schema may change in any 0.x minor release. The release that produced this copy is the version of the @openpresentation/opf package it came from (opf --version; opf schemas lists it next to each id). See docs/schema-versioning.md.",
   "title": "Catalog Snapshot Manifest",
   "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",

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

@@ -1,6 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-chart-type/v1",
+  "$comment": "The v1 in the $id is the pre-1.0 line, not a frozen contract: this schema may change in any 0.x minor release. The release that produced this copy is the version of the @openpresentation/opf package it came from (opf --version; opf schemas lists it next to each id). See docs/schema-versioning.md.",
   "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/gallery ships them as catalogDisplay.chartTypes.",
   "type": "object",

package/dist/spec/schemas/color-scheme.schema.json

@@ -1,6 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-color-scheme/v1",
+  "$comment": "The v1 in the $id is the pre-1.0 line, not a frozen contract: this schema may change in any 0.x minor release. The release that produced this copy is the version of the @openpresentation/opf package it came from (opf --version; opf schemas lists it next to each id). See docs/schema-versioning.md.",
   "title": "Color Scheme",
   "description": "Schema for color-scheme records. Each scheme is a named palette with the twelve PowerPoint color slots (six accents, two darks, two lights, plus hyperlink and followed-hyperlink), suitable for being mapped directly into OOXML theme XML. Documents reference a scheme from design.colorScheme (or design.colorScheme.id) and from a theme's colorScheme; slot overrides on design.colorScheme take precedence over the resolved scheme.\n\nThe slot fields here mirror the inline-override fields on the in-document ColorScheme type (in opf.schema.json), so records and inline OPF overrides are interchangeable.\n\nA document references a record as a bare id or 'name:id' and resolves it in its own catalogs groups first, then in the catalog the host registered for the group's source; engines never fetch a catalog. A published record file carries '$schema' and 'id'; the copy a document embeds under catalogs.<group>.<kind>.<id> carries neither (the key is the id) and no 'x-*' display metadata.",
   "type": "object",

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

@@ -1,6 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-finding/v1",
+  "$comment": "The v1 in the $id is the pre-1.0 line, not a frozen contract: this schema may change in any 0.x minor release. The release that produced this copy is the version of the @openpresentation/opf package it came from (opf --version; opf schemas lists it next to each id). See docs/schema-versioning.md.",
   "title": "Validation results",
   "description": "Errors, warnings and suggested fixes.",
   "type": "object",

package/dist/spec/schemas/font-scheme.schema.json

@@ -1,6 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-font-scheme/v1",
+  "$comment": "The v1 in the $id is the pre-1.0 line, not a frozen contract: this schema may change in any 0.x minor release. The release that produced this copy is the version of the @openpresentation/opf package it came from (opf --version; opf schemas lists it next to each id). See docs/schema-versioning.md.",
   "title": "Font Scheme",
   "description": "Schema for font-scheme records. Each scheme pairs a major (heading) and minor (body) font family in the OOXML majorFont/minorFont sense, scoped to a target app (powerpoint or google-slides) and a language family (Latin, East Asian, or Complex Script). Documents reference a scheme from design.fontScheme (or design.fontScheme.id), from a theme's fontScheme and from a language's fontScheme / googleFontScheme. Role overrides on design.fontScheme (heading, body, accent, code), each a font family name, take precedence over the resolved scheme.\n\nA document references a record as a bare id or 'name:id' and resolves it in its own catalogs groups first, then in the catalog the host registered for the group's source; engines never fetch a catalog. A published record file carries '$schema' and 'id'; the copy a document embeds under catalogs.<group>.<kind>.<id> carries neither (the key is the id) and no 'x-*' display metadata.",
   "type": "object",

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

@@ -1,6 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-language/v1",
+  "$comment": "The v1 in the $id is the pre-1.0 line, not a frozen contract: this schema may change in any 0.x minor release. The release that produced this copy is the version of the @openpresentation/opf package it came from (opf --version; opf schemas lists it next to each id). See docs/schema-versioning.md.",
   "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/gallery ships them as catalogDisplay.languages.",
   "type": "object",

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

@@ -1,6 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-layout-preview-index/v1",
+  "$comment": "The v1 in the $id is the pre-1.0 line, not a frozen contract: this schema may change in any 0.x minor release. The release that produced this copy is the version of the @openpresentation/opf package it came from (opf --version; opf schemas lists it next to each id). See docs/schema-versioning.md.",
   "title": "Layout Preview Index",
   "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",

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

@@ -1,6 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-layout/v2",
+  "$comment": "The v2 in the $id marks the pre-1.0 line of this schema, not a frozen contract: it may change in any 0.x minor release. The release that produced this copy is the version of the @openpresentation/opf package it came from (opf --version; opf schemas lists it next to each id). See docs/schema-versioning.md.",
   "title": "Slide Layout",
   "description": "Schema for slide-layout records. A layout is one ordered list of regions, declared once, in reading order: 'direction' says whether the record's 'regions' sit side by side (row) or are stacked (column), and each region says which content kinds it takes and how several blocks share it. A split is an entry that nests a second list the other way, which is how a layout gets two dimensions. 'title' and 'subtitle' are reserved heading regions. Engines compile the list into a grid of tracks (the guillotine partition it describes). Slide content stays flat: engines bind a slide's blocks to the regions by reading order, role and kind (bindRegions in @openpresentation/opf), a block may pin itself to a region with 'region', and an empty region collapses into a neighbour. Built-in and custom layouts are records of this one schema; a custom layout is embedded under catalogs.custom.layouts or shipped in a catalog. Documents reference a layout from Slide.layout; a slide without a layout, with layout 'auto', or whose layout resolves nowhere composes automatically.\n\nA document references a record as a bare id or 'name:id' and resolves it in its own catalogs groups first, then in the catalog the host registered for the group's source; engines never fetch a catalog. A published record file carries '$schema' and 'id'; the copy a document embeds under catalogs.<group>.<kind>.<id> carries neither (the key is the id) and no 'x-*' display metadata.",
   "type": "object",
@@ -77,7 +78,7 @@
         "middle",
         "bottom"
       ],
-      "description": "Vertical position of the content of every body region when it is shorter than the region. A split's 'anchor' replaces it for the regions under that split, and a region's own 'anchor' replaces both. Only 'anchor' is inherited, and only by body regions: the heading regions 'title' and 'subtitle' never take it, and the other region rules stay per region. Default 'top'."
+      "description": "Vertical position of the content of every body region when it is shorter than the region. A split's 'anchor' replaces it for the regions under that split, and a region's own 'anchor' replaces both. Only 'anchor' is inherited, and only by body regions: the heading regions 'title' and 'subtitle' never take it, and the other region rules stay per region. One exception places the whole slide: when the record is a column and every entry of its 'regions' list is sized 'auto' (heading regions included), the record has no numeric row to hold the leftover height, so its 'anchor' places the whole stack, title and subtitle included, in the content box's leftover height: 'middle' centres it, 'bottom' sits it at the foot, 'top' (default) starts it at the top as before. A record with any numeric entry, a row record and an anchor on a split keep the rule above. Default 'top'."
     },
     "regions": {
       "type": "array",
@@ -220,7 +221,7 @@
           "const": "auto"
         }
       ],
-      "description": "The region's or split's share along its parent's direction: a number above 0 and up to 100 that siblings share in proportion (the gap is taken out first), default 1; or 'auto', the length the content needs at the starting text size (at most half the content box; a split sized auto is as tall as its tallest content, and every row of a column split sized auto is auto too; auto regions with no content take no space). 'auto' is allowed only on an entry of a column; in a row it is the validate finding opf/layout-template. The default for a heading region is 'auto' in a column and 1 in a row.",
+      "description": "The region's or split's share along its parent's direction: a number above 0 and up to 100 that siblings share in proportion (the gap is taken out first), default 1; or 'auto', the length the content needs at the starting text size (up to the space the heading rows and the content of the numeric rows leave; auto rows that do not all fit shrink together, each giving up the same fraction of what it can give up above its content's length at the minimum font size; a split sized auto is as tall as its tallest content, and every row of a column split sized auto is auto too; auto regions with no content take no space). 'auto' is allowed only on an entry of a column; in a row it is the validate finding opf/layout-template. When every entry of a column record is 'auto', the record's 'anchor' places the whole stack. The default for a heading region is 'auto' in a column and 1 in a row.",
       "examples": [
         1,
         2,
@@ -362,7 +363,7 @@
             "column",
             "auto"
           ],
-          "description": "How several blocks share the region: 'none' one block fills it; 'grid' by count (1 fills, 2 side by side, 3 in a row, 4 as 2 x 2, 5 as 3 + 2, 6 as 3 x 2, 7 to 12 in four columns; rows and columns swap in a portrait region; a short last row is centred); 'column' stacked with equal heights; 'auto' a grid when every block is short and a column when any block is long (more than 6 estimated lines in its grid cell at the starting size). design.contentDirection turns every flowing region into one row or one column. Default 'auto'."
+          "description": "How several blocks share the region: 'none' one block fills it; 'grid' by count (1 fills, 2 side by side, 3 in a row, 4 as 2 x 2, 5 as 3 + 2, 6 as 3 x 2, 7 to 12 in four columns; rows and columns swap in a portrait region; a short last row is centred); 'column' stacked at the heights the blocks need, one gap apart, and placed by the region's anchor (charts, pictures, tables, timelines and videos take what the measured blocks leave; blocks that do not fit share the region, each giving up the same fraction of what it can give up above its height at the minimum font size); 'auto' a grid when every block is short and a column when any block is long (more than 6 estimated lines in its grid cell at the starting size). design.contentDirection turns every flowing region into one row or one column. Default 'auto'."
         },
         "max": {
           "type": "integer",
@@ -392,7 +393,7 @@
             "middle",
             "bottom"
           ],
-          "description": "Vertical position of the region's content when it is shorter than the region. Replaces the 'anchor' of the record and of the splits around it. Default: the nearest of those that sets one, else 'top'."
+          "description": "Vertical position of the region's content when it is shorter than the region. Replaces the 'anchor' of the record and of the splits around it. Default: the nearest of those that sets one, else 'top'. A picture shown whole (fit 'contain') and a video, whose 16:9 frame is the largest that fits the cell, sit at the anchor inside the cell."
         },
         "empty": {
           "type": "string",
@@ -466,9 +467,10 @@
           "type": "string",
           "enum": [
             "character",
-            "image"
+            "image",
+            "none"
           ],
-          "description": "Marker style of lists: 'character' draws the glyph, 'image' draws the deck's icon logo as a picture bullet."
+          "description": "Marker style of lists: 'character' draws the glyph, 'image' draws the deck's icon logo as a picture bullet, 'none' draws no marker and no hanging indent (label-and-description lists)."
         },
         "mirror": {
           "type": "boolean",

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

@@ -1,6 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-narrative/v1",
+  "$comment": "The v1 in the $id is the pre-1.0 line, not a frozen contract: this schema may change in any 0.x minor release. The release that produced this copy is the version of the @openpresentation/opf package it came from (opf --version; opf schemas lists it next to each id). See docs/schema-versioning.md.",
   "title": "Narrative Template",
   "description": "Schema for narrative records. A narrative is a plan: a named story arc (e.g. 'problem-solution', 'scqa') as an ordered list of beats, each saying what its slide must do. A document points at one with the string 'narrative' and links its slides to beats with 'slides[].beat'; a narrative the document defines itself is a record in catalogs.custom.narratives. Core validate warns about a 'slides[].beat' id the resolved narrative does not define (opf/unknown-beat) and about a root 'duration' outside this record's 'duration' range (opf/duration-outside-narrative), and reports a beat no slide references (opf/unused-beat).\n\nA document references a record as a bare id or 'name:id' and resolves it in its own catalogs groups first, then in the catalog the host registered for the group's source; engines never fetch a catalog. A published record file carries '$schema' and 'id'; the copy a document embeds under catalogs.<group>.<kind>.<id> carries neither (the key is the id) and no 'x-*' display metadata.",
   "type": "object",

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

@@ -1,6 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf/v1",
+  "$comment": "The v1 in the $id is the pre-1.0 line, not a frozen contract: this schema may change in any 0.x minor release. The release that produced this copy is the version of the @openpresentation/opf package it came from (opf --version; opf schemas lists it next to each id). See docs/schema-versioning.md.",
   "title": "Presentation",
   "description": "Open-source JSON format for describing PowerPoint presentations. Agents describe narratives, content, audience, reusable assets, and design — the engine handles OOXML complexity.\n\nContent references (Slide.layout, design.theme, design.colorScheme / design.colorScheme.id, design.fontScheme / design.fontScheme.id, narrative, audience, purpose and tone, and the colorScheme / fontScheme a theme record names) point at catalog records. Each is a bare 'id' or a 'name:id' whose prefix names a group in 'catalogs'. A bare id resolves in catalogs.custom, then in the records embedded under catalogs.default, then in the catalog the host registered for catalogs.default.source (or the host's default catalog when 'default' is omitted); 'name:id' resolves in catalogs.<name>, then in the catalog the host registered for its source. A reference that resolves nowhere is the warning opf/unresolved-reference, and the slide uses automatic composition or the engine default. Engines never fetch a catalog: a saved document embeds every record it uses, and hosts register any other catalog by its source string. See docs/default-catalog.md.\n\nchart.type, the language tag and the keys of Organization.socials / Speaker.socials are engine vocabularies, validated directly with no catalog lookup. When a document names no theme, colour scheme or font scheme, every engine uses the same small engine defaults (spec/reference/engine-defaults.json). Asset references use 'asset:<id>' strings that point into the top-level assets registry, and content color fields (rich-text runs, styled table cells) accept hex values, color-scheme slot/role names, or 'var:<id>' references into the top-level variables map.",
   "type": "object",
@@ -748,7 +749,7 @@
         "contentAlignment": {
           "type": "string",
           "enum": ["left", "center", "right"],
-          "description": "Default horizontal alignment for body/content regions in resolved layouts. Effective value: the slide's design, then the deck's design, then the theme's design.contentAlignment, then the layout record's design.contentAlignment, then the engine default. The tag follows titleAlignment (and a cover's subtitle with it) unless the slide's own design sets contentAlignment."
+          "description": "Default horizontal alignment for body/content regions in resolved layouts. Effective value: the slide's design, then the deck's design, then the theme's design.contentAlignment, then the layout record's design.contentAlignment, then the engine default. The tag follows titleAlignment (and so does a subtitle in the title area, as on a cover) unless the slide's own design sets contentAlignment."
         },
         "contentBox": {
           "type": "boolean",
@@ -767,12 +768,12 @@
         "imageFit": {
           "type": "string",
           "enum": ["cover", "contain", "stretch"],
-          "description": "Default fit of image blocks (and Slide.image) that set no fit of their own: 'cover' fills the frame and crops what overflows around the block's focus, 'contain' shows the whole picture centered in the frame, 'stretch' scales it to the frame exactly. Effective value: the slide's design, then the deck's design, then the theme's design.imageFit, then the layout record's design.imageFit, then 'cover'. Backgrounds set their own fit."
+          "description": "Default fit of image blocks (and Slide.image) that set no fit of their own: 'cover' fills the frame and crops what overflows around the block's focus, 'contain' shows the whole picture in a frame of its own proportions, centered across and placed down the cell by the region's anchor (top by default), 'stretch' scales it to the frame exactly. Effective value: the slide's design, then the deck's design, then the theme's design.imageFit, then the layout record's design.imageFit, then 'cover'; a slide composed with no layout shows its pictures whole ('contain') instead. Backgrounds set their own fit."
         },
         "listBullet": {
           "type": "string",
-          "enum": ["character", "image"],
-          "description": "Marker style for items and bullets lists. Effective value: the slide's design, then the deck's design, then the theme's design.listBullet, then the layout record's design.listBullet, then 'character'. 'character' (the default) draws the glyph marker. 'image' draws the primary organization's icon logo (or the organization and shape design.logo names; the onDark value on dark backgrounds) as a picture bullet: a square with side 0.65 times the marker's font size whose bottom sits on the marker baseline, so list geometry does not change. Without a logo the glyph is drawn and the engine reports unresolved-content at this field."
+          "enum": ["character", "image", "none"],
+          "description": "Marker style for items and bullets lists. Effective value: the slide's design, then the deck's design, then the theme's design.listBullet, then the layout record's design.listBullet, then 'character'. 'character' (the default) draws the glyph marker. 'image' draws the primary organization's icon logo (or the organization and shape design.logo names; the onDark value on dark backgrounds) as a picture bullet: a square with side 0.65 times the marker's font size whose bottom sits on the marker baseline, so list geometry does not change. Without a logo the glyph is drawn and the engine reports unresolved-content at this field. 'none' draws no marker and no hanging indent, so each entry's text (and its description) starts at the left edge of the list: use it for label-and-description lists such as pillars, team members and questions with answers. Nested levels keep their indent. A list that sets numbering still draws its numbers."
         },
         "mirror": {
           "type": "boolean",
@@ -2316,7 +2317,7 @@
         "fit": {
           "type": "string",
           "enum": ["cover", "contain", "stretch"],
-          "description": "Image payloads only. How the picture fills its frame: 'cover' fills it and crops what overflows around focus; 'contain' shows the whole picture centered; 'stretch' scales it to the frame exactly. Default: the effective design.imageFit, else 'cover'."
+          "description": "Image payloads only. How the picture fills its frame: 'cover' fills it and crops what overflows around focus; 'contain' shows the whole picture, in a frame of its own proportions placed at the region's anchor (top by default); 'stretch' scales it to the frame exactly. Default: the effective design.imageFit, else 'cover' in a layout and 'contain' on a slide with no layout."
         },
         "focus": {
           "$ref": "#/$defs/ImageFocus",
@@ -3157,7 +3158,7 @@
     },
     "Chart": {
       "type": "object",
-      "description": "Chart content. The chart object keeps chart-specific fields together so slides and regions do not expose loose chart fields.",
+      "description": "Chart content. The chart object keeps chart-specific fields together so slides and regions do not expose loose chart fields. OPF charts are `{ type, data }` where `data` is `{ columns, rows }`: the first column holds the category labels and every further column is one series. There are no `categories`, `series`, `labels` or `datasets` keys (the Chart.js and ECharts shape); write them as columns and rows. Example: `{ \"type\": \"column\", \"data\": { \"columns\": [\"Quarter\", \"Decks\"], \"rows\": [[\"Q1\", 3], [\"Q2\", 8], [\"Q3\", 21]] } }`.",
       "additionalProperties": false,
       "required": ["type", "data"],
       "properties": {
@@ -3390,7 +3391,7 @@
     },
     "ChartData": {
       "type": "object",
-      "description": "Inline tabular data driving a chart. The first column usually supplies category/x-axis labels; subsequent columns are plotted measures unless 'chart.mapping' or a chart type maps them differently. Value cells are numbers; a string is read only in strict decimal syntax ('12', '-3.5', '1e6'), and anything else ('12%', '$5', '(5)', '1,234') is a gap and a 'chart-value-not-numeric' warning.",
+      "description": "Inline tabular data driving a chart, written as `{ \"columns\": [\"Quarter\", \"Decks\"], \"rows\": [[\"Q1\", 3], [\"Q2\", 8]] }`: one column of labels plus one column per series, not separate `categories` and `series` lists. The first column usually supplies category/x-axis labels; subsequent columns are plotted measures unless 'chart.mapping' or a chart type maps them differently. Value cells are numbers; a string is read only in strict decimal syntax ('12', '-3.5', '1e6'), and anything else ('12%', '$5', '(5)', '1,234') is a gap and a 'chart-value-not-numeric' warning.",
       "additionalProperties": false,
       "required": ["columns", "rows"],
       "properties": {
@@ -3724,7 +3725,7 @@
               "$ref": "#/$defs/TableCellBorder"
             }
           },
-          "description": "Independent cell edges. Omitted edges retain the table theme border; width 0 removes an edge."
+          "description": "Independent cell edges. An omitted edge keeps the table's default rule: a line under every row (and over the first row), none between columns. Width 0 removes an edge."
         }
       },
       "description": "Cell appearance. Sizes use reference pixels at a 720-pixel canvas short edge and scale with the slide."