paraframe 0.0.0-stage → 0.2.0

package/dist/internal/CanvasPreview.svelte

@@ -0,0 +1,153 @@
+<script lang="ts">
+	import { untrack } from 'svelte';
+	import { isFrameMessage } from '../messages.js';
+	import type { Frame } from '../types.js';
+	import type { ScheduleFrameLoad } from './canvas-load-queue.js';
+	import { canvasFrame } from './canvas-frame.js';
+
+	let {
+		frame,
+		src,
+		preview,
+		pixelScale,
+		nearViewport,
+		hovered,
+		scheduleLoad
+	}: {
+		frame: Frame;
+		src: string;
+		preview: string;
+		/** Device pixels per canvas CSS pixel, including canvas and browser zoom. */
+		pixelScale: number;
+		nearViewport: boolean;
+		hovered: boolean;
+		scheduleLoad: ScheduleFrameLoad;
+	} = $props();
+
+	const FADE_MS = 160;
+	const RETURN_TO_IMAGE = 0.85;
+	let imageWidth = $state(0);
+	let imageHeight = $state(0);
+	let imageFailed = $state(false);
+	let live = $state(false);
+	let mounted = $state(false);
+	let ready = $state(false);
+	let completeLoad = () => {};
+
+	// Direct image URLs have no srcset density correction: natural dimensions are
+	// the screenshot's available pixels. Use the weaker axis if sizes differ.
+	const sampling = $derived(imageFailed ? Infinity : imageWidth && imageHeight
+		? pixelScale * Math.max(frame.size.width / imageWidth, frame.size.height / imageHeight)
+		: 0);
+
+	$effect(() => {
+		const nearby = nearViewport;
+		const ratio = sampling;
+		const hovering = hovered;
+		untrack(() => {
+			if (!nearby) live = false;
+			else if (hovering || ratio >= 1) live = true;
+			else if (ratio <= RETURN_TO_IMAGE) live = false;
+		});
+	});
+
+	$effect(() => {
+		if (live) {
+			if (untrack(() => mounted)) return;
+			// The canvas starts this job only while idle. Effect cleanup cancels it
+			// when this frame leaves the viewport or returns to thumbnail scale.
+			return scheduleLoad((complete) => {
+				completeLoad = complete;
+				mounted = true;
+			});
+		}
+		// Keep the image underneath throughout both fades. Off-screen frames and
+		// frames that never finished loading can be destroyed immediately.
+		if (!nearViewport || !untrack(() => ready)) {
+			mounted = false;
+			return;
+		}
+		const timer = setTimeout(() => { mounted = false; }, FADE_MS);
+		return () => clearTimeout(timer);
+	});
+
+	function trackFrame(node: HTMLIFrameElement) {
+		ready = false;
+		let loaded = false;
+		let hydrated = false;
+		let paint = 0;
+		function reveal() {
+			if (!loaded || !hydrated) return;
+			cancelAnimationFrame(paint);
+			// Allow ResizeObserver-driven charts to lay out after fonts and hydration.
+			paint = requestAnimationFrame(() => {
+				paint = requestAnimationFrame(() => {
+					ready = true;
+					completeLoad();
+				});
+			});
+		}
+		function onload() {
+			loaded = true;
+			reveal();
+		}
+		function onmessage(event: MessageEvent) {
+			if (event.origin !== location.origin || event.source !== node.contentWindow) return;
+			if (!isFrameMessage(event.data) || event.data.type !== 'paraframe:ready') return;
+			if (event.data.frame !== frame.id) return;
+			hydrated = true;
+			reveal();
+		}
+		node.addEventListener('load', onload);
+		window.addEventListener('message', onmessage);
+		return () => {
+			cancelAnimationFrame(paint);
+			completeLoad();
+			node.removeEventListener('load', onload);
+			window.removeEventListener('message', onmessage);
+			ready = false;
+		};
+	}
+</script>
+
+<img
+	data-pf-canvas
+	src={preview}
+	alt={frame.title}
+	width={frame.size.width}
+	height={frame.size.height}
+	decoding="async"
+	draggable="false"
+	onload={(event) => {
+		const image = event.currentTarget as HTMLImageElement;
+		imageWidth = image.naturalWidth;
+		imageHeight = image.naturalHeight;
+		imageFailed = false;
+	}}
+	onerror={() => { imageFailed = true; }}
+	class="pointer-events-none size-full"
+/>
+{#if mounted}
+	<iframe
+		{@attach trackFrame}
+		{@attach canvasFrame}
+		data-pf-canvas
+		data-pf-frame={frame.id}
+		data-pf-ready={ready}
+		data-vc-frame
+		{src}
+		title={frame.title}
+		tabindex="-1"
+		aria-hidden="true"
+		class="pointer-events-none absolute inset-0 size-full border-0 data-[pf-hover=true]:pointer-events-auto"
+		style:pointer-events={live && ready ? undefined : 'none'}
+		style:opacity={live && ready ? 1 : 0}
+		style:transition="opacity {FADE_MS}ms ease"
+	></iframe>
+{/if}
+
+<style>
+	@media (prefers-reduced-motion: reduce) {
+		iframe { transition: none !important; }
+	}
+</style>

package/dist/internal/CanvasPreview.svelte.d.ts

@@ -0,0 +1,15 @@
+import type { Frame } from '../types.js';
+import type { ScheduleFrameLoad } from './canvas-load-queue.js';
+type $$ComponentProps = {
+    frame: Frame;
+    src: string;
+    preview: string;
+    /** Device pixels per canvas CSS pixel, including canvas and browser zoom. */
+    pixelScale: number;
+    nearViewport: boolean;
+    hovered: boolean;
+    scheduleLoad: ScheduleFrameLoad;
+};
+declare const CanvasPreview: import("svelte").Component<$$ComponentProps, {}, "">;
+type CanvasPreview = ReturnType<typeof CanvasPreview>;
+export default CanvasPreview;

package/dist/internal/Icon.svelte

@@ -0,0 +1,44 @@
+<script lang="ts" module>
+	// 24×24 stroke icons.
+	const PATHS = {
+		canvas:
+			'M3 6.5a3.5 3.5 0 1 0 7 0a3.5 3.5 0 1 0-7 0M14 6.5a3.5 3.5 0 1 0 7 0a3.5 3.5 0 1 0-7 0M3 17.5a3.5 3.5 0 1 0 7 0a3.5 3.5 0 1 0-7 0M14 17.5a3.5 3.5 0 1 0 7 0a3.5 3.5 0 1 0-7 0',
+		'chevron-left': 'M15 6l-6 6 6 6',
+		'chevron-right': 'M9 6l6 6-6 6',
+		'chevron-down': 'M6 9l6 6 6-6',
+		'chevron-up': 'M6 15l6-6 6 6',
+		play: 'M7 5l12 7-12 7z',
+		external: 'M14 4h6v6M20 4l-9 9M18 14v5a1 1 0 0 1-1 1H5a1 1 0 0 1-1-1V7a1 1 0 0 1 1-1h5',
+		restart: 'M4 12a8 8 0 1 0 2.4-5.7M4 4v4h4',
+		check: 'M5 12.5l4.5 4.5L19 7.5',
+		plus: 'M12 5v14M5 12h14',
+		minus: 'M5 12h14',
+		fit: 'M4 9V4h5M20 9V4h-5M4 15v5h5M20 15v5h-5',
+		comment: 'M12 3.5a8.5 8.5 0 1 1 0 17H3.5V12A8.5 8.5 0 0 1 12 3.5z',
+		search: 'M11 4.5a6.5 6.5 0 1 0 0 13a6.5 6.5 0 1 0 0-13zM20 20l-4.4-4.4',
+		filter: 'M4 7h16M7 12h10M10 17h4',
+		more: 'M5 11a1 1 0 1 0 0 2a1 1 0 1 0 0-2zM12 11a1 1 0 1 0 0 2a1 1 0 1 0 0-2zM19 11a1 1 0 1 0 0 2a1 1 0 1 0 0-2z',
+		resolve: 'M12 3a9 9 0 1 0 0 18a9 9 0 1 0 0-18zM8 12.2l2.7 2.7L16 9.6',
+		close: 'M6 6l12 12M18 6L6 18',
+		send: 'M12 19V5M6.5 10.5L12 5l5.5 5.5'
+	} as const;
+	export type IconName = keyof typeof PATHS;
+</script>
+
+<script lang="ts">
+	let { name, size = 16 }: { name: IconName; size?: number } = $props();
+</script>
+
+<svg
+	width={size}
+	height={size}
+	viewBox="0 0 24 24"
+	fill="none"
+	stroke="currentColor"
+	stroke-width="1.75"
+	stroke-linecap="round"
+	stroke-linejoin="round"
+	aria-hidden="true"
+>
+	<path d={PATHS[name]} />
+</svg>

package/dist/internal/Icon.svelte.d.ts

@@ -0,0 +1,29 @@
+declare const PATHS: {
+    readonly canvas: "M3 6.5a3.5 3.5 0 1 0 7 0a3.5 3.5 0 1 0-7 0M14 6.5a3.5 3.5 0 1 0 7 0a3.5 3.5 0 1 0-7 0M3 17.5a3.5 3.5 0 1 0 7 0a3.5 3.5 0 1 0-7 0M14 17.5a3.5 3.5 0 1 0 7 0a3.5 3.5 0 1 0-7 0";
+    readonly 'chevron-left': "M15 6l-6 6 6 6";
+    readonly 'chevron-right': "M9 6l6 6-6 6";
+    readonly 'chevron-down': "M6 9l6 6 6-6";
+    readonly 'chevron-up': "M6 15l6-6 6 6";
+    readonly play: "M7 5l12 7-12 7z";
+    readonly external: "M14 4h6v6M20 4l-9 9M18 14v5a1 1 0 0 1-1 1H5a1 1 0 0 1-1-1V7a1 1 0 0 1 1-1h5";
+    readonly restart: "M4 12a8 8 0 1 0 2.4-5.7M4 4v4h4";
+    readonly check: "M5 12.5l4.5 4.5L19 7.5";
+    readonly plus: "M12 5v14M5 12h14";
+    readonly minus: "M5 12h14";
+    readonly fit: "M4 9V4h5M20 9V4h-5M4 15v5h5M20 15v5h-5";
+    readonly comment: "M12 3.5a8.5 8.5 0 1 1 0 17H3.5V12A8.5 8.5 0 0 1 12 3.5z";
+    readonly search: "M11 4.5a6.5 6.5 0 1 0 0 13a6.5 6.5 0 1 0 0-13zM20 20l-4.4-4.4";
+    readonly filter: "M4 7h16M7 12h10M10 17h4";
+    readonly more: "M5 11a1 1 0 1 0 0 2a1 1 0 1 0 0-2zM12 11a1 1 0 1 0 0 2a1 1 0 1 0 0-2zM19 11a1 1 0 1 0 0 2a1 1 0 1 0 0-2z";
+    readonly resolve: "M12 3a9 9 0 1 0 0 18a9 9 0 1 0 0-18zM8 12.2l2.7 2.7L16 9.6";
+    readonly close: "M6 6l12 12M18 6L6 18";
+    readonly send: "M12 19V5M6.5 10.5L12 5l5.5 5.5";
+};
+export type IconName = keyof typeof PATHS;
+type $$ComponentProps = {
+    name: IconName;
+    size?: number;
+};
+declare const Icon: import("svelte").Component<$$ComponentProps, {}, "">;
+type Icon = ReturnType<typeof Icon>;
+export default Icon;

package/dist/internal/Menu.svelte

@@ -0,0 +1,138 @@
+<!--
+  A button that opens a popover menu below it. Items close the menu with `close()`.
+  Follows the ARIA menu button pattern: opening moves focus to the checked item
+  (or the first), Up/Down/Home/End move between items, and Escape, Tab or
+  choosing an item closes the menu and returns focus to the trigger.
+-->
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	let {
+		label,
+		trigger,
+		children,
+		footer,
+		align = 'start',
+		tone = 'light',
+		class: className = ''
+	}: {
+		/** Accessible name for the trigger and the menu. */
+		label: string;
+		trigger: Snippet;
+		children: Snippet<[close: () => void]>;
+		/** Non-interactive content shown below the items, outside the menu role. */
+		footer?: Snippet;
+		align?: 'start' | 'end';
+		tone?: 'light' | 'dark';
+		class?: string;
+	} = $props();
+
+	const id = $props.id();
+	let button = $state<HTMLButtonElement>();
+	let popover = $state<HTMLDivElement>();
+	let menu = $state<HTMLDivElement>();
+	let open = $state(false);
+	// Which item gets focus when the menu opens: the checked one (or first) unless a key asked otherwise.
+	let initial: 'first' | 'last' | undefined;
+
+	const items = () => [...(menu?.querySelectorAll<HTMLElement>('[role^=menuitem]') ?? [])];
+
+	function beforetoggle(event: ToggleEvent) {
+		// Closing with focus inside the menu (Escape, Tab, an item was chosen): hand focus back to the trigger.
+		if (event.newState === 'closed' && popover?.contains(document.activeElement)) button?.focus();
+	}
+
+	function ontoggle(event: ToggleEvent) {
+		open = event.newState === 'open';
+		if (!open || !button || !popover) return;
+		const rect = button.getBoundingClientRect();
+		const gutter = 12;
+		const left = align === 'start' ? rect.left : rect.right - popover.offsetWidth;
+		popover.style.left = `${Math.max(gutter, Math.min(left, window.innerWidth - popover.offsetWidth - gutter))}px`;
+		popover.style.top = `${Math.max(gutter, Math.min(rect.bottom + 6, window.innerHeight - popover.offsetHeight - gutter))}px`;
+
+		focusItem(initial);
+		initial = undefined;
+	}
+
+	function focusItem(which?: 'first' | 'last') {
+		const all = items();
+		const checked = which ? undefined : all.find((item) => item.getAttribute('aria-checked') === 'true');
+		(checked ?? (which === 'last' ? all.at(-1) : all[0]))?.focus();
+	}
+
+	function ontriggerkeydown(event: KeyboardEvent) {
+		if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp') return;
+		event.preventDefault();
+		const which = event.key === 'ArrowUp' ? 'last' : 'first';
+		if (open) return focusItem(which);
+		initial = which;
+		popover?.showPopover();
+	}
+
+	function onmenukeydown(event: KeyboardEvent) {
+		const all = items();
+		const index = all.indexOf(document.activeElement as HTMLElement);
+		let next: HTMLElement | undefined;
+		if (event.key === 'ArrowDown') next = all[(index + 1) % all.length];
+		else if (event.key === 'ArrowUp') next = all.at(index - 1);
+		else if (event.key === 'Home') next = all[0];
+		else if (event.key === 'End') next = all.at(-1);
+		else if (event.key === 'Escape') {
+			// Only the menu closes; the canvas and comments don't see this Escape.
+			event.preventDefault();
+			event.stopPropagation();
+			close();
+			return;
+		} else if (event.key === 'Tab') {
+			// Close and let Tab move on from the trigger.
+			close();
+			return;
+		} else return;
+		event.preventDefault();
+		next?.focus();
+	}
+
+	const close = () => popover?.hidePopover();
+</script>
+
+<button
+	bind:this={button}
+	type="button"
+	id="pf-menu-button-{id}"
+	popovertarget="pf-menu-{id}"
+	aria-label={label}
+	aria-haspopup="menu"
+	aria-expanded={open}
+	aria-controls="pf-menu-items-{id}"
+	title={label}
+	class={className}
+	onkeydown={ontriggerkeydown}
+>
+	{@render trigger()}
+</button>
+<div
+	bind:this={popover}
+	id="pf-menu-{id}"
+	popover="auto"
+	onbeforetoggle={beforetoggle}
+	{ontoggle}
+	class={[
+		'pf-menu fixed inset-auto m-0 max-h-[min(70vh,560px)] w-max min-w-52 max-w-[calc(100vw-24px)] overflow-y-auto rounded border p-1 text-[13px] shadow-lg',
+		tone === 'dark'
+			? 'border-white/10 bg-pf-ink text-white/90'
+			: 'border-pf-line bg-pf-surface text-pf-ink'
+	]}
+>
+	<div
+		bind:this={menu}
+		id="pf-menu-items-{id}"
+		role="menu"
+		tabindex="-1"
+		aria-labelledby="pf-menu-button-{id}"
+		onkeydown={onmenukeydown}
+	>
+		{@render children(close)}
+	</div>
+	{@render footer?.()}
+</div>

package/dist/internal/Menu.svelte.d.ts

@@ -0,0 +1,15 @@
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    /** Accessible name for the trigger and the menu. */
+    label: string;
+    trigger: Snippet;
+    children: Snippet<[close: () => void]>;
+    /** Non-interactive content shown below the items, outside the menu role. */
+    footer?: Snippet;
+    align?: 'start' | 'end';
+    tone?: 'light' | 'dark';
+    class?: string;
+};
+declare const Menu: import("svelte").Component<$$ComponentProps, {}, "">;
+type Menu = ReturnType<typeof Menu>;
+export default Menu;

package/dist/internal/MenuItem.svelte

@@ -0,0 +1,40 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import Icon from './Icon.svelte';
+
+	let {
+		onselect,
+		checked,
+		children,
+		hint,
+		tone = 'light'
+	}: {
+		onselect: () => void;
+		/** Makes this a radio item (`menuitemradio` with `aria-checked`) with a check mark column when not undefined. */
+		checked?: boolean;
+		children: Snippet;
+		hint?: string;
+		tone?: 'light' | 'dark';
+	} = $props();
+</script>
+
+<button
+	type="button"
+	role={checked === undefined ? 'menuitem' : 'menuitemradio'}
+	aria-checked={checked}
+	tabindex="-1"
+	onclick={onselect}
+	class={[
+		'flex w-full items-center gap-2 rounded-[2px] px-2 py-1.5 text-left',
+		tone === 'dark' ? 'hover:bg-white/10 focus-visible:bg-white/10' : 'hover:bg-pf-wash focus-visible:bg-pf-wash',
+		'outline-none'
+	]}
+>
+	{#if checked !== undefined}
+		<span class="w-4 shrink-0 text-pf-accent" aria-hidden="true">
+			{#if checked}<Icon name="check" size={14} />{/if}
+		</span>
+	{/if}
+	<span class="min-w-0 flex-1 truncate">{@render children()}</span>
+	{#if hint}<span class="shrink-0 opacity-50">{hint}</span>{/if}
+</button>

package/dist/internal/MenuItem.svelte.d.ts

@@ -0,0 +1,12 @@
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    onselect: () => void;
+    /** Makes this a radio item (`menuitemradio` with `aria-checked`) with a check mark column when not undefined. */
+    checked?: boolean;
+    children: Snippet;
+    hint?: string;
+    tone?: 'light' | 'dark';
+};
+declare const MenuItem: import("svelte").Component<$$ComponentProps, {}, "">;
+type MenuItem = ReturnType<typeof MenuItem>;
+export default MenuItem;

package/dist/internal/canvas-frame.d.ts

@@ -0,0 +1,2 @@
+/** Let a canvas iframe receive hover while its host owns every other gesture. */
+export declare function canvasFrame(node: HTMLIFrameElement): () => void;

package/dist/internal/canvas-frame.js

@@ -0,0 +1,88 @@
+/** Let a canvas iframe receive hover while its host owns every other gesture. */
+export function canvasFrame(node) {
+    let disconnect = () => { };
+    function connect() {
+        disconnect();
+        delete node.dataset.pfHover;
+        const view = node.contentWindow;
+        // Frame routes are same-origin. Leave an inaccessible frame non-interactive.
+        try {
+            if (!view?.document.body)
+                return;
+        }
+        catch {
+            return;
+        }
+        const removers = [];
+        function listen(type, listener) {
+            view.addEventListener(type, listener, { capture: true, passive: false });
+            removers.push(() => view.removeEventListener(type, listener, { capture: true }));
+        }
+        function block(event) {
+            event.preventDefault();
+            event.stopImmediatePropagation();
+        }
+        function point(event) {
+            const rect = node.getBoundingClientRect();
+            // Frame events use local CSS pixels; canvas handlers use viewport pixels.
+            return {
+                bubbles: true, cancelable: true,
+                clientX: rect.left + event.clientX * rect.width / node.clientWidth,
+                clientY: rect.top + event.clientY * rect.height / node.clientHeight,
+                button: event.button, buttons: event.buttons,
+                altKey: event.altKey, ctrlKey: event.ctrlKey, metaKey: event.metaKey, shiftKey: event.shiftKey
+            };
+        }
+        for (const type of ['pointerdown', 'pointermove', 'pointerup', 'pointercancel']) {
+            listen(type, (event) => {
+                const pointer = event;
+                // Charts and tooltips still receive unpressed pointer movement.
+                if (type !== 'pointermove' || pointer.buttons)
+                    block(event);
+                node.dispatchEvent(new PointerEvent(type, {
+                    ...point(pointer), pointerId: pointer.pointerId, pointerType: pointer.pointerType,
+                    isPrimary: pointer.isPrimary, pressure: pointer.pressure
+                }));
+            });
+        }
+        listen('dblclick', (event) => {
+            block(event);
+            node.dispatchEvent(new MouseEvent('dblclick', point(event)));
+        });
+        listen('wheel', (event) => {
+            block(event);
+            const wheel = event;
+            node.dispatchEvent(new WheelEvent('wheel', {
+                ...point(wheel), deltaX: wheel.deltaX, deltaY: wheel.deltaY,
+                deltaZ: wheel.deltaZ, deltaMode: wheel.deltaMode
+            }));
+        });
+        for (const type of ['keydown', 'keyup']) {
+            listen(type, (event) => {
+                block(event);
+                const key = event;
+                node.dispatchEvent(new KeyboardEvent(type, {
+                    bubbles: true, cancelable: true, key: key.key, code: key.code, repeat: key.repeat,
+                    altKey: key.altKey, ctrlKey: key.ctrlKey, metaKey: key.metaKey, shiftKey: key.shiftKey
+                }));
+            });
+        }
+        for (const type of [
+            'mousedown', 'mouseup', 'click', 'auxclick', 'contextmenu', 'dragstart',
+            'touchstart', 'touchmove', 'touchend', 'beforeinput', 'submit'
+        ])
+            listen(type, block);
+        // Enable hit testing only after the capture guards are in place.
+        node.dataset.pfHover = 'true';
+        disconnect = () => {
+            for (const remove of removers)
+                remove();
+            delete node.dataset.pfHover;
+        };
+    }
+    node.addEventListener('load', connect);
+    return () => {
+        node.removeEventListener('load', connect);
+        disconnect();
+    };
+}

package/dist/internal/canvas-load-queue.d.ts

@@ -0,0 +1,7 @@
+export type ScheduleFrameLoad = (start: (complete: () => void) => void) => () => void;
+export declare function createCanvasLoadQueue(): {
+    request: ScheduleFrameLoad;
+    pause: () => void;
+    resume(): void;
+    destroy(): void;
+};

package/dist/internal/canvas-load-queue.js

@@ -0,0 +1,69 @@
+// Loading and hydration share the canvas's main thread. Leave a short gap after
+// each ready frame, and don't let a failed readiness message stall the queue.
+const START_GAP_MS = 50;
+const LOAD_TIMEOUT_MS = 5_000;
+export function createCanvasLoadQueue() {
+    const pending = new Set();
+    let paused = true;
+    let destroyed = false;
+    let active;
+    let startTimer;
+    let loadTimer;
+    function schedule(delay = 0) {
+        if (paused || destroyed || active || startTimer !== undefined || !pending.size)
+            return;
+        startTimer = setTimeout(() => {
+            startTimer = undefined;
+            const entry = pending.values().next().value;
+            if (paused || destroyed || active || !entry)
+                return;
+            pending.delete(entry);
+            active = entry;
+            entry.start();
+        }, delay);
+    }
+    const request = (start) => {
+        if (destroyed)
+            return () => { };
+        const complete = () => {
+            if (active !== entry)
+                return;
+            clearTimeout(loadTimer);
+            loadTimer = undefined;
+            active = undefined;
+            schedule(START_GAP_MS);
+        };
+        const entry = {
+            start: () => {
+                loadTimer = setTimeout(complete, LOAD_TIMEOUT_MS);
+                start(complete);
+            }
+        };
+        pending.add(entry);
+        schedule();
+        return () => {
+            pending.delete(entry);
+            complete();
+        };
+    };
+    function pause() {
+        paused = true;
+        clearTimeout(startTimer);
+        startTimer = undefined;
+    }
+    return {
+        request,
+        pause,
+        resume() {
+            paused = false;
+            schedule();
+        },
+        destroy() {
+            destroyed = true;
+            pause();
+            clearTimeout(loadTimer);
+            pending.clear();
+            active = undefined;
+        }
+    };
+}

package/dist/internal/comments.d.ts

@@ -0,0 +1,36 @@
+import type { Prototype } from '../types.js';
+/** The part of a comment thread the canvas and player read. */
+export interface CommentThreadPin {
+    /** The frame it is on. */
+    surface: string;
+    /** Pin position in the frame's CSS pixels. */
+    x: number;
+    y: number;
+}
+export interface CommentsOptions {
+    show?: (thread: CommentThreadPin) => boolean | void;
+    describe?: (surface: string) => {
+        title?: string;
+        order?: number;
+    } | undefined;
+}
+/** What the canvas and player use of visual-comments' `VisualComments`. */
+export interface CommentsController {
+    readonly active: boolean;
+    readonly openId: number | undefined;
+    readonly unreadCount: number;
+    toggle(): unknown;
+    configure(options: CommentsOptions): void;
+}
+/** The comments of the prototype, once they have started in the browser. */
+export interface ParaframeComments {
+    readonly current: CommentsController | undefined;
+}
+export declare function setComments(comments: ParaframeComments): void;
+/** The comments object itself, for components that read it reactively. */
+export declare function useCommentsHolder(): ParaframeComments | undefined;
+/** A frame's title and place in reading order, for threads on frames not on screen. */
+export declare function describeFrame(prototype: Prototype, id: string): {
+    title: string;
+    order: number;
+} | undefined;

package/dist/internal/comments.js

@@ -0,0 +1,14 @@
+import { getContext, setContext } from 'svelte';
+const KEY = Symbol('paraframe.comments');
+export function setComments(comments) {
+    setContext(KEY, comments);
+}
+/** The comments object itself, for components that read it reactively. */
+export function useCommentsHolder() {
+    return getContext(KEY);
+}
+/** A frame's title and place in reading order, for threads on frames not on screen. */
+export function describeFrame(prototype, id) {
+    const frame = prototype.get(id);
+    return frame && { title: frame.title, order: frame.index };
+}

package/dist/internal/storage.d.ts

@@ -0,0 +1,3 @@
+export declare function readStored<T>(store: 'local' | 'session', key: string, fallback: T): T;
+export declare function writeStored(store: 'local' | 'session', key: string, value: unknown): void;
+export declare function storageKey(prototypeTitle: string, name: string): string;