@fjader/svelte 0.2.4 → 0.2.5

package/dist/query-engine/sliced-lane.js

@@ -0,0 +1,299 @@
+/**
+ * A sliced lane: one DuckDB-WASM connection whose statements run through the
+ * pending-query API, so the worker executes them in slices and serves other
+ * connections' messages in between. A slow read on a lane no longer holds up a
+ * quick one on another connection.
+ *
+ * ONE STATEMENT AT A TIME, enforced here. A connection holds one pending query,
+ * and a second one, or a `runQuery`, on the same connection silently resets the
+ * first (measured in Phase 0). So the lane queues: first in, first out.
+ *
+ * ABORT (an AbortSignal per statement) has three cases:
+ * - queued: dropped, rejected with AbortError, never sent;
+ * - running, before the result header: `cancelPendingQuery`, rejected with
+ *   AbortError. Only an abort we asked for becomes AbortError; any other error
+ *   passes through unchanged;
+ * - after the header, fetching chunks: the query has finished executing, so
+ *   there is nothing to cancel. Fetching stops and the statement rejects; the
+ *   next `startPendingQuery` resets the leftover result.
+ * A cancel that loses the race (the query finished as it arrived, so the next
+ * poll returns the header) still rejects with AbortError: the caller sees one
+ * outcome for one abort.
+ *
+ * SLICE LENGTH is the database's `queryPollingInterval`, set when it is opened
+ * (`initDuckDB` uses 5 ms). At the default, ~100 ms, a quick statement on
+ * another connection can wait ~50 ms for a slice to end. It cannot be read
+ * back. When the opener knows it (`connectionFrom`'s `pollingIntervalMs`),
+ * the lane trusts that; otherwise it measures, and warns once per page when
+ * the MEDIAN slice over its first sliced statements runs long. A median, not
+ * one reading: each poll waits for a main-thread turn, and during load a busy
+ * main thread stretches round trips past the threshold with short slices.
+ */
+/** Slices longer than this warn once: the polling interval is long. */
+const SLOW_SLICE_MS = 25;
+/** Enough polls in one statement to measure its slices. */
+const MEASURE_POLLS = 3;
+/** Statements measured before judging: the median of these. */
+const MEASURE_STATEMENTS = 5;
+let warnedSlowSlices = false;
+function abortError() {
+    return new DOMException('Statement aborted', 'AbortError');
+}
+export class PendingQueryLane {
+    #bindings;
+    #conn;
+    #closeConnection;
+    #queue = [];
+    #running = null;
+    #runningDone = null;
+    #closed = false;
+    #hold;
+    /**
+     * Wait as `hold` asks before a call that executes. Fetches are not held:
+     * they move finished bytes, nearly no worker time, and holding them would
+     * only delay the slow result. Returns the wait, which is not execution, or
+     * null when there is none: then the caller goes on in the same tick, as a
+     * lane without a hold always did.
+     */
+    #beforeSlice() {
+        const wait = this.#hold?.();
+        if (!wait)
+            return null;
+        const t = performance.now();
+        return wait.then(() => performance.now() - t);
+    }
+    /** Per-statement slice lengths, until judged; null when not measuring. */
+    #slices = [];
+    constructor(bindings, conn, closeConnection, 
+    /** The database's polling interval, when the opener knows it. */
+    options = {}) {
+        this.#bindings = bindings;
+        this.#conn = conn;
+        this.#closeConnection = closeConnection;
+        this.#hold = options.hold ?? null;
+        const known = options.pollingIntervalMs;
+        if (known != null) {
+            this.#slices = null;
+            if (known > SLOW_SLICE_MS)
+                warnSlowSlices(known);
+        }
+    }
+    query(sql, signal) {
+        return this.#enqueue(sql, signal, true);
+    }
+    async exec(sql, signal) {
+        const { polls } = await this.#enqueue(sql, signal, false);
+        return { polls };
+    }
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        for (const job of this.#queue)
+            this.#settleAborted(job);
+        this.#queue = [];
+        if (this.#running)
+            this.#abort(this.#running);
+        await this.#runningDone;
+        await this.#closeConnection();
+    }
+    #enqueue(sql, signal, fetch) {
+        if (this.#closed || signal?.aborted)
+            return Promise.reject(abortError());
+        return new Promise((resolve, reject) => {
+            const job = {
+                sql,
+                signal,
+                fetch,
+                phase: 'queued',
+                aborted: false,
+                resolve,
+                reject,
+                onAbort: null
+            };
+            if (signal) {
+                job.onAbort = () => this.#abort(job);
+                signal.addEventListener('abort', job.onAbort, { once: true });
+            }
+            this.#queue.push(job);
+            this.#pump();
+        });
+    }
+    #abort(job) {
+        if (job.aborted)
+            return;
+        job.aborted = true;
+        if (job.phase === 'queued') {
+            const i = this.#queue.indexOf(job);
+            if (i >= 0)
+                this.#queue.splice(i, 1);
+            this.#settleAborted(job);
+        }
+        else if (job.phase === 'running') {
+            // Interrupts execution; the poll in flight rejects or, if the query
+            // just finished, returns the header. Either way #run sees `aborted`.
+            this.#bindings.cancelPendingQuery(this.#conn).catch(() => { });
+        }
+        // 'fetching': the query has finished; #run stops at its next fetch.
+    }
+    #settleAborted(job) {
+        job.aborted = true;
+        this.#detach(job);
+        job.reject(abortError());
+    }
+    #detach(job) {
+        if (job.onAbort)
+            job.signal?.removeEventListener('abort', job.onAbort);
+        job.onAbort = null;
+    }
+    #pump() {
+        if (this.#running)
+            return;
+        const job = this.#queue.shift();
+        if (!job)
+            return;
+        this.#running = job;
+        this.#runningDone = this.#run(job).finally(() => {
+            this.#running = null;
+            this.#runningDone = null;
+            this.#pump();
+        });
+    }
+    async #run(job) {
+        const b = this.#bindings;
+        const conn = this.#conn;
+        job.phase = 'running';
+        const t0 = performance.now();
+        let polls = 0;
+        let held = 0;
+        try {
+            let header;
+            try {
+                const before = this.#beforeSlice();
+                if (before)
+                    held += await before;
+                if (job.aborted)
+                    throw abortError();
+                header = await b.startPendingQuery(conn, job.sql, false);
+                while (header == null) {
+                    const wait = this.#beforeSlice();
+                    if (wait)
+                        held += await wait;
+                    if (job.aborted)
+                        throw abortError();
+                    polls++;
+                    header = await b.pollPendingQuery(conn);
+                }
+            }
+            catch (e) {
+                // The cancel's own rejection, or anything else after an abort: one
+                // outcome for the caller. Not asked for: passed through as is.
+                throw job.aborted ? abortError() : e;
+            }
+            // Finished just as a cancel arrived: aborted all the same.
+            if (job.aborted)
+                throw abortError();
+            // Held time is waiting for the main connection, not execution.
+            const execMs = performance.now() - t0 - held;
+            const ipc = [header];
+            if (job.fetch) {
+                job.phase = 'fetching';
+                for (;;) {
+                    if (job.aborted)
+                        throw abortError();
+                    const chunk = await b.fetchQueryResults(conn);
+                    if (!chunk || chunk.byteLength === 0)
+                        break;
+                    ipc.push(chunk);
+                }
+            }
+            if (job.aborted)
+                throw abortError();
+            this.#noteSlices(polls, execMs);
+            this.#detach(job);
+            job.resolve({ ipc, polls, execMs });
+        }
+        catch (e) {
+            this.#detach(job);
+            job.reject(e);
+        }
+    }
+    #noteSlices(polls, ms) {
+        const slices = this.#slices;
+        if (!slices || polls < MEASURE_POLLS)
+            return;
+        slices.push(ms / polls);
+        if (slices.length < MEASURE_STATEMENTS)
+            return;
+        this.#slices = null;
+        const median = [...slices].sort((x, y) => x - y)[slices.length >> 1];
+        if (median > SLOW_SLICE_MS)
+            warnSlowSlices(median);
+    }
+}
+function warnSlowSlices(ms) {
+    if (warnedSlowSlices)
+        return;
+    warnedSlowSlices = true;
+    console.warn(`[Fjader] DuckDB runs sliced statements in ~${Math.round(ms)} ms slices, so a quick ` +
+        'query can wait that long behind a slow one. Open the database with ' +
+        'db.open({ query: { queryPollingInterval: 5 } }) and pass ' +
+        'connectionFrom(conn, { pollingIntervalMs: 5 }) (initDuckDB does both).');
+}
+/** For tests: the once-per-page slice warning, rearmed. */
+export function _resetSliceWarning() {
+    warnedSlowSlices = false;
+}
+/**
+ * One lane, opened on first use. `get()` answers in the same tick once the
+ * lane's state is known (open, or none to be had), and returns a promise only
+ * while it opens: a statement sent while there is no lane goes out with no
+ * extra microtask, so nothing sent after it in the same tick can overtake it.
+ */
+export class LaneSlot {
+    #open;
+    #onFail;
+    #state = 'unknown';
+    #lane = null;
+    #promise = null;
+    /** `open` returns null when no lane can be had (no capability). */
+    constructor(open, onFail) {
+        this.#open = open;
+        this.#onFail = onFail;
+    }
+    get isOpen() {
+        return this.#state === 'open';
+    }
+    get() {
+        if (this.#state === 'open')
+            return this.#lane;
+        if (this.#state === 'none')
+            return null;
+        if (this.#promise)
+            return this.#promise;
+        const opening = this.#open();
+        if (!opening) {
+            this.#state = 'none';
+            return null;
+        }
+        this.#state = 'opening';
+        this.#promise = opening.then((lane) => {
+            this.#lane = lane;
+            this.#state = 'open';
+            return lane;
+        }, (e) => {
+            this.#state = 'none';
+            this.#onFail(e);
+            return null;
+        });
+        return this.#promise;
+    }
+    /** Close the lane if it was opened (or is opening); none can open after. */
+    async close() {
+        const lane = this.#promise ? await this.#promise : null;
+        this.#state = 'none';
+        this.#lane = null;
+        if (lane)
+            await lane.close().catch(() => { });
+    }
+}

package/dist/query-engine/source-routing.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Where an interaction read runs, by the source it reads: the main connection
+ * (`runQuery`: no polling, no chunked fetch) or a sliced lane, where a slow
+ * read interleaves with everyone else's instead of holding the worker.
+ *
+ * A COST RECORD PER SOURCE (the table a statement actually reads: a base table,
+ * a view, or a preagg table): unknown, fast or slow.
+ *
+ * - Unknown and slow sources read on a lane; fast ones on the main connection.
+ * - LANES ARE FOR SLOW SOURCES ONLY. A lane read costs 20-27 ms where the main
+ *   connection takes 2-5 ms (measured on /test/entrance at load): it needs at
+ *   least three round trips (start, fetch, a final empty fetch), and each
+ *   waits behind a slice of every other busy lane, a cost that grows with the
+ *   number of busy lanes (so the pool stays small).
+ * - Hence the PRIOR, where a source starts: first from the DDL that made it
+ *   through the engine (QueryEngine #noteDDL: a table starts fast, a view
+ *   unknown), else from the catalog, looked up off the critical path (a
+ *   table in an in-memory catalog starts fast; anything else unknown). A
+ *   preagg table, which fjader builds in memory, starts fast. fjader's own
+ *   identity views are never a source: a mark's reads name its base table.
+ *   An app can override the prior (QueryEngine.sourceCost), and a
+ *   measurement corrects either.
+ * - TEMP sources never leave the main connection: they exist only on the
+ *   connection that made it (QueryEngine #localSources).
+ * - Only DATA reads update the record. A source's first statements are a
+ *   DESCRIBE or a range query, quick even when its data query (a GROUP BY, a
+ *   window, dense padding) is not.
+ * - On a lane the measure is the poll count, taken in the worker: finished in
+ *   its first slice or the next marks the source FAST, whatever its record
+ *   was. Symmetric on purpose: the usual slow read is a cold one (remote
+ *   parquet, a view slow the first time), and brushing that source later is
+ *   quick; a "slow" that stuck would slice every brush frame for the session.
+ * - More slices than that marks it SLOW, unless the result was large and its
+ *   execution short: a 2M-row read passes two 5 ms slices on transfer and
+ *   decode alone, the fetch phase barely holds the worker, and on a lane it
+ *   would come back in ~1000 chunks (+~40 ms a frame). Large results stay on
+ *   the main connection unless execution alone is long.
+ * - On the main connection the measure is send-to-bytes time, taken on the
+ *   main thread, so a busy frame inflates it: a fast source turns slow only
+ *   after TWO consecutive slow reads.
+ *
+ * ORDER when a source changes lane. Its next read may go to the main
+ * connection while an earlier one is still queued on its lane. Mark data
+ * cannot overtake itself: execute-latest keeps at most one read of a mark in
+ * flight, and the next waits for it. Setup reads are cached and order-free.
+ * A future read without a callerId that cares about order must keep its
+ * source's lane.
+ */
+export type SourceCost = 'unknown' | 'fast' | 'slow';
+/** Past this many polls (slices after the first) a lane read was slow. */
+export declare const FAST_POLLS = 1;
+/** A main-connection read slower than this, twice running, turns its source slow. */
+export declare const SLOW_MAIN_MS = 50;
+/** A result this large is "large": it stays on the main connection... */
+export declare const LARGE_ROWS = 200000;
+/** ...unless its execution alone takes longer than this. */
+export declare const LARGE_EXEC_MS = 100;
+export declare class SourceRouting {
+    #private;
+    constructor(laneCount: number);
+    cost(source: string): SourceCost;
+    /**
+     * The prior for a source not yet measured: what it is (see the module
+     * comment). Applies only while its record is unknown and not hinted.
+     */
+    prior(source: string, cost: SourceCost): void;
+    /**
+     * The source was dropped or replaced by something else: back to unknown,
+     * unless the app hinted it.
+     */
+    forget(source: string): void;
+    /** The app knows better than the prior: a slow table, a cheap view. */
+    hint(source: string, cost: 'fast' | 'slow'): void;
+    /** The lane a source sticks to, whatever its cost (a read forced sliced). */
+    laneOf(source: string): number;
+    /** The lane index to read `source` on, or null for the main connection. */
+    route(source: string): number | null;
+    /**
+     * A data read finished on a lane: `polls` slices after the first, `execMs`
+     * until its result header, `rows` in the result.
+     */
+    noteLaneRead(source: string, polls: number, execMs: number, rows: number): void;
+    /** A data read finished on the main connection, `ms` from send to its bytes. */
+    noteMainRead(source: string, ms: number, rows: number): void;
+    /**
+     * A data reload: every measured cost is unknown again (the prior is set
+     * again by the next describe); an app's hint stays.
+     */
+    reset(): void;
+}
+/**
+ * What a statement does to the set of sources, read from its text: a table or
+ * view created under a plain name, or one dropped. Narrow on purpose: a wrong
+ * "table" (fast) is the expensive mistake, a wrong "unknown" costs one sliced
+ * read (~20 ms) before the first quick one corrects it. Qualified names
+ * (an attached database), CREATE MACRO, TYPE, SEQUENCE and anything else
+ * return null.
+ */
+export declare function sourceDDL(sql: string): {
+    kind: 'table' | 'view';
+    name: string;
+    temp: boolean;
+} | {
+    kind: 'drop';
+    name: string;
+} | null;

package/dist/query-engine/source-routing.js

@@ -0,0 +1,189 @@
+/**
+ * Where an interaction read runs, by the source it reads: the main connection
+ * (`runQuery`: no polling, no chunked fetch) or a sliced lane, where a slow
+ * read interleaves with everyone else's instead of holding the worker.
+ *
+ * A COST RECORD PER SOURCE (the table a statement actually reads: a base table,
+ * a view, or a preagg table): unknown, fast or slow.
+ *
+ * - Unknown and slow sources read on a lane; fast ones on the main connection.
+ * - LANES ARE FOR SLOW SOURCES ONLY. A lane read costs 20-27 ms where the main
+ *   connection takes 2-5 ms (measured on /test/entrance at load): it needs at
+ *   least three round trips (start, fetch, a final empty fetch), and each
+ *   waits behind a slice of every other busy lane, a cost that grows with the
+ *   number of busy lanes (so the pool stays small).
+ * - Hence the PRIOR, where a source starts: first from the DDL that made it
+ *   through the engine (QueryEngine #noteDDL: a table starts fast, a view
+ *   unknown), else from the catalog, looked up off the critical path (a
+ *   table in an in-memory catalog starts fast; anything else unknown). A
+ *   preagg table, which fjader builds in memory, starts fast. fjader's own
+ *   identity views are never a source: a mark's reads name its base table.
+ *   An app can override the prior (QueryEngine.sourceCost), and a
+ *   measurement corrects either.
+ * - TEMP sources never leave the main connection: they exist only on the
+ *   connection that made it (QueryEngine #localSources).
+ * - Only DATA reads update the record. A source's first statements are a
+ *   DESCRIBE or a range query, quick even when its data query (a GROUP BY, a
+ *   window, dense padding) is not.
+ * - On a lane the measure is the poll count, taken in the worker: finished in
+ *   its first slice or the next marks the source FAST, whatever its record
+ *   was. Symmetric on purpose: the usual slow read is a cold one (remote
+ *   parquet, a view slow the first time), and brushing that source later is
+ *   quick; a "slow" that stuck would slice every brush frame for the session.
+ * - More slices than that marks it SLOW, unless the result was large and its
+ *   execution short: a 2M-row read passes two 5 ms slices on transfer and
+ *   decode alone, the fetch phase barely holds the worker, and on a lane it
+ *   would come back in ~1000 chunks (+~40 ms a frame). Large results stay on
+ *   the main connection unless execution alone is long.
+ * - On the main connection the measure is send-to-bytes time, taken on the
+ *   main thread, so a busy frame inflates it: a fast source turns slow only
+ *   after TWO consecutive slow reads.
+ *
+ * ORDER when a source changes lane. Its next read may go to the main
+ * connection while an earlier one is still queued on its lane. Mark data
+ * cannot overtake itself: execute-latest keeps at most one read of a mark in
+ * flight, and the next waits for it. Setup reads are cached and order-free.
+ * A future read without a callerId that cares about order must keep its
+ * source's lane.
+ */
+/** Past this many polls (slices after the first) a lane read was slow. */
+export const FAST_POLLS = 1;
+/** A main-connection read slower than this, twice running, turns its source slow. */
+export const SLOW_MAIN_MS = 50;
+/** A result this large is "large": it stays on the main connection... */
+export const LARGE_ROWS = 200_000;
+/** ...unless its execution alone takes longer than this. */
+export const LARGE_EXEC_MS = 100;
+export class SourceRouting {
+    #records = new Map();
+    #laneCount;
+    /** Sources per lane, to place a new one on the least used. */
+    #laneLoad;
+    constructor(laneCount) {
+        this.#laneCount = laneCount;
+        this.#laneLoad = new Array(laneCount).fill(0);
+    }
+    #of(source) {
+        let r = this.#records.get(source);
+        if (!r) {
+            let lane = 0;
+            for (let i = 1; i < this.#laneCount; i++) {
+                if (this.#laneLoad[i] < this.#laneLoad[lane])
+                    lane = i;
+            }
+            this.#laneLoad[lane]++;
+            r = { cost: 'unknown', hinted: false, mainSlow: 0, lane };
+            this.#records.set(source, r);
+        }
+        return r;
+    }
+    cost(source) {
+        return this.#records.get(source)?.cost ?? 'unknown';
+    }
+    /**
+     * The prior for a source not yet measured: what it is (see the module
+     * comment). Applies only while its record is unknown and not hinted.
+     */
+    prior(source, cost) {
+        const r = this.#of(source);
+        if (r.cost === 'unknown' && !r.hinted)
+            r.cost = cost;
+    }
+    /**
+     * The source was dropped or replaced by something else: back to unknown,
+     * unless the app hinted it.
+     */
+    forget(source) {
+        const r = this.#records.get(source);
+        if (!r || r.hinted)
+            return;
+        r.cost = 'unknown';
+        r.mainSlow = 0;
+    }
+    /** The app knows better than the prior: a slow table, a cheap view. */
+    hint(source, cost) {
+        const r = this.#of(source);
+        r.cost = cost;
+        r.hinted = true;
+        r.mainSlow = 0;
+    }
+    /** The lane a source sticks to, whatever its cost (a read forced sliced). */
+    laneOf(source) {
+        return this.#of(source).lane;
+    }
+    /** The lane index to read `source` on, or null for the main connection. */
+    route(source) {
+        const r = this.#of(source);
+        return r.cost === 'fast' ? null : r.lane;
+    }
+    /**
+     * A data read finished on a lane: `polls` slices after the first, `execMs`
+     * until its result header, `rows` in the result.
+     */
+    noteLaneRead(source, polls, execMs, rows) {
+        const r = this.#of(source);
+        r.mainSlow = 0;
+        if (polls <= FAST_POLLS)
+            r.cost = 'fast';
+        else if (rows > LARGE_ROWS && execMs <= LARGE_EXEC_MS)
+            r.cost = 'fast';
+        else
+            r.cost = 'slow';
+    }
+    /** A data read finished on the main connection, `ms` from send to its bytes. */
+    noteMainRead(source, ms, rows) {
+        const r = this.#of(source);
+        const slow = rows > LARGE_ROWS ? ms > LARGE_EXEC_MS : ms > SLOW_MAIN_MS;
+        if (!slow) {
+            r.mainSlow = 0;
+            if (r.cost === 'unknown')
+                r.cost = 'fast';
+            return;
+        }
+        if (++r.mainSlow >= 2) {
+            r.cost = 'slow';
+            r.mainSlow = 0;
+        }
+    }
+    /**
+     * A data reload: every measured cost is unknown again (the prior is set
+     * again by the next describe); an app's hint stays.
+     */
+    reset() {
+        for (const r of this.#records.values()) {
+            if (r.hinted)
+                continue;
+            r.cost = 'unknown';
+            r.mainSlow = 0;
+        }
+    }
+}
+/**
+ * What a statement does to the set of sources, read from its text: a table or
+ * view created under a plain name, or one dropped. Narrow on purpose: a wrong
+ * "table" (fast) is the expensive mistake, a wrong "unknown" costs one sliced
+ * read (~20 ms) before the first quick one corrects it. Qualified names
+ * (an attached database), CREATE MACRO, TYPE, SEQUENCE and anything else
+ * return null.
+ */
+export function sourceDDL(sql) {
+    const name = String.raw `("(?:[^"]|"")+"|[A-Za-z_][A-Za-z0-9_$]*)`;
+    const end = String.raw `(?=\s|\(|;|$)`;
+    const create = new RegExp(String.raw `^\s*CREATE\s+(?:OR\s+REPLACE\s+)?((?:TEMP|TEMPORARY)\s+)?(TABLE|VIEW)\s+(?:IF\s+NOT\s+EXISTS\s+)?` +
+        name +
+        end, 'i').exec(sql);
+    if (create)
+        return {
+            kind: create[2].toUpperCase() === 'TABLE' ? 'table' : 'view',
+            name: unquote(create[3]),
+            // TEMP objects belong to the connection that made them.
+            temp: !!create[1]
+        };
+    const drop = new RegExp(String.raw `^\s*DROP\s+(?:TABLE|VIEW)\s+(?:IF\s+EXISTS\s+)?` + name + end, 'i').exec(sql);
+    if (drop)
+        return { kind: 'drop', name: unquote(drop[1]) };
+    return null;
+}
+function unquote(name) {
+    return name.startsWith('"') ? name.slice(1, -1).replaceAll('""', '"') : name;
+}

package/dist/scales/BandScaleState.svelte.d.ts

@@ -310,7 +310,9 @@ export declare class BandScaleState {
      * reports what CHANGED rather than notifying anyone: nothing below runs for
      * an answer identical to the one already on screen.
      */
-    updateDomainFromExtents(): void;
+    updateDomainFromExtents(options?: {
+        instant?: boolean;
+    }): void;
     /**
      * The band channel as GPU-ready floats.
      *
@@ -362,6 +364,12 @@ export declare class BandScaleState {
      * Changes only when the dim or the domain does.
      */
     getTicks(): Float32Array;
+    /**
+     * The slots' latest layout if it landed at once (a catch-up result), else 0:
+     * what follows from it, like `tickVisibility`, lands with it. Reactive
+     * through `_version`, which every layout bumps.
+     */
+    get slotsLandedLayout(): number;
     /**
      * Where each grid line is headed: 1 for a displayed category, 0 otherwise,
      * row-aligned with `getTicks`. A grid morphs its lines' opacity toward this on

package/dist/scales/BandScaleState.svelte.js

@@ -451,12 +451,12 @@ export class BandScaleState {
      * all-NULL column that renders nothing — because an expression-backed axis
      * gets a dim like any other since `c55e719`.
      */
-    #rebuildSlotTable() {
+    #rebuildSlotTable(instant = false) {
         if (this.hasIdentity) {
-            this.#slots.layout('ids', this.#displayOrder, this.#resolver.idCount);
+            this.#slots.layout('ids', this.#displayOrder, this.#resolver.idCount, instant);
         }
         else {
-            this.#slots.layout('positions', null, this.#domain.length);
+            this.#slots.layout('positions', null, this.#domain.length, instant);
         }
     }
     // =========================================================================
@@ -552,7 +552,7 @@ export class BandScaleState {
      * reports what CHANGED rather than notifying anyone: nothing below runs for
      * an answer identical to the one already on screen.
      */
-    updateDomainFromExtents() {
+    updateDomainFromExtents(options = {}) {
         if (!this.#enableUpdates) {
             return;
         }
@@ -566,7 +566,9 @@ export class BandScaleState {
             return;
         this.#domain = values;
         this.#displayOrder = ids;
-        this.#rebuildSlotTable();
+        // Instant: the categories take their new slots at once (a catch-up
+        // result, see SlotTransition.layout).
+        this.#rebuildSlotTable(options.instant);
         this._version++;
         // Notify GPU to re-render charts using this scale
         this.#registry?.invalidateChartsUsingScale(this);
@@ -684,6 +686,15 @@ export class BandScaleState {
             ticks[i] = i;
         return ticks;
     }
+    /**
+     * The slots' latest layout if it landed at once (a catch-up result), else 0:
+     * what follows from it, like `tickVisibility`, lands with it. Reactive
+     * through `_version`, which every layout bumps.
+     */
+    get slotsLandedLayout() {
+        void this._version;
+        return this.#slots.landedLayout;
+    }
     /**
      * Where each grid line is headed: 1 for a displayed category, 0 otherwise,
      * row-aligned with `getTicks`. A grid morphs its lines' opacity toward this on

package/dist/scales/ChartScales.svelte.d.ts

@@ -1,3 +1,4 @@
+import type { EntranceGate } from '../animation/EntranceGate';
 import type { RegisteredScaleRequirement, ResolvedScaleConfiguration } from './ScalePriorities';
 import type { ScaleRegistry } from './ScaleRegistry.svelte';
 import type { GPUCoordinator } from '../gpu/GPUCoordinator.svelte';
@@ -32,6 +33,8 @@ interface ChartScalesConfig {
     yDisableZoom?: boolean;
     useXSelection?: boolean;
     useYSelection?: boolean;
+    /** The chart's entrance gate: its scales snap, and show no ticks, until it opens. */
+    entranceGate?: EntranceGate | null;
 }
 export declare class ChartScales {
     #private;