@openpresentation/opf 0.14.0 → 0.15.1

package/README.md

@@ -29,14 +29,8 @@ Requires Node 22 or later (`engines.node` `>=22`) from the release after 0.12.1.
 Use the common root API for most application code:
 
 ```ts
-import {
-  presentation,
-  audiences,
-  tones,
-  catalogs,
-  validate,
-  validateCatalogRecord,
-} from "@openpresentation/opf";
+import { presentation, validate, embed } from "@openpresentation/opf";
+import { defaultCatalog } from "@openpresentation/opf/catalog";
 
 import type { Presentation } from "@openpresentation/opf";
 
@@ -46,34 +40,32 @@ const deck: Presentation = {
 };
 
 console.log(presentation.$id);
-console.log(validate(deck).valid);
-console.log(validateCatalogRecord("tones", tones[0]).valid);
-console.log(audiences.map((audience) => audience.id));
-console.log(Object.keys(catalogs));
+// Register the catalogs your host trusts; core itself ships no records in its main entry.
+const catalogs = [defaultCatalog];
+console.log(validate({ ...deck, design: { theme: "classic" } }, { catalogs }).valid);
+// Save with every record the deck uses embedded, so it renders the same with no catalog registered.
+const saved = embed({ ...deck, design: { theme: "classic" } }, { catalogs }).document;
+console.log(Object.keys(saved.catalogs.default.themes)); // ["classic"]
+console.log(Object.keys(defaultCatalog.tones));
 ```
 
 Use focused imports when you only need one surface:
 
 ```ts
 import { presentation, audience } from "@openpresentation/opf/schemas";
-import { audiences, tones } from "@openpresentation/opf/catalogs";
+import { defaultCatalog, catalogDisplay, layoutPreviews, getLayoutPreview, hasLayoutPreview } from "@openpresentation/opf/catalog";
 import { specFileEntries } from "@openpresentation/opf/spec-files";
 import { validate, assertValid, validationRules } from "@openpresentation/opf/validator";
-import {
-  layoutPreviews,
-  getLayoutPreview,
-  hasLayoutPreview,
-} from "@openpresentation/opf/previews";
 import type { Presentation, Audience, Tone } from "@openpresentation/opf/types";
 ```
 
-The root entry holds the application-level API: schemas, catalogs, validation, variables, pagination, data helpers, font policy, `stats` and `resolveSlideContext`. Prefer the focused subpaths above when a package consumer only needs one surface, so the root bundle's full catalog/schema payload is not loaded unnecessarily.
+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 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`.
 
 ### Facts, slide context and the fonts handle
 
-`stats(presentation, options?)` reports neutral facts about a deck (structure, words, notes, images, charts, tables, datasets, citations, variables, assets, fonts) without composing, measuring or validating; see [the stats guide](../../docs/stats.md). `resolveSlideContext(presentation, index, { fonts })` resolves one slide's canvas, layout, theme and font families (slide design, then deck design, then theme, then the default font scheme) into the `ComposeSlideOptions` that `composeSlide` takes, with `unresolved-font-scheme`, `unresolved-layout` and `unresolved-theme` diagnostics. Deck-level verbs take `{ fonts }`, a handle whose `textMeasurement` is how wide the host's real fonts draw text (`paginate(deck, { fonts })`); the renderer's font loader returns a richer handle that extends it. `composeSlide` itself is engine-level and takes `textMeasurement` and `fontFamilies` (`{ heading, body, code, accent? }`) directly.
+`stats(presentation, options?)` reports neutral facts about a deck (structure, words, notes, images, charts, tables, datasets, citations, variables, assets, fonts) without composing, measuring or validating; see [the stats guide](../../docs/stats.md). `resolveSlideContext(presentation, index, { fonts, catalogs })` resolves one slide's canvas, layout, theme and font families (slide design, then deck design, then theme, then the engine defaults) into the `ComposeSlideOptions` that `composeSlide` takes, with one `unresolved-reference` diagnostic per reference that resolves nowhere (`strictReferences: true` throws `OPFUnresolvedReferenceError` instead). Deck-level verbs take `{ fonts }`, a handle whose `textMeasurement` is how wide the host's real fonts draw text (`paginate(deck, { fonts })`); the renderer's font loader returns a richer handle that extends it. `composeSlide` itself is engine-level and takes `textMeasurement` and `fontFamilies` (`{ heading, body, code, accent? }`) directly.
 
 ### Content conversions
 
@@ -89,7 +81,7 @@ The layout engine's names are not on the root. `composeSlide`, `fitText`, `layou
 
 ### Validate (0.14.0)
 
-`validate(input, options?)` is the one checker, from the root and from `@openpresentation/opf/validator`. `input` is a parsed presentation or strict JSON text; the result is a `ValidationReport` whose `findings` (the shared `Finding` format, `spec/schemas/finding.schema.json`) each have a stable `opf/<rule>` id, a severity and one of six categories: `format` (JSON syntax, duplicate keys, schema), `references` (catalog ids, assets, citations, datasets), `policy` (host `contracts`), `accessibility` (contrast, alt text, reading order, links), `layout` (overflow, type size, image resolution, fonts) and `content` (placeholders, empty slides, non-numeric chart cells). `valid` means no finding has severity `error`, which by default only `format`, `references` and `policy` findings can have. Text input adds line and column; `only`, `ignore` and `severity` pick and promote rules or categories; composition is lazy, so `validate(deck, { only: ["format"] })` costs what a schema check costs. Read-only and deterministic: no remote resources are fetched. See [the validate guide](../../docs/validate.md). A clean report does not certify layout, fonts, or native export fidelity.
+`validate(input, options?)` is the one checker, from the root and from `@openpresentation/opf/validator`. `input` is a parsed presentation or strict JSON text; the result is a `ValidationReport` whose `findings` (the shared `Finding` format, `spec/schemas/finding.schema.json`) each have a stable `opf/<rule>` id, a severity and one of six categories: `format` (JSON syntax, duplicate keys, schema), `references` (catalog references, assets, citations, datasets), `policy` (host `contracts`), `accessibility` (contrast, alt text, reading order, links), `layout` (overflow, type size, image resolution, fonts) and `content` (placeholders, empty slides, non-numeric chart cells). `valid` means no finding has severity `error`, which by default only `format`, `references` and `policy` findings can have. Text input adds line and column; `only`, `ignore` and `severity` pick and promote rules or categories; composition is lazy, so `validate(deck, { only: ["format"] })` costs what a schema check costs. Read-only and deterministic: no remote resources are fetched. See [the validate guide](../../docs/validate.md). A clean report does not certify layout, fonts, or native export fidelity.
 
 ### Patch, diff, merge and format (0.12.0)
 
@@ -97,14 +89,14 @@ Added in 0.12.0 (not in 0.11.4 or earlier): `@openpresentation/opf/patch` is the
 
 ### Layout previews
 
-`@openpresentation/opf/previews` ships pre-rendered HTML thumbnails for the
+`@openpresentation/opf/catalog` ships pre-rendered HTML thumbnails for the
 slide layouts catalogued at pptx.gallery. Each preview is a Tailwind-styled
 fragment sized to fill a 16:9 container and only depends on the standard
 `--background`, `--foreground`, `--card`, `--muted`, `--muted-foreground`,
 `--accent`, and `--border` CSS variables.
 
 ```tsx
-import { getLayoutPreview } from "@openpresentation/opf/previews";
+import { getLayoutPreview } from "@openpresentation/opf/catalog";
 
 export function LayoutThumbnail({ slug }: { slug: string }) {
   const html = getLayoutPreview(slug);
@@ -179,14 +171,13 @@ console.log(repoReadme.split("\n").slice(0, 3).join("\n"));
 
 Validation reports carry `findings`. A finding with severity `error` is a
 structural problem that makes `valid` false; `warning` and `info` findings are
-advisory, such as an unknown catalog id in `narrative`, `design`, or a chart
-`type` reference (`opf/catalog-reference`) or a missing alt text. An id that a
-matching inline `catalogs.<kind>.records[]` entry defines is known, and a custom
-`catalogs.<kind>.source` exempts that kind's ids from unknown-id warnings
-unless the host loads the source's records and passes them as `catalogs`.
+advisory, such as a `narrative`, `design` or `layout` reference that resolves
+nowhere (`opf/unresolved-reference`) or a missing alt text. A reference resolves
+in the records the document embeds (`catalogs.custom`, `catalogs.default`, named
+groups), then in the catalogs the host registered with `{ catalogs }`.
 
 ```ts
-const report = validate(deck);
+const report = validate(deck, { catalogs: [defaultCatalog] });
 if (!report.valid) console.error(report.findings.filter((finding) => finding.severity === "error"));
 for (const finding of report.findings) console.warn(finding.ruleId, finding.path, finding.message);
 ```
@@ -221,16 +212,11 @@ const openApi = specFileEntries.find((entry) => entry.path === "openapi.yaml");
 console.log(openApi?.packagePath);
 ```
 
-Package-addressable catalog paths can be used by OPF catalog resolvers:
+The snapshot's raw record files stay package-addressable (`@openpresentation/opf/spec/catalogs/<kind>/<id>.json`) for tools that read published records; documents never point at them. A host registers the catalog instead:
 
-```json
-{
-  "catalogs": {
-    "narratives": {
-      "source": "pkg:@openpresentation/opf/spec/catalogs/narratives"
-    }
-  }
-}
+```js
+import { defaultCatalog } from "@openpresentation/opf/catalog";
+validate(deck, { catalogs: [defaultCatalog] });
 ```
 
 ## Development

package/dist/catalog-refs-BSfGELpt.d.ts

@@ -0,0 +1,128 @@
+/**
+ * OPF 0.15 content references and their one resolution rule (FA-20). Catalog-free: this module reads the document's
+ * own `catalogs` groups and the catalogs a host registers, never any bundled data, and it never fetches.
+ *
+ * A reference is a bare `id` or `name:id`. A bare id resolves in `catalogs.custom`, then in the records embedded
+ * under `catalogs.default`, then in the registered catalog for `default.source` (the first registered catalog when
+ * the document omits `default`; nothing when `default` is false). `name:id` resolves in `catalogs.<name>`, then in
+ * the registered catalog for its source. A reference written inside an embedded record resolves in that record's
+ * own group first.
+ */
+/** The content kinds a catalog group holds, keyed by id. */
+declare const catalogKinds: readonly ["layouts", "themes", "colorSchemes", "fontSchemes", "narratives", "audiences", "purposes", "tones"];
+type CatalogKind = (typeof catalogKinds)[number];
+/** A content reference: a bare id or `name:id`. */
+declare const CATALOG_REFERENCE_PATTERN: RegExp;
+/** A catalog group name. `default` and `custom` are reserved. */
+declare const CATALOG_GROUP_PATTERN: RegExp;
+/** Records of one kind, keyed by id. */
+type CatalogRecordMap = Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+/** A catalog's records by kind, then by id: the shape of a document's `catalogs.<group>` without `source`. */
+type CatalogRecords = {
+    readonly [K in CatalogKind]?: CatalogRecordMap;
+};
+/** A catalog a host registers. `source` is matched against `catalogs.<group>.source`. */
+interface Catalog extends CatalogRecords {
+    /** The catalog's identity: an HTTPS URL or a `pkg:` reference. Never fetched. */
+    readonly source: string;
+}
+/** The one option every entry point that resolves references accepts. */
+interface CatalogOptions {
+    /**
+     * Catalogs the host registered, matched by `source`. The first is the host default: bare ids use it when the
+     * document omits `catalogs.default`. Omitted or empty: only the records the document embeds resolve.
+     */
+    catalogs?: readonly Catalog[];
+}
+/** A reference that resolved. */
+interface ResolvedReference {
+    kind: CatalogKind;
+    /** The reference as written. */
+    reference: string;
+    /** The record's key. */
+    id: string;
+    /** The group it resolved in: `custom`, `default` or a named group. */
+    group: string;
+    /** That group's source (the host default's source for an omitted `default`). */
+    source?: string;
+    /** `document` when the record is embedded, `host` when it came from a registered catalog. */
+    origin: 'document' | 'host';
+    record: Record<string, unknown>;
+}
+/**
+ * Where a resolved record came from, without the record itself: what an engine records as provenance
+ * (`resolveSlideContext().resolved.provenance`, `resolveDesignRecords().provenance`).
+ */
+type RecordProvenance = Omit<ResolvedReference, 'record'>;
+/** Reported when a reference resolves nowhere. Never thrown, except under `strictReferences`. */
+interface UnresolvedReferenceDiagnostic {
+    code: 'unresolved-reference';
+    kind: CatalogKind;
+    /** The reference as written, such as `acme:hero`. */
+    reference: string;
+    /** Where it is written, dotted: `slides.3.layout`, `design.theme`, `catalogs.acme.themes.brand.colorScheme`. */
+    path: string;
+    /** The group the reference names: its prefix, or `default` for a bare id. */
+    group: string;
+    /** That group's source, when one is known. */
+    source?: string;
+    /** What the engine uses instead: automatic composition (layouts) or the engine default record. */
+    fallback: 'automatic' | 'engine-default';
+    message: string;
+}
+/** Thrown by `resolveSlideContext` and `paginate` under `strictReferences` when a reference resolves nowhere. */
+/**
+ * Thrown by every entry point that takes the `catalogs` option when it is not an array of registered catalogs
+ * (`{ source: string, <kind>: { <id>: record } }` with known kinds). `code` is always `invalid-catalogs`.
+ */
+declare class OPFCatalogsOptionError extends TypeError {
+    readonly code = "invalid-catalogs";
+    constructor(entry: string, detail: string);
+}
+declare class OPFUnresolvedReferenceError extends Error {
+    readonly diagnostics: UnresolvedReferenceDiagnostic[];
+    constructor(diagnostics: UnresolvedReferenceDiagnostic[]);
+}
+/** Split a reference into its group prefix and id; undefined for anything that is not a reference. */
+declare function parseReference(reference: unknown): {
+    group?: string;
+    id: string;
+} | undefined;
+/**
+ * The source of group `name` as resolution uses it: the group's own `source`, or for an omitted (or source-less)
+ * `default` the first registered catalog's source. Undefined for `custom`, for `default: false` and for an
+ * undeclared named group.
+ */
+declare function catalogGroupSource(document: unknown, name: string, options?: CatalogOptions): string | undefined;
+/**
+ * Resolve one reference. `group` is the group of the record the reference is written in, which is searched first.
+ * Undefined when the reference is malformed, names an undeclared group or resolves nowhere.
+ */
+declare function resolveReference(document: unknown, kind: CatalogKind, reference: unknown, options?: CatalogOptions & {
+    group?: string;
+}): ResolvedReference | undefined;
+/** The diagnostic for a reference that resolves nowhere, naming the reference and the source it was looked for in. */
+declare function unresolvedReference(document: unknown, kind: CatalogKind, reference: string, path: string, options?: CatalogOptions): UnresolvedReferenceDiagnostic;
+/** One place a document writes a content reference. */
+interface CatalogReferenceSite {
+    kind: CatalogKind;
+    /** The reference as written. */
+    reference: string;
+    /** JSON Pointer segments of the string. */
+    path: readonly (string | number)[];
+    /** For a reference written inside an embedded record: that record's group, searched first. */
+    group?: string;
+}
+/**
+ * Every content reference a document writes, in document order: the root narrative, audience, purpose and tone, the
+ * language's font schemes, the deck and slide designs, each slide's layout, and (with `records`) the references
+ * inside embedded records. Free-form audience and purpose text is not a reference and is not listed.
+ */
+declare function catalogReferenceSites(document: unknown, options?: {
+    records?: boolean;
+    slides?: boolean;
+}): CatalogReferenceSite[];
+/** 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 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-CinPh5WA.d.ts

@@ -0,0 +1,12 @@
+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. */
+declare const catalogDisplayKinds: readonly ["chartTypes", "languages", "socialPlatforms"];
+type CatalogDisplayKind = (typeof catalogDisplayKinds)[number];
+/** Every kind of record a catalog publishes: the content kinds documents reference, and the display kinds. */
+type CatalogRecordKind = CatalogKind | CatalogDisplayKind;
+/** The companion schema each catalog record kind validates against. */
+declare const catalogSchemaNames: Readonly<Record<CatalogRecordKind, SchemaName>>;
+
+export { type CatalogDisplayKind as C, type CatalogRecordKind as a, catalogSchemaNames as b, catalogDisplayKinds as c };

package/dist/catalog.d.ts

@@ -0,0 +1,91 @@
+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';
+
+/** A lightweight summary entry inside a catalog's `index.json`. */
+interface CatalogIndexRecord {
+    readonly id: string;
+    readonly name: string;
+    readonly file: string;
+    readonly [key: string]: unknown;
+}
+/** Parsed shape of a catalog's `index.json`. */
+interface CatalogIndex {
+    readonly $schema: string;
+    /** Catalog kind as its default-catalog URL segment, e.g. `chart-types`. */
+    readonly kind?: string;
+    readonly version: string;
+    readonly description: string;
+    /** SHA-256 of the canonical JSON of the index-ordered records (see docs/default-catalog.md). */
+    readonly contentSha256?: string;
+    readonly records: readonly CatalogIndexRecord[];
+    readonly [key: string]: unknown;
+}
+
+interface LayoutPreviewRecord {
+    /** Layout slug — matches `spec/catalogs/layouts/<id>.json` when available, and otherwise the pptx.gallery extended catalog. */
+    id: string;
+    /** Filename relative to `spec/previews/layouts/`. */
+    file: string;
+    /** UTF-8 byte length of the HTML. */
+    bytes: number;
+}
+interface LayoutPreviewIndex {
+    $schema: string;
+    version: string;
+    description: string;
+    records: readonly LayoutPreviewRecord[];
+}
+/**
+ * Static HTML for a given layout preview. Each snippet is a self-contained
+ * Tailwind-styled fragment intended to fill a 16:9 thumbnail container.
+ *
+ * The CSS variables used by the snippets are:
+ *   --background, --foreground, --card, --muted, --muted-foreground,
+ *   --accent, --border
+ *
+ * Consumers should apply these on a parent element (or import the
+ * pptx.gallery design tokens).
+ */
+declare const layoutPreviews: Readonly<Record<string, string>>;
+/** Catalog index — the list of available preview slugs and metadata. */
+declare const layoutPreviewIndex: LayoutPreviewIndex;
+/** Slugs of every layout that ships an HTML preview, sorted alphabetically. */
+declare const layoutPreviewSlugs: readonly string[];
+/** Whether an HTML preview exists for the given slug. */
+declare function hasLayoutPreview(slug: string): boolean;
+/**
+ * Look up the HTML preview for a layout slug. Returns `undefined` for slugs
+ * with no shipped preview — callers should fall back to a generic renderer in
+ * that case. Exported from `@openpresentation/opf/catalog`.
+ */
+declare function getLayoutPreview(slug: string): string | undefined;
+
+/**
+ * `@openpresentation/opf/catalog`: the pinned snapshot of the default catalog pptx.gallery publishes (spec/catalogs,
+ * pinned by spec/catalogs/manifest.json), shaped for hosts to register. The only entry of the package that carries
+ * catalog data; the root and every other subpath resolve only what a document embeds and what a host registers.
+ *
+ * ```js
+ * import { defaultCatalog } from '@openpresentation/opf/catalog';
+ * validate(document, { catalogs: [defaultCatalog] });
+ * ```
+ */
+
+/** The source the default catalog is registered under, and the `source` of a document's `catalogs.default`. */
+declare const DEFAULT_CATALOG_SOURCE = "https://www.pptx.gallery";
+/**
+ * The default catalog: every content record of the snapshot, by kind and then by id, with no `$schema` or `id` (the
+ * key is the id). Register it with every entry point that resolves references: `{ catalogs: [defaultCatalog] }`.
+ */
+declare const defaultCatalog: Catalog;
+/**
+ * Display metadata for pickers: chart types, languages and social platforms by id. Documents never reference these
+ * records; chart.type, the language tag and Socials keys are engine vocabularies.
+ */
+declare const catalogDisplay: Readonly<Record<CatalogDisplayKind, Readonly<Record<string, Readonly<Record<string, unknown>>>>>>;
+/** Each kind's `index.json` in the snapshot: the record summaries and their content hash. */
+declare const catalogIndexes: Readonly<Record<string, CatalogIndex>>;
+
+export { type CatalogIndex, type CatalogIndexRecord, DEFAULT_CATALOG_SOURCE, type LayoutPreviewIndex, type LayoutPreviewRecord, catalogDisplay, catalogIndexes, defaultCatalog, getLayoutPreview, hasLayoutPreview, layoutPreviewIndex, layoutPreviewSlugs, layoutPreviews };