@openpresentation/opf 0.10.1 → 0.11.0

package/dist/spec/catalogs/narratives/venture-pitch.json

@@ -26,84 +26,84 @@
       "name": "Opening",
       "instructions": "Establish identity",
       "slideType": "text",
-      "layoutHint": "text-1x-left"
+      "layoutHint": "text-1x"
     },
     {
       "id": "purpose",
       "name": "Purpose",
       "instructions": "State your mission",
       "slideType": "text",
-      "layoutHint": "text-1x-left"
+      "layoutHint": "text-1x"
     },
     {
       "id": "problem",
       "name": "Problem",
       "instructions": "Present the challenge",
       "slideType": "text",
-      "layoutHint": "text-1x-left"
+      "layoutHint": "text-1x"
     },
     {
       "id": "solution",
       "name": "Solution",
       "instructions": "Propose your idea",
       "slideType": "text",
-      "layoutHint": "text-1x-left"
+      "layoutHint": "text-1x"
     },
     {
       "id": "why-now",
       "name": "Why Now",
       "instructions": "Explain timing importance",
       "slideType": "text",
-      "layoutHint": "text-1x-left"
+      "layoutHint": "text-1x"
     },
     {
       "id": "market-size",
       "name": "Market Size",
       "instructions": "Demonstrate potential",
       "slideType": "text",
-      "layoutHint": "text-1x-left"
+      "layoutHint": "text-1x"
     },
     {
       "id": "competition",
       "name": "Competition",
       "instructions": "Analyze competitive landscape",
       "slideType": "text",
-      "layoutHint": "text-1x-left"
+      "layoutHint": "text-1x"
     },
     {
       "id": "product",
       "name": "Product",
       "instructions": "Showcase features/benefits",
       "slideType": "text",
-      "layoutHint": "text-1x-left"
+      "layoutHint": "text-1x"
     },
     {
       "id": "business-model",
       "name": "Business Model",
       "instructions": "Detail revenue streams",
       "slideType": "text",
-      "layoutHint": "text-1x-left"
+      "layoutHint": "text-1x"
     },
     {
       "id": "team",
       "name": "Team",
       "instructions": "Highlight key members",
       "slideType": "text",
-      "layoutHint": "text-1x-left"
+      "layoutHint": "text-1x"
     },
     {
       "id": "financials",
       "name": "Financials",
       "instructions": "Show projections/needs",
       "slideType": "text",
-      "layoutHint": "text-1x-left"
+      "layoutHint": "text-1x"
     },
     {
       "id": "closing",
       "name": "Closing",
       "instructions": "Reinforce brand",
       "slideType": "text",
-      "layoutHint": "text-1x-left"
+      "layoutHint": "text-1x"
     }
   ]
 }

package/dist/spec/catalogs/narratives/weekly-progress.json

@@ -23,7 +23,7 @@
       "id": "opening",
       "name": "Opening",
       "description": "Open with the initiative name, the date, and the one-line headline for the week. Frame the meeting in fifteen seconds so the rest of the time is content.",
-      "layoutHint": "title-left",
+      "layoutHint": "title",
       "instructions": "Initiative name & date",
       "slideType": "text"
     },
@@ -33,7 +33,7 @@
       "description": "State what the team set out to do this week. Specific, measurable. The audience should be able to read this slide alone and know what 'on track' would mean.",
       "instructions": "Set the expectations",
       "slideType": "text",
-      "layoutHint": "text-1x-left"
+      "layoutHint": "text-1x"
     },
     {
       "id": "achievements",
@@ -41,7 +41,7 @@
       "description": "Celebrate the week's wins. Concrete, attributable, dated. Brevity here — the meeting is for what's next, not a victory lap.",
       "instructions": "Celebrate success",
       "slideType": "text",
-      "layoutHint": "text-1x-left"
+      "layoutHint": "text-1x"
     },
     {
       "id": "overall-progress",
@@ -49,7 +49,7 @@
       "description": "Evaluate performance against the objectives. Use a simple status indicator (green/yellow/red) plus the leading metric. Help the audience scan the state in seconds.",
       "instructions": "Evaluate performance",
       "slideType": "text",
-      "layoutHint": "text-1x-left"
+      "layoutHint": "text-1x"
     },
     {
       "id": "challenges",
@@ -57,7 +57,7 @@
       "description": "Address what's hard right now: blockers, slipping items, surfaced risks. Tie each challenge to either an owner working it or a discussion you want this week.",
       "instructions": "Address difficulties",
       "slideType": "text",
-      "layoutHint": "text-1x-left"
+      "layoutHint": "text-1x"
     },
     {
       "id": "opportunities-for-improvement",
@@ -65,7 +65,7 @@
       "description": "Surface where the team can level up. Process tweaks, tooling needs, ways of working. Improvement opportunities should feel like seeds, not corrections.",
       "instructions": "Seek growth",
       "slideType": "text",
-      "layoutHint": "text-1x-left"
+      "layoutHint": "text-1x"
     },
     {
       "id": "highlights-recognition",
@@ -73,7 +73,7 @@
       "description": "Recognize specific contributions by name. Recognition belongs in the deck, not just in the meeting — written acknowledgment travels further than verbal.",
       "instructions": "Appreciate efforts",
       "slideType": "text",
-      "layoutHint": "text-1x-left"
+      "layoutHint": "text-1x"
     },
     {
       "id": "goals-next-week",
@@ -81,7 +81,7 @@
       "description": "Plan the week ahead with three to five specific goals. Each should be small enough to finish, large enough to matter, and clearly owned.",
       "instructions": "Plan ahead",
       "slideType": "text",
-      "layoutHint": "text-1x-left"
+      "layoutHint": "text-1x"
     },
     {
       "id": "discussion-feedback",
@@ -89,13 +89,13 @@
       "description": "Open the floor with two or three prompts — decisions you need, opinions you want, blockers you'd like cleared. End the recap actively.",
       "instructions": "Encourage input",
       "slideType": "text",
-      "layoutHint": "text-1x-left"
+      "layoutHint": "text-1x"
     },
     {
       "id": "conclusion",
       "name": "Conclusion",
       "description": "Close with one line that motivates the team into the next week. Echo the headline so the meeting feels closed.",
-      "layoutHint": "title-left",
+      "layoutHint": "title",
       "instructions": "Recap & motivate",
       "slideType": "text"
     }

package/dist/spec/openapi.yaml

@@ -493,6 +493,10 @@ components:
           type: object
           additionalProperties: true
           description: Optional design system (theme, colorScheme, fontScheme, dimensions, background, logo, header, footer, etc).
+        variables:
+          type: object
+          additionalProperties: true
+          description: Optional named color variables referenced from content color fields as `var:<id>` strings.
         assets:
           type: object
           additionalProperties: true
@@ -719,6 +723,7 @@ components:
           type: string
         color:
           type: string
+          description: Hex color, color-scheme slot/role name, or `var:<id>` variable reference (ColorRef in the canonical schema).
         alignment:
           type: string
 

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.",
+  "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.",
   "type": "object",
   "required": ["slides"],
   "additionalProperties": false,
@@ -176,6 +176,10 @@
       "$ref": "#/$defs/Design",
       "description": "Optional design system covering theme, color scheme, font scheme, dimensions, background, logo, watermark, header, and footer applied to the deck. When omitted, engines use their default design configuration."
     },
+    "variables": {
+      "$ref": "#/$defs/Variables",
+      "description": "Optional named color variables for values the deck uses in more than one place or wants to name for intent (e.g. a risk red, a brand highlight). Content color fields reference entries as 'var:<id>' strings. Variables complement the color scheme: scheme slots and roles stay the primary vocabulary; variables cover deck-specific named colors that have no scheme slot."
+    },
     "narrative": {
       "oneOf": [
         { "type": "string" },
@@ -1223,6 +1227,63 @@
       "description": "Hex color shorthand accepted by selected string fields.",
       "examples": ["#fff", "#ffff00", "#0F172AFF"]
     },
+    "ColorRef": {
+      "anyOf": [
+        { "$ref": "#/$defs/HexColor" },
+        {
+          "type": "string",
+          "enum": [
+            "accent1", "accent2", "accent3", "accent4", "accent5", "accent6",
+            "dark1", "dark2", "light1", "light2", "hyperlink", "followedHyperlink",
+            "primary", "secondary", "accent", "background", "surface", "text", "textSecondary"
+          ]
+        },
+        {
+          "type": "string",
+          "pattern": "^var:[a-z][a-z0-9-]*$"
+        }
+      ],
+      "description": "A color value or reference, enforced on styled table cell fill and text colors and on cell border colors. Three forms:\n- Literal hex: '#RGB', '#RRGGBB', or '#RRGGBBAA'.\n- Color-scheme name, resolved through the effective color scheme after design resolution: an OOXML slot ('accent1'-'accent6', 'dark1', 'dark2', 'light1', 'light2', 'hyperlink', 'followedHyperlink') or an abstract role ('primary', 'secondary', 'accent', 'background', 'surface', 'text', 'textSecondary'). Roles resolve through the same role-to-slot mapping engines already apply to color schemes.\n- Variable reference: 'var:<id>' into the top-level variables map.\n\nNames keep content theme-portable: re-theming the deck updates every named reference, where a literal hex stays frozen. Unknown 'var:' ids produce a validation warning, never an error, and engines fall back to their default text color. TextRun.color documents the same three forms but remains an open string so imported decks with unrecognized run colors stay valid; validators warn there instead of erroring.",
+      "examples": ["#0F4C81", "accent2", "text", "var:risk"]
+    },
+    "Variables": {
+      "type": "object",
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9-]*$"
+      },
+      "additionalProperties": { "$ref": "#/$defs/Variable" },
+      "description": "Named color variables, keyed by stable kebab-case id. Content color fields reference entries as 'var:<id>' strings. Each value is a hex string shorthand or a Variable object.",
+      "examples": [
+        { "risk": "#B42318", "highlight": { "type": "color", "value": "#0F4C81", "description": "Brand highlight for emphasized runs." } }
+      ]
+    },
+    "Variable": {
+      "oneOf": [
+        { "$ref": "#/$defs/HexColor" },
+        {
+          "type": "object",
+          "required": ["type", "value"],
+          "additionalProperties": false,
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": ["color"],
+              "description": "Variable kind. Only 'color' is defined today; other kinds may be added when content surfaces exist to consume them."
+            },
+            "value": {
+              "$ref": "#/$defs/HexColor",
+              "description": "Hex color this variable resolves to."
+            },
+            "description": {
+              "type": "string",
+              "description": "Optional prose describing what the variable is for, surfaced by pickers and agents."
+            }
+          }
+        }
+      ],
+      "description": "A single named variable. A hex string is shorthand for { \"type\": \"color\", \"value\": value }.",
+      "examples": ["#B42318", { "type": "color", "value": "#B42318", "description": "Risk emphasis." }]
+    },
     "BackgroundShortcut": {
       "oneOf": [
         { "$ref": "#/$defs/ThemeBackgroundSlot" },
@@ -1811,6 +1872,10 @@
         },
         "composition": {
           "$ref": "#/$defs/Composition"
+        },
+        "extensions": {
+          "type": "object",
+          "description": "Custom data passthrough for agent workflows at slide scope; ignored by the engine but preserved across read/write round-trips. Use for review state, generation provenance, or authoring conventions such as { \"authoring\": { \"locked\": true } }."
         }
       }
     },
@@ -1819,6 +1884,15 @@
       "description": "A content leaf or recursively composed group. A group contains blocks and optional composition; it cannot mix blocks with leaf payload fields. Groups may nest up to 32 levels.",
       "additionalProperties": false,
       "properties": {
+        "id": {
+          "type": "string",
+          "description": "Optional stable identifier for this payload, unique among slide and payload ids in the document. Use when another system needs to address the payload across edits — patch-style agent edits, comments, review state, or generation provenance. Identity survives reordering where array indexes do not.",
+          "examples": ["kpi-adoption", "churn-quote"]
+        },
+        "extensions": {
+          "type": "object",
+          "description": "Custom data passthrough for agent workflows at payload scope; ignored by the engine but preserved across read/write round-trips."
+        },
         "type": {
           "type": "string",
           "enum": ["text", "list", "image", "chart", "table", "video", "code", "metric", "quote", "timeline",
@@ -2427,8 +2501,8 @@
             },
             "color": {
               "type": "string",
-              "description": "Run text color as a hex string.",
-              "examples": ["#0F172A", "#1E40AF"]
+              "description": "Run text color. Documented forms: a hex string ('#RGB', '#RRGGBB', '#RRGGBBAA'), a color-scheme slot or role name resolved through the effective color scheme ('accent2', 'text'), or a 'var:<id>' reference into the top-level variables map. Prefer names over hex so runs survive re-theming. Any other string stays schema-valid so imported decks keep validating: validators warn and renderers fall back to the theme text color.",
+              "examples": ["#0F172A", "accent2", "var:risk"]
             },
             "fontSize": {
               "type": "number",
@@ -2676,14 +2750,12 @@
       "additionalProperties": false,
       "properties": {
         "fill": {
-          "type": "string",
-          "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
-          "description": "Explicit RGB or RGBA color. Eight-digit colors include alpha; #00000000 is transparent."
+          "$ref": "#/$defs/ColorRef",
+          "description": "Cell background: a hex color, a color-scheme slot or role name, or a 'var:<id>' variable reference. Eight-digit hex colors include alpha; #00000000 is transparent."
         },
         "color": {
-          "type": "string",
-          "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
-          "description": "Default text color, overridden by individual rich run colors."
+          "$ref": "#/$defs/ColorRef",
+          "description": "Default text color, overridden by individual rich run colors. Accepts a hex color, a color-scheme slot or role name, or a 'var:<id>' variable reference."
         },
         "align": {
           "type": "string",
@@ -2764,9 +2836,8 @@
       ],
       "properties": {
         "color": {
-          "type": "string",
-          "pattern": "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
-          "description": "Explicit RGB or RGBA color. Eight-digit colors include alpha; #00000000 is transparent."
+          "$ref": "#/$defs/ColorRef",
+          "description": "Border color: a hex color, a color-scheme slot or role name, or a 'var:<id>' variable reference. Eight-digit hex colors include alpha; #00000000 is transparent."
         },
         "width": {
           "type": "number",

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-export { P as Presentation } from './presentation-BMTdX6O1.js';
-export { A as Audience, c as CatalogKind, e as ChartType, f as ColorScheme, F as FontScheme, L as Language, g as Layout, N as Narrative, P as Purpose, S as SocialPlatform, T as Theme, h as Tone } from './catalogs-DoVmvDr7.js';
-export { a as SchemaName } from './schemas-BYe5y8-i.js';
+export { P as Presentation } from './presentation-Ct42Mitb.js';
+export { A as Audience, C as CatalogKind, e as ChartType, f as ColorScheme, F as FontScheme, L as Language, g as Layout, N as Narrative, P as Purpose, S as SocialPlatform, T as Theme, h as Tone } from './catalogs-atkOF4Vy.js';
+export { a as SchemaName } from './schemas-CiVmUT2p.js';
 export { ValidationIssue, ValidationResult } from './validator.js';

package/dist/validator.d.ts

@@ -1,6 +1,8 @@
-import { P as Presentation } from './presentation-BMTdX6O1.js';
-import { c as CatalogKind } from './catalogs-DoVmvDr7.js';
-import { a as SchemaName, m as JsonSchema } from './schemas-BYe5y8-i.js';
+import { P as Presentation } from './presentation-Ct42Mitb.js';
+import { C as CatalogKind } from './catalogs-atkOF4Vy.js';
+import { a as SchemaName, m as JsonSchema } from './schemas-CiVmUT2p.js';
+
+declare const promotedRegionKeys: readonly ["left", "center", "right", "left+center", "center+right", "left+center+right", "top", "middle", "bottom", "top+middle", "middle+bottom", "top+middle+bottom", "top:left", "top:center", "top:right", "top:left+center", "top:center+right", "top:left+center+right", "middle:left", "middle:center", "middle:right", "middle:left+center", "middle:center+right", "middle:left+center+right", "bottom:left", "bottom:center", "bottom:right", "bottom:left+center", "bottom:center+right", "bottom:left+center+right", "top+middle:left", "top+middle:center", "top+middle:right", "top+middle:left+center", "top+middle:center+right", "top+middle:left+center+right", "middle+bottom:left", "middle+bottom:center", "middle+bottom:right", "middle+bottom:left+center", "middle+bottom:center+right", "middle+bottom:left+center+right", "top+middle+bottom:left", "top+middle+bottom:center", "top+middle+bottom:right", "top+middle+bottom:left+center", "top+middle+bottom:center+right", "top+middle+bottom:left+center+right"];
 
 interface ValidationIssue {
     path: string;
@@ -23,6 +25,7 @@ declare class OPFValidationError extends Error {
     readonly result: ValidationResult;
     constructor(result: ValidationResult);
 }
+
 declare function validate(value: unknown, schemaOrKind?: SchemaOrKind): ValidationResult;
 declare function assertValid<T = unknown>(value: T, schemaOrKind?: SchemaOrKind): T;
 declare function validatePresentation(value: unknown): ValidationResult;
@@ -30,4 +33,4 @@ declare function assertValidPresentation(value: unknown): asserts value is Prese
 declare function validateCatalogRecord(kind: CatalogKind, value: unknown): ValidationResult;
 declare function assertValidCatalogRecord(kind: CatalogKind, value: unknown): void;
 
-export { OPFValidationError, type SchemaOrKind, type ValidationIssue, type ValidationResult, assertValid, assertValidCatalogRecord, assertValidPresentation, validate, validateCatalogRecord, validatePresentation };
+export { OPFValidationError, type SchemaOrKind, type ValidationIssue, type ValidationResult, assertValid, assertValidCatalogRecord, assertValidPresentation, promotedRegionKeys, validate, validateCatalogRecord, validatePresentation };

package/dist/validator.js

@@ -1,4 +1,4 @@
-export { OPFValidationError, assertValid, assertValidCatalogRecord, assertValidPresentation, validate, validateCatalogRecord, validatePresentation } from './chunk-ZIL7MGZU.js';
-import './chunk-PQJRDNA6.js';
-import './chunk-D3GQIREP.js';
-import './chunk-TU7I3KSB.js';
+export { OPFValidationError, assertValid, assertValidCatalogRecord, assertValidPresentation, promotedRegionKeys, validate, validateCatalogRecord, validatePresentation } from './chunk-CHKJ4QHQ.js';
+import './chunk-FTWNWFIV.js';
+import './chunk-GN52EE3P.js';
+import './chunk-6FU2KICU.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpresentation/opf",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "Canonical Open Presentation Format schemas, catalogs, TypeScript types, and local validation.",
   "license": "MIT",
   "author": "Open Presentation",