@openpresentation/opf 0.17.0 → 0.18.3

package/README.md

@@ -49,10 +49,10 @@ console.log(Object.keys(saved.catalogs.default.themes)); // ["classic"]
 console.log(Object.keys(defaultCatalog.tones));
 ```
 
-In Node, `@openpresentation/opf/node` adds files: `convert` turns one file into another (a deck to PDF, PNG, SVG or PPTX, a PowerPoint file to a deck, one deck form to another, or bytes with no output path), `open` reads a deck file or imports a `.pptx`, and `save` writes one. It re-exports the rest of core, so one namespace import covers an application:
+In Node (and Bun and Deno), the root adds files: `convert` turns one file into another (a deck to PDF, PNG, SVG or PPTX, a PowerPoint file to a deck, one deck form to another, or bytes with no output path), `open` reads a deck file or imports a `.pptx`, and `save` writes one. The same import works in every runtime, so one namespace import covers an application:
 
 ```ts
-import * as opf from "@openpresentation/opf/node";
+import * as opf from "@openpresentation/opf";
 
 await opf.convert("deck.opf.md", "deck.pdf");
 const deck = await opf.open("deck.opf.md");
@@ -61,7 +61,7 @@ await opf.save(deck, "deck.opf.md");
 const { files } = await opf.convert(deck, { format: "pptx" }); // bytes, nothing written
 ```
 
-Drawing and PowerPoint go through the optional peers `@openpresentation/opf-render` and `@openpresentation/opf-pptx`, which `/node` loads the first time a call needs them; npm does not install them for you. `/node` is the only Node-only entry: the root and every other subpath run in a browser. See [OPF files in Node](../../docs/node.md).
+Drawing and PowerPoint go through the optional peers `@openpresentation/opf-render` and `@openpresentation/opf-pptx`, which core loads the first time a call needs them; npm does not install them for you. The root has conditional exports (OPF 0.18 removed `/node`): `node`, `bun` and `deno` get this full build, and `browser`, `worker`, `workerd` and `default` get a browser-safe build with the same names and the same types, where `open`, `save` and `convert` reject with `OPFApiError` code `node-only`. Every other subpath runs in a browser. `parseSlideSelection(3 | "1-3" | [1, 3], total)` reads slide selections in both. See [OPF files in Node](../../docs/node.md).
 
 Use focused imports when you only need one surface:
 
@@ -91,7 +91,7 @@ The layout engine's names are not on the root. `composeSlide`, `fitText`, `layou
 
 ### Reading and writing a deck in any form
 
-`parse(text, { format, filename, catalogs })` and `stringify(presentation, { format | filename })` (the root and `@openpresentation/opf/deck`) read and write a deck as JSON (canonical), YAML or Markdown. The format is the `format` option, else the file name (`.opf.md` is Markdown, `.yaml` and `.yml` are YAML, anything else JSON; a plain `.md` is not a deck), and never the content. `parse` returns the presentation and throws `OPFValidationError` for a syntax, schema or reference error; the error's `report.findings` are located by line and column in the text (`opf/json-syntax`, `yaml/<rule>` or `markdown/<rule>` for syntax errors). Warnings do not throw: `validate(text)` returns the full report. Both run in a browser; files are `/node`'s job (below).
+`parse(text, { format, filename, catalogs })` and `stringify(presentation, { format | filename })` (the root and `@openpresentation/opf/deck`) read and write a deck as JSON (canonical), YAML or Markdown. The format is the `format` option, else the file name (`.opf.md` is Markdown, `.yaml` and `.yml` are YAML, anything else JSON; a plain `.md` is not a deck), and never the content. `parse` returns the presentation and throws `OPFValidationError` for a syntax, schema or reference error; the error's `report.findings` are located by line and column in the text (`opf/json-syntax`, `yaml/<rule>` or `markdown/<rule>` for syntax errors). Warnings do not throw: `validate(text)` returns the full report. Both run in a browser; files are the Node build's job (above).
 
 ### OPF as YAML
 

package/dist/browser.js

@@ -0,0 +1,38 @@
+import { OPFApiError } from './chunk-IM337HP5.js';
+export { OPFApiError, OPFExportError, OPFImportError, OPFMoveToCustomError, copySlides, edit, embed, fill, fillRecords, moveToCustom, parseSlideSelection, sameRecord, stats, updateFromCatalog } from './chunk-IM337HP5.js';
+export { specFileEntries, specFileKinds, specFilePaths } from './chunk-HXHOZ7AH.js';
+export { OPFDataImportError, ingest, parseTabularData } from './chunk-ZCFSDSUX.js';
+export { DECK_FORMATS, deckFormatOf, parse, stringify } from './chunk-GVOLSWAJ.js';
+export { fromMarkdown, toMarkdown } from './chunk-MSFE2HUK.js';
+import './chunk-ECP7QPGK.js';
+export { OPFMarkdownError } from './chunk-R7KIASS4.js';
+export { diff, merge } from './chunk-L5YACLWK.js';
+export { OPFPatchError, OPFPatchValidationError, applyPatch } from './chunk-WHHLGDCQ.js';
+export { OPFFormatError, format } from './chunk-JCOSZTOI.js';
+export { OPFPaginationError, paginate, paginateSlide } from './chunk-FO3WGS4R.js';
+import './chunk-PNINP5IF.js';
+import './chunk-TRELE6I6.js';
+export { DEFAULT_CHART_PALETTE, DEFAULT_VALIDATION_THRESHOLDS, OPFValidationError, assertValid, assertValidCatalogRecord, findValidationRule, resolveSlideContext, validate, validateCatalogRecord, validationCategories, validationRules } from './chunk-KA3ZPFVT.js';
+export { CHART_TYPES, DEFAULT_VARIABLE_DATE_FORMAT, ENGINE_DEFAULT_CHART_TYPES, ENGINE_DEFAULT_COLOR_SCHEME, ENGINE_DEFAULT_FONT_SCHEME, ENGINE_DEFAULT_THEME, LANGUAGES, LOGO_SHAPES, OPFVariableError, SLIDE_SCOPED_BUILTINS, SOCIAL_PLATFORMS, VARIABLE_KINDS, chartNumber, coerceVariableValue, datasetDiagnostics, formatDataNumber, formatVariableNumber, fromExcelNumberFormat, hasContentVariables, inlineChartData, inlineDatasets, inlineTableData, isDatasetRef, isTemplate, isXYChartType, listBuiltinVariables, listVariables, normalizeLanguageFamily, numberFormatError, resolveChartData, resolveDesignRecords, resolveFontScheme, resolveSlideVariables, resolveTableData, resolveVariables, suggestChartNumberFix, tableCellDisplayValue, toExcelNumberFormat, unusedDatasets, variableDeclarations } from './chunk-MBU42S5Y.js';
+export { catalogDisplayKinds, catalogSchemaNames } from './chunk-TRDXRRQK.js';
+export { CATALOG_GROUP_PATTERN, CATALOG_REFERENCE_PATTERN, OPFCatalogsOptionError, OPFUnresolvedReferenceError, catalogGroupSource, catalogKinds, catalogRecords, catalogReferenceSites, parseReference, resolveReference, unresolvedReference } from './chunk-SPFV27O5.js';
+export { audience, chartType, colorScheme, fontScheme, language, layout, narrative, presentation, purpose, schemaEntries, schemaNames, schemas, socialPlatform, theme, tone } from './chunk-2PEWUUBR.js';
+export { FONT_POLICY, applyFontPolicyDecisions, fontAvailabilityDiagnostics, fontPolicyFor } from './chunk-WXSPETQ6.js';
+
+// src/browser.ts
+var nodeOnly = (name, message) => new OPFApiError(`\`${name}\` ${message}`, "node-only", { details: { function: name, build: "browser" } });
+var PARSE = "In a browser or a worker, read the text yourself and call parse(text, { filename }).";
+var STRINGIFY = "In a browser or a worker, call stringify(deck, { filename }) and store or download the text.";
+var CONVERT = "In a browser or a worker, change deck forms with parse and stringify (YAML, Markdown, JSON), and draw slides with @openpresentation/opf-render's /export-browser entry.";
+var open = async () => {
+  throw nodeOnly("open", `reads files and needs Node. ${PARSE}`);
+};
+var save = async () => {
+  throw nodeOnly("save", `writes files and needs Node. ${STRINGIFY}`);
+};
+var convert = (async (_input, output) => {
+  const inMemory = output !== null && typeof output === "object";
+  throw nodeOnly("convert", inMemory ? `needs Node in OPF 0.18, also for the in-memory convert(deck, { format }). ${CONVERT}` : `reads and writes files and needs Node. ${CONVERT}`);
+});
+
+export { convert, open, save };

package/dist/{catalog-refs-C4K4y-vh.d.ts → catalog-refs-BSfGELpt.d.ts}

@@ -125,4 +125,4 @@ declare function catalogReferenceSites(document: unknown, options?: {
 /** Records a picker can offer for `kind`: the document's embedded records, then those of the registered catalogs its groups name, with the reference to write for each. */
 declare function catalogRecords(document: unknown, kind: CatalogKind, options?: CatalogOptions): ResolvedReference[];
 
-export { CATALOG_GROUP_PATTERN as C, OPFCatalogsOptionError as O, type RecordProvenance as R, type UnresolvedReferenceDiagnostic as U, CATALOG_REFERENCE_PATTERN as a, type Catalog as b, type CatalogKind as c, type CatalogOptions as d, type CatalogRecordMap as e, type CatalogRecords as f, type CatalogReferenceSite as g, OPFUnresolvedReferenceError as h, type ResolvedReference as i, catalogGroupSource as j, catalogKinds as k, catalogRecords as l, catalogReferenceSites as m, parseReference as p, resolveReference as r, unresolvedReference as u };
+export { type CatalogKind as C, OPFCatalogsOptionError as O, type RecordProvenance as R, type UnresolvedReferenceDiagnostic as U, type Catalog as a, type CatalogOptions as b, CATALOG_GROUP_PATTERN as c, CATALOG_REFERENCE_PATTERN as d, type CatalogRecordMap as e, type CatalogRecords as f, type CatalogReferenceSite as g, OPFUnresolvedReferenceError as h, type ResolvedReference as i, catalogGroupSource as j, catalogKinds as k, catalogRecords as l, catalogReferenceSites as m, parseReference as p, resolveReference as r, unresolvedReference as u };

package/dist/{catalog-schemas-g7RFQBdc.d.ts → catalog-schemas-CinPh5WA.d.ts}

@@ -1,4 +1,4 @@
-import { c as CatalogKind } from './catalog-refs-C4K4y-vh.js';
+import { C as CatalogKind } from './catalog-refs-BSfGELpt.js';
 import { SchemaName } from './schemas.js';
 
 /** Kinds of catalog display metadata: published by catalogs for pickers, never referenced by documents. */

package/dist/catalog.d.ts

@@ -1,5 +1,5 @@
-import { b as Catalog } from './catalog-refs-C4K4y-vh.js';
-import { C as CatalogDisplayKind } from './catalog-schemas-g7RFQBdc.js';
+import { a as Catalog } from './catalog-refs-BSfGELpt.js';
+import { C as CatalogDisplayKind } from './catalog-schemas-CinPh5WA.js';
 import './schemas.js';
 import './json-BFSdESOE.js';
 

package/dist/{chart-data-DTxdRRT1.d.ts → chart-data-BnNqgnC-.d.ts}

@@ -185,4 +185,4 @@ declare function resolveTableData(table: unknown, document?: unknown, options?:
 /** Display value of a table cell: a number with a format (cell, else column) becomes formatted text; anything else is returned unchanged. */
 declare function tableCellDisplayValue(cell: DataTableCell, columnFormat?: string): DataTableCell;
 
-export { numberFormatError as A, resolveChartData as B, type ChartComboSeries as C, type DataCellValue as D, resolveTableData as E, suggestChartNumberFix as F, tableCellDisplayValue as G, toExcelNumberFormat as H, unusedDatasets as I, type ResolvedChartData as R, type ChartMapping as a, type ChartNumberFix as b, type ChartNumberFixOperation as c, type ChartNumberFixOptions as d, type DataColumn as e, type DataDiagnostic as f, type DataDiagnosticCode as g, type DataResolveOptions as h, type DataSourceRef as i, type DataStyledCell as j, type DataTableCell as k, type DataTableHeader as l, type DataTableValue as m, type DataTextRun as n, type Dataset as o, type DatasetRef as p, type ResolvedTableData as q, chartNumber as r, datasetDiagnostics as s, formatDataNumber as t, fromExcelNumberFormat as u, inlineChartData as v, inlineDatasets as w, inlineTableData as x, isDatasetRef as y, isXYChartType as z };
+export { resolveChartData as A, resolveTableData as B, type ChartMapping as C, type DataCellValue as D, suggestChartNumberFix as E, tableCellDisplayValue as F, toExcelNumberFormat as G, unusedDatasets as H, type ChartComboSeries as I, type ResolvedChartData as R, type ChartNumberFix as a, type ChartNumberFixOperation as b, type ChartNumberFixOptions as c, type DataColumn as d, type DataDiagnostic as e, type DataDiagnosticCode as f, type DataResolveOptions as g, type DataSourceRef as h, type DataStyledCell as i, type DataTableCell as j, type DataTableHeader as k, type DataTableValue as l, type DataTextRun as m, type Dataset as n, type DatasetRef as o, type ResolvedTableData as p, chartNumber as q, datasetDiagnostics as r, formatDataNumber as s, fromExcelNumberFormat as t, inlineChartData as u, inlineDatasets as v, inlineTableData as w, isDatasetRef as x, isXYChartType as y, numberFormatError as z };

package/dist/{chunk-RA64UQKI.js → chunk-2PEWUUBR.js}

@@ -52,7 +52,7 @@ var presentation = {
           "minItems": 1
         }
       ],
-      "description": "Organization associated with the presentation, usually the presenting company. Array form supports hosts, partners, clients, and sponsors. The primary organization (Organization.role 'primary', else the first item) supplies the default deck logo, the 'socials' header/footer field and the 'organization.<field>' built-in variables; the others are available by id as 'organization.<id>.<field>' and are not drawn automatically."
+      "description": "Organization associated with the presentation, usually the presenting company. Array form supports hosts, partners, clients, and sponsors. The primary organization (Organization.role 'primary', else the first item) supplies the cover and section logo, the 'socials' header/footer field and the 'organization.<field>' built-in variables; the others are available by id as 'organization.<id>.<field>' and are not drawn automatically."
     },
     "speaker": {
       "oneOf": [
@@ -775,7 +775,7 @@ var presentation = {
     },
     "Organization": {
       "type": "object",
-      "description": "An organization associated with the presentation, typically the presenting company, but also hosts, partners, clients, or sponsors. The primary organization (role 'primary', else the first one) supplies the default deck logo (unless design.logo overrides it) and the 'socials' header/footer field (its socials). Every field is also a built-in variable ('{{organization.name}}', 'var:organization.logo', 'organization.<id>.<field>'). Nothing else about an organization is drawn automatically. See docs/templates-and-variables.md.",
+      "description": "An organization associated with the presentation, typically the presenting company, but also hosts, partners, clients, or sponsors. The primary organization (role 'primary', else the first one) supplies the cover and section logo (unless design.logo overrides it) and the 'socials' header/footer field (its socials). Every field is also a built-in variable ('{{organization.name}}', 'organization.<id>.<field>'), and every logo a slide-scoped image ('var:organization.logo.icon', 'var:organization.<id>.logo'). Nothing else about an organization is drawn automatically. See docs/templates-and-variables.md.",
       "required": [
         "id",
         "name"
@@ -809,12 +809,29 @@ var presentation = {
           ]
         },
         "logo": {
-          "$ref": "#/$defs/Asset",
-          "description": "Source for the organization's logo image. Accepts an HTTPS URL, data URI, relative path (resolved against the OPF file location), local path, or 'asset:<id>' reference. Common formats are SVG (preferred for vector logos), PNG (with transparency), or JPG. The primary organization's logo (role 'primary', else the first organization) is the fallback source wherever the deck logo is drawn: a slide's design.logo, then design.logo, then this value. It is therefore drawn on cover and section slides and by header/footer zones with logo: true, exactly as design.logo would be (see design.logo and docs/design-resolution.md). It is also the built-in image variable 'organization.logo' (or 'organization.<id>.logo'), placed with 'var:organization.logo' in an image field.",
+          "oneOf": [
+            {
+              "$ref": "#/$defs/Asset"
+            },
+            {
+              "$ref": "#/$defs/OrganizationLogo"
+            }
+          ],
+          "description": "The organization's logo. A path, URL or Asset is one logo for every shape; an object gives up to four shapes (full, stacked, icon, wordmark), each a path or Asset, or { onLight, onDark } for the two backgrounds. A path is resolved against the OPF file location; an HTTPS URL, data URI or 'asset:<id>' reference works too. SVG (preferred for vector logos) or PNG with transparency are typical. The primary organization's full logo (role 'primary', else the first organization) is drawn on cover and section slides unless design.logo names another or is false. Every logo is also a slide-scoped built-in image, placed with a whole-field reference in any image field: 'var:organization.logo' (the full logo), 'var:organization.logo.icon' (likewise stacked, wordmark, full), and 'var:organization.<id>.logo' or 'var:organization.<id>.logo.<shape>' for another organization. A missing shape falls back to full, and full to the first defined of wordmark, stacked and icon. The onLight or onDark value is chosen for each slide's background; a missing one uses the other. See docs/templates-and-variables.md and docs/design-resolution.md.",
           "examples": [
+            "./assets/acme-logo.svg",
+            {
+              "full": "./assets/acme-logo.svg",
+              "icon": "./assets/acme-mark.svg"
+            },
+            {
+              "full": {
+                "onLight": "./assets/acme-logo.svg",
+                "onDark": "./assets/acme-logo-white.svg"
+              },
+              "icon": "./assets/acme-mark.svg"
+            },
             "https://cdn.acme.com/logo.svg",
-            "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAusB9V3iWggAAAAASUVORK5CYII=",
-            "./assets/logo.jpg",
             "asset:acme-logo"
           ]
         },
@@ -863,7 +880,7 @@ var presentation = {
             "sponsor",
             "host"
           ],
-          "description": "Role of the organization relative to the presentation. Only 'primary' has behavior: it selects the primary organization (deck logo, the 'socials' header/footer field, and the 'organization.<field>' built-ins). When no organization has role 'primary', the first one is primary. 'partner', 'client', 'sponsor' and 'host' are descriptive labels that change nothing."
+          "description": "Role of the organization relative to the presentation. Only 'primary' has behavior: it selects the primary organization (cover and section logo, the 'socials' header/footer field, and the 'organization.<field>' built-ins). When no organization has role 'primary', the first one is primary. 'partner', 'client', 'sponsor' and 'host' are descriptive labels that change nothing."
         },
         "socials": {
           "$ref": "#/$defs/Socials",
@@ -1086,20 +1103,19 @@ var presentation = {
         "logo": {
           "oneOf": [
             {
-              "$ref": "#/$defs/Asset"
+              "type": "string",
+              "pattern": "^var:organization(\\.[A-Za-z0-9_-]+)?\\.logo(\\.(full|stacked|icon|wordmark))?$"
             },
             {
-              "$ref": "#/$defs/LogoSet"
+              "type": "boolean",
+              "const": false
             }
           ],
-          "description": "Deck logo assets used by covers, section dividers, headers, footers and picture bullets. A string or Asset object is the default logo source; the LogoSet object form provides light/dark, stacked, icon, and wordmark variants (see LogoSet for the selection order). Source precedence: a slide's design.logo, then this value, then the primary organization's logo; absence inherits. Placement (reference engines, vetoable): on a cover or section slide (no body payload on a heading-only layout such as title, title-subtitle or section-divider, or no layout) the lockup variant is drawn at the top-left of the free area, inside the slide padding and below any header furniture, in a box 56 reference pixels tall and at most four times as wide; the tag/title/subtitle group then centers in the remaining span. Content slides never get an automatic logo. Header and footer zones draw the icon variant when they set logo: true, and design.listBullet 'image' draws it as the picture bullet. composeSlide returns the cover box as geometry.logo.",
+          "description": "Which logo covers, section dividers and picture bullets draw. Logos live on the organization (Organization.logo); without this field covers and sections draw the primary organization's full logo and picture bullets its icon. A logo reference overrides that: 'var:organization.beta.logo' draws organization beta's logo, and a reference that names a shape ('var:organization.logo.wordmark') draws that shape everywhere this field applies. false draws no logo. A slide's design.logo overrides the deck's; absence inherits. An override naming an organization without a logo draws nothing (validation warns). Placement (reference engines, vetoable): on a cover or section slide (no body payload on a heading-only layout such as title, title-subtitle or section-divider, or no layout) the logo is drawn at the top-left of the free area, inside the slide padding and below any header furniture, in a box 56 reference pixels tall and at most four times as wide; the tag/title/subtitle group then centers in the remaining span. Content slides never get an automatic logo; a header or footer zone places one with image: 'var:organization.logo.icon'. composeSlide returns the cover box as geometry.logo.",
           "examples": [
-            "asset:acme-logo",
-            {
-              "default": "asset:acme-logo",
-              "light": "asset:acme-logo-white",
-              "icon": "asset:acme-icon"
-            }
+            "var:organization.logo.wordmark",
+            "var:organization.beta.logo",
+            false
           ]
         },
         "watermark": {
@@ -1147,7 +1163,7 @@ var presentation = {
                 "text": "{{slide.section}}"
               },
               "right": {
-                "image": "asset:acme-logo"
+                "image": "var:organization.logo.icon"
               }
             }
           ]
@@ -1167,7 +1183,7 @@ var presentation = {
             false,
             {
               "left": {
-                "image": "asset:acme-logo"
+                "image": "var:organization.logo.icon"
               },
               "center": {
                 "text": "Confidential"
@@ -1234,7 +1250,7 @@ var presentation = {
             "character",
             "image"
           ],
-          "description": "Marker style for items and bullets lists. Effective value: the slide's design, then the deck's design, then the layout record's design.listBullet, then 'character'. 'character' (the default) draws the glyph marker. 'image' draws the deck's icon logo (a slide's design.logo, then design.logo, then the primary organization's logo; light variants on dark backgrounds) as a picture bullet: a square of the marker's font size whose bottom sits on the marker baseline, so list geometry does not change. Without a logo the glyph is drawn and the engine reports unresolved-content at this field."
+          "description": "Marker style for items and bullets lists. Effective value: the slide's design, then the deck's design, then the layout record's design.listBullet, then 'character'. 'character' (the default) draws the glyph marker. 'image' draws the primary organization's icon logo (or the organization and shape design.logo names; the onDark value on dark backgrounds) as a picture bullet: a square of the marker's font size whose bottom sits on the marker baseline, so list geometry does not change. Without a logo the glyph is drawn and the engine reports unresolved-content at this field."
         }
       }
     },
@@ -1574,11 +1590,11 @@ var presentation = {
         "widescreen",
         "standard"
       ],
-      "description": "Named dimension preset; chooses both aspect ratio and physical size. 'widescreen' is an alias for 16:9 in PowerPoint widescreen size; 'standard' is an alias for 4:3 in PowerPoint standard size. The social-feed ratios keep the widescreen short edge of 7.5 in: 1:1 is 7.5 x 7.5 in, 4:5 is 7.5 x 9.375 in and 9:16 is 7.5 x 13.333 in (portrait)."
+      "description": "Named preset; sets aspect ratio and physical size. 16:9 ('widescreen'): 13.333 x 7.5 in, PowerPoint's Widescreen. 4:3 ('standard'): 10 x 7.5 in. 16:10: 10 x 6.25 in. letter (11 x 8.5 in) and a4 (11.69 x 8.27 in) are paper sizes, not PowerPoint's Letter Paper or A4 Paper. 1:1, 4:5 and 9:16 are 7.5 in on the short edge."
     },
     "Dimensions": {
       "type": "object",
-      "description": "Slide dimensions; either pick a preset or specify custom inches.",
+      "description": "Slide dimensions: a preset, or custom inches that override it. PowerPoint's Letter Paper (10 x 7.5 in), A4 Paper (10.8333 x 7.5 in) and On-screen Show (16:9) (10 x 5.625 in) are not OPF presets; use widthInches and heightInches. docs/slide-sizes.md compares every preset.",
       "properties": {
         "preset": {
           "$ref": "#/$defs/DimensionPreset"
@@ -1666,7 +1682,7 @@ var presentation = {
       "additionalProperties": {
         "$ref": "#/$defs/Variable"
       },
-      "description": "Named variables, keyed by stable kebab-case id. A variable is a typed, named value the deck declares once and uses in many places: a color ('var:<id>' in color fields, the original use), or content that fills a template (text, number, date, image, url, list). Content is referenced inline as '{{<id>}}' inside any string, or whole as 'var:<id>' in a field of the matching type; '\\{{' writes a literal '{{'. A hex string is shorthand for a color variable. A variable with no 'value' is unfilled: expected in a template (root 'template': true), an error in a normal deck. Engines resolve variables with resolveVariables() before composing, rendering or exporting, so a template plus its values previews and exports exactly like the equivalent hand-written deck. Read-only built-in variables come from the deck's own metadata and use dotted names that a user id can never take: 'deck.name', 'deck.description', 'deck.author', 'speaker.name|title|email|phone|bio|photo' (first speaker), 'speakers' (every speaker's name, a list), 'organization.name|legalName|tagline|domain|email|phone|logo' (primary organization), and 'speaker.<id>.<field>' / 'organization.<id>.<field>' by id. They are written the same two ways ('{{speaker.name}}', 'var:speaker.photo'), are never declared, and an unknown built-in path is a validation error; a known one with no source value resolves to nothing with a warning. The id 'speakers' is reserved. Three built-ins are slide-scoped and written only as inline tokens: '{{slide.number}}' (the displayed slide number after pagination), '{{slide.section}}' (the slide's section) and '{{deck.slideCount}}' (the number of slides after pagination). resolveVariables() leaves them as written; they resolve per slide as it is composed (resolveSlideVariables(), and header/footer text in layoutFurniture()), so every 'slide.' name is reserved and 'var:slide.*' or 'var:deck.slideCount' is a validation error. See docs/templates-and-variables.md.",
+      "description": "Named variables, keyed by stable kebab-case id. A variable is a typed, named value the deck declares once and uses in many places: a color ('var:<id>' in color fields, the original use), or content that fills a template (text, number, date, image, url, list). Content is referenced inline as '{{<id>}}' inside any string, or whole as 'var:<id>' in a field of the matching type; '\\{{' writes a literal '{{'. A hex string is shorthand for a color variable. A variable with no 'value' is unfilled: expected in a template (root 'template': true), an error in a normal deck. Engines resolve variables with resolveVariables() before composing, rendering or exporting, so a template plus its values previews and exports exactly like the equivalent hand-written deck. Read-only built-in variables come from the deck's own metadata and use dotted names that a user id can never take: 'deck.name', 'deck.description', 'deck.author', 'speaker.name|title|email|phone|bio|photo' (first speaker), 'speakers' (every speaker's name, a list), 'organization.name|legalName|tagline|domain|email|phone' (primary organization), and 'speaker.<id>.<field>' / 'organization.<id>.<field>' by id. They are written the same two ways ('{{speaker.name}}', 'var:speaker.photo'), are never declared, and an unknown built-in path is a validation error; a known one with no source value resolves to nothing with a warning. The id 'speakers' is reserved. Three built-ins are slide-scoped and written only as inline tokens: '{{slide.number}}' (the displayed slide number after pagination), '{{slide.section}}' (the slide's section) and '{{deck.slideCount}}' (the number of slides after pagination). resolveVariables() leaves them as written; they resolve per slide as it is composed (resolveSlideVariables(), and header/footer text in layoutFurniture()), so every 'slide.' name is reserved and 'var:slide.*' or 'var:deck.slideCount' is a validation error. Organization logos are slide-scoped whole-field images: 'var:organization.logo', 'var:organization.logo.<shape>' (full, stacked, icon, wordmark), 'var:organization.<id>.logo' and 'var:organization.<id>.logo.<shape>' resolve per slide to the onLight or onDark asset for its background. See docs/templates-and-variables.md.",
       "examples": [
         {
           "risk": "#B42318",
@@ -2509,60 +2525,71 @@ var presentation = {
         }
       }
     },
-    "LogoSet": {
+    "OrganizationLogo": {
       "type": "object",
-      "description": "Deck logo variants surfaced by covers, section dividers, headers, footers and picture bullets. Organization identity lives in organization; this object only controls visual rendering assets. Engines select one variant per slot and background tone (resolveLogo in @openpresentation/opf): same-tone variants first, neutral ones next, the opposite tone last. Lockup on a dark background: light, default, stackedLight, stacked, wordmarkLight, wordmark, iconLight, icon, then dark, stackedDark, wordmarkDark, iconDark; on a light background: dark, default, stackedDark, stacked, wordmarkDark, wordmark, iconDark, icon, then light, stackedLight, wordmarkLight, iconLight. The icon slot (headers, footers, picture bullets) tries iconLight or iconDark for the tone, then icon, then the lockup chain; the stacked slot tries stackedLight or stackedDark, then stacked, then the lockup chain.",
+      "description": "An organization's logo in up to four shapes. Each shape is a path or Asset, or { onLight, onDark } for the two backgrounds. A missing shape falls back to full, and full to the first defined of wordmark, stacked and icon; within a shape a missing onLight or onDark uses the other. Shapes are placed with slide-scoped references such as 'var:organization.logo.icon'.",
       "additionalProperties": false,
+      "minProperties": 1,
       "properties": {
-        "default": {
-          "$ref": "#/$defs/Asset",
-          "description": "Default full-lockup logo. Used as fallback when no more specific variant is set."
-        },
-        "light": {
-          "$ref": "#/$defs/Asset",
-          "description": "Light-colored full-lockup logo intended for rendering on dark backgrounds."
-        },
-        "dark": {
-          "$ref": "#/$defs/Asset",
-          "description": "Dark-colored full-lockup logo intended for rendering on light backgrounds."
+        "full": {
+          "$ref": "#/$defs/LogoSource",
+          "description": "The full logo (lockup): mark and name side by side. Drawn on cover and section slides, and placed by 'var:organization.logo'."
         },
         "stacked": {
-          "$ref": "#/$defs/Asset",
-          "description": "Stacked vertical logo lockup, suited to portrait or square brand-mark slots."
-        },
-        "stackedLight": {
-          "$ref": "#/$defs/Asset",
-          "description": "Light-colored stacked logo variant intended for rendering on dark backgrounds."
-        },
-        "stackedDark": {
-          "$ref": "#/$defs/Asset",
-          "description": "Dark-colored stacked logo variant intended for rendering on light backgrounds."
+          "$ref": "#/$defs/LogoSource",
+          "description": "The stacked lockup: mark above the name, for portrait or square slots. Placed by 'var:organization.logo.stacked'."
         },
         "icon": {
-          "$ref": "#/$defs/Asset",
-          "description": "Default icon, mark, or symbol without wordmark. Useful for tight spaces such as footers, badges, and slide-corner marks."
-        },
-        "iconLight": {
-          "$ref": "#/$defs/Asset",
-          "description": "Light-colored icon variant intended for rendering on dark backgrounds."
-        },
-        "iconDark": {
-          "$ref": "#/$defs/Asset",
-          "description": "Dark-colored icon variant intended for rendering on light backgrounds."
+          "$ref": "#/$defs/LogoSource",
+          "description": "The mark or symbol without the name, for tight spaces such as header and footer zones and picture bullets. Placed by 'var:organization.logo.icon'."
         },
         "wordmark": {
-          "$ref": "#/$defs/Asset",
-          "description": "Default wordmark: the organization name set in branded typography, without icon."
+          "$ref": "#/$defs/LogoSource",
+          "description": "The name set in the brand's lettering, without the mark. Placed by 'var:organization.logo.wordmark'."
+        }
+      },
+      "examples": [
+        {
+          "full": "./assets/acme-logo.svg",
+          "icon": "./assets/acme-mark.svg"
         },
-        "wordmarkLight": {
-          "$ref": "#/$defs/Asset",
-          "description": "Light-colored wordmark variant intended for rendering on dark backgrounds."
+        {
+          "full": {
+            "onLight": "./assets/acme-logo.svg",
+            "onDark": "./assets/acme-logo-white.svg"
+          }
+        }
+      ]
+    },
+    "LogoSource": {
+      "description": "One logo shape: a path or Asset for every background, or { onLight, onDark }. onLight is drawn on light backgrounds (usually dark artwork) and onDark on dark backgrounds (usually light artwork), by each slide's background; a missing one uses the other.",
+      "oneOf": [
+        {
+          "$ref": "#/$defs/Asset"
         },
-        "wordmarkDark": {
-          "$ref": "#/$defs/Asset",
-          "description": "Dark-colored wordmark variant intended for rendering on light backgrounds."
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "minProperties": 1,
+          "properties": {
+            "onLight": {
+              "$ref": "#/$defs/Asset",
+              "description": "The logo for light backgrounds, usually dark artwork."
+            },
+            "onDark": {
+              "$ref": "#/$defs/Asset",
+              "description": "The logo for dark backgrounds, usually light or white artwork."
+            }
+          }
         }
-      }
+      ],
+      "examples": [
+        "./assets/acme-mark.svg",
+        {
+          "onLight": "./assets/acme-logo.svg",
+          "onDark": "./assets/acme-logo-white.svg"
+        }
+      ]
     },
     "Watermark": {
       "type": "object",
@@ -2625,13 +2652,9 @@ var presentation = {
     },
     "HeaderFooterItem": {
       "type": "object",
-      "description": "One header/footer zone. Every configured field renders; fields in one zone stack top to bottom in the order logo, image, text, socials, date. Generated values such as the slide number, the slide count, the section, the organization or the speaker are variables inside text ('{{slide.number}} / {{deck.slideCount}}', '{{organization.name}}'), so one text writes several values in the author's order; a line break is '\\n'. Put a date and a slide number in different zones to keep each on the zone's single line. See docs/templates-and-variables.md.",
+      "description": "One header/footer zone. Every configured field renders, side by side in one row in the order image, text, socials, date (mirrored in a right-to-left deck), aligned to the zone's edge (left, center or right) and vertically centered on each other; a line break inside text or socials ('\\n') stacks lines within that part. When the parts are wider than the zone their text wraps, and a row that cannot fit even so is reported as overflow. Generated values such as the slide number, the slide count, the section, the organization or the speaker are variables inside text ('{{slide.number}} / {{deck.slideCount}}', '{{organization.name}}'), so one text writes several values in the author's order. An organization logo is image: 'var:organization.logo.icon'. See docs/templates-and-variables.md.",
       "additionalProperties": false,
       "properties": {
-        "logo": {
-          "type": "boolean",
-          "description": "Whether to render the deck's icon logo in this zone: a slide's design.logo, then design.logo, then the primary organization's logo (LogoSet icon variants first, light ones on dark backgrounds). It is a generated image part in the same box as image; without a logo the engine reports unresolved-content at this field. Use image for a literal picture that is not the deck logo."
-        },
         "text": {
           "type": "string",
           "description": "Text rendered in this zone. Variables resolve inside it like any string: deck-wide ones ('{{organization.name}}', '{{speaker.name}}, {{speaker.title}}', '{{customer}}') before composition, and the slide-scoped built-ins '{{slide.number}}', '{{slide.section}}' and '{{deck.slideCount}}' for each slide as it is laid out. Each '{{slide.number}}' is a live slide-number field: PPTX export writes it as a native field when its value fits within one accepted text line, and as static text with a diagnostic otherwise. '{{deck.slideCount}}' is fixed text, because PowerPoint has no slide-count field. Write '\\{{' for literal braces.",
@@ -2644,10 +2667,11 @@ var presentation = {
         },
         "image": {
           "$ref": "#/$defs/Asset",
-          "description": "Generic image rendered in this zone, such as a logo, partner mark, certification badge, or icon.",
+          "description": "Image rendered first in this zone's row, such as a logo, partner mark, certification badge, or icon: a path, URL or Asset, or an organization logo reference ('var:organization.logo.icon', 'var:organization.<id>.logo.wordmark'), which resolves for each slide's background (onLight or onDark).",
           "examples": [
-            "asset:acme-logo",
-            "./assets/footer-badge.svg"
+            "var:organization.logo.icon",
+            "./assets/footer-badge.svg",
+            "var:organization.beta.logo"
           ]
         },
         "date": {
@@ -3087,7 +3111,7 @@ var presentation = {
         },
         "hidden": {
           "type": "boolean",
-          "description": "Whether the slide is hidden from the presented sequence. The player skips it, the PPTX export writes it as a hidden slide, and per-slide image and PDF output skips it unless the caller asks to include hidden slides (opf CLI: --include-hidden; the deck-level renderSvg: the opt-in skipHidden). A slide named explicitly (opf render --slides, renderSvg slideIndex) is still rendered."
+          "description": "Whether the slide is hidden from the presented sequence. The player skips it, the PPTX export writes it as a hidden slide, and per-slide image and PDF output skips it unless the caller asks to include hidden slides (opf CLI: --include-hidden; the deck-level toSvg: the opt-in skipHidden). A slide named explicitly (opf convert --slides, toSvg with a slide number) is still rendered."
         },
         "composition": {
           "$ref": "#/$defs/Composition"

package/dist/{chunk-TCD2FB2K.js → chunk-ECP7QPGK.js}

@@ -1,9 +1,9 @@
-import { NOT_CHECKED, Ctx } from './chunk-IS5H5JKH.js';
-import { sortPresentationKeys } from './chunk-YT7FMQER.js';
-import { same } from './chunk-PPROJP2E.js';
-import { validate } from './chunk-NLNYNBTS.js';
+import { NOT_CHECKED, Ctx } from './chunk-R7KIASS4.js';
+import { sortPresentationKeys } from './chunk-JCOSZTOI.js';
+import { same } from './chunk-TRELE6I6.js';
+import { validate } from './chunk-KA3ZPFVT.js';
 import { checkCatalogsOption } from './chunk-SPFV27O5.js';
-import { presentation } from './chunk-RA64UQKI.js';
+import { presentation } from './chunk-2PEWUUBR.js';
 import { Parser, parseDocument, isMap, Document, visit, isScalar, isAlias, isSeq } from 'yaml';
 
 var MAX_ALIAS_COUNT = 100;

package/dist/{chunk-O2CX5NEH.js → chunk-FO3WGS4R.js}

@@ -1,5 +1,5 @@
-import { assertValid, resolveSlideScriptMeasurement, resolveSlideContext } from './chunk-NLNYNBTS.js';
-import { resolveSlideVariables, usesSlideBuiltin, composeSlide, codeHighlightSlice, tableRowBoundaries, visitContentPayloads, slideTokenSpans, sliceNumberedItems } from './chunk-CW7GEAV3.js';
+import { assertValid, resolveSlideScriptMeasurement, resolveSlideContext } from './chunk-KA3ZPFVT.js';
+import { resolveSlideVariables, usesSlideBuiltin, composeSlide, codeHighlightSlice, tableRowBoundaries, visitContentPayloads, slideTokenSpans, sliceNumberedItems } from './chunk-MBU42S5Y.js';
 import { checkCatalogsOption } from './chunk-SPFV27O5.js';
 
 // src/pagination.ts
@@ -122,10 +122,11 @@ function paginateSlide(input, options = {}) {
   if (options.layout !== void 0) composeOptions.layout = readableLayout(options.layout);
   const presentationSlides = options.presentation?.slides;
   const slideCount = options.slideCount ?? (Array.isArray(presentationSlides) && presentationSlides.length ? presentationSlides.length : void 0);
+  const logoContext = options.presentation !== void 0 ? { presentation: options.presentation, darkBackground: options.darkBackground === true } : {};
   const geometry = (slide, pageIndex = 0) => {
     if (++evaluations > 2e4) throw new OPFPaginationError("Pagination exceeded its layout evaluation limit. Split the input into smaller sections.");
     const slideNumber = (options.slideNumber ?? sourceIndex + 1) + pageIndex;
-    return composeSlide(resolveSlideVariables(withReadability(slide, true), { slideNumber, ...slideCount !== void 0 ? { slideCount } : {} }), { ...composeOptions, slideNumber });
+    return composeSlide(resolveSlideVariables(withReadability(slide, true), { slideNumber, ...slideCount !== void 0 ? { slideCount } : {}, ...logoContext }), { ...composeOptions, slideNumber });
   };
   const initial = geometry(source);
   const fit = (diagnostics) => diagnostics.filter((issue) => issue.code === "text-overflow" || issue.code === "small-cell" || !!initial.furniture?.diagnostics.includes(issue));
@@ -141,7 +142,7 @@ function paginateSlide(input, options = {}) {
   if (!fit(initial.diagnostics).length) return { slides: [source], pages: [{ slideIndex: sourceIndex, mappings: initial.items.map((item) => ({ sourcePath: item.path, outputPath: item.path })), ...initial.furniture ? { repeatedMappings: repeatedMappings(0) } : {} }] };
   const headerIssues = initial.diagnostics.filter((issue) => headingFields.has(issue.path.slice(sourceBase.length + 1)) || initial.furniture?.diagnostics.includes(issue));
   if (headerIssues.length) throw new OPFPaginationError("Repeated headings or header/footer content cannot fit or resolve. Change the repeated content or slide design before pagination.", headerIssues);
-  const tokens = resolveSlideVariables(source, { slideNumber: 1, slideCount: 1 }) !== source;
+  const tokens = resolveSlideVariables(source, { slideNumber: 1, slideCount: 1, ...logoContext }) !== source;
   const sourceValue = (path, fallback) => {
     if (!tokens || !path.startsWith(`${sourceBase}.`)) return fallback;
     let node = source;
@@ -312,7 +313,7 @@ function paginate(input, options = {}) {
   const { output, pages } = result;
   presentation.slides = output;
   assertValid(presentation, { only: ["format"] });
-  return { presentation, pages };
+  return { presentation, pages, layout: options.fonts ? "measured" : "estimated" };
 }
 
 export { OPFPaginationError, paginate, paginateSlide };

package/dist/{chunk-N4EVOFEA.js → chunk-GVOLSWAJ.js}

@@ -1,7 +1,7 @@
-import { fromMarkdown, toMarkdown } from './chunk-BIC3SWPK.js';
-import { fromYaml, toYaml } from './chunk-TCD2FB2K.js';
-import { NOT_CHECKED } from './chunk-IS5H5JKH.js';
-import { parseSource, validate, OPFValidationError } from './chunk-NLNYNBTS.js';
+import { fromMarkdown, toMarkdown } from './chunk-MSFE2HUK.js';
+import { fromYaml, toYaml } from './chunk-ECP7QPGK.js';
+import { NOT_CHECKED } from './chunk-R7KIASS4.js';
+import { parseSource, validate, OPFValidationError } from './chunk-KA3ZPFVT.js';
 import { checkCatalogsOption } from './chunk-SPFV27O5.js';
 
 // src/deck-report.ts