@expofp/renderer 3.2.5 → 3.27.0

package/dist/types/events.d.ts

@@ -0,0 +1,183 @@
+import { type PlanPoint } from '../space/Space';
+import { type LayerDef, type RenderableDef } from './defs';
+/**
+ * The def one of a layer's {@link PointerHandlers} is handed: a content layer's own child type, and —
+ * because a layer whose children are layers stands above every kind — any renderable at all for one
+ * of those. Never a {@link LayerDef} in practice: a hit resolves to the primitive under the pointer.
+ */
+export type SubtreeDef<T extends RenderableDef> = T extends LayerDef ? RenderableDef : T;
+/** A pointer event delivered to one of a layer's {@link PointerHandlers}. */
+export interface PointerEventData<T extends RenderableDef = RenderableDef> {
+    /**
+     * The def under the pointer — the nearest hit inside the subtree of the layer whose handler is
+     * running. A hit the renderer cannot trace back to a def is dropped rather than reported, so this
+     * is never absent.
+     */
+    def: SubtreeDef<T>;
+    /**
+     * Where the pointer struck {@link def}, in plan units — the ray's own intersection with the
+     * geometry, taken back into plan space, so `z` is the elevation it was drawn at and a click on the
+     * roof of a raised model reports the roof.
+     *
+     * The same kind of answer {@link PointerMissedEventData} carries, which searches the scene for
+     * itself. A caller that wants the floor coordinate under an elevated hit instead — "which square
+     * metre of the hall is this" rather than "what did I touch" — converts the canvas position through
+     * `ViewportAPI.canvasToPlan`, which crosses the plan plane on purpose.
+     *
+     * A fresh instance per event, so keeping a reference to it is safe.
+     */
+    point: PlanPoint;
+    /** Keeps the event from reaching the ancestors of the layer whose handler is running. */
+    stopPropagation(): void;
+    /** The DOM event this was dispatched from. */
+    nativeEvent: MouseEvent;
+}
+/**
+ * A click that reached no layer handler — empty background, or a def whose layer declares no
+ * handlers and so is not picked at all. Delivered to the renderer's `onPointerMissed`.
+ */
+export interface PointerMissedEventData {
+    /**
+     * Where the click landed, in plan units — the nearest geometry under the pointer, with the
+     * elevation it was struck at, exactly as {@link PointerEventData.point} reports for a hit.
+     *
+     * **Reaching no handler is not the same as striking nothing.** A layer declaring no pointer
+     * handlers is never raycast, so a click arrives here as readily from the middle of a wall as from
+     * open background. The scene is searched along the same ray to tell those apart, and only the case
+     * that really is empty — past the edge of every piece of geometry — falls back to where the ray
+     * crosses the plan plane (`z = 0`).
+     */
+    point: PlanPoint;
+    /** The DOM event this was dispatched from. */
+    nativeEvent: MouseEvent;
+}
+/**
+ * The pointer handlers a {@link LayerDef} may carry. Kept apart from {@link LayoutHandlers} so that
+ * `keyof PointerHandlers` is exactly the dispatchable names.
+ *
+ * **Declaring one is what makes a layer interactive.** A layer with none is never raycast; a layer
+ * with any is raycast together with its whole subtree; a layer that is off screen — hidden, or under
+ * something hidden — is not picked at all.
+ *
+ * **Events travel upward.** The nearest layer's handler runs first, then each ancestor that declares
+ * the same handler, until one calls {@link PointerEventData.stopPropagation}; `event.def` stays the
+ * def that was hit. Overlapping defs deliver one event apiece — even within one layer — in the order
+ * their slots were claimed (mount order), not paint order; `Pointer/Overlap` pins that.
+ *
+ * **Handlers return nothing.** One that mutates defs calls `update()` afterward, like any other code.
+ *
+ * **Handlers take no receiver.** They are read off the layer and called as plain functions —
+ * `this: void` makes reading `this` a compile error rather than an `undefined` at runtime — so a
+ * handler shared across layers keys off `event.def`. Declared as methods rather than function-typed
+ * fields on purpose: a method's parameters are checked bivariantly, which is what keeps a
+ * `LayerDef<ShapeDef>` assignable to a plain `RenderableDef`.
+ */
+export interface PointerHandlers<T extends RenderableDef = RenderableDef> {
+    /**
+     * Called for a click on a def in this layer — a press and release that stayed within a few pixels,
+     * so a pan gesture ending over a def does not click it.
+     * @param event - The def that was clicked, and where.
+     */
+    onClick?(this: void, event: PointerEventData<T>): void;
+    /**
+     * Called while the pointer is over a def in this layer, on every move it stays over one, including
+     * the move that first entered it.
+     * @param event - The def under the pointer, and where.
+     */
+    onPointerMove?(this: void, event: PointerEventData<T>): void;
+    /**
+     * Called when the pointer leaves the def it was over, naming that def — so a handler mirroring
+     * hover state clears it here.
+     * @param event - The def the pointer left, and where the pointer was.
+     */
+    onPointerOut?(this: void, event: PointerEventData<T>): void;
+}
+/** The pointer handlers by name, so dispatch can name one without repeating the list. */
+export type PointerHandlerName = keyof PointerHandlers;
+/** A def's re-layout handler, named so a caller can annotate one apart from the def it serves. */
+export type ScaleHandler = NonNullable<LayoutHandlers['onScale']>;
+/** A def's counter-rotation handler, named like {@link ScaleHandler}. */
+export type RollHandler = NonNullable<LayoutHandlers['onRoll']>;
+/**
+ * What the camera currently shows, as a layout rule sees it — every {@link LayoutHandlers} handler
+ * receives the same view, whichever axis's move invoked it, so a rule that turns a label can re-fit
+ * it at the size it is drawn at without asking anyone.
+ *
+ * **Valid during the call.** The registry reuses one instance across a sweep, so destructure or
+ * copy what you need rather than retaining the object.
+ */
+export interface LayoutView {
+    /**
+     * How much of the plan one device pixel spans, in plan units — the factor anything sized in
+     * pixels is laid out against, and the quantity the imperative renderer published as `ptScale`.
+     */
+    readonly pixelSize: number;
+    /**
+     * Which way the plan is turned, in **radians** clockwise from north — the same quantity, in the
+     * same unit, the imperative renderer's `navigation:roll` event carried, so ported rules keep the
+     * quarter-turn thresholds they were written against. (`CameraState.roll` reports the same angle
+     * in degrees, for people; rules get the unit their arithmetic wants.)
+     */
+    readonly roll: number;
+}
+/**
+ * The layout handlers a def may carry — camera-driven rules that re-derive a def's geometry, one
+ * per axis the camera moves on: `onScale` for the pixel size, `onRoll` for the turn. Both receive
+ * the same {@link LayoutView}.
+ *
+ * Where {@link PointerHandlers} hang off the layer that gets picked — picking is a query over a
+ * subtree — a layout handler hangs off the one def it lays out, a layer included (which is how a
+ * layer whose *membership* depends on the camera re-derives it), and never propagates: a def's
+ * geometry has exactly one owner.
+ *
+ * A handler takes no def parameter: it is typically a closure built where its def is built, closing
+ * over the def or the plan-lived object that owns it. **What such a closure captures is the one
+ * thing to watch.** Defs live for the plan's lifetime, so a handler must capture nothing
+ * shorter-lived than the def — an owner alive as long as the plan is safe, since the closure then
+ * retains nothing the def was not already keeping alive, while a build-time temporary (a parse
+ * buffer, a raw config) captured even incidentally would stay pinned in memory for as long as the
+ * def exists. Should defs ever stop being built by plan-lived owners, keep that property by moving
+ * per-def data onto the defs themselves and capturing only the def.
+ */
+export interface LayoutHandlers {
+    /**
+     * Lays the def this handler is declared on out for a new pixel size — the hook everything sized
+     * in pixels rather than plan units hangs off: label font steps, badge and marker rescaling, a
+     * bookmark's clamp.
+     *
+     * Called once when the def is first registered, and again whenever the pixel size moves — hidden
+     * defs included, since whether a def draws at all can be exactly what its rule decides (a booth's
+     * dot appears only once the plan is far enough out for its label to stop fitting).
+     *
+     * **Returns what changed, and the renderer writes it** by the cheapest route that is correct for
+     * each def: a layer is reconciled, anything else goes straight into its slot with no render — what
+     * makes it affordable for every label on a plan to re-lay out while the camera moves. Return
+     * nothing when nothing changed and the write — the expensive half — is skipped; the def still
+     * counts as laid out either way. Do not call `update()` here: returning *is* this handler's
+     * update.
+     *
+     * Called as a plain function with no receiver, like the pointer handlers.
+     * @param view - What the camera shows; multiply pixel-authored sizes by `view.pixelSize`.
+     * @returns The defs that changed and need writing, or nothing.
+     */
+    onScale?(this: void, view: LayoutView): readonly RenderableDef[] | void;
+    /**
+     * Lays the def out for a new camera roll — the hook everything that stays upright, or snaps to the
+     * nearest cardinal direction, hangs off: label and bookmark counter-rotation, a badge walking its
+     * anchor corner, a marker turning with the plan.
+     *
+     * Called once when the def is first registered — so a def added while the plan is turned is
+     * correct before its first paint — and again whenever the roll moves at all. There is no epsilon:
+     * the rules themselves step in quarter turns, so nearly every call returns nothing, exactly as the
+     * imperative renderer's `navigation:roll` handlers did.
+     *
+     * The same write contract as {@link onScale}: return what changed, return nothing when nothing
+     * did, and never call `update()` here. Called as a plain function with no receiver.
+     * @param view - What the camera shows — `view.roll` is the angle to lay out against, and
+     *   `view.pixelSize` rides along because a rule that turns a label re-fits it at the size it is
+     *   currently drawn at.
+     * @returns The defs that changed and need writing, or nothing.
+     */
+    onRoll?(this: void, view: LayoutView): readonly RenderableDef[] | void;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/types/events.js

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

package/dist/types/guards.d.ts

@@ -0,0 +1,14 @@
+import { type ImageDef, type LayerDef, type LineDef, type ModelDef, type RenderableDef, type RenderableDefCollection, type ShapeDef, type TextDef } from './defs';
+export declare function isShapeDef(def: RenderableDef): def is ShapeDef;
+export declare function isImageDef(def: RenderableDef): def is ImageDef;
+export declare function isTextDef(def: RenderableDef): def is TextDef;
+export declare function isLineDef(def: RenderableDef): def is LineDef;
+export declare function isModelDef(def: RenderableDef): def is ModelDef;
+export declare function isLayerDef(def: RenderableDef): def is LayerDef;
+export declare function isLayerDefs(defs: Readonly<RenderableDefCollection>): defs is readonly LayerDef[];
+export declare function isShapeDefs(defs: Readonly<RenderableDefCollection>): defs is readonly ShapeDef[];
+export declare function isImageDefs(defs: Readonly<RenderableDefCollection>): defs is readonly ImageDef[];
+export declare function isTextDefs(defs: Readonly<RenderableDefCollection>): defs is readonly TextDef[];
+export declare function isLineDefs(defs: Readonly<RenderableDefCollection>): defs is readonly LineDef[];
+export declare function isModelDefs(defs: Readonly<RenderableDefCollection>): defs is readonly ModelDef[];
+//# sourceMappingURL=guards.d.ts.map

package/dist/types/guards.js

@@ -0,0 +1,42 @@
+export function isShapeDef(def) {
+    return def.shape !== undefined;
+}
+export function isImageDef(def) {
+    return def.source !== undefined;
+}
+export function isTextDef(def) {
+    return def.lines !== undefined;
+}
+export function isLineDef(def) {
+    return def.points !== undefined;
+}
+export function isModelDef(def) {
+    return def.url !== undefined;
+}
+export function isLayerDef(def) {
+    return def.children !== undefined;
+}
+// The array guards below take the collection type, not `readonly RenderableDef[]`: the collection
+// is a union of single-kind arrays, so a first-element check is sound for the whole array. A plain
+// `RenderableDef[]` parameter would admit mixed arrays the check cannot speak for. The `Readonly`
+// wrapper widens, not narrows: mutable collections are assignable to readonly parameters (and
+// narrowing a mutable union member keeps it mutable), while the reverse would reject the readonly
+// snapshots from `useStagedChildren`.
+export function isLayerDefs(defs) {
+    return defs[0] !== undefined && isLayerDef(defs[0]);
+}
+export function isShapeDefs(defs) {
+    return defs[0] !== undefined && isShapeDef(defs[0]);
+}
+export function isImageDefs(defs) {
+    return defs[0] !== undefined && isImageDef(defs[0]);
+}
+export function isTextDefs(defs) {
+    return defs[0] !== undefined && isTextDef(defs[0]);
+}
+export function isLineDefs(defs) {
+    return defs[0] !== undefined && isLineDef(defs[0]);
+}
+export function isModelDefs(defs) {
+    return defs[0] !== undefined && isModelDef(defs[0]);
+}

package/dist/update/index.d.ts

@@ -0,0 +1,3 @@
+export { registerSlotWriter, syncNow, writeChanged } from './slot-writers';
+export { childrenOf, subscribeDef, update, versionOf } from './store';
+//# sourceMappingURL=index.d.ts.map

package/dist/update/index.js

@@ -0,0 +1,2 @@
+export { registerSlotWriter, syncNow, writeChanged } from './slot-writers';
+export { childrenOf, subscribeDef, update, versionOf } from './store';

package/dist/update/slot-writers.d.ts

@@ -0,0 +1,30 @@
+import { type RenderableDef } from '../types/defs';
+/**
+ * Registers a def's sync closure, paired with the frame request that shows what it writes.
+ *
+ * The two are registered together rather than left to each caller because a slot write nobody asked
+ * a frame for is invisible: the renderer runs a demand frameloop, so the write lands in GPU memory
+ * and waits for a frame that never comes. Pairing them here is what makes every write path — React's
+ * and the frame loop's — correct without remembering anything. The frame loop's writes ask for a
+ * frame they are already inside, which costs one more after the camera stops.
+ * @param def - The def the instance component renders.
+ * @param sync - Writes the def's current state into its slot.
+ * @param invalidate - Requests the frame that draws it.
+ * @returns An unregister function, which removes this writer and leaves the def's others alone.
+ */
+export declare function registerSlotWriter(def: RenderableDef, sync: () => void, invalidate: () => void): () => void;
+/**
+ * Runs every write registered for a def — each of its slots, and the frame that draws them. A no-op
+ * for defs that are not mounted.
+ * @param def - The def to re-sync.
+ */
+export declare function syncNow(def: RenderableDef): void;
+/**
+ * Writes the defs a layout handler reported changed, by the cheapest route that is correct for
+ * each: a layer means its membership moved, which only React can reconcile, while anything else is
+ * a field write that goes straight into the slot, with no render at all behind the frame that draws
+ * it. This is what a layout handler returning defs buys — see `LayoutHandlers.onScale`.
+ * @param defs - The defs the handler reported changed, or nothing when it changed nothing.
+ */
+export declare function writeChanged(defs: readonly RenderableDef[] | undefined): void;
+//# sourceMappingURL=slot-writers.d.ts.map

package/dist/update/slot-writers.js

@@ -0,0 +1,72 @@
+import { isLayerDef } from '../types/guards';
+import { update } from './store';
+/**
+ * The write closures mounted instance components register for their defs — the single write path
+ * from a def's fields into its GPU slots, and the frame that draws what they wrote.
+ *
+ * Two callers run them: the instance's own effect (after `update(def)`), and the camera re-layout
+ * frame loop — the latter mutating defs and re-syncing them without going through React at all.
+ * Sharing one closure is what keeps the two paths from disagreeing.
+ *
+ * A **set** per def, because one def can be drawn by more than one mesh: a model merged into a part
+ * per source material has an instance in each, and an image whose source is split into tiles has one
+ * per placement. Holding a single writer let the last instance to mount overwrite its siblings, so
+ * every later write reached exactly one of a def's slots — a two-part model faded half of itself.
+ */
+const slotWriters = new WeakMap();
+/**
+ * Registers a def's sync closure, paired with the frame request that shows what it writes.
+ *
+ * The two are registered together rather than left to each caller because a slot write nobody asked
+ * a frame for is invisible: the renderer runs a demand frameloop, so the write lands in GPU memory
+ * and waits for a frame that never comes. Pairing them here is what makes every write path — React's
+ * and the frame loop's — correct without remembering anything. The frame loop's writes ask for a
+ * frame they are already inside, which costs one more after the camera stops.
+ * @param def - The def the instance component renders.
+ * @param sync - Writes the def's current state into its slot.
+ * @param invalidate - Requests the frame that draws it.
+ * @returns An unregister function, which removes this writer and leaves the def's others alone.
+ */
+export function registerSlotWriter(def, sync, invalidate) {
+    /** Writes the def's slot and asks for the frame that shows it. */
+    function write() {
+        sync();
+        invalidate();
+    }
+    const writers = slotWriters.get(def) ?? new Set();
+    writers.add(write);
+    slotWriters.set(def, writers);
+    return () => {
+        writers.delete(write);
+    };
+}
+/**
+ * Runs every write registered for a def — each of its slots, and the frame that draws them. A no-op
+ * for defs that are not mounted.
+ * @param def - The def to re-sync.
+ */
+export function syncNow(def) {
+    const writers = slotWriters.get(def);
+    if (!writers)
+        return;
+    // Over a copy: a write can re-claim a slot, and a re-claim mounts and unmounts writers.
+    for (const write of [...writers])
+        write();
+}
+/**
+ * Writes the defs a layout handler reported changed, by the cheapest route that is correct for
+ * each: a layer means its membership moved, which only React can reconcile, while anything else is
+ * a field write that goes straight into the slot, with no render at all behind the frame that draws
+ * it. This is what a layout handler returning defs buys — see `LayoutHandlers.onScale`.
+ * @param defs - The defs the handler reported changed, or nothing when it changed nothing.
+ */
+export function writeChanged(defs) {
+    if (!defs)
+        return;
+    for (const def of defs) {
+        if (isLayerDef(def))
+            update(def);
+        else
+            syncNow(def);
+    }
+}

package/dist/update/store.d.ts

@@ -0,0 +1,41 @@
+import { type LayerDef, type RenderableDef, type RenderableDefCollection } from '../types/defs';
+/**
+ * Marks defs as changed after their fields, geometry, or `children` were mutated, so the renderer
+ * mirrors the mutation into GPU state.
+ *
+ * This is the renderer's only update signal. Mutate whatever you like — scalar fields, geometry in
+ * place, a layer's `children` array — then pass the defs you touched; for a membership change pass
+ * the parent layer, and for a reparent pass both parents. Calling it before the renderer mounts, or
+ * after it unmounts, is a safe no-op: defs are the source of truth and mounting performs a full
+ * sync. Calling it on an unchanged def is harmless.
+ * @param defs - Defs that changed.
+ */
+export declare function update(...defs: RenderableDef[]): void;
+/**
+ * Subscribes to a def's change notifications. Internal — components reach this through
+ * `useDefSync` and `useStagedChildren`.
+ * @param def - The def to watch.
+ * @param listener - Called after every {@link update} touching the def.
+ * @returns An unsubscribe function.
+ */
+export declare function subscribeDef(def: RenderableDef, listener: () => void): () => void;
+/**
+ * Reads a def's current version — the value `useSyncExternalStore` snapshots.
+ * @param def - The def to read.
+ * @returns The version, or `0` when nothing is subscribed.
+ */
+export declare function versionOf(def: RenderableDef): number;
+/**
+ * Reads a layer's children as a version-keyed snapshot. Internal — components reach this through
+ * `useStagedChildren`.
+ *
+ * The layer's `children` array is mutated in place, so its identity can never signal a membership
+ * change to memoization. The snapshot restores that signal at the store level: it is rebuilt as a
+ * fresh copy exactly when the layer's version has moved, and the cached copy is returned otherwise —
+ * the identity stability `useSyncExternalStore` requires between updates, and the identity change
+ * downstream memoization invalidates on.
+ * @param def - The layer whose children to snapshot.
+ * @returns The current snapshot; a new array iff the layer was updated since the last call.
+ */
+export declare function childrenOf<T extends RenderableDef>(def: LayerDef<T>): Readonly<RenderableDefCollection<T>>;
+//# sourceMappingURL=store.d.ts.map

package/dist/update/store.js

@@ -0,0 +1,98 @@
+/**
+ * Per-def subscription state, created on first subscribe and dropped when the last subscriber
+ * leaves. Keyed weakly by def identity: a def the renderer never mounted has no entry, which is
+ * exactly why {@link update} on it is a no-op rather than an error.
+ */
+const subscriptions = new WeakMap();
+/**
+ * Marks defs as changed after their fields, geometry, or `children` were mutated, so the renderer
+ * mirrors the mutation into GPU state.
+ *
+ * This is the renderer's only update signal. Mutate whatever you like — scalar fields, geometry in
+ * place, a layer's `children` array — then pass the defs you touched; for a membership change pass
+ * the parent layer, and for a reparent pass both parents. Calling it before the renderer mounts, or
+ * after it unmounts, is a safe no-op: defs are the source of truth and mounting performs a full
+ * sync. Calling it on an unchanged def is harmless.
+ * @param defs - Defs that changed.
+ */
+export function update(...defs) {
+    for (const def of defs)
+        notify(def);
+}
+/**
+ * Subscribes to a def's change notifications. Internal — components reach this through
+ * `useDefSync` and `useStagedChildren`.
+ * @param def - The def to watch.
+ * @param listener - Called after every {@link update} touching the def.
+ * @returns An unsubscribe function.
+ */
+export function subscribeDef(def, listener) {
+    const entry = entryFor(def);
+    entry.listeners.add(listener);
+    return () => {
+        const current = subscriptions.get(def);
+        if (!current)
+            return;
+        current.listeners.delete(listener);
+        // The entry outlives its listeners deliberately. `useSyncExternalStore` re-subscribes whenever
+        // its subscribe closure changes identity, which happens on every render unless the closure is
+        // memoized; dropping the entry on the last unsubscribe would reset the version to 0 mid-render,
+        // costing a spurious re-render and re-sync and breaking the monotonicity the `childrenOf` cache
+        // relies on to signal in-place mutation. Retaining it costs nothing: the map is weak, so
+        // an entry is collected with its def.
+    };
+}
+/**
+ * Reads a def's current version — the value `useSyncExternalStore` snapshots.
+ * @param def - The def to read.
+ * @returns The version, or `0` when nothing is subscribed.
+ */
+export function versionOf(def) {
+    return subscriptions.get(def)?.version ?? 0;
+}
+/**
+ * Reads a layer's children as a version-keyed snapshot. Internal — components reach this through
+ * `useStagedChildren`.
+ *
+ * The layer's `children` array is mutated in place, so its identity can never signal a membership
+ * change to memoization. The snapshot restores that signal at the store level: it is rebuilt as a
+ * fresh copy exactly when the layer's version has moved, and the cached copy is returned otherwise —
+ * the identity stability `useSyncExternalStore` requires between updates, and the identity change
+ * downstream memoization invalidates on.
+ * @param def - The layer whose children to snapshot.
+ * @returns The current snapshot; a new array iff the layer was updated since the last call.
+ */
+export function childrenOf(def) {
+    const entry = entryFor(def);
+    if (entry.childrenSnapshot?.version !== entry.version) {
+        entry.childrenSnapshot = { version: entry.version, snapshot: [...def.children] };
+    }
+    // A layer's children are homogeneous (`RenderableDefCollection<T>`), so the erased cache entry is
+    // safely re-narrowed to the layer's own child type.
+    return entry.childrenSnapshot.snapshot;
+}
+/**
+ * Returns a def's subscription entry, creating it on first contact.
+ * @param def - The def to look up.
+ * @returns The entry.
+ */
+function entryFor(def) {
+    let entry = subscriptions.get(def);
+    if (!entry) {
+        entry = { version: 0, listeners: new Set() };
+        subscriptions.set(def, entry);
+    }
+    return entry;
+}
+/**
+ * Bumps one def's version and notifies its listeners.
+ * @param def - The def that changed.
+ */
+function notify(def) {
+    const entry = subscriptions.get(def);
+    if (!entry)
+        return;
+    entry.version++;
+    for (const listener of entry.listeners)
+        listener();
+}

package/dist/utils/arrays.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Whether two arrays hold the same values in the same positions, compared by identity.
+ *
+ * The batched classes keep an applied order and are handed a desired one on every membership
+ * change; this is what lets an unchanged order skip the work of applying it — which matters most
+ * where applying it is expensive (repacking glyphs or endpoints) and the caller cannot know whether
+ * anything moved.
+ * @param a - The first sequence.
+ * @param b - The second sequence.
+ * @returns Whether they match.
+ */
+export declare function sameSequence<T>(a: readonly T[], b: readonly T[]): boolean;
+//# sourceMappingURL=arrays.d.ts.map

package/dist/utils/arrays.js

@@ -0,0 +1,20 @@
+/**
+ * Whether two arrays hold the same values in the same positions, compared by identity.
+ *
+ * The batched classes keep an applied order and are handed a desired one on every membership
+ * change; this is what lets an unchanged order skip the work of applying it — which matters most
+ * where applying it is expensive (repacking glyphs or endpoints) and the caller cannot know whether
+ * anything moved.
+ * @param a - The first sequence.
+ * @param b - The second sequence.
+ * @returns Whether they match.
+ */
+export function sameSequence(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}

package/dist/utils/colors.d.ts

@@ -0,0 +1,19 @@
+import { type RgbaColor } from 'colord';
+import { type ColorInput } from '../types/defs';
+/**
+ * Normalizes a {@link ColorInput} into an rgba color object.
+ * @param colorInput color as a css color string or a numeric 0xRRGGBB value
+ * @returns rgba color (r/g/b 0-255, a 0-1), or undefined if the input is not a valid color
+ */
+export declare function normalizeColor(colorInput: ColorInput): RgbaColor | undefined;
+/**
+ * Whether a color carries an alpha below 1, and so belongs in a translucent batch.
+ *
+ * A color that does not parse counts as **opaque**: `ShapeInstance` reports it and leaves the slot's
+ * tint alone, so moving a shape into a later render pass on the strength of a value the renderer
+ * could not read would compound one fault with another.
+ * @param colorInput color as a css color string or a numeric 0xRRGGBB value
+ * @returns true when the color is translucent
+ */
+export declare function isTranslucentColor(colorInput: ColorInput): boolean;
+//# sourceMappingURL=colors.d.ts.map

package/dist/utils/colors.js

@@ -0,0 +1,27 @@
+import { colord, extend } from 'colord';
+import namesPlugin from 'colord/plugins/names';
+extend([namesPlugin]);
+/**
+ * Normalizes a {@link ColorInput} into an rgba color object.
+ * @param colorInput color as a css color string or a numeric 0xRRGGBB value
+ * @returns rgba color (r/g/b 0-255, a 0-1), or undefined if the input is not a valid color
+ */
+export function normalizeColor(colorInput) {
+    const colorString = typeof colorInput === 'string' ? colorInput : `#${colorInput.toString(16).padStart(6, '0')}`;
+    const color = colord(colorString);
+    if (!color.isValid())
+        return undefined;
+    return color.toRgb();
+}
+/**
+ * Whether a color carries an alpha below 1, and so belongs in a translucent batch.
+ *
+ * A color that does not parse counts as **opaque**: `ShapeInstance` reports it and leaves the slot's
+ * tint alone, so moving a shape into a later render pass on the strength of a value the renderer
+ * could not read would compound one fault with another.
+ * @param colorInput color as a css color string or a numeric 0xRRGGBB value
+ * @returns true when the color is translucent
+ */
+export function isTranslucentColor(colorInput) {
+    return (normalizeColor(colorInput)?.a ?? 1) < 1;
+}

package/dist/utils/logging.d.ts

@@ -0,0 +1,26 @@
+import { type Debugger } from 'debug';
+import { type SceneDef } from '../types/defs';
+/** Logger interface */
+export interface Logger {
+    /** Debug level logger */
+    debug: Debugger;
+    /** Info level logger */
+    info: Debugger;
+    /** Warn level logger */
+    warn: Debugger;
+    /** Error level logger */
+    error: Debugger;
+}
+/**
+ * Creates a logger with the given namespace.
+ * @param namespace - The namespace to use for the logger.
+ * @returns A logger with the given namespace.
+ */
+export declare function createLogger(namespace: string): Logger;
+/**
+ * Prints the layer tree of the given scene to the console.
+ * @param scene - Scene tree to print
+ * @param logger - The logger to use to print the tree.
+ */
+export declare function printScene(scene: SceneDef, logger: Debugger): void;
+//# sourceMappingURL=logging.d.ts.map

package/dist/utils/logging.js

@@ -0,0 +1,47 @@
+/* eslint-disable no-console */
+import createLog from 'debug';
+import { isLayerDefs } from '../types/guards';
+const rootNamespace = 'efp:renderer';
+/**
+ * Creates a logger with the given namespace.
+ * @param namespace - The namespace to use for the logger.
+ * @returns A logger with the given namespace.
+ */
+export function createLogger(namespace) {
+    const fullNamespace = namespace ? `${rootNamespace}:${namespace}` : rootNamespace;
+    const info = createLog(fullNamespace);
+    info.log = console.info.bind(console);
+    const debug = info.extend('debug');
+    debug.log = console.debug.bind(console);
+    const warn = info.extend('warn');
+    warn.log = console.warn.bind(console);
+    const error = info.extend('error');
+    error.log = console.error.bind(console);
+    return {
+        debug,
+        info,
+        warn,
+        error,
+    };
+}
+/**
+ * Prints the layer tree of the given scene to the console.
+ * @param scene - Scene tree to print
+ * @param logger - The logger to use to print the tree.
+ */
+export function printScene(scene, logger) {
+    function printLayer(def) {
+        const fullName = def.name;
+        if (isLayerDefs(def.children)) {
+            console.groupCollapsed(fullName);
+            def.children.forEach((c) => printLayer(c));
+            console.groupEnd();
+        }
+        else {
+            logger(fullName);
+        }
+    }
+    if (!logger.enabled)
+        return;
+    printLayer(scene.rootLayer);
+}