fundus 0.12.2 → 0.14.0

package/dist/runtime/components/Slice.svelte

@@ -1,31 +1,58 @@
 <!--
-	The slice component hosts rendering: one component, backend chosen per use.
-	Dispatches between the two private implementations — SliceDom (default) and
-	SliceCanvas — which share `computeRenderCells` geometry. The DOM backend maps
-	that geometry to one CSS border-image paint; Canvas draws the cells into one
-	canvas backing store.
+	Slice renderer using the entry-based API (slicing arrives inline on the
+	`SliceManifestEntry`). Owns the source lifecycle (load, decode, latest-wins
+	commit). A one-slice snapshot renders as a regular image; sliced snapshots
+	draw each cell with one `drawImage` into a backing canvas. A ResizeObserver
+	triggers a redraw on resize; window `resize` and DPR changes (browser zoom,
+	moving between displays) redraw too, and a reactive effect redraws when the
+	entry changes — so it also works live inside the editor.
+
+	The backing-store ratio is the devicePixelRatio FLOORED to an integer and
+	capped at `maxDpr` (default 2), never the exact ratio. Cell edges are
+	integer virtual CSS pixels, so an integer ratio lands every drawImage edge on
+	integer backing pixels — abutting cells cannot open an antialiased gap. On
+	displays with a fractional devicePixelRatio (2.625-class Androids, browser
+	zoom, scaled desktops) those gaps are exactly the hairlines this avoids;
+	the compositor applies the remainder to the finished canvas as one
+	upscale, where slice boundaries are plain content. Floor + cap
+	deliberately favor seam-freeness and backing memory over sharpness.
+
+	The measured element is the root div, not its painted child: with overdraw
+	the canvas or image is enlarged by the overdraw's destination size and
+	offset negatively (see `computeCanvasPaintLayout`), so the baked shadow/glow
+	paints outside the layout box while the root (and therefore the layout)
+	keeps the box size.
 -->
 <script lang="ts">
 	import { onDestroy } from 'svelte';
 	import type { SliceManifestEntry } from '../../core/index.js';
-	import { SliceSourceLifecycle, type LoadedSliceSnapshot } from '../slice-source-lifecycle.js';
-	import SliceDom from './SliceDom.svelte';
-	import SliceCanvas from './SliceCanvas.svelte';
+	import {
+		computeCanvasPaintLayout,
+		computeRenderCells,
+		type CanvasPaintLayout
+	} from '../geometry.js';
+	import { observeBorderBoxSize } from '../observe-border-box-size.js';
+	import {
+		SliceSourceLifecycle,
+		isDetachedSliceSource,
+		type LoadedSliceSnapshot
+	} from '../slice-source-lifecycle.js';
+	import { logRender } from '../logging.js';
 
 	interface Props {
 		src: SliceManifestEntry;
 		/**
-		 * Rendering backend. `dom` (default) paints the shared slice geometry as
-		 * one CSS `border-image`; `canvas` draws the same cells into one `<canvas>`
-		 * with a device-pixel-ratio-sized backing store.
+		 * Upper bound of the canvas backing-store ratio (floored itself). The
+		 * default of 2 is rarely distinguishable and keeps backing memory bounded.
 		 */
-		backend?: 'dom' | 'canvas';
+		maxDpr?: number;
 		/** Accessible label for the rendered graphic. */
 		alt?: string;
 		class?: string;
 	}
 
-	let { src, backend = 'dom', alt = '', class: className = '' }: Props = $props();
+	let { src, maxDpr = 2, alt = '', class: className = '' }: Props = $props();
+
 	let snapshot = $state.raw<LoadedSliceSnapshot | null>(null);
 	const sourceLifecycle = new SliceSourceLifecycle((loaded) => {
 		snapshot = loaded;
@@ -35,11 +62,181 @@
 		sourceLifecycle.request(src);
 	});
 
+	$effect(() => logRender(src));
+
 	onDestroy(() => sourceLifecycle.dispose());
+
+	let root = $state<HTMLDivElement>();
+	let canvas = $state<HTMLCanvasElement>();
+	let boxWidth = $state(0);
+	let boxHeight = $state(0);
+	let devicePixelRatio = $state(1);
+	// Bumped by window `resize` so the draw effect re-runs even when neither the
+	// box nor the entry changed (belt and braces alongside the ResizeObserver).
+	let redrawTick = $state(0);
+
+	// Track the display's devicePixelRatio: a resolution media query fires
+	// exactly when the DPR leaves the tracked value (browser zoom, moving the
+	// window to another display). The tracked state must be READ first — a
+	// state the effect writes before reading is deliberately not a dependency
+	// in Svelte, so a write-first version would never re-arm the query after
+	// the first transition. Reconciling via update() converges in one extra
+	// run when the real DPR drifted (mount, or a change event).
+	$effect(() => {
+		const trackedRatio = devicePixelRatio;
+		const query = window.matchMedia(`(resolution: ${trackedRatio}dppx)`);
+		const update = () => {
+			devicePixelRatio = window.devicePixelRatio || 1;
+		};
+		update();
+		query.addEventListener('change', update);
+		return () => query.removeEventListener('change', update);
+	});
+
+	$effect(() => {
+		const element = root;
+		if (!element) return;
+		return observeBorderBoxSize(element, (width, height) => {
+			boxWidth = width;
+			boxHeight = height;
+		});
+	});
+
+	const emptyLayout: CanvasPaintLayout = {
+		renderWidth: 0,
+		renderHeight: 0,
+		cssLeft: 0,
+		cssTop: 0,
+		cssWidth: 0,
+		cssHeight: 0,
+		backingWidth: 0,
+		backingHeight: 0,
+		originX: 0,
+		originY: 0
+	};
+	// The ratio the backing store and every draw use; the css placement is
+	// unaffected, so the compositor bridges any difference on the whole texture.
+	const renderRatio = $derived.by(() => {
+		const cap = Math.max(1, Math.floor(maxDpr));
+		return Math.min(cap, Math.max(1, Math.floor(devicePixelRatio)));
+	});
+
+	const layout = $derived.by(() => {
+		const current = snapshot;
+		return current
+			? computeCanvasPaintLayout(current.entry, boxWidth, boxHeight, renderRatio)
+			: emptyLayout;
+	});
+
+	// Redraw only when a committed snapshot, the box, DPR, or window changes.
+	$effect(() => {
+		const current = snapshot;
+		const currentLayout = layout;
+		void redrawTick;
+		draw(current, currentLayout);
+	});
+
+	function draw(current: LoadedSliceSnapshot | null, currentLayout: CanvasPaintLayout): void {
+		const element = canvas;
+		if (!element || current?.entry.slicing.mode === 'one') return;
+		if (!current || boxWidth === 0 || boxHeight === 0) {
+			element.width = 0;
+			element.height = 0;
+			return;
+		}
+		if (isDetachedSliceSource(current.image)) {
+			// A preload release closed the retained bitmap while this slice stayed
+			// mounted. Keep the last painted pixels and reload asynchronously.
+			sourceLifecycle.request(src);
+			return;
+		}
+
+		element.width = currentLayout.backingWidth;
+		element.height = currentLayout.backingHeight;
+
+		const context = element.getContext('2d');
+		if (!context) return;
+		// Origin at the layout box's top-left, so the (possibly negative) cell
+		// coordinates from computeRenderCells apply directly.
+		context.setTransform(
+			renderRatio,
+			0,
+			0,
+			renderRatio,
+			currentLayout.originX,
+			currentLayout.originY
+		);
+		context.clearRect(
+			currentLayout.cssLeft,
+			currentLayout.cssTop,
+			currentLayout.cssWidth,
+			currentLayout.cssHeight
+		);
+
+		for (const cell of computeRenderCells(
+			current.entry,
+			currentLayout.renderWidth,
+			currentLayout.renderHeight
+		)) {
+			context.drawImage(
+				current.image,
+				cell.sx,
+				cell.sy,
+				cell.sw,
+				cell.sh,
+				cell.dx,
+				cell.dy,
+				cell.dw,
+				cell.dh
+			);
+		}
+	}
 </script>
 
-{#if backend === 'canvas'}
-	<SliceCanvas {snapshot} {alt} class={className} />
-{:else}
-	<SliceDom {snapshot} {alt} class={className} />
-{/if}
+<svelte:window onresize={() => (redrawTick += 1)} />
+
+<div
+	bind:this={root}
+	class="fundus-slice {className}"
+	role={snapshot?.entry.slicing.mode === 'one' ? undefined : alt ? 'img' : undefined}
+	aria-label={snapshot?.entry.slicing.mode === 'one' ? undefined : alt || undefined}
+>
+	{#if snapshot?.entry.slicing.mode === 'one'}
+		<img
+			src={snapshot.entry.src}
+			{alt}
+			style:left="{layout.cssLeft}px"
+			style:top="{layout.cssTop}px"
+			style:width="{layout.cssWidth}px"
+			style:height="{layout.cssHeight}px"
+		/>
+	{:else if snapshot}
+		<canvas
+			bind:this={canvas}
+			style:left="{layout.cssLeft}px"
+			style:top="{layout.cssTop}px"
+			style:width="{layout.cssWidth}px"
+			style:height="{layout.cssHeight}px"
+		></canvas>
+	{/if}
+</div>
+
+<style>
+	.fundus-slice {
+		position: relative;
+		width: 100%;
+		height: 100%;
+	}
+
+	canvas,
+	img {
+		position: absolute;
+		display: block;
+		pointer-events: none;
+	}
+
+	img {
+		max-width: none;
+		max-height: none;
+	}
+</style>

package/dist/runtime/components/Slice.svelte.d.ts

@@ -2,11 +2,10 @@ import type { SliceManifestEntry } from '../../core/index.js';
 interface Props {
     src: SliceManifestEntry;
     /**
-     * Rendering backend. `dom` (default) paints the shared slice geometry as
-     * one CSS `border-image`; `canvas` draws the same cells into one `<canvas>`
-     * with a device-pixel-ratio-sized backing store.
+     * Upper bound of the canvas backing-store ratio (floored itself). The
+     * default of 2 is rarely distinguishable and keeps backing memory bounded.
      */
-    backend?: 'dom' | 'canvas';
+    maxDpr?: number;
     /** Accessible label for the rendered graphic. */
     alt?: string;
     class?: string;

package/dist/runtime/components/Video.svelte

@@ -7,6 +7,7 @@
 <script lang="ts">
 	import type { VideoManifestEntry } from '../../core/index.js';
 	import { resolveRetainedSource } from '../preload-registry.js';
+	import { logRender } from '../logging.js';
 
 	interface Props {
 		src: VideoManifestEntry;
@@ -35,6 +36,8 @@
 
 	const source = $derived(resolveRetainedSource(src.src));
 
+	$effect(() => logRender(src));
+
 	$effect(() => {
 		const video = videoElement;
 		if (!video) return;

package/dist/runtime/geometry.d.ts

@@ -58,22 +58,27 @@ export declare function effectiveOverdraw(entry: SliceManifestEntry): SliceInset
  */
 export declare function computeOverdrawDestination(entry: SliceManifestEntry, boxWidth: number, boxHeight: number): SliceInsets;
 /**
- * How the canvas backend's `<canvas>` relates to the layout box: with overdraw
+ * How the slice renderer's `<canvas>` relates to the layout box: with overdraw
  * the canvas is enlarged by the overdraw's destination size and offset
  * negatively, so the baked shadow/glow paints outside the layout box while the
  * wrapper (and therefore the layout) keeps the box size. The backing store is
- * the CSS size × `devicePixelRatio` (rounded) for crispness, and the paint
- * origin sits at the layout box's top-left in device pixels — so the (possibly
- * negative) cell coordinates from `computeRenderCells` apply directly.
+ * the rounded virtual CSS size × the integer render ratio. This matches the
+ * integer final edges from `computeRenderCells`; the browser scales the
+ * completed texture to the possibly fractional CSS size. The paint origin sits
+ * at the layout box's top-left in backing pixels — so the (possibly negative)
+ * cell coordinates from `computeRenderCells` apply directly.
  */
 export interface CanvasPaintLayout {
+    /** Integer virtual layout-box size used by `computeRenderCells`. */
+    renderWidth: number;
+    renderHeight: number;
     /** CSS offset of the canvas within the wrapper (0 or negative — overdraw). */
     cssLeft: number;
     cssTop: number;
-    /** CSS size of the canvas (box expanded by the overdraw's destination size). */
+    /** CSS size of the scaled canvas, including overdraw. */
     cssWidth: number;
     cssHeight: number;
-    /** Backing-store size in device pixels (CSS size × devicePixelRatio). */
+    /** Backing-store size in pixels (rounded virtual CSS size × render ratio). */
     backingWidth: number;
     backingHeight: number;
     /** Paint origin (the layout box's top-left) in device pixels. */
@@ -82,10 +87,11 @@ export interface CanvasPaintLayout {
 }
 /**
  * The canvas geometry for a slice filling a `boxWidth × boxHeight` layout box
- * at the given `devicePixelRatio` (the display's, not the asset's export
- * scale). Pure — the canvas backend derives every size and offset from this.
+ * at the given integer render ratio (the floored/capped display DPR, not the
+ * asset's export scale). Pure — the slice renderer derives every size and
+ * offset from this.
  */
-export declare function computeCanvasPaintLayout(entry: SliceManifestEntry, boxWidth: number, boxHeight: number, devicePixelRatio: number): CanvasPaintLayout;
+export declare function computeCanvasPaintLayout(entry: SliceManifestEntry, boxWidth: number, boxHeight: number, renderRatio: number): CanvasPaintLayout;
 /**
  * Compute the cells to paint for a slice filling a `boxWidth × boxHeight` box.
  * Returns an empty array for a zero-size box. With overdraw the cells cover the

package/dist/runtime/geometry.js

@@ -85,23 +85,30 @@ export function computeOverdrawDestination(entry, boxWidth, boxHeight) {
 }
 /**
  * The canvas geometry for a slice filling a `boxWidth × boxHeight` layout box
- * at the given `devicePixelRatio` (the display's, not the asset's export
- * scale). Pure — the canvas backend derives every size and offset from this.
+ * at the given integer render ratio (the floored/capped display DPR, not the
+ * asset's export scale). Pure — the slice renderer derives every size and
+ * offset from this.
  */
-export function computeCanvasPaintLayout(entry, boxWidth, boxHeight, devicePixelRatio) {
-    const overdrawDestination = computeOverdrawDestination(entry, boxWidth, boxHeight);
-    const cssWidth = boxWidth + overdrawDestination.left + overdrawDestination.right;
-    const cssHeight = boxHeight + overdrawDestination.top + overdrawDestination.bottom;
+export function computeCanvasPaintLayout(entry, boxWidth, boxHeight, renderRatio) {
+    const renderWidth = boxWidth > 0 ? Math.max(1, Math.round(boxWidth)) : 0;
+    const renderHeight = boxHeight > 0 ? Math.max(1, Math.round(boxHeight)) : 0;
+    const overdrawDestination = computeOverdrawDestination(entry, renderWidth, renderHeight);
+    const virtualWidth = renderWidth + overdrawDestination.left + overdrawDestination.right;
+    const virtualHeight = renderHeight + overdrawDestination.top + overdrawDestination.bottom;
+    const horizontalScale = renderWidth > 0 ? boxWidth / renderWidth : 1;
+    const verticalScale = renderHeight > 0 ? boxHeight / renderHeight : 1;
     return {
+        renderWidth,
+        renderHeight,
         // `+ 0` normalizes the negative zero a zero overdraw would produce.
-        cssLeft: -overdrawDestination.left + 0,
-        cssTop: -overdrawDestination.top + 0,
-        cssWidth,
-        cssHeight,
-        backingWidth: Math.round(cssWidth * devicePixelRatio),
-        backingHeight: Math.round(cssHeight * devicePixelRatio),
-        originX: overdrawDestination.left * devicePixelRatio,
-        originY: overdrawDestination.top * devicePixelRatio
+        cssLeft: -overdrawDestination.left * horizontalScale + 0,
+        cssTop: -overdrawDestination.top * verticalScale + 0,
+        cssWidth: virtualWidth * horizontalScale,
+        cssHeight: virtualHeight * verticalScale,
+        backingWidth: virtualWidth * renderRatio,
+        backingHeight: virtualHeight * renderRatio,
+        originX: overdrawDestination.left * renderRatio,
+        originY: overdrawDestination.top * renderRatio
     };
 }
 /** Cumulative, rounded edges so adjacent cells abut exactly on integer pixels. */

package/dist/runtime/index.d.ts

@@ -5,5 +5,8 @@ export { default as Video } from './components/Video.svelte';
 export { default as ChromaKeyVideo } from './components/ChromaKeyVideo.svelte';
 export { resolveRetainedSource } from './preload-registry.js';
 export { audioSourceOf } from './kind-handlers.js';
+export { setFundusLogger } from './logging.js';
+export type { FundusLogger, RenderedSource } from './logging.js';
+export type { SourceStatus } from './preload-registry.js';
 export type { ImageManifestEntry, SliceManifestEntry, VideoManifestEntry, ChromaKeyVideoManifestEntry, AudioManifestEntry, ManifestEntry, ChromaKeyParameters, ImagePreloadOptions, SlicePreloadOptions, VideoPreloadOptions, ChromaKeyVideoPreloadOptions, AudioPreloadOptions, PreloadOptions } from '../core/index.js';
 export { DEFAULT_CHROMA_KEY_PARAMETERS } from '../core/index.js';

package/dist/runtime/index.js

@@ -6,4 +6,5 @@ export { default as Video } from './components/Video.svelte';
 export { default as ChromaKeyVideo } from './components/ChromaKeyVideo.svelte';
 export { resolveRetainedSource } from './preload-registry.js';
 export { audioSourceOf } from './kind-handlers.js';
+export { setFundusLogger } from './logging.js';
 export { DEFAULT_CHROMA_KEY_PARAMETERS } from '../core/index.js';

package/dist/runtime/kind-handlers.d.ts

@@ -1,11 +1,13 @@
 /**
  * The runtime part of the type-plugin contract: per-kind preload
  * strategy and its inverse release strategy. Each first-party kind registers
- * a handler that knows how its delivered file is loaded — image-backed kinds
- * fetch + optionally decode, media kinds (video/audio) fetch fully and mint
- * an object URL — and how what it loaded is disposed (revoke the object URL;
- * image-backed kinds have nothing to dispose). An unknown kind falls back to
- * a plain full fetch: no decode, no retention.
+ * a handler that knows how its delivered file is loaded — images fetch +
+ * optionally decode, slices fetch and retain a decoded form (an ImageBitmap
+ * for multi-cell slices, the decoded element for one-slices), media kinds
+ * (video/audio) fetch fully and mint an object URL — and how what it loaded
+ * is disposed (revoke the object URL, close the bitmap; images have nothing
+ * to dispose). An unknown kind falls back to a plain full fetch: no decode,
+ * no retention.
  *
  * Handlers are pure strategy: refcounting, cross-manifest dedup, and
  * in-flight bookkeeping live in the module-wide registry
@@ -16,12 +18,20 @@ import type { AudioManifestEntry, PreloadOptions } from '../core/index.js';
 export declare function audioSourceOf(entry: AudioManifestEntry): string;
 /**
  * What a handler's `preload` acquired and its `release` must dispose. For
- * retained media kinds this is the minted object URL; cache-backed kinds
- * (image, slice, unknown) hold no disposable resources.
+ * retained media kinds this is the minted object URL, for slices the decoded
+ * bitmap; cache-backed kinds (image, unknown) hold no disposable resources.
  */
 export interface KindHandlerResources {
     /** Object URL minted over the fully fetched file (retained media kinds). */
     objectUrl?: string;
+    /** Decoded pixels of a multi-cell slice source, pinned against cache eviction. */
+    imageBitmap?: ImageBitmap;
+    /**
+     * Decoded element of a one-slice source: the synchronous-commit token for
+     * `SliceSourceLifecycle`, whose decode also warms the (evictable) browser
+     * cache the mounted `<img>` paints from. Nothing to dispose.
+     */
+    image?: HTMLImageElement;
 }
 /** How one asset kind preloads — and releases — its delivered file. */
 export interface KindRuntimeHandler {
@@ -29,12 +39,14 @@ export interface KindRuntimeHandler {
      * Fully load one source of this kind — the promise resolves only once the
      * file is completely transferred (plus the kind's strategy: decoded /
      * retained as an object URL), its body matches the build-time `byteSize`,
-     * and return the resources `release` disposes.
+     * and return the resources `release` disposes. `entry` is the manifest
+     * entry the source came from, for strategies keyed on entry metadata.
      */
-    preload(url: string, byteSize: number, options: PreloadOptions): Promise<KindHandlerResources>;
+    preload(url: string, byteSize: number, options: PreloadOptions, entry?: Record<string, unknown>): Promise<KindHandlerResources>;
     /**
      * The inverse of `preload`: dispose the resources it returned (revoke the
-     * object URL). Omitted = the kind acquires nothing disposable.
+     * object URL, close the bitmap). Omitted = the kind acquires nothing
+     * disposable.
      */
     release?(resources: KindHandlerResources): void;
 }

package/dist/runtime/kind-handlers.js

@@ -66,28 +66,65 @@ function verifyByteSize(url, expected, actual) {
     }
 }
 /**
- * The image-backed strategy (image, slice): fetch the full file, then decode
- * by default. Decoding goes via an HTMLImageElement where a DOM exists (the
- * browser serves the bytes from cache); headless environments (Node tests,
- * SSR) skip decoding. Nothing to release — the browser cache owns the bytes.
+ * The image strategy: fetch the full file, then decode by default. Decoding
+ * goes via an HTMLImageElement where a DOM exists (the browser serves the
+ * bytes from cache); headless environments (Node tests, SSR) skip decoding.
+ * Nothing to release — the browser cache owns the bytes, and the mounted
+ * `<img>` decodes from it.
  */
-function imageBackedHandler(kind) {
-    return {
-        async preload(url, byteSize, options) {
-            const response = await fetchCompletely(url);
-            // Read the body fully so the file is actually transferred (and
-            // cached), not just the response headers.
-            const bytes = await response.arrayBuffer();
-            verifyByteSize(url, byteSize, bytes.byteLength);
-            if (shouldDecode(kind, options) && typeof globalThis.Image === 'function') {
-                const image = new globalThis.Image();
-                image.src = url;
-                await image.decode();
-            }
+const imageHandler = {
+    async preload(url, byteSize, options) {
+        const response = await fetchCompletely(url);
+        // Read the body fully so the file is actually transferred (and
+        // cached), not just the response headers.
+        const bytes = await response.arrayBuffer();
+        verifyByteSize(url, byteSize, bytes.byteLength);
+        if (shouldDecode('image', options) && typeof globalThis.Image === 'function') {
+            const image = new globalThis.Image();
+            image.src = url;
+            await image.decode();
+        }
+        return {};
+    }
+};
+/**
+ * The slice strategy: fetch the full file and retain a decoded form while
+ * held, chosen by the entry's slicing mode. Multi-cell slices (nine,
+ * three-*) draw through a canvas and retain the pixels as an ImageBitmap —
+ * unlike a throwaway decode into the browser's evictable image cache, the
+ * bitmap survives memory pressure and lets `SliceSourceLifecycle` commit
+ * synchronously, so a preloaded slice paints in its mount frame. One-slice
+ * sources render as a plain `<img>`, which cannot paint from a bitmap: they
+ * retain the decoded HTMLImageElement instead — the same synchronous commit,
+ * and its decode warms the (evictable) cache the mounted `<img>` paints
+ * from. Release closes the bitmap; a retained element has nothing to
+ * dispose. Slice sources are small (the insets cover every rendered size),
+ * so retention is cheap. Environments without `createImageBitmap` retain the
+ * decoded element for every mode.
+ */
+const sliceHandler = {
+    async preload(url, byteSize, options, entry) {
+        const response = await fetchCompletely(url);
+        const blob = await response.blob();
+        verifyByteSize(url, byteSize, blob.size);
+        if (!shouldDecode('slice', options))
             return {};
+        const oneSlice = entry?.slicing?.mode === 'one';
+        if (!oneSlice && typeof globalThis.createImageBitmap === 'function') {
+            return { imageBitmap: await globalThis.createImageBitmap(blob) };
         }
-    };
-}
+        if (typeof globalThis.Image === 'function') {
+            const image = new globalThis.Image();
+            image.src = url;
+            await image.decode();
+            return { image };
+        }
+        return {};
+    },
+    release(resources) {
+        resources.imageBitmap?.close();
+    }
+};
 /**
  * The retained-media strategy (video, chroma-key-video, audio): fetch the
  * full file and retain it as an object URL so later playback does not touch
@@ -118,8 +155,8 @@ const unknownKindHandler = {
     }
 };
 const runtimeHandlerCatalogue = {
-    image: imageBackedHandler('image'),
-    slice: imageBackedHandler('slice'),
+    image: imageHandler,
+    slice: sliceHandler,
     video: retainedMediaHandler,
     'chroma-key-video': retainedMediaHandler,
     audio: retainedMediaHandler

package/dist/runtime/logging.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Opt-in render-time diagnostics: a host registers one logger and every Fundus
+ * render component reports, on mount and whenever its displayed asset changes,
+ * which sources it needs and whether each was preloaded. Purely additive and
+ * gated — with no logger registered this is a single null-check, no walk, no
+ * cost. It never participates in rendering: `logRender` swallows any error
+ * (a malformed entry, a throwing logger) so diagnostics can't break the view.
+ */
+import type { ManifestEntry } from '../core/index.js';
+import { type SourceStatus } from './preload-registry.js';
+/** One rendered source and its preload state at the moment of the render. */
+export interface RenderedSource {
+    /** The asset id the source belongs to — an inlined mask/fallback carries its own. */
+    id: string;
+    kind: string;
+    url: string;
+    status: SourceStatus;
+}
+export interface FundusLogger {
+    /**
+     * Reported once per component render (mount and each in-place asset swap),
+     * listing every source the component displays. A single-file kind yields one
+     * source; a chroma-key-video yields its video plus the inlined mask/fallback.
+     * Sources are not deduped — a url shared by two of them appears twice.
+     */
+    onRender(sources: RenderedSource[]): void;
+}
+/** Register (or clear, with `null`) the process-wide render logger. */
+export declare function setFundusLogger(logger: FundusLogger | null): void;
+/**
+ * Report the sources a component is rendering and their current preload state.
+ * A no-op without a registered logger; never throws.
+ */
+export declare function logRender(entry: ManifestEntry): void;

package/dist/runtime/logging.js

@@ -0,0 +1,27 @@
+import { collectEntrySources } from './manifest.js';
+import { sourceStatus } from './preload-registry.js';
+let activeLogger = null;
+/** Register (or clear, with `null`) the process-wide render logger. */
+export function setFundusLogger(logger) {
+    activeLogger = logger;
+}
+/**
+ * Report the sources a component is rendering and their current preload state.
+ * A no-op without a registered logger; never throws.
+ */
+export function logRender(entry) {
+    if (!activeLogger)
+        return;
+    try {
+        activeLogger.onRender(collectEntrySources(entry).map((source) => ({
+            id: source.id,
+            kind: source.kind,
+            url: source.url,
+            status: sourceStatus(source.url)
+        })));
+    }
+    catch (cause) {
+        // Diagnostics must never break rendering.
+        console.warn('fundus: render logging failed', cause);
+    }
+}