@openpresentation/opf 0.16.0 → 0.17.0

package/README.md

@@ -49,6 +49,20 @@ 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:
+
+```ts
+import * as opf from "@openpresentation/opf/node";
+
+await opf.convert("deck.opf.md", "deck.pdf");
+const deck = await opf.open("deck.opf.md");
+deck.slides.push({ title: "Q4" });
+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).
+
 Use focused imports when you only need one surface:
 
 ```ts
@@ -59,7 +73,7 @@ import { validate, assertValid, validationRules } from "@openpresentation/opf/va
 import type { Presentation, Audience, Tone } from "@openpresentation/opf/types";
 ```
 
-The root entry holds the application-level API: schemas, catalog references and their resolution (`resolveReference`, `embed`, `copySlides`, `updateFromCatalog`), validation, variables, pagination, data helpers, font policy, `stats` and `resolveSlideContext`. It carries no catalog records: the pinned pptx.gallery snapshot is the opt-in `@openpresentation/opf/catalog` (`defaultCatalog`, display metadata and layout previews), and every entry point that resolves references takes `{ catalogs }`, the catalogs the host registered; the first one is the default for documents that omit `catalogs.default`. See [catalogs and the default catalog](../../docs/default-catalog.md).
+The root entry holds the application-level API: schemas, catalog references and their resolution (`resolveReference`, `embed`, `copySlides`, `updateFromCatalog`), validation, variables, pagination, data helpers, font policy, `stats`, `resolveSlideContext` and `resolveSlideVariables`. Engines compose and draw `context.slide` from `resolveSlideContext(deck, index, { slideNumber, slideCount })`: the slide with the slide-scoped built-ins `{{slide.number}}`, `{{slide.section}}` and `{{deck.slideCount}}` substituted for the same numbers its `options` carry (`resolveSlideVariables(slide, { slideNumber, slideCount })` does that substitution alone). Header and footer text is substituted by `layoutFurniture`, which records each slide number in `FurnitureTextPart.fields`. See [templates and variables](../../docs/templates-and-variables.md#slide-scoped-built-ins). It carries no catalog records: the pinned pptx.gallery snapshot is the opt-in `@openpresentation/opf/catalog` (`defaultCatalog`, display metadata and layout previews), and every entry point that resolves references takes `{ catalogs }`, the catalogs the host registered; the first one is the default for documents that omit `catalogs.default`. See [catalogs and the default catalog](../../docs/default-catalog.md).
 
 The layout engine's names are not on the root. `composeSlide`, `fitText`, `layoutQuote` and the other `layoutX`/`fitX` functions, numbering, footnotes and citations, colour contrast, code syntax, pattern fills, metric trends, chart options, script fonts and text direction come from `@openpresentation/opf/composition`; the symbol-font tables come from `@openpresentation/opf/symbol-font-encodings`.
 
@@ -77,7 +91,7 @@ The layout engine's names are not on the root. `composeSlide`, `fitText`, `layou
 
 ### Reading and writing a deck in any form
 
-`readDeck(text, { format, filename, catalogs, validate })` and `writeDeck(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. `readDeck` returns `{ presentation, format, valid, findings, counts, schemaValid, checks }`: the `validate` report of the deck, with every finding located in the text that was read (`opf/json-syntax`, `yaml/<rule>` or `markdown/<rule>` for syntax errors) and no exception for malformed content. It runs in a browser.
+`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).
 
 ### OPF as YAML
 

package/dist/{catalog-refs-_anZs-Qz.d.ts → catalog-refs-C4K4y-vh.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 { type Catalog as C, OPFCatalogsOptionError as O, type RecordProvenance as R, type UnresolvedReferenceDiagnostic as U, type CatalogKind 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 };
+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 };

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

@@ -1,4 +1,4 @@
-import { a as CatalogKind } from './catalog-refs-_anZs-Qz.js';
+import { c as CatalogKind } from './catalog-refs-C4K4y-vh.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 { C as Catalog } from './catalog-refs-_anZs-Qz.js';
-import { C as CatalogDisplayKind } from './catalog-schemas-BZCjgAxu.js';
+import { b as Catalog } from './catalog-refs-C4K4y-vh.js';
+import { C as CatalogDisplayKind } from './catalog-schemas-g7RFQBdc.js';
 import './schemas.js';
 import './json-BFSdESOE.js';