@openpresentation/opf 0.11.2 → 0.11.3

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

@@ -1,7 +1,9 @@
 {
   "$schema": "https://openpresentation.org/schema/opf-catalog-index/v1",
+  "kind": "purposes",
   "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.",
+  "contentSha256": "43d9ba617491fe1d98b527d24032d5da9bc6763a01b0ea41da421c5ec27e649c",
   "records": [
     {
       "id": "inform",

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

@@ -1,7 +1,9 @@
 {
   "$schema": "https://openpresentation.org/schema/opf-catalog-index/v1",
+  "kind": "social-platforms",
   "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.",
+  "contentSha256": "22292ed144ac3caf37a86c9e644f9b648cda51ed670cbc3c0ed64915d251b375",
   "records": [
     {
       "id": "linkedin",
@@ -65,4 +67,3 @@
     }
   ]
 }
-

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

@@ -1,13 +1,15 @@
 {
   "$schema": "https://openpresentation.org/schema/opf-catalog-index/v1",
+  "kind": "themes",
   "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.",
+  "contentSha256": "5af95e3e353857bb49a2c303e66b99d74d884210070baac0b68291aad90fa8d5",
   "records": [
     {
-      "id": "bold",
-      "name": "Bold",
-      "description": "A vibrant, high-energy theme with bold colors and a dynamic, attention-grabbing style. Great for presentations that need to stand out.",
-      "file": "bold.json"
+      "id": "minimal",
+      "name": "Minimal",
+      "description": "A clean, minimalistic theme with a focus on simplicity and readability. Ideal for professional, straightforward presentations.",
+      "file": "minimal.json"
     },
     {
       "id": "classic",
@@ -22,10 +24,10 @@
       "file": "dark.json"
     },
     {
-      "id": "minimal",
-      "name": "Minimal",
-      "description": "A clean, minimalistic theme with a focus on simplicity and readability. Ideal for professional, straightforward presentations.",
-      "file": "minimal.json"
+      "id": "bold",
+      "name": "Bold",
+      "description": "A vibrant, high-energy theme with bold colors and a dynamic, attention-grabbing style. Great for presentations that need to stand out.",
+      "file": "bold.json"
     }
   ]
 }

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

@@ -1,7 +1,9 @@
 {
   "$schema": "https://openpresentation.org/schema/opf-catalog-index/v1",
+  "kind": "tones",
   "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.",
+  "contentSha256": "b5a8d0933f494d09cd3b9a399c8de2032c43d253fcf432974135e841fcc9e703",
   "records": [
     {
       "id": "formal",

package/dist/spec/reference/font-policy.json

@@ -928,8 +928,8 @@
         "compatibility": "visual",
         "measured": {
           "replacement": "Source Sans 3",
-          "meanAbsWidthDelta": 0.0157,
-          "meanWidthDelta": 0.0151,
+          "meanAbsWidthDelta": 0.0158,
+          "meanWidthDelta": 0.0152,
           "maxAbsWidthDelta": 0.0521,
           "styles": 4,
           "reference": "Corbel 6.01"
@@ -1357,9 +1357,9 @@
         "compatibility": "visual",
         "measured": {
           "replacement": "Source Sans 3",
-          "meanAbsWidthDelta": 0.051,
-          "meanWidthDelta": 0.0038,
-          "maxAbsWidthDelta": 0.1456,
+          "meanAbsWidthDelta": 0.0511,
+          "meanWidthDelta": 0.0039,
+          "maxAbsWidthDelta": 0.1459,
           "styles": 4,
           "reference": "Gill Sans MT 1.65"
         }

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

@@ -48,6 +48,27 @@
         "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.",

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

@@ -2,15 +2,37 @@
   "$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.",
+  "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.",
   "type": "object",
   "required": ["$schema", "version", "description", "records"],
   "additionalProperties": false,
+  "patternProperties": {
+    "^x-": {
+      "description": "Publisher extension member, such as pptx.gallery's `x-gallery` reconciliation status. Consumers ignore top-level `x-*` members, and the pinned snapshot in spec/catalogs never carries them."
+    }
+  },
   "properties": {
     "$schema": {
       "type": "string",
       "const": "https://openpresentation.org/schema/opf-catalog-index/v1"
     },
+    "kind": {
+      "type": "string",
+      "description": "Catalog kind, as the URL segment of the default catalog (`https://www.pptx.gallery/<kind>`) and the `spec/catalogs/<kind>` directory name.",
+      "enum": [
+        "audiences",
+        "chart-types",
+        "color-schemes",
+        "font-schemes",
+        "languages",
+        "layouts",
+        "narratives",
+        "purposes",
+        "social-platforms",
+        "themes",
+        "tones"
+      ]
+    },
     "version": {
       "type": "string",
       "description": "Index format version, as a string.",
@@ -20,6 +42,11 @@
       "type": "string",
       "description": "Human-readable description of what this catalog kind holds and how entries are ordered."
     },
+    "contentSha256": {
+      "type": "string",
+      "description": "SHA-256 (lowercase hex) of the canonical JSON of the full records this index lists, in index order, with every top-level `x-*` member removed. Canonical JSON sorts object keys and has no insignificant whitespace. Lets a consumer prove it holds exactly the published content.",
+      "pattern": "^[0-9a-f]{64}$"
+    },
     "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`.",
@@ -35,8 +62,8 @@
       "properties": {
         "id": {
           "type": "string",
-          "description": "Stable identifier, matching the `id` field inside the record file named by `file`.",
-          "pattern": "^[a-z][a-z0-9-]*$"
+          "description": "Stable identifier, matching the `id` field inside the record file named by `file`. Lowercase kebab-case; chart-type ids may start with a digit (e.g. '100pct-stacked-bar').",
+          "pattern": "^[a-z0-9][a-z0-9-]*$"
         },
         "name": {
           "type": "string",
@@ -46,6 +73,16 @@
           "type": "string",
           "description": "Filename of the full record, relative to this index file's directory.",
           "pattern": "^[^/]+\\.json$"
+        },
+        "deprecated": {
+          "type": "boolean",
+          "const": true,
+          "description": "Present on the entry of a record that carries `deprecation`. Pickers and default listings hide deprecated entries; the id keeps resolving."
+        },
+        "replacedBy": {
+          "type": "string",
+          "description": "The deprecated record's `deprecation.replacedBy`, repeated so a picker can offer the replacement without loading the record.",
+          "pattern": "^[a-z0-9][a-z0-9-]*$"
         }
       }
     }

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

@@ -0,0 +1,83 @@
+{
+  "$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.",
+  "type": "object",
+  "required": ["$schema", "description", "publisher", "source", "kinds"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "const": "https://openpresentation.org/schema/opf-catalog-manifest/v1"
+    },
+    "description": {
+      "type": "string"
+    },
+    "publisher": {
+      "type": "string",
+      "description": "Base URL of the default-catalog publisher. Each kind is published at `<publisher>/<kind>/index.json`.",
+      "format": "uri"
+    },
+    "source": {
+      "type": "object",
+      "description": "The published catalog files the snapshot was taken from.",
+      "required": ["repository", "commit", "path"],
+      "additionalProperties": false,
+      "properties": {
+        "repository": {
+          "type": "string",
+          "description": "Git repository of the publisher.",
+          "format": "uri"
+        },
+        "commit": {
+          "type": "string",
+          "description": "Full commit SHA of the publisher checkout whose published files the snapshot matches."
+        },
+        "path": {
+          "type": "string",
+          "description": "Directory in that repository holding `<kind>/index.json` and `<kind>/<id>.json`."
+        }
+      }
+    },
+    "kinds": {
+      "type": "object",
+      "description": "One entry per catalog kind, keyed by the kind's URL segment.",
+      "additionalProperties": { "$ref": "#/$defs/KindEntry" }
+    }
+  },
+  "$defs": {
+    "KindEntry": {
+      "type": "object",
+      "required": ["mode", "records", "contentSha256", "gallery"],
+      "additionalProperties": false,
+      "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"]
+        },
+        "records": {
+          "type": "integer",
+          "description": "Number of records bundled for this kind.",
+          "minimum": 0
+        },
+        "contentSha256": {
+          "type": "string",
+          "description": "contentSha256 of the bundled records, as defined by the catalog index schema.",
+          "pattern": "^[0-9a-f]{64}$"
+        },
+        "gallery": {
+          "type": "object",
+          "description": "The published catalog for this kind at the pinned commit.",
+          "required": ["records", "contentSha256"],
+          "additionalProperties": false,
+          "properties": {
+            "records": { "type": "integer", "minimum": 0 },
+            "contentSha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -5,6 +5,11 @@
   "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.",
   "type": "object",
   "additionalProperties": false,
+  "patternProperties": {
+    "^x-": {
+      "description": "Publisher extension member, such as the `x-gallery` presentation metadata that pptx.gallery adds to the records it publishes. Engines and validators ignore top-level `x-*` members, and the pinned snapshot in spec/catalogs never carries them."
+    }
+  },
   "required": [
     "$schema",
     "id",

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

@@ -36,6 +36,27 @@
         "Forest Green"
       ]
     },
+    "deprecation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["replacedBy"],
+      "description": "Present when this color scheme 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 color scheme 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 palette — what mood it evokes and where to use it.",

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

@@ -40,6 +40,27 @@
         "Microsoft Yahei"
       ]
     },
+    "deprecation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["replacedBy"],
+      "description": "Present when this font scheme 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 font scheme 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."
+        }
+      }
+    },
     "major": {
       "type": "string",
       "description": "Heading (major) font family — mirrors the OOXML majorFont entry.",

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

@@ -37,6 +37,27 @@
         "Chinese (simplified)"
       ]
     },
+    "deprecation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["replacedBy"],
+      "description": "Present when this language 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 language 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."
+        }
+      }
+    },
     "code": {
       "type": "string",
       "description": "ISO 639-3 (or 639-2) three-letter language code. Carried for engines that prefer ISO codes.",

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

@@ -36,6 +36,27 @@
         "Image Bleed"
       ]
     },
+    "deprecation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["replacedBy"],
+      "description": "Present when this layout 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 layout 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 layout — when to reach for it.",

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

@@ -24,6 +24,27 @@
       "type": "string",
       "description": "Human-readable template name, e.g. 'Problem → Solution'."
     },
+    "deprecation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["replacedBy"],
+      "description": "Present when this narrative 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 narrative 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 description of when and why to use this narrative."

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

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf/v1",
   "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\nFields that reference catalog records (narrative, language, tone, audience, purpose, design.theme / design.theme.id, design.colorScheme / design.colorScheme.id, design.fontScheme / design.fontScheme.id, Slide.layout, Chart.type, Organization.socials / Speaker.socials) resolve through the catalog system: inline 'catalogs.<kind>.records[]' on the document → 'catalogs.<kind>.source' on the document → engine defaults → the default catalog at https://www.pptx.gallery/<kind>. Every reference resolves to the catalog record's 'id' field. When an OPF document omits a reference entirely, the engine falls back to engine defaults (see /spec/reference/engine-defaults.json for a reference example). The defaults file is engine configuration; it is not part of the OPF document contract and has no JSON Schema.\n\nMost catalog references accept the bare 'id' as a string for the common case (e.g. narrative = 'classic-story', design.colorScheme = 'cool-horizon'). Audience, purpose, tone, design, and language object forms use 'id' as a base catalog reference plus inline overrides. 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.",
+  "description": "Open-source JSON format for describing PowerPoint presentations. Agents describe narratives, content, audience, reusable assets, and design — the engine handles OOXML complexity.\n\nFields that reference catalog records (narrative, language, tone, audience, purpose, design.theme / design.theme.id, design.colorScheme / design.colorScheme.id, design.fontScheme / design.fontScheme.id, Slide.layout, Chart.type, Organization.socials / Speaker.socials) resolve through the catalog system: inline 'catalogs.<kind>.records[]' on the document → 'catalogs.<kind>.source' on the document → engine defaults → the default catalog at https://www.pptx.gallery/<kind>. The default catalog is published by pptx.gallery: the index at https://www.pptx.gallery/<kind>/index.json (also GET https://www.pptx.gallery/<kind> with Accept: application/json) and each record at https://www.pptx.gallery/<kind>/<id>.json. Engines resolve it from the pinned snapshot bundled in @openpresentation/opf (spec/catalogs, pinned by spec/catalogs/manifest.json) and never fetch it at run time; fetching a document's catalogs.<kind>.source is an explicit opt-in by the caller. Every reference resolves to the catalog record's 'id' field. When an OPF document omits a reference entirely, the engine falls back to engine defaults (see /spec/reference/engine-defaults.json for a reference example). The defaults file is engine configuration; it is not part of the OPF document contract and has no JSON Schema.\n\nMost catalog references accept the bare 'id' as a string for the common case (e.g. narrative = 'classic-story', design.colorScheme = 'cool-horizon'). Audience, purpose, tone, design, and language object forms use 'id' as a base catalog reference plus inline overrides. 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",
   "required": ["slides"],
   "additionalProperties": false,
@@ -634,7 +634,7 @@
     },
     "Socials": {
       "type": "object",
-      "description": "Social media handles or URLs, keyed by platform id from the 'socialPlatforms' catalog. Each value is a string — either a full URL or a platform handle (e.g., '@acme'). The catalog record for each platform carries the URL pattern, handle prefix, brand color, and themed icons used by renderers.\n\nKeys resolve to the 'id' of a 'socialPlatforms' catalog record. Resolution order: inline catalogs.socialPlatforms.records[] → catalogs.socialPlatforms.source → default catalog at https://www.pptx.gallery/social-platforms. Unknown platform keys render with engine fallbacks (the raw value as text). Used both for organization and speaker records.",
+      "description": "Social media handles or URLs, keyed by platform id from the 'socialPlatforms' catalog. Each value is a string — either a full URL or a platform handle (e.g., '@acme'). The catalog record for each platform carries the URL pattern and handle prefix that engines use to render and link the profile URL, plus brand color and themed icons as catalog metadata for authoring UIs (engines render the profile URL, not icons or brand colors).\n\nKeys resolve to the 'id' of a 'socialPlatforms' catalog record. Resolution order: inline catalogs.socialPlatforms.records[] → catalogs.socialPlatforms.source → default catalog at https://www.pptx.gallery/social-platforms. Unknown platform keys render with engine fallbacks (the raw value as text). Used both for organization and speaker records.",
       "additionalProperties": {
         "type": "string",
         "description": "Handle or URL for the platform identified by the property key."
@@ -2997,7 +2997,7 @@
     },
     "Catalogs": {
       "type": "object",
-      "description": "Catalog overrides for the in-document references. Every property is optional. The default catalog for a kind lives at https://www.pptx.gallery/<kind> (e.g. https://www.pptx.gallery/narratives, https://www.pptx.gallery/themes). For each kind, declaring a 'source' replaces the default registry and/or 'records' adds inline records that take precedence over anything fetched from a source.\n\nResolution order for any reference (e.g. narrative, design.theme): inline catalogs.<kind>.records[] → catalogs.<kind>.source → default catalog at https://www.pptx.gallery/<kind>. Every reference resolves to the catalog record's 'id' field. References that are themselves URLs or 'pkg:' references skip the catalog lookup and resolve directly.",
+      "description": "Catalog overrides for the in-document references. Every property is optional. The default catalog for a kind lives at https://www.pptx.gallery/<kind> (e.g. https://www.pptx.gallery/narratives, https://www.pptx.gallery/themes). pptx.gallery is its canonical publisher: GET https://www.pptx.gallery/<kind>/index.json (or https://www.pptx.gallery/<kind> with Accept: application/json) returns a catalog index (https://openpresentation.org/schema/opf-catalog-index/v1) and https://www.pptx.gallery/<kind>/<id>.json returns one record that validates against the kind's companion schema; publisher metadata sits in top-level 'x-*' members that consumers ignore. Engines resolve the default catalog from the pinned snapshot bundled in @openpresentation/opf (spec/catalogs, pinned to a publisher commit and content hash by spec/catalogs/manifest.json), so resolution is deterministic offline and in the cloud; they do not fetch pptx.gallery at run time. For each kind, declaring a 'source' replaces the default registry and/or 'records' adds inline records that take precedence over anything fetched from a source.\n\nResolution order for any reference (e.g. narrative, design.theme): inline catalogs.<kind>.records[] → catalogs.<kind>.source → default catalog at https://www.pptx.gallery/<kind>. Every reference resolves to the catalog record's 'id' field. References that are themselves URLs or 'pkg:' references skip the catalog lookup and resolve directly.",
       "properties": {
         "narratives": {
           "$ref": "#/$defs/CatalogEntry",
@@ -3059,7 +3059,7 @@
               "description": "Ordered search path of sources. The engine tries each in order; first match wins. The default catalog for the kind is appended implicitly at the end."
             }
           ],
-          "description": "Single source or an ordered search path of sources. When omitted, the engine falls back to https://www.pptx.gallery/<kind>."
+          "description": "Single source or an ordered search path of sources. When omitted, the engine falls back to the default catalog at https://www.pptx.gallery/<kind>, resolved from its bundled snapshot. Fetching a declared source is an explicit opt-in: the engine or its caller performs that fetch."
         },
         "records": {
           "type": "array",
@@ -3070,7 +3070,7 @@
     },
     "CatalogSource": {
       "type": "string",
-      "description": "Catalog source location. Accepts:\n- A bare URL pointing at a catalog directory (e.g. 'https://acme.com/decks/narratives'); record ids resolve to '<base>/<id>.json'.\n- A URL pointing at an index file (e.g. 'https://acme.com/decks/narratives/index.json'); records are resolved relative to the index file's directory and the index entries describe what's available.\n- A package reference of the form 'pkg:<package>[/<subpath>]'; resolved through a locally-installed package on the engine's package path.",
+      "description": "Catalog source location. Accepts:\n- A bare URL pointing at a catalog directory (e.g. 'https://acme.com/decks/narratives'); record ids resolve to '<base>/<id>.json'.\n- A URL pointing at an index file (e.g. 'https://acme.com/decks/narratives/index.json'); records are resolved relative to the index file's directory and the index entries describe what's available. Index files follow https://openpresentation.org/schema/opf-catalog-index/v1; the default catalog's index is https://www.pptx.gallery/<kind>/index.json.\n- A package reference of the form 'pkg:<package>[/<subpath>]'; resolved through a locally-installed package on the engine's package path.",
       "examples": [
         "https://www.pptx.gallery/narratives",
         "https://acme.com/decks/narratives/index.json",

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

@@ -26,6 +26,27 @@
       "description": "Human-readable purpose name shown in pickers.",
       "examples": ["Inform", "Drive a Decision", "Align", "Persuade"]
     },
+    "deprecation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["replacedBy"],
+      "description": "Present when this purpose 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 purpose 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 purpose — what this deck is trying to accomplish."

package/dist/spec/schemas/social-platform.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-social-platform/v1",
   "title": "Social Platform",
-  "description": "Schema for social-platform records in the pptx.gallery library. Each record describes a single social-media platform — its base URL, profile-URL pattern, handle prefix, brand color, and themed icons. Records are referenced from OPF documents indirectly: the property keys of any Socials object (Organization.socials, Speaker.socials) match record ids, and renderers use the catalog record to format URLs and pick icons. The engine resolves references against catalogs.socialPlatforms (inline) → catalogs.socialPlatforms.source → the default catalog at https://www.pptx.gallery/social-platforms.",
+  "description": "Schema for social-platform records in the pptx.gallery library. Each record describes a single social-media platform — its base URL, profile-URL pattern, handle prefix, brand color, and themed icons. Records are referenced from OPF documents indirectly: the property keys of any Socials object (Organization.socials, Speaker.socials) match record ids, and engines use the catalog record's URL patterns and handle prefix to format and link the profile URL. The brand color and the themed icons are catalog metadata for authoring UIs: engines (opf-render, opf-pptx) render the profile URL, not icons or brand colors. The engine resolves references against catalogs.socialPlatforms (inline) → catalogs.socialPlatforms.source → the default catalog at https://www.pptx.gallery/social-platforms.",
   "type": "object",
   "required": [
     "$schema",
@@ -48,6 +48,27 @@
         "Bluesky"
       ]
     },
+    "deprecation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["replacedBy"],
+      "description": "Present when this social platform 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 social platform 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 platform — what it's used for and who's on it.",
@@ -111,7 +132,7 @@
     },
     "brandColor": {
       "type": "string",
-      "description": "Brand color (hex) used for branded icon chips, link styling, or section accents.",
+      "description": "Brand color (hex) for branded icon chips, link styling, or section accents in authoring UIs. Catalog metadata: engines do not draw it.",
       "examples": [
         "#0A66C2",
         "#000000",
@@ -121,7 +142,7 @@
     },
     "icon": {
       "type": "string",
-      "description": "Default icon source. Accepts an HTTPS URL, data URI, relative path, or asset reference. Used as the fallback when a themed (Light/Dark) variant isn't set.",
+      "description": "Default icon source. Accepts an HTTPS URL, data URI, relative path, or asset reference. Used as the fallback when a themed (Light/Dark) variant isn't set. Catalog metadata for authoring UIs: engines do not draw icons.",
       "examples": [
         "https://www.pptx.gallery/social-platforms/linkedin.svg",
         "./assets/social-platforms/linkedin.svg",
@@ -130,7 +151,7 @@
     },
     "iconLight": {
       "type": "string",
-      "description": "Light-colored icon variant intended for rendering on dark backgrounds.",
+      "description": "Light-colored icon variant intended for authoring UIs that draw the icon on dark backgrounds (engines do not draw icons).",
       "examples": [
         "https://www.pptx.gallery/social-platforms/linkedin-light.svg",
         "./assets/social-platforms/linkedin-light.svg"
@@ -138,7 +159,7 @@
     },
     "iconDark": {
       "type": "string",
-      "description": "Dark-colored icon variant intended for rendering on light backgrounds.",
+      "description": "Dark-colored icon variant intended for authoring UIs that draw the icon on light backgrounds (engines do not draw icons).",
       "examples": [
         "https://www.pptx.gallery/social-platforms/linkedin-dark.svg",
         "./assets/social-platforms/linkedin-dark.svg"