@folienbaukasten/extension-toolkit 1.0.0

package/README.md

@@ -0,0 +1,109 @@
+# `fbk-pack` — the extension toolkit
+
+Builds and checks a Folienbaukasten extension. **It needs no checkout of the
+app.**
+
+```sh
+node ../toolkit/bin/fbk-pack.ts check .     # everything knowable before install
+node ../toolkit/bin/fbk-pack.ts pack .      # → dist/<id>-<version>.fbkset
+node ../toolkit/bin/fbk-pack.ts abi         # what platform this toolkit targets
+```
+
+Every extension in this repo calls it through its own `npm run pack` /
+`npm run check`.
+
+How this fits together, and how to build and publish an extension end to
+end, is [the repository README](../README.md).
+
+## Why it exists
+
+Packaging used to run out of the app's source tree: the packer, the runtime
+shims, the pack format's rules and the theme token contract all lived there,
+so building a `.fbkset` meant having the app checked out at a path your
+`tsconfig.json` knew about. That is the wrong dependency. An extension is
+built against a **published platform**, not against someone's working copy —
+and an extension author is not necessarily an app developer.
+
+So the parts a packer needs are emitted from the app as data and checked in
+here, under [`abi/`](abi/README.md):
+
+| In the bundle | What it is |
+| --- | --- |
+| `abi.json` | ABI major, pack format, the design tokens a theme owes, the named box styles, the swatch tokens, the platform's exports, the layout vocabulary, the built-in theme ids |
+| `pack.js` / `pack.d.ts` | the app's own `src/sets/pack.ts`, compiled — so the manifest rules enforced here are the *same code* the app runs at install, not a second implementation that can disagree |
+| `shims/*.js` | the `react`, `react/jsx-runtime` and `@folienbaukasten/platform` shims a pack is built against |
+| `types/` | declarations for `@folienbaukasten/platform`, so `tsconfig.json` maps the platform at the ABI rather than at a path into the app |
+| `provenance.json` | which app build emitted the bundle — for a person, never read to decide anything, and excluded from the drift check so that check fires on a changed *contract* rather than on a changed commit |
+
+Refresh it from the app repo, whose `npm run check` also fails if this copy
+has drifted from what it would emit:
+
+```sh
+cd <app repo> && npm run abi:emit
+```
+
+## What `check` checks
+
+Packing runs all of it first: a pack that would not install is not written.
+Everything is reported in one pass — a tool that reports one problem per
+attempt is how an extension author gives up.
+
+**The manifest** — id shape, an id that shadows no built-in theme, semver,
+the declared platform ABI, template ids, `provides`, and component kinds
+namespaced by the pack id. This is `manifestProblems` from the bundle: the
+function the app runs at install time.
+
+**The theme contract** — every custom property the platform reads without a
+fallback, and all ten named box styles. *Nothing checked this for an
+out-of-repo theme before.* A missing token silently degraded the rendering,
+on the user's machine, with no message anywhere. A missing swatch is a
+warning: the theme installs, the chooser just shows it without its palette.
+
+**The components** —
+
+- each `schemaType` resolves and generates a JSON Schema from the author's
+  TypeScript;
+- each `example` validates against the schema generated from its own type —
+  a pack whose own example fails its own schema does not build;
+- each `glyph` exists, is an SVG, and is under 16 KB;
+- `pack.json` and `index.ts` agree: no kind declared but unregistered (the
+  app would offer the slide type and then blank the body), none registered
+  but undeclared (no description, schema or glyph — so the model never writes
+  it), no `webOnly` that differs between the two (a web-only component
+  declared PPTX-safe exports as a silently blank region), and the set's own
+  `id` equal to the pack's.
+
+That last group needs the built module, so `check` builds one into a
+temporary file and imports it with a stand-in for the set runtime. If the
+module's top-level code throws, the group degrades to a warning rather than
+blocking the pack.
+
+**Intent** — warnings, not errors: a theme without `production: true`
+installs but never appears in the chooser; a pack without a `publisher` gives
+the install dialog no name to show; a template naming another theme opens in
+that other theme.
+
+## What it does not do
+
+Rendering. Screenshots, PPTX export and installing into a running app all go
+through the app itself:
+
+```sh
+PPT_SETS_ROOT=$PWD/.dev-sets node <app>/tools/install-set.ts dist/<pack>.fbkset
+PPT_SETS_ROOT=$PWD/.dev-sets node <app>/tools/export.ts --deck templates/x.json --out out/deck.pptx
+```
+
+That is the honest split: *packaging* is a contract, and the contract is in
+this repo; *rendering* is the app, and only the app has it.
+
+## Reproducibility
+
+Two builds of an unchanged extension are byte-identical: file dates are
+fixed, and no directory entries are written (JSZip stamps those with the
+current time whatever date you ask for — which is what used to make packs
+differ run to run; install skips directory entries anyway).
+
+The dependency versions in `package.json` are pinned to the ones the app's
+packer used, `esbuild` above all: a different minifier is a different
+`set.js`. Every extension in this repo was migrated onto this toolkit and
+verified to produce byte-identical pack contents.

package/abi/README.md

@@ -0,0 +1,20 @@
+# Generated — do not edit
+
+This directory is the extension ABI bundle, emitted from the app by
+`node tools/emit-abi.ts --out <here>`. It is what lets an extension be
+built and checked without a checkout of the app.
+
+Platform ABI 1, pack format 2.
+Which app build it came from is in provenance.json — deliberately not in
+abi.json, so the drift check fires on a changed contract and not on a
+changed commit.
+
+Refresh it after any change to the platform surface, the pack format,
+the runtime shims, or the design tokens the platform reads:
+
+```sh
+cd <app repo> && npm run abi:emit
+```
+
+Anything an extension needs that is missing here is a gap in the ABI,
+not a reason to reach back into the app source.

package/abi/abi.json

@@ -0,0 +1,151 @@
+{
+  "platformAbi": 1,
+  "packFormatVersion": 2,
+  "supportedPackFormats": [
+    1,
+    2
+  ],
+  "platformExports": [
+    "Block",
+    "BlockArrow",
+    "Card",
+    "ChartView",
+    "ContentSlide",
+    "DriverTree",
+    "FindingsBanner",
+    "HARVEY_SIZE_PX",
+    "HARVEY_STROKE_PX",
+    "HarveyBall",
+    "InsightRail",
+    "KpiTile",
+    "LABEL_MIN_GAP",
+    "Matrix",
+    "QuoteColumn",
+    "SLIDE_HEIGHT",
+    "SLIDE_WIDTH",
+    "SlideFrame",
+    "SourceLine",
+    "Table",
+    "Timeline",
+    "bandCentre",
+    "bandCentreX",
+    "bandCentreY",
+    "formatNumber",
+    "headerTitle",
+    "platformDefaults",
+    "spreadLabels",
+    "valueY"
+  ],
+  "requiredTokens": [
+    "--banner-height",
+    "--border-width",
+    "--box-dir",
+    "--box-gap",
+    "--box-padding",
+    "--chart-1",
+    "--chart-2",
+    "--chart-3",
+    "--chart-4",
+    "--chart-5",
+    "--chart-6",
+    "--chart-neutral",
+    "--chrome-header-max-h",
+    "--color-accent",
+    "--color-accent-deep",
+    "--color-accent-soft",
+    "--color-bg",
+    "--color-box-bg",
+    "--color-box-border",
+    "--color-edge-muted",
+    "--color-highlight",
+    "--color-highlight-deep",
+    "--color-highlight-soft",
+    "--color-negative",
+    "--color-positive",
+    "--color-text",
+    "--color-text-faint",
+    "--color-text-inverse",
+    "--color-text-muted",
+    "--edge-h",
+    "--edge-w",
+    "--font-family",
+    "--gradient-accent-from",
+    "--gradient-accent-to",
+    "--gradient-soft-from",
+    "--gradient-soft-to",
+    "--line-height",
+    "--radius",
+    "--radius-lg",
+    "--radius-md",
+    "--shadow-lifted",
+    "--shadow-soft",
+    "--space-1",
+    "--space-12",
+    "--space-2",
+    "--space-3",
+    "--space-4",
+    "--space-6",
+    "--space-8",
+    "--text-2xl",
+    "--text-lg",
+    "--text-md",
+    "--text-sm",
+    "--text-xl",
+    "--text-xs",
+    "--weight-bold",
+    "--weight-medium",
+    "--weight-regular"
+  ],
+  "optionalTokens": [
+    "--font-display"
+  ],
+  "requiredBoxStyles": [
+    "box-card",
+    "box-card-emphasis",
+    "box-card-light",
+    "box-callout",
+    "box-stat",
+    "box-edge",
+    "box-title",
+    "box-body",
+    "box-banner-label",
+    "box-banner-body"
+  ],
+  "swatchTokens": {
+    "bg": "--color-bg",
+    "surface": "--color-box-bg",
+    "ink": "--color-text",
+    "accent": "--color-accent",
+    "highlight": "--color-highlight"
+  },
+  "layouts": [
+    "agenda",
+    "cards",
+    "chapters",
+    "chart",
+    "component",
+    "driver-tree",
+    "freeform",
+    "kpis",
+    "matrix",
+    "quote",
+    "quotes",
+    "split",
+    "table",
+    "timeline",
+    "title",
+    "two-block",
+    "web",
+    "while-arrow"
+  ],
+  "builtInSetIds": [
+    "consulting",
+    "corporate",
+    "editorial",
+    "forest",
+    "heritage",
+    "keynote",
+    "picnic",
+    "signal"
+  ]
+}

package/abi/pack.d.ts

@@ -0,0 +1,196 @@
+/**
+ * `.fbkset` theme packs — the installable form of a component set (ui.md A9).
+ *
+ * A pack is a zip, the same move `.fbk` makes for decks (project/bundle.ts):
+ * one file that can be mailed, double-clicked, or downloaded. Installing it
+ * extracts it under `userData/sets/<id>/<major>/`; from there it is served at
+ * `/sets/<id>/…` and `src/sets/loader.ts` loads it beside the compiled-in
+ * sets, returning the same `ComponentSet` the renderer already consumes.
+ *
+ *   manifest.json    what this file describes — id, version, ABI, publisher
+ *   set.js           prebuilt ESM, default-exporting a ComponentSet
+ *   set.css          the theme's tokens (the `import './theme.css'` output)
+ *   guide.md         optional LLM guidance, appended to GUIDE.md when active
+ *   templates/*.json optional starter decks, offered in the New Deck dialog
+ *   preview.png      optional picture for the chooser
+ *   signature.json   optional Ed25519 signature over the other files
+ *
+ * This module is types and pure functions only: main validates packs with
+ * it at install time, the renderer reads the installed index with it, and
+ * tools/pack-set.ts writes manifests with it. Nothing here touches fs or
+ * electron.
+ */
+/** Bumped when the pack layout itself changes shape. v2 added `provides`,
+ * per-component metadata and web-only declarations; v1 packs still install — they are
+ * simply themes that provide no components. */
+export declare const PACK_FORMAT_VERSION = 2;
+/** Formats this app still reads. */
+export declare const SUPPORTED_PACK_FORMATS: readonly number[];
+/**
+ * The platform ABI a pack is built against: the `ComponentSet` interface
+ * plus the `data-pptx` tagging contract the exporter measures
+ * (src/export/types.ts). A set that renders untagged markup produces a
+ * broken PPTX, which is why this is versioned separately from the app and
+ * checked at install time rather than discovered at export time.
+ *
+ * Major changes break packs; minor additions do not. A pack declares the
+ * major it was built for and is accepted while that major still matches.
+ */
+export declare const PLATFORM_ABI = 1;
+export declare const PACK_EXT = ".fbkset";
+/** Files every pack must contain. A pack that provides a theme additionally
+ * needs `set.css` — see `requiredPackFiles`. */
+export declare const REQUIRED_PACK_FILES: readonly ['manifest.json', 'set.js'];
+/** What an extension provides. Absent in a manifest = `['theme']`, which is
+ * every v1 pack. */
+export type PackProvides = 'theme' | 'components';
+/** One extension-supplied slide component, as the manifest declares it. */
+export interface PackComponentMeta {
+    /** Namespaced kind: `<pack id>/<component-name>`. */
+    kind: string;
+    /** One line for the sidebar and the LLM prompt. */
+    description?: string;
+    /** JSON Schema for the component's props, generated from the author's
+     * TypeScript by tools/pack-set.ts. Absent = unvalidated. */
+    schema?: unknown;
+    /**
+     * Worked example props, valid against `schema` — the pack ships the *data*,
+     * never a picture. The app
+     * renders it through its own thumbnail path to show the component in the
+     * editor, and hands it to the model as a usage example. Absent costs the
+     * component its preview and nothing else.
+     */
+    example?: unknown;
+    /**
+     * Pack-relative path to a stylized SVG for the components view — the
+     * author's own diagram of what this component draws, in the app's palette. Preferred over the
+     * rendered example: it is legible at card size, costs no render, and is the
+     * only thing a catalogue can show for an extension that is not installed.
+     *
+     * It is displayed as an *image*, never inlined into the editor's DOM —
+     * scripts do not run and external references do not load in that context,
+     * which is what makes author-supplied markup safe here at all.
+     */
+    glyph?: string;
+    /** The component is interactive, animated or otherwise unmeasurable: it
+     * only validates in a Web Mode deck. */
+    webOnly?: boolean;
+}
+export interface SetPackManifest {
+    formatVersion: number;
+    /** Folder name and `meta.componentSet` value. Lowercase, url-safe. */
+    id: string;
+    name: string;
+    description?: string;
+    /** Semver. The major decides which install slot the pack occupies. */
+    version: string;
+    /** Platform ABI major this pack was built against. */
+    platformAbi: number;
+    /** Who made it — shown in the install dialog beside the trust verdict. */
+    publisher?: string;
+    /** Offer it in the theme chooser. Absent = installed but not promoted. */
+    production?: boolean;
+    /** Palette preview for the chooser, same five colours the catalog carries. */
+    swatch?: PackSwatch;
+    /** Starter decks shipped with the theme, in the order they are offered. */
+    templates?: PackTemplate[];
+    /** Per-layout advice that replaces the platform description in the prompt. */
+    layoutDescriptions?: Record<string, string>;
+    /** What the pack ships. Absent = `['theme']` (every v1 pack). A
+     * components-only pack carries no `set.css` and no chrome, and is never
+     * offered as a theme — its components render under any theme. */
+    provides?: PackProvides[];
+    /** Slide components the pack ships, when `provides` includes 'components'. */
+    components?: PackComponentMeta[];
+    /**
+     * The theme keeps every "Rules that keep HTML ↔ PPTX identical" rule and is
+     * safe for PowerPoint-mode decks. Absent = true. A web-only theme
+     * (`pptxSafe: false`) uses CSS the exporter cannot measure and is offered
+     * only to Web Mode decks.
+     */
+    pptxSafe?: boolean;
+}
+/** Whether a manifest provides the given capability. */
+export declare function packProvides(manifest: SetPackManifest, what: PackProvides): boolean;
+/** The files this particular pack must contain. */
+export declare function requiredPackFiles(manifest: SetPackManifest): string[];
+export interface PackSwatch {
+    bg: string;
+    surface: string;
+    ink: string;
+    accent: string;
+    highlight: string;
+}
+export interface PackTemplate {
+    /** File under templates/, without the .json. */
+    id: string;
+    name: string;
+    description?: string;
+}
+/** Ed25519 over the sorted `sha256(file)` digests of every other pack file. */
+export interface PackSignature {
+    algorithm: 'ed25519';
+    /** Key id, so a rotated key can still verify what the old one signed. */
+    keyId: string;
+    /** Base64 signature over `signingPayload()`. */
+    signature: string;
+}
+/**
+ * What a signature covers: every file in the pack except the signature
+ * itself, as `path\tsha256hex` lines, sorted. Signing the digests rather
+ * than the zip means a pack stays verifiable after extraction — which is
+ * what lets the app re-check an *installed* set, not just an incoming file.
+ */
+export declare function signingPayload(digests: Record<string, string>): string;
+/**
+ * Whether a pack's code is known to come from a publisher we trust.
+ *
+ * This is a *label*, never a gate: an unsigned pack installs and runs with
+ * exactly the same capability as a signed one. The distinction the user is
+ * shown is honest about what it means — a theme is code running in the
+ * renderer, and a signature says who wrote it, not that it is harmless.
+ */
+export type PackTrust = 'verified' | 'untrusted';
+/** An installed pack, as the app and the renderer see it. */
+export interface InstalledSet {
+    id: string;
+    name: string;
+    description?: string;
+    version: string;
+    publisher?: string;
+    production?: boolean;
+    swatch?: PackSwatch;
+    templates?: PackTemplate[];
+    layoutDescriptions?: Record<string, string>;
+    provides?: PackProvides[];
+    components?: PackComponentMeta[];
+    pptxSafe?: boolean;
+    trust: PackTrust;
+    /** Root-relative base every pack file is served under: `/sets/<id>`. */
+    base: string;
+    /** ISO timestamp of the install, for the manage list. */
+    installedAt: string;
+    /** Pack ships a guide.md the system prompt should pick up. */
+    hasGuide?: boolean;
+}
+/** Served at `/sets/index.json`; the loader's whole view of what is installed. */
+export interface SetsIndex {
+    sets: InstalledSet[];
+}
+/** Ids the platform owns; a pack may not shadow one of the compiled-in sets. */
+export declare function reservedIds(builtIn: readonly string[]): Set<string>;
+export declare function majorOf(version: string): number;
+/** Compare two semvers; >0 when `a` is newer. Pre-release tags are ignored. */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * Everything wrong with a manifest, in one pass — an install dialog that
+ * reports one problem per attempt is how a theme author gives up.
+ * Empty array = installable.
+ */
+export declare function manifestProblems(value: unknown, builtIn?: readonly string[]): string[];
+/** The `InstalledSet` view of a manifest, once it is on disk. */
+export declare function installedSetOf(manifest: SetPackManifest, extra: {
+    trust: PackTrust;
+    installedAt: string;
+    hasGuide: boolean;
+}): InstalledSet;

package/abi/pack.js

@@ -0,0 +1,126 @@
+// src/sets/pack.ts
+var PACK_FORMAT_VERSION = 2;
+var SUPPORTED_PACK_FORMATS = [1, 2];
+var PLATFORM_ABI = 1;
+var PACK_EXT = ".fbkset";
+var REQUIRED_PACK_FILES = ["manifest.json", "set.js"];
+function packProvides(manifest, what) {
+  return (manifest.provides ?? ["theme"]).includes(what);
+}
+function requiredPackFiles(manifest) {
+  return [...REQUIRED_PACK_FILES, ...packProvides(manifest, "theme") ? ["set.css"] : []];
+}
+function signingPayload(digests) {
+  return Object.entries(digests).filter(([file]) => file !== "signature.json").map(([file, hash]) => `${file}	${hash}`).sort().join("\n");
+}
+var ID_RE = /^[a-z][a-z0-9-]*(?:\.[a-z0-9][a-z0-9-]*)*[a-z0-9]$/;
+var ID_MAX = 40;
+var SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)(?:-[0-9a-z.-]+)?$/i;
+function reservedIds(builtIn) {
+  return new Set(builtIn);
+}
+function majorOf(version) {
+  const m = SEMVER_RE.exec(version);
+  return m ? Number(m[1]) : 0;
+}
+function compareVersions(a, b) {
+  const pa = SEMVER_RE.exec(a);
+  const pb = SEMVER_RE.exec(b);
+  if (!pa || !pb) return a.localeCompare(b);
+  for (let i = 1; i <= 3; i++) {
+    const d = Number(pa[i]) - Number(pb[i]);
+    if (d !== 0) return d;
+  }
+  return 0;
+}
+function manifestProblems(value, builtIn = []) {
+  const out = [];
+  if (typeof value !== "object" || value === null) return ["manifest.json is not an object"];
+  const m = value;
+  if (!SUPPORTED_PACK_FORMATS.includes(m.formatVersion)) {
+    out.push(
+      `manifest formatVersion is ${String(m.formatVersion)}, this app reads ` + SUPPORTED_PACK_FORMATS.join(" and ")
+    );
+  }
+  if (typeof m.id !== "string" || !ID_RE.test(m.id) || m.id.length > ID_MAX) {
+    out.push(
+      `"${String(m.id)}" is not a usable extension id \u2014 lowercase letters, digits and dashes, optionally as publisher.name, at most ${ID_MAX} characters`
+    );
+  } else if (reservedIds(builtIn).has(m.id)) {
+    out.push(`"${m.id}" is the id of a theme built into the app`);
+  }
+  if (typeof m.name !== "string" || m.name.trim() === "") out.push("manifest has no name");
+  if (typeof m.version !== "string" || !SEMVER_RE.test(m.version)) {
+    out.push(`"${String(m.version)}" is not a version number (e.g. 1.0.0)`);
+  }
+  if (m.platformAbi !== PLATFORM_ABI) {
+    out.push(
+      `theme was built for platform ${String(m.platformAbi)}; this app provides ${PLATFORM_ABI}`
+    );
+  }
+  for (const t of m.templates ?? []) {
+    if (typeof t?.id !== "string" || !/^[a-z0-9][a-z0-9-]*$/.test(t.id)) {
+      out.push(`"${String(t?.id)}" is not a usable template id`);
+    }
+  }
+  if (m.provides !== void 0) {
+    if (!Array.isArray(m.provides) || m.provides.length === 0) {
+      out.push('manifest "provides" must be a non-empty array of "theme" / "components"');
+    } else {
+      for (const p of m.provides) {
+        if (p !== "theme" && p !== "components") {
+          out.push(`"${String(p)}" is not something a pack can provide`);
+        }
+      }
+    }
+  }
+  const providesComponents = (m.provides ?? ["theme"]).includes("components");
+  if (providesComponents && !(Array.isArray(m.components) && m.components.length > 0)) {
+    out.push("the pack claims to provide components but declares none");
+  }
+  for (const c of m.components ?? []) {
+    if (typeof c?.kind !== "string" || !c.kind.startsWith(`${String(m.id)}/`)) {
+      out.push(
+        `component kind "${String(c?.kind)}" must be namespaced by the pack id ("${String(m.id)}/\u2026")`
+      );
+    } else if (!/^[a-z][a-z0-9.-]*\/[a-z][a-z0-9-]*$/.test(c.kind)) {
+      out.push(`"${c.kind}" is not a usable component kind (lowercase letters, digits, dashes)`);
+    }
+  }
+  return out;
+}
+function installedSetOf(manifest, extra) {
+  return {
+    id: manifest.id,
+    name: manifest.name,
+    ...manifest.description ? { description: manifest.description } : {},
+    version: manifest.version,
+    ...manifest.publisher ? { publisher: manifest.publisher } : {},
+    ...manifest.production ? { production: true } : {},
+    ...manifest.swatch ? { swatch: manifest.swatch } : {},
+    ...manifest.templates?.length ? { templates: manifest.templates } : {},
+    ...manifest.layoutDescriptions ? { layoutDescriptions: manifest.layoutDescriptions } : {},
+    ...manifest.provides ? { provides: manifest.provides } : {},
+    ...manifest.components?.length ? { components: manifest.components } : {},
+    ...manifest.pptxSafe === false ? { pptxSafe: false } : {},
+    trust: extra.trust,
+    base: `/sets/${manifest.id}`,
+    installedAt: extra.installedAt,
+    ...extra.hasGuide ? { hasGuide: true } : {}
+  };
+}
+export {
+  PACK_EXT,
+  PACK_FORMAT_VERSION,
+  PLATFORM_ABI,
+  REQUIRED_PACK_FILES,
+  SUPPORTED_PACK_FORMATS,
+  compareVersions,
+  installedSetOf,
+  majorOf,
+  manifestProblems,
+  packProvides,
+  requiredPackFiles,
+  reservedIds,
+  signingPayload
+};

package/abi/provenance.json

@@ -0,0 +1,5 @@
+{
+  "app": "0.5.0",
+  "commit": "12bedfc",
+  "emittedAt": "2026-09-13T17:50:33.133Z"
+}

package/abi/shims/jsx-runtime.js

@@ -0,0 +1,13 @@
+// Injected in place of `react/jsx-runtime` and `react/jsx-dev-runtime`.
+// See tools/set-shims/react.js for why a pack may not bundle its own.
+const runtime = globalThis.__FBK_SET_RUNTIME__;
+if (!runtime) {
+  throw new Error('This theme was loaded without the Folien Baukasten set runtime.');
+}
+const jsxRuntime = runtime.jsxRuntime;
+export const Fragment = jsxRuntime.Fragment;
+export const jsx = jsxRuntime.jsx;
+export const jsxs = jsxRuntime.jsxs;
+// The dev runtime's extra arguments are ignored by the production one, which
+// is what a pack is always built against.
+export const jsxDEV = jsxRuntime.jsx;

package/abi/shims/platform.js

@@ -0,0 +1,48 @@
+// Injected in place of `@folienbaukasten/platform` — the surface a theme pack
+// is allowed to build against (src/sets/platform.ts). Resolved at load time
+// from the app's own module instances, so a pack shares the platform's React
+// components rather than carrying a snapshot of them.
+//
+// The lists below have to name every VALUE export of src/sets/platform.ts —
+// ESM named exports cannot be spread from a runtime object. Miss one and
+// `npm run pack:set` fails on that name, which is the intended failure: it
+// is loud, and it happens to whoever added the export.
+const runtime = globalThis.__FBK_SET_RUNTIME__;
+if (!runtime) {
+  throw new Error('This theme was loaded without the Folien Baukasten set runtime.');
+}
+const platform = runtime.platform;
+
+// Every value export of src/sets/platform.ts, named so it can be re-exported.
+const NAMES = [
+  'Block', 'BlockArrow', 'Card', 'ChartView', 'ContentSlide', 'DriverTree',
+  'FindingsBanner', 'HarveyBall', 'HARVEY_SIZE_PX', 'HARVEY_STROKE_PX',
+  'InsightRail', 'KpiTile', 'Matrix', 'QuoteColumn', 'SlideFrame',
+  'SourceLine', 'Table', 'Timeline', 'formatNumber', 'headerTitle',
+  'platformDefaults', 'SLIDE_HEIGHT', 'SLIDE_WIDTH',
+  'bandCentre', 'bandCentreX', 'bandCentreY', 'spreadLabels', 'valueY',
+  'LABEL_MIN_GAP',
+];
+
+// A theme built against a NEWER app than the one loading it destructures
+// `undefined` here and dies later, inside React, as a blank slide with no
+// clue attached. Fail at load instead, naming what is missing: the loader
+// already has a path for a theme that will not load (the deck renders in
+// the default theme and the slides say so), and "the app is older than the
+// theme" is something a person can act on.
+const missing = NAMES.filter((name) => platform[name] === undefined);
+if (missing.length > 0) {
+  throw new Error(
+    `This theme needs platform features this app does not have: ${missing.join(', ')}. ` +
+      'The app is older than the theme — update the app, or install a build of the ' +
+      'theme made for it.',
+  );
+}
+
+export const {
+  Block, BlockArrow, Card, ChartView, ContentSlide, DriverTree, FindingsBanner,
+  HarveyBall, HARVEY_SIZE_PX, HARVEY_STROKE_PX, InsightRail, KpiTile, Matrix,
+  QuoteColumn, SlideFrame, SourceLine, Table, Timeline, formatNumber,
+  headerTitle, platformDefaults, SLIDE_HEIGHT, SLIDE_WIDTH,
+  bandCentre, bandCentreX, bandCentreY, spreadLabels, valueY, LABEL_MIN_GAP,
+} = platform;