@fjader/svelte 0.2.2 → 0.2.4

package/dist/query-engine/preagg/plan.js

@@ -12,7 +12,7 @@
  * License; see NOTICE.
  */
 import { isAggregateExpression, isNode, collectColumns, column, and, isBetween, literal, Query, sql as sqlTag } from '@uwdata/mosaic-sql';
-import { togglePredicate } from '../toggle-predicate';
+import { BITMAP_MIN_IDS, idBitmapPredicate, togglePredicate } from '../toggle-predicate';
 import { rewriteForPreagg, buildBinExpr, binsFineEnough, BIN_WINDOW_MARGIN } from '../sufficient-statistics';
 import { assembleQuery, castNumeric, castReal } from '../../components/marks/lifecycle/query-builder';
 /**
@@ -37,6 +37,11 @@ export function planPreagg(descriptor, dims, identity) {
     const { parts, table, baseTable, schema } = descriptor;
     if (!parts.hasAggregates && !parts.hasWindowAggregates)
         return null;
+    // A having() on a preagg table would count its groups, not the source rows, and
+    // return the wrong rows without an error. The built-in transforms add none; see
+    // TransformCompiler.hasHaving for why, and for what supporting it would take.
+    if (descriptor.transformCompiler.hasHaving())
+        return null;
     // Analyze selectDef for preagg compatibility
     const analysis = rewriteForPreagg(parts.selectDef, parts.passthroughChannels);
     if (!analysis)
@@ -74,7 +79,8 @@ export function planPreagg(descriptor, dims, identity) {
             activeMeta.push({ kind: 'value', field, column: channel, byId: true });
             return;
         }
-        // One more group for -1: NULL, or a value the dim does not hold.
+        // One more group for -1: a value the dim does not hold yet. NULL has an id
+        // of its own, counted in the values.
         const idGroups = identity.values(field).length + 1;
         if (identity.dimCovers(field, baseTable)) {
             // Case 2.
@@ -114,6 +120,7 @@ export function planPreagg(descriptor, dims, identity) {
             groupby: [...preaggGroupBy, ...activeGroupBy],
             // Sorted by bin columns for fast range scans
             orderby: binOrder,
+            where: descriptor.transformCompiler.rowFilters(),
             joins
         },
         outputSelect,
@@ -217,16 +224,16 @@ export function estimateGroups(markKeys, activeKeys) {
  * mismatch the table's SQL is rebuilt from the current clauses and compared.
  * Once that fails, frames that still see the same clauses skip the rebuild.
  */
-export function bakedClausesHold(markId, selection, state) {
+export function bakedClausesHold(route, selection, state) {
     const { basis } = state;
     const { activeSourceId } = basis;
-    if (selection.bakedClausesMatch(markId, activeSourceId, basis.bakedClauses))
+    if (selection.bakedClausesMatch(route, activeSourceId, basis.bakedClauses))
         return true;
-    if (state.mismatch && selection.bakedClausesMatch(markId, activeSourceId, state.mismatch)) {
+    if (state.mismatch && selection.bakedClausesMatch(route, activeSourceId, state.mismatch)) {
         return false;
     }
-    const current = selection.bakedClauses(markId, activeSourceId);
-    const sql = preaggSelectSQL(state.creation, selection.bakedPredicates(markId, activeSourceId));
+    const current = selection.bakedClauses(route, activeSourceId);
+    const sql = preaggSelectSQL(state.creation, selection.bakedPredicates(route, activeSourceId));
     if (sql === state.sql) {
         basis.bakedClauses = current;
         state.mismatch = null;
@@ -241,15 +248,16 @@ export function bakedClausesHold(markId, selection, state) {
  * Builds modified QueryParts from the stored outputSelect + bin filters,
  * then delegates to assembleQuery().
  */
-export function preaggQuerySQL(markId, descriptor, selection, preagg, params, identity) {
+export function preaggQuerySQL(route, descriptor, selection, preagg, params, identity) {
     const { activeMeta, outputSelect, windowChannels } = preagg;
     const { parts, transformCompiler } = descriptor;
     // --- The active source's clause as a filter on the active columns. None
-    // when it has no clause (an empty toggle: every category) or excludes
-    // this mark.
+    // when it has no clause (an empty toggle: every category) or does not
+    // filter this mark.
     const filters = [];
-    const clause = selection.get(preagg.basis.activeSourceId);
-    if (clause && !clause.excludeMarkIds.has(markId)) {
+    const activeSourceId = preagg.basis.activeSourceId;
+    const clause = selection.get(activeSourceId);
+    if (clause && selection.applies(activeSourceId, clause, route)) {
         // A drag frame runs this per mark: nothing below allocates for a brush
         // beyond its filter, so the value arrays are created only when needed.
         let binCount = 0;
@@ -278,8 +286,9 @@ export function preaggQuerySQL(markId, descriptor, selection, preagg, params, id
         }
         if (valueExprs && valueMeta) {
             // A toggle's clause holds tuples in its field order. Id columns
-            // filter by id; a value with no id (NULL, or not in the dim) cannot
-            // be expressed, so this query goes to the base table instead.
+            // filter by id (the NULL category has one); a value with no id (not in
+            // the dim yet) cannot be expressed, so this query goes to the base
+            // table instead.
             const tuples = [];
             for (const tuple of clause.value) {
                 const mapped = [];
@@ -292,7 +301,17 @@ export function preaggQuerySQL(markId, descriptor, selection, preagg, params, id
                 }
                 tuples.push(mapped);
             }
-            filters.push(togglePredicate(valueExprs, tuples));
+            // One field by id, and many of them (a click on a large Other): a
+            // constant-size bitmap rather than a long IN list, which DuckDB spends
+            // most of its time parsing. Measured on a preagg table: 1 ms against
+            // 20 ms for IN of 9 000 ids.
+            const only = valueMeta.length === 1 ? valueMeta[0] : null;
+            if (only?.byId && tuples.length > BITMAP_MIN_IDS) {
+                filters.push(idBitmapPredicate(valueExprs[0], tuples.map((t) => t[0]), identity.identity(only.field).values.length));
+            }
+            else {
+                filters.push(togglePredicate(valueExprs, tuples));
+            }
         }
     }
     // --- Build selectDef: CAST recombined aggregates; dimensions are already
@@ -322,13 +341,19 @@ export function preaggQuerySQL(markId, descriptor, selection, preagg, params, id
         hasSQLTransforms: parts.hasSQLTransforms,
         orderChannels: parts.orderChannels,
         aliasMap: parts.aliasMap,
-        passthroughChannels: parts.passthroughChannels
+        passthroughChannels: parts.passthroughChannels,
+        // nulls="drop", read through this select: each dropped channel is a group
+        // key, so the table keeps NULL as its own group, and dropping that group
+        // here removes exactly what the base scan would have left out.
+        nullDrops: parts.nullDrops
     };
     return assembleQuery({
         table: preagg.table,
         parts: preaggParts,
         filter: filters,
         transformCompiler,
+        // The table was built with them.
+        skipRowFilters: true,
         limit: params.limit,
         window: windowChannels ? { channels: windowChannels, cteName: '__preagg_cte' } : null
     }).toString();
@@ -336,8 +361,9 @@ export function preaggQuerySQL(markId, descriptor, selection, preagg, params, id
 /** A preagg table's SELECT. Build and validity check share it, so equal SQL means an equal table. */
 export function preaggSelectSQL(creation, filters) {
     const query = Query.from(creation.table).select(creation.select).groupby(creation.groupby);
-    if (filters.length > 0)
-        query.where(and(filters));
+    const where = [...creation.where, ...filters];
+    if (where.length > 0)
+        query.where(and(where));
     if (creation.joins.length === 0)
         return query.orderby(creation.orderby).toString();
     // Map fields grouped by value to their ids on the grouped result: a join

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.
@@ -9,8 +9,47 @@ import { and as sqlAnd, isIn, isNotDistinct, literal, or } from '@uwdata/mosaic-
  */
 export function togglePredicate(exprs, tuples) {
     if (exprs.length === 1) {
-        return isIn(exprs[0], tuples.map((t) => literal(t[0])));
+        // NULL is a category, but `IN (…, NULL)` never matches it: NULL = NULL is
+        // not true. It goes beside the list as IS NULL instead.
+        const values = tuples.map((t) => t[0]);
+        const real = values.filter((v) => v !== null);
+        const hasNull = real.length < values.length;
+        const inList = real.length > 0
+            ? isIn(exprs[0], real.map((v) => literal(v)))
+            : null;
+        const isNull = hasNull ? isNotDistinct(exprs[0], literal(null)) : null;
+        if (inList && isNull)
+            return or([inList, isNull]);
+        return inList ?? isNull ?? isIn(exprs[0], []);
     }
     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

@@ -0,0 +1,103 @@
+import { TransitionClock, type ClockLoop } from '../animation';
+/**
+ * Stiffness for a selection fade: ~0.25 s to settle, against ~0.32 s for a data
+ * transition (TRANSITION_STIFFNESS, 240). A click should feel immediate; the
+ * charts it filters take their own time to re-query and morph.
+ */
+export declare const SELECTION_STIFFNESS = 400;
+/**
+ * How visible an inactive category is, by default: marks are drawn at this
+ * opacity (the shaders' SELECTION_DIM_STRENGTH is 1 - this), and
+ * band labels fade to it.
+ */
+export declare const DEFAULT_INACTIVE_OPACITY = 0.25;
+/**
+ * How visible a category is for its activity: `inactiveOpacity` when
+ * unselected, 1 when selected, and in between mid-fade.
+ *
+ * The CPU twin of the shaders' `selectionDim`, which computes the same thing as
+ * `1 - dimStrength * (1 - activity)` with `dimStrength = 1 - inactiveOpacity`.
+ * Band labels and legend entries use this, so they match the marks.
+ */
+export declare function selectionOpacity(activity: number, inactiveOpacity?: number): number;
+/**
+ * Which categories of a scale are selected, and how far each one has faded.
+ *
+ * One float per identity id: 1 active, 0 inactive. A categorical scale owns one
+ * of these beside its slots, and the shaders read it through the same id they
+ * already resolve to a slot, so every mark drawn against the scale dims its
+ * inactive categories without knowing whether it is the source of the
+ * selection, filtered by it, or outside the filter group.
+ *
+ * The same shape as SlotTransition, on its own clock: `from` and `to` are the
+ * two ends of the fade, the value NOW is `mix(from, to, t)`, the GPU computes it
+ * for every id, and `activityOf` for the few a CPU consumer asks about. A
+ * SEPARATE clock from the slots', because a click changes what is selected
+ * without changing any data, and a data update has nothing to do with dimming.
+ * One `t` for every id, not a spring per category: everything fading because of
+ * one click arrives together, and there is one moment of rest.
+ */
+export declare class ActivityTable {
+    #private;
+    /**
+     * Bumped whenever `from` or `to` change: a selection, a resize, a settle. The
+     * packer compares this rather than the contents, so a frame where only `t`
+     * moved uploads nothing.
+     */
+    version: number;
+    readonly clock: TransitionClock;
+    /**
+     * `charts` is required: the loop redraws only the charts a clock names, so a
+     * fade whose clock named none would animate without anything redrawing it.
+     * `loop` is null in unit tests and before a coordinator exists, and then a
+     * fade lands at once. `onFrame` is called for every driven frame and once
+     * more at rest, for CPU consumers such as axis labels.
+     */
+    constructor(loop: ClockLoop | null, options: {
+        charts: () => string[];
+        onFrame?: () => void;
+        stiffness?: number;
+    });
+    /** How many ids the table covers. */
+    get count(): number;
+    get from(): Float32Array;
+    get to(): Float32Array;
+    /** Extrapolated for the frame being drawn. 1 when settled. */
+    get t(): number;
+    /** True while the clock is in the loop. */
+    get isAnimating(): boolean;
+    /**
+     * How active one id is now, 0..1. An id outside the table is fully active,
+     * the same answer the shader gives for an id past the block's count.
+     */
+    activityOf(id: number): number;
+    /**
+     * Cover `count` ids. Existing ids keep their fade; new ones snap to their
+     * state rather than fading in.
+     *
+     * `active` is the selection the new ids join, as ids: null for none, so
+     * every new id is active. Without it, a new id is inactive while something
+     * is selected, since a category that did not exist when the selection was
+     * made is not part of it. Passing it matters when the selection was made
+     * before the ids existed (before identity landed, or across a reload): the
+     * table has not seen it, and a new id it names must start selected rather
+     * than fade in from 0, and one it does not name must start dim rather than
+     * 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, 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.
+     */
+    setActive(ids: Iterable<number>): void;
+    /** Nothing selected: every id fades back to active. */
+    clear(): void;
+    /** Leave the loop, for an owner being torn down. Later changes land at once. */
+    destroy(): void;
+}

package/dist/scales/ActivityTable.js

@@ -0,0 +1,220 @@
+import { TransitionClock } from '../animation';
+/**
+ * Stiffness for a selection fade: ~0.25 s to settle, against ~0.32 s for a data
+ * transition (TRANSITION_STIFFNESS, 240). A click should feel immediate; the
+ * charts it filters take their own time to re-query and morph.
+ */
+export const SELECTION_STIFFNESS = 400;
+/**
+ * How visible an inactive category is, by default: marks are drawn at this
+ * opacity (the shaders' SELECTION_DIM_STRENGTH is 1 - this), and
+ * band labels fade to it.
+ */
+export const DEFAULT_INACTIVE_OPACITY = 0.25;
+/**
+ * How visible a category is for its activity: `inactiveOpacity` when
+ * unselected, 1 when selected, and in between mid-fade.
+ *
+ * The CPU twin of the shaders' `selectionDim`, which computes the same thing as
+ * `1 - dimStrength * (1 - activity)` with `dimStrength = 1 - inactiveOpacity`.
+ * Band labels and legend entries use this, so they match the marks.
+ */
+export function selectionOpacity(activity, inactiveOpacity = DEFAULT_INACTIVE_OPACITY) {
+    return inactiveOpacity + (1 - inactiveOpacity) * activity;
+}
+/**
+ * Which categories of a scale are selected, and how far each one has faded.
+ *
+ * One float per identity id: 1 active, 0 inactive. A categorical scale owns one
+ * of these beside its slots, and the shaders read it through the same id they
+ * already resolve to a slot, so every mark drawn against the scale dims its
+ * inactive categories without knowing whether it is the source of the
+ * selection, filtered by it, or outside the filter group.
+ *
+ * The same shape as SlotTransition, on its own clock: `from` and `to` are the
+ * two ends of the fade, the value NOW is `mix(from, to, t)`, the GPU computes it
+ * for every id, and `activityOf` for the few a CPU consumer asks about. A
+ * SEPARATE clock from the slots', because a click changes what is selected
+ * without changing any data, and a data update has nothing to do with dimming.
+ * One `t` for every id, not a spring per category: everything fading because of
+ * one click arrives together, and there is one moment of rest.
+ */
+export class ActivityTable {
+    #from = new Float32Array(0);
+    #to = new Float32Array(0);
+    /**
+     * Where a new selection is computed before it is compared with `to`. Reused,
+     * because `setActive` is called on every filter update, and most of those
+     * (every brush move on some other field) change nothing here.
+     */
+    #scratch = new Float32Array(0);
+    /** Whether some categories are selected, which decides what a new id starts as. */
+    #selecting = false;
+    /**
+     * Bumped whenever `from` or `to` change: a selection, a resize, a settle. The
+     * packer compares this rather than the contents, so a frame where only `t`
+     * moved uploads nothing.
+     */
+    version = 0;
+    clock;
+    #onFrame;
+    /**
+     * `charts` is required: the loop redraws only the charts a clock names, so a
+     * fade whose clock named none would animate without anything redrawing it.
+     * `loop` is null in unit tests and before a coordinator exists, and then a
+     * fade lands at once. `onFrame` is called for every driven frame and once
+     * more at rest, for CPU consumers such as axis labels.
+     */
+    constructor(loop, options) {
+        this.#onFrame = options.onFrame ?? null;
+        this.clock = new TransitionClock({
+            loop,
+            charts: options.charts,
+            stiffness: options.stiffness ?? SELECTION_STIFFNESS,
+            onRest: () => this.#onClockRest(),
+            onFrame: this.#onFrame ?? undefined
+        });
+    }
+    /** How many ids the table covers. */
+    get count() {
+        return this.#to.length;
+    }
+    get from() {
+        return this.#from;
+    }
+    get to() {
+        return this.#to;
+    }
+    /** Extrapolated for the frame being drawn. 1 when settled. */
+    get t() {
+        return this.clock.t;
+    }
+    /** True while the clock is in the loop. */
+    get isAnimating() {
+        return this.clock.running;
+    }
+    /**
+     * How active one id is now, 0..1. An id outside the table is fully active,
+     * the same answer the shader gives for an id past the block's count.
+     */
+    activityOf(id) {
+        const f = this.#from[id];
+        if (f === undefined)
+            return 1;
+        return f + (this.#to[id] - f) * this.clock.t;
+    }
+    /**
+     * Cover `count` ids. Existing ids keep their fade; new ones snap to their
+     * state rather than fading in.
+     *
+     * `active` is the selection the new ids join, as ids: null for none, so
+     * every new id is active. Without it, a new id is inactive while something
+     * is selected, since a category that did not exist when the selection was
+     * made is not part of it. Passing it matters when the selection was made
+     * before the ids existed (before identity landed, or across a reload): the
+     * table has not seen it, and a new id it names must start selected rather
+     * than fade in from 0, and one it does not name must start dim rather than
+     * 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, trailing = false) {
+        if (count === this.#to.length)
+            return;
+        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) => {
+            const next = new Float32Array(count);
+            next.fill(fill);
+            next.set(old.subarray(0, keep), 0);
+            if (active) {
+                for (const id of active)
+                    if (id >= keep && id < ids)
+                        next[id] = 1;
+            }
+            if (tail)
+                next[count - 1] = old[oldLength - 1];
+            return next;
+        };
+        this.#from = grown(this.#from);
+        this.#to = grown(this.#to);
+        this.#scratch = new Float32Array(count);
+        this.version++;
+    }
+    /**
+     * 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.
+     */
+    setActive(ids) {
+        const next = this.#scratch;
+        next.fill(0);
+        for (const id of ids) {
+            if (id >= 0 && id < next.length)
+                next[id] = 1;
+        }
+        this.#selecting = true;
+        this.#retarget(next);
+    }
+    /** Nothing selected: every id fades back to active. */
+    clear() {
+        const next = this.#scratch;
+        next.fill(1);
+        this.#selecting = false;
+        this.#retarget(next);
+    }
+    /** Leave the loop, for an owner being torn down. Later changes land at once. */
+    destroy() {
+        this.clock.stop();
+    }
+    /**
+     * Fold, point every id at its new state, and wake the loop.
+     *
+     * Returns early when `next` equals `to`: the fade already in flight (or the
+     * rest already reached) is headed exactly there, and restarting it would
+     * re-fold and bump the version for nothing, on every filter update.
+     */
+    #retarget(next) {
+        const from = this.#from;
+        const to = this.#to;
+        let changed = false;
+        for (let id = 0; id < to.length; id++) {
+            if (to[id] !== next[id]) {
+                changed = true;
+                break;
+            }
+        }
+        if (!changed)
+            return;
+        // THE FOLD: every id continues from where it is now, so a click landing
+        // mid-fade reverses or redirects it in place instead of jumping.
+        const t = this.clock.t;
+        for (let id = 0; id < to.length; id++) {
+            from[id] += (to[id] - from[id]) * t;
+            to[id] = next[id];
+        }
+        this.clock.restart();
+        this.version++;
+    }
+    /**
+     * Land exactly on `to`. A spring rests at an epsilon, and a table left at
+     * 0.0003 would start its next fold from a value that was never a state.
+     */
+    #settle() {
+        this.clock.settle();
+        this.#from.set(this.#to);
+    }
+    #onClockRest() {
+        this.#settle();
+        this.version++;
+        // The last frame, at exactly t = 1, which the loop's final frame was not.
+        this.#onFrame?.();
+    }
+}

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

@@ -1,5 +1,5 @@
 import type { ScaleBand } from 'd3-scale';
-import type { DimValue, FieldIdentity } from '../query-engine/categorical-identity';
+import type { DimValue, FieldIdentity, SyntheticId } from '../query-engine/categorical-identity';
 import type { ClockLoop } from '../animation';
 import { type BandSlots } from './SlotTransition';
 /**
@@ -77,10 +77,6 @@ export declare class BandScaleState {
     currentDataPoint: number | null;
     constructor(name: string, domain?: DimValue[], config?: BandScaleConfig);
     setReady(): void;
-    get activeValues(): Set<DimValue> | null;
-    setActiveValues(values: Iterable<DimValue>): void;
-    clearActiveValues(): void;
-    isActive(value: DimValue): boolean;
     /**
      * Marks the scale dead. Clears nothing, deliberately.
      *
@@ -121,6 +117,12 @@ export declare class BandScaleState {
      * where name is "__facet__species" but sourceField is "species").
      */
     get sourceField(): string;
+    /**
+     * The identity key of the dim this scale adopted, or null before it has one.
+     * Selection activity is kept per identity key, so this is what the packer
+     * points the scale's block at.
+     */
+    get identityKey(): string | null;
     /**
      * Enable or disable scale updates
      * When disabled, domain is frozen at current state
@@ -209,6 +211,26 @@ 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.
+     *
+     * One id per band scale, not per mark or per chart: marks share a band scale
+     * only when they agree on what Other is — the scale's key carries the table
+     * and the category-reducing transform (its `transformKey`), N included — so
+     * everything drawn on one axis lines up in one Other band. A bar and its
+     * value labels, or two charts with the identical topN, share it.
+     *
+     * Reference-counted by mark id. The first holder acquires; holders arriving
+     * while that is in flight share it; the last to release gives it back.
+     */
+    retainOther(holder: string, acquire: () => Promise<SyntheticId>): Promise<SyntheticId>;
+    /**
+     * Drop `holder`'s claim on the Other bucket. The last one out hands the id to
+     * `release` — once the acquire has landed, if it is still in flight.
+     */
+    releaseOther(holder: string, release: (other: SyntheticId) => void): void;
     /**
      * Identity id currently displayed at `slot`, or null when the slot holds no
      * category. Use this to compare a display position — what invertScreenToData
@@ -311,7 +333,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)
      */
@@ -375,26 +397,30 @@ export declare class BandScaleState {
      * so it fades out over the half slot before that centre reaches the axis end
      * (the animated count), and is gone from there; the same at the start. An
      * entrant's label appears as its band crosses in.
+     *
+     * A selection's dimming is not here: it belongs to the filter groups of the
+     * marks the axis labels, so the axis multiplies it in (BandAxisTicks).
      */
     tickOpacity(key: number): number;
     /**
      * 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;
-    /** Whether a tick's category is outside the current selection. */
-    isTickDimmed(tick: BandTick): boolean;
+    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
@@ -431,7 +457,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.
      */