@kadal/deck 0.0.0-stage → 0.1.0

package/dist/renderers/contract.d.ts

@@ -0,0 +1,173 @@
+//#region src/renderers/contract.d.ts
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * THE RENDERER CONTRACT
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * A slide is HTML. Nothing about that requires the thing drawn inside it to be React, and this is
+ * the seam where every other framework gets in: a renderer knows how to put one framework's
+ * component into an element and how to take it out again, and the engine knows nothing else about
+ * it. Astro's islands are the same idea — static page, small pieces of framework, each with its own
+ * runtime bundled separately so a Vue slide never ships React.
+ *
+ * WHY A MARKER AND NOT A SNIFF
+ *
+ * The obvious design is for each renderer to recognise its own components. It cannot: a React
+ * component and a Solid component are both plain functions, and no amount of looking at one tells
+ * you which runtime it was written for. Svelte and Angular do not even have a virtual DOM — their
+ * reactivity is produced by their compilers, so there is nothing at runtime to recognise.
+ *
+ * So the build says so, not the engine. A `.vue` file goes through the Vue plugin, which stamps
+ * `DECK_RENDERER` onto what it exports; an author can say `framework="vue"` by hand. `owns()` is
+ * the last resort, for the renderers that genuinely can tell — a web component is a tag name with a
+ * hyphen in it, and that is unambiguous.
+ *
+ * WHAT A RENDERER MUST SURVIVE
+ *
+ * A deck shows the same slide in several places at once: the stage, the presenter's current-slide
+ * box, an overview tile, the audience's mirror, a print page. So `mount` is called more than once
+ * for the same component, on different elements, and may be torn down and mounted again as the
+ * presenter moves. Keep per-mount state on the mount, never in the module.
+ */
+/** Whatever a framework calls a component. The engine never looks inside one. */
+export type IslandComponent = unknown;
+export type IslandProps = Record<string, unknown>;
+/**
+ * Stamped onto a component by a framework's build plugin (or by hand) to say which renderer owns
+ * it. Checked before `owns()`, because a stamp is knowledge and a sniff is a guess.
+ */
+export declare const DECK_RENDERER: unique symbol;
+/** A component carrying its renderer's name. */
+export interface MarkedComponent {
+  [DECK_RENDERER]?: string;
+}
+export interface RenderContext {
+  /**
+   * The component's children, already rendered to HTML.
+   *
+   * Cross-framework children are HTML and not a live tree, deliberately: a React subtree cannot
+   * keep its state inside a Vue component, and pretending otherwise would produce the kind of bug
+   * nobody can explain. Markdown inside an island arrives as markup; interactivity inside an
+   * island belongs to that island's framework.
+   */
+  slot?: string;
+  /** The deck's colour scheme at mount, for frameworks that theme once rather than reactively. */
+  scheme?: "light" | "dark";
+  /**
+   * False while printing, exporting, or where the viewer asked for reduced motion. A renderer that
+   * starts a loop should not start one.
+   */
+  animate: boolean;
+}
+/** A live island. The engine holds this and calls it when the slide moves on. */
+export interface IslandMount {
+  /** Undo everything: unmount, drop listeners, stop loops. Must be safe to call twice. */
+  destroy(): void;
+  /**
+   * New props without a teardown. Optional — the engine remounts when a renderer cannot update,
+   * which is correct but loses the island's internal state, so implement this where it is cheap.
+   */
+  update?(props: IslandProps): void;
+}
+export interface DeckRenderer {
+  /** `framework="…"` names this. Lowercase, hyphenated: `react`, `web-components`, `vue`. */
+  readonly name: string;
+  /**
+   * Last-resort recognition, for renderers that can genuinely tell. Return false when unsure —
+   * a wrong yes is worse than no answer, because it takes the component away from the renderer
+   * that did know.
+   */
+  owns?(component: IslandComponent): boolean;
+  /** Put the component in the element and keep it alive. */
+  mount(host: Element, component: IslandComponent, props: IslandProps, context: RenderContext): IslandMount;
+  /**
+   * HTML for a surface that will never hydrate — a print page, an export frame, a thumbnail.
+   * Optional: without it such a surface shows the island's fallback instead.
+   */
+  ssr?(component: IslandComponent, props: IslandProps, context: RenderContext): string | Promise<string>;
+  /**
+   * The renderer whose components the deck runtime can draw directly, without an island. There is
+   * exactly one — React today — and marking it lets `<Island>` keep such components inside the
+   * React tree, where the deck's own context (clicks, theme, the live room) still reaches them.
+   */
+  readonly native?: boolean;
+}
+/**
+ * Add a renderer. Registration order is `owns()` order, so a renderer that recognises broadly
+ * should be registered after one that recognises precisely. Registering a name twice replaces the
+ * first, which is what a dev server doing hot reload needs.
+ */
+export declare function registerRenderer(renderer: DeckRenderer): void;
+export declare function registeredRenderers(): readonly DeckRenderer[];
+export declare function rendererNamed(name: string): DeckRenderer | null;
+/** The renderer the deck runtime draws directly, if one is registered. */
+export declare function nativeRenderer(): DeckRenderer | null;
+/** Forget every renderer. For tests; nothing in the engine calls this. */
+export declare function clearRenderers(): void;
+/**
+ * WHY A FRAMEWORK MUST BE ABLE TO ARRIVE LATE
+ *
+ * Registering a renderer imports it, and importing it imports its framework. Measured on the
+ * showcase deck, registering Vue eagerly put 64 kB (25 kB gzipped) of Vue runtime into the first
+ * chunk — paid on slide one, by every viewer, for one island nineteen slides away. Ten frameworks
+ * would make that a quarter of a megabyte of runtimes a given deck never runs.
+ *
+ * So a renderer may be registered as a name and an import instead. Resolution by name
+ * (`framework="vue"`) and by stamp (`DECK_RENDERER`) both work on a string, so the engine can know
+ * which renderer a component needs before that renderer's code exists in the page — which is the
+ * whole trick, and the reason the contract went to a marker rather than a sniff.
+ *
+ * The cost is deliberate and small: `owns()` cannot run for a renderer that has not loaded, so a
+ * deferred renderer's components must be named or stamped. A web component is recognised by its tag
+ * and React is the native one, so neither is affected.
+ */
+export type RendererLoader = () => Promise<DeckRenderer | {
+  default: DeckRenderer;
+}>;
+/**
+ * Register a renderer by name, loading it only when a slide actually needs it.
+ *
+ *     registerLazyRenderer("vue", () => import("@kadal/deck-vue").then((m) => m.vueRenderer));
+ *
+ * An eager registration of the same name wins: it is already here, so there is nothing to wait for.
+ */
+export declare function registerLazyRenderer(name: string, load: RendererLoader): void;
+/** Names that are registered, loaded or not. */
+export declare function knownRendererNames(): string[];
+/**
+ * The renderer called `name`, loading it if that is what it takes. Null when no such renderer is
+ * registered, or when its import failed — a failed import is reported once and then retried on the
+ * next ask, because a deck that lost its network on slide three should recover on slide four.
+ */
+export declare function loadRenderer(name: string): Promise<DeckRenderer | null>;
+export type Resolution = {
+  renderer: DeckRenderer;
+  how: "named" | "marked" | "owned";
+} |
+/** A renderer by this name is registered but not loaded. `loadRenderer(name)` finishes the job. */
+{
+  renderer: null;
+  how: "deferred";
+  name: string;
+} | {
+  renderer: null;
+  how: "unknown";
+  reason: string;
+};
+/**
+ * Which renderer draws this component, and on what grounds.
+ *
+ * The order is deliberate: what the author said, then what the build stamped, then what a renderer
+ * can prove about the component itself. `how` is carried out of here so a failure can say which
+ * step it got to rather than "no renderer".
+ */
+export declare function resolveRenderer(component: IslandComponent, framework?: string): Resolution;
+/**
+ * Resolution, including the renderers that have to be fetched first.
+ *
+ * This is what the engine calls. The synchronous `resolveRenderer` above stays exactly as honest as
+ * it was — it reports what is in the page right now — and this one takes its `deferred` answer and
+ * finishes it.
+ */
+export declare function resolveRendererAsync(component: IslandComponent, framework?: string): Promise<Resolution>;
+//#endregion

package/dist/renderers/contract.js

@@ -0,0 +1,152 @@
+//#region src/renderers/contract.ts
+/**
+* Stamped onto a component by a framework's build plugin (or by hand) to say which renderer owns
+* it. Checked before `owns()`, because a stamp is knowledge and a sniff is a guess.
+*/
+const DECK_RENDERER = Symbol.for("deck.renderer");
+const registry = [];
+/**
+* Add a renderer. Registration order is `owns()` order, so a renderer that recognises broadly
+* should be registered after one that recognises precisely. Registering a name twice replaces the
+* first, which is what a dev server doing hot reload needs.
+*/
+function registerRenderer(renderer) {
+	const at = registry.findIndex((r) => r.name === renderer.name);
+	if (at >= 0) registry[at] = renderer;
+	else registry.push(renderer);
+}
+function registeredRenderers() {
+	return registry;
+}
+function rendererNamed(name) {
+	return registry.find((r) => r.name === name) ?? null;
+}
+/** The renderer the deck runtime draws directly, if one is registered. */
+function nativeRenderer() {
+	return registry.find((r) => r.native) ?? null;
+}
+/** Forget every renderer. For tests; nothing in the engine calls this. */
+function clearRenderers() {
+	registry.length = 0;
+	deferred.clear();
+}
+const deferred = /* @__PURE__ */ new Map();
+const loading = /* @__PURE__ */ new Map();
+/**
+* Register a renderer by name, loading it only when a slide actually needs it.
+*
+*     registerLazyRenderer("vue", () => import("@kadal/deck-vue").then((m) => m.vueRenderer));
+*
+* An eager registration of the same name wins: it is already here, so there is nothing to wait for.
+*/
+function registerLazyRenderer(name, load) {
+	deferred.set(name, load);
+}
+/** Names that are registered, loaded or not. */
+function knownRendererNames() {
+	return [.../* @__PURE__ */ new Set([...registry.map((r) => r.name), ...deferred.keys()])];
+}
+/**
+* The renderer called `name`, loading it if that is what it takes. Null when no such renderer is
+* registered, or when its import failed — a failed import is reported once and then retried on the
+* next ask, because a deck that lost its network on slide three should recover on slide four.
+*/
+function loadRenderer(name) {
+	const here = rendererNamed(name);
+	if (here) return Promise.resolve(here);
+	const inFlight = loading.get(name);
+	if (inFlight) return inFlight;
+	const load = deferred.get(name);
+	if (!load) return Promise.resolve(null);
+	const promise = load().then((module) => {
+		const renderer = module && typeof module === "object" && "default" in module ? module.default : module;
+		if (!renderer || typeof renderer.mount !== "function") throw new Error(`the module registered for “${name}” did not export a renderer`);
+		registerRenderer(renderer);
+		return renderer;
+	}).catch((error) => {
+		console.error(`[deck] could not load the “${name}” renderer:`, error);
+		return null;
+	}).finally(() => {
+		loading.delete(name);
+	});
+	loading.set(name, promise);
+	return promise;
+}
+/**
+* Which renderer draws this component, and on what grounds.
+*
+* The order is deliberate: what the author said, then what the build stamped, then what a renderer
+* can prove about the component itself. `how` is carried out of here so a failure can say which
+* step it got to rather than "no renderer".
+*/
+function resolveRenderer(component, framework) {
+	if (framework) {
+		const named = rendererNamed(framework);
+		if (named) return {
+			renderer: named,
+			how: "named"
+		};
+		if (deferred.has(framework)) return {
+			renderer: null,
+			how: "deferred",
+			name: framework
+		};
+		const known = knownRendererNames();
+		return {
+			renderer: null,
+			how: "unknown",
+			reason: `no renderer named “${framework}” is registered${known.length ? ` (have: ${known.join(", ")})` : " — none are"}`
+		};
+	}
+	const marked = component?.[DECK_RENDERER];
+	if (typeof marked === "string") {
+		const stamped = rendererNamed(marked);
+		if (stamped) return {
+			renderer: stamped,
+			how: "marked"
+		};
+		if (deferred.has(marked)) return {
+			renderer: null,
+			how: "deferred",
+			name: marked
+		};
+		return {
+			renderer: null,
+			how: "unknown",
+			reason: `this component was built for “${marked}”, which is not registered`
+		};
+	}
+	for (const renderer of registry) try {
+		if (renderer.owns?.(component)) return {
+			renderer,
+			how: "owned"
+		};
+	} catch {}
+	return {
+		renderer: null,
+		how: "unknown",
+		reason: "no renderer claimed it — pass framework=\"…\", or have the build stamp DECK_RENDERER on it"
+	};
+}
+/**
+* Resolution, including the renderers that have to be fetched first.
+*
+* This is what the engine calls. The synchronous `resolveRenderer` above stays exactly as honest as
+* it was — it reports what is in the page right now — and this one takes its `deferred` answer and
+* finishes it.
+*/
+async function resolveRendererAsync(component, framework) {
+	const now = resolveRenderer(component, framework);
+	if (now.how !== "deferred") return now;
+	const renderer = await loadRenderer(now.name);
+	return renderer ? {
+		renderer,
+		how: framework ? "named" : "marked"
+	} : {
+		renderer: null,
+		how: "unknown",
+		reason: `the “${now.name}” renderer is registered but could not be loaded`
+	};
+}
+//#endregion
+export { DECK_RENDERER, clearRenderers, knownRendererNames, loadRenderer, nativeRenderer, registerLazyRenderer, registerRenderer, registeredRenderers, rendererNamed, resolveRenderer, resolveRendererAsync };

package/dist/renderers/index.d.ts

@@ -0,0 +1,12 @@
+import { DECK_RENDERER, DeckRenderer, IslandComponent, IslandMount, IslandProps, MarkedComponent, RenderContext, RendererLoader, Resolution, clearRenderers, knownRendererNames, loadRenderer, nativeRenderer, registerLazyRenderer, registerRenderer, registeredRenderers, rendererNamed, resolveRenderer, resolveRendererAsync } from "./contract.js";
+import { ClientStrategy, Island, IslandLoader, IslandOwnProps } from "./Island.js";
+import { reactRenderer } from "./react.js";
+import { webComponentsRenderer } from "./web-components.js";
+//#region src/renderers/index.d.ts
+/**
+ * The two that ship with the engine, in `owns()` order: custom elements can recognise their own
+ * (a hyphenated tag is unambiguous), React cannot and does not try.
+ */
+export declare function registerBuiltinRenderers(): void;
+//#endregion
+export { type ClientStrategy, DECK_RENDERER, type DeckRenderer, Island, type IslandComponent, type IslandLoader, type IslandMount, type IslandOwnProps, type IslandProps, type MarkedComponent, type RenderContext, type RendererLoader, type Resolution, clearRenderers, knownRendererNames, loadRenderer, nativeRenderer, reactRenderer, registerLazyRenderer, registerRenderer, registeredRenderers, rendererNamed, resolveRenderer, resolveRendererAsync, webComponentsRenderer };

package/dist/renderers/index.js

@@ -0,0 +1,16 @@
+import { DECK_RENDERER, clearRenderers, knownRendererNames, loadRenderer, nativeRenderer, registerLazyRenderer, registerRenderer, registeredRenderers, rendererNamed, resolveRenderer, resolveRendererAsync } from "./contract.js";
+import { Island } from "./Island.js";
+import { reactRenderer } from "./react.js";
+import { webComponentsRenderer } from "./web-components.js";
+//#region src/renderers/index.ts
+/**
+* The two that ship with the engine, in `owns()` order: custom elements can recognise their own
+* (a hyphenated tag is unambiguous), React cannot and does not try.
+*/
+function registerBuiltinRenderers() {
+	registerRenderer(webComponentsRenderer);
+	registerRenderer(reactRenderer);
+}
+registerBuiltinRenderers();
+//#endregion
+export { DECK_RENDERER, Island, clearRenderers, knownRendererNames, loadRenderer, nativeRenderer, reactRenderer, registerBuiltinRenderers, registerLazyRenderer, registerRenderer, registeredRenderers, rendererNamed, resolveRenderer, resolveRendererAsync, webComponentsRenderer };

package/dist/renderers/react.d.ts

@@ -0,0 +1,16 @@
+import { DeckRenderer } from "./contract.js";
+//#region src/renderers/react.d.ts
+/**
+ * React — the framework the deck runtime itself draws with.
+ *
+ * `native: true` is the whole point of this file. `<Island>` sees it and renders the component
+ * directly into the tree instead of mounting it, so a React component on a slide keeps the deck's
+ * context: the click it should be revealed at, the theme, the live room, the glossary. Through an
+ * island it would get a second React root, and context does not cross a root boundary — the
+ * component would render, and every hook that made it part of a deck would quietly return nothing.
+ *
+ * `mount` exists anyway, for the day the host surface is not React: a React island inside a Vue
+ * deck is a root, and then a root is the right answer.
+ */
+export declare const reactRenderer: DeckRenderer;
+//#endregion

package/dist/renderers/react.js

@@ -0,0 +1,32 @@
+import { createElement } from "react";
+import { createRoot } from "react-dom/client";
+//#region src/renderers/react.tsx
+/**
+* React — the framework the deck runtime itself draws with.
+*
+* `native: true` is the whole point of this file. `<Island>` sees it and renders the component
+* directly into the tree instead of mounting it, so a React component on a slide keeps the deck's
+* context: the click it should be revealed at, the theme, the live room, the glossary. Through an
+* island it would get a second React root, and context does not cross a root boundary — the
+* component would render, and every hook that made it part of a deck would quietly return nothing.
+*
+* `mount` exists anyway, for the day the host surface is not React: a React island inside a Vue
+* deck is a root, and then a root is the right answer.
+*/
+const reactRenderer = {
+	name: "react",
+	native: true,
+	mount(host, component, props, context) {
+		const root = createRoot(host);
+		const render = (p) => root.render(createElement(component, p, context.slot ? createElement("div", { dangerouslySetInnerHTML: { __html: context.slot } }) : void 0));
+		render(props);
+		return {
+			destroy() {
+				queueMicrotask(() => root.unmount());
+			},
+			update: render
+		};
+	}
+};
+//#endregion
+export { reactRenderer };

package/dist/renderers/web-components.d.ts

@@ -0,0 +1,4 @@
+import { DeckRenderer } from "./contract.js";
+//#region src/renderers/web-components.d.ts
+export declare const webComponentsRenderer: DeckRenderer;
+//#endregion

package/dist/renderers/web-components.js

@@ -0,0 +1,103 @@
+//#region src/renderers/web-components.ts
+/**
+* Custom elements — the renderer with no framework behind it.
+*
+* This one is first on purpose. Every other renderer will be a framework with opinions about
+* mounting, and it is easy to write a contract that quietly assumes the shape of the framework you
+* already have. Custom elements assume nothing: a tag name, an element, properties, `remove()`. If
+* the contract fits here it is a contract rather than React with extra steps.
+*
+* An author writes either the tag name:
+*
+*     <Island component="my-chart" props={{ data }} />
+*
+* or the class, which is defined on first use:
+*
+*     <Island component={MyChart} props={{ data }} />
+*/
+/** Tag names must contain a hyphen; that is the whole rule, and it makes recognition reliable. */
+function isCustomElementName(value) {
+	return typeof value === "string" && value.includes("-") && !/\s/.test(value);
+}
+function isCustomElementClass(value) {
+	if (typeof value !== "function") return false;
+	if (typeof HTMLElement === "undefined") return false;
+	return value === HTMLElement || value.prototype instanceof HTMLElement;
+}
+let anonymous = 0;
+const named = /* @__PURE__ */ new WeakMap();
+/** The tag for a class: its own `tagName`, one it is already defined under, or a fresh one. */
+function tagFor(ctor) {
+	const existing = named.get(ctor);
+	if (existing) return existing;
+	const declared = ctor.tagName;
+	let tag = typeof declared === "string" && declared.includes("-") ? declared : "";
+	if (!tag) tag = `deck-island-${++anonymous}`;
+	const already = customElements.get(tag);
+	if (!already) customElements.define(tag, ctor);
+	else if (already !== ctor) {
+		tag = `deck-island-${++anonymous}`;
+		customElements.define(tag, ctor);
+	}
+	named.set(ctor, tag);
+	return tag;
+}
+/**
+* A property where the element has one, an attribute where it does not.
+*
+* This is the custom-element convention rather than a preference: rich values (arrays, objects,
+* functions) only survive as properties, and attributes only carry strings. `false` removes the
+* attribute instead of writing "false", which is what every element in HTML means by a boolean.
+*/
+function apply(el, props) {
+	for (const [key, value] of Object.entries(props)) {
+		if (key === "children") continue;
+		if (key in el || typeof value === "object" || typeof value === "function") try {
+			el[key] = value;
+			continue;
+		} catch {}
+		if (value === false || value === null || value === void 0) el.removeAttribute(key);
+		else if (value === true) el.setAttribute(key, "");
+		else el.setAttribute(key, String(value));
+	}
+}
+/**
+* `>` does not strictly need escaping inside a quoted attribute, and is escaped anyway: this string
+* is concatenated into markup that may be read somewhere less forgiving than a browser.
+*/
+function escapeAttribute(value) {
+	return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+const webComponentsRenderer = {
+	name: "web-components",
+	owns(component) {
+		return isCustomElementName(component) || isCustomElementClass(component);
+	},
+	mount(host, component, props, context) {
+		const tag = isCustomElementName(component) ? component : tagFor(component);
+		const el = document.createElement(tag);
+		if (context.slot) el.innerHTML = context.slot;
+		if (context.animate === false) el.setAttribute("data-still", "");
+		apply(el, props);
+		host.replaceChildren(el);
+		return {
+			destroy() {
+				el.remove();
+			},
+			update(next) {
+				apply(el, next);
+			}
+		};
+	},
+	/**
+	* The element's markup without a browser to upgrade it. A custom element that has not been
+	* defined is an inert tag with its attributes — which is exactly what a print page or an export
+	* frame should show, as long as the element's styling does not depend on being upgraded.
+	*/
+	ssr(component, props, context) {
+		const tag = isCustomElementName(component) ? component : typeof component === "function" ? tagFor(component) : "deck-island-unknown";
+		return `<${tag}${Object.entries(props).filter(([k, v]) => k !== "children" && typeof v !== "object" && typeof v !== "function").map(([k, v]) => v === true ? ` ${k}=""` : v === false || v == null ? "" : ` ${k}="${escapeAttribute(String(v))}"`).join("")}>${context.slot ?? ""}</${tag}>`;
+	}
+};
+//#endregion
+export { webComponentsRenderer };

package/dist/sketch/Canvas.js

@@ -0,0 +1,49 @@
+import { useUi } from "../react/hooks.js";
+import { getScene } from "./render.js";
+import { jsx } from "react/jsx-runtime";
+import { Excalidraw } from "@excalidraw/excalidraw";
+import "@excalidraw/excalidraw/index.css";
+//#region src/sketch/Canvas.tsx
+/**
+* The real Excalidraw canvas, in view mode, for the lightbox: pan, zoom and point at a part of a
+* sketch during the talk. Loaded only when a sketch is opened — the package is 2.7 MB.
+*/
+function SketchCanvas({ id }) {
+	const scene = getScene(id);
+	const scheme = useUi((s) => s.colorScheme);
+	if (!scene) return /* @__PURE__ */ jsx("div", {
+		className: "deck-sketch-missing",
+		children: "This sketch has not been drawn yet."
+	});
+	return /* @__PURE__ */ jsx("div", {
+		className: "deck-sketch-canvas",
+		children: /* @__PURE__ */ jsx(Excalidraw, {
+			initialData: {
+				elements: scene.elements,
+				files: scene.files,
+				appState: { viewBackgroundColor: "#fbfbf9" },
+				scrollToContent: true
+			},
+			viewModeEnabled: true,
+			zenModeEnabled: true,
+			theme: scheme,
+			detectScroll: false,
+			handleKeyboardGlobally: false,
+			autoFocus: true,
+			UIOptions: {
+				canvasActions: {
+					changeViewBackgroundColor: false,
+					clearCanvas: false,
+					export: false,
+					loadScene: false,
+					saveAsImage: false,
+					saveToActiveFile: false,
+					toggleTheme: false
+				},
+				tools: { image: false }
+			}
+		})
+	});
+}
+//#endregion
+export { SketchCanvas as default };