@openpresentation/opf 0.13.0 → 0.15.1

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

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-audience/v1",
   "title": "Audience",
-  "description": "Schema for audience records in the pptx.gallery library. 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. Audiences are referenced from OPF documents via audience; the engine resolves the reference against catalogs.audiences (inline) → catalogs.audiences.source → the default catalog at https://www.pptx.gallery/audiences. The audience field also accepts free-form strings; this catalog is for engine-aware audience archetypes that carry generation hints.",
+  "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",
   "required": [
     "$schema",
@@ -13,12 +13,12 @@
     "$schema": {
       "type": "string",
       "const": "https://openpresentation.org/schema/opf-audience/v1",
-      "description": "Identifies this record as an audience in the openpresentation.org catalog."
+      "description": "Identifies a published record file as a audience record. Required in a published file; an embedded copy omits it."
     },
     "id": {
       "type": "string",
       "pattern": "^[a-z][a-z0-9-]*$",
-      "description": "Stable slug used by OPF documents to reference this audience via audience. Lowercase kebab-case.",
+      "description": "The audience's id in its catalog, lowercase kebab-case. Required in a published record file; a document references the record by it (a bare id, or 'name:id' for a named group) and embeds it keyed by it, without this field.",
       "examples": [
         "executive",
         "board",
@@ -48,27 +48,6 @@
         "Regulators"
       ]
     },
-    "deprecation": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["replacedBy"],
-      "description": "Present when this audience is deprecated, for example an alias kept for backward compatibility. Deprecated records stay resolvable so existing documents keep validating and rendering unchanged, but pickers and default listings exclude them and validators warn when a document references them. Same shape as the chart-type deprecation.",
-      "properties": {
-        "replacedBy": {
-          "type": "string",
-          "pattern": "^[a-z][a-z0-9-]*$",
-          "description": "Id of the non-deprecated audience record that documents should reference instead."
-        },
-        "reason": {
-          "type": "string",
-          "description": "Why the record is deprecated."
-        },
-        "removal": {
-          "type": "string",
-          "description": "Package version in which the record is scheduled for removal from the bundled catalog, if any."
-        }
-      }
-    },
     "summary": {
       "type": "string",
       "description": "One-sentence positioning of the audience — who they are and what they care about.",
@@ -118,14 +97,14 @@
     "attentionBudgetMinutes": {
       "type": "number",
       "exclusiveMinimum": 0,
-      "description": "Realistic upper bound on this audience's focused attention for a single presentation, in minutes. Used as a hint when comparing against duration and the resolved narrative's durationRange."
+      "description": "Realistic upper bound on this audience's focused attention for a single presentation, in minutes. Used as a hint when comparing against duration and the resolved narrative's duration range."
     },
     "recommendedNarratives": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "Soft cross-link: narrative-catalog ids that work well for this audience. Used by picker UIs to suggest narratives once an audience is chosen. Validators warn on unknown ids; never error.",
+      "description": "Soft cross-link: ids of narratives in the same catalog that work well for this audience. Used by picker UIs to suggest narratives once an audience is chosen. Never resolved, embedded or validated as references.",
       "examples": [
         ["scqa", "board-meeting", "qbr"]
       ]
@@ -135,7 +114,7 @@
       "items": {
         "type": "string"
       },
-      "description": "Soft cross-link: tone-catalog ids that work well for this audience.",
+      "description": "Soft cross-link: ids of tones in the same catalog that work well for this audience. Never resolved, embedded or validated as references.",
       "examples": [
         ["formal", "authoritative"]
       ]

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

@@ -2,7 +2,7 @@
   "$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 and by the default-catalog index that pptx.gallery publishes at `https://www.pptx.gallery/<kind>/index.json` (spec/catalogs 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`, `durationRange`). 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.",
+  "description": "Generic shape shared by every `spec/catalogs/<kind>/index.json` file in the OPF repo and by the default-catalog index that pptx.gallery publishes at `https://www.pptx.gallery/<kind>/index.json` (spec/catalogs 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",
   "required": ["$schema", "version", "description", "records"],
   "additionalProperties": false,
@@ -56,7 +56,7 @@
   "$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.",
+      "description": "Lightweight summary of one catalog record. Additional per-kind fields (e.g. `summary`, `tags`, `bcp47`, `duration`, `group`, `label`) are allowed and vary by catalog kind.",
       "required": ["id", "name", "file"],
       "additionalProperties": true,
       "properties": {

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

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-catalog-manifest/v1",
   "title": "Catalog Snapshot Manifest",
-  "description": "Shape of `spec/catalogs/manifest.json`, which pins the bundled catalogs to 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.",
+  "description": "Shape of `spec/catalogs/manifest.json`, which pins the snapshot of the default OPF catalog published by pptx.gallery (shipped as @openpresentation/opf/catalog). 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",
   "required": ["$schema", "description", "publisher", "source", "kinds"],
   "additionalProperties": false,
@@ -54,8 +54,8 @@
       "properties": {
         "mode": {
           "type": "string",
-          "description": "'mirror': the snapshot holds every published record. 'subset': the snapshot keeps its existing ids (their content comes from the publisher) while the publisher also serves records that are not reconciled for bundling yet.",
-          "enum": ["mirror", "subset"]
+          "description": "Always 'mirror': the snapshot holds every record the publisher serves for the kind (OPF 0.15).",
+          "enum": ["mirror"]
         },
         "records": {
           "type": "integer",

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

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-chart-type/v1",
   "title": "Chart Type",
-  "description": "Schema for chart-type records in the pptx.gallery catalog. The bundled catalog holds one record per chart type that Aspose.Slides officially supports (see mappings.renderers[\"aspose-slides\"].chartType). Each record describes a named chart variant, its Open XML mapping, its series/category cardinality, the column structure of the underlying workbook, and a small sample dataset suitable for previews. Chart types are referenced from OPF chart content payloads; the engine resolves the reference against catalogs.chartTypes (inline) -> catalogs.chartTypes.source -> the default catalog at https://www.pptx.gallery/chart-types.",
+  "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/opf/catalog ships them as catalogDisplay.chartTypes.",
   "type": "object",
   "additionalProperties": false,
   "patternProperties": {
@@ -25,29 +25,19 @@
     "id": {
       "type": "string",
       "pattern": "^[a-z0-9][a-z0-9-]*$",
-      "description": "Stable slug used by OPF documents to reference this chart type. Lowercase kebab-case. Chart type ids may start with a digit (e.g., '100pct-stacked-column', '3d-column') to mirror conventional chart naming.",
+      "description": "The chart-type value (`chart.type`) this record describes. Lowercase kebab-case; it may start with a digit (e.g., '100pct-stacked-column') to mirror conventional chart naming.",
       "examples": [
         "column",
         "bar",
-        "stacked-column-3x",
+        "stacked-column",
         "doughnut",
         "treemap",
-        "100pct-stacked-column-3x"
+        "100pct-stacked-column"
       ]
     },
     "name": {
       "type": "string",
-      "description": "Stable display/programmatic name for this chart type.",
-      "examples": [
-        "COLUMN",
-        "STACKED_COLUMN_3X",
-        "DOUGHNUT",
-        "TREEMAP"
-      ]
-    },
-    "label": {
-      "type": "string",
-      "description": "Human-readable label shown in chart pickers.",
+      "description": "Human-readable name of the chart type, as a chart picker shows it.",
       "examples": [
         "Column",
         "Stacked Column",
@@ -60,27 +50,23 @@
       "description": "One-sentence positioning: when to reach for this chart variant.",
       "examples": [
         "Single-series vertical column chart for comparing values across categories.",
-        "Bullet chart that benchmarks one value against ranked threshold bands."
+        "Stacked column chart that shows how the parts of each category add up to its total."
       ]
     },
     "description": {
       "type": "string",
       "description": "Longer prose describing the chart and ideal use cases.",
       "examples": [
-        "Use a clustered column when you want to compare a small number of series across the same categories — e.g., revenue by quarter for two product lines. Best with 2–4 series and ≤12 categories."
+        "Use a stacked column when you want to compare totals across categories and also show how each series contributes — e.g., revenue by quarter split by product line. Best with 2–4 series and ≤12 categories."
       ]
     },
     "mappings": {
       "$ref": "#/$defs/ChartTypeMappings",
       "description": "Canonical and optional renderer-specific mappings used by engines to render this chart type."
     },
-    "deprecation": {
-      "$ref": "#/$defs/ChartTypeDeprecation",
-      "description": "Present when this chart type is deprecated. Deprecated records stay resolvable so existing documents keep validating, but pickers and default listings exclude them, validators warn when a document references them, and they are removed in the release named by `removal`."
-    },
     "group": {
       "type": "string",
-      "description": "Top-level grouping in the chart picker (column, bar, line, area, pie, radar, etc.).",
+      "description": "Top-level grouping in the chart picker.",
       "examples": [
         "Column",
         "Bar",
@@ -91,9 +77,8 @@
         "Histogram",
         "XY (Scatter)",
         "Treemap",
-        "Bullet",
-        "Sparkline",
         "Map",
+        "Combo",
         "Other"
       ]
     },
@@ -115,155 +100,18 @@
         "hierarchical",
         "normalized"
       ],
-      "description": "Shape of the underlying data: a flat series ('simple'), one with engine-side calculation ('calculated'), parent-child rows ('hierarchical'), or pre-normalized rows ('normalized')."
+      "description": "Shape of the underlying data: a flat series ('simple'), one with engine-side calculation ('calculated'), parent-child rows ('hierarchical'), or pre-normalized rows ('normalized'). The editor offers only 'simple' types as switch targets for a chart's existing data."
     },
     "series": {
       "type": "integer",
       "minimum": 0,
-      "description": "Number of data series this chart type expects.",
-      "examples": [
-        1,
-        2,
-        3,
-        4
-      ]
-    },
-    "categories": {
-      "type": "integer",
-      "minimum": 0,
-      "description": "Number of category labels this chart type expects on the primary axis.",
-      "examples": [
-        4,
-        6,
-        8,
-        12
-      ]
-    },
-    "seriesGroups": {
-      "type": "integer",
-      "minimum": 1,
-      "description": "Number of series groups (axis bands) this chart type uses; >1 for combo or banded charts.",
+      "description": "Number of data series this chart type expects: exactly that many, except that a stacked or percent-stacked type and a combination (composition 'mixed', such as combo) expect at least that many. The editor offers a type that expects more than one series only for data with a fitting number of value columns; a one-series type fits one value column, and column, bar, line, area and radar types fit any number.",
       "examples": [
         1,
         2,
         3
       ]
     },
-    "useSecondaryCategories": {
-      "type": "boolean",
-      "description": "Whether the chart type uses a secondary category axis.",
-      "examples": [
-        false,
-        true
-      ]
-    },
-    "workbookRange": {
-      "type": "string",
-      "description": "A1 reference to the source range in the embedded workbook.",
-      "examples": [
-        "Sheet1!$A$1:$I$2",
-        "Sheet1!$A$1:$G$3"
-      ]
-    },
-    "columns": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      },
-      "description": "Column header names of the embedded workbook, in left-to-right order.",
-      "examples": [
-        [
-          "Series 1",
-          "Value"
-        ],
-        [
-          "Series 1",
-          "Value 1",
-          "Value 2"
-        ]
-      ]
-    },
-    "dataColumns": {
-      "type": "array",
-      "items": {
-        "$ref": "#/$defs/ChartDataColumn"
-      },
-      "description": "Per-column metadata describing the role and position of each column in the workbook source.",
-      "examples": [
-        [
-          {
-            "name": "Series 1",
-            "role": "categoryLabel",
-            "type": "string",
-            "position": "row0_col0"
-          },
-          {
-            "name": "Value 1",
-            "role": "series",
-            "type": "number",
-            "position": "row1_col0"
-          },
-          {
-            "name": "Value 2",
-            "role": "series",
-            "type": "number",
-            "position": "row2_col0"
-          }
-        ]
-      ]
-    },
-    "helperColumns": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      },
-      "description": "Optional auxiliary column names used by calculated or banded charts (e.g., 'Excellent', 'Good', 'Fair', 'Poor' for a bullet chart).",
-      "examples": [
-        [
-          "Excellent",
-          "Good",
-          "Fair",
-          "Poor"
-        ],
-        [
-          "Band"
-        ]
-      ]
-    },
-    "sampleData": {
-      "$ref": "#/$defs/ChartSampleData",
-      "description": "Inline sample dataset for previews and pickers.",
-      "examples": [
-        {
-          "headers": [
-            "Series 1",
-            "Q1 2024",
-            "Q2 2024",
-            "Q3 2024",
-            "Q4 2024"
-          ],
-          "rows": [
-            [
-              "Value",
-              93810,
-              24592,
-              13278,
-              46048
-            ]
-          ]
-        }
-      ]
-    },
-    "slideNumber": {
-      "type": "integer",
-      "minimum": 1,
-      "description": "Source slide number in the original chart-gallery deck. Carried for traceability.",
-      "examples": [
-        1,
-        2,
-        48
-      ]
-    },
     "tags": {
       "type": "array",
       "items": {
@@ -276,9 +124,8 @@
           "comparison"
         ],
         [
-          "bullet",
-          "kpi",
-          "benchmark"
+          "stacked",
+          "composition"
         ]
       ]
     },
@@ -291,7 +138,7 @@
           "format": "uri",
           "description": "Main preview image (PNG/JPG). Used as the primary visual in picker UIs and previews of the record.",
           "examples": [
-            "https://www.pptx.gallery/chart-types/clustered-column.png"
+            "https://www.pptx.gallery/chart-types/column.png"
           ]
         },
         "thumbnailSrc": {
@@ -299,7 +146,7 @@
           "format": "uri",
           "description": "Smaller thumbnail preview suited to dense grid views.",
           "examples": [
-            "https://www.pptx.gallery/chart-types/clustered-column.thumbnail.png"
+            "https://www.pptx.gallery/chart-types/column.thumbnail.png"
           ]
         },
         "vectorSrc": {
@@ -307,42 +154,13 @@
           "format": "uri",
           "description": "SVG / vector preview for crisp scaling at any size.",
           "examples": [
-            "https://www.pptx.gallery/chart-types/clustered-column.svg"
+            "https://www.pptx.gallery/chart-types/column.svg"
           ]
         }
       }
     }
   },
   "$defs": {
-    "ChartTypeDeprecation": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "replacedBy"
-      ],
-      "properties": {
-        "replacedBy": {
-          "type": "string",
-          "pattern": "^[a-z0-9][a-z0-9-]*$",
-          "description": "Id of the non-deprecated chart type that documents should reference instead.",
-          "examples": [
-            "column",
-            "stacked-column-3x"
-          ]
-        },
-        "reason": {
-          "type": "string",
-          "description": "Why the record is deprecated."
-        },
-        "removal": {
-          "type": "string",
-          "description": "Package version in which the record is scheduled for removal from the bundled catalog.",
-          "examples": [
-            "0.12.0"
-          ]
-        }
-      }
-    },
     "ChartTypeMappings": {
       "type": "object",
       "additionalProperties": false,
@@ -356,7 +174,7 @@
         },
         "renderers": {
           "type": "object",
-          "description": "Optional renderer-specific mappings. Keys are renderer ids; values are intentionally opaque to OPF. The bundled catalog records the matching Aspose.Slides ChartType enumeration member under the \"aspose-slides\" key, e.g. {\"aspose-slides\": {\"chartType\": \"StackedColumn\"}}.",
+          "description": "Optional renderer-specific mappings. Keys are renderer ids; values are intentionally opaque to OPF. The bundled catalog records the matching Aspose.Slides ChartType enumeration member under the \"aspose-slides\" key, e.g. {\"aspose-slides\": {\"chartType\": \"StackedColumn\"}}; a mixed composition names the ChartType it starts from and the series type it switches series to, e.g. {\"chartType\": \"ClusteredColumn\", \"lineSeriesType\": \"LineWithMarkers\"}.",
           "additionalProperties": {
             "type": "object",
             "additionalProperties": true
@@ -455,128 +273,6 @@
           "description": "Short implementation note for mappings that need renderer interpretation."
         }
       }
-    },
-    "ChartDataColumn": {
-      "type": "object",
-      "description": "One column of the embedded chart workbook, annotated with its role and grid position.",
-      "required": [
-        "name",
-        "role",
-        "type"
-      ],
-      "properties": {
-        "name": {
-          "type": "string",
-          "description": "Column header name (e.g. 'Series 1', 'Value', 'Level1', 'Level2').",
-          "examples": [
-            "Series 1",
-            "Value",
-            "Level1",
-            "Level2"
-          ]
-        },
-        "role": {
-          "type": "string",
-          "enum": [
-            "categoryLabel",
-            "series",
-            "helper"
-          ],
-          "description": "Role this column plays: a category label (axis tick), a series (plotted values), or a helper (calculated/auxiliary)."
-        },
-        "type": {
-          "type": "string",
-          "enum": [
-            "string",
-            "number"
-          ],
-          "description": "Cell value type for the column."
-        },
-        "position": {
-          "type": "string",
-          "pattern": "^row[0-9]+_col[0-9]+$",
-          "description": "Grid position of the column header in the source workbook, as 'row<N>_col<M>' (zero-indexed).",
-          "examples": [
-            "row0_col0",
-            "row1_col0",
-            "row2_col0"
-          ]
-        }
-      }
-    },
-    "ChartSampleData": {
-      "type": "object",
-      "description": "Inline sample dataset for previews. Mirrors a small workbook with header row plus data rows.",
-      "required": [
-        "headers",
-        "rows"
-      ],
-      "properties": {
-        "headers": {
-          "type": "array",
-          "items": {
-            "type": "string"
-          },
-          "description": "Header row labels. The first cell typically labels the series column; the rest are category labels.",
-          "examples": [
-            [
-              "Series 1",
-              "Q1 2024",
-              "Q2 2024",
-              "Q3 2024",
-              "Q4 2024",
-              "Q1 2025",
-              "Q2 2025",
-              "Q3 2025",
-              "Q4 2025"
-            ]
-          ]
-        },
-        "rows": {
-          "type": "array",
-          "items": {
-            "type": "array",
-            "items": {
-              "type": [
-                "string",
-                "number"
-              ]
-            }
-          },
-          "description": "Two-dimensional sample data. Each row aligns by index with the headers — first cell is the row label, remaining cells are values.",
-          "examples": [
-            [
-              [
-                "Value",
-                93810,
-                24592,
-                13278,
-                46048,
-                42098,
-                39256,
-                28289,
-                23434
-              ]
-            ],
-            [
-              [
-                "Value 1",
-                98696,
-                81482,
-                21395,
-                87397
-              ],
-              [
-                "Value 2",
-                38657,
-                40495,
-                76237,
-                88907
-              ]
-            ]
-          ]
-        }
-      }
     }
   }
 }