@fjader/svelte 0.2.2 → 0.2.4

package/dist/scales/BandScaleState.svelte.js

@@ -47,7 +47,6 @@ export class BandScaleState {
     // =========================================================================
     // SELECTION STATE
     // =========================================================================
-    #activeValues = $state(null); // null = all active, Set = only these active
     // =========================================================================
     // POINTER STATE
     // =========================================================================
@@ -104,21 +103,6 @@ export class BandScaleState {
     setReady() {
         this.ready = true;
     }
-    // =========================================================================
-    // ACTIVE VALUES (selection feedback)
-    // =========================================================================
-    get activeValues() {
-        return this.#activeValues;
-    }
-    setActiveValues(values) {
-        this.#activeValues = values instanceof Set ? values : new Set(values);
-    }
-    clearActiveValues() {
-        this.#activeValues = null;
-    }
-    isActive(value) {
-        return this.#activeValues == null || this.#activeValues.has(value);
-    }
     /**
      * Marks the scale dead. Clears nothing, deliberately.
      *
@@ -186,6 +170,15 @@ export class BandScaleState {
     get sourceField() {
         return this.#sourceField ?? this.name;
     }
+    /**
+     * 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() {
+        // Only while the channel carries ids, as for colour.
+        return this.hasIdentity ? this.#resolver.identity.key || null : null;
+    }
     // =========================================================================
     // FREEZE/DEBOUNCE CONTROL
     // =========================================================================
@@ -334,6 +327,53 @@ 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.
+     *
+     * 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, acquire) {
+        this.#otherHolders.add(holder);
+        if (!this.#other) {
+            const pending = acquire();
+            this.#other = pending;
+            pending.then((other) => {
+                if (this.#other === pending)
+                    this.setOtherId(other.id);
+            }, () => {
+                if (this.#other === pending)
+                    this.#other = null;
+            });
+        }
+        return this.#other;
+    }
+    /**
+     * 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, release) {
+        if (!this.#otherHolders.delete(holder) || this.#otherHolders.size > 0)
+            return;
+        const pending = this.#other;
+        this.#other = null;
+        this.setOtherId(null);
+        pending?.then(release, () => { });
+    }
+    /** The marks holding this axis's Other bucket. */
+    #otherHolders = new Set();
+    /** The bucket they share, while any holds it. */
+    #other = null;
     // -------------------------------------------------------------------------
     // IDENTITY <-> DISPLAY, FOR CPU CONSUMERS
     // -------------------------------------------------------------------------
@@ -585,8 +625,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);
         }
@@ -709,6 +751,9 @@ export 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) {
         void this.#slotFrame;
@@ -720,27 +765,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;
-    }
-    /** Whether a tick's category is outside the current selection. */
-    isTickDimmed(tick) {
-        return tick.value != null && !this.isActive(tick.value);
+    slotPosition(slot, rangeSize) {
+        return this.slotCenter(slot, rangeSize);
     }
     /**
      * Centre of a (possibly fractional) slot, measured from the start of the
@@ -819,7 +862,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)
@@ -828,10 +873,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

@@ -65,8 +65,8 @@ export declare class ChartScales {
     };
     get xScaleState(): ScaleStateInstance | null;
     get yScaleState(): ScaleStateInstance | null;
-    baseXScale: import("d3-scale").ScaleContinuousNumeric<number, number, never> | import("d3-scale").ScaleBand<import("../query-engine/categorical-identity").DimValue>;
-    baseYScale: import("d3-scale").ScaleContinuousNumeric<number, number, never> | import("d3-scale").ScaleBand<import("../query-engine/categorical-identity").DimValue>;
+    baseXScale: import("d3-scale").ScaleBand<import("../query-engine/categorical-identity").DimValue> | import("d3-scale").ScaleContinuousNumeric<number, number, never>;
+    baseYScale: import("d3-scale").ScaleBand<import("../query-engine/categorical-identity").DimValue> | import("d3-scale").ScaleContinuousNumeric<number, number, never>;
     get xScale(): D3Scale | null;
     get yScale(): D3Scale | null;
     get xTargetScale(): D3Scale | null;

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

@@ -25,7 +25,21 @@ export declare class ColorScaleState {
     domain: (string | number)[];
     ready: boolean;
     _version: number;
+    /**
+     * Read by the packer every frame. The rank table covers the ids the field had
+     * when it was built, and the field's identity grows in place: another table
+     * appends categories, and a chart acquiring an Other bucket appends its id,
+     * any chart, since this scale is shared per field. An id past the table's end
+     * reads as unranked and draws transparent, so a grown identity rebuilds it
+     * here, once per growth.
+     */
     get slots(): SlotSource;
+    /**
+     * Reactive: changes whenever the palette ranks are rebuilt, which is also when
+     * identity is adopted. A reader of `identityKey` or `getColor` in a derived
+     * reads this to re-run then.
+     */
+    get ranksRevision(): number;
     /**
      * Called by the packer when this scale's block moves, and told its own base
      * rather than having it written into its config from outside.
@@ -51,9 +65,14 @@ export declare class ColorScaleState {
     setSlotBase(base: number): void;
     constructor(config: ColorScaleConfig, registry: ScaleRegistry, gpuCoordinator: GPUCoordinator | null);
     get field(): 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;
     get scheme(): string;
     get scaleType(): ColorScaleType;
-    get activeValues(): Set<string | number> | null;
     get isOrdinal(): boolean;
     get isContinuous(): boolean;
     /**
@@ -73,9 +92,14 @@ export declare class ColorScaleState {
      */
     get d3Scale(): D3ColorScale | null;
     /**
-     * Unique scale ID for ViewManager registration.
+     * The id the coordinator tracks this scale by, as it does every scale.
+     *
+     * Tracking is what puts the scale in front of the identity slot packer
+     * (see tracked-scales.ts). Without an id, its rank table and selection
+     * activity were never packed: the shader read the channel's dim id as a
+     * palette index, and selection dimming had nothing to read.
      */
-    get scaleId(): string;
+    get id(): string;
     /**
      * Converts raw data into GPU-ready values.
      * - Ordinal: string -> 0-based index (-1 = null/unknown, 0+ = categories)
@@ -95,13 +119,15 @@ export declare class ColorScaleState {
      */
     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;
     get hasIdentity(): boolean;
     /**
      * Source value for a channel id — the decode side of the encode the query
      * performs, for tooltips and legends. Undefined without identity, where the
      * channel carries a palette index and the caller should read the domain.
      */
-    categoryAt(id: number): string | number | undefined;
+    categoryAt(id: number): string | number | null | undefined;
     /** Update the domain. Triggers GPU re-upload. */
     setDomain(newDomain: (string | number)[]): void;
     /**
@@ -139,14 +165,16 @@ export declare class ColorScaleState {
      * Returns NULL_COLOR for values that are unmappable under the current
      * transform (e.g. non-positive values under log), mirroring the GPU shader.
      */
-    getColor(value: string | number): string;
+    getColor(value: string | number | null): string;
     /**
      * Get color as RGBA array (0-1 range).
      */
     getColorRGBA(value: string | number): RGBA;
-    setActiveValues(values: Iterable<string | number>): void;
-    clearActiveValues(): void;
-    isActive(value: string | number): boolean;
+    /**
+     * Charts drawing this scale. Asked of the registry, as BandScaleState does,
+     * so it is current when charts come and go.
+     */
+    get _affectedChartsArray(): string[];
     /**
      * Marks the scale dead. Clears nothing, deliberately — see
      * BandScaleState.destroy for the full argument.

package/dist/scales/ColorScaleState.svelte.js

@@ -2,7 +2,7 @@
 import { scaleOrdinal } from 'd3-scale';
 import { createD3Scale, getOrdinalColors, bakeGradient, bakeInterpolator, bakePalette, getSchemeType, parseColorToRGBA, resolveColorScaleTypes, getResolvedInterpolator, transformTypeToGPU, applyTransform, colorScaleTicks } from './color-utils';
 import { COLOR_RAMP_RESOLUTION } from '../gpu/GPUCoordinator.svelte';
-import { COLOR_CONFIG_BYTES, COLOR_CONFIG_SLOT_BASE_OFFSET, NO_SLOT_TABLE } from '../gpu/ColorScaleShaderLib';
+import { COLOR_CONFIG_BYTES, COLOR_CONFIG_SLOT_BASE_OFFSET, NO_SLOT_TABLE, NULL_COLOR_RANK } from '../gpu/ColorScaleShaderLib';
 /**
  * Reactive state for a GPU-backed color scale.
  *
@@ -14,7 +14,7 @@ export class ColorScaleState {
     #field;
     #registry;
     #gpuCoordinator;
-    #scaleId = crypto.randomUUID(); // Unique ID for ViewManager registration
+    #id = crypto.randomUUID();
     // GPU slot indices (allocated from registry)
     #configSlot = -1;
     #rampSlot = -1; // Used by continuous scales
@@ -31,7 +31,6 @@ export class ColorScaleState {
     // Reactive state
     domain = $state([]);
     ready = $state(false);
-    #activeValues = $state(null); // null = all active, Set = only these active
     // Bumped on any visual-config change (transform type, constant, exponent, scheme).
     // Legend components read this to know when to re-render the gradient.
     _version = $state(0);
@@ -90,9 +89,37 @@ export class ColorScaleState {
      * a change.
      */
     #slots = { count: 0, from: new Float32Array(0), to: new Float32Array(0), t: 1, version: 0 };
+    /**
+     * Read by the packer every frame. The rank table covers the ids the field had
+     * when it was built, and the field's identity grows in place: another table
+     * appends categories, and a chart acquiring an Other bucket appends its id,
+     * any chart, since this scale is shared per field. An id past the table's end
+     * reads as unranked and draws transparent, so a grown identity rebuilds it
+     * here, once per growth.
+     */
     get slots() {
+        const identity = this.#identity;
+        if (identity?.present && identity.version !== this.#ranksVersion)
+            this.#refreshRanks();
         return this.#slots;
     }
+    /** The identity version the rank table was last built from. */
+    #ranksVersion = -1;
+    /**
+     * Bumped whenever the ranks change, so a reader of getColor (a legend's
+     * swatches) re-reads once identity lands. The ranks are a plain Map, and the
+     * domain usually arrives first: without this a legend kept the colours it
+     * computed before there were ranks.
+     */
+    #ranksRevision = $state(0);
+    /**
+     * Reactive: changes whenever the palette ranks are rebuilt, which is also when
+     * identity is adopted. A reader of `identityKey` or `getColor` in a derived
+     * reads this to re-run then.
+     */
+    get ranksRevision() {
+        return this.#ranksRevision;
+    }
     /**
      * Where this scale's block sits in the shared identity slot table. Assigned
      * by the coordinator's packer.
@@ -132,9 +159,18 @@ export class ColorScaleState {
         // Before the scale has a config slot there is nothing to patch; whichever
         // upload path claims one writes the base with the rest of the struct.
         if (this.#configSlot >= 0) {
-            this.#gpuCoordinator?.writeColorConfigSlotBase(this.#configSlot, base);
+            this.#gpuCoordinator?.writeColorConfigSlotBase(this.#configSlot, this.#configSlotBase);
         }
     }
+    /**
+     * The slot base the config carries: this scale's block while its channel
+     * carries ids, NO_SLOT_TABLE while it carries palette indices. The one rule
+     * for both writers (setSlotBase's patch and the full upload), so which wrote
+     * last cannot change what the GPU reads.
+     */
+    get #configSlotBase() {
+        return this.hasIdentity && this.#slotBase >= 0 ? this.#slotBase : NO_SLOT_TABLE;
+    }
     // ViewManager integration - tracks tables this scale has registered columns for
     constructor(config, registry, gpuCoordinator) {
         this.#field = config.field;
@@ -170,15 +206,22 @@ export class ColorScaleState {
     get field() {
         return this.#field;
     }
+    /**
+     * 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() {
+        // Only while the channel carries ids: a key without them would route a
+        // mark to dim by activity the shader cannot read.
+        return this.hasIdentity ? this.#identity.key || null : null;
+    }
     get scheme() {
         return this.#scheme;
     }
     get scaleType() {
         return this.#scaleType;
     }
-    get activeValues() {
-        return this.#activeValues;
-    }
     get isOrdinal() {
         return this.#renderType === 'ordinal';
     }
@@ -208,10 +251,15 @@ export class ColorScaleState {
         return this.#d3Scale;
     }
     /**
-     * Unique scale ID for ViewManager registration.
+     * The id the coordinator tracks this scale by, as it does every scale.
+     *
+     * Tracking is what puts the scale in front of the identity slot packer
+     * (see tracked-scales.ts). Without an id, its rank table and selection
+     * activity were never packed: the shader read the channel's dim id as a
+     * palette index, and selection dimming had nothing to read.
      */
-    get scaleId() {
-        return this.#scaleId;
+    get id() {
+        return this.#id;
     }
     // ============================================================
     // SLOT ALLOCATION
@@ -300,6 +348,10 @@ export class ColorScaleState {
         return [lo, hi];
     }
     #uploadToGPU() {
+        // A destroyed scale's slots may already belong to another scale: a late
+        // upload (identity landing after the chart unmounted) would overwrite them.
+        if (this.#destroyed)
+            return;
         if (!this.#gpuCoordinator) {
             console.warn('[ColorScaleState] No GPU coordinator, skipping upload');
             return;
@@ -388,15 +440,28 @@ export class ColorScaleState {
      */
     setIdentity(identity) {
         this.#warnIfDestroyed('setIdentity');
+        const hadIdentity = this.hasIdentity;
         const previous = this.#identity;
         this.#identity = identity;
         if (previous && previous !== identity && !previous.present) {
             this.#paletteRank.clear();
             this.#nextRank = 0;
         }
+        // Identity landing after the config was uploaded, or going (a reload
+        // empties it). The domain fetch and the identity columns are fetched in
+        // parallel, so either can arrive first; the config's slot base, its palette
+        // size and the CPU scale all depend on whether the channel carries ids,
+        // so a change of that uploads again. The ranks are refreshed here either
+        // way: they are CPU state, needed without a coordinator too.
         this.#refreshRanks();
+        if (hadIdentity !== this.hasIdentity && this.domain.length > 0)
+            this.#uploadToGPU();
     }
     /** True once this scale's channel carries dim ids rather than palette indices. */
+    /** The field's live id <-> value bijection, once adopted. */
+    get identity() {
+        return this.#identity ?? null;
+    }
     get hasIdentity() {
         return this.isOrdinal && (this.#identity?.present ?? false);
     }
@@ -419,10 +484,14 @@ export class ColorScaleState {
         const identity = this.#identity;
         if (!identity?.present)
             return;
+        this.#ranksVersion = identity.version;
         for (const value of this.domain) {
             const id = identity.ids.get(value);
             if (id === undefined || this.#paletteRank.has(id))
                 continue;
+            // The NULL category takes no palette slot (see below).
+            if (id === identity.nullId)
+                continue;
             this.#paletteRank.set(id, this.#nextRank++);
         }
         const table = new Float32Array(identity.values.length);
@@ -431,6 +500,16 @@ export class ColorScaleState {
             if (id >= 0 && id < table.length)
                 table[id] = rank;
         }
+        // The NULL category and the Other buckets draw the null colour: no palette
+        // slot, so they read as missing data or "the rest" and shift no category's
+        // colour. Not -1, which the shader draws transparent: a category outside
+        // this scale's domain.
+        if (identity.nullId !== null)
+            table[identity.nullId] = NULL_COLOR_RANK;
+        for (const id of identity.synthetic)
+            if (id < table.length)
+                table[id] = NULL_COLOR_RANK;
+        this.#ranksRevision++;
         const slots = this.#slots;
         slots.from = table;
         slots.to = table;
@@ -476,9 +555,8 @@ export class ColorScaleState {
             return undefined;
         return this.#identity.values[id];
     }
+    /** Called from #uploadToGPU only, which has refreshed the ranks. */
     #uploadOrdinal() {
-        // New categories in the domain need ranks before the palette is sized.
-        this.#refreshRanks();
         // Bake and upload palette
         const paletteData = bakePalette(this.#scheme, { reverse: this.#reverse });
         this.#gpuCoordinator.writeColorPalette(this.#paletteSlot, paletteData);
@@ -497,7 +575,7 @@ export class ColorScaleState {
             type: 0, // ORDINAL
             paletteOffset: this.#paletteSlot * 32,
             paletteSize: Math.min(Math.max(rankSpace, 1), 32),
-            slotBase: this.hasIdentity ? this.#slotBase : undefined
+            slotBase: this.#configSlotBase
         });
         this.#gpuCoordinator.writeColorConfig(this.#configSlot, config);
     }
@@ -660,6 +738,14 @@ export class ColorScaleState {
      * transform (e.g. non-positive values under log), mirroring the GPU shader.
      */
     getColor(value) {
+        // With palette ranks, the colour is exactly the shader's: value -> id ->
+        // rank -> palette, and the null colour for the NULL category and the Other
+        // buckets. Not through the d3 scale, whose domain is stringified: a null
+        // (or a number) would miss it, and d3 would hand the value the next
+        // palette colour.
+        void this.#ranksRevision;
+        if (this.#hasRanks())
+            return this.#rankedColor(value);
         if (!this.#d3Scale)
             return '#000000';
         if (this.#transformType === 'log' && typeof value === 'number' && value <= 0) {
@@ -667,6 +753,18 @@ export class ColorScaleState {
         }
         return this.#d3Scale(value);
     }
+    #rankedColor(value) {
+        const identity = this.#identity;
+        const id = identity.ids.get(value);
+        const rank = id === undefined ? undefined : this.#paletteRank.get(id);
+        if (rank === undefined)
+            return ColorScaleState.NULL_COLOR;
+        let colors = getOrdinalColors(this.#scheme) ?? [];
+        if (this.#reverse)
+            colors = [...colors].reverse();
+        // Same wrap the shader applies, so an over-32 palette agrees too.
+        return colors.length ? colors[rank % colors.length] : ColorScaleState.NULL_COLOR;
+    }
     /**
      * Get color as RGBA array (0-1 range).
      */
@@ -674,18 +772,14 @@ export class ColorScaleState {
         const cssColor = this.getColor(value);
         return parseColorToRGBA(cssColor);
     }
-    // ============================================================
-    // ACTIVE VALUES (selection feedback)
-    // ============================================================
-    setActiveValues(values) {
-        this.#activeValues = values instanceof Set ? values : new Set(values);
-    }
-    clearActiveValues() {
-        this.#activeValues = null;
-    }
-    isActive(value) {
-        return this.#activeValues == null || this.#activeValues.has(value);
+    /**
+     * Charts drawing this scale. Asked of the registry, as BandScaleState does,
+     * so it is current when charts come and go.
+     */
+    get _affectedChartsArray() {
+        return this.#registry?.chartsUsing(this) ?? ColorScaleState.#noCharts;
     }
+    static #noCharts = [];
     // ============================================================
     // CLEANUP
     // ============================================================

package/dist/scales/DomainResolver.d.ts

@@ -141,6 +141,8 @@ export declare class DomainResolver {
     channelValueFor(value: DimValue, displayed: readonly DimValue[]): number | null;
     /** True once this field's dim exists and holds at least one value. */
     get hasIdentity(): boolean;
+    /** The dim adopted last; a different object after a reload. */
+    get identity(): FieldIdentity | null;
     /** How many ids the dim holds — the width of a slot table over it. */
     get idCount(): number;
     /** How many marks have registered. */

package/dist/scales/DomainResolver.js

@@ -188,17 +188,18 @@ export class DomainResolver {
         // #extents encodes at the boundary, which is the whole point of the two
         // registration methods, so its input was already ids that had passed the
         // same check, and the list it was given had just been deduplicated. Its
-        // range check is subsumed by the `value == null` test below, which drops
-        // an id past the end, a negative one and a non-integer one alike, because
-        // all three index the value array to undefined.
+        // range check is subsumed by the `value === undefined` test below, which
+        // drops an id past the end, a negative one and a non-integer one alike,
+        // because all three index the value array to undefined. Not `== null`:
+        // the NULL category's value IS null, and it is a category like any other.
         //
         // An id with no value is dropped from the IDS, before either projection.
         // Filtering only the values would shorten the value list without
         // shortening the permutation, and the two would disagree with the band
         // index space d3 and the shader's categoryCount use — by one, with
-        // nothing failing. Unreachable today (the dim has no NULL values and
-        // synthetic rows carry a label), which is why the two are built together
-        // rather than checked against each other.
+        // nothing failing. Unreachable today (every dim row has a value: a real
+        // one, a synthetic row's label, or the NULL category's null), which is
+        // why the two are built together rather than checked against each other.
         const seen = new Set();
         const orderedIds = [];
         const resolved = [];
@@ -214,7 +215,7 @@ export class DomainResolver {
                     continue;
                 }
                 const value = values[category];
-                if (value == null)
+                if (value === undefined)
                     continue;
                 orderedIds.push(category);
                 resolved.push(value);
@@ -293,7 +294,9 @@ export class DomainResolver {
         const out = [];
         const seen = new Set();
         for (const item of items) {
-            if (item == null)
+            // A value of null is the NULL category, which `ids` maps to its id; an
+            // encoded null is no id at all.
+            if (item === undefined || (encoded && item === null))
                 continue;
             const id = encoded ? item : identity.ids.get(item);
             if (id === undefined || !Number.isInteger(id) || id < 0 || id >= limit)
@@ -371,6 +374,10 @@ export class DomainResolver {
     get hasIdentity() {
         return this.#identity?.present ?? false;
     }
+    /** The dim adopted last; a different object after a reload. */
+    get identity() {
+        return this.#identity;
+    }
     /** How many ids the dim holds — the width of a slot table over it. */
     get idCount() {
         return this.#identity?.values.length ?? 0;

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

@@ -73,6 +73,15 @@ export declare class ScaleRegistry {
      * a scale this registry has never seen.
      */
     chartsUsing(scale: AnyScaleState): string[];
+    /**
+     * Fill `out` with every chart drawing a scale on the categorical field
+     * `key` (by identity key), each once: the charts a selection fade on that
+     * field redraws. A superset of the charts whose marks read the field's
+     * activity, since every such mark draws through a scale on it; the extra
+     * charts (other groups, marks holding the scale without reading it) redraw
+     * for the 0.25 s of a fade. Read on every frame a fade runs.
+     */
+    chartsDrawingField(key: string, out: string[]): string[];
     deregisterChart(scale: AnyScaleState, chartId: string): void;
     removeChartUsage(chartId: string): void;
     _removeScaleFromStorage(scaleInstance: AnyScaleState): void;