@graphty/graphty-element 2.6.2 → 3.0.1

package/dist/src/session/sets/store.d.ts

@@ -1,13 +1,14 @@
 /**
- * @file The kept-set slice: one keyed map of frozen records, written only through `put` and
- * `delete` inside a write group (design/sets/sets-design.md sections 3.1, 12.4, 13).
+ * @file The kept sets: the `sets` slice of project state, one keyed map of frozen records written
+ * only by the `set.*` commands through the session's dispatcher, and the state kept beside it
+ * (design/sets/sets-design.md sections 3.1, 12.4, 13; design/sets/undo-integration.md section 1).
  *
  * Beside the slice, never in it:
  *
  * - the ISSUED-ID REGISTER, every id ever minted. Monotonic: appended when a group commits,
  *   never written by `put` or `delete`, never rewound. Minting skips it, the live ids and the ids
- *   pending in the open group, so an id is never issued twice even when a group creates, removes
- *   and re-creates one name.
+ *   minted and not yet sealed, so an id is never issued twice even when a transaction creates,
+ *   removes and re-creates one name. Undo, redo and a rollback never rewind it.
  * - the TOMBSTONES, `{ id, name, record? }` for each removed id, rewritten at every commit that
  *   removes it. A tombstone is authoritative only while its id is absent from the slice. Its
  *   record is kept while anything still names the id -- a reference to a removed set resolves
@@ -21,13 +22,14 @@
  * - the ORDER high-water mark: a new set's order is one past the highest order the store has
  *   held, so a restored record can never share its order with a set created after it was removed.
  *
- * A committed group tells its listeners one {@link SetChange} per touched key, from the key's
- * before and after values; a group that throws is rolled back and tells nobody.
+ * Each change of the slice the dispatcher publishes -- a step recorded, undone or redone --
+ * tells the listeners one {@link SetChange} per changed key, from the key's before and after
+ * values; a rollback tells nobody.
  *
- * Only `session/sets/` may import this module (a static test enforces it): nothing else writes
- * set state.
+ * Only `session/sets/` may import this module (a static test enforces it).
  */
 import type { SetId } from "../../catalog/types";
+import { Dispatcher } from "../project/Dispatcher";
 import { type RecordView } from "./prepare";
 import type { EdgeSeeds } from "./resolve";
 import type { ElementSet, SetChange } from "./types";
@@ -52,17 +54,34 @@ interface LogicalSets {
     /** Removed ids, oldest first, with their last name and, while anything named them, record. */
     readonly tombstones: readonly Tombstone[];
 }
-/** The kept-set slice and the state beside it. */
+/** The kept sets and the state beside them. */
 export declare class SetsStore implements RecordView {
-    private readonly records;
+    /** The dispatcher whose `sets` slice holds the records and whose commands write them. */
+    readonly dispatcher: Dispatcher;
     private readonly issued;
+    /** Ids minted for a write not yet sealed; dropped once no group is open. */
+    private readonly pending;
     private readonly tombstones;
     private readonly listeners;
     private readonly commitListeners;
     private readonly seeds;
     private highestOrder;
-    private group;
     private listed;
+    /** The records as the listeners were last told of them. */
+    private told;
+    /** The history position the listeners were last told at, to tell a restore's direction. */
+    private position;
+    /**
+     * Keep sets in a dispatcher's `sets` slice.
+     * @param dispatcher - The session's dispatcher; one of its own, over the set ops alone, when
+     *     absent.
+     */
+    constructor(dispatcher?: Dispatcher);
+    /**
+     * The slice, live.
+     * @returns The records by id.
+     */
+    private get records();
     /**
      * One live record.
      * @param id - Its id.
@@ -75,12 +94,12 @@ export declare class SetsStore implements RecordView {
      */
     values(): Iterable<ElementSet>;
     /**
-     * Every live record by order, ties by id: the same frozen array until a write.
+     * Every live record by order, ties by id: the same frozen array until the slice is written.
      * @returns The records.
      */
     list(): readonly ElementSet[];
     /**
-     * Every id ever issued and committed.
+     * Every id ever issued and sealed.
      * @returns The register.
      */
     register(): ReadonlySet<SetId>;
@@ -111,9 +130,9 @@ export declare class SetsStore implements RecordView {
     forget(named: (id: SetId) => boolean): void;
     /**
      * Mint an id for a name: `set_<slug>`, then `_2`, `_3` and on, skipping the register, the
-     * live ids and the ids already minted in the open group. Only inside a write group.
+     * live ids and the ids minted for writes not yet sealed.
      * @param name - The trimmed name.
-     * @returns The id, pending until the group commits.
+     * @returns The id, issued once the step that writes it is sealed.
      */
     mint(name: string): SetId;
     /**
@@ -122,75 +141,57 @@ export declare class SetsStore implements RecordView {
      */
     nextOrder(): number;
     /**
-     * Write one record. Only inside a write group.
-     * @param record - A frozen record from `prepare`, or restored.
+     * Note a record a set op is about to write: its order is never given out again. Called by the
+     * set service, never rewound.
+     * @param record - The record.
      */
-    put(record: ElementSet): void;
+    written(record: ElementSet): void;
     /**
-     * Remove one record. Only inside a write group.
-     * @param id - Its id.
+     * Keep an id in the register: the step that wrote it has been sealed.
+     * @param id - The id.
      */
-    delete(id: SetId): void;
+    issue(id: SetId): void;
     /**
-     * Run one write group: every `mint`, `put` and `delete` inside commits together, or, when
-     * `write` throws, none of them does. A nested call joins the open group as a savepoint: when
-     * it throws, its own writes and mints are undone and the group goes on.
-     * @param write - The writes.
-     * @param cause - What the listeners are told caused it, for an outermost group.
-     * @returns What `write` returned.
+     * Tombstone a record about to be removed, newest last, so `sets.restore` can bring it back.
+     * @param record - The record.
      */
-    transact<T>(write: () => T, cause?: SetChange["cause"]): T;
+    bury(record: ElementSet): void;
     /**
      * The slice as stored. Internal: the one serialiser a project file or an undo slice uses.
      * @returns The records, the register and the tombstones.
      */
     toLogicalRecords(): LogicalSets;
     /**
-     * Load a stored slice into this empty store: every record validated in load mode and `put`,
-     * the register and the tombstones restored. One write group, told as `load`. Internal.
+     * Load a stored slice into this empty store, as the baseline: every record validated in load
+     * mode, the register and the tombstones restored, and the listeners told once, as `load`.
+     * Internal.
      * @param stored - What {@link toLogicalRecords} returned, after any JSON round trip.
      *
      * A record's `createdFrom` of a kind this version does not know is kept as given and written
      * back unchanged, as an unknown definition kind is (design 12.5). A tombstone whose id is also
      * a live record is dropped: a tombstone speaks only for an absent id.
      * @throws `E_BAD_COMMAND` for a malformed slice, record or tombstone, or two records with one
-     *     id; an Error for a non-empty store.
+     *     id; an Error for a non-empty store, or once the history has recorded a step.
      */
     loadLogicalRecords(stored: unknown): void;
     /**
-     * Listen to committed changes: one call per touched key per group.
+     * Listen to committed changes: one call per changed key per change of the slice.
      * @param listener - The listener.
      * @returns A function that stops listening.
      */
     onChange(listener: (change: SetChange) => void): () => void;
     /**
-     * Hear each committed group whole, before any per-key listener: the change notification
+     * Hear each change of the slice whole, before any per-key listener: the change notification
      * (`./notify`) re-resolves live sets here, ahead of `set:changed`.
      * @param listener - The listener, handed every change of the group.
      * @returns A function that stops listening.
      */
     onCommit(listener: (changes: readonly SetChange[]) => void): () => void;
     /**
-     * The open group.
-     * @param verb - What needs it, for the message.
-     * @returns The group.
-     * @throws An Error outside a write group.
-     */
-    private requireGroup;
-    /**
-     * Remember a key's value before the group first touched it.
-     * @param id - The key.
-     */
-    private touch;
-    /**
-     * Commit a group: register its ids, tombstone what it removed, tell the listeners.
-     * @param group - The group.
-     */
-    private commit;
-    /**
-     * Tombstone a removed record, newest last.
-     * @param record - The record removed.
+     * Tell the listeners what changed since they were last told: the diff of the slice.
+     * @param cause - What changed it. A rollback puts back what nobody was told of, so it tells
+     *     nobody.
      */
-    private bury;
+    private tell;
 }
 export {};

package/dist/src/session/sets/types.d.ts

@@ -39,8 +39,11 @@ export interface SetChange {
     readonly fields: readonly ("name" | "definition" | "order")[];
     /** The frozen record after the change; null after removal. */
     readonly set: ElementSet | null;
-    /** What caused it. OPEN UNION: `command`, or `load` for a stored slice; undo and redo are added later. */
-    readonly cause: "command" | "load";
+    /**
+     * What caused it. OPEN UNION: `command`, `load` for a stored slice, or `undo` and `redo` for a
+     * history call (a restore across several steps is told as the direction it moved).
+     */
+    readonly cause: "command" | "load" | "undo" | "redo";
 }
 /**
  * Whether a set still means what it meant, derived on read from what its definition reads and the

package/dist/src/session/styles/Layer.d.ts

@@ -221,6 +221,11 @@ export interface CompiledLayer {
     readonly layer: Layer;
     /** Its selector, reduced to a predicate and the columns that predicate reads. */
     readonly selector: CompiledSelector;
+    /**
+     * Every path the layer reads, its selector's and its bindings', without repeats: what a
+     * change to a record's attributes has to name for the layer to paint anything differently.
+     */
+    readonly reads: readonly Path[];
 }
 /** Which edit asked for a repaint. */
 export type RepaintReason = "add" | "update" | "remove" | "move" | "sweep";

package/dist/src/session/styles/StylesApi.d.ts

@@ -17,10 +17,10 @@
  * READING IS SYNCHRONOUS, WRITING IS A COMMAND. `list`, `get`, `validate`, `legend`, `explain`
  * and `toDocument` answer from what the session already holds and cost nothing. `add`, `update`,
  * `remove`, `move`, `removeBySource`, `encode`, `highlight`, `applyTemplate` and
- * `resolveToStatic` VALIDATE AND REPAINT, and a repaint is a pass over the elements a layer
- * matches -- so they are commands, not properties, and each returns a `Run`. That is what lets a
- * layer edit on a large graph report progress, take an `AbortSignal`, and be fired from a click
- * handler and forgotten without an unhandled rejection. Awaiting one gives the layer.
+ * `resolveToStatic` each dispatch a command (`style.patch`, `style.encode`, `style.template`),
+ * which is one undoable step in the session's history, and each returns a `Run` that can be
+ * fired from a click handler and forgotten without an unhandled rejection. Awaiting one gives the
+ * layer.
  *
  * ONE ANALYSIS LAYER PER RUN AND CHANNEL. `encode()` is the one path an analysis layer takes, and
  * it REPLACES the layer already painting that channel from that run rather than stacking a second
@@ -40,11 +40,20 @@
  * window. The door for "is this valid" before anything is committed is {@link StylesApi.validate},
  * which is synchronous, writes nothing, and reports every problem at once.
  *
- * THE MODEL MOVES ONLY AFTER THE PAINT SUCCEEDS. Each verb computes the stack it WOULD produce,
- * hands it to the repaint, and commits it only when the repaint resolves. A cancelled or failed
- * edit therefore leaves the list exactly as it was, rather than leaving the layer list saying one
- * thing and the screen showing another. The visible consequence is worth stating plainly: `add()`
- * followed immediately by `list()` does not show the new layer -- `await add()` does.
+ * THE STACK MOVES AT ONCE, AND THE PICTURE FOLLOWS IT. The stack is project state: the command
+ * writes the new stack when it is dispatched, so `add()` followed immediately by `list()` shows
+ * the new layer. The repaint then runs on the session's derivation lane, from the stack the
+ * picture shows to the stack state holds, whatever moved it -- an edit, an undo, a redo -- so
+ * restoring a stack restores the picture. Several edits made faster than a repaint are drawn by
+ * one pass. What a verb's `Run` means follows from that:
+ *
+ * - it settles once the pass that repaints the edit has run, and rejects when that repaint fails
+ *   (the edit stays recorded, and undo takes it back);
+ * - a signal already aborted when the verb is called refuses the edit, and nothing is written;
+ * - `cancel()`, or an abort after the call, does NOT take the edit back: it has been recorded,
+ *   and may have merged into a larger step (a colour picker's drag is one step), so undo is the
+ *   way back. The run then resolves with the edit applied;
+ * - it is never listed in `history.pending` or in `runs`.
  *
  * AN ELEMENT-OWNED LAYER IS NOT THE CONSUMER'S. The base and selection layers are seeded at
  * construction with `source.by === "element"`, which makes them {@link Layer.locked}. Removing,
@@ -53,15 +62,18 @@
  * own comment admits breaks for a reader who calls their own layer "default".
  *
  * WHERE THE REPAINT PLUGS IN. `sources.repaint` is the seam, and nothing in this module
- * implements it: see {@link LayerRepaint} in `./Layer`. A session with no renderer hands none in
- * and paints nothing, which is not a degraded mode -- the stack is the session's and the paint is
- * the renderer's.
+ * implements it: see {@link LayerRepaint} in `./Layer`. This module registers the `styles` hook
+ * of the derivation lane, which hands the repaint the difference between two stacks
+ * (`stackChange` in `./repaint`). A session with no renderer hands none in and paints nothing,
+ * which is not a degraded mode -- the stack is the session's and the paint is the renderer's.
  *
  * Nothing here reaches Babylon.js, Lit or the DOM.
  */
 import type { Channel, EdgeId, LayerId, LayerSource, LayerSpec, NodeId, Path, Scope, StaticStyle, StyleDocument } from "../../catalog/types";
+import { Dispatcher } from "../project/Dispatcher";
 import { type RunRef } from "../results/types";
 import { type EngineVersions, type ResolvedScope, type Run, type RunOptions, type RunQueue } from "../runs";
+import type { HistoryCause } from "../types";
 import type { PreparedBinding } from "./encoding";
 import { type EncodingSource, type EncodingSpec } from "./EncodingSpec";
 import { type ExplainTarget, type StyleExplanation, type UnboundLayer } from "./explain";
@@ -343,6 +355,31 @@ export interface StylesApi {
      * @returns The document, bottom first.
      */
     toDocument(): StyleDocument;
+    /**
+     * Choose the palette a colour binding uses when it names none, one per palette kind: a
+     * binding on groups takes the categorical default, one on amounts the sequential default, and
+     * one with a `midpoint` the diverging default. A kind left out keeps its current default.
+     *
+     * RESOLVED WHEN A LAYER IS WRITTEN: a binding that names no palette records the default's id,
+     * so a saved document always names a concrete palette. The call therefore belongs before the
+     * layers are added. A later call leaves the layers that took the previous default as they are
+     * and writes a warning naming them; with `reapply: true` it re-resolves those layers instead.
+     * A layer that names its palette is never touched.
+     * @param palettes - The palette id per kind. Each must name a palette of that kind.
+     * @param options - How a late call treats the layers already written.
+     * @param options.reapply - True re-resolves the layers that took the previous default.
+     * @throws `E_UNKNOWN_PALETTE` for an id no palette answers to, `E_BAD_COMMAND` for a palette
+     *   of the wrong kind or a slot that is not a palette kind.
+     */
+    setDefaultPalettes(palettes: DefaultPalettes, options?: {
+        readonly reapply?: boolean;
+    }): void;
+}
+/** The palette a colour binding naming none uses, per palette kind. */
+export interface DefaultPalettes {
+    readonly categorical?: string;
+    readonly sequential?: string;
+    readonly diverging?: string;
 }
 /**
  * The style stack as the session holds it: the consumer surface, plus the compiled form.
@@ -380,7 +417,11 @@ export interface StyleChange {
     readonly reason: RepaintReason;
     /** The layers it touched, bottom first. */
     readonly layers: readonly LayerId[];
-    /** How much was repainted, or null when no renderer is bound to this session. */
+    /**
+     * How much the pass that drew this change repainted, or null when no renderer is bound to
+     * this session. When one pass covers several edits (a colour picker's drag, a held undo),
+     * each edit's change carries that pass's whole report.
+     */
     readonly painted: RepaintReport | null;
     /**
      * The paths the changed layers read that nothing in this session answers.
@@ -390,6 +431,11 @@ export interface StyleChange {
      * paints nothing instead of showing a confident empty screen.
      */
     readonly unresolvedPaths: readonly Path[];
+    /**
+     * What moved the stack: an edit (`"command"`), or an undo, a redo, a restore or a rollback,
+     * which each publish one change per step they passed.
+     */
+    readonly cause: HistoryCause;
 }
 /** Everything the style stack is built from. */
 export interface StylesSources {
@@ -476,11 +522,16 @@ export interface StylesSources {
      */
     readonly repaint?: LayerRepaint;
     /**
-     * The queue an edit takes its turn in. Absent builds a sequential one of its own, which is
-     * right for a headless session and wrong for a rendered graph -- a rendered graph hands in
-     * the element's own operation queue so a repaint does not interleave with a load.
+     * The queue the session's runs take their turn in, which `settled()` waits on because a run
+     * paints its suggested layers when it finishes. An edit does not take a turn in it: it is
+     * written when it is dispatched.
      */
     readonly queue?: RunQueue;
+    /**
+     * The one path every change to project state takes, and the history it records. The stack
+     * lives in its `styles` slice. Absent, the stack gets a dispatcher of its own.
+     */
+    readonly dispatcher?: Dispatcher;
     /**
      * Resolve a scope specification, so an edit can record what it looked at.
      *
@@ -525,7 +576,7 @@ export declare const DEFAULT_HIGHLIGHT: {
 /**
  * Build the style stack one session holds.
  * @param sources - What a selector compiles against, the element's own layers, the scales, the
- *     repaint seam, the queue and the change hook.
+ *     repaint seam, the dispatcher and the change hook.
  * @returns The stack, including the compiled form a renderer reads.
  * @throws A `GraphtyError` with code `E_INTERNAL` when one of the element's own layers is
  *     malformed, which is a bug in the element rather than in the call.

package/dist/src/session/styles/autoApply.d.ts

@@ -10,7 +10,9 @@
  * THE RULES, ALL SIX OF THEM:
  *
  * - **A run paints on its FIRST completion, and never again.** A re-run keeps its id, so it keeps
- *   its layers too -- repainting would stack a second copy on the one already bound to it.
+ *   its layers too -- repainting would stack a second copy on the one already bound to it. Whether
+ *   a run has had that moment is kept on its entry in the `runs` slice (`RunEntry.painted`), so an
+ *   undo that takes the run away takes the moment with it, and a redo brings both back.
  * - **A layer somebody wrote by hand wins.** If an authored layer already drives the channel a
  *   suggestion would paint, the suggestion is dropped rather than painted over the decision. The
  *   element's own base layers are not authored and do not suppress anything, or nothing would ever
@@ -21,53 +23,40 @@
  *   the one that would have ended up on top -- so the picture is the same as running the six by
  *   hand, without the five dead layers.
  * - **An explicit `encode()` replaces the derived layer rather than stacking on it.** That rule is
- *   `styles.encode()`'s own, which is exactly why this policy applies suggestions THROUGH the same
- *   verb a consumer calls instead of adding layers by another door: a stranger who runs an
- *   algorithm and then colours by it gets one layer and one legend block, in the place the derived
- *   layer already had.
+ *   `styles.encode()`'s own, which is exactly why a suggestion is applied as the same command a
+ *   consumer's call dispatches (see {@link suggestionCommand}) instead of adding layers by another
+ *   door: a stranger who runs an algorithm and then colours by it gets one layer and one legend
+ *   block, in the place the derived layer already had.
  * - **A highlight is exclusive**, likewise enforced by `styles.highlight()`: a second route or
  *   chosen set replaces the first.
  * - **`{ style: false }` opts out**, and a run that failed, was cancelled or has nothing per
  *   element to paint suggests nothing in the first place.
  *
+ * WHERE THE LAYERS GO. This policy only decides; the runs API plans what it decides into the run's
+ * own step, in the synchronous tail that records the run, so the run, its result and its layers are
+ * one step and one undo (design/undo/undo-design.md section 4.7). A batch's decisions are held and
+ * planned into the batch's step when it is released.
+ *
  * WHAT THIS DOES NOT DO. It never removes a layer, never disables one, and never paints an element
  * a run measured nothing about: what a suggestion becomes is decided by {@link suggestStyles} and
- * applied by the two verbs, both of which scope the layer to the elements carrying that run's
- * value. Dimming the rest is a reader's choice and is not made here.
+ * applied as an encoding or a highlight, both of which scope the layer to the elements carrying
+ * that run's value. Dimming the rest is a reader's choice and is not made here.
  *
  * Nothing here reaches Babylon.js, Lit or the DOM.
  */
 import type { RunId } from "../../catalog/types";
+import type { StyleCommand } from "../commands/style";
 import type { RunStatus, RunStyle } from "../runs/types";
-import type { EncodingRun, EncodingSpec } from "./EncodingSpec";
+import { type StyleSuggestion } from "./derive";
+import type { EncodingRun } from "./EncodingSpec";
 import type { Layer } from "./Layer";
-import type { HighlightSpec } from "./StylesApi";
-/**
- * The stack, as the policy needs it: what is in it, and the two verbs that bind a run to it.
- *
- * Narrow on purpose. A policy that held the whole styles API could add, move and remove layers,
- * and the reason it applies a suggestion through `encode()` rather than through `add()` is that
- * `encode()` carries the replacement rule and the generated selector. Taking only the two verbs is
- * what makes going around them impossible rather than merely discouraged.
- */
+/** The stack, as the policy reads it: what is in it, so an authored layer can win. */
 export interface AutoApplyStyles {
     /**
      * Every layer in the stack, bottom first.
      * @returns The layers.
      */
     list(): readonly Layer[];
-    /**
-     * Paint a run's measurement onto a channel.
-     * @param spec - The run, the channel and the taste.
-     * @returns A run that resolves with the layer.
-     */
-    encode(spec: EncodingSpec): PromiseLike<unknown>;
-    /**
-     * Paint the elements a run chose.
-     * @param spec - The run, the field that says which elements it chose, and what they look like.
-     * @returns A run that resolves with the layers it added.
-     */
-    highlight(spec: HighlightSpec): PromiseLike<unknown>;
 }
 /**
  * What the policy needs to know about a finished run: what it suggests, plus whether to listen.
@@ -94,43 +83,65 @@ export interface AutoApplySources {
     /**
      * Called when applying a suggestion was refused.
      *
-     * Optional, and the reason it exists at all is that the defect this whole system replaces was
-     * silent: a style that failed to apply left the picture looking like an answer. A host that
-     * wires this can say so; a host that does not still never has a refusal reach a consumer's
-     * click handler, because applying is fire-and-forget.
+     * The defect this whole system replaces was silent: a style that failed to apply left the
+     * picture looking like an answer. The run is still recorded without the refused layer, and
+     * the refusal arrives here instead of at a caller who did not ask for the layer.
      * @param runId - The run whose suggestion was refused.
      * @param error - Why.
      */
     readonly onProblem?: (runId: RunId, error: unknown) => void;
 }
-/**
- * The policy, as whoever finishes a run calls it.
- *
- * Three verbs, and the middle two are a pair: everything between `hold()` and `release()` is one
- * piece of work as far as painting is concerned.
- */
+/** A batch's suggestions, held until the batch is released. */
+export interface PaintHold {
+    /**
+     * Stop holding.
+     * @returns What was held, one suggestion per channel, keeping the member that would have
+     * ended up on top, minus what an authored layer already drives; empty on a second release.
+     */
+    release(): readonly StyleSuggestion[];
+}
+/** What the policy decided about one finished run. */
+interface PaintDecision {
+    /** Whether the run has now had its first-completion moment: `RunEntry.painted`. */
+    readonly painted: boolean;
+    /** What to plan into the run's step now; empty when held or when there is nothing to paint. */
+    readonly paint: readonly StyleSuggestion[];
+}
+/** The policy, as whoever records a finished run calls it. */
 export interface AutoApplyPolicy {
     /**
-     * A run reached the end of its life. Paint it, if this is the moment to.
+     * A run reached the end of its life. Decide whether this is the moment it paints.
      * @param run - The run that finished.
+     * @param painted - Whether it had its moment already: the `painted` flag of the entry its
+     * record replaces.
+     * @param hold - The batch holding it, whose release paints it instead.
+     * @returns The decision.
      */
-    completed(run: AutoApplyRun): void;
-    /** Hold painting until the matching {@link AutoApplyPolicy.release}. Nests. */
-    hold(): void;
-    /** Release one hold, painting what was held once the last one is released. */
-    release(): void;
+    completed(run: AutoApplyRun, painted: boolean, hold?: PaintHold): PaintDecision;
     /**
-     * Forget that a run has already painted, because the session no longer holds it.
-     *
-     * Starting the same work again after it was removed is a first completion again: the layers
-     * that painted it went with it, so "never again" would leave a run that nothing can draw.
-     * @param runId - The run that was removed.
+     * Hold a batch's painting until the hold is released.
+     * @returns The hold.
      */
-    forget(runId: RunId): void;
+    hold(): PaintHold;
+    /**
+     * Report a suggestion the stack refused.
+     * @param runId - The run.
+     * @param error - Why.
+     */
+    refused(runId: RunId, error: unknown): void;
 }
 /**
- * Build the policy one session applies its runs' styling through.
- * @param sources - The stack to paint into, and where a refusal is reported.
+ * The command a suggestion is applied as: the one `styles.encode()` or `styles.highlight()`
+ * dispatches for the same specification, so the replacement and exclusivity rules of those verbs
+ * hold for it too.
+ * @param suggestion - The suggestion.
+ * @returns The style command.
+ */
+export declare function suggestionCommand(suggestion: StyleSuggestion): StyleCommand;
+/**
+ * Build the policy one session decides its runs' styling with.
+ * @param sources - The stack to read, and where a refusal is reported.
  * @returns The policy.
  */
 export declare function createAutoApplyPolicy(sources: AutoApplySources): AutoApplyPolicy;
+export {};

package/dist/src/session/styles/index.d.ts

@@ -19,16 +19,16 @@
  *
  * Nothing in this module's import graph reaches Babylon.js, Lit or the DOM.
  */
-export type { AutoApplyPolicy, AutoApplyRun, AutoApplySources, AutoApplyStyles, } from "./autoApply";
+export type { AutoApplyPolicy, AutoApplyRun, AutoApplySources, AutoApplyStyles } from "./autoApply";
 export { createAutoApplyPolicy } from "./autoApply";
 export type { EncodingSuggestion, HighlightSuggestion, StyleSuggestion } from "./derive";
 export { suggestStyles } from "./derive";
 export type { EncodingRun, EncodingSource, EncodingSpec } from "./EncodingSpec";
-export type { ChannelExplanation, ExplainTarget, StyleContribution, StyleExplanation, UnboundLayer, } from "./explain";
+export type { ChannelExplanation, ExplainTarget, StyleContribution, StyleExplanation, UnboundLayer } from "./explain";
 export type { CompiledLayer, Layer, LayerEdit, LayerPosition, LayerProblem, LayerRepaint, PathDirectory, RepaintContext, RepaintReason, RepaintReport, RepaintRequest, ValidationResult, } from "./Layer";
 export type { FieldWords, LegendBlock, LegendSwatch } from "./legend";
 export { quotePath } from "./predicate";
 export type { ElementPaint } from "./repaint";
 export type { Selector } from "./selector";
-export type { ElementLayerSpec, HighlightSpec, SessionStylesApi, StyleChange, StylesApi, StylesSources, TemplateOptions, TemplateReport, } from "./StylesApi";
+export type { DefaultPalettes, ElementLayerSpec, HighlightSpec, SessionStylesApi, StyleChange, StylesApi, StylesSources, TemplateOptions, TemplateReport, } from "./StylesApi";
 export { createStylesApi } from "./StylesApi";

package/dist/src/session/styles/predicate.d.ts

@@ -226,6 +226,13 @@ export interface CompiledSelector {
      */
     readonly problem?: () => string | undefined;
 }
+/**
+ * JMESPath equality: deep, and structural for lists and objects.
+ * @param left - One value.
+ * @param right - The other.
+ * @returns Whether JMESPath considers them equal.
+ */
+export declare function deepEquals(left: unknown, right: unknown): boolean;
 /**
  * Write a column key as a path an expression selector reads back as the same key.
  *

package/dist/src/session/styles/repaint.d.ts

@@ -57,7 +57,7 @@
 import type { GraphtyErrorCode, LayerId, Path } from "../../catalog/types";
 import { type ChannelValues } from "./channels";
 import { type PreparedBinding } from "./encoding";
-import type { CompiledLayer, LayerRepaint, RepaintContext, RepaintReport } from "./Layer";
+import type { CompiledLayer, LayerRepaint, RepaintContext, RepaintReport, RepaintRequest } from "./Layer";
 import { type SelectorSource, type SelectorTarget } from "./predicate";
 import { type ScaleRegistry } from "./scales";
 /**
@@ -319,6 +319,21 @@ export interface ElementIndices {
     /** Edge indices. */
     readonly edge: ArrayLike<number>;
 }
+/**
+ * What the `styles` hook of the derivation lane hands the repaint: the difference between the
+ * stack the picture shows and the stack project state holds, whatever moved it -- an edit, an
+ * undo, a redo, a rollback, or several of them folded into one pass.
+ *
+ * A layer is the same layer when it is the same compiled object: an update replaces it, so the
+ * old and new objects under one id are an edit from one to the other; a layer only in one of the
+ * two stacks was added or removed. A layer kept by identity whose place among the kept layers
+ * changed was moved, and is marked with itself on both sides, so the repaint visits the elements
+ * it matches.
+ * @param previous - The stack the picture shows, bottom first.
+ * @param next - The stack to show.
+ * @returns The request; no edits when the two stacks are the same.
+ */
+export declare function stackChange(previous: readonly CompiledLayer[], next: readonly CompiledLayer[]): RepaintRequest;
 /**
  * Build the repaint one session paints through.
  *

package/dist/src/session/styles/sources.d.ts

@@ -171,7 +171,7 @@ export declare function edgeEndpointOf(graph: GraphSnapshot, index: number, key:
  * @example
  * ```ts
  * const elements = createSelectorSource({
- *     snapshot: () => session.snapshot(),
+ *     snapshot: () => store.getSnapshot(),
  *     results: (id) => session.runs.get(id)?.result,
  *     records,
  * });