fundus 0.22.1 → 0.24.0

package/dist/runtime/geometry.js

@@ -145,6 +145,9 @@ export function computeCanvasPaintLayout(entry, boxWidth, boxHeight, renderRatio
         originY: overdrawDestination.top * renderRatio
     };
 }
+function mapEdges(edges, transform) {
+    return [transform(edges[0]), transform(edges[1]), transform(edges[2]), transform(edges[3])];
+}
 /** Cumulative, rounded edges so adjacent cells abut exactly on integer pixels. */
 function cumulativeEdges(sizes) {
     let accumulated = 0;
@@ -156,15 +159,14 @@ function cumulativeEdges(sizes) {
     return edges;
 }
 /**
- * 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
- * box expanded by `computeOverdrawDestination` on each side, so `dx`/`dy` can be
- * negative and cells can extend past the box.
+ * The grid for a slice filling an integer `boxWidth × boxHeight` box with its
+ * core at the origin: destination edges are integers, so adjacent cells abut
+ * exactly. With overdraw the grid covers the box expanded by
+ * `computeOverdrawDestination` on each side, so the first edges are negative
+ * and the last extend past the box.
  */
-export function computeRenderCells(entry, boxWidth, boxHeight) {
-    if (boxWidth <= 0 || boxHeight <= 0)
-        return [];
-    // Render into a virtual box expanded by the overdraw, then shift every cell
+function integerSliceGrid(entry, boxWidth, boxHeight) {
+    // Render into a virtual box expanded by the overdraw, then shift every edge
     // back so the element core lands exactly in the layout box.
     const overdrawDestination = computeOverdrawDestination(entry, boxWidth, boxHeight);
     const paintWidth = boxWidth + overdrawDestination.left + overdrawDestination.right;
@@ -209,37 +211,51 @@ export function computeRenderCells(entry, boxWidth, boxHeight) {
         bottomDestination = bottom / pixelRatio;
     }
     const centerDestinationHeight = Math.max(0, paintHeight - topDestination - bottomDestination);
-    const sourceColumns = [left, centerWidth, right];
-    const sourceRows = [top, centerHeight, bottom];
-    const sourceColumnStarts = [0, left, left + centerWidth];
-    const sourceRowStarts = [0, top, top + centerHeight];
     const columnEdges = cumulativeEdges([leftDestination, centerDestinationWidth, rightDestination]);
     const rowEdges = cumulativeEdges([topDestination, centerDestinationHeight, bottomDestination]);
-    const cells = [];
-    for (let row = 0; row < 3; row++) {
-        for (let column = 0; column < 3; column++) {
-            const sw = sourceColumns[column];
-            const sh = sourceRows[row];
-            if (sw <= 0 || sh <= 0)
-                continue;
-            const dx = columnEdges[column];
-            const dw = columnEdges[column + 1] - dx;
-            const dy = rowEdges[row];
-            const dh = rowEdges[row + 1] - dy;
-            if (dw <= 0 || dh <= 0)
-                continue;
-            cells.push({
-                key: `${row}-${column}`,
-                sx: sourceColumnStarts[column],
-                sy: sourceRowStarts[row],
-                sw,
-                sh,
-                dx: dx - overdrawDestination.left,
-                dy: dy - overdrawDestination.top,
-                dw,
-                dh
-            });
-        }
+    return {
+        sourceX: [0, left, left + centerWidth, left + centerWidth + right],
+        sourceY: [0, top, top + centerHeight, top + centerHeight + bottom],
+        destX: mapEdges(columnEdges, (edge) => edge - overdrawDestination.left),
+        destY: mapEdges(rowEdges, (edge) => edge - overdrawDestination.top)
+    };
+}
+/**
+ * The renderer-agnostic paint grid for a slice whose core fills the box
+ * `(x, y, width, height)`, in any unit the caller draws in — pass device
+ * pixels for seam-free edges on a GPU. This is exactly the geometry `<Slice>`
+ * and `drawSlice` paint: the box is laid out on the integer grid
+ * `max(1, round(size))` per axis, then scaled back to the requested size and
+ * offset by `(x, y)`. Paint cells by the rule documented on `SliceGrid`.
+ *
+ * Baked-in overdraw paints outside the core box, so `destX[0]` / `destY[0]`
+ * may be smaller than `x` / `y` and the last edges may exceed `x + width` /
+ * `y + height`. The last edges also exceed the box when it is smaller than
+ * the fixed borders: the center clamps to zero and the borders keep their
+ * size.
+ *
+ * A non-positive `width` (or `height`) yields destination edges that all
+ * equal `x` (or `y`), so nothing is painted.
+ *
+ * @throws {RangeError} When any coordinate or dimension is not finite.
+ */
+export function sliceGrid(entry, x, y, width, height) {
+    if (![x, y, width, height].every(Number.isFinite)) {
+        throw new RangeError('Slice grid coordinates and dimensions must be finite.');
     }
-    return cells;
+    const renderWidth = width > 0 ? Math.max(1, Math.round(width)) : 0;
+    const renderHeight = height > 0 ? Math.max(1, Math.round(height)) : 0;
+    const grid = integerSliceGrid(entry, renderWidth, renderHeight);
+    const place = (edges, origin, size, renderSize) => {
+        if (renderSize === 0)
+            return [origin, origin, origin, origin];
+        const scale = size / renderSize;
+        return mapEdges(edges, (edge) => origin + edge * scale);
+    };
+    return {
+        sourceX: grid.sourceX,
+        sourceY: grid.sourceY,
+        destX: place(grid.destX, x, width, renderWidth),
+        destY: place(grid.destY, y, height, renderHeight)
+    };
 }

package/dist/runtime/index.d.ts

@@ -1,12 +1,14 @@
 export { Manifest, createManifest } from './manifest.js';
+export { drawImage, drawSlice } from './canvas.js';
+export type { CanvasDrawTarget } from './canvas.js';
+export { retainEntry } from './retained-entry.js';
+export type { RetainedEntry, RetainedSourceOf } from './retained-entry.js';
 export { default as Image } from './components/Image.svelte';
 export { default as Slice } from './components/Slice.svelte';
-export { sliceLayoutGeometry } from './geometry.js';
-export type { SliceLayoutGeometry, SliceLayoutEntry } from './geometry.js';
+export { sliceGrid, sliceLayoutGeometry } from './geometry.js';
+export type { SliceGrid, SliceLayoutGeometry, SliceLayoutEntry } from './geometry.js';
 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';

package/dist/runtime/index.js

@@ -1,11 +1,11 @@
 // Supported host-facing manifest and rendering APIs for the `fundus` root export.
 export { Manifest, createManifest } from './manifest.js';
+export { drawImage, drawSlice } from './canvas.js';
+export { retainEntry } from './retained-entry.js';
 export { default as Image } from './components/Image.svelte';
 export { default as Slice } from './components/Slice.svelte';
-export { sliceLayoutGeometry } from './geometry.js';
+export { sliceGrid, sliceLayoutGeometry } from './geometry.js';
 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,25 +1,7 @@
-/**
- * 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 — 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
- * (preload-registry.ts); kind-agnostic orchestration lives in `Manifest`.
- */
-import type { AudioManifestEntry, PreloadOptions } from '../core/index.js';
-/** The playable URL hosts feed to their own audio engine. */
-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, for slices the decoded
- * bitmap; cache-backed kinds (image, unknown) hold no disposable resources.
+ * bitmap; image elements and unknown kinds hold no disposable resources.
  */
 export interface KindHandlerResources {
     /** Object URL minted over the fully fetched file (retained media kinds). */
@@ -27,9 +9,9 @@ export interface KindHandlerResources {
     /** 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.
+     * Decoded image or one-slice source, reused for canvas drawing and by
+     * `SliceSourceLifecycle`. Its decode also warms the browser image cache.
+     * Nothing to dispose; release drops the registry's reference.
      */
     image?: HTMLImageElement;
 }
@@ -42,7 +24,7 @@ export interface KindRuntimeHandler {
      * 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, entry?: Record<string, unknown>): Promise<KindHandlerResources>;
+    preload(url: string, byteSize: number, entry?: Record<string, unknown>): Promise<KindHandlerResources>;
     /**
      * The inverse of `preload`: dispose the resources it returned (revoke the
      * object URL, close the bitmap). Omitted = the kind acquires nothing
@@ -51,12 +33,5 @@ export interface KindRuntimeHandler {
     release?(resources: KindHandlerResources): void;
 }
 export declare const RETAINED_KINDS: ReadonlySet<string>;
-/**
- * Whether a source of `kind` decodes under the given per-kind preload options
- * (options are namespaced per plugin type, like `plugins.<type>` in
- * the config). Image-backed kinds decode by default; each kind opts out
- * independently (`{ image: { decode: false } }` leaves slices decoding).
- */
-export declare function shouldDecode(kind: string, options: PreloadOptions): boolean;
 /** The runtime handler owning `kind`'s preload/release strategy (fallback for unknown kinds). */
 export declare function runtimeHandlerFor(kind: string): KindRuntimeHandler;

package/dist/runtime/kind-handlers.js

@@ -1,11 +1,4 @@
 import { plugins } from '../core/plugins/registry.js';
-import { resolveRetainedSource } from './preload-registry.js';
-/** The playable URL hosts feed to their own audio engine. */
-export function audioSourceOf(entry) {
-    return resolveRetainedSource(entry.src);
-}
-/** Entry kinds whose delivered file is an image the browser can pre-decode. */
-const IMAGE_BACKED_KINDS = new Set(['image', 'slice']);
 /**
  * Entry kinds whose delivered file is retained as an object URL by
  * `preload()` while held. A chroma-key-video's own `src` is a video file, so
@@ -18,19 +11,6 @@ const RETAINED_KIND_CATALOGUE = new Set([
     'audio'
 ]);
 export const RETAINED_KINDS = new Set([...RETAINED_KIND_CATALOGUE].filter((kind) => plugins.has(kind)));
-/**
- * Whether a source of `kind` decodes under the given per-kind preload options
- * (options are namespaced per plugin type, like `plugins.<type>` in
- * the config). Image-backed kinds decode by default; each kind opts out
- * independently (`{ image: { decode: false } }` leaves slices decoding).
- */
-export function shouldDecode(kind, options) {
-    if (!IMAGE_BACKED_KINDS.has(kind))
-        return false;
-    // The image-backed check above narrows the kind — only these carry `decode`.
-    const kindOptions = options[kind];
-    return kindOptions?.decode ?? true;
-}
 /**
  * Whether a fetch response represents a successfully delivered resource.
  *
@@ -66,23 +46,24 @@ function verifyByteSize(url, expected, actual) {
     }
 }
 /**
- * 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.
+ * The image strategy: fetch the full file, then decode it via an
+ * HTMLImageElement where a DOM exists (the browser serves the bytes from
+ * cache); headless environments (Node tests, SSR) skip decoding.
+ * Retains the decoded element for canvas drawing until the last holder releases.
+ * Nothing to explicitly dispose — release drops the registry's reference.
  */
 const imageHandler = {
-    async preload(url, byteSize, options) {
+    async preload(url, byteSize) {
         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') {
+        if (typeof globalThis.Image === 'function') {
             const image = new globalThis.Image();
             image.src = url;
             await image.decode();
+            return { image };
         }
         return {};
     }
@@ -101,17 +82,21 @@ const imageHandler = {
  * 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.
+ *
+ * Bitmaps are premultiplied so WebGL uploads match the premultiplied texture a
+ * retained element yields with `UNPACK_PREMULTIPLY_ALPHA_WEBGL` (bitmaps ignore
+ * that flag); Canvas 2D draws either form identically.
  */
 const sliceHandler = {
-    async preload(url, byteSize, options, entry) {
+    async preload(url, byteSize, 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) };
+            return {
+                imageBitmap: await globalThis.createImageBitmap(blob, { premultiplyAlpha: 'premultiply' })
+            };
         }
         if (typeof globalThis.Image === 'function') {
             const image = new globalThis.Image();

package/dist/runtime/manifest.d.ts

@@ -23,6 +23,8 @@ export interface EntrySource {
      */
     entry: Record<string, unknown>;
 }
+/** Reject an entry `byteSize` that is not a non-negative safe integer. */
+export declare function assertEntryByteSize(src: string, byteSize: unknown): asserts byteSize is number;
 /**
  * Collect every deliverable source of an entry, including the entries codegen
  * inlined in place of asset references: a source is any nested object carrying
@@ -38,30 +40,26 @@ export declare class Manifest {
     /**
      * Fetch every deliverable file of this manifest up front — including the
      * reference closure, which codegen inlined into the entries — and decode
-     * image-backed entries. Options are namespaced per asset kind, mirroring
-     * `plugins.<type>` in the config: `{ image: { decode: false } }`
-     * skips decoding for image entries only; slices keep decoding unless
-     * `slice: { decode: false }` is passed too. An option applies to every
-     * entry of its kind, inlined reference entries included.
+     * image-backed entries where a DOM exists. Options are namespaced per asset
+     * kind, mirroring `plugins.<type>` in the config; no kind defines any yet.
      *
      * Idempotent and concurrent-safe: one in-flight promise per manifest; a
      * second call joins it (or resolves immediately once done), and URLs shared
      * by several entries are fetched once. Sharing goes further than this
      * manifest: every URL is acquired through the module-wide refcounted
-     * registry, so a URL another manifest already preloaded (or is preloading)
-     * is never fetched again — this manifest just takes a hold on it. A failed
-     * preload rolls back this manifest's holds and clears the in-flight state
-     * so it can be retried. A joined call's options are ignored: options apply
-     * per preload run (the first call after construction or `release()`).
+     * registry, so a URL another holder (a manifest or a `retainEntry` handle)
+     * already loaded (or is loading) is never fetched again — this manifest
+     * just takes a hold on it. A failed preload rolls back this manifest's
+     * holds and clears the in-flight state so it can be retried.
      */
     preload(options?: PreloadOptions): Promise<void>;
     /**
      * 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, slice bitmaps closed, freeing
-     * the memory). Consumers of a fully released source fall back to its
-     * network URL.
+     * with another holder (a manifest or a `retainEntry` handle) stay fully
+     * alive for that holder; assets nobody holds anymore are disposed via their
+     * kind's release strategy (retained media object URLs are revoked, slice
+     * bitmaps closed, decoded image references dropped). Components fall back
+     * to the 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,4 +1,10 @@
 import { acquireSource, releaseSource } from './preload-registry.js';
+/** Reject an entry `byteSize` that is not a non-negative safe integer. */
+export function assertEntryByteSize(src, byteSize) {
+    if (!Number.isSafeInteger(byteSize) || byteSize < 0) {
+        throw new Error(`Manifest entry for "${src}" requires a non-negative safe integer "byteSize".`);
+    }
+}
 /**
  * Collect every deliverable source of an entry, including the entries codegen
  * inlined in place of asset references: a source is any nested object carrying
@@ -23,9 +29,7 @@ export function collectEntrySources(entry) {
         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".`);
-            }
+            assertEntryByteSize(record.src, record.byteSize);
             sources.push({
                 id: record.id,
                 url: record.src,
@@ -43,8 +47,8 @@ export class Manifest {
     #preloading = null;
     /**
      * URLs this manifest currently holds in the module-wide registry (each
-     * held at most once — the registry's reference count counts holding
-     * manifests, not preload calls). Replaced wholesale by `release()`: an
+     * held at most once — the registry's reference count counts holders, not
+     * preload calls). Replaced wholesale by `release()`: an
      * in-flight preload run keeps operating on the set object it captured, so
      * a release during the run (which drains that set) turns the run's own
      * failure rollback into a no-op instead of a double release.
@@ -64,25 +68,21 @@ export class Manifest {
     /**
      * Fetch every deliverable file of this manifest up front — including the
      * reference closure, which codegen inlined into the entries — and decode
-     * image-backed entries. Options are namespaced per asset kind, mirroring
-     * `plugins.<type>` in the config: `{ image: { decode: false } }`
-     * skips decoding for image entries only; slices keep decoding unless
-     * `slice: { decode: false }` is passed too. An option applies to every
-     * entry of its kind, inlined reference entries included.
+     * image-backed entries where a DOM exists. Options are namespaced per asset
+     * kind, mirroring `plugins.<type>` in the config; no kind defines any yet.
      *
      * Idempotent and concurrent-safe: one in-flight promise per manifest; a
      * second call joins it (or resolves immediately once done), and URLs shared
      * by several entries are fetched once. Sharing goes further than this
      * manifest: every URL is acquired through the module-wide refcounted
-     * registry, so a URL another manifest already preloaded (or is preloading)
-     * is never fetched again — this manifest just takes a hold on it. A failed
-     * preload rolls back this manifest's holds and clears the in-flight state
-     * so it can be retried. A joined call's options are ignored: options apply
-     * per preload run (the first call after construction or `release()`).
+     * registry, so a URL another holder (a manifest or a `retainEntry` handle)
+     * already loaded (or is loading) is never fetched again — this manifest
+     * just takes a hold on it. A failed preload rolls back this manifest's
+     * holds and clears the in-flight state so it can be retried.
      */
     preload(options = {}) {
         if (!this.#preloading) {
-            const tracked = this.#preloadAll(options, this.#heldUrls).catch((cause) => {
+            const tracked = this.#preloadAll(this.#heldUrls).catch((cause) => {
                 // Reset for retry — unless release() or a follow-up preload()
                 // already superseded this run while it was in flight.
                 if (this.#preloading === tracked)
@@ -95,11 +95,11 @@ 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, slice bitmaps closed, freeing
-     * the memory). Consumers of a fully released source fall back to its
-     * network URL.
+     * with another holder (a manifest or a `retainEntry` handle) stay fully
+     * alive for that holder; assets nobody holds anymore are disposed via their
+     * kind's release strategy (retained media object URLs are revoked, slice
+     * bitmaps closed, decoded image references dropped). Components fall back
+     * to the 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
@@ -117,7 +117,7 @@ export class Manifest {
         // captured it) finds nothing left to release.
         held.clear();
     }
-    async #preloadAll(options, held) {
+    async #preloadAll(held) {
         const sourceByUrl = new Map();
         for (const entry of Object.values(this.#entries)) {
             for (const source of collectEntrySources(entry)) {
@@ -132,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, source.entry));
+            acquisitions.push(acquireSource(url, source.kind, source.byteSize, source.entry));
         }
         const outcomes = await Promise.allSettled(acquisitions);
         const failure = outcomes.find((outcome) => outcome.status === 'rejected');

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

@@ -1,30 +1,11 @@
 /**
- * The module-wide refcounted source registry: one entry per
- * URL — reference count, in-flight promise, loaded handler resources.
- *
- * Guarantees:
- * - **Once-per-URL fetches across manifests, all kinds** — a URL in flight or
- *   loaded is never fetched again while held, including image and slice.
- * - **The reference count counts holding manifests, not calls** — each
- *   `Manifest` acquires a URL at most once per hold (its held-URL set guards
- *   idempotent `preload()` calls).
- * - **Release at zero disposes via the kind handler** — the object URL is
- *   revoked and the entry cleared, so releasing one of two holders keeps the
- *   resource fully alive for the other, and a released URL can be re-acquired
- *   with a fresh fetch.
- * - **No leak on release-during-in-flight** — dropping the last hold while
- *   the fetch is still running lets the acquisition complete, then disposes
- *   immediately (no cancellation, no throw).
- */
-import type { PreloadOptions } from '../core/index.js';
-/**
- * Acquire one hold on `url` for a manifest: increments the reference count
+ * Acquire one hold on `url` for a holder: increments the reference count
  * immediately, then loads via the kind handler unless the URL is already
  * loaded (resolves at once) or in flight (joins the pending load). A failed
  * 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, sourceEntry?: Record<string, unknown>): Promise<void>;
+export declare function acquireSource(url: string, kind: string, byteSize: number, 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
@@ -33,19 +14,19 @@ export declare function acquireSource(url: string, kind: string, byteSize: numbe
  */
 export declare function releaseSource(url: string): void;
 /**
- * The retained object URL of a source while some manifest holds it, or the
+ * The retained object URL of a source while some holder holds it, or the
  * source itself when not (or no longer) preloaded — after a full release a
  * 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
+ * The retained decoded source of an image or slice URL while a holder holds
+ * it — a multi-cell slice bitmap or decoded image element — 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;
+export declare function resolveRetainedImageSource(url: string): ImageBitmap | HTMLImageElement | null;
 /**
  * A source's preload state, for render-time diagnostics:
  * - `loaded` — fully preloaded and held (every kind resolves non-null

package/dist/runtime/preload-registry.js

@@ -1,13 +1,32 @@
+/**
+ * The module-wide refcounted source registry: one entry per
+ * URL — reference count, in-flight promise, loaded handler resources.
+ *
+ * Guarantees:
+ * - **Once-per-URL fetches across holders, all kinds** — a URL in flight or
+ *   loaded is never fetched again while held, including image and slice.
+ * - **The reference count counts holders, not calls** — a holder is a
+ *   `Manifest` or a `retainEntry` handle. Each `Manifest` acquires a URL at
+ *   most once per hold (its held-URL set guards idempotent `preload()` calls);
+ *   each handle takes exactly one hold and its idempotent `release` drops it.
+ * - **Release at zero disposes via the kind handler** — the object URL is
+ *   revoked and the entry cleared, so releasing one of two holders keeps the
+ *   resource fully alive for the other, and a released URL can be re-acquired
+ *   with a fresh fetch.
+ * - **No leak on release-during-in-flight** — dropping the last hold while
+ *   the fetch is still running lets the acquisition complete, then disposes
+ *   immediately (no cancellation, no throw).
+ */
 import { runtimeHandlerFor } from './kind-handlers.js';
 const registryByUrl = new Map();
 /**
- * Acquire one hold on `url` for a manifest: increments the reference count
+ * Acquire one hold on `url` for a holder: increments the reference count
  * immediately, then loads via the kind handler unless the URL is already
  * loaded (resolves at once) or in flight (joins the pending load). A failed
  * 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, sourceEntry) {
+export function acquireSource(url, kind, byteSize, sourceEntry) {
     let entry = registryByUrl.get(url);
     if (!entry) {
         entry = { kind, byteSize, referenceCount: 0, pending: null, resources: null };
@@ -23,7 +42,7 @@ export function acquireSource(url, kind, byteSize, options, sourceEntry) {
     if (!pending) {
         const acquired = entry;
         pending = runtimeHandlerFor(kind)
-            .preload(url, byteSize, options, sourceEntry)
+            .preload(url, byteSize, sourceEntry)
             .then((resources) => {
             acquired.pending = null;
             if (acquired.referenceCount === 0) {
@@ -65,7 +84,7 @@ export function releaseSource(url) {
     registryByUrl.delete(url);
 }
 /**
- * The retained object URL of a source while some manifest holds it, or the
+ * The retained object URL of a source while some holder holds it, or the
  * source itself when not (or no longer) preloaded — after a full release a
  * consumer falls back to the network URL and simply streams.
  */
@@ -73,13 +92,13 @@ 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
+ * The retained decoded source of an image or slice URL while a holder holds
+ * it — a multi-cell slice bitmap or decoded image element — 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) {
+export function resolveRetainedImageSource(url) {
     const resources = registryByUrl.get(url)?.resources;
     return resources?.imageBitmap ?? resources?.image ?? null;
 }

package/dist/runtime/retained-entry.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Handle-based retention of one manifest entry's own source: the renderer-
+ * agnostic way to hold a loaded file (Canvas 2D, WebGL, audio engines)
+ * without depending on some manifest still being preloaded. Each handle is
+ * one holder in the module-wide registry (preload-registry.ts), sharing loads
+ * and disposal with manifests.
+ */
+import type { ManifestEntry } from '../core/index.js';
+/**
+ * The retained source a `RetainedEntry` exposes for its entry kind: decoded
+ * pixels for image-backed kinds, a playable URL (an object URL over the fully
+ * fetched file where supported) for media kinds.
+ */
+export type RetainedSourceOf<E extends ManifestEntry> = E extends {
+    kind: 'image' | 'slice';
+} ? HTMLImageElement | ImageBitmap : E extends {
+    kind: 'video' | 'chroma-key-video' | 'audio';
+} ? string : never;
+/** One hold on an entry's loaded source, from `retainEntry`. */
+export interface RetainedEntry<E extends ManifestEntry> {
+    readonly entry: E;
+    /**
+     * The loaded source. The same object for every handle while any holder
+     * keeps the source loaded; a later re-retain may load a new one.
+     *
+     * @throws {Error} After `release()`.
+     */
+    readonly source: RetainedSourceOf<E>;
+    /** Drop this handle's hold. Idempotent; safe to call unbound (`onDestroy(handle.release)`). */
+    readonly release: () => void;
+}
+/**
+ * Take one hold on `entry`'s own source and resolve with a handle to it once
+ * loaded. An already loaded source (e.g. after `manifest.preload()`) resolves
+ * without loading, a source in flight is joined, and an absent one loads via
+ * its kind — deduplicated and cached exactly like `preload()`. Only the
+ * entry's own `src` is retained: a chroma-key-video's `mask` and `fallback`
+ * are separate entries to retain on their own.
+ *
+ * The hold lasts until `release()`, even when the source was already
+ * preloaded; while any holder keeps it, the source object stays the same.
+ * Always release, including when a caller stops waiting for the promise.
+ *
+ * @throws {Error} (rejects) When the entry's `byteSize` is invalid, the load
+ * fails, or an image-backed source cannot be decoded in this environment.
+ * A rejection leaves no hold behind.
+ */
+export declare function retainEntry<E extends ManifestEntry>(entry: E): Promise<RetainedEntry<E>>;