@openpresentation/opf 0.2.2 → 0.4.0

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

@@ -22,7 +22,7 @@
     "If you take one thing from this section, take this."
   ],
   "recommendedNarratives": [
-    "all-hands",
+    "focus",
     "company-intro",
     "weekly-progress",
     "performance-review"

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": [

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

@@ -25,7 +25,7 @@
     "challenge-resolution",
     "innovation",
     "conference-talk",
-    "engineering-update"
+    "status-update"
   ],
   "tags": ["technical", "engineering", "research"]
 }

package/dist/spec/openapi.yaml

@@ -1,32 +1,32 @@
 openapi: 3.1.0
 info:
-  title: pptx.dev API
+  title: OPF Service API Reference
   version: "1.0.0"
   description: |
-    REST API for parsing, validating, converting, generating, and rendering presentations.
+    Reference REST API shape for downstream services that parse, validate, convert, generate, or render presentations with OPF.
     OPF (Open Presentation Format) is the JSON contract; schema URL: `https://openpresentation.org/schema/opf/v1`.
 
-    **Authentication:** Send `Authorization: Bearer <Clerk API key>` on every request, or use a signed-in browser session (Studio). `POST /v1/preview` is anonymous (IP rate-limited) for the OPF Playground.
+    OpenPresentation does not host this API. Implementers may use this contract as a starting point for their own hosted services, internal tools, or self-hosted deployments.
 
-    Human-readable docs: [pptx.dev/docs](https://www.pptx.dev/docs)
+    **Authentication:** Send `Authorization: Bearer <token>` on authenticated requests. `POST /v1/preview` is shown as an optional unauthenticated preview endpoint for services that choose to expose one.
   contact:
-    name: pptx.dev
-    url: https://www.pptx.dev
+    name: OpenPresentation
+    url: https://openpresentation.org
   license:
     name: MIT
     url: https://opensource.org/licenses/MIT
 
 servers:
-  - url: https://api.pptx.dev
-    description: Production API
+  - url: https://api.example.com
+    description: Downstream service endpoint
   - url: http://localhost:3000/api
-    description: Local Next.js App Router (`/api` prefix)
+    description: Example local development endpoint
 
 tags:
   - name: playground
-    description: Anonymous OPF playground helpers (IP rate limits)
+    description: Optional unauthenticated OPF preview helpers
   - name: validate
-    description: OPF schema validation (no billing for validation)
+    description: OPF schema validation
   - name: parse
     description: Upload and inspect .pptx files
   - name: convert
@@ -57,18 +57,13 @@ paths:
                 summary: Minimal OPF
                 value:
                   $schema: "https://openpresentation.org/schema/opf/v1"
-                  meta:
-                    title: Example
+                  name: Example
                   design:
-                    theme: corporate-minimal
+                    theme: minimal
                   slides:
                     - id: s1
-                      layout: title-slide
-                      elements:
-                        - id: h1
-                          type: text
-                          content:
-                            text: Hello
+                      layout: title
+                      title: Hello
       responses:
         "200":
           description: Validation result
@@ -421,7 +416,7 @@ components:
     bearerAuth:
       type: http
       scheme: bearer
-      description: Clerk user or org API key (`ppx_…`), or session cookie from signed-in Studio user.
+      description: Service-defined bearer token.
 
   parameters:
     ParseId:
@@ -479,18 +474,63 @@ components:
 
     OpfDocument:
       type: object
-      description: OPF v1 document. See https://www.pptx.dev/docs/opf for field reference.
+      description: |
+        OPF v1 document. See https://openpresentation.org/schema/opf/v1 for the canonical schema.
+        This is a loose property sketch for API tooling, not a full mirror of the schema — deck identity
+        lives in `name` (there is no `meta` wrapper and no root `title`); slide content is authored via
+        content-kind fields (`text`, `items`, `bullets`, `image`, `chart`, `table`, `code`, `metric`,
+        `quote`, `timeline`, `blocks`) or promoted region keys, not a generic `elements` array.
       additionalProperties: true
+      required: [slides]
       properties:
         $schema:
           type: string
           const: "https://openpresentation.org/schema/opf/v1"
-        meta:
+        name:
+          type: string
+          description: Display name of the presentation (deck identity, not slide content).
+        design:
           type: object
           additionalProperties: true
-        design:
+          description: Optional design system (theme, colorScheme, fontScheme, dimensions, background, logo, header, footer, etc).
+        assets:
+          type: object
+          additionalProperties: true
+          description: Optional reusable asset registry referenced elsewhere via `asset:<id>` strings.
+        catalogs:
           type: object
           additionalProperties: true
+          description: Optional per-kind catalog overrides (inline records and/or a non-default source).
+        narrative:
+          description: Structured storyline. A bare catalog id string, or an inline narrative object.
+          oneOf:
+            - type: string
+            - type: object
+              additionalProperties: true
+        audience:
+          description: Intended audience(s). A string shorthand, or an array of strings/inline audience objects.
+          oneOf:
+            - type: string
+            - type: array
+              items: {}
+        purpose:
+          description: Primary goal of the presentation. A string shorthand, or an inline purpose object.
+          oneOf:
+            - type: string
+            - type: object
+              additionalProperties: true
+        tone:
+          description: Desired tone. A string shorthand, or an inline tone object.
+          oneOf:
+            - type: string
+            - type: object
+              additionalProperties: true
+        language:
+          description: Presentation language. A BCP-47 tag or catalog id string, or an inline language object.
+          oneOf:
+            - type: string
+            - type: object
+              additionalProperties: true
         slides:
           type: array
           items:
@@ -604,7 +644,7 @@ components:
               type: string
             filename:
               type: string
-              description: Suggested download filename including extension (resolved from meta.filename or title).
+              description: Suggested download filename including extension (resolved from the OPF document's `filename` or a slug of its `name`).
             subtitle:
               type: string
         design:
@@ -653,7 +693,7 @@ components:
           type: string
         filename:
           type: string
-          description: Suggested output filename including extension (from meta.filename or title slug).
+          description: Suggested output filename including extension (from the OPF document's `filename` or a slug of its `name`).
         slideCount:
           type: integer
         validationWarnings:

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

@@ -1,357 +1,357 @@
 {
   "$schema": "https://openpresentation.org/schema/opf-layout-preview-index/v1",
   "version": "1",
-  "description": "Catalog of static HTML previews for slide layouts. Each preview is a self-contained Tailwind-styled snippet sized to fill a 16:9 thumbnail. Consumers should provide the standard pptx.gallery CSS variables (--background, --foreground, --card, --muted, --muted-foreground, --accent, --border) on a parent element.",
+  "description": "Vendored gallery of static HTML previews for slide archetypes (e.g. 'swot-analysis', 'agenda', 'org-chart') — a subject-matter taxonomy for picker thumbnails, distinct from and non-overlapping with the structural layout catalog at spec/catalogs/layouts/ (e.g. 'title', 'chart-2x'); preview ids here do not correspond to layout catalog ids. Each preview is a self-contained Tailwind-styled snippet sized to fill a 16:9 thumbnail. Consumers should provide the standard pptx.gallery CSS variables (--background, --foreground, --card, --muted, --muted-foreground, --accent, --border) on a parent element. Generated from the sibling pptx-gallery repo via packages/javascript/scripts/render-layout-previews.mjs; treat the HTML files here as committed, read-only build output.",
   "records": [
     {
       "id": "action-plan",
       "file": "action-plan.html",
-      "bytes": 1940
+      "bytes": 1941
     },
     {
       "id": "agenda",
       "file": "agenda.html",
-      "bytes": 1196
+      "bytes": 1197
     },
     {
       "id": "appendix-index",
       "file": "appendix-index.html",
-      "bytes": 1678
+      "bytes": 1679
     },
     {
       "id": "architecture-stack",
       "file": "architecture-stack.html",
-      "bytes": 1656
+      "bytes": 1657
     },
     {
       "id": "assumptions-dependencies",
       "file": "assumptions-dependencies.html",
-      "bytes": 1977
+      "bytes": 1978
     },
     {
       "id": "before-after",
       "file": "before-after.html",
-      "bytes": 475
+      "bytes": 476
     },
     {
       "id": "benchmark-target-table",
       "file": "benchmark-target-table.html",
-      "bytes": 1984
+      "bytes": 1985
     },
     {
       "id": "bullet-list",
       "file": "bullet-list.html",
-      "bytes": 1028
+      "bytes": 1029
     },
     {
       "id": "business-model-canvas",
       "file": "business-model-canvas.html",
-      "bytes": 2734
+      "bytes": 2735
     },
     {
       "id": "capability-map",
       "file": "capability-map.html",
-      "bytes": 2343
+      "bytes": 2344
     },
     {
       "id": "case-study",
       "file": "case-study.html",
-      "bytes": 1476
+      "bytes": 1477
     },
     {
       "id": "chapter-recap",
       "file": "chapter-recap.html",
-      "bytes": 1682
+      "bytes": 1683
     },
     {
       "id": "circular-lifecycle",
       "file": "circular-lifecycle.html",
-      "bytes": 1796
+      "bytes": 1797
     },
     {
       "id": "comparison",
       "file": "comparison.html",
-      "bytes": 1304
+      "bytes": 1305
     },
     {
       "id": "competitive-landscape",
       "file": "competitive-landscape.html",
-      "bytes": 1377
+      "bytes": 1378
     },
     {
       "id": "customer-journey",
       "file": "customer-journey.html",
-      "bytes": 2024
+      "bytes": 2025
     },
     {
       "id": "customer-logos",
       "file": "customer-logos.html",
-      "bytes": 2222
+      "bytes": 2223
     },
     {
       "id": "dashboard",
       "file": "dashboard.html",
-      "bytes": 1582
+      "bytes": 1583
     },
     {
       "id": "data-visualization",
       "file": "data-visualization.html",
-      "bytes": 506
+      "bytes": 507
     },
     {
       "id": "decision-tree",
       "file": "decision-tree.html",
-      "bytes": 1869
+      "bytes": 1870
     },
     {
       "id": "detailed-data-table",
       "file": "detailed-data-table.html",
-      "bytes": 4158
+      "bytes": 4159
     },
     {
       "id": "ecosystem-map",
       "file": "ecosystem-map.html",
-      "bytes": 2026
+      "bytes": 2027
     },
     {
       "id": "executive-decision",
       "file": "executive-decision.html",
-      "bytes": 1229
+      "bytes": 1230
     },
     {
       "id": "executive-summary",
       "file": "executive-summary.html",
-      "bytes": 1699
+      "bytes": 1700
     },
     {
       "id": "faq",
       "file": "faq.html",
-      "bytes": 530
+      "bytes": 531
     },
     {
       "id": "feature-comparison-matrix",
       "file": "feature-comparison-matrix.html",
-      "bytes": 3035
+      "bytes": 3036
     },
     {
       "id": "forecast-scenario",
       "file": "forecast-scenario.html",
-      "bytes": 997
+      "bytes": 998
     },
     {
       "id": "funnel-pyramid",
       "file": "funnel-pyramid.html",
-      "bytes": 462
+      "bytes": 463
     },
     {
       "id": "gantt-project-plan",
       "file": "gantt-project-plan.html",
-      "bytes": 1912
+      "bytes": 1913
     },
     {
       "id": "geographic-map",
       "file": "geographic-map.html",
-      "bytes": 1388
+      "bytes": 1389
     },
     {
       "id": "heatmap-cohort",
       "file": "heatmap-cohort.html",
-      "bytes": 2763
+      "bytes": 2764
     },
     {
       "id": "hub-and-spoke",
       "file": "hub-and-spoke.html",
-      "bytes": 2331
+      "bytes": 2332
     },
     {
       "id": "icon-grid",
       "file": "icon-grid.html",
-      "bytes": 1125
+      "bytes": 1126
     },
     {
       "id": "image-focus",
       "file": "image-focus.html",
-      "bytes": 230
+      "bytes": 231
     },
     {
       "id": "key-takeaway",
       "file": "key-takeaway.html",
-      "bytes": 393
+      "bytes": 394
     },
     {
       "id": "kpi-scorecard",
       "file": "kpi-scorecard.html",
-      "bytes": 1633
+      "bytes": 1634
     },
     {
       "id": "logic-tree",
       "file": "logic-tree.html",
-      "bytes": 1531
+      "bytes": 1532
     },
     {
       "id": "market-size",
       "file": "market-size.html",
-      "bytes": 1100
+      "bytes": 1101
     },
     {
       "id": "matrix-quadrant",
       "file": "matrix-quadrant.html",
-      "bytes": 644
+      "bytes": 645
     },
     {
       "id": "network-dependency-map",
       "file": "network-dependency-map.html",
-      "bytes": 1816
+      "bytes": 1817
     },
     {
       "id": "one-column-explainer",
       "file": "one-column-explainer.html",
-      "bytes": 1263
+      "bytes": 1264
     },
     {
       "id": "org-chart",
       "file": "org-chart.html",
-      "bytes": 2565
+      "bytes": 2566
     },
     {
       "id": "persona-grid",
       "file": "persona-grid.html",
-      "bytes": 1770
+      "bytes": 1771
     },
     {
       "id": "photo-grid",
       "file": "photo-grid.html",
-      "bytes": 254
+      "bytes": 255
     },
     {
       "id": "pricing-table",
       "file": "pricing-table.html",
-      "bytes": 2171
+      "bytes": 2172
     },
     {
       "id": "process-flow",
       "file": "process-flow.html",
-      "bytes": 1057
+      "bytes": 1058
     },
     {
       "id": "product-feature",
       "file": "product-feature.html",
-      "bytes": 405
+      "bytes": 406
     },
     {
       "id": "pros-cons",
       "file": "pros-cons.html",
-      "bytes": 1846
+      "bytes": 1847
     },
     {
       "id": "qa-discussion",
       "file": "qa-discussion.html",
-      "bytes": 945
+      "bytes": 946
     },
     {
       "id": "quote-highlight",
       "file": "quote-highlight.html",
-      "bytes": 373
+      "bytes": 374
     },
     {
       "id": "raci-matrix",
       "file": "raci-matrix.html",
-      "bytes": 4854
+      "bytes": 4855
     },
     {
       "id": "risk-heatmap",
       "file": "risk-heatmap.html",
-      "bytes": 1264
+      "bytes": 1265
     },
     {
       "id": "roadmap",
       "file": "roadmap.html",
-      "bytes": 819
+      "bytes": 820
     },
     {
       "id": "screenshot-walkthrough",
       "file": "screenshot-walkthrough.html",
-      "bytes": 1808
+      "bytes": 1809
     },
     {
       "id": "section-divider",
       "file": "section-divider.html",
-      "bytes": 255
+      "bytes": 256
     },
     {
       "id": "single-message-statement",
       "file": "single-message-statement.html",
-      "bytes": 419
+      "bytes": 420
     },
     {
       "id": "stats-metrics",
       "file": "stats-metrics.html",
-      "bytes": 570
+      "bytes": 571
     },
     {
       "id": "status-rag",
       "file": "status-rag.html",
-      "bytes": 1678
+      "bytes": 1679
     },
     {
       "id": "swimlane-process",
       "file": "swimlane-process.html",
-      "bytes": 1815
+      "bytes": 1816
     },
     {
       "id": "swot-analysis",
       "file": "swot-analysis.html",
-      "bytes": 1112
+      "bytes": 1113
     },
     {
       "id": "team-bio",
       "file": "team-bio.html",
-      "bytes": 1527
+      "bytes": 1528
     },
     {
       "id": "testimonial-grid",
       "file": "testimonial-grid.html",
-      "bytes": 1374
+      "bytes": 1375
     },
     {
       "id": "thank-you-cta",
       "file": "thank-you-cta.html",
-      "bytes": 314
+      "bytes": 315
     },
     {
       "id": "three-column",
       "file": "three-column.html",
-      "bytes": 857
+      "bytes": 858
     },
     {
       "id": "timeline",
       "file": "timeline.html",
-      "bytes": 1189
+      "bytes": 1190
     },
     {
       "id": "title-slide",
       "file": "title-slide.html",
-      "bytes": 279
+      "bytes": 280
     },
     {
       "id": "two-column",
       "file": "two-column.html",
-      "bytes": 600
+      "bytes": 601
     },
     {
       "id": "venn-overlap",
       "file": "venn-overlap.html",
-      "bytes": 943
+      "bytes": 944
     },
     {
       "id": "waterfall-bridge",
       "file": "waterfall-bridge.html",
-      "bytes": 1068
+      "bytes": 1069
     },
     {
       "id": "wheel-radial",
       "file": "wheel-radial.html",
-      "bytes": 2159
+      "bytes": 2160
     }
   ]
 }

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

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openpresentation.org/schema/opf-catalog-index/v1",
+  "title": "Catalog Index",
+  "description": "Generic shape shared by every `spec/catalogs/<kind>/index.json` file in the OPF repo. 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`, `durationRange`). This schema describes the repo-internal catalog index files themselves, not OPF documents or individual catalog records — it is not part of the OPF document contract and is intentionally excluded from the package's published/typed schema surface.",
+  "type": "object",
+  "required": ["$schema", "version", "description", "records"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "const": "https://openpresentation.org/schema/opf-catalog-index/v1"
+    },
+    "version": {
+      "type": "string",
+      "description": "Index format version, as a string.",
+      "examples": ["1"]
+    },
+    "description": {
+      "type": "string",
+      "description": "Human-readable description of what this catalog kind holds and how entries are ordered."
+    },
+    "records": {
+      "type": "array",
+      "description": "Ordered list of lightweight record summaries. Order defines the catalog's canonical/display order; full record data lives in the sibling JSON file named by `file`.",
+      "items": { "$ref": "#/$defs/IndexRecord" }
+    }
+  },
+  "$defs": {
+    "IndexRecord": {
+      "type": "object",
+      "description": "Lightweight summary of one catalog record. Additional per-kind fields (e.g. `summary`, `tags`, `bcp47`, `durationRange`, `group`, `label`) are allowed and vary by catalog kind.",
+      "required": ["id", "name", "file"],
+      "additionalProperties": true,
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Stable identifier, matching the `id` field inside the record file named by `file`.",
+          "pattern": "^[a-z][a-z0-9-]*$"
+        },
+        "name": {
+          "type": "string",
+          "description": "Human-readable name shown in pickers."
+        },
+        "file": {
+          "type": "string",
+          "description": "Filename of the full record, relative to this index file's directory.",
+          "pattern": "^[^/]+\\.json$"
+        }
+      }
+    }
+  }
+}