@protoyard/decks-ui 0.0.0-stage → 1.1.0

package/dist/app/FreeSlide.svelte

@@ -0,0 +1,135 @@
+<script lang="ts">
+import type { Block } from '@protoyard/blocks';
+import type { DeckSlide, FreeSlide as FreeSlideModel } from '@texuli/deck/model';
+import { fitText } from '@texuli/slides/layouts';
+import {
+  createDeckStepContext,
+  type DeckSlideRendererProps,
+  deckSlideSteps,
+  getDeckStepContext,
+} from '@texuli/slides/stage-core';
+import { getDeckHostContext } from './context.js';
+import FreeBlock from './FreeBlock.svelte';
+import { fitContent } from './fit.js';
+
+/**
+ * Protoyard's free slide renderer for the `@texuli/slides` stage: the
+ * author's `@protoyard/blocks` (the stage checked them with DeckApp's
+ * `validateBlock`, see `renderers.ts`), with a leading unstepped heading
+ * promoted to the slide title. Reveals use the stage's step machinery: the
+ * deck model's step table of the original slide, at the stage's step. The blocks zoom down (to a floor) when they would not fit
+ * the canvas. Texuli's `--tx-*` tokens feed Protoyard's blocks, so they follow the deck
+ * theme, the slide theme and the background's text color.
+ */
+let { slide, context }: DeckSlideRendererProps<FreeSlideModel> = $props();
+const host = getDeckHostContext();
+const fromContext = getDeckStepContext();
+const stageStep = $derived(fromContext ?? context.step);
+const original = $derived(host.freeSlides.get(slide.id));
+// The deck passed DeckSchema (@protoyard/blocks) before it reached DeckApp.
+const blocks = $derived((original?.blocks ?? []) as Block[]);
+const steps = $derived(original ? deckSlideSteps(original as unknown as DeckSlide) : null);
+const step = createDeckStepContext(() => ({
+  slide: (original ?? slide) as unknown as DeckSlide,
+  steps: steps ?? stageStep.steps,
+  step: stageStep.step,
+  active: stageStep.active,
+  direction: stageStep.direction,
+}));
+const lead = $derived(
+  blocks[0]?.type === 'heading' && blocks[0].step === undefined ? blocks[0] : null
+);
+const start = $derived(lead ? 1 : 0);
+</script>
+
+<div class="py-deck-free" data-py-deck-free={slide.id}>
+  {#if lead && lead.type === 'heading'}
+    <header class="py-deck-free__heading" data-slot="heading">
+      {#if lead.eyebrow}<p class="py-deck-free__eyebrow">{lead.eyebrow}</p>{/if}
+      <h2 class="py-deck-free__title" data-slot="title" {@attach fitText(40)}>{lead.text}</h2>
+      {#if lead.subtitle}<p class="py-deck-free__subtitle">{lead.subtitle}</p>{/if}
+    </header>
+  {/if}
+  <!-- Safe centering: content taller than the slot starts at the top, under the heading. -->
+  <div class="py-deck-free__blocks" data-slot="blocks" {@attach fitContent()}>
+    {#each blocks.slice(start) as block, offset (start + offset)}
+      <FreeBlock {block} index={start + offset} {step} />
+    {/each}
+  </div>
+</div>
+
+<style>
+  .py-deck-free {
+    /* Text on the slide follows the background's ink (`--tx-deck-bg-text`). */
+    --deck-free-foreground: var(--tx-deck-bg-text, var(--tx-foreground));
+    /*
+     * The deck's radius choice: the stage writes it to --tx-deck-radius only,
+     * so Texuli components on the slide (buttons, cards, inputs) would keep the
+     * theme radius.
+     */
+    --tx-radius: var(--tx-deck-radius);
+    --color-foreground: var(--deck-free-foreground);
+    --color-border: var(--tx-border);
+    --color-primary: var(--tx-primary);
+    --color-muted-foreground: var(--tx-muted-foreground);
+    --font-sans: var(--tx-font-sans);
+    --font-heading: var(--tx-font-heading);
+    /* One frame over the slide body, as the stage's layout frames: a fixed box the content fits in. */
+    position: absolute;
+    inset: 0;
+    overflow: hidden;
+    display: flex;
+    flex-direction: column;
+    gap: 30px;
+    box-sizing: border-box;
+    padding-block: 64px;
+    padding-inline: 77px;
+    color: var(--deck-free-foreground);
+    font-family: var(--tx-font-sans);
+    font-size: 24px;
+  }
+
+  .py-deck-free__heading {
+    display: flex;
+    flex-direction: column;
+    flex-shrink: 0;
+    gap: 10px;
+  }
+
+  .py-deck-free__eyebrow {
+    margin: 0;
+    color: var(--tx-primary);
+    font-size: 20px;
+    font-weight: 600;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+  }
+
+  .py-deck-free__title {
+    display: -webkit-box;
+    margin: 0;
+    overflow: hidden;
+    font-family: var(--tx-font-heading);
+    font-size: 56px;
+    font-weight: 700;
+    line-height: 1.1;
+    -webkit-box-orient: vertical;
+    -webkit-line-clamp: 2;
+    line-clamp: 2;
+  }
+
+  .py-deck-free__subtitle {
+    margin: 0;
+    color: var(--tx-muted-foreground);
+    font-size: 28px;
+  }
+
+  .py-deck-free__blocks {
+    display: flex;
+    flex: 1;
+    flex-direction: column;
+    justify-content: safe center;
+    gap: 26px;
+    min-block-size: 0;
+  }
+</style>

package/dist/app/FreeSlide.svelte.d.ts

@@ -0,0 +1,5 @@
+import type { FreeSlide as FreeSlideModel } from '@texuli/deck/model';
+import { type DeckSlideRendererProps } from '@texuli/slides/stage-core';
+declare const FreeSlide: import("svelte").Component<DeckSlideRendererProps<FreeSlideModel>, {}, "">;
+type FreeSlide = ReturnType<typeof FreeSlide>;
+export default FreeSlide;

package/dist/app/context.d.ts

@@ -0,0 +1,14 @@
+import type { FreeSlide } from '@protoyard/decks/schema';
+import type { CustomSlideRegistry } from '../layouts/custom-slides.ts';
+/**
+ * What DeckApp hands its slide renderers through Svelte context (the
+ * `@texuli/slides` stage passes renderers only the slide and its render
+ * context): the generated deck's custom slide registry and its free slides.
+ */
+export interface DeckHostContext {
+    readonly customSlides: CustomSlideRegistry | undefined;
+    /** The deck's free slides by id (the stage sees them as host slides, see `stage-deck.ts`). */
+    readonly freeSlides: ReadonlyMap<string, FreeSlide>;
+}
+export declare function setDeckHostContext(context: DeckHostContext): void;
+export declare function getDeckHostContext(): DeckHostContext;

package/dist/app/context.js

@@ -0,0 +1,11 @@
+import { getContext, setContext } from 'svelte';
+const KEY = Symbol.for('@protoyard/decks-ui/host');
+export function setDeckHostContext(context) {
+    setContext(KEY, context);
+}
+export function getDeckHostContext() {
+    return (getContext(KEY) ?? {
+        customSlides: undefined,
+        freeSlides: new Map(),
+    });
+}

package/dist/app/fit.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Free-slide content fit: `@texuli/slides/layouts`' `fitContent` plus the
+ * oscillation guard Protoyard's former `design/fit.ts` had (`keepsZoom`).
+ *
+ * Texuli's attachment resets the zoom and measures again on every resize of
+ * the box. Blocks that lay out at their measured width (a Texuli chart, the
+ * chart explorer) reflow when the zoom is reset, the box resizes, the fit runs
+ * again and puts the zoom back: the zoom flips every frame and the slide never
+ * holds still (the flagship's `explore` slide did, in both levels). Remove this
+ * file and import `fitContent` from `@texuli/slides/layouts` again once the
+ * Texuli attachment keeps a zoom under which the content still fits.
+ */
+/** Why a fit runs again: a box resized, or the content itself changed. */
+export type FitReason = 'resize' | 'content';
+/**
+ * Whether a re-fit may keep the zoom it already applied instead of resetting
+ * and measuring again. Measuring with the zoom reset reads a layout the
+ * content has not reflowed to yet (a block sized for the zoomed width), which
+ * can find "it fits", drop the zoom, and flip back a frame later, forever. So
+ * a resize keeps a zoom under which the content still fits, or the floor zoom
+ * (content taller than the floor allows cannot shrink further, and measuring
+ * again only flips between the floor and a near guess), unless the space
+ * around it changed; new content always measures from scratch.
+ */
+export declare function keepsZoom(state: {
+    applied: number;
+    reason: FitReason;
+    spaceChanged: boolean;
+    fitsAtApplied: boolean;
+    /** The floor zoom (`fitContent`'s `min`). */
+    min: number;
+}): boolean;
+/**
+ * Zooms `node` down (CSS `zoom`, so layout follows) until its content fits its
+ * own box, never below `min` (0.75, the floor of the stage's layouts, keeps
+ * 24 px body text at the 18 px label minimum). Same contract and attribute
+ * (`data-tx-deck-fit`) as `@texuli/slides/layouts`' `fitContent`.
+ */
+export declare function fitContent(min?: number): (node: HTMLElement) => () => void;

package/dist/app/fit.js

@@ -0,0 +1,97 @@
+import { fitScale } from '@texuli/slides/layouts';
+/**
+ * Whether a re-fit may keep the zoom it already applied instead of resetting
+ * and measuring again. Measuring with the zoom reset reads a layout the
+ * content has not reflowed to yet (a block sized for the zoomed width), which
+ * can find "it fits", drop the zoom, and flip back a frame later, forever. So
+ * a resize keeps a zoom under which the content still fits, or the floor zoom
+ * (content taller than the floor allows cannot shrink further, and measuring
+ * again only flips between the floor and a near guess), unless the space
+ * around it changed; new content always measures from scratch.
+ */
+export function keepsZoom(state) {
+    return (state.applied < 1 &&
+        state.reason === 'resize' &&
+        !state.spaceChanged &&
+        (state.fitsAtApplied || state.applied <= state.min));
+}
+function watch(node, run) {
+    if (typeof requestAnimationFrame !== 'function')
+        return () => { };
+    let frame = 0;
+    let pending = 'content';
+    const schedule = (reason) => {
+        // Content outranks a resize when both arrive in one frame.
+        pending = pending === 'content' || reason === 'content' ? 'content' : 'resize';
+        cancelAnimationFrame(frame);
+        frame = requestAnimationFrame(() => {
+            const why = pending;
+            pending = 'resize';
+            run(why);
+        });
+    };
+    schedule('content');
+    const resized = () => schedule('resize');
+    const changed = () => schedule('content');
+    const observer = typeof ResizeObserver === 'function' ? new ResizeObserver(resized) : null;
+    observer?.observe(node);
+    if (node.parentElement)
+        observer?.observe(node.parentElement);
+    // Images and fonts change the size after the first measure.
+    node.addEventListener('load', changed, true);
+    // Lazy blocks arrive after the first measure without resizing this box, so
+    // added content also triggers a re-fit (only nodes, never style changes).
+    const mutations = typeof MutationObserver === 'function' ? new MutationObserver(changed) : null;
+    mutations?.observe(node, { childList: true, subtree: true });
+    return () => {
+        cancelAnimationFrame(frame);
+        observer?.disconnect();
+        mutations?.disconnect();
+        node.removeEventListener('load', changed, true);
+    };
+}
+/**
+ * Zooms `node` down (CSS `zoom`, so layout follows) until its content fits its
+ * own box, never below `min` (0.75, the floor of the stage's layouts, keeps
+ * 24 px body text at the 18 px label minimum). Same contract and attribute
+ * (`data-tx-deck-fit`) as `@texuli/slides/layouts`' `fitContent`.
+ */
+export function fitContent(min = 0.75) {
+    return (node) => {
+        let applied = 1;
+        let space = '';
+        const spaceOf = () => {
+            const parent = node.parentElement;
+            return parent ? `${parent.clientWidth}x${parent.clientHeight}` : '';
+        };
+        return watch(node, (reason) => {
+            const now = spaceOf();
+            if (keepsZoom({
+                applied,
+                reason,
+                spaceChanged: now !== space,
+                fitsAtApplied: node.scrollHeight <= node.clientHeight + 2,
+                min,
+            })) {
+                return;
+            }
+            node.style.zoom = '';
+            if (node.clientHeight === 0)
+                return;
+            let scale = fitScale(node.scrollHeight, node.clientHeight, min);
+            // Content reflows under the zoom (a wider box, shorter lines), so the
+            // first estimate is checked under the zoom itself and tightened until it
+            // fits there: the result is a fixed point, not a guess the next frame undoes.
+            for (let pass = 0; scale < 1 && pass < 6; pass += 1) {
+                node.style.zoom = String(scale);
+                if (node.scrollHeight <= node.clientHeight + 2 || scale <= min)
+                    break;
+                scale = Math.max(min, Math.floor(scale * (node.clientHeight / node.scrollHeight) * 1000) / 1000);
+            }
+            node.style.zoom = scale < 1 ? String(scale) : '';
+            node.dataset.txDeckFit = scale < 1 ? String(scale) : '1';
+            applied = scale;
+            space = now;
+        });
+    };
+}

package/dist/app/free-prefetch.d.ts

@@ -0,0 +1,3 @@
+import type { FreeSlide } from '@protoyard/decks/schema';
+/** Load the block families a free slide needs (lazy: this module is its own chunk). */
+export declare function prefetchFreeSlide(slide: FreeSlide): Promise<unknown>;

package/dist/app/free-prefetch.js

@@ -0,0 +1,13 @@
+import { blockRendererRegistry } from '@protoyard/blocks-ui';
+const BLOCK_TYPES = new Set(Object.keys(blockRendererRegistry));
+/** Load the block families a free slide needs (lazy: this module is its own chunk). */
+export function prefetchFreeSlide(slide) {
+    const families = new Set();
+    for (const block of slide.blocks) {
+        const type = block.type;
+        if (typeof type !== 'string' || !BLOCK_TYPES.has(type))
+            continue;
+        families.add(blockRendererRegistry[type].load);
+    }
+    return Promise.all([...families].map((load) => load()));
+}

package/dist/app/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `@protoyard/decks-ui/app` — DeckApp, the one deck component that the
+ * player's deck entry and generated deck prototypes both mount (ADR-038).
+ */
+export type { CustomSlideComponent, CustomSlideLoader, CustomSlideProps, CustomSlideRegistry, } from '../layouts/custom-slides.ts';
+export { default as DeckApp } from './DeckApp.svelte';

package/dist/app/index.js

@@ -0,0 +1,5 @@
+/**
+ * `@protoyard/decks-ui/app` — DeckApp, the one deck component that the
+ * player's deck entry and generated deck prototypes both mount (ADR-038).
+ */
+export { default as DeckApp } from './DeckApp.svelte';

package/dist/app/interactive.d.ts

@@ -0,0 +1,3 @@
+import type { Block } from '@protoyard/blocks';
+/** True when `block` (or a block nested in it) has its own controls. */
+export declare function containsDeckControl(block: Block): boolean;

package/dist/app/interactive.js

@@ -0,0 +1,25 @@
+/** Blocks with their own controls: clicks and keys inside them never move the deck. */
+const INTERACTIVE_TYPES = new Set([
+    'tabs',
+    'reveal',
+    'poll',
+    'quiz',
+    'calculator',
+    'counter',
+    'chart-controls',
+    'map',
+    'embed-app',
+    'form',
+    'chart',
+    'table',
+    'stat',
+    'code',
+]);
+/** True when `block` (or a block nested in it) has its own controls. */
+export function containsDeckControl(block) {
+    if (INTERACTIVE_TYPES.has(block.type))
+        return true;
+    if (block.type === 'columns')
+        return block.columns.some((column) => column.some(containsDeckControl));
+    return false;
+}

package/dist/app/renderers.d.ts

@@ -0,0 +1,14 @@
+import type { FreeSlide } from '@protoyard/decks/schema';
+import { type DeckDiagnostic, type PathSegment } from '@texuli/deck/schema';
+import type { DeckRenderers } from '@texuli/slides/stage-core';
+/**
+ * The stage's free-slide block check for Protoyard blocks (step fields already
+ * removed). DeckApp only receives a deck that passed `DeckSchema`, which
+ * validates every block body with `@protoyard/blocks`; that zod schema is far
+ * too large for the deck entry, so the stage checks only that each block is a
+ * typed object (`@protoyard/blocks-ui` shows a labelled card for a type it
+ * does not render). Returns no diagnostics to accept the block.
+ */
+export declare function validateProtoyardBlock(block: unknown, path: PathSegment[]): DeckDiagnostic[];
+/** The renderer table for one deck (its free slides are looked up by id for prefetch). */
+export declare function createProtoyardRenderers(freeSlides: ReadonlyMap<string, FreeSlide>): DeckRenderers;

package/dist/app/renderers.js

@@ -0,0 +1,49 @@
+import { createDiagnostic } from '@texuli/deck/schema';
+import { layoutRenderers } from '@texuli/slides/layouts';
+const free = { load: () => import('./FreeSlide.svelte') };
+const custom = { load: () => import('./CustomSlide.svelte') };
+/**
+ * The stage's free-slide block check for Protoyard blocks (step fields already
+ * removed). DeckApp only receives a deck that passed `DeckSchema`, which
+ * validates every block body with `@protoyard/blocks`; that zod schema is far
+ * too large for the deck entry, so the stage checks only that each block is a
+ * typed object (`@protoyard/blocks-ui` shows a labelled card for a type it
+ * does not render). Returns no diagnostics to accept the block.
+ */
+export function validateProtoyardBlock(block, path) {
+    const typed = block !== null &&
+        typeof block === 'object' &&
+        !Array.isArray(block) &&
+        typeof block.type === 'string' &&
+        block.type.length > 0;
+    if (typed)
+        return [];
+    return [
+        createDiagnostic('block-props', 'A free-slide block is an object with a "type".', path, {
+            fix: 'Check the block against the @protoyard/blocks schema for its type.',
+        }),
+    ];
+}
+/** The renderer table for one deck (its free slides are looked up by id for prefetch). */
+export function createProtoyardRenderers(freeSlides) {
+    return Object.freeze({
+        layout: (slide, lookup) => layoutRenderers.layout?.(slide, lookup),
+        free: () => free,
+        custom: () => custom,
+        validateBlock: validateProtoyardBlock,
+        prefetch(slide) {
+            if (slide.layout === 'custom')
+                return custom.load();
+            if (slide.layout !== 'free')
+                return layoutRenderers.prefetch?.(slide);
+            const original = freeSlides.get(slide.id);
+            // The block families load from a lazy module, so the deck entry never carries blocks-ui.
+            return Promise.all([
+                free.load(),
+                original
+                    ? import("./free-prefetch.js").then((module) => module.prefetchFreeSlide(original))
+                    : undefined,
+            ]);
+        },
+    });
+}

package/dist/app/stage-deck.d.ts

@@ -0,0 +1,40 @@
+import type { Deck, FreeSlide } from '@protoyard/decks/schema';
+import { type PreparedDeck } from '@texuli/slides/stage-core';
+/**
+ * The deck DeckApp hands the `@texuli/slides` stage.
+ *
+ * - **Theme:** `style.theme` becomes Protoyard's theme key (a theme id, a
+ *   palette seed as `seed-<hex>`, or the default theme) with the font pair
+ *   (`stageThemeKey`), which DeckApp's `loadTheme` resolves through
+ *   `@protoyard/themes`.
+ * - **Free slides** stay free slides: the stage checks their blocks with
+ *   DeckApp's `validateBlock` (a typed-object check, see `renderers.ts`)
+ *   and counts their steps itself. A free slide with no title takes its
+ *   first heading's text, which the stage names the slide by. DeckApp's
+ *   free-slide renderer paints the original `@protoyard/blocks` from
+ *   `freeSlides`.
+ */
+/**
+ * The theme key the stage loads and caches a theme by: the deck theme key,
+ * plus `-font-<pair>` when the deck picks a font pairing. The stage caches
+ * loaded themes by key, so a font pair change (Deck Studio) must change the
+ * key or the stage keeps the old fonts. Both parts are slugs, so the key is
+ * still a valid catalog theme id for the deck model.
+ */
+export declare function stageThemeKey(style: Deck['style'] | undefined): string;
+/** The deck theme key inside a stage theme key, given the font pair the deck has now. */
+export declare function themeKeyOf(stageKey: string, fontPair: string | undefined): string;
+export interface StageDeck {
+    input: Record<string, unknown>;
+    /** The original free slides, by id, for the free-slide renderer. */
+    freeSlides: ReadonlyMap<string, FreeSlide>;
+}
+export declare function stageDeck(deck: Deck): StageDeck;
+/**
+ * Migrate a stage input (`stageDeck(deck).input`) to the deck model and validate it
+ * once with Protoyard's block check (`prepareDeckV2`, Texuli G83). An `ok` result is a
+ * prepared deck: at the `developer` tier the stage paints it on its first render
+ * without migrating or validating it again, and loads no validation chunk for it.
+ * Never throws: a deck that does not validate comes back with its issues.
+ */
+export declare function prepareStageDeck(input: Record<string, unknown>): PreparedDeck;

package/dist/app/stage-deck.js

@@ -0,0 +1,65 @@
+import { toTexuliDeck } from '@protoyard/decks';
+import { deckThemeKey } from '@protoyard/decks/style/key';
+import { prepareDeckV2 } from '@texuli/slides/stage-core';
+import { validateProtoyardBlock } from "./renderers.js";
+/**
+ * The deck DeckApp hands the `@texuli/slides` stage.
+ *
+ * - **Theme:** `style.theme` becomes Protoyard's theme key (a theme id, a
+ *   palette seed as `seed-<hex>`, or the default theme) with the font pair
+ *   (`stageThemeKey`), which DeckApp's `loadTheme` resolves through
+ *   `@protoyard/themes`.
+ * - **Free slides** stay free slides: the stage checks their blocks with
+ *   DeckApp's `validateBlock` (a typed-object check, see `renderers.ts`)
+ *   and counts their steps itself. A free slide with no title takes its
+ *   first heading's text, which the stage names the slide by. DeckApp's
+ *   free-slide renderer paints the original `@protoyard/blocks` from
+ *   `freeSlides`.
+ */
+/**
+ * The theme key the stage loads and caches a theme by: the deck theme key,
+ * plus `-font-<pair>` when the deck picks a font pairing. The stage caches
+ * loaded themes by key, so a font pair change (Deck Studio) must change the
+ * key or the stage keeps the old fonts. Both parts are slugs, so the key is
+ * still a valid catalog theme id for the deck model.
+ */
+export function stageThemeKey(style) {
+    const theme = deckThemeKey(style);
+    return style?.fontPair ? `${theme}-font-${style.fontPair}` : theme;
+}
+/** The deck theme key inside a stage theme key, given the font pair the deck has now. */
+export function themeKeyOf(stageKey, fontPair) {
+    const suffix = fontPair ? `-font-${fontPair}` : '';
+    return suffix && stageKey.endsWith(suffix) ? stageKey.slice(0, -suffix.length) : stageKey;
+}
+export function stageDeck(deck) {
+    const freeSlides = new Map();
+    const slides = deck.slides.map((slide) => {
+        if (slide.layout !== 'free')
+            return slide;
+        const free = slide;
+        freeSlides.set(free.id, free);
+        if (free.title)
+            return free;
+        // The stage names the slide by its title: keep the first heading as one when it has none.
+        const heading = free.blocks.find((block) => block.type === 'heading');
+        return heading && 'text' in heading
+            ? { ...free, title: String(heading.text).slice(0, 160) }
+            : free;
+    });
+    const { paletteSeed: _seed, ...style } = deck.style ?? {};
+    return {
+        input: { ...deck, style: { ...style, theme: stageThemeKey(deck.style) }, slides },
+        freeSlides,
+    };
+}
+/**
+ * Migrate a stage input (`stageDeck(deck).input`) to the deck model and validate it
+ * once with Protoyard's block check (`prepareDeckV2`, Texuli G83). An `ok` result is a
+ * prepared deck: at the `developer` tier the stage paints it on its first render
+ * without migrating or validating it again, and loads no validation chunk for it.
+ * Never throws: a deck that does not validate comes back with its issues.
+ */
+export function prepareStageDeck(input) {
+    return prepareDeckV2(toTexuliDeck(input), { validateBlock: validateProtoyardBlock });
+}

package/dist/debug/BlockOutline.svelte

@@ -0,0 +1,117 @@
+<script lang="ts">
+import { Badge } from 'texuli/badge';
+
+/**
+ * Outline mode: a box and the JSON pointer for each top-level block of the
+ * slide on screen (a free slide), or for the slide's props (a catalog
+ * layout). Decoration only: `aria-hidden`, `pointer-events: none`, hidden in
+ * print. Boxes are measured from the rendered stage and refit on resize.
+ */
+let {
+  root,
+  slideId,
+  slidePointer,
+  propsPointer,
+}: {
+  /** The deck root the stage renders in. */
+  root: HTMLElement | undefined;
+  slideId: string;
+  /** `/deck/slides/3`: block pointers are `<slidePointer>/blocks/<n>`. */
+  slidePointer: string;
+  /** The props pointer of a catalog slide, or null for a free slide. */
+  propsPointer: string | null;
+} = $props();
+
+interface Box {
+  pointer: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+let layer = $state<HTMLDivElement | undefined>();
+let boxes = $state<Box[]>([]);
+
+function slideElement(host: HTMLElement, id: string): HTMLElement | null {
+  for (const node of host.querySelectorAll<HTMLElement>('[data-tx-deck-slide]')) {
+    if (node.dataset.txDeckSlide === id) return node;
+  }
+  return null;
+}
+
+function measure(): void {
+  const host = root;
+  const own = layer;
+  if (!host || !own) return;
+  const origin = own.getBoundingClientRect();
+  const slide = slideElement(host, slideId);
+  if (!slide) {
+    boxes = [];
+    return;
+  }
+  const box = (element: Element, pointer: string): Box => {
+    const rect = element.getBoundingClientRect();
+    return {
+      pointer,
+      x: rect.left - origin.left,
+      y: rect.top - origin.top,
+      width: rect.width,
+      height: rect.height,
+    };
+  };
+  // A free slide: the promoted heading is block 0, every other block has a (box-less) item wrapper.
+  const free = slide.querySelector('[data-py-deck-free]');
+  if (!propsPointer && free) {
+    const heading = free.querySelector('[data-slot="heading"]');
+    const items = [...free.querySelectorAll<HTMLElement>('[data-tx-deck-item]')].flatMap((item) => {
+      const child = item.firstElementChild;
+      return child ? [box(child, `${slidePointer}/blocks/${item.dataset.txDeckItem}`)] : [];
+    });
+    boxes = heading ? [box(heading, `${slidePointer}/blocks/0`), ...items] : items;
+  } else {
+    boxes = [box(slide, propsPointer ?? slidePointer)];
+  }
+}
+
+$effect(() => {
+  // Re-measure whenever the slide (or the deck root) changes, after it renders.
+  void slideId;
+  void propsPointer;
+  const host = root;
+  if (!host) return;
+  let frame = requestAnimationFrame(measure);
+  const again = () => {
+    cancelAnimationFrame(frame);
+    frame = requestAnimationFrame(measure);
+  };
+  const observer = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(again);
+  observer?.observe(host);
+  window.addEventListener('resize', again);
+  return () => {
+    cancelAnimationFrame(frame);
+    observer?.disconnect();
+    window.removeEventListener('resize', again);
+  };
+});
+</script>
+
+<div
+  bind:this={layer}
+  class="pointer-events-none absolute inset-0 z-30 overflow-hidden"
+  aria-hidden="true"
+  data-py-deck-outline
+>
+  {#each boxes as item (item.pointer)}
+    <div
+      class="absolute rounded-sm border-2 border-dashed border-primary"
+      style={`left:${item.x}px;top:${item.y}px;width:${item.width}px;height:${item.height}px`}
+      data-py-deck-outline-box={item.pointer}
+    >
+      <Badge
+        class="absolute top-0 left-0 max-w-full truncate rounded-sm px-1 font-mono text-[10px] leading-4"
+        label={item.pointer}
+      />
+    </div>
+  {/each}
+</div>