@openpresentation/opf 0.13.0 → 0.15.1

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.",
@@ -72,157 +51,14 @@
         "Two equal-width columns under a left-aligned slide title. Use when comparing two ideas, before/after pairs, or paired text + image content."
       ]
     },
-    "contentType": {
-      "type": "string",
-      "enum": [
-        "Title",
-        "Text",
-        "List",
-        "Image",
-        "Number",
-        "Metric",
-        "Chart",
-        "Table",
-        "Code",
-        "Video",
-        "Quote",
-        "Timeline"
-      ],
-      "description": "Primary kind of content the layout holds. Drives pickers and AI placement decisions. Metric is the canonical numeric/KPI category; Number remains an accepted legacy label."
-    },
-    "contentMultiple": {
-      "type": "string",
-      "enum": [
-        "None",
-        "1x",
-        "2x",
-        "3x",
-        "4x",
-        "5x",
-        "6x"
-      ],
-      "description": "How many parallel content blocks the layout exposes ('2x' = two-column, '3x' = three-up, etc.)."
-    },
-    "contentAlignment": {
-      "type": "string",
-      "enum": [
-        "None",
-        "Left",
-        "Center"
-      ],
-      "description": "Default horizontal alignment of the content area."
-    },
-    "contentBox": {
-      "type": "boolean",
-      "description": "Whether the content area is rendered inside a visible box / card.",
-      "examples": [
-        false,
-        true
-      ]
-    },
-    "contentTypeChartPrimary": {
-      "type": "string",
-      "enum": [
-        "None",
-        "Top",
-        "Bottom",
-        "Left",
-        "Right"
-      ],
-      "description": "For chart layouts, where the primary chart sits relative to the rest of the content."
-    },
-    "contentTypeImageFill": {
-      "type": "string",
-      "enum": [
-        "None",
-        "Crop",
-        "Fit"
-      ],
-      "description": "For image layouts, how the image fills its slot."
-    },
-    "contentTypeListBullet": {
-      "type": "string",
-      "enum": [
-        "None",
-        "Character",
-        "Image"
-      ],
-      "description": "For list layouts, how bullets are rendered."
-    },
-    "contentTypeListHeading": {
-      "type": "boolean",
-      "description": "For list layouts, whether each list item carries a heading.",
-      "examples": [
-        false,
-        true
-      ]
-    },
-    "slideTag": {
-      "type": "boolean",
-      "description": "Whether the layout includes a small slide-level tag / label region above or near the title.",
-      "examples": [
-        false,
-        true
-      ]
-    },
-    "slideTitle": {
-      "type": "boolean",
-      "description": "Whether the layout includes a slide title region.",
-      "examples": [
-        true,
-        false
-      ]
-    },
-    "slideSubtitle": {
-      "type": "boolean",
-      "description": "Whether the layout includes a slide-level subtitle or supporting-description region. When placeholders is present, this is true exactly when the layout exposes a placeholder with type 'subtitle'.",
-      "examples": [
-        false,
-        true
-      ]
-    },
-    "slideTitleAlignment": {
-      "type": "string",
-      "enum": [
-        "None",
-        "Left",
-        "Center"
-      ],
-      "description": "Horizontal alignment of the slide title region."
-    },
-    "slideImage": {
-      "type": "boolean",
-      "description": "Whether the layout includes a dedicated slide-level image region (separate from any content image).",
-      "examples": [
-        false,
-        true
-      ]
-    },
-    "slideImageAlignment": {
-      "type": "string",
-      "enum": [
-        "None",
-        "Top",
-        "Bottom",
-        "Left",
-        "Right",
-        "Background"
-      ],
-      "description": "Where the slide-level image sits relative to the content."
-    },
-    "slideLayoutDirection": {
-      "type": "string",
-      "enum": [
-        "None",
-        "Horizontal",
-        "Vertical"
-      ],
-      "description": "Axis along which the layout's primary regions are arranged."
+    "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). Composition, the renderer and the PPTX exporter all read the one result."
     },
     "placeholders": {
       "type": "array",
       "items": { "$ref": "#/$defs/Placeholder" },
-      "description": "Ordered regions the layout exposes. The engine fills 'title', 'subtitle', and 'tag' placeholders from Slide.title, Slide.subtitle, and Slide.tag. Other placeholders are content-kind hints for renderers and pickers. Slide content itself lives either in root payload fields or promoted region keys on Slide. Chrome — slide number, footer, date — is not included here; it is owned by Design.header / Design.footer."
+      "description": "Ordered regions the layout exposes. This is the single source of truth for what the layout holds: the content kind, the number of body regions and whether it has a title, subtitle or tag are derived from it (layoutContent in @openpresentation/opf), never stored separately. The engine fills 'title', 'subtitle' and 'tag' placeholders from Slide.title, Slide.subtitle and Slide.tag. The other placeholders are content-kind regions that composition uses to size the body and that pickers use to match layouts. Slide content itself lives either in root payload fields or promoted region keys on Slide. Chrome (slide number, footer, date) is not included here; it is owned by Design.header / Design.footer."
     },
     "tags": {
       "type": "array",
@@ -254,7 +90,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/layouts/title-left.png"
+            "https://example.com/layouts/title-subtitle.png"
           ]
         },
         "thumbnailSrc": {
@@ -262,7 +98,7 @@
           "format": "uri",
           "description": "Smaller thumbnail preview suited to dense grid views.",
           "examples": [
-            "https://www.pptx.gallery/layouts/title-left.thumbnail.png"
+            "https://example.com/layouts/title-subtitle.thumbnail.png"
           ]
         },
         "vectorSrc": {
@@ -270,7 +106,7 @@
           "format": "uri",
           "description": "SVG / vector preview for crisp scaling at any size.",
           "examples": [
-            "https://www.pptx.gallery/layouts/title-left.svg"
+            "https://www.pptx.gallery/layout-previews/title-subtitle.svg"
           ]
         }
       }
@@ -285,7 +121,19 @@
       "required": [
         "type"
       ],
-      "description": "A single region inside a slide layout. Title, subtitle, and tag placeholders bind to the corresponding Slide fields; other placeholders describe the intended content kind for that region. The array order in the surrounding 'placeholders' field preserves layout region order.",
+      "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",
@@ -294,18 +142,116 @@
             "subtitle",
             "tag",
             "text",
-            "metric",
-            "quote",
-            "timeline",
             "list",
+            "image",
+            "video",
             "chart",
-            "picture",
             "table",
-            "media",
-            "diagram",
-            "code"
+            "code",
+            "metric",
+            "quote",
+            "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."
+        }
+      }
+    },
+    "DesignHints": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Design hints a layout carries. The keys and lowercase values are those of the deck's design and a slide's design in opf.schema.json (Design), so a slide overrides a layout by the same name and layout.design can be copied into slide.design unchanged. An absent key means the layout has no opinion. Only the keys the layout sets are stored. scripts/check-spec-integrity.mjs verifies that every key here has the same type and values as its Design counterpart.",
+      "properties": {
+        "titleAlignment": {
+          "type": "string",
+          "enum": [
+            "left",
+            "center",
+            "right"
+          ],
+          "description": "Horizontal alignment of the title placeholder."
+        },
+        "contentAlignment": {
+          "type": "string",
+          "enum": [
+            "left",
+            "center",
+            "right"
+          ],
+          "description": "Horizontal alignment of the body regions."
+        },
+        "contentBox": {
+          "type": "boolean",
+          "description": "Whether the body regions are drawn inside a visible card or surface."
+        },
+        "contentDirection": {
+          "type": "string",
+          "enum": [
+            "horizontal",
+            "vertical"
+          ],
+          "description": "Axis along which parallel body content is arranged: 'vertical' is a column, 'horizontal' a row. Composition applies it when neither the slide nor this layout's composition sets a mode, below the slide's and the deck's design.contentDirection and above automatic selection."
+        },
+        "chartPrimary": {
+          "type": "string",
+          "enum": [
+            "none",
+            "top",
+            "bottom",
+            "left",
+            "right"
+          ],
+          "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."
+        },
+        "imageFit": {
+          "type": "string",
+          "enum": [
+            "cover",
+            "contain",
+            "stretch"
+          ],
+          "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",
+          "enum": [
+            "character",
+            "image"
           ],
-          "description": "OPF placeholder kind. 'text' and 'list' are flexible textual content regions. 'metric' is a numeric/KPI content region filled by a metric payload, including its optional label, description, unit, delta, and trend. The named kinds describe a specific content role used by pickers, AI generation, and engine defaulting. 'picture' and legacy 'diagram' use image payloads; 'media' uses video. Quote and timeline use their corresponding payload fields."
+          "description": "Marker style of lists: 'character' draws the glyph, 'image' draws the deck's icon logo as a picture bullet."
         }
       }
     },

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

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-narrative/v1",
   "title": "Narrative Template",
-  "description": "Schema for narrative template files in the openpresentation.org catalog. Each template describes a named story arc (e.g. 'problem-solution', 'scqa') as an ordered list of beats. Templates are referenced from OPF documents via narrative — either as a bare id string (e.g. 'classic-story') or as an inline object whose shape matches this schema (sans '$schema').",
+  "description": "Schema for narrative records. A narrative is a plan: a named story arc (e.g. 'problem-solution', 'scqa') as an ordered list of beats, each saying what its slide must do. A document points at one with the string 'narrative' and links its slides to beats with 'slides[].beat'; a narrative the document defines itself is a record in catalogs.custom.narratives. Core validate warns about a 'slides[].beat' id the resolved narrative does not define (opf/unknown-beat) and about a root 'duration' outside this record's 'duration' range (opf/duration-outside-narrative), and reports a beat no slide references (opf/unused-beat).\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,38 +13,18 @@
   "properties": {
     "$schema": {
       "type": "string",
-      "const": "https://openpresentation.org/schema/opf-narrative/v1"
+      "const": "https://openpresentation.org/schema/opf-narrative/v1",
+      "description": "Identifies a published record file as a narrative 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 template, e.g. 'problem-solution'. Lowercase kebab-case."
+      "description": "The narrative'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."
     },
     "name": {
       "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."
@@ -63,17 +43,20 @@
       },
       "description": "Audiences this narrative works well for, e.g. ['executive', 'investor', 'customer']."
     },
-    "durationRange": {
+    "duration": {
       "type": "object",
-      "description": "Typical talk-length window this narrative suits.",
+      "additionalProperties": false,
+      "description": "Typical talk length this narrative suits, as a range in minutes. A deck's own target is the root 'duration' (one number); core validate warns when that target lies outside this range, and when 'min' is greater than 'max'.",
       "properties": {
-        "minMinutes": {
+        "min": {
           "type": "number",
-          "exclusiveMinimum": 0
+          "exclusiveMinimum": 0,
+          "description": "Shortest talk length, in minutes, this narrative suits."
         },
-        "maxMinutes": {
+        "max": {
           "type": "number",
-          "exclusiveMinimum": 0
+          "exclusiveMinimum": 0,
+          "description": "Longest talk length, in minutes, this narrative suits."
         }
       }
     },
@@ -126,7 +109,7 @@
   "$defs": {
     "Beat": {
       "type": "object",
-      "description": "A single narrative beat — a labeled segment of the story arc with a specific dramatic purpose. Mirrors the NarrativeBeat definition in opf.schema.json so library entries and inline OPF beats are interchangeable.",
+      "description": "A single narrative beat — a labeled segment of the story arc with a specific dramatic purpose. One beat is one slide: 'type' is that slide's Slide.type and 'layout' is its Slide.layout, so a planner copies them straight into a skeleton deck. Split a heavy beat into several beats rather than giving it several slides.",
       "required": [
         "id",
         "name"
@@ -171,36 +154,25 @@
             "Inspire & conclude"
           ]
         },
-        "slideCount": {
-          "type": "integer",
-          "minimum": 1,
-          "description": "Optional explicit slide count for this beat. Defaults to 1 when omitted; values >1 are reserved for beats that intentionally span multiple slides. Prefer decomposing a heavy beat into multiple beats over setting a high slideCount. The validator emits a warning if the deck's actual count differs significantly.",
-          "examples": [
-            1,
-            2,
-            3
-          ]
-        },
-        "slideType": {
+        "type": {
           "type": "string",
           "enum": [
             "text",
             "list",
             "image",
-            "shape",
+            "video",
             "chart",
             "table",
-            "video",
             "code",
             "metric",
             "quote",
             "timeline"
           ],
-          "description": "Default content kind for the beat's slide. Uses ContentPayload.type names to help engines choose a layout. The legacy shape value is retained for compatibility and requests an image representation; it is not a native ContentPayload type."
+          "description": "Default content kind for the beat's slide: the same values as Slide.type. Helps engines and planners choose a layout when only the beat is known."
         },
-        "layoutHint": {
+        "layout": {
           "type": "string",
-          "description": "Suggested layout id for the beat's opening slide, e.g. 'section-divider', 'title-slide', 'text-left'. Resolves the same way as Slide.layout — against catalogs.layouts and the default catalog at https://www.pptx.gallery/layouts.",
+          "description": "Suggested layout id for the beat's slide, e.g. 'section-divider', 'title-slide', 'text-left'. Resolves the same way as Slide.layout — against catalogs.layouts and the default catalog at https://www.pptx.gallery/layouts.",
           "examples": [
             "section-divider",
             "title-slide",
@@ -214,7 +186,7 @@
           "items": {
             "type": "string"
           },
-          "description": "Optional speaker or thinking cues attached to the beat. Surfaced in presenter notes.",
+          "description": "Optional speaker or thinking cues for the beat: questions the slide should answer. A planner or author turns them into the slide's notes; no engine copies them there on its own.",
           "examples": [
             [
               "What pain is the audience feeling right now?",