@openpresentation/opf 0.14.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.",
@@ -125,7 +104,7 @@
       "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-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), plus the column-and-line combination 'combo' (mappings.openxml.composition \"mixed\"). Each record names a chart variant, its Open XML mapping, how many data series it expects and how pickers group it. 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,7 +25,7 @@
     "id": {
       "type": "string",
       "pattern": "^[a-z0-9][a-z0-9-]*$",
-      "description": "Stable slug used by OPF documents to reference this chart type (`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",
@@ -64,10 +64,6 @@
       "$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. A deprecated record stays resolvable so existing documents keep validating, validators warn when a document references it, and pickers and generators should not offer it. The bundled default catalog holds no deprecated records; a publisher or an inline `catalogs.chartTypes.records` entry can still use the field."
-    },
     "group": {
       "type": "string",
       "description": "Top-level grouping in the chart picker.",
@@ -165,35 +161,6 @@
     }
   },
   "$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"
-          ]
-        },
-        "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,

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

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-color-scheme/v1",
   "title": "Color Scheme",
-  "description": "Schema for color-scheme records in the pptx.gallery library. Each scheme is a named palette with the twelve PowerPoint color slots (six accents, two darks, two lights, plus hyperlink and followed-hyperlink), suitable for being mapped directly into OOXML theme XML. Color schemes are referenced from OPF documents via design.colorScheme or design.colorScheme.id; the engine resolves the reference against catalogs.colorSchemes (inline) -> catalogs.colorSchemes.source -> the default catalog at https://www.pptx.gallery/color-schemes. Slot overrides on design.colorScheme take precedence over the resolved scheme.\n\nThe slot fields here mirror the inline-override fields on the in-document ColorScheme type (in opf.schema.json), so library entries and inline OPF overrides are interchangeable.",
+  "description": "Schema for color-scheme records. Each scheme is a named palette with the twelve PowerPoint color slots (six accents, two darks, two lights, plus hyperlink and followed-hyperlink), suitable for being mapped directly into OOXML theme XML. Documents reference a scheme from design.colorScheme (or design.colorScheme.id) and from a theme's colorScheme; slot overrides on design.colorScheme take precedence over the resolved scheme.\n\nThe slot fields here mirror the inline-override fields on the in-document ColorScheme type (in opf.schema.json), so records and inline OPF overrides are interchangeable.\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",
@@ -21,12 +21,12 @@
     "$schema": {
       "type": "string",
       "const": "https://openpresentation.org/schema/opf-color-scheme/v1",
-      "description": "Identifies this record as a color scheme in the openpresentation.org catalog."
+      "description": "Identifies a published record file as a colour scheme 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 color scheme. Lowercase kebab-case.",
+      "description": "The colour scheme'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": [
         "cool-horizon",
         "boost",
@@ -44,27 +44,6 @@
         "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/finding.schema.json

@@ -123,7 +123,7 @@
       "properties": {
         "value": { "type": ["string", "number", "boolean", "null"] },
         "label": { "type": "string" },
-        "origin": { "type": "string", "description": "Where the suggestion comes from: `schema`, `built-in`, `loaded`, `document` or `contract`." },
+        "origin": { "type": "string", "description": "Where the suggestion comes from: `schema`, `document` (a record the document embeds), `registered` (a catalog the host registered) or `contract`." },
         "definition": { "type": "string", "description": "Where the suggested record or constraint is defined." }
       }
     },

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

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-font-scheme/v1",
   "title": "Font Scheme",
-  "description": "Schema for font-scheme records in the pptx.gallery library. Each scheme pairs a major (heading) and minor (body) font family in the OOXML majorFont/minorFont sense, scoped to a target app (powerpoint or google-slides) and a language family (Latin, East Asian, or Complex Script). Font schemes are referenced from OPF documents via design.fontScheme or design.fontScheme.id; the engine resolves the reference against catalogs.fontSchemes (inline) → catalogs.fontSchemes.source → the default catalog at https://www.pptx.gallery/font-schemes. Role overrides on design.fontScheme (heading, body, accent, code), each a font family name, take precedence over the resolved scheme.",
+  "description": "Schema for font-scheme records. Each scheme pairs a major (heading) and minor (body) font family in the OOXML majorFont/minorFont sense, scoped to a target app (powerpoint or google-slides) and a language family (Latin, East Asian, or Complex Script). Documents reference a scheme from design.fontScheme (or design.fontScheme.id), from a theme's fontScheme and from a language's fontScheme / googleFontScheme. Role overrides on design.fontScheme (heading, body, accent, code), each a font family name, take precedence over the resolved scheme.\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",
@@ -15,12 +15,12 @@
     "$schema": {
       "type": "string",
       "const": "https://openpresentation.org/schema/opf-font-scheme/v1",
-      "description": "Identifies this record as a font scheme in the openpresentation.org catalog."
+      "description": "Identifies a published record file as a font scheme 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 font scheme. Lowercase kebab-case.",
+      "description": "The font scheme'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": [
         "aptos",
         "tenorite",
@@ -40,27 +40,6 @@
         "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.",
@@ -169,19 +148,9 @@
     },
     "languages": {
       "type": "array",
-      "items": {
-        "type": "string",
-        "pattern": "^[a-z][a-z0-9-]*$"
-      },
-      "description": "Optional list of languages catalog ids (see the languages catalog, https://www.pptx.gallery/languages) this scheme is curated for. Useful for picker UIs that group fonts by language coverage. As the design font scheme, an 'ea' or 'cs' scheme fills its script slot only when this list is empty or names the presentation language by id.",
-      "examples": [
-        [
-          "chinese-simplified",
-          "chinese-traditional",
-          "japanese",
-          "korean"
-        ]
-      ]
+      "items": { "type": "string", "pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{1,8})*$" },
+      "description": "Optional list of BCP-47 language tags this scheme is curated for. Useful for picker UIs that group fonts by language coverage. As the design font scheme, an 'ea' or 'cs' scheme fills its script slot only when this list is empty or names the presentation language: an entry matches a tag with the same language subtag (and the same script, when the entry names one).",
+      "examples": [["zh-Hans", "zh-Hant", "ja", "ko"]]
     },
     "textSample": {
       "type": "string",

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

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-language/v1",
   "title": "Language",
-  "description": "Schema for language records in the pptx.gallery library. Each record names a presentation language, carries a BCP-47 language tag, and pairs it with sensible default font schemes for PowerPoint and Google Slides output. Languages are referenced from OPF documents via language; the engine resolves the reference against catalogs.languages (inline) → catalogs.languages.source → the default catalog at https://www.pptx.gallery/languages. The presentation language field also accepts BCP-47 tags directly or inline Language objects for engine-aware language records that carry default-font hints.",
+  "description": "Schema for language records: display metadata for the language pickers of authoring tools (name, ISO code, the default font schemes a picker suggests). The document's 'language' is an engine vocabulary, a BCP-47 tag validated directly; engines never look a language record up, and their script, direction, OOXML tag and default script fonts come from spec/reference/engine-vocabularies.json. pptx.gallery publishes these records and @openpresentation/opf/catalog ships them as catalogDisplay.languages.",
   "type": "object",
   "required": [
     "$schema",
@@ -19,7 +19,7 @@
     "id": {
       "type": "string",
       "pattern": "^[a-z][a-z0-9-]*$",
-      "description": "Stable slug used by OPF documents to reference this language via language. Lowercase kebab-case.",
+      "description": "The record's id in the gallery's language catalog, lowercase kebab-case. Documents name a language by its BCP-47 tag ('bcp47'), never by this id.",
       "examples": [
         "english",
         "spanish",
@@ -37,27 +37,6 @@
         "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.",
@@ -83,23 +62,23 @@
     },
     "ooxmlLang": {
       "type": "string",
-      "description": "Curated culture tag for OOXML text-run language attributes (a:rPr/@lang, a:endParaRPr/@lang), in the language-[Script-]REGION form Office recognizes (e.g. 'ja-JP', 'ar-SA', 'ms-MY', 'nb-NO', 'fil-PH', 'zh-CN'). Engines emit it instead of 'bcp47' when the document names the language by catalog id or by a tag without a region; a region-bearing tag written by the author is emitted as written. Curated rather than inferred so output does not depend on the runtime's locale data.",
+      "description": "Curated culture tag for OOXML text-run language attributes (a:rPr/@lang, a:endParaRPr/@lang), in the language-[Script-]REGION form Office recognizes (e.g. 'ja-JP', 'ar-SA', 'ms-MY', 'nb-NO', 'fil-PH', 'zh-CN'). Engines emit it instead of 'bcp47' for a tag without a region; a region-bearing tag written by the author is emitted as written. Display metadata here: engines take the curated tag from their language vocabulary. Curated rather than inferred so output does not depend on the runtime's locale data.",
       "examples": ["en-US", "ja-JP", "ar-SA", "ms-MY", "nb-NO", "zh-CN"]
     },
     "direction": {
       "type": "string",
       "enum": ["ltr", "rtl"],
-      "description": "Base text direction for the language. When omitted, engines derive it from the script: Arabic (Arab), Hebrew (Hebr), Syriac (Syrc), Thaana (Thaa), N'Ko (Nkoo), Adlam (Adlm), Samaritan (Samr), Mandaic (Mand) and Hanifi Rohingya (Rohg) are right-to-left; every other script is left-to-right. Bundled language records state it explicitly.",
+      "description": "Base text direction for the language. When omitted, engines derive it from the script: Arabic (Arab), Hebrew (Hebr), Syriac (Syrc), Thaana (Thaa), N'Ko (Nkoo), Adlam (Adlm), Samaritan (Samr), Mandaic (Mand) and Hanifi Rohingya (Rohg) are right-to-left; every other script is left-to-right. The engine language vocabulary (spec/reference/engine-vocabularies.json) states it for the tags it knows.",
       "examples": ["ltr", "rtl"]
     },
     "script": {
       "type": "string",
-      "description": "ISO 15924 script code of the language's writing system. The script selects the OOXML font slot the language's text uses: East Asian scripts (Hans, Hant, Hani, Jpan, Kore, Hang, Hira, Kana, Bopo, Yiii) use the eastAsian slot; complex scripts (for example Arab, Hebr, Syrc, Thaa, Deva, Beng, Guru, Gujr, Orya, Taml, Telu, Knda, Mlym, Sinh, Thai, Laoo, Tibt, Mymr, Khmr, Mong) use the complexScript slot; every other script (Latn, Cyrl, Grek, Armn, Geor, Ethi, ...) uses the latin slot. When omitted, engines infer it from the BCP-47 tag. Bundled language records state it explicitly. See docs/programs/font-fidelity-everywhere/script-font-model.md.",
+      "description": "ISO 15924 script code of the language's writing system. The script selects the OOXML font slot the language's text uses: East Asian scripts (Hans, Hant, Hani, Jpan, Kore, Hang, Hira, Kana, Bopo, Yiii) use the eastAsian slot; complex scripts (for example Arab, Hebr, Syrc, Thaa, Deva, Beng, Guru, Gujr, Orya, Taml, Telu, Knda, Mlym, Sinh, Thai, Laoo, Tibt, Mymr, Khmr, Mong) use the complexScript slot; every other script (Latn, Cyrl, Grek, Armn, Geor, Ethi, ...) uses the latin slot. When omitted, engines infer it from the BCP-47 tag. The engine language vocabulary (spec/reference/engine-vocabularies.json) states it for the tags it knows. See docs/programs/font-fidelity-everywhere/script-font-model.md.",
       "examples": ["Latn", "Cyrl", "Grek", "Arab", "Hebr", "Jpan", "Kore", "Hans", "Hant", "Deva", "Thai"]
     },
     "fontScheme": {
       "type": "string",
-      "description": "Default font-scheme id for this language when targeting PowerPoint output. Resolves against catalogs.fontSchemes the same way design.fontScheme or design.fontScheme.id does. Its major/minor families fill the language's script slot (eastAsian or complexScript, chosen by 'script') unless the effective design font scheme sets that slot itself; the latin slot always follows the design font scheme.",
+      "description": "The font-scheme id a picker suggests for this language when targeting PowerPoint output. Display metadata: engines take a language's default script fonts from their own vocabulary.",
       "examples": [
         "aptos",
         "microsoft-yahei",
@@ -108,7 +87,7 @@
     },
     "googleFontScheme": {
       "type": "string",
-      "description": "Default font-scheme id for this language when targeting Google Slides output. Resolves against catalogs.fontSchemes the same way design.fontScheme or design.fontScheme.id does. Used in place of 'fontScheme' when resolving script fonts for Google Slides output.",
+      "description": "The font-scheme id a picker suggests for this language when targeting Google Slides output. Display metadata.",
       "examples": [
         "roboto",
         "noto-sans",

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

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-layout/v1",
   "title": "Slide Layout",
-  "description": "Schema for slide-layout records in the pptx.gallery library. Each record describes a semantic slide layout — what regions it exposes and what content kinds those regions are intended to hold. Layouts are referenced from OPF documents via Slide.layout; the engine resolves the reference against catalogs.layouts (inline) → catalogs.layouts.source → the default catalog at https://www.pptx.gallery/layouts. Free-form custom layout names that don't resolve through any catalog fall through to engine-defined layouts.",
+  "description": "Schema for slide-layout records. Each record describes a semantic slide layout: what regions it exposes, what content kinds those regions are intended to hold, how they are arranged (composition) and its design hints. Documents reference a layout from Slide.layout; a slide without a layout, or whose layout resolves nowhere, composes automatically.\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,17 +13,17 @@
     "$schema": {
       "type": "string",
       "const": "https://openpresentation.org/schema/opf-layout/v1",
-      "description": "Identifies this record as a slide layout in the openpresentation.org catalog."
+      "description": "Identifies a published record file as a layout 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 layout via Slide.layout. Lowercase kebab-case.",
+      "description": "The layout'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": [
         "title",
         "title-subtitle",
         "chart-1x",
-        "image-bleed"
+        "image-focus"
       ]
     },
     "name": {
@@ -36,27 +36,6 @@
         "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.",
@@ -74,7 +53,7 @@
     },
     "design": {
       "$ref": "#/$defs/DesignHints",
-      "description": "The layout's design hints, with the same keys and values as the deck's design and a slide's design (a slide overrides exactly what its layout sets, by the same name). An absent key means the layout has no opinion. Every key is applied from the record as the lowest-precedence default, per key: the slide's design, then the deck's design, then this record's design, then the engine default, so a layout value nobody overrides is honored without copying it anywhere (a layout's composition.mode still ranks above contentDirection; slideImage.position is the fallback position of a slide image the layout reserves). Composition, the renderer and the PPTX exporter all read the one result."
+      "description": "The layout's design hints, with the same keys and values as the deck's design and a slide's design (a slide overrides exactly what its layout sets, by the same name). An absent key means the layout has no opinion. Every key is applied from the record as the lowest-precedence default, per key: the slide's design, then the deck's design, then this record's design, then the engine default, so a layout value nobody overrides is honored without copying it anywhere (a layout's composition.mode still ranks above contentDirection). Composition, the renderer and the PPTX exporter all read the one result."
     },
     "placeholders": {
       "type": "array",
@@ -143,6 +122,18 @@
         "type"
       ],
       "description": "A single region inside a slide layout. Title, subtitle, and tag placeholders bind to the corresponding Slide fields; every other placeholder describes the content kind that region holds. The array order in the surrounding 'placeholders' field preserves layout region order.",
+      "if": {
+        "required": [
+          "placement"
+        ]
+      },
+      "then": {
+        "properties": {
+          "type": {
+            "const": "image"
+          }
+        }
+      },
       "properties": {
         "type": {
           "type": "string",
@@ -162,6 +153,40 @@
             "timeline"
           ],
           "description": "The content kind of the region. This is the one OPF content-kind vocabulary: the same words name a slide's payload fields (text, items, image, video, chart, table, code, metric, quote, timeline). 'title', 'subtitle' and 'tag' are the heading kinds and bind to Slide.title, Slide.subtitle and Slide.tag. 'text' holds text and bullets; 'list' holds items. 'image' is filled by an image payload and 'video' by a video payload. 'metric', 'quote', 'timeline', 'chart', 'table' and 'code' are filled by the payload of the same name; a metric region shows the metric payload with its optional label, description, unit, delta, trend and sentiment."
+        },
+        "placement": {
+          "$ref": "#/$defs/ImagePlacement",
+          "description": "Image placeholders only. Bleeds the slide's image for this region to one slide edge, as an image block's placement does: the n-th image placeholder places the slide's n-th top-level image (Slide.image or an image block in blocks) unless that block sets its own placement. The headings and the other content compose in the rest of the slide."
+        }
+      }
+    },
+    "ImagePlacement": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "edge"
+      ],
+      "description": "The same object as ImagePlacement in opf.schema.json: a band along one slide edge for the image, edge to edge, with the rest of the slide left to the headings and the other content.",
+      "properties": {
+        "edge": {
+          "type": "string",
+          "enum": [
+            "left",
+            "right",
+            "top",
+            "bottom"
+          ],
+          "description": "The slide edge the image bleeds to. In a right-to-left deck 'left' is the start side, drawn at the right."
+        },
+        "size": {
+          "type": "number",
+          "minimum": 0.1,
+          "maximum": 0.9,
+          "description": "Share of the slide width (left, right) or height (top, bottom) given to the band. Default 0.5."
+        },
+        "inset": {
+          "type": "boolean",
+          "description": "Draw the frame inside the slide padding on every side of the band instead of edge to edge. Default false."
         }
       }
     },
@@ -211,13 +236,14 @@
           ],
           "description": "Where the primary chart sits relative to the other body content. Composition applies it below the slide's and the deck's design.chartPrimary, with the semantics described there."
         },
-        "imageFill": {
+        "imageFit": {
           "type": "string",
           "enum": [
-            "crop",
-            "fit"
+            "cover",
+            "contain",
+            "stretch"
           ],
-          "description": "How images fill their region: 'crop' covers the region, 'fit' shows the whole image."
+          "description": "Default fit of the slide's image blocks: 'cover' fills the frame and crops around focus, 'contain' shows the whole picture, 'stretch' scales it to the frame."
         },
         "listBullet": {
           "type": "string",
@@ -226,27 +252,6 @@
             "image"
           ],
           "description": "Marker style of lists: 'character' draws the glyph, 'image' draws the deck's icon logo as a picture bullet."
-        },
-        "slideImage": {
-          "type": "object",
-          "additionalProperties": false,
-          "required": [
-            "position"
-          ],
-          "description": "A slide-level image region the layout reserves, separate from any content image. Its presence is what lets a deck-wide design.slideImage apply to slides on this layout. The image itself comes from the slide or the deck design.",
-          "properties": {
-            "position": {
-              "type": "string",
-              "enum": [
-                "background",
-                "top",
-                "bottom",
-                "left",
-                "right"
-              ],
-              "description": "Where the slide-level image sits relative to the content. 'background' is a full-bleed image behind the content; the other positions give the image a band along that edge. Used when the slide's or deck's design.slideImage gives no position."
-            }
-          }
         }
       }
     },