@expofp/renderer 3.2.5 → 3.27.0

package/dist/objects/containers/props.d.ts

@@ -0,0 +1,23 @@
+import { type RenderableDef } from '../../types/defs';
+/** Props for a component drawing one layer's defs. */
+export interface DefsProps<T extends RenderableDef> {
+    /**
+     * The defs to draw, in paint order. Layer-level concerns (`hidden`, `dim`, pointer handlers)
+     * belong to `<Layer>`, not here.
+     *
+     * A **new array identity means the collection may have changed** — that is the whole contract.
+     * Callers must not pass a layer's `children` directly: it is mutated in place, so its identity
+     * never changes and a memoizing compiler would keep serving a stale instance list. Pass the
+     * version-keyed snapshot from `useStagedChildren`, whose identity changes exactly when the layer is
+     * updated.
+     */
+    defs: readonly T[];
+}
+/** Props for a component keeping one def's instance in sync. */
+export interface InstanceProps<T extends RenderableDef, C> {
+    /** The def this instance draws. */
+    def: T;
+    /** The container holding the instance. */
+    container: C;
+}
+//# sourceMappingURL=props.d.ts.map

package/dist/objects/containers/props.js

@@ -0,0 +1 @@
+export {};

package/dist/objects/images/ImageInstance.d.ts

@@ -0,0 +1,29 @@
+import { type ImageDef } from '../../types/defs';
+import { type InstanceProps } from '../containers';
+import { type PackedImage } from './atlas-packer';
+import { type ImageContainer } from './image-container';
+/** Props for {@link ImageInstance}. */
+export interface ImageInstanceProps extends InstanceProps<ImageDef, ImageContainer> {
+    /**
+     * The atlas placement this instance draws — the whole image, or one tile of a split one. A def
+     * whose source was cut across atlases has several instances, one per {@link PackedImage}.
+     */
+    packed: PackedImage;
+}
+/**
+ * Keeps one image placement current: claims a slot on mount (where the container writes the fixed
+ * uv region), writes the def's transform and visibility on mount and after every `update(def)`, and
+ * releases the slot on unmount.
+ *
+ * Renders no scene node — the mesh belongs to the container. Only the transform lives here:
+ * visibility is `useDefSync`'s, the uv region is written once at claim (a def's source cannot
+ * change), and color has no analogue for a textured quad. Memoized for the same reason as
+ * `ShapeInstance`: a structural change hands the atlas a fresh placement list, rebuilding every
+ * instance element, so only prop-equality keeps the unchanged siblings from re-rendering. Both props
+ * are identity-stable across a membership's lifetime — a change repacks into a fresh container and
+ * fresh placements — so the bailout holds.
+ * @param props - The def, its placement, and its container.
+ * @returns `null`; the instance lives in the mesh, not the scene graph.
+ */
+export declare const ImageInstance: import("react").MemoExoticComponent<(props: ImageInstanceProps) => null>;
+//# sourceMappingURL=ImageInstance.d.ts.map

package/dist/objects/images/ImageInstance.js

@@ -0,0 +1,83 @@
+import { memo } from 'react';
+import { Matrix4 } from 'three';
+import { shapeToMatrix, useDefSync, writeMatrixIfChanged } from '../containers';
+import { imageSourceSize } from './atlas-packer';
+/**
+ * Keeps one image placement current: claims a slot on mount (where the container writes the fixed
+ * uv region), writes the def's transform and visibility on mount and after every `update(def)`, and
+ * releases the slot on unmount.
+ *
+ * Renders no scene node — the mesh belongs to the container. Only the transform lives here:
+ * visibility is `useDefSync`'s, the uv region is written once at claim (a def's source cannot
+ * change), and color has no analogue for a textured quad. Memoized for the same reason as
+ * `ShapeInstance`: a structural change hands the atlas a fresh placement list, rebuilding every
+ * instance element, so only prop-equality keeps the unchanged siblings from re-rendering. Both props
+ * are identity-stable across a membership's lifetime — a change repacks into a fresh container and
+ * fresh placements — so the bailout holds.
+ * @param props - The def, its placement, and its container.
+ * @returns `null`; the instance lives in the mesh, not the scene graph.
+ */
+export const ImageInstance = memo(function ImageInstance(props) {
+    const { def, packed, container } = props;
+    useDefSync(container, def, packed, (slot) => {
+        writeImageMatrix(container.mesh, slot, def, packed);
+    });
+    return null;
+});
+/**
+ * Writes an image placement's transform into its instance, skipping the write when nothing moved.
+ *
+ * `bounds` is a rect, so the quad's placement composes exactly as a rect shape's does; the image's
+ * own offsets are then post-multiplied onto it, innermost last. The origin shifts the quad within
+ * its own unit square so the anchor — not the quad's center — lands on `bounds.center`, which also
+ * makes the anchor the point rotation pivots about. A split source draws as several instances, so
+ * this instance's quad is finally shrunk onto the fraction of the image its tile covers.
+ * @param mesh - The mesh holding the instance.
+ * @param slot - The instance's slot.
+ * @param def - The image def supplying the transform.
+ * @param packed - This instance's placement, whose `source` region marks it as a tile.
+ */
+function writeImageMatrix(mesh, slot, def, packed) {
+    // The shared scratch `shapeToMatrix` returns, adjusted in place below and uploaded before any
+    // other write can claim it.
+    const matrix = shapeToMatrix(def.bounds);
+    // Unit-plane axes run the same way as image axes — x right, y down, matching the atlas uv and the
+    // scene's y-down coordinates — so an origin of `[0, 0]` (top-left) shifts the quad by a positive
+    // half in both, putting its top-left corner on the bounds' center.
+    const [originX, originY] = def.origin ?? DEFAULT_ORIGIN;
+    matrix.multiply(_origin.makeTranslation(0.5 - originX, 0.5 - originY, 0));
+    if (packed.source)
+        applyTile(matrix, packed.source, def);
+    writeMatrixIfChanged(mesh, slot, matrix);
+}
+/**
+ * Post-multiplies the image transform by the local sub-quad a tile occupies, so a split source's
+ * tiles reassemble into the whole image. The tile's fraction of the source (in source pixels) is
+ * its fraction of the image, so the sub-quad is that fraction of the unit plane — scaled to the
+ * tile's size and translated to its center, both in unit-plane coordinates.
+ * @param matrix - The image transform, multiplied in place.
+ * @param source - The tile's region of the source, in source pixels.
+ * @param def - The def whose source supplies the total pixel dimensions.
+ */
+function applyTile(matrix, source, def) {
+    const { width, height } = imageSourceSize(def.source);
+    if (width <= 0 || height <= 0)
+        return;
+    const fx0 = source.x / width;
+    const fy0 = source.y / height;
+    const fx1 = (source.x + source.width) / width;
+    const fy1 = (source.y + source.height) / height;
+    _tile
+        .makeScale(fx1 - fx0, fy1 - fy0, 1)
+        .setPosition((fx0 + fx1) / 2 - 0.5, (fy0 + fy1) / 2 - 0.5, 0);
+    matrix.multiply(_tile);
+}
+/**
+ * The anchor a def leaves unset: the image's center, so `bounds.center` is where the middle of the
+ * image sits. Matches {@link ImageDef.origin}'s documented default.
+ */
+const DEFAULT_ORIGIN = [0.5, 0.5];
+// Scratch shared by every instance and every write: filled and uploaded within a single
+// synchronous statement, so an instance costs a texture write and no allocation.
+const _origin = new Matrix4();
+const _tile = new Matrix4();

package/dist/objects/images/Images.d.ts

@@ -0,0 +1,37 @@
+import { type ImageDef } from '../../types/defs';
+import { type DefsProps } from '../containers';
+/** Props for {@link Images}. */
+export interface ImagesProps extends DefsProps<ImageDef> {
+    /**
+     * Largest atlas edge in pixels, capping how big a source can be before it is split into tiles.
+     * Defaults to the GPU's `maxTextureSize`, which is the true hardware ceiling; pass a smaller
+     * value to cap atlas memory below it, or to force splitting deterministically in a test.
+     */
+    maxAtlasSize?: number;
+}
+/**
+ * Draws a collection of images as textured quads, packing their pixels into one or more atlases and
+ * drawing each atlas as a single `InstancedMesh` — so a layer of many images costs a handful of
+ * draw calls, not one per image.
+ *
+ * Unlike a shape layer, an image layer can span **several meshes**: bin-packing splits the images
+ * across as many atlases as their pixels need, and each atlas gets its own mesh, batch, and
+ * texture (an {@link ImageAtlas}). A def whose source is too big for one atlas is cut into tiles
+ * that may land on different atlases, so one def can drive several instances — the atlas iterates
+ * its packed placements, not the defs.
+ *
+ * Packing has no incremental path, so a change to the **set** of images **repacks from scratch**: a
+ * fresh atlas set under fresh keys, remounting every mesh and instance. A **reorder** of the same
+ * set does not — packing is order-independent, so the atlases stand and each simply re-labels its
+ * instances' paint order in place. A per-def `update()` flows straight to the instance's slot, never
+ * through here.
+ *
+ * Paint order holds **within** an atlas (each mesh sorts its instances by the def's membership
+ * index) but is best-effort **across** atlases: separate meshes draw in atlas order, which packing
+ * decides, not paint order. Overlapping images in one layer that pack onto different atlases is the
+ * one case this does not order — rare for the markers, dots, and logos an image layer holds.
+ * @param props - The images to draw.
+ * @returns One {@link ImageAtlas} per packed atlas.
+ */
+export declare function Images(props: ImagesProps): import("react").JSX.Element;
+//# sourceMappingURL=Images.d.ts.map

package/dist/objects/images/Images.js

@@ -0,0 +1,204 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useThree } from '@react-three/fiber';
+import { use, useEffect, useRef, useState } from 'react';
+import { CanvasTexture, SRGBColorSpace } from 'three';
+import { InstancedMesh } from '../../core/instanced/InstancedMesh';
+import { defKey, useContainer } from '../containers';
+import { TextureMaterial } from '../materials/TextureMaterial';
+import { packAtlases } from './atlas-packer';
+import { ImageContainer, UV_OFFSET_UNIFORM } from './image-container';
+import { ImageInstance } from './ImageInstance';
+import { TextureBudgetContext, useResizeFactor } from './texture-budget';
+/**
+ * Draws a collection of images as textured quads, packing their pixels into one or more atlases and
+ * drawing each atlas as a single `InstancedMesh` — so a layer of many images costs a handful of
+ * draw calls, not one per image.
+ *
+ * Unlike a shape layer, an image layer can span **several meshes**: bin-packing splits the images
+ * across as many atlases as their pixels need, and each atlas gets its own mesh, batch, and
+ * texture (an {@link ImageAtlas}). A def whose source is too big for one atlas is cut into tiles
+ * that may land on different atlases, so one def can drive several instances — the atlas iterates
+ * its packed placements, not the defs.
+ *
+ * Packing has no incremental path, so a change to the **set** of images **repacks from scratch**: a
+ * fresh atlas set under fresh keys, remounting every mesh and instance. A **reorder** of the same
+ * set does not — packing is order-independent, so the atlases stand and each simply re-labels its
+ * instances' paint order in place. A per-def `update()` flows straight to the instance's slot, never
+ * through here.
+ *
+ * Paint order holds **within** an atlas (each mesh sorts its instances by the def's membership
+ * index) but is best-effort **across** atlases: separate meshes draw in atlas order, which packing
+ * decides, not paint order. Overlapping images in one layer that pack onto different atlases is the
+ * one case this does not order — rare for the markers, dots, and logos an image layer holds.
+ * @param props - The images to draw.
+ * @returns One {@link ImageAtlas} per packed atlas.
+ */
+export function Images(props) {
+    const { defs, maxAtlasSize } = props;
+    const gl = useThree((state) => state.gl);
+    const maxTextureSize = maxAtlasSize ?? gl.capabilities.maxTextureSize;
+    // Repack when the *set* of images changes, via the "adjust state on prop change" pattern. The
+    // comparison is by content, not identity: `useStagedChildren` rebuilds its snapshot on *every*
+    // `update(layer)` — including one that only flipped the layer's own `hidden` — so identity alone
+    // would repack for changes that touched no image at all. Order is excluded on purpose: packing
+    // reads only pixels, so a reorder produces the same atlases and needs no repack, only the
+    // paint-order relabel each atlas does below. Set equality is O(n) over a list already in cache,
+    // against a repack that redraws every canvas.
+    const [packed, setPacked] = useState(() => packImages(defs, maxTextureSize, 0));
+    if (!sameSet(packed.defs, defs)) {
+        setPacked((current) => packImages(defs, maxTextureSize, current.generation + 1));
+    }
+    return (_jsx(_Fragment, { children: packed.atlases.map((atlas) => (_jsx(ImageAtlas, { atlas: atlas, defs: defs }, atlasKey(atlas, packed.generation)))) }));
+}
+/**
+ * Draws one atlas as an `InstancedMesh`: the R3F-owned mesh with the atlas texture as its
+ * `TextureMaterial`, plus one {@link ImageInstance} per placement on the atlas. Its set of images is
+ * fixed for its lifetime — a repack remounts the whole component — so the batch and texture are
+ * built once from state and released together on unmount. Paint order is not fixed: a reorder keeps
+ * this atlas and re-labels its instances through the effect below.
+ *
+ * The uploaded texture is not fixed either: a resizable atlas registers with the scene's texture
+ * budget and re-derives a downscaled copy of its canvas whenever the shared resize factor moves (see
+ * {@link resizeTexture}). That is a texture re-upload, not a repack — the mesh, container,
+ * instances, and their normalized uv regions all stand, since uv is invariant to the canvas's pixel
+ * size.
+ * @param props - The atlas and the layer's images in paint order.
+ * @returns The mesh and one instance component per placement.
+ */
+function ImageAtlas(props) {
+    const { atlas, defs } = props;
+    const [texture] = useState(() => makeAtlasTexture(atlas.canvas));
+    const container = useContainer(() => new ImageContainer(atlas), defs);
+    const invalidate = useThree((state) => state.invalidate);
+    const budget = use(TextureBudgetContext);
+    const factor = useResizeFactor(budget, atlas);
+    const displayRef = useRef(undefined);
+    // Only the texture is ours to free — the mesh, its quad, and its material are all R3F's.
+    // StrictMode's simulated unmount disposes then remounts, but three's `dispose` only frees GPU
+    // resources — the state-retained texture re-uploads from its canvas on the next render — so the
+    // double is a harmless dev-only reupload, not a use-after-free.
+    useEffect(() => {
+        invalidate();
+        return () => texture.dispose();
+    }, [texture, invalidate]);
+    // Re-derive the uploaded pixels for the current resize factor. Runs on mount and every factor
+    // move; a fixed atlas reads `1` forever, so this settles once for it and never fires again.
+    useEffect(() => {
+        resizeTexture(texture, atlas.canvas, displayRef, factor);
+        invalidate();
+    }, [texture, atlas, factor, invalidate]);
+    // `args` is a frozen snapshot so R3F never rebuilds the mesh; the `ref` arrow (not
+    // `ref={container.bind}`) keeps the React Compiler from inferring `container` itself as a ref and
+    // rejecting its render reads.
+    // The quad and the material are children so R3F creates, attaches, and disposes both — the args
+    // pair are placeholders the constructor demands (see `ImageMeshArgs`). The material has to be per
+    // mesh: `InstancedMeshExt` wraps whatever it draws with in a closure over its own textures, and two
+    // instanced meshes on one material would both render against the first one's.
+    return (_jsxs(_Fragment, { children: [_jsxs(InstancedMesh, { args: container.args, ref: (mesh) => container.bind(mesh), sortObjects: true, customSort: container.customSort, perObjectFrustumCulled: true, children: [_jsx("planeGeometry", {}), _jsx(TextureMaterial, { map: texture, uvOffset: UV_OFFSET_UNIFORM })] }), atlas.images.map((packed) => (_jsx(ImageInstance, { def: packed.def, packed: packed, container: container }, `${defKey(packed.def)}:${packed.uv.u0}:${packed.uv.v0}`)))] }));
+}
+/**
+ * Whether two snapshots hold the same *set* of images, order aside — the question "does this need a
+ * repack". Order is excluded on purpose: packing reads only pixels, so a reorder produces the same
+ * atlases and needs only a paint-order relabel, not a repack. Array identity answers neither
+ * question, because the store hands out a fresh snapshot on every layer update.
+ * @param a - The packed set.
+ * @param b - The incoming set.
+ * @returns Whether they hold the same defs.
+ */
+function sameSet(a, b) {
+    if (a.length !== b.length)
+        return false;
+    const set = new Set(a);
+    return b.every((def) => set.has(def));
+}
+/**
+ * A stable React key for an atlas: the repack generation, so a repack remounts every atlas, plus
+ * its first placement's def, uv origin, and — for a split source — tile region, which together no
+ * other atlas in the same generation can repeat (a placement lands on exactly one atlas). Packing
+ * never returns an empty atlas, so the first placement always exists.
+ * @param atlas - The atlas to key.
+ * @param generation - The repack counter this atlas belongs to.
+ * @returns The key.
+ */
+function atlasKey(atlas, generation) {
+    const first = atlas.images[0];
+    // A def keys by identity and uv origin, but a source split into one-tile-per-atlas puts the same
+    // def at uv origin (0, 0) on every one of its atlases; the tile's source region is what tells
+    // those atlases apart. Absent for an unsplit image, whose uv origin already differs per atlas.
+    const region = first.source ? `:${first.source.x},${first.source.y}` : '';
+    return `${generation}:${defKey(first.def)}:${first.uv.u0}:${first.uv.v0}${region}`;
+}
+/**
+ * Packs a set of images into atlases. Paint order is not recorded here — it is a layer-wide property
+ * the atlases relabel from the current `defs` on every update, so a reorder never repacks.
+ * @param defs - The images to pack.
+ * @param maxDimension - Largest atlas edge, the GPU's max texture size.
+ * @param generation - The repack counter for this pack.
+ * @returns The pack.
+ */
+function packImages(defs, maxDimension, generation) {
+    return { defs, atlases: packAtlases(defs, maxDimension), generation };
+}
+/**
+ * Points an atlas texture at the pixels it should upload for the current resize factor: the full
+ * canvas at `factor >= 1`, or a downscaled copy of it below that.
+ *
+ * The copy lives in `displayRef`, created on first need and resized in place after — so a factor that
+ * later climbs back (a budget freed up) re-derives from the untouched full canvas, never upscaling
+ * pixels already thrown away. The full canvas is retained regardless (the atlas holds it), so this
+ * costs one extra canvas only while actually scaling. UVs are untouched throughout: they are
+ * normalized, so the same regions address the smaller canvas unchanged.
+ * @param texture - The atlas texture to re-point.
+ * @param full - The full-resolution atlas canvas, never mutated.
+ * @param displayRef - Holds the downscaled copy across factor changes.
+ * @param factor - The linear factor to scale by, in `(0, 1]`.
+ */
+function resizeTexture(texture, full, displayRef, factor) {
+    if (factor >= 1) {
+        // Point back at the full canvas; a copy from an earlier, smaller factor is left for GC.
+        if (texture.image !== full) {
+            texture.image = full;
+            texture.needsUpdate = true;
+        }
+        return;
+    }
+    const width = Math.max(1, Math.round(full.width * factor));
+    const height = Math.max(1, Math.round(full.height * factor));
+    const display = (displayRef.current ??= document.createElement('canvas'));
+    // Setting the size also clears the canvas, so the downscale draws onto a blank surface.
+    display.width = width;
+    display.height = height;
+    const context = display.getContext('2d');
+    // No 2d context is the same dead end as a blank atlas: fall back to the full canvas so the images
+    // still draw — over budget — rather than not at all.
+    if (!context) {
+        texture.image = full;
+        texture.needsUpdate = true;
+        return;
+    }
+    context.drawImage(full, 0, 0, width, height);
+    texture.image = display;
+    texture.needsUpdate = true;
+}
+/**
+ * Wraps an atlas canvas as a texture for `MeshBasicMaterial.map`.
+ *
+ * Mipmaps stay on: a floor plan is zoomed far out as readily as far in, and without them every
+ * image shimmers under minification. The cost is that neighbors can bleed through the deeper mip
+ * levels, where the packer's one-pixel gutter no longer separates them.
+ * @param canvas - The packed atlas canvas.
+ * @returns The texture.
+ */
+function makeAtlasTexture(canvas) {
+    const texture = new CanvasTexture(canvas);
+    // The atlas holds sRGB pixels; tagging the color space is what makes `MeshBasicMaterial` sample
+    // and display them without a gamma shift.
+    texture.colorSpace = SRGBColorSpace;
+    // Upload the canvas rows in their own order rather than three's default vertical flip, so v runs
+    // down the atlas — the same direction as the packer's uv regions and as the scene's y axis. Every
+    // axis in the chain then points the same way; flip at one end only and images come out upside
+    // down.
+    texture.flipY = false;
+    texture.generateMipmaps = true;
+    return texture;
+}

package/dist/objects/images/atlas-packer.d.ts

@@ -0,0 +1,128 @@
+import { type ImageDef, type ImageSource } from '../../types/defs';
+/** A canvas an atlas is drawn onto. `OffscreenCanvas` included so packing can move to a worker. */
+export type AtlasCanvas = HTMLCanvasElement | OffscreenCanvas;
+/**
+ * Creates the backing canvas for one atlas, sized to that atlas exactly.
+ * @param width - The atlas width in pixels.
+ * @param height - The atlas height in pixels.
+ * @returns The canvas to draw on.
+ */
+export type CreateAtlasCanvas = (width: number, height: number) => AtlasCanvas;
+/**
+ * A region of a source image, in **source pixels with a top-left origin** — the same axes as
+ * `ImageDef.bounds`, and literally the `sx, sy, sw, sh` the packer hands to `drawImage`. Kept in
+ * pixels rather than normalized so it cannot be mistaken for a {@link UvRect}, whose origin is the
+ * other corner.
+ */
+export interface SourceRect {
+    /** Distance from the source's left edge, in pixels. */
+    x: number;
+    /** Distance from the source's top edge, in pixels. */
+    y: number;
+    /** Region width in pixels. */
+    width: number;
+    /** Region height in pixels. */
+    height: number;
+}
+/**
+ * A region of an atlas, **normalized in the canvas's own axes: a top-left origin, v running down**.
+ *
+ * Consumed by a texture uploaded with `flipY = false`, which maps canvas row 0 to `v = 0`, so these
+ * numbers feed a uv transform directly with no vertical inversion. That is deliberate: the scene's
+ * y axis already points down (SVG coordinates, and the camera is placed to match), so a uv space
+ * that also runs down keeps every axis in the pipeline pointing the same way — invert at one end
+ * only and images come out upside down.
+ */
+export interface UvRect {
+    /** Left edge, `0` at the atlas's left. */
+    u0: number;
+    /** Top edge, `0` at the atlas's top. */
+    v0: number;
+    /** Right edge. */
+    u1: number;
+    /** Bottom edge. */
+    v1: number;
+}
+/** One image — or one tile of a split image — placed in an atlas. */
+export interface PackedImage {
+    /**
+     * The def these pixels belong to. Defs whose sources dedupe appear as separate entries sharing
+     * one region, so the list maps one-to-one onto the instances an atlas has to draw.
+     */
+    def: ImageDef;
+    /** Where the pixels sit in the atlas. */
+    uv: UvRect;
+    /**
+     * Which part of `def.source` this entry holds. Undefined when the source was small enough to
+     * pack whole, which is the common case; set only on the tiles of a split source, where a
+     * consumer needs it to work out the fraction of `def.bounds` this tile covers.
+     */
+    source?: SourceRect;
+}
+/** One packed atlas: a canvas of pixels, and what landed where on it. */
+export interface Atlas {
+    /** The canvas holding the packed pixels. Its `width`/`height` are the atlas's size. */
+    canvas: AtlasCanvas;
+    /** Every def placement on this atlas. */
+    images: PackedImage[];
+    /**
+     * Whether this atlas's pixels may be downscaled to fit a memory budget. Image and bitmap sources
+     * pack into resizable atlases; canvas sources into fixed ones. An atlas never mixes the two (they
+     * are packed as separate groups), so this one flag speaks for every placement on it — which is
+     * what lets a memory budget scale the whole canvas at once without dragging a canvas source down
+     * with the images. See {@link isResizableSource}.
+     */
+    resizable: boolean;
+}
+/** Options for {@link packAtlases}. */
+export interface AtlasPackerOptions {
+    /** Creates each atlas canvas. Defaults to a DOM canvas. */
+    createCanvas?: CreateAtlasCanvas;
+}
+/**
+ * Whether a source's pixels may be downscaled to fit a memory budget. `true` for decoded images and
+ * bitmaps, `false` for canvases — a canvas's pixels are the caller's, counted at full size but never
+ * compressed (see the scene's `memoryLimit`).
+ *
+ * Detected by the absence of `getContext`: `HTMLCanvasElement` and `OffscreenCanvas` both have it,
+ * `HTMLImageElement` and `ImageBitmap` do not. A property test rather than `instanceof`, because the
+ * SDK runs in WebViews where `OffscreenCanvas`/`ImageBitmap` may be missing as globals and an
+ * `instanceof` against an absent one throws.
+ * @param source - The source to classify.
+ * @returns Whether the source can be downscaled.
+ */
+export declare function isResizableSource(source: ImageSource): boolean;
+/**
+ * Packs image defs into atlas canvases and reports where every def's pixels landed.
+ *
+ * Sources are split by kind first — resizable (image/bitmap) from fixed (canvas) — and each kind is
+ * packed on its own, so no atlas ever mixes the two and a memory budget can scale a resizable atlas
+ * whole without touching a canvas's pixels. Within a kind, sources are deduped — two defs pointing
+ * at the same URL, or holding the same canvas object, are drawn once and share one region — and then
+ * offered to the packer whole. Anything too big for an atlas comes back parked in a natural-size bin
+ * of its own, which the packer flags; those are the only sources cut into tiles, and the tiles go
+ * back through the same packer. Letting the packer decide is what keeps the guarantee that no atlas
+ * exceeds `maxDimension` without measuring every image up front.
+ *
+ * Packing reads only the sources' pixel dimensions, never `bounds`, so a def that later moves or
+ * resizes keeps its region: the quad's matrix scales it, and nothing needs repacking. Membership
+ * changes do, though — this is a batch call with no incremental path.
+ * @param defs - The images to pack.
+ * @param maxDimension - Largest atlas edge in pixels, floored to a positive integer.
+ * @param options - Overrides for how atlas canvases are made.
+ * @returns One entry per atlas, in packing order — resizable atlases first, then fixed.
+ */
+export declare function packAtlases(defs: readonly ImageDef[], maxDimension: number, options?: AtlasPackerOptions): Atlas[];
+/**
+ * The pixel size of an image source.
+ *
+ * Duck-typed rather than `instanceof`: the SDK runs in WebViews where `OffscreenCanvas` and
+ * `ImageBitmap` may be missing as globals, and an `instanceof` against an absent global throws.
+ * @param source - The source to measure.
+ * @returns Its intrinsic size, `0 × 0` for an image element that has not decoded yet.
+ */
+export declare function imageSourceSize(source: ImageSource): {
+    width: number;
+    height: number;
+};
+//# sourceMappingURL=atlas-packer.d.ts.map