@fjader/svelte 0.2.3 → 0.2.5

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/query-engine/toggle-predicate.d.ts

@@ -8,3 +8,24 @@ import { type ExprNode } from '@uwdata/mosaic-sql';
  * so a predicate is never rewritten after the fact.
  */
 export declare function togglePredicate(exprs: ExprNode[], tuples: unknown[][]): ExprNode;
+/**
+ * Above this many ids, a selection over an id column is a bitmap, not an `IN`
+ * list (see idBitmapPredicate). The crossover measured in DuckDB-WASM 1.30 lies
+ * between 500 values (`IN`, 29 ms on 2 M rows) and the bitmap (26 ms).
+ */
+export declare const BITMAP_MIN_IDS = 256;
+/**
+ * `expr`'s id is one of `ids`, as one constant-size literal:
+ * `get_bit('<bits>'::BIT, <index>) = 1`.
+ *
+ * Never `NOT IN`, whatever the selection's size: DuckDB evaluates it as a chain
+ * of `<>`, 2.8 s on 2 M rows for 1 000 ids. And never a long `IN`, which it
+ * spends most of its time parsing.
+ *
+ * Bit `id + 1` is set for each selected id; bit 0 is id -1 ("not in the dim
+ * yet") and is never set; the last bit, `size + 1`, is a sentinel kept 0. The
+ * index is clamped onto [0, sentinel], so an id appended to the dim after the
+ * selection was made reads the sentinel (it was not selected: a snapshot), and
+ * get_bit never sees an index out of range, which is an error rather than a 0.
+ */
+export declare function idBitmapPredicate(expr: ExprNode, ids: readonly number[], size: number): ExprNode;

package/dist/query-engine/toggle-predicate.js

@@ -1,4 +1,4 @@
-import { and as sqlAnd, isIn, isNotDistinct, literal, or } from '@uwdata/mosaic-sql';
+import { and as sqlAnd, isIn, isNotDistinct, literal, or, sql as sqlTag } from '@uwdata/mosaic-sql';
 /**
  * A toggle's clause over its selected tuples: `IN` for one field, an `OR` of
  * `IS NOT DISTINCT FROM` tuples for several, so a NULL member matches NULL.
@@ -25,3 +25,31 @@ export function togglePredicate(exprs, tuples) {
     const clauses = tuples.map((t) => sqlAnd(t.map((v, i) => isNotDistinct(exprs[i], literal(v)))));
     return clauses.length === 1 ? clauses[0] : or(clauses);
 }
+/**
+ * Above this many ids, a selection over an id column is a bitmap, not an `IN`
+ * list (see idBitmapPredicate). The crossover measured in DuckDB-WASM 1.30 lies
+ * between 500 values (`IN`, 29 ms on 2 M rows) and the bitmap (26 ms).
+ */
+export const BITMAP_MIN_IDS = 256;
+/**
+ * `expr`'s id is one of `ids`, as one constant-size literal:
+ * `get_bit('<bits>'::BIT, <index>) = 1`.
+ *
+ * Never `NOT IN`, whatever the selection's size: DuckDB evaluates it as a chain
+ * of `<>`, 2.8 s on 2 M rows for 1 000 ids. And never a long `IN`, which it
+ * spends most of its time parsing.
+ *
+ * Bit `id + 1` is set for each selected id; bit 0 is id -1 ("not in the dim
+ * yet") and is never set; the last bit, `size + 1`, is a sentinel kept 0. The
+ * index is clamped onto [0, sentinel], so an id appended to the dim after the
+ * selection was made reads the sentinel (it was not selected: a snapshot), and
+ * get_bit never sees an index out of range, which is an error rather than a 0.
+ */
+export function idBitmapPredicate(expr, ids, size) {
+    const bits = new Array(size + 2).fill('0');
+    for (const id of ids)
+        if (id >= 0 && id < size)
+            bits[id + 1] = '1';
+    const sentinel = size + 1;
+    return sqlTag `get_bit(${literal(bits.join(''))}::BIT, CAST(greatest(least(${expr} + 1, ${sentinel}), 0) AS INTEGER)) = 1`;
+}

package/dist/scales/ActivityTable.d.ts

@@ -85,8 +85,12 @@ export declare class ActivityTable {
      * fade down from 1.
      *
      * `resize(0)` drops every id, for ids that stopped meaning their category.
+     *
+     * `trailing`: the last slot is not an id but a slot of its own that stays
+     * last (FieldActivity's free slot). Its fade moves to the new end, and the
+     * slot it leaves is a new id like any other, rather than inheriting it.
      */
-    resize(count: number, active?: readonly number[] | null): void;
+    resize(count: number, active?: readonly number[] | null, trailing?: boolean): void;
     /**
      * Select exactly these ids; every other id fades out. Ids outside the table
      * are ignored. Does nothing when the selection is the one already headed to.

package/dist/scales/ActivityTable.js

@@ -117,11 +117,18 @@ export class ActivityTable {
      * fade down from 1.
      *
      * `resize(0)` drops every id, for ids that stopped meaning their category.
+     *
+     * `trailing`: the last slot is not an id but a slot of its own that stays
+     * last (FieldActivity's free slot). Its fade moves to the new end, and the
+     * slot it leaves is a new id like any other, rather than inheriting it.
      */
-    resize(count, active) {
+    resize(count, active, trailing = false) {
         if (count === this.#to.length)
             return;
-        const keep = Math.min(this.#to.length, count);
+        const oldLength = this.#to.length;
+        const tail = trailing && oldLength > 0 && count > 0;
+        const keep = tail ? Math.min(oldLength - 1, count - 1) : Math.min(oldLength, count);
+        const ids = tail ? count - 1 : count;
         const selecting = active === undefined ? this.#selecting : active !== null;
         const fill = selecting ? 0 : 1;
         const grown = (old) => {
@@ -130,9 +137,11 @@ export class ActivityTable {
             next.set(old.subarray(0, keep), 0);
             if (active) {
                 for (const id of active)
-                    if (id >= keep && id < count)
+                    if (id >= keep && id < ids)
                         next[id] = 1;
             }
+            if (tail)
+                next[count - 1] = old[oldLength - 1];
             return next;
         };
         this.#from = grown(this.#from);

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

@@ -211,6 +211,8 @@ export declare class BandScaleState {
      * undisplayed Other is ignored.
      */
     setOtherId(id: number | null): void;
+    /** This axis's Other bucket id, while a mark on it has one; null otherwise. */
+    get otherId(): number | null;
     /**
      * This axis's Other bucket, shared by every mark on it that has one.
      *
@@ -308,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.
      *
@@ -331,7 +335,7 @@ export declare class BandScaleState {
     /**
      * Get D3 band scale configured for rendering
      */
-    getBaseScale(axis: string, innerWidthOrHeight: number): ScaleBand<DimValue>;
+    getBaseScale(_axis: string, innerWidthOrHeight: number): ScaleBand<DimValue>;
     /**
      * Update scale domain (for D3 scale)
      */
@@ -360,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
@@ -403,19 +413,22 @@ export declare class BandScaleState {
     /**
      * Where a tick's label sits now, in pixels along the axis: the centre of its
      * category's current slot, so it travels with the bar. Slot 0 is at the start
-     * of the range on x and at the bottom on y, as in the shader and d3's
-     * reversed range. Per frame, O(1).
+     * of the range on both axes: the left on x, the top on y, as in the shader
+     * and d3's range. Per frame, O(1).
      */
-    tickPosition(key: number, rangeSize: number, axis: 'x' | 'y'): number;
+    tickPosition(key: number, rangeSize: number): number;
     /**
      * The same, for a caller that already has the slot.
      *
      * A consumer that has to test the slot first — an SVG label, which must not
      * draw a category the axis is not displaying — would otherwise ask for it
-     * twice per item per frame. The axis flip lives here rather than being
-     * re-derived by such a caller.
+     * twice per item per frame.
+     *
+     * The same on both axes. A y band axis reads top-down, like a list: slot 0
+     * at the top, so a ranking and an explicit domain need no reversing, and
+     * the exit one past the last slot is the end of the list on either axis.
      */
-    slotPosition(slot: number, rangeSize: number, axis: 'x' | 'y'): number;
+    slotPosition(slot: number, rangeSize: number): number;
     /**
      * Centre of a (possibly fractional) slot, measured from the start of the
      * range — the same layout the shader's computeBandLayout uses, so a label
@@ -452,7 +465,7 @@ export declare class BandScaleState {
      * Returns the 0-based index of the band under the cursor, or null if
      * no bands exist.
      */
-    invertScreenToData(screenVal: number, rangeSize: number, isYAxis?: boolean): number | null;
+    invertScreenToData(screenVal: number, rangeSize: number, _isYAxis?: boolean): number | null;
     /**
      * Get all mark extents (for debugging). Ids when the scale has identity.
      */

package/dist/scales/BandScaleState.svelte.js

@@ -327,6 +327,10 @@ export class BandScaleState {
     setOtherId(id) {
         this.#slots.otherId = id;
     }
+    /** This axis's Other bucket id, while a mark on it has one; null otherwise. */
+    get otherId() {
+        return this.#slots.otherId;
+    }
     /**
      * This axis's Other bucket, shared by every mark on it that has one.
      *
@@ -447,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);
         }
     }
     // =========================================================================
@@ -548,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;
         }
@@ -562,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);
@@ -621,8 +627,10 @@ export class BandScaleState {
     /**
      * Get D3 band scale configured for rendering
      */
-    getBaseScale(axis, innerWidthOrHeight) {
-        this.#sharedScale.range(axis === 'x' ? [0, innerWidthOrHeight] : [innerWidthOrHeight, 0]);
+    getBaseScale(_axis, innerWidthOrHeight) {
+        // The same on both axes, not reversed on y: slot 0 is at the top, as in
+        // the shader (slotPosition).
+        this.#sharedScale.range([0, innerWidthOrHeight]);
         if (this.#paddingInner !== null && this.#paddingOuter !== null) {
             this.#sharedScale.paddingInner(this.#paddingInner).paddingOuter(this.#paddingOuter);
         }
@@ -678,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
@@ -759,23 +776,25 @@ export class BandScaleState {
     /**
      * Where a tick's label sits now, in pixels along the axis: the centre of its
      * category's current slot, so it travels with the bar. Slot 0 is at the start
-     * of the range on x and at the bottom on y, as in the shader and d3's
-     * reversed range. Per frame, O(1).
+     * of the range on both axes: the left on x, the top on y, as in the shader
+     * and d3's range. Per frame, O(1).
      */
-    tickPosition(key, rangeSize, axis) {
-        return this.slotPosition(this.tickSlot(key), rangeSize, axis);
+    tickPosition(key, rangeSize) {
+        return this.slotPosition(this.tickSlot(key), rangeSize);
     }
     /**
      * The same, for a caller that already has the slot.
      *
      * A consumer that has to test the slot first — an SVG label, which must not
      * draw a category the axis is not displaying — would otherwise ask for it
-     * twice per item per frame. The axis flip lives here rather than being
-     * re-derived by such a caller.
+     * twice per item per frame.
+     *
+     * The same on both axes. A y band axis reads top-down, like a list: slot 0
+     * at the top, so a ranking and an explicit domain need no reversing, and
+     * the exit one past the last slot is the end of the list on either axis.
      */
-    slotPosition(slot, rangeSize, axis) {
-        const centre = this.slotCenter(slot, rangeSize);
-        return axis === 'y' ? rangeSize - centre : centre;
+    slotPosition(slot, rangeSize) {
+        return this.slotCenter(slot, rangeSize);
     }
     /**
      * Centre of a (possibly fractional) slot, measured from the start of the
@@ -854,7 +873,9 @@ export class BandScaleState {
      * Returns the 0-based index of the band under the cursor, or null if
      * no bands exist.
      */
-    invertScreenToData(screenVal, rangeSize, isYAxis = false) {
+    invertScreenToData(screenVal, rangeSize, 
+    // Band slots run from the start of the range on both axes (slotPosition).
+    _isYAxis = false) {
         const config = this.getConfig();
         const n = config.categoryCount;
         if (n === 0)
@@ -863,10 +884,7 @@ export class BandScaleState {
         if (stepSize === 0)
             return null;
         const offset = config.paddingOuter * stepSize;
-        // GPU band scale renders Y categories bottom-to-top (matching D3),
-        // so flip screen coordinate for Y axis inversion.
-        const pos = isYAxis ? rangeSize - screenVal : screenVal;
-        const bandIndex = Math.floor((pos - offset) / stepSize);
+        const bandIndex = Math.floor((screenVal - offset) / stepSize);
         // Clamped to a WHOLE slot. Mid-transition the count is fractional, so a
         // bare `n - 1` hands back a fraction for a pointer past the last band —
         // and a fractional slot indexes nothing, so idAtSlot and the domain both

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;

package/dist/scales/ChartScales.svelte.js

@@ -55,6 +55,7 @@ export class ChartScales {
         this.gpuCoordinator = config.gpuCoordinator;
         this.#scaleRegistry = config.scaleRegistry;
         this.#getFacetChartIds = config.getFacetChartIds ?? null;
+        this.#entranceGateOff = config.entranceGate?.onOpen(() => this.#markScalesEntered()) ?? null;
         if (!this.#scaleRegistry) {
             console.error('ChartScales initialized without scaleRegistry!');
         }
@@ -271,14 +272,10 @@ export class ChartScales {
                 xScaleConfig.__fitDomain = this.chartId;
             const neededXScale = this.#scaleRegistry.getOrCreateScale(xKey, xConfig.type, xScaleConfig, this.chartId);
             if (this.#xScaleInstance !== neededXScale) {
-                const wasReplacement = !!this.#xScaleInstance;
                 if (this.#xScaleInstance) {
                     this.#scaleRegistry.deregisterChart(this.#xScaleInstance, this.chartId);
                 }
                 this.#xScaleInstance = neededXScale;
-                if (wasReplacement && neededXScale instanceof LinearScaleState) {
-                    neededXScale.zoomInEffect.enabled = false;
-                }
             }
         }
         if (yConfig) {
@@ -290,16 +287,13 @@ export class ChartScales {
                 yScaleConfig.__fitDomain = this.chartId;
             const neededYScale = this.#scaleRegistry.getOrCreateScale(yKey, yConfig.type, yScaleConfig, this.chartId);
             if (this.#yScaleInstance !== neededYScale) {
-                const wasReplacement = !!this.#yScaleInstance;
                 if (this.#yScaleInstance) {
                     this.#scaleRegistry.deregisterChart(this.#yScaleInstance, this.chartId);
                 }
                 this.#yScaleInstance = neededYScale;
-                if (wasReplacement && neededYScale instanceof LinearScaleState) {
-                    neededYScale.zoomInEffect.enabled = false;
-                }
             }
         }
+        this.#markScalesEntered();
     }
     scaleConfigurations = $derived.by(() => {
         try {
@@ -438,6 +432,7 @@ export class ChartScales {
                 this.#scaleRegistry.deregisterChart(scale, this.chartId);
         }
         this.#parallelScaleInstances = next;
+        this.#markScalesEntered();
         this.#parallelAxisOrder = wanted.map((_, i) => i);
         if (next.size > 0)
             this.#ensureReorder().resetSprings();
@@ -764,7 +759,30 @@ export class ChartScales {
             setBinStepMultiplier: (v) => coordinator.setBinStepMultiplier(v)
         };
     }
+    /**
+     * A scale snaps every extent change until a chart drawing it has its marks'
+     * first data in, so the domain is that chart's whole extent when it enters,
+     * and its axes show no ticks before then (the domain is a placeholder).
+     * Marked here when the chart's entrance gate opens, and again whenever the
+     * scale instances change after that.
+     */
+    #entranceGateOff = null;
+    #markScalesEntered() {
+        const gate = this.config.entranceGate;
+        if (gate && !gate.opened)
+            return;
+        for (const scale of [
+            this.#xScaleInstance,
+            this.#yScaleInstance,
+            ...this.#parallelScaleInstances.values()
+        ]) {
+            if (scale instanceof LinearScaleState && !scale.entered)
+                scale.entered = true;
+        }
+    }
     destroy() {
+        this.#entranceGateOff?.();
+        this.#entranceGateOff = null;
         this.#reorder?.destroy();
         this.#reorder = null;
         if (this.#scaleRegistry) {

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

@@ -1,6 +1,6 @@
 import type { RGBA, D3ColorScale } from './color-utils';
 import type { FieldIdentity } from '../query-engine/categorical-identity';
-import type { ColorScaleType } from '../types';
+import type { ColorDomainValue, ColorScaleType } from '../types';
 import type { ScaleRegistry } from './ScaleRegistry.svelte';
 import { type GPUCoordinator } from '../gpu/GPUCoordinator.svelte';
 import type { SlotSource } from '../gpu/identity-slot-packing';
@@ -13,6 +13,10 @@ interface ColorScaleConfig {
     midpoint?: number;
     constant?: number;
     exponent?: number;
+    /** Explicit palette colours, in place of the scheme's. */
+    range?: readonly string[] | null;
+    /** Values pinned to palette positions: pinnedDomain[i] draws range[i]. */
+    pinnedDomain?: readonly ColorDomainValue[] | null;
 }
 /**
  * Reactive state for a GPU-backed color scale.
@@ -118,9 +122,9 @@ export declare class ColorScaleState {
      * the new one and simply mean other categories.
      */
     setIdentity(identity: FieldIdentity): void;
-    /** True once this scale's channel carries dim ids rather than palette indices. */
     /** The field's live id <-> value bijection, once adopted. */
     get identity(): FieldIdentity | null;
+    /** True once this scale's channel carries dim ids rather than palette indices. */
     get hasIdentity(): boolean;
     /**
      * Source value for a channel id — the decode side of the encode the query
@@ -134,6 +138,18 @@ export declare class ColorScaleState {
      * Update the scheme. Triggers GPU re-upload.
      */
     setScheme(newScheme: string): void;
+    /**
+     * Set explicit palette colours and pinned values, or clear them with nulls.
+     * Triggers GPU re-upload.
+     *
+     * The ranks are cleared: they were handed out under the old mapping, and a
+     * new pin means the author has just said which value takes which colour.
+     */
+    setRange(range: readonly string[] | null, pinnedDomain: readonly ColorDomainValue[] | null): void;
+    /** The explicit palette colours, or null for the scheme's. */
+    get range(): readonly string[] | null;
+    /** The pinned values, or null when ranks follow the domain's sorted order. */
+    get pinnedDomain(): readonly ColorDomainValue[] | null;
     /**
      * Update the normalization transform. Triggers GPU re-upload.
      * Called when the user changes the color scale type (e.g., linear → symlog)