@openpresentation/opf 0.2.2 → 0.4.0

package/dist/spec/README.md

@@ -0,0 +1,57 @@
+# spec/
+
+Canonical, package-addressable OPF spec content. Everything in this directory ships inside `@openpresentation/opf` and is importable as `@openpresentation/opf/spec/<path>`.
+
+New to the format? Read [`docs/how-opf-works.md`](../docs/how-opf-works.md) first — this directory is the machine-readable half of that story.
+
+## Layout
+
+| Path | Contents |
+|---|---|
+| [`schemas/opf.schema.json`](./schemas/opf.schema.json) | Canonical JSON Schema for top-level OPF `Presentation` documents (`$id: https://openpresentation.org/schema/opf/v1`). |
+| [`schemas/*.schema.json`](./schemas) | Companion schemas for catalog records. Each has a stable `$id` of the form `https://openpresentation.org/schema/opf-<kind>/v1` (e.g. `opf-narrative`, `opf-theme`, `opf-chart-type`). Two schemas in this directory — `catalog-index.schema.json` and `layout-preview-index.schema.json` — describe repo-internal *index* 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). |
+| [`catalogs/<kind>/`](./catalogs) | Bundled catalog records, one JSON file per record plus an `index.json` per kind. These are the same records served from `https://www.pptx.gallery/<kind>`. 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. |
+| [`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`). |
+| [`reference/engine-defaults.json`](./reference/engine-defaults.json) | Reference example of engine-side defaults. Engine configuration, not part of the OPF document contract; it has no JSON Schema. |
+| [`openapi.yaml`](./openapi.yaml) | Optional reference OpenAPI 3.1 contract for downstream services that choose to expose OPF operations (validate, parse, convert, generate, render) over HTTP. OpenPresentation does not host this API; implementers can use it as a starting point for their own hosted or internal services. Local format tooling never needs it. |
+
+## Preview gallery vs. layout catalog
+
+`spec/catalogs/layouts/` and `spec/previews/layouts/` are two unrelated taxonomies that happen to share a directory name. Do not assume a preview id corresponds to a layout catalog id — none of them do.
+
+- **`spec/catalogs/layouts/`** is the **structural layout catalog**: 28 records (`title`, `title-subtitle`, `text-1x`…`text-3x`, `list-1x`…`list-6x`, `chart-1x`…`chart-3x`, `image-bleed`, `blank`, …) that `Slide.layout` resolves against. These describe placeholder structure — how many regions a slide has and what kind of content goes where — independent of subject matter.
+- **`spec/previews/layouts/`** is the **slide archetype preview gallery**: 70 self-contained HTML snippets keyed by subject-matter archetype (`swot-analysis`, `agenda`, `org-chart`, `pricing-table`, `roadmap`, …), used to render picker thumbnails. These ids describe *what a slide is about*, not its structural layout, and are never used as a `Slide.layout` value.
+
+The preview HTML files are **vendored, generated artifacts**, not hand-authored spec content. They're produced by rendering React/Tailwind components from `lib/layout-previews.tsx` in the sibling `pptx-gallery` repo via `packages/javascript/scripts/render-layout-previews.mjs`, which requires a local `../pptx-gallery` checkout (a sibling directory to this repo) to run:
+
+```sh
+node --import tsx packages/javascript/scripts/render-layout-previews.mjs
+```
+
+Without that sibling checkout, treat `spec/previews/layouts/*.html` and `index.json` as read-only committed output — edit the source components in `pptx-gallery` and re-render, rather than hand-editing the generated HTML here.
+
+## Consuming this directory
+
+Validate a document and load catalog records without touching the files directly:
+
+```ts
+import { validatePresentation, 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
+```
+
+Import the raw files when an engine, resolver, or non-JavaScript toolchain needs them:
+
+```ts
+import presentationSchema from "@openpresentation/opf/spec/schemas/opf.schema.json" with { type: "json" };
+import qbr from "@openpresentation/opf/spec/catalogs/narratives/qbr.json" with { type: "json" };
+```
+
+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.
+
+## 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/engineering-team.json

@@ -9,7 +9,7 @@
   "decisionPower": "advisory",
   "attentionBudgetMinutes": 45,
   "recommendedNarratives": [
-    "engineering-update",
+    "status-update",
     "challenge-resolution",
     "innovation",
     "weekly-progress"

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

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://openpresentation.org/schema/opf-audience-index/v1",
+  "$schema": "https://openpresentation.org/schema/opf-catalog-index/v1",
   "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.",
   "records": [

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

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://openpresentation.org/schema/opf-chart-type-index/v1",
+  "$schema": "https://openpresentation.org/schema/opf-catalog-index/v1",
   "version": "1",
   "description": "Catalog of chart types available in the pptx.gallery catalog. Each entry is a lightweight summary; full chart-type records live in the per-id JSON files alongside this index.",
   "records": [

package/dist/spec/catalogs/color-schemes/index.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://openpresentation.org/schema/opf-color-scheme-index/v1",
+  "$schema": "https://openpresentation.org/schema/opf-catalog-index/v1",
   "version": "1",
   "description": "Catalog of color schemes available in the openpresentation.org catalog. Each entry is a lightweight summary; full color-scheme records live in the per-id JSON files alongside this index.",
   "records": [

package/dist/spec/catalogs/font-schemes/index.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://openpresentation.org/schema/opf-font-scheme-index/v1",
+  "$schema": "https://openpresentation.org/schema/opf-catalog-index/v1",
   "version": "1",
   "description": "Catalog of font schemes available in the openpresentation.org catalog. Each entry is a lightweight summary; full font-scheme records live in the per-id JSON files alongside this index.",
   "records": [

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

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://openpresentation.org/schema/opf-language-index/v1",
+  "$schema": "https://openpresentation.org/schema/opf-catalog-index/v1",
   "version": "1",
   "description": "Catalog of languages available in the openpresentation.org catalog. Each entry is a lightweight summary with the canonical BCP-47 tag; full language records live in the per-id JSON files alongside this index.",
   "records": [

package/dist/spec/catalogs/layouts/chart-1x.json

@@ -12,5 +12,8 @@
     {
       "type": "text"
     }
-  ]
+  ],
+  "composition": {
+    "mode": "row"
+  }
 }

package/dist/spec/catalogs/layouts/chart-2x.json

@@ -18,5 +18,9 @@
     {
       "type": "text"
     }
-  ]
+  ],
+  "composition": {
+    "mode": "grid",
+    "columns": 2
+  }
 }

package/dist/spec/catalogs/layouts/chart-3x.json

@@ -24,5 +24,9 @@
     {
       "type": "text"
     }
-  ]
+  ],
+  "composition": {
+    "mode": "grid",
+    "columns": 3
+  }
 }

package/dist/spec/catalogs/layouts/code-1x.json

@@ -12,5 +12,8 @@
     {
       "type": "text"
     }
-  ]
+  ],
+  "composition": {
+    "mode": "row"
+  }
 }

package/dist/spec/catalogs/layouts/extract/canonical.json

@@ -45,7 +45,10 @@
       {
         "type": "text"
       }
-    ]
+    ],
+    "composition": {
+      "mode": "row"
+    }
   },
   {
     "id": "text-3x",
@@ -63,7 +66,10 @@
       {
         "type": "text"
       }
-    ]
+    ],
+    "composition": {
+      "mode": "row"
+    }
   },
   {
     "id": "list-1x",
@@ -90,7 +96,10 @@
       {
         "type": "list"
       }
-    ]
+    ],
+    "composition": {
+      "mode": "row"
+    }
   },
   {
     "id": "list-3x",
@@ -108,7 +117,10 @@
       {
         "type": "list"
       }
-    ]
+    ],
+    "composition": {
+      "mode": "row"
+    }
   },
   {
     "id": "list-4x",
@@ -129,7 +141,11 @@
       {
         "type": "list"
       }
-    ]
+    ],
+    "composition": {
+      "mode": "grid",
+      "columns": 2
+    }
   },
   {
     "id": "list-5x",
@@ -153,7 +169,11 @@
       {
         "type": "list"
       }
-    ]
+    ],
+    "composition": {
+      "mode": "grid",
+      "columns": 3
+    }
   },
   {
     "id": "list-6x",
@@ -180,7 +200,11 @@
       {
         "type": "list"
       }
-    ]
+    ],
+    "composition": {
+      "mode": "grid",
+      "columns": 3
+    }
   },
   {
     "id": "number-1x",
@@ -207,7 +231,10 @@
       {
         "type": "text"
       }
-    ]
+    ],
+    "composition": {
+      "mode": "row"
+    }
   },
   {
     "id": "number-3x",
@@ -225,7 +252,10 @@
       {
         "type": "text"
       }
-    ]
+    ],
+    "composition": {
+      "mode": "row"
+    }
   },
   {
     "id": "number-4x",
@@ -246,7 +276,11 @@
       {
         "type": "text"
       }
-    ]
+    ],
+    "composition": {
+      "mode": "grid",
+      "columns": 2
+    }
   },
   {
     "id": "number-5x",
@@ -270,7 +304,11 @@
       {
         "type": "text"
       }
-    ]
+    ],
+    "composition": {
+      "mode": "grid",
+      "columns": 3
+    }
   },
   {
     "id": "number-6x",
@@ -297,7 +335,11 @@
       {
         "type": "text"
       }
-    ]
+    ],
+    "composition": {
+      "mode": "grid",
+      "columns": 3
+    }
   },
   {
     "id": "chart-1x",
@@ -312,7 +354,10 @@
       {
         "type": "text"
       }
-    ]
+    ],
+    "composition": {
+      "mode": "row"
+    }
   },
   {
     "id": "chart-2x",
@@ -333,7 +378,11 @@
       {
         "type": "text"
       }
-    ]
+    ],
+    "composition": {
+      "mode": "grid",
+      "columns": 2
+    }
   },
   {
     "id": "chart-3x",
@@ -360,7 +409,11 @@
       {
         "type": "text"
       }
-    ]
+    ],
+    "composition": {
+      "mode": "grid",
+      "columns": 3
+    }
   },
   {
     "id": "image-1x",
@@ -375,7 +428,10 @@
       {
         "type": "text"
       }
-    ]
+    ],
+    "composition": {
+      "mode": "row"
+    }
   },
   {
     "id": "image-2x",
@@ -396,7 +452,11 @@
       {
         "type": "text"
       }
-    ]
+    ],
+    "composition": {
+      "mode": "grid",
+      "columns": 2
+    }
   },
   {
     "id": "image-3x",
@@ -423,7 +483,11 @@
       {
         "type": "text"
       }
-    ]
+    ],
+    "composition": {
+      "mode": "grid",
+      "columns": 3
+    }
   },
   {
     "id": "table-1x",
@@ -438,7 +502,10 @@
       {
         "type": "text"
       }
-    ]
+    ],
+    "composition": {
+      "mode": "row"
+    }
   },
   {
     "id": "code-1x",
@@ -453,7 +520,10 @@
       {
         "type": "text"
       }
-    ]
+    ],
+    "composition": {
+      "mode": "row"
+    }
   },
   {
     "id": "media-1x",
@@ -468,7 +538,10 @@
       {
         "type": "text"
       }
-    ]
+    ],
+    "composition": {
+      "mode": "row"
+    }
   },
   {
     "id": "image-bleed",

package/dist/spec/catalogs/layouts/image-1x.json

@@ -12,5 +12,8 @@
     {
       "type": "text"
     }
-  ]
+  ],
+  "composition": {
+    "mode": "row"
+  }
 }

package/dist/spec/catalogs/layouts/image-2x.json

@@ -18,5 +18,9 @@
     {
       "type": "text"
     }
-  ]
+  ],
+  "composition": {
+    "mode": "grid",
+    "columns": 2
+  }
 }

package/dist/spec/catalogs/layouts/image-3x.json

@@ -24,5 +24,9 @@
     {
       "type": "text"
     }
-  ]
+  ],
+  "composition": {
+    "mode": "grid",
+    "columns": 3
+  }
 }

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

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://openpresentation.org/schema/opf-layout-index/v1",
+  "$schema": "https://openpresentation.org/schema/opf-catalog-index/v1",
   "version": "1",
   "description": "Catalog of slide layouts available in the openpresentation.org catalog. Each entry is a lightweight summary; full layout records live in the per-id JSON files alongside this index.",
   "records": [

package/dist/spec/catalogs/layouts/list-2x.json

@@ -12,5 +12,8 @@
     {
       "type": "list"
     }
-  ]
+  ],
+  "composition": {
+    "mode": "row"
+  }
 }

package/dist/spec/catalogs/layouts/list-3x.json

@@ -15,5 +15,8 @@
     {
       "type": "list"
     }
-  ]
+  ],
+  "composition": {
+    "mode": "row"
+  }
 }

package/dist/spec/catalogs/layouts/list-4x.json

@@ -18,5 +18,9 @@
     {
       "type": "list"
     }
-  ]
+  ],
+  "composition": {
+    "mode": "grid",
+    "columns": 2
+  }
 }

package/dist/spec/catalogs/layouts/list-5x.json

@@ -21,5 +21,9 @@
     {
       "type": "list"
     }
-  ]
+  ],
+  "composition": {
+    "mode": "grid",
+    "columns": 3
+  }
 }

package/dist/spec/catalogs/layouts/list-6x.json

@@ -24,5 +24,9 @@
     {
       "type": "list"
     }
-  ]
+  ],
+  "composition": {
+    "mode": "grid",
+    "columns": 3
+  }
 }

package/dist/spec/catalogs/layouts/media-1x.json

@@ -12,5 +12,8 @@
     {
       "type": "text"
     }
-  ]
+  ],
+  "composition": {
+    "mode": "row"
+  }
 }

package/dist/spec/catalogs/layouts/number-2x.json

@@ -12,5 +12,8 @@
     {
       "type": "text"
     }
-  ]
+  ],
+  "composition": {
+    "mode": "row"
+  }
 }

package/dist/spec/catalogs/layouts/number-3x.json

@@ -15,5 +15,8 @@
     {
       "type": "text"
     }
-  ]
+  ],
+  "composition": {
+    "mode": "row"
+  }
 }

package/dist/spec/catalogs/layouts/number-4x.json

@@ -18,5 +18,9 @@
     {
       "type": "text"
     }
-  ]
+  ],
+  "composition": {
+    "mode": "grid",
+    "columns": 2
+  }
 }

package/dist/spec/catalogs/layouts/number-5x.json

@@ -21,5 +21,9 @@
     {
       "type": "text"
     }
-  ]
+  ],
+  "composition": {
+    "mode": "grid",
+    "columns": 3
+  }
 }

package/dist/spec/catalogs/layouts/number-6x.json

@@ -24,5 +24,9 @@
     {
       "type": "text"
     }
-  ]
+  ],
+  "composition": {
+    "mode": "grid",
+    "columns": 3
+  }
 }

package/dist/spec/catalogs/layouts/table-1x.json

@@ -12,5 +12,8 @@
     {
       "type": "text"
     }
-  ]
+  ],
+  "composition": {
+    "mode": "row"
+  }
 }

package/dist/spec/catalogs/layouts/text-2x.json

@@ -12,5 +12,8 @@
     {
       "type": "text"
     }
-  ]
+  ],
+  "composition": {
+    "mode": "row"
+  }
 }

package/dist/spec/catalogs/layouts/text-3x.json

@@ -15,5 +15,8 @@
     {
       "type": "text"
     }
-  ]
+  ],
+  "composition": {
+    "mode": "row"
+  }
 }

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

@@ -1,8 +1,8 @@
 {
-  "$schema": "https://openpresentation.org/schema/opf-narrative-index/v1",
+  "$schema": "https://openpresentation.org/schema/opf-catalog-index/v1",
   "version": "1",
   "description": "Catalog of narrative templates available in the openpresentation.org catalog. Each entry is a lightweight summary; full beat definitions live in the per-template JSON files alongside this index. Entries are grouped by usage: foundational arcs first, then pitches, sales and GTM, strategy and consulting, storytelling, keynotes and inspiration, rhythm-of-business reviews, data-driven analyses, and workforce reviews.",
-  "templates": [
+  "records": [
     {
       "id": "problem-solution",
       "name": "Problem → Solution",

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

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://openpresentation.org/schema/opf-purpose-index/v1",
+  "$schema": "https://openpresentation.org/schema/opf-catalog-index/v1",
   "version": "1",
   "description": "Catalog of presentation purposes available in the openpresentation.org catalog. Each entry is a lightweight summary; full purpose records live in the per-id JSON files alongside this index. Purposes are referenced from OPF documents via purpose.",
   "records": [

package/dist/spec/catalogs/social-platforms/index.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://openpresentation.org/schema/opf-social-platform-index/v1",
+  "$schema": "https://openpresentation.org/schema/opf-catalog-index/v1",
   "version": "1",
   "description": "Catalog of social-media platforms available in the openpresentation.org catalog. Each entry is a lightweight summary; full platform records live in the per-id JSON files alongside this index. The property keys of any Socials object on Organization or Speaker resolve to ids in this catalog.",
   "records": [

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

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://openpresentation.org/schema/opf-theme-index/v1",
+  "$schema": "https://openpresentation.org/schema/opf-catalog-index/v1",
   "version": "1",
   "description": "Catalog of themes available in the openpresentation.org catalog. Each entry is a lightweight summary; full theme records live in the per-id JSON files alongside this index.",
   "records": [

package/dist/spec/catalogs/tones/casual.json

@@ -25,7 +25,7 @@
     "weekly-progress",
     "status-update",
     "company-intro",
-    "all-hands"
+    "focus"
   ],
   "tags": ["internal", "warm", "conversational"]
 }