@weasel-js/core 1.12.0 → 1.13.0

package/dist/{types-CniVctmk.d.ts → types-BEdRIhNc.d.ts}

@@ -1,9 +1,10 @@
 import * as _weasel_js_history from '@weasel-js/history';
 import { Op, SerializedHistory, History } from '@weasel-js/history';
-import { P as ParallaxOpts, C as ContainerBounds, L as LayoutStrategy } from './types-7puAuVD2.js';
+import { P as ParallaxOpts, C as ContainerBounds, L as LayoutStrategy } from './types-49uYJN3j.js';
 import { UnitScope } from '@weasel-js/quantity';
 import { NodeId } from '@weasel-js/routing';
 import { Path, PoseLinear, Affine } from '@weasel-js/geom';
+import { PaintedFill, PaintedStroke, Inherit } from '@weasel-js/paint';
 
 /**
  * Scene edit passes: functions that hear what a live edit did, once its own
@@ -60,10 +61,10 @@ interface SceneBatchOptions {
 }
 
 /** The form a scene's undo entries are recorded in. A serialized history
- *  carries it, and one carrying another is not restored. Form 2 holds the
- *  scene's own ops for every edit; before it, an `applyBatch` entry held the
- *  ops it was given. */
-declare const SCENE_HISTORY_FORM = 2;
+ *  carries it, and one carrying another is not restored. Form 3 names
+ *  nodes `mark` and `group`; form 2 held the scene's own ops for every edit,
+ *  and before it an `applyBatch` entry held the ops it was given. */
+declare const SCENE_HISTORY_FORM = 3;
 /** What `Scene.serializeHistory` answers with. */
 interface SerializedSceneHistory extends SerializedHistory {
     form: typeof SCENE_HISTORY_FORM;
@@ -253,11 +254,11 @@ interface ScenePoseReports<TPose, TNode = unknown> {
  * about a node without saying it about the document.
  *
  * Not document content: never recorded in history, never in `toJSON`, and
- * writing one does not bump `Scene.getVersion()`. Hoist one entry per node and
+ * writing one does not bump `Scene.getVersion()`. A writer hoists one entry per node and
  * mutate it in place on a frame loop; `PoseOverrides.commit()` is what makes a
  * mutation visible.
  */
-interface PoseOverride<TPose> {
+interface PoseOverride<TPose, TData = unknown> {
     /** Replaces the node's document pose everywhere the render and hit-test
      *  paths read one, including the clip a container derives from its pose, and
      *  winning over a `derivePose`. Resolved by `effectivePose` — reading
@@ -269,9 +270,19 @@ interface PoseOverride<TPose> {
     /** Replaces the geometry the node paints and is picked by: the path in its data, or the one
      *  it derives. It is in the frame a painter draws in, so give `pose` beside it, as the
      *  path's bounds with no rotation, or the pose's turn is applied to the path again and the
-     *  selection chrome stays on the old box. A skinned rig is the writer. */
+     *  selection chrome stays on the old box. A pose laid over it by another writer carries the
+     *  path from that box to its own; a path given with no pose is drawn where it is. A skinned
+     *  rig is the writer. */
     path?: Path;
+    /** The data the node is shown with, from the data it stores — so a recorded write made while it is
+     *  installed shows through. Painting, picking, drawn bounds and the effective reading of every
+     *  derivation read it through `nodeAsShown`; the document never sees it. Replace the function to
+     *  change what it answers: the shown data is kept per stored data and function. A text edit's
+     *  drafts and a gesture's `previewData` are the writers. */
+    data?(stored: TData): TData;
 }
+/** What a writer publishing whole frames says about one node: see {@link PoseHold.show}. */
+type ShownOverride<TPose, TData = unknown> = Pick<PoseOverride<TPose, TData>, 'pose' | 'data'>;
 /**
  * The scene's ephemeral per-node overrides — see {@link PoseOverride}.
  *
@@ -280,23 +291,44 @@ interface PoseOverride<TPose> {
  * the painter memo keys on pose *reference*, so a mutation without a commit
  * paints the previous frame with no error.
  *
+ * Several writers can override one node: each entry `set` is a ply over the
+ * ones set before it. A field shows what the topmost ply giving it says —
+ * `alpha` multiplies through every ply instead, and `data` runs each ply's
+ * function on what the plies under it show — and releasing a ply shows what
+ * lies under it. A ply's `path` is drawn in the box of the `pose` it gives
+ * beside it, so a pose from a ply above carries the path along.
+ *
+ * A full `clear(id)` keeps each ply's place: a writer that sets its entry again
+ * goes back where it stood, whatever order the writers come back in. A writer
+ * checks `has(id, entry)` each frame and sets its entry again when it is gone.
+ * A hand-written table honors `entry` on `has` and `clear` too: a writer
+ * releasing its own ply must not clear another's.
+ *
  * To promote a frame to document state (dropping a drag, baking an animation),
  * write it once through `Scene.setPose` and `clear` the override.
  */
-interface PoseOverrides<TPose> {
-    /** Store `entry` for `id` **by reference**; the caller keeps mutating it. */
-    set(id: NodeId, entry: PoseOverride<TPose>): void;
-    /** The entry `set` stored, by reference — what a writer checks to know
-     *  whether its own entry is still installed. Painting reads `read`. */
-    get(id: NodeId): PoseOverride<TPose> | undefined;
-    /** What the node is drawn and picked with: every source of overrides for
-     *  it folded into one, as of the last write or `commit()`. `undefined` for
-     *  a node nothing overrides. The object is reused per node. */
-    read(id: NodeId): PoseOverride<TPose> | undefined;
-    has(id: NodeId): boolean;
+interface PoseOverrides<TPose, TData = unknown> {
+    /** Store `entry` for `id` **by reference**, as the node's top ply, or where it
+     *  stood when a full `clear` took it off; the caller keeps mutating it. An
+     *  entry already installed moves to the top. */
+    set(id: NodeId, entry: PoseOverride<TPose, TData>): void;
+    /** The node's top ply, by reference. Painting reads `read`. */
+    get(id: NodeId): PoseOverride<TPose, TData> | undefined;
+    /** What the node is drawn and picked with: every ply for it folded into
+     *  one, as of the last write or `commit()`. `undefined` for a node nothing
+     *  overrides. The object is reused per node. */
+    read(id: NodeId): PoseOverride<TPose, TData> | undefined;
+    /** Whether anything overrides the node; given `entry`, whether that entry is
+     *  one of its plies — what a writer checks to know whether its own is
+     *  still installed. */
+    has(id: NodeId, entry?: PoseOverride<TPose, TData>): boolean;
     /** The overridden ids, as a snapshot array. */
     ids(): readonly NodeId[];
-    clear(id: NodeId): void;
+    /** Drop every ply of the node, each keeping its place for its writer's next
+     *  `set`; given `entry`, only that one, forgetting its place, and nothing
+     *  else when it is not installed. */
+    clear(id: NodeId, entry?: PoseOverride<TPose, TData>): void;
+    /** {@link PoseOverrides.clear} of every node. */
     clearAll(): void;
     /** Publish this frame's in-place mutations: invalidate the painter memo for
      *  every overridden node, then notify subscribers. */
@@ -308,7 +340,7 @@ interface PoseOverrides<TPose> {
     getGeneration(): number;
     /** A claim on some nodes' poses for a writer that publishes a whole frame
      *  at a time: a gesture's preview, a layout run. Each call is a new claim. */
-    hold(): PoseHold<TPose>;
+    hold(): PoseHold<TPose, TData>;
 }
 /**
  * One writer's claim on some nodes' pose overrides, from
@@ -316,18 +348,24 @@ interface PoseOverrides<TPose> {
  *
  * A hold knows which entries are its own, so several writers share the table
  * without clearing each other: a drag and a layout run each publish their
- * frame, and each sees the other's nodes as pinned.
+ * frame, and each sees the other's nodes as pinned. Each id it holds is one
+ * ply of that node's overrides, installed with the hold's first frame
+ * naming it.
  */
-interface PoseHold<TPose> {
-    /** Publish this frame's poses. It is the whole picture, not a delta: an id
-     *  the frame leaves out is released. Subscribers are notified once. */
+interface PoseHold<TPose, TData = unknown> {
+    /** Publish this frame's poses. It is the whole picture of this hold's
+     *  fields, not a delta: an id the frame leaves out is released, and a field
+     *  it leaves out shows what the plies under it say. Subscribers are
+     *  notified once. */
     set(poses: Iterable<readonly [NodeId, TPose]>): void;
-    /** The poses other writers are publishing, by id. */
+    /** {@link PoseHold.set} for a frame that shows data as well as poses. */
+    show(frame: Iterable<readonly [NodeId, ShownOverride<TPose, TData>]>): void;
+    /** The poses other writers are publishing, by id: each node's topmost pose
+     *  that is not this hold's. */
     others(): ReadonlyMap<NodeId, TPose>;
-    /** Release every id still held. An id whose entry another writer has since
-     *  replaced is left alone: that writer owns it now. When the frame is being
-     *  committed to the document, call this after the write lands, or the scene
-     *  answers with the old pose in between. */
+    /** Release every id still held, revealing whatever other writers lay under
+     *  it. When the frame is being committed to the document, call this after
+     *  the write lands, or the scene answers with the old pose in between. */
     drop(): void;
 }
 
@@ -356,7 +394,7 @@ interface SerializedLayer<TLayer extends string> extends SystemLayerSpec<TLayer>
  *  (e.g., `clipFromPose`) appear as string keys (`clipFromPoseKey`) and
  *  are resolved through `SceneRegistry` at load time. */
 interface SerializedScene<TData, TLayer extends string, TPose> {
-    version: 1;
+    version: 2;
     /** The whole layer stack, system and user alike — the name predates user
      *  layers and is kept so existing snapshots still parse. */
     systemLayers: readonly SerializedLayer<TLayer>[];
@@ -368,7 +406,7 @@ interface SerializedScene<TData, TLayer extends string, TPose> {
  *  with function fields replaced by registry keys. */
 interface SerializedNode<TData, TLayer extends string, TPose> {
     id: string;
-    kind: 'leaf' | 'container';
+    kind: 'mark' | 'group';
     layer: TLayer;
     pose: TPose;
     data: TData;
@@ -395,8 +433,19 @@ interface SerializedNode<TData, TLayer extends string, TPose> {
     derivePoseKey?: string;
     /** Registry key for the container's layout strategy. Omitted when it has none. */
     layoutKey?: string;
-    /** Mirrors `ContainerNode.units`. Omitted when the container declares none. */
+    /** Mirrors `SceneNode.units`. Omitted when the node declares none. */
     units?: UnitScope;
+    /** Mirrors `SceneNode.clip`. Omitted when the node declares none. */
+    clip?: NodeClip;
+}
+/** A node as version 1 saves wrote it: the kinds were `leaf` and `container`. */
+interface SerializedNodeV1<TData, TLayer extends string, TPose> extends Omit<SerializedNode<TData, TLayer, TPose>, 'kind'> {
+    kind: 'leaf' | 'container';
+}
+/** A version 1 save, still read and never written. */
+interface SerializedSceneV1<TData, TLayer extends string, TPose> extends Omit<SerializedScene<TData, TLayer, TPose>, 'version' | 'nodes'> {
+    version: 1;
+    nodes: readonly SerializedNodeV1<TData, TLayer, TPose>[];
 }
 
 /**
@@ -418,6 +467,91 @@ interface SceneDocValues {
 /** A snapshot's document values. */
 type SerializedDoc = Readonly<Record<string, unknown>>;
 
+/**
+ * What a node declares for its children — the unit scope they are shown in and
+ * the clip they are drawn in: the kit ops that write each, and the scene
+ * methods that record them.
+ */
+
+/** The scene methods that write a node's declared `units` and `clip`, each one undo step. */
+interface SceneDeclaredFieldSetters {
+    /** Declare the unit scope of container `id`, or clear it with `null`. */
+    setUnits(id: NodeId, units: UnitScope | null): void;
+    /** Declare the clip `id` draws its children in (see `SceneNode.clip`), or clear it with `null`. */
+    setClip(id: NodeId, clip: NodeClip | null): void;
+}
+
+/**
+ * Decides what one edit's changes to containers do to their children.
+ * `arrivals` maps each container to the ids that joined it — by an `add`
+ * under it or a `move` into it, whatever op or call made them — in the order
+ * they arrived. `changed` names every container whose child set or order
+ * changed, whose pose changed size, or one of whose children was posed,
+ * arrivals included. Both are read once the edit's other mutations have landed.
+ *
+ * Return the poses to write, in each node's stored frame; they become part of
+ * the same edit, and so of the same undo step. An empty map writes nothing.
+ * Return `null` to refuse: the whole edit is reverted (see
+ * `SceneArrivalRefused`).
+ *
+ * Runs only for live edits. Undo, redo and a restored history replay the
+ * arrangement that was decided the first time. With none installed, a scene
+ * holding declared layouts (`GroupNode.layout`) runs its own.
+ */
+type SceneArrivalHandler<TPose> = (arrivals: ReadonlyMap<NodeId, readonly NodeId[]>, changed: ReadonlySet<NodeId>, 
+/** The nodes that left each container in the edit, by the container they
+ *  left — removed, or moved out. */
+departures: ReadonlyMap<NodeId, readonly NodeId[]>) => ReadonlyMap<NodeId, TPose> | null;
+
+/** A custom scene mutation registered with `Scene.registerOp`: how to apply
+ *  it and how to undo it. The pair is what makes it participate in history. */
+interface RegisteredOp<P> {
+    apply: (payload: P) => void;
+    revert: (payload: P) => void;
+    /** Opts this kind into coalescing under `UseSceneOptions.coalesceWindowMs`:
+     *  two entries of this kind that return the same key inside the window
+     *  merge, and undoing the merged entry calls `revert` with the first
+     *  payload only. Declare it only when `revert` restores an absolute state
+     *  (a stored "from" value), never for a relative payload such as a delta.
+     *  Omitted, or returning `undefined`, the op is always its own entry. */
+    coalesceKey?: (payload: P) => string | undefined;
+}
+
+/**
+ * A scene to and from its JSON snapshot: the walk that writes one, and the
+ * two readers that turn one back into layer records and node specs.
+ */
+
+/** Decides what a version 1 `container` becomes; `leaf` is always a mark. */
+type V1Classifier<TData, TLayer extends string, TPose> = (node: SerializedNodeV1<TData, TLayer, TPose>) => 'mark' | 'group';
+/** Options for {@link specsFromSerialized}. */
+interface SpecsFromSerializedOptions<TData, TLayer extends string, TPose> {
+    /** What a version 1 `container` loads as; see {@link V1Classifier}. */
+    classifyV1?: V1Classifier<TData, TLayer, TPose>;
+    /** `'skip'` loads a node whose registry key is unknown without that
+     *  function, for a save that outlived the code that registered it.
+     *  Default `'throw'`. */
+    unknownKeys?: 'throw' | 'skip';
+    /** Hears each key `unknownKeys: 'skip'` leaves out, as it is left out. */
+    onSkip?: (skipped: SkippedKey) => void;
+}
+/** A registry key a load left out: the node, the function field it named,
+ *  and the key. */
+interface SkippedKey {
+    id: NodeId;
+    field: keyof SceneRegistry<unknown>;
+    key: string;
+}
+/** Map a `SerializedScene` to construction specs. Shared by `sceneFromJSON`
+ *  (new instance) and `Scene.loadState` (in-place). Validates version and
+ *  resolves every `NODE_FN_FIELDS` key → function via the registry;
+ *  throws on an unsupported version, and on an unknown registry key unless
+ *  `opts.unknownKeys` is `'skip'`. */
+declare function specsFromSerialized<TData, TLayer extends string, TPose>(json: SerializedScene<TData, TLayer, TPose> | SerializedSceneV1<TData, TLayer, TPose>, registry: SceneRegistry<TPose, TData, TLayer>, opts?: SpecsFromSerializedOptions<TData, TLayer, TPose>): AddNodeSpec<TData, TLayer, TPose>[];
+/** The kind a saved node loads as: its own on version 2; on version 1 a `leaf` is a
+ *  mark and a `container` goes to `classify`, or is a group without one. */
+declare function nodeKindOf<TData, TLayer extends string, TPose>(version: 1 | 2, n: SerializedNode<TData, TLayer, TPose> | SerializedNodeV1<TData, TLayer, TPose>, classify?: V1Classifier<TData, TLayer, TPose>): 'mark' | 'group';
+
 /**
  * Axis-aligned rectangle pose with optional rotation. Rotation is in
  * radians, pivoted on the unrotated AABB center; absent === 0.
@@ -434,6 +568,61 @@ interface RectPose {
     transform?: PoseLinear;
 }
 
+/**
+ * What a node's `'inherit'` fill and stroke resolve to: its nearest enclosing
+ * container's, `null` for none. A field the node does not inherit is `null`
+ * here whatever its containers hold.
+ */
+interface InheritedPaint {
+    readonly fill: PaintedFill | null;
+    readonly stroke: PaintedStroke | null;
+}
+/** Whether `node`'s fill or stroke is {@link INHERIT}, so painting it needs
+ *  its containers' paint. */
+declare function inheritsPaint(node: {
+    data?: unknown;
+}): boolean;
+/**
+ * {@link InheritedPaint} for `node`, given its ancestors innermost first. Any
+ * ancestor is a source, mark or group; one whose own field is `'inherit'`
+ * passes the question on to the next, and running out of ancestors is none.
+ *
+ * Hands back the object it returned last time for `node` while both values
+ * are the same references, so a memo can key on it.
+ */
+declare function inheritedPaintOf(node: {
+    data?: unknown;
+}, ancestors: Iterable<{
+    kind?: string;
+    data?: unknown;
+}>): InheritedPaint;
+/** What `node`'s `'inherit'` fields take from its containers in `scene`, or
+ *  `undefined` for a node that inherits nothing. */
+declare function inheritedPaintIn<TNode extends {
+    data?: unknown;
+    parent?: string | null;
+}>(scene: {
+    get(id: never): TNode | undefined;
+}, node: TNode): InheritedPaint | undefined;
+/** The fields {@link withInheritedPaint} resolves. */
+type ResolvedPaintFields<T> = Omit<T, 'fill' | 'stroke'> & {
+    fill?: Exclude<T extends {
+        fill?: infer F;
+    } ? F : never, Inherit>;
+    stroke?: Exclude<T extends {
+        stroke?: infer S;
+    } ? S : never, Inherit>;
+};
+/**
+ * `data` with an `'inherit'` fill or stroke replaced by what `inherited` says
+ * it resolves to, for a reader that wants the paint a node shows rather than
+ * the one it declares. Hands `data` back as is when nothing inherits.
+ */
+declare function withInheritedPaint<T extends {
+    fill?: unknown;
+    stroke?: unknown;
+}>(data: T, inherited: InheritedPaint | undefined): ResolvedPaintFields<T>;
+
 /**
  * One dependency, as a derivation reads it: the node itself and the pose it is
  * painted at.
@@ -453,6 +642,10 @@ interface DerivedDep<TPose, TData = unknown, TLayer extends string = string> {
      *  it to place something *along* a dependency: a label on a routed edge.
      *  Resolved on first read and memoized on the dependency. */
     readonly path: Path | null;
+    /** What its `'inherit'` fill and stroke take from its containers, or
+     *  `undefined` when it inherits nothing. A dependency built by hand rather
+     *  than by the scene may leave it out, and then inherits nothing. */
+    readonly inherited?: InheritedPaint;
 }
 /** `F` with its parameters checked bivariantly, as a method's are, so that a
  *  `Scene<D, L, MyPose>` is a `Scene<unknown, string, unknown>`. A callback for
@@ -466,18 +659,20 @@ type DerivePathFn<TPose, TData = unknown, TLayer extends string = string> = Biva
 /** Computes a node's pose from its dependencies: the type of a node's
  *  `derivePose` and of each entry in `SceneRegistry.derivePose`. */
 type DerivePoseFn<TPose, TData = unknown, TLayer extends string = string> = Bivariant<(node: Node<TData, TLayer, TPose>, deps: readonly (DerivedDep<TPose, TData, TLayer> | undefined)[]) => TPose | null>;
-/** A container's clip, from its pose: the type of `ContainerNode.clipFromPose`
+/** A container's clip, from its pose: the type of `clipFromPose`
  *  and of each entry in `SceneRegistry.clipFromPose`. */
 type ClipFromPoseFn<TPose> = Bivariant<(pose: TPose) => Path | null>;
 /** The extra times a container draws its children: the type of
- *  `ContainerNode.copiesFromPose` and of each entry in
+ *  `copiesFromPose` and of each entry in
  *  `SceneRegistry.copiesFromPose`. Each affine is in world coordinates and
  *  carries the children, as drawn, to one copy. */
-type CopiesFromPoseFn<TPose, TData = unknown, TLayer extends string = string> = Bivariant<(pose: TPose, node: ContainerNode<TData, TLayer, TPose>) => readonly Affine[] | null>;
+type CopiesFromPoseFn<TPose, TData = unknown, TLayer extends string = string> = Bivariant<(pose: TPose, node: Node<TData, TLayer, TPose>) => readonly Affine[] | null>;
 
 /** Brand a string as a NodeId. */
 declare const asNodeId: (s: string) => NodeId;
 
+/** A clip a node declares by name rather than by function: see `SceneNode.clip`. */
+type NodeClip = 'outline';
 interface NodeBase<TData, TLayer extends string, TPose> {
     id: NodeId;
     layer: TLayer;
@@ -533,21 +728,16 @@ interface NodeBase<TData, TLayer extends string, TPose> {
      *  the node falls back to its authored `pose`. `setPose` on a derived node
      *  still writes that authored pose; it is simply not what anything reads. */
     derivePose?: DerivePoseFn<TPose, TData, TLayer>;
-}
-/** A node with no children — a shape, a label, an image. */
-interface LeafNode<TData, TLayer extends string, TPose = RectPose> extends NodeBase<TData, TLayer, TPose> {
-    kind: 'leaf';
-}
-/** A node with an ordered list of children. This is the real group: what
- *  Cmd+G creates, what SVG `<g>` round-trips to. A container has its own pose,
- *  which its children's poses are relative to, and may optionally clip them. */
-interface ContainerNode<TData, TLayer extends string, TPose = RectPose> extends NodeBase<TData, TLayer, TPose> {
-    kind: 'container';
-    children: NodeId[];
+    /** Ordered child ids. Absent until the node gets its first child. */
+    children?: NodeId[];
     /** Optional clip-path source. Re-evaluated each render. Returning `null`
-     *  means "no clip for this container right now"; an empty / zero-area path
-     *  means "clip everything out" (children render nowhere). */
+     *  means "no clip for this node right now"; an empty / zero-area path
+     *  means "clip everything out" (children render nowhere). Wins over `clip`. */
     clipFromPose?: ClipFromPoseFn<TPose>;
+    /** `'outline'` clips the children to this node's own outline: a mark's
+     *  painter silhouette, or for a group the silhouette of its `data.path`.
+     *  Absent, and with no `clipFromPose`, the children are not clipped. */
+    clip?: NodeClip;
     /** Draws the whole subtree again under each affine it returns, on top of
      *  the original, which still draws once as authored. The copies are paint,
      *  not nodes: nothing stores them, so they follow every edit to the
@@ -555,7 +745,7 @@ interface ContainerNode<TData, TLayer extends string, TPose = RectPose> extends
      *  A copy is a copy of the clipped content — the clip travels with it.
      *  Re-evaluated each render; `null` or `[]` draws no copies. */
     copiesFromPose?: CopiesFromPoseFn<TPose, TData, TLayer>;
-    /** How this container arranges its children. Whenever the container's
+    /** How this node arranges its children. Whenever the node's
      *  child set or order changes, its bounds change size, or a child's pose is
      *  written, the scene hands the change to the strategy — `depart` for children that left it,
      *  `arrive` for children that joined it, `childPoses` otherwise — and records the poses it writes in the same
@@ -564,16 +754,26 @@ interface ContainerNode<TData, TLayer extends string, TPose = RectPose> extends
     layout?: LayoutStrategy<TPose>;
     /** The units its children are shown, typed and snapped in (their poses stay
      *  in world units), and what one base unit is worth in the enclosing scope's.
-     *  It covers the children, not the container; `sceneUnitScopes` reads the chain. */
+     *  It covers the children, not the node; `sceneUnitScopes` reads the chain. */
     units?: UnitScope;
 }
-/** A node in the scene tree: either a leaf or a container. Re-exported
+/** A node that is drawn and picked as one thing — a shape, a label, an image.
+ *  It may still hold children, which are what it is made of. */
+interface MarkNode<TData, TLayer extends string, TPose = RectPose> extends NodeBase<TData, TLayer, TPose> {
+    kind: 'mark';
+}
+/** A node the user gathers things into: what Cmd+G creates, what SVG `<g>`
+ *  round-trips to. An emptied group is still a group. */
+interface GroupNode<TData, TLayer extends string, TPose = RectPose> extends NodeBase<TData, TLayer, TPose> {
+    kind: 'group';
+}
+/** A node in the scene tree: either a mark or a group. Re-exported
  *  publicly as `SceneNode`, to avoid colliding with the DOM's `Node`. */
-type Node<TData, TLayer extends string, TPose = RectPose> = LeafNode<TData, TLayer, TPose> | ContainerNode<TData, TLayer, TPose>;
+type Node<TData, TLayer extends string, TPose = RectPose> = MarkNode<TData, TLayer, TPose> | GroupNode<TData, TLayer, TPose>;
 /** What `Scene.add` needs to mint a node. Everything except the id is
  *  required; the id is generated unless one is supplied. */
 interface AddNodeSpec<TData, TLayer extends string, TPose = RectPose> {
-    kind: 'leaf' | 'container';
+    kind: 'mark' | 'group';
     layer: TLayer;
     pose: TPose;
     data: TData;
@@ -587,10 +787,11 @@ interface AddNodeSpec<TData, TLayer extends string, TPose = RectPose> {
     hidden?: boolean;
     /** Mirrors `SceneNode.locked`. */
     locked?: boolean;
-    /** Only meaningful when `kind === 'container'`. Attach a clip-path function
-     *  to the node; ignored for leaves. Mirrors `ContainerNode.clipFromPose`. */
+    /** Attach a clip-path function to the node; mirrors `SceneNode.clipFromPose`. */
     clipFromPose?: ClipFromPoseFn<TPose>;
-    /** Mirrors `ContainerNode.copiesFromPose`; ignored for leaves. */
+    /** Mirrors `SceneNode.clip`. */
+    clip?: NodeClip;
+    /** Mirrors `SceneNode.copiesFromPose`. */
     copiesFromPose?: CopiesFromPoseFn<TPose, TData, TLayer>;
     /** Mirrors `SceneNode.dependsOn`. */
     dependsOn?: readonly NodeId[] | 'children';
@@ -599,60 +800,26 @@ interface AddNodeSpec<TData, TLayer extends string, TPose = RectPose> {
     derivePath?: DerivePathFn<TPose, TData, TLayer>;
     /** Mirrors `SceneNode.derivePose`, on the same terms as `derivePath`. */
     derivePose?: DerivePoseFn<TPose, TData, TLayer>;
-    /** Mirrors `ContainerNode.layout`; ignored for leaves. */
+    /** Mirrors `SceneNode.layout`. */
     layout?: LayoutStrategy<TPose>;
-    /** Mirrors `ContainerNode.units`; ignored for leaves. */
+    /** Mirrors `SceneNode.units`. */
     units?: UnitScope;
 }
-/** A custom scene mutation registered with `Scene.registerOp`: how to apply
- *  it and how to undo it. The pair is what makes it participate in history. */
-interface RegisteredOp<P> {
-    apply: (payload: P) => void;
-    revert: (payload: P) => void;
-    /** Opts this kind into coalescing under `UseSceneOptions.coalesceWindowMs`:
-     *  two entries of this kind that return the same key inside the window
-     *  merge, and undoing the merged entry calls `revert` with the first
-     *  payload only. Declare it only when `revert` restores an absolute state
-     *  (a stored "from" value), never for a relative payload such as a delta.
-     *  Omitted, or returning `undefined`, the op is always its own entry. */
-    coalesceKey?: (payload: P) => string | undefined;
-}
 /** Per-scene registry mapping string keys to live function references.
  *  Passed to `createScene({ ..., registry })` and `sceneFromJSON(json, { registry })`.
  *  Each function-field type has its own keyed map. */
 interface SceneRegistry<TPose, TData = unknown, TLayer extends string = string> {
-    /** Maps registry keys to `clipFromPose` factory functions for container nodes. */
+    /** Maps registry keys to `clipFromPose` factory functions for nodes. */
     clipFromPose?: Readonly<Record<string, ClipFromPoseFn<TPose>>>;
-    /** Maps registry keys to `copiesFromPose` functions for container nodes. */
+    /** Maps registry keys to `copiesFromPose` functions for nodes. */
     copiesFromPose?: Readonly<Record<string, CopiesFromPoseFn<TPose, TData, TLayer>>>;
     /** Maps registry keys to `derivePath` functions for nodes with `dependsOn`. */
     derivePath?: Readonly<Record<string, DerivePathFn<TPose, TData, TLayer>>>;
     /** Maps registry keys to `derivePose` functions for nodes with `dependsOn`. */
     derivePose?: Readonly<Record<string, DerivePoseFn<TPose, TData, TLayer>>>;
-    /** Maps registry keys to container layout strategies. */
+    /** Maps registry keys to layout strategies. */
     layout?: Readonly<Record<string, LayoutStrategy<TPose>>>;
 }
-/**
- * Decides what one edit's changes to containers do to their children.
- * `arrivals` maps each container to the ids that joined it — by an `add`
- * under it or a `move` into it, whatever op or call made them — in the order
- * they arrived. `changed` names every container whose child set or order
- * changed, whose pose changed size, or one of whose children was posed,
- * arrivals included. Both are read once the edit's other mutations have landed.
- *
- * Return the poses to write, in each node's stored frame; they become part of
- * the same edit, and so of the same undo step. An empty map writes nothing.
- * Return `null` to refuse: the whole edit is reverted (see
- * `SceneArrivalRefused`).
- *
- * Runs only for live edits. Undo, redo and a restored history replay the
- * arrangement that was decided the first time. With none installed, a scene
- * holding declared layouts (`ContainerNode.layout`) runs its own.
- */
-type SceneArrivalHandler<TPose> = (arrivals: ReadonlyMap<NodeId, readonly NodeId[]>, changed: ReadonlySet<NodeId>, 
-/** The nodes that left each container in the edit, by the container they
- *  left — removed, or moved out. */
-departures: ReadonlyMap<NodeId, readonly NodeId[]>) => ReadonlyMap<NodeId, TPose> | null;
 /**
  * The kit-owned scene tree: nodes, layers, and the undo history over both.
  *
@@ -665,7 +832,7 @@ departures: ReadonlyMap<NodeId, readonly NodeId[]>) => ReadonlyMap<NodeId, TPose
  * which the kit never inspects; `TPose` is the transform shape, `RectPose` by
  * default; `TLayer` is the union of layer names.
  */
-interface Scene<TData, TLayer extends string, TPose = RectPose> extends ScenePoseReports<TPose, Node<TData, TLayer, TPose>>, SceneChanges, SceneDocValues, SceneEditPasses {
+interface Scene<TData, TLayer extends string, TPose = RectPose> extends ScenePoseReports<TPose, Node<TData, TLayer, TPose>>, SceneChanges, SceneDocValues, SceneEditPasses, SceneDeclaredFieldSetters {
     readonly nodes: ReadonlyMap<NodeId, Node<TData, TLayer, TPose>>;
     readonly roots: readonly NodeId[];
     readonly layers: readonly LayerRecord<TLayer>[];
@@ -750,7 +917,7 @@ interface Scene<TData, TLayer extends string, TPose = RectPose> extends ScenePos
     setDependsOn(id: NodeId, dependsOn: readonly NodeId[] | 'children' | undefined): void;
     /** Give container `id` a different layout — a strategy, its key in
      *  `SceneRegistry.layout`, or `null` for none — and re-arrange its children
-     *  under it, as one undoable step. Throws for a leaf, or a key the registry
+     *  under it, as one undoable step. Throws for a mark, or a key the registry
      *  does not hold. A registered layout is recorded by its key, so a
      *  serialized history restores it; an unregistered one lives only as long
      *  as the session.
@@ -763,7 +930,6 @@ interface Scene<TData, TLayer extends string, TPose = RectPose> extends ScenePos
      *  Siblings are reindexed. Recorded as one undoable step.
      *
      *  Rejected (throws) when:
-     *  - `parent` exists but is a **leaf**, not a container;
      *  - the move would form a **cycle** — `parent` is `id` itself or one of
      *    `id`'s own descendants;
      *  - it would drop `id` **below its new parent's layer** (child may not
@@ -851,11 +1017,11 @@ interface Scene<TData, TLayer extends string, TPose = RectPose> extends ScenePos
      *  undo step of its own. Removing a node deselects it. */
     getSelection(): readonly NodeId[];
     setSelection(ids: readonly NodeId[]): void;
-    /** Per-node pose / alpha overrides the render and hit-test paths read
+    /** Per-node pose / alpha / path / data overrides the render and hit-test paths read
      *  through. Like {@link Scene.getSelection} this is not document content:
      *  writes are never recorded, never serialized, and do not bump
      *  {@link Scene.getVersion}. See {@link PoseOverrides}. */
-    readonly overrides: PoseOverrides<TPose>;
+    readonly overrides: PoseOverrides<TPose, TData>;
     /** The scene's undo/redo engine, in the shape `@weasel-js/history` defines.
      *  Mutating members route through
      *  the scene's own wrappers, so an undo driven through this bumps
@@ -868,11 +1034,8 @@ interface Scene<TData, TLayer extends string, TPose = RectPose> extends ScenePos
     canUndo(): boolean;
     canRedo(): boolean;
     batch<T>(label: string, fn: () => T, options?: SceneBatchOptions): T;
-    /** The layout container `id` declares, or `null` for a leaf or a
-     *  container that declares none. */
+    /** The layout group `id` declares, or `null` for a mark or a group with none. */
     layoutOf(id: NodeId): LayoutStrategy<TPose> | null;
-    /** Declare the unit scope of container `id`, or clear it with `null`. */
-    setUnits(id: NodeId, units: UnitScope | null): void;
     /** Run `fn` with every mutation applied but none recorded — for writes
      *  that are not edits, such as a simulation stepping poses each frame.
      *  Undo and redo move between recorded states and never restore an
@@ -927,7 +1090,7 @@ interface Scene<TData, TLayer extends string, TPose = RectPose> extends ScenePos
     setHistoryAdapter(fn: (() => unknown) | null): void;
     /** Snapshot the current scene state to a JSON-serializable shape.
      *  History (undo/redo stacks) is NOT captured. Function fields like
-     *  `ContainerNode.clipFromPose` are translated to string keys via the
+     *  `GroupNode.clipFromPose` are translated to string keys via the
      *  scene's registry; throws if any function field has no matching key. */
     toJSON(): SerializedScene<TData, TLayer, TPose>;
     /** Replace this scene's entire node + layer state in place from a snapshot
@@ -942,8 +1105,8 @@ interface Scene<TData, TLayer extends string, TPose = RectPose> extends ScenePos
      *  undo — which would revert to a state this replaces. Throws on an unsupported version or unknown registry/layer ids; on a
      *  malformed snapshot the scene is left empty or partially populated (callers should treat a
      *  `loadState` throw as fatal and reload). Snapshots from `toJSON()` are
-     *  always well-formed. */
-    loadState(json: SerializedScene<TData, TLayer, TPose>): void;
+     *  always well-formed. `opts` reads the snapshot as `specsFromSerialized` does. */
+    loadState(json: SerializedScene<TData, TLayer, TPose> | SerializedSceneV1<TData, TLayer, TPose>, opts?: SpecsFromSerializedOptions<TData, TLayer, TPose>): void;
 }
 
-export { type AddNodeSpec as A, type Bivariant as B, type ClipFromPoseFn as C, type DerivePoseFn as D, type SceneDocValues as E, type SceneEditPass as F, type SceneEditPassOptions as G, type SceneEditSummary as H, IDENTITY_POSE_COMPOSITION as I, type SerializedDoc as J, type SerializedLayer as K, type LayoutFrame as L, type SerializedNode as M, type Node as N, type SerializedSceneHistory as O, type PoseComposition as P, type SystemLayerRecord as Q, type RectPose as R, type Scene as S, asNodeId as T, type UserLayerRecord as U, composeWorldPose as V, composesFrames as W, rebaseLocalPose as X, type SystemLayerSpec as a, type RegisteredOp as b, type SceneRegistry as c, type PoseAdapter as d, type PoseRemoval as e, type PoseWrite as f, type ScenePoseReports as g, type PoseOverrides as h, type SerializedScene as i, type DerivePathFn as j, type DerivedDep as k, type AddLayerSpec as l, type ContainerNode as m, type CopiesFromPoseFn as n, type LayerRecord as o, type LayoutMove as p, type LeafNode as q, type PoseClosure as r, type PoseHold as s, type PoseOverride as t, type PoseWriteOrigin as u, type RemovedNode as v, SCENE_HISTORY_FORM as w, type SceneArrivalHandler as x, type SceneBatchOptions as y, type SceneDoc as z };
+export { type V1Classifier as $, type AddNodeSpec as A, type Bivariant as B, type ClipFromPoseFn as C, type DerivePoseFn as D, type SceneBatchOptions as E, type SceneDeclaredFieldSetters as F, type GroupNode as G, type SceneDoc as H, type InheritedPaint as I, type SceneDocValues as J, type SceneEditPass as K, type LayoutFrame as L, type MarkNode as M, type Node as N, type SceneEditPassOptions as O, type PoseComposition as P, type SceneEditSummary as Q, type RectPose as R, type Scene as S, type SerializedDoc as T, type SerializedLayer as U, type SerializedNode as V, type SerializedNodeV1 as W, type SerializedSceneHistory as X, type SkippedKey as Y, type SystemLayerRecord as Z, type UserLayerRecord as _, type SystemLayerSpec as a, asNodeId as a0, composeWorldPose as a1, composesFrames as a2, inheritedPaintIn as a3, inheritedPaintOf as a4, inheritsPaint as a5, nodeKindOf as a6, rebaseLocalPose as a7, specsFromSerialized as a8, withInheritedPaint as a9, type RegisteredOp as b, type SceneRegistry as c, type PoseAdapter as d, type PoseRemoval as e, type PoseWrite as f, type ScenePoseReports as g, type PoseOverrides as h, type SerializedScene as i, type SerializedSceneV1 as j, type SpecsFromSerializedOptions as k, type NodeClip as l, type DerivePathFn as m, type DerivedDep as n, type AddLayerSpec as o, type CopiesFromPoseFn as p, IDENTITY_POSE_COMPOSITION as q, type LayerRecord as r, type LayoutMove as s, type PoseClosure as t, type PoseHold as u, type PoseOverride as v, type PoseWriteOrigin as w, type RemovedNode as x, SCENE_HISTORY_FORM as y, type SceneArrivalHandler as z };

package/dist/{types-oFeQ5VjV.d.ts → types-p2alu-R1.d.ts}

@@ -1,4 +1,4 @@
-import { L as LayoutStrategy, P as ParallaxOpts } from './types-7puAuVD2.js';
+import { L as LayoutStrategy, P as ParallaxOpts } from './types-49uYJN3j.js';
 import { Op } from '@weasel-js/history';
 import { View } from '@weasel-js/geom';
 import { P as PoseDescriptor } from './poseDescriptor-DN2yfnq_.js';

package/dist/version.js

@@ -7,7 +7,7 @@
 * throwing, since nothing about version reporting should be able to break a
 * consumer's build.
 */
-var VERSION = "1.12.0";
+var VERSION = "1.13.0";
 
 //#endregion
 export { VERSION };