fundus 0.13.0 → 0.15.0

package/dist/runtime/components/Slice.svelte

@@ -1,11 +1,11 @@
 <!--
 	Slice renderer using the entry-based API (slicing arrives inline on the
 	`SliceManifestEntry`). Owns the source lifecycle (load, decode, latest-wins
-	commit) and draws each cell of the committed snapshot 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.
+	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
@@ -17,11 +17,11 @@
 	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 the canvas: with overdraw the
-	canvas 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.
+	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';
@@ -32,7 +32,12 @@
 		type CanvasPaintLayout
 	} from '../geometry.js';
 	import { observeBorderBoxSize } from '../observe-border-box-size.js';
-	import { SliceSourceLifecycle, type LoadedSliceSnapshot } from '../slice-source-lifecycle.js';
+	import {
+		SliceSourceLifecycle,
+		isDetachedSliceSource,
+		type LoadedSliceSnapshot
+	} from '../slice-source-lifecycle.js';
+	import { logRender } from '../logging.js';
 
 	interface Props {
 		src: SliceManifestEntry;
@@ -57,6 +62,8 @@
 		sourceLifecycle.request(src);
 	});
 
+	$effect(() => logRender(src));
+
 	onDestroy(() => sourceLifecycle.dispose());
 
 	let root = $state<HTMLDivElement>();
@@ -131,12 +138,18 @@
 
 	function draw(current: LoadedSliceSnapshot | null, currentLayout: CanvasPaintLayout): void {
 		const element = canvas;
-		if (!element) return;
+		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;
@@ -185,16 +198,27 @@
 <div
 	bind:this={root}
 	class="fundus-slice {className}"
-	role={alt ? 'img' : undefined}
-	aria-label={alt || undefined}
+	role={snapshot?.entry.slicing.mode === 'one' ? undefined : alt ? 'img' : undefined}
+	aria-label={snapshot?.entry.slicing.mode === 'one' ? undefined : alt || undefined}
 >
-	<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 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>
@@ -204,9 +228,15 @@
 		height: 100%;
 	}
 
-	canvas {
+	canvas,
+	img {
 		position: absolute;
 		display: block;
 		pointer-events: none;
 	}
+
+	img {
+		max-width: none;
+		max-height: none;
+	}
 </style>

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/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);
+    }
+}

package/dist/runtime/manifest.d.ts

@@ -11,14 +11,24 @@
 import type { ManifestEntry, PreloadOptions } from '../core/index.js';
 /** One deliverable file of an entry: identity, kind, and expected byte length. */
 export interface EntrySource {
+    /** The asset id the source belongs to — inlined reference sources carry their own. */
+    id: string;
     url: string;
     kind: string;
     byteSize: number;
+    /**
+     * The (possibly inlined) entry the source came from. Kind strategies read
+     * per-entry metadata from it — the slice handler picks its retention form
+     * by slicing mode. Orchestration itself never looks inside.
+     */
+    entry: Record<string, unknown>;
 }
 /**
- * Collect every deliverable URL of an entry, including the entries codegen
- * inlined in place of asset references: any nested object carrying
- * a string `kind` is an entry, and its `src` (when present) is a source.
+ * Collect every deliverable source of an entry, including the entries codegen
+ * inlined in place of asset references: a source is any nested object carrying
+ * a string `id`, `kind`, and `src` — i.e. an asset entry (every generated entry
+ * carries all three). Requiring `id` keeps `EntrySource.id` an honest `string`
+ * and never drops a real source, since codegen bakes an id into every entry.
  * Generic by design: adding a kind does not change preload orchestration.
  */
 export declare function collectEntrySources(entry: ManifestEntry): EntrySource[];
@@ -49,8 +59,9 @@ export declare class Manifest {
      * Drop this manifest's holds on everything it preloaded. Assets shared
      * with another preloaded manifest stay fully alive for that holder; assets
      * nobody holds anymore are disposed via their kind's release strategy
-     * (retained media object URLs are revoked, freeing the memory). Consumers
-     * of a fully released source fall back to its network URL.
+     * (retained media object URLs are revoked, slice bitmaps closed, freeing
+     * the memory). Consumers of a fully released source fall back to its
+     * network URL.
      *
      * Safe in every state: before or without `preload()` it is a no-op, and
      * calling it while a `preload()` is still in flight drops the holds

package/dist/runtime/manifest.js

@@ -1,8 +1,10 @@
 import { acquireSource, releaseSource } from './preload-registry.js';
 /**
- * Collect every deliverable URL of an entry, including the entries codegen
- * inlined in place of asset references: any nested object carrying
- * a string `kind` is an entry, and its `src` (when present) is a source.
+ * Collect every deliverable source of an entry, including the entries codegen
+ * inlined in place of asset references: a source is any nested object carrying
+ * a string `id`, `kind`, and `src` — i.e. an asset entry (every generated entry
+ * carries all three). Requiring `id` keeps `EntrySource.id` an honest `string`
+ * and never drops a real source, since codegen bakes an id into every entry.
  * Generic by design: adding a kind does not change preload orchestration.
  */
 export function collectEntrySources(entry) {
@@ -18,11 +20,19 @@ export function collectEntrySources(entry) {
         if (typeof value !== 'object' || value === null)
             return;
         const record = value;
-        if (typeof record.kind === 'string' && typeof record.src === 'string') {
+        if (typeof record.id === 'string' &&
+            typeof record.kind === 'string' &&
+            typeof record.src === 'string') {
             if (!Number.isSafeInteger(record.byteSize) || record.byteSize < 0) {
                 throw new Error(`Manifest entry for "${record.src}" requires a non-negative safe integer "byteSize".`);
             }
-            sources.push({ url: record.src, kind: record.kind, byteSize: record.byteSize });
+            sources.push({
+                id: record.id,
+                url: record.src,
+                kind: record.kind,
+                byteSize: record.byteSize,
+                entry: record
+            });
         }
         for (const nested of Object.values(record))
             visit(nested);
@@ -87,8 +97,9 @@ export class Manifest {
      * Drop this manifest's holds on everything it preloaded. Assets shared
      * with another preloaded manifest stay fully alive for that holder; assets
      * nobody holds anymore are disposed via their kind's release strategy
-     * (retained media object URLs are revoked, freeing the memory). Consumers
-     * of a fully released source fall back to its network URL.
+     * (retained media object URLs are revoked, slice bitmaps closed, freeing
+     * the memory). Consumers of a fully released source fall back to its
+     * network URL.
      *
      * Safe in every state: before or without `preload()` it is a no-op, and
      * calling it while a `preload()` is still in flight drops the holds
@@ -121,7 +132,7 @@ export class Manifest {
         const acquisitions = [];
         for (const [url, source] of sourceByUrl) {
             held.add(url);
-            acquisitions.push(acquireSource(url, source.kind, source.byteSize, options));
+            acquisitions.push(acquireSource(url, source.kind, source.byteSize, options, source.entry));
         }
         const outcomes = await Promise.allSettled(acquisitions);
         const failure = outcomes.find((outcome) => outcome.status === 'rejected');

package/dist/runtime/preload-registry.d.ts

@@ -24,7 +24,7 @@ import type { PreloadOptions } from '../core/index.js';
  * load clears the in-flight state so the URL stays retryable; the caller
  * rolls back its own hold via `releaseSource`.
  */
-export declare function acquireSource(url: string, kind: string, byteSize: number, options: PreloadOptions): Promise<void>;
+export declare function acquireSource(url: string, kind: string, byteSize: number, options: PreloadOptions, sourceEntry?: Record<string, unknown>): Promise<void>;
 /**
  * Drop one hold on `url`. At zero holds the kind handler's release strategy
  * runs (object URL revoked) and the entry is cleared — unless the load is
@@ -38,3 +38,22 @@ export declare function releaseSource(url: string): void;
  * consumer falls back to the network URL and simply streams.
  */
 export declare function resolveRetainedSource(url: string): string;
+/**
+ * The retained decoded source of a slice URL while some manifest holds it —
+ * the pinned bitmap of a multi-cell slice, or the decoded element of a
+ * one-slice — or `null` when not (or no longer) preloaded; the consumer then
+ * falls back to an async image load. Never returns a closed bitmap: closing
+ * happens only when the entry is dropped from the registry.
+ */
+export declare function resolveRetainedSliceSource(url: string): ImageBitmap | HTMLImageElement | null;
+/**
+ * A source's preload state, for render-time diagnostics:
+ * - `loaded` — fully preloaded and held (every kind resolves non-null
+ *   `resources`, so this holds for image/slice as well as retained media);
+ * - `pending` — a preload is in flight;
+ * - `absent` — never preloaded, released, or a prior preload failed. `absent`
+ *   means "not currently loaded", not "not needed" — a component showing an
+ *   `absent` source fetches it fresh on render.
+ */
+export type SourceStatus = 'loaded' | 'pending' | 'absent';
+export declare function sourceStatus(url: string): SourceStatus;

package/dist/runtime/preload-registry.js

@@ -7,7 +7,7 @@ const registryByUrl = new Map();
  * load clears the in-flight state so the URL stays retryable; the caller
  * rolls back its own hold via `releaseSource`.
  */
-export function acquireSource(url, kind, byteSize, options) {
+export function acquireSource(url, kind, byteSize, options, sourceEntry) {
     let entry = registryByUrl.get(url);
     if (!entry) {
         entry = { kind, byteSize, referenceCount: 0, pending: null, resources: null };
@@ -23,7 +23,7 @@ export function acquireSource(url, kind, byteSize, options) {
     if (!pending) {
         const acquired = entry;
         pending = runtimeHandlerFor(kind)
-            .preload(url, byteSize, options)
+            .preload(url, byteSize, options, sourceEntry)
             .then((resources) => {
             acquired.pending = null;
             if (acquired.referenceCount === 0) {
@@ -72,3 +72,24 @@ export function releaseSource(url) {
 export function resolveRetainedSource(url) {
     return registryByUrl.get(url)?.resources?.objectUrl ?? url;
 }
+/**
+ * The retained decoded source of a slice URL while some manifest holds it —
+ * the pinned bitmap of a multi-cell slice, or the decoded element of a
+ * one-slice — or `null` when not (or no longer) preloaded; the consumer then
+ * falls back to an async image load. Never returns a closed bitmap: closing
+ * happens only when the entry is dropped from the registry.
+ */
+export function resolveRetainedSliceSource(url) {
+    const resources = registryByUrl.get(url)?.resources;
+    return resources?.imageBitmap ?? resources?.image ?? null;
+}
+export function sourceStatus(url) {
+    const entry = registryByUrl.get(url);
+    if (!entry)
+        return 'absent';
+    if (entry.resources !== null)
+        return 'loaded';
+    if (entry.pending !== null)
+        return 'pending';
+    return 'absent';
+}

package/dist/runtime/slice-source-lifecycle.d.ts

@@ -1,14 +1,23 @@
 import type { SliceManifestEntry } from '../core/index.js';
+/** What a committed slice draws from: a decoded element or a retained bitmap. */
+export type SliceRenderSource = HTMLImageElement | ImageBitmap;
 export interface LoadedSliceSnapshot {
     entry: SliceManifestEntry;
-    image: HTMLImageElement;
+    image: SliceRenderSource;
 }
 export type SliceImageLoader = (url: string) => Promise<HTMLImageElement>;
+export type RetainedSliceSourceResolver = (url: string) => SliceRenderSource | null;
+/**
+ * Whether a committed source can no longer be drawn: a preload-retained
+ * bitmap is closed when its last hold is released, and drawing a closed
+ * bitmap throws. A detached source is dropped and reloaded asynchronously.
+ */
+export declare function isDetachedSliceSource(image: SliceRenderSource): boolean;
 export declare function loadSliceImage(url: string): Promise<HTMLImageElement>;
 /** Coordinates requested slice entries with the last image-ready snapshot. */
 export declare class SliceSourceLifecycle {
     #private;
-    constructor(commit: (snapshot: LoadedSliceSnapshot) => void, loadImage?: SliceImageLoader);
+    constructor(commit: (snapshot: LoadedSliceSnapshot) => void, loadImage?: SliceImageLoader, resolveRetained?: RetainedSliceSourceResolver);
     request(entry: SliceManifestEntry): void;
     dispose(): void;
 }

package/dist/runtime/slice-source-lifecycle.js

@@ -1,3 +1,12 @@
+import { resolveRetainedSliceSource } from './preload-registry.js';
+/**
+ * Whether a committed source can no longer be drawn: a preload-retained
+ * bitmap is closed when its last hold is released, and drawing a closed
+ * bitmap throws. A detached source is dropped and reloaded asynchronously.
+ */
+export function isDetachedSliceSource(image) {
+    return typeof ImageBitmap !== 'undefined' && image instanceof ImageBitmap && image.width === 0;
+}
 export function loadSliceImage(url) {
     const image = new Image();
     image.decoding = 'async';
@@ -7,24 +16,34 @@ export function loadSliceImage(url) {
 /** Coordinates requested slice entries with the last image-ready snapshot. */
 export class SliceSourceLifecycle {
     #loadImage;
+    #resolveRetained;
     #commit;
     #requestedEntry = null;
     #displayedSnapshot = null;
     #inFlight = new Map();
     #disposed = false;
-    constructor(commit, loadImage = loadSliceImage) {
+    constructor(commit, loadImage = loadSliceImage, resolveRetained = resolveRetainedSliceSource) {
         this.#commit = commit;
         this.#loadImage = loadImage;
+        this.#resolveRetained = resolveRetained;
     }
     request(entry) {
         if (this.#disposed)
             return;
         this.#requestedEntry = entry;
         const displayed = this.#displayedSnapshot;
-        if (displayed?.entry.src === entry.src) {
+        if (displayed?.entry.src === entry.src && !isDetachedSliceSource(displayed.image)) {
             this.#commitSnapshot({ entry, image: displayed.image });
             return;
         }
+        // A preload-retained source (the pinned bitmap of a multi-cell slice,
+        // the decoded element of a one-slice) commits synchronously — the slice
+        // paints in its mount frame instead of one decode roundtrip later.
+        const retained = this.#resolveRetained(entry.src);
+        if (retained) {
+            this.#commitSnapshot({ entry, image: retained });
+            return;
+        }
         if (this.#inFlight.has(entry.src))
             return;
         let promise;

package/dist/server/codegen.js

@@ -43,7 +43,7 @@ export function manifestModuleFileName(manifestName) {
  */
 export function manifestEntryForAsset(record, proxy, config, registry = serverPluginsByType) {
     const plugin = serverPluginForType(record.type, registry);
-    return plugin.buildManifestEntry({
+    const entry = plugin.buildManifestEntry({
         assetId: proxy.assetId,
         parameters: plugin.descriptor.validateParameters(record.parameters),
         src: `${config.proxyBasePath}${proxy.relativePath
@@ -52,6 +52,10 @@ export function manifestEntryForAsset(record, proxy, config, registry = serverPl
             .join('/')}`,
         proxy
     });
+    // The asset id is the SSOT key codegen already owns — bake it into the
+    // entry centrally so every kind carries it (and a new plugin can't forget
+    // it), rather than repeating it in each plugin's builder.
+    return { id: proxy.assetId, ...entry };
 }
 /**
  * Replace every `{ $asset }` marker in a built entry with the referenced