@openpresentation/opf 0.3.0 → 0.4.0

package/dist/spec/README.md

@@ -9,12 +9,27 @@ New to the format? Read [`docs/how-opf-works.md`](../docs/how-opf-works.md) firs
 | Path | Contents |
 |---|---|
 | [`schemas/opf.schema.json`](./schemas/opf.schema.json) | Canonical JSON Schema for top-level OPF `Presentation` documents (`$id: https://openpresentation.org/schema/opf/v1`). |
-| [`schemas/*.schema.json`](./schemas) | Companion schemas for catalog records. Each has a stable `$id` of the form `https://openpresentation.org/schema/opf-<kind>/v1` (e.g. `opf-narrative`, `opf-theme`, `opf-chart-type`). |
-| [`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>`. |
-| [`previews/`](./previews) | Preview metadata for catalog records (currently layout previews). |
+| [`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:

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/index.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://openpresentation.org/schema/opf-tone-index/v1",
+  "$schema": "https://openpresentation.org/schema/opf-catalog-index/v1",
   "version": "1",
   "description": "Catalog of presentation tones available in the openpresentation.org catalog. Each entry is a lightweight summary; full tone records (voice cues, anti-patterns, sample phrases) live in the per-id JSON files alongside this index. Tones are referenced from OPF documents via tone.",
   "records": [