@fjader/svelte 0.2.2 → 0.2.4

package/dist/gpu/identity-slot-packing.js

@@ -18,12 +18,45 @@
  * on it. It is a pure function over plain arrays and maps, which is
  * what it should have been.
  *
- * Layout: index 0 is a permanent zero-length block, then one block per scale of
- * `[count, slot0, slot1, ...]`. The count header makes each block
- * self-describing, so the shader rejects an id past this scale's end instead of
- * reading into the next scale's slots — ids and the slot table can disagree
- * transiently while a dim appends. Budget is therefore
- * `capacity - 1 - (1 per scale)` slots.
+ * LAYOUT. Index 0 is a permanent empty block `[0, 0, 0]`. Then one SLOT
+ * block per scale, then one ACTIVITY block per live categorical field:
+ *
+ *   scale block: [count, actRef, n, slot0 … slot(count-1)]
+ *   field block: [group 0: act0 … act(n-1), group 1: act0 … act(n-1), …]
+ *
+ * Slots come first so that when the buffer runs out it is activity that is
+ * lost (a mark draws undimmed), never an axis. A field has a block while a
+ * scale draws it, selected on or not, and a field no chart draws any more
+ * frees its space. Tying the block to the selection instead saved that space
+ * on pages with nothing selected, but every select and clear then moved the
+ * block and rewrote every scale block pointing at it, slots included:
+ * measured at about 105000 floats uploaded per click for 20 scales on a
+ * 5000-category field, against 5000 when the block stays.
+ *
+ * KNOWN LIMIT: a field block that does not fit leaves a selection on that
+ * field doing nothing for the marks that dim by it. Routing (the mark's reads,
+ * see activity-reads.ts) still sends them to dim rather than filter, and their
+ * shader finds no activity. Routing does not ask the packer whether a field
+ * got a block, which would tie the query layer to the GPU layout; the packer
+ * warns instead, on load. It takes fields of tens of thousands of ids across
+ * several groups to reach. A buffer that grows on demand is the real fix.
+ *
+ * A scale block's header says how many ids its slots cover (`count`), where its
+ * field's activity block starts (`actRef`) and how many ids that block covers
+ * (`n`). The count is what makes a block self-describing, so the shader rejects
+ * an id past this scale's end instead of reading into the next scale's slots —
+ * ids and the slot table can disagree transiently while a dim appends.
+ *
+ * ACTIVITY says how selected each id is in each filter group (1 active, 0
+ * inactive; see FieldActivity). It belongs to the field, not to the scale:
+ * every scale on one field reads the same block, a mark choosing its group's
+ * half by its group index. So a click rewrites and resolves one half of one
+ * field block, however many scales draw that field. The header comes first so
+ * the shader finds `actRef` and `n` without reading `count`: the activity read
+ * is two dependent loads, as it was when the activity sat after the slots. No
+ * mark holds `actRef`; the packer writes it in the same pass that moves the
+ * field block, so it cannot go stale. A scale with no field to dim points at
+ * the empty block, where `n` is 0 and every id is active.
  *
  * TWO buffers share one set of offsets: `from` is where each id's current
  * transition started and `to` where it is going, and the resolve kernel writes
@@ -31,128 +64,276 @@
  * bindings rather than two runs in one buffer, so the halves line up at the
  * same base and one dispatch per block covers both.
  *
- * `t` is not in the buffers. It is PER SCALE — each band scale has its own
- * driver — and reaches the kernel as an immediate on that scale's dispatch, so
- * a frame where only `t` moved uploads nothing at all.
+ * `t` is not in the buffers. It is per scale (its data clock) and per field
+ * half (that group's selection clock), and reaches the kernel as an immediate
+ * on that range's dispatch, so a frame where only `t` moved uploads nothing.
  */
 /**
  * Floats GLOBALLY across every band and point scale on the page, headers
- * included.
+ * included, and every live field's activity.
  *
  * No longer a binding limit: the tables are storage buffers, bound only to the
- * resolve pass, and the render stages read one resolved storage buffer. The
- * number is left over from when they were 64 KB uniforms, and making the
- * allocation grow on demand (recreate the buffers, rebuild the bind groups) is
- * what would retire it.
+ * resolve pass, and the render stages read one resolved storage buffer. Making
+ * the allocation grow on demand (recreate the buffers, rebuild the bind groups)
+ * is what would retire it.
+ *
+ * Each scale takes `3 + count`; each live field `n × groups`. 65536 fits a
+ * 5000-category field selected on across 3 groups (15000) with its scales
+ * (about 5000 each) several times over. It costs 256 KB per buffer, 768 KB for
+ * the three; the resolve pass dispatches per block, sized by the block, so a
+ * larger buffer costs no GPU time.
  */
-export const IDENTITY_SLOT_CAPACITY = 16384;
+export const IDENTITY_SLOT_CAPACITY = 65536;
 /**
- * Base of the permanent zero-length block. A scale that cannot be placed points
- * here, so every lookup finds count 0 and discards — which is what the capacity
- * warning claims happens. Pointing it at a stale base instead left the scale
- * rendering, from another scale's slots.
+ * Base of the permanent empty block `[0, 0, 0]`. A scale that cannot be placed
+ * points here, so every lookup finds count 0 and discards, and every activity
+ * read finds n 0 and is fully active. Pointing it at a stale base instead left
+ * the scale rendering, from another scale's slots.
  */
 export const IDENTITY_SLOT_EMPTY = 0;
+/**
+ * The group index of a mark that reads no selection activity: identityActivity
+ * returns fully active for it before computing any offset, so it never indexes
+ * past a field block. A mark whose selectionResponse is 'filter' gets it: in
+ * the chart holding a selection's control it keeps its data (the chart skips
+ * its own selection), and this keeps it from dimming there too.
+ */
+export const NO_GROUP = 0xffffffff;
+/** Floats before a scale block's slots: count, actRef, n. */
+export const IDENTITY_SLOT_HEADER = 3;
 /** A state with the permanent empty block in place. */
 export function createIdentitySlotState(capacity = IDENTITY_SLOT_CAPACITY) {
     const buffer = new Float32Array(capacity);
     const bufferTo = new Float32Array(capacity);
     buffer.fill(-1);
     bufferTo.fill(-1);
-    // The permanent empty block: count 0, so it holds no slots.
-    buffer[IDENTITY_SLOT_EMPTY] = 0;
-    bufferTo[IDENTITY_SLOT_EMPTY] = 0;
+    // The permanent empty block: count 0, actRef 0, n 0. Never -1: u32(-1.0)
+    // is undefined in WGSL.
+    buffer.fill(0, IDENTITY_SLOT_EMPTY, IDENTITY_SLOT_EMPTY + IDENTITY_SLOT_HEADER);
+    bufferTo.fill(0, IDENTITY_SLOT_EMPTY, IDENTITY_SLOT_EMPTY + IDENTITY_SLOT_HEADER);
     return {
         buffer,
         bufferTo,
         offsets: new Map(),
         versions: new Map(),
+        counts: new Map(),
+        refs: new Map(),
+        ns: new Map(),
         resolvedT: new Map(),
-        seen: new Set(),
+        fieldBases: new Map(),
+        fieldNs: new Map(),
+        fieldGroups: new Map(),
+        fieldVersions: new Map(),
+        fieldT: new Map(),
+        fieldSeen: new Map(),
+        warnedFields: new Set(),
+        seenPass: new Map(),
+        pass: 0,
         result: { uploadStart: 0, uploadEnd: 0, resolves: [], resolveCount: 0 }
     };
 }
 /**
- * Assign every scale a base, write the blocks that moved, and list what to
- * upload and what to resolve.
+ * Assign every field and scale a base, write the ranges that moved, and list
+ * what to upload and what to resolve.
+ *
+ * | Range | Rewritten when | Resolved when |
+ * |---|---|---|
+ * | A field's group half | its base, `n` or the group count moved, or that group's fade version | rewritten, or that fade's `t` moved |
+ * | A scale's header + slots | its base, slot version, or its field block's base or `n` moved | rewritten, or slot `t` moved |
  *
- * A block is REWRITTEN when its base or its version moved, and RESOLVED when it
- * was rewritten or its `t` moved. A parked scale is neither: it has no block,
- * and the empty block it points at is never written.
+ * A range that is rewritten must be resolved even when its `t` did not move:
+ * the render stages read the resolved buffer, not these. A parked scale is
+ * neither rewritten nor resolved: it has no block, and the empty block it
+ * points at is never written.
  *
- * Offsets are recomputed on every call because a scale appearing or
- * disappearing shifts every scale after it. That is a running sum over a
- * handful of scales, and the alternative — a free list — would have to survive
- * a scale changing size, which happens whenever a dim appends.
+ * Offsets are recomputed on every call because a block appearing or
+ * disappearing shifts every block after it. That is a running sum over a
+ * handful of blocks, and the alternative — a free list — would have to survive
+ * a block changing size, which happens whenever a dim appends. A field block
+ * that moves rewrites the headers pointing at it in the same pass.
+ *
+ * `fields` and `groups` default to none, which packs the slots alone.
  */
-export function packIdentitySlots(scales, state) {
-    const { buffer, bufferTo, offsets, versions, resolvedT, result } = state;
+export function packIdentitySlots(scales, state, fields = NO_FIELDS, groups = 0) {
+    const { buffer, bufferTo, offsets, versions, counts, refs, ns, resolvedT, result } = state;
+    const { fieldBases, fieldNs, fieldGroups, fieldVersions, fieldT, seenPass } = state;
+    const { fieldSeen, warnedFields } = state;
     const capacity = buffer.length;
     const resolves = result.resolves;
-    // Index 0 is the permanent empty block; real blocks start after it.
-    let offset = 1;
+    // The permanent empty block comes first; real blocks start after it.
+    let offset = IDENTITY_SLOT_EMPTY + IDENTITY_SLOT_HEADER;
     let uploadStart = capacity;
     let uploadEnd = 0;
     let resolveCount = 0;
-    // Runs every frame: the scratch set and the result are the state's own.
-    const seen = state.seen;
-    seen.clear();
+    // Runs every frame, so nothing here may allocate on a frame where no block
+    // appeared: the pass stamp replaces a Set cleared every pack. Kept a small
+    // integer (a Smi) so storing it never boxes.
+    const pass = (state.pass = state.pass >= 0x3fffffff ? 1 : state.pass + 1);
+    let seenCount = 0;
+    // --- Where the scale blocks end, and which fields a scale draws ---
+    // The same running sum the scale loop below makes, so the field blocks can
+    // be placed after the scales before the scale headers are written.
+    let fieldOffset = offset;
+    for (let i = 0; i < scales.length; i++) {
+        const need = IDENTITY_SLOT_HEADER + scales[i].slots.count;
+        if (fieldOffset + need <= capacity)
+            fieldOffset += need;
+        const key = scales[i].field;
+        if (key)
+            fieldSeen.set(key, pass);
+    }
+    // --- Field blocks: one run per group, after the scales ---
+    for (let f = 0; f < fields.length; f++) {
+        const field = fields[f];
+        const key = field.key;
+        const count = field.count;
+        const live = fieldSeen.get(key) === pass;
+        const need = live ? count * groups : 0;
+        const fits = need > 0 && fieldOffset + need <= capacity;
+        const base = fits ? fieldOffset : IDENTITY_SLOT_EMPTY;
+        const n = fits ? count : 0;
+        if (fits)
+            fieldOffset += need;
+        if (need > 0 && !fits) {
+            // On the transition only: this runs every frame.
+            if (!warnedFields.has(key)) {
+                warnedFields.add(key);
+                console.warn(`[GPUCoordinator] Identity slot capacity (${capacity}) exhausted; ` +
+                    `"${key}" (${count} ids × ${groups} groups) will not dim: a selection on it ` +
+                    `leaves the marks that dim by it unchanged.`);
+            }
+        }
+        else if (fits && warnedFields.size > 0) {
+            warnedFields.delete(key);
+        }
+        const moved = fieldBases.get(key) !== base || fieldNs.get(key) !== n || fieldGroups.get(key) !== groups;
+        let written = fieldVersions.get(key);
+        let lastT = fieldT.get(key);
+        if (!written || written.length !== groups) {
+            // Created when a field first packs or the page gains a group: rare.
+            written = new Float64Array(groups).fill(NaN);
+            lastT = new Float64Array(groups).fill(NaN);
+            fieldVersions.set(key, written);
+            fieldT.set(key, lastT);
+        }
+        if (moved) {
+            fieldBases.set(key, base);
+            fieldNs.set(key, n);
+            fieldGroups.set(key, groups);
+        }
+        if (!fits)
+            continue;
+        for (let g = 0; g < groups; g++) {
+            const fade = field.fadeOf(g);
+            const version = fade ? fade.version : -1;
+            const start = base + n * g;
+            let rewritten = false;
+            if (moved || written[g] !== version) {
+                writeActivity(buffer, bufferTo, start, n, fade);
+                written[g] = version;
+                if (start < uploadStart)
+                    uploadStart = start;
+                if (start + n > uploadEnd)
+                    uploadEnd = start + n;
+                rewritten = true;
+            }
+            const t = fade ? fade.t : 1;
+            if (rewritten || lastT[g] !== t) {
+                lastT[g] = t;
+                const block = (resolves[resolveCount++] ??= { base: 0, length: 0, t: 0 });
+                block.base = start;
+                block.length = n;
+                block.t = t;
+            }
+        }
+    }
+    // --- Scale blocks: [count, actRef, n, slots…] ---
     for (let i = 0; i < scales.length; i++) {
         const scale = scales[i];
-        seen.add(scale.id);
+        if (seenPass.get(scale.id) !== pass) {
+            seenPass.set(scale.id, pass);
+            seenCount++;
+        }
         const slots = scale.slots;
-        // One extra float for the block's count header.
-        const need = slots.count + 1;
+        const count = slots.count;
+        const need = IDENTITY_SLOT_HEADER + count;
         const fits = offset + need <= capacity;
         const base = fits ? offset : IDENTITY_SLOT_EMPTY;
         if (fits)
             offset += need;
+        const fieldKey = scale.field;
+        const ref = fieldKey ? (fieldBases.get(fieldKey) ?? IDENTITY_SLOT_EMPTY) : IDENTITY_SLOT_EMPTY;
+        const n = ref === IDENTITY_SLOT_EMPTY ? 0 : (fieldNs.get(fieldKey) ?? 0);
         const version = slots.version;
+        const dirty = offsets.get(scale.id) !== base ||
+            versions.get(scale.id) !== version ||
+            counts.get(scale.id) !== count ||
+            refs.get(scale.id) !== ref ||
+            ns.get(scale.id) !== n;
         let rewritten = false;
-        if (offsets.get(scale.id) !== base || versions.get(scale.id) !== version) {
+        if (dirty) {
             if (fits) {
-                buffer[base] = slots.count;
-                buffer.set(slots.from, base + 1);
-                bufferTo[base] = slots.count;
-                bufferTo.set(slots.to, base + 1);
+                buffer[base] = count;
+                buffer[base + 1] = ref;
+                buffer[base + 2] = n;
+                buffer.set(slots.from, base + IDENTITY_SLOT_HEADER);
+                bufferTo[base] = count;
+                bufferTo[base + 1] = ref;
+                bufferTo[base + 2] = n;
+                bufferTo.set(slots.to, base + IDENTITY_SLOT_HEADER);
                 if (base < uploadStart)
                     uploadStart = base;
                 if (base + need > uploadEnd)
                     uploadEnd = base + need;
                 rewritten = true;
             }
-            else {
+            else if (offsets.get(scale.id) !== base || versions.get(scale.id) !== version) {
                 // Warn on the transition only — the caller runs this every frame.
-                console.warn(`[GPUCoordinator] Band slot capacity (${capacity}) exhausted; ` +
-                    `scale "${scale.id}" (${slots.count} ids) will not render.`);
+                console.warn(`[GPUCoordinator] Identity slot capacity (${capacity}) exhausted; ` +
+                    `scale "${scale.id}" (${count} ids) will not render.`);
             }
             offsets.set(scale.id, base);
             versions.set(scale.id, version);
+            counts.set(scale.id, count);
+            refs.set(scale.id, ref);
+            ns.set(scale.id, n);
         }
         // No break: a later scale with a smaller table may still fit, and one
         // that does not is parked on the empty block rather than left holding a
         // base that now belongs to someone else.
         if (!fits)
             continue;
+        // Created once per scale; NaN so the first comparison always differs.
+        let lastT = resolvedT.get(scale.id);
+        if (!lastT) {
+            lastT = new Float64Array(1).fill(NaN);
+            resolvedT.set(scale.id, lastT);
+        }
         const t = slots.t;
-        if (!rewritten && resolvedT.get(scale.id) === t)
-            continue;
-        resolvedT.set(scale.id, t);
-        const block = (resolves[resolveCount++] ??= { base: 0, length: 0, t: 0 });
-        block.base = base;
-        block.length = need;
-        block.t = t;
+        if (rewritten || lastT[0] !== t) {
+            lastT[0] = t;
+            const block = (resolves[resolveCount++] ??= { base: 0, length: 0, t: 0 });
+            block.base = base;
+            block.length = need;
+            block.t = t;
+        }
     }
     // Drop entries for scales that have gone away, so a re-registered id cannot
-    // inherit a base from a previous life. `offsets` is a superset of `seen` by
-    // construction — every scale above is written — so comparing sizes is a
-    // sound test for set equality and not just a cheap approximation of one.
-    if (offsets.size !== seen.size) {
+    // inherit a base from a previous life. `offsets` is a superset of this pass's
+    // scales by construction — every scale above is written — so comparing sizes
+    // is a sound test for set equality and not just a cheap approximation of one.
+    // The sweep allocates, but only on a frame where a scale went away. Fields
+    // are not swept: the registry keeps every field it created.
+    if (offsets.size !== seenCount) {
         for (const id of [...offsets.keys()]) {
-            if (!seen.has(id)) {
+            if (seenPass.get(id) !== pass) {
                 offsets.delete(id);
                 versions.delete(id);
+                counts.delete(id);
+                refs.delete(id);
+                ns.delete(id);
                 resolvedT.delete(id);
+                seenPass.delete(id);
             }
         }
     }
@@ -161,3 +342,22 @@ export function packIdentitySlots(scales, state) {
     result.resolveCount = resolveCount;
     return result;
 }
+const NO_FIELDS = [];
+/**
+ * Write one group's half of a field block: `count` floats from `start`, in
+ * both buffers.
+ *
+ * The length is the block's `n`, not the fade's: ids past the fade's end are
+ * fully active, and entries past `n` are dropped. A plain loop, so a rewrite
+ * allocates nothing. With no fade every id is active.
+ */
+function writeActivity(buffer, bufferTo, start, count, activity) {
+    const from = activity?.from;
+    const to = activity?.to;
+    const fromLen = from ? from.length : 0;
+    const toLen = to ? to.length : 0;
+    for (let i = 0; i < count; i++) {
+        buffer[start + i] = i < fromLen ? from[i] : 1;
+        bufferTo[start + i] = i < toLen ? to[i] : 1;
+    }
+}

package/dist/gpu/tracked-scales.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Which of the registry's scales the coordinator tracks: every scale with an
+ * id, keyed by it.
+ *
+ * Tracking is what puts a scale in front of the identity slot packer each
+ * frame, so a scale that offers `slots` but has no `id` is silently never
+ * packed. Ordinal colour was that case: its rank table and selection activity
+ * never reached the GPU, the shader read the dim id as a palette index, and
+ * nothing failed visibly. Pulled out of the coordinator so the rule can be
+ * tested without a device.
+ */
+export declare function trackScalesById<T extends {
+    id?: string;
+}>(scales: Iterable<T>, into: Map<string, T>): void;

package/dist/gpu/tracked-scales.js

@@ -0,0 +1,18 @@
+/**
+ * Which of the registry's scales the coordinator tracks: every scale with an
+ * id, keyed by it.
+ *
+ * Tracking is what puts a scale in front of the identity slot packer each
+ * frame, so a scale that offers `slots` but has no `id` is silently never
+ * packed. Ordinal colour was that case: its rank table and selection activity
+ * never reached the GPU, the shader read the dim id as a palette index, and
+ * nothing failed visibly. Pulled out of the coordinator so the rule can be
+ * tested without a device.
+ */
+export function trackScalesById(scales, into) {
+    into.clear();
+    for (const scale of scales) {
+        if (scale?.id)
+            into.set(scale.id, scale);
+    }
+}

package/dist/index.d.ts

@@ -19,5 +19,7 @@ export * from './components';
 export * from './transforms';
 export * from './sql/bin';
 export * from './types';
+export { getFilterGroups } from './query-engine';
+export type { FilterGroupRegistry, FilterGroup, FilterItem } from './query-engine';
 export { Fjader, render } from './spec';
 export type { FjaderSpec, FjaderHandle, RenderOptions } from './spec';

package/dist/index.js

@@ -17,6 +17,7 @@ export function initFjader(connection) {
     const scaleRegistry = setScaleRegistry();
     const gpuCoordinator = setGPUCoordinator({ msaaSampleCount: 4 });
     gpuCoordinator.setScaleRegistry(scaleRegistry);
+    gpuCoordinator.setFilterGroups(filterGroups);
     scaleRegistry.setGPUCoordinator(gpuCoordinator);
     return { queryEngine, filterGroups, scaleRegistry, gpuCoordinator };
 }
@@ -24,5 +25,8 @@ export * from './components';
 export * from './transforms';
 export * from './sql/bin';
 export * from './types';
+// Selection state: the registry initFjader() returns, for code outside it (is anything
+// brushed? which groups exist?). Read from the same context.
+export { getFilterGroups } from './query-engine';
 // Spec-driven rendering API
 export { Fjader, render } from './spec';

package/dist/interactors/BandLabelToggle.svelte

@@ -1,11 +1,7 @@
 <script lang="ts">
 	import { getContext, onDestroy } from 'svelte';
 	import type { ChartContext } from '../types';
-	import type {
-		ActiveValueScale,
-		FilterGroup,
-		ToggleHandle
-	} from '../query-engine/FilterGroup.svelte';
+	import type { FilterGroup, ToggleHandle } from '../query-engine/FilterGroup.svelte';
 
 	/**
 	 * A Toggle's registration for one band axis field, so label clicks toggle
@@ -22,17 +18,17 @@
 	interface Props {
 		filterGroup: FilterGroup;
 		field: string;
-		excludeMarkIds: () => Set<string>;
-		scales: () => ActiveValueScale[];
+		/** The chart its toggle skips (see Toggle). */
+		chart: object;
 		/** Where the parent's click handler finds this field's toggle. */
 		handles: Map<string, ToggleHandle>;
 	}
 
 	// Keyed by field in the parent, so none of these change for an instance.
-	const { filterGroup, field, excludeMarkIds, scales, handles }: Props = $props();
+	const { filterGroup, field, chart: skips, handles }: Props = $props();
 
 	const chart = getContext<ChartContext>('chart');
-	const toggle = filterGroup.registerToggle(field, { excludeMarkIds, scales });
+	const toggle = filterGroup.registerToggle(field, { chart: skips });
 
 	handles.set(field, toggle);
 	chart.activators.add(toggle.activate);

package/dist/interactors/BandLabelToggle.svelte.d.ts

@@ -1,4 +1,4 @@
-import type { ActiveValueScale, FilterGroup, ToggleHandle } from '../query-engine/FilterGroup.svelte';
+import type { FilterGroup, ToggleHandle } from '../query-engine/FilterGroup.svelte';
 /**
  * A Toggle's registration for one band axis field, so label clicks toggle
  * the axis's own field. Renders nothing: it exists for its lifecycle.
@@ -13,8 +13,8 @@ import type { ActiveValueScale, FilterGroup, ToggleHandle } from '../query-engin
 interface Props {
     filterGroup: FilterGroup;
     field: string;
-    excludeMarkIds: () => Set<string>;
-    scales: () => ActiveValueScale[];
+    /** The chart its toggle skips (see Toggle). */
+    chart: object;
     /** Where the parent's click handler finds this field's toggle. */
     handles: Map<string, ToggleHandle>;
 }

package/dist/interactors/DerivedInterval1D.svelte

@@ -15,6 +15,8 @@
 	import type { ChartContext } from '../types';
 	import { TimeScaleState } from '../scales/TimeScaleState.svelte';
 	import type { FilterGroupRegistry } from '../query-engine/FilterGroupRegistry.svelte';
+	import type { Clause } from '../query-engine/CrossfilterSelection.svelte';
+	import { ClauseRelay } from './relay-clauses';
 
 	interface Props {
 		sourceSelection: string;
@@ -63,13 +65,15 @@
 	// Filter Bridge: Watch source group items → compute derived extent
 	// =========================================================================
 
-	// Extract primary range from source group's active filter items
+	// The primary range: the source group's first range clause, found by the
+	// schema its brush stored when writing it.
 	const primaryRange = $derived.by((): [number, number] | null => {
-		const items = sourceGroup.items;
-		const rangeItem = items.find((item) => item.schema?.kind === 'range');
-		if (!rangeItem?.schema?.values?.length) return null;
-		const values = rangeItem.schema.values as number[];
-		return [values[0], values[1]];
+		let rangeClause: Clause | null = null;
+		sourceGroup.selection.forEach((clause) => {
+			if (!rangeClause && clause.schema?.kind === 'range') rangeClause = clause;
+		});
+		const values = (rangeClause as Clause | null)?.schema?.values as number[] | undefined;
+		return values?.length ? [values[0], values[1]] : null;
 	});
 
 	// Compute derived extent via Temporal calendar offset
@@ -149,69 +153,37 @@
 
 		if (!ref) return;
 
-		targetGroup.upsertManual(
-			sourceKey,
-			isBetween(ref, [dataMin, dataMax]),
-			[dataMin, dataMax],
-			new Set<string>(), // No excludeMarkIds — target group only has comparison marks
-			{
-				kind: 'range',
-				column: fieldStr,
-				label: fieldStr,
-				values: [dataMin, dataMax]
-			}
-		);
+		targetGroup.upsertManual(sourceKey, isBetween(ref, [dataMin, dataMax]), [dataMin, dataMax], {
+			kind: 'range',
+			column: fieldStr,
+			label: fieldStr,
+			values: [dataMin, dataMax]
+		});
 	}
 
 	// =========================================================================
 	// Relay non-axis clauses from source → target
 	// =========================================================================
 
-	let relayedKeys = new Set<string>();
+	const relay = new ClauseRelay(sourceGroup, targetGroup);
+	/** Does nothing: forEach(track) only subscribes the effect to every clause. */
+	const track = () => {};
 
 	// Tracks only the source group's clauses and what decides which to relay.
-	// The writes to the target group run untracked, as above: tracked, they
-	// made this effect re-run itself without end once the source had a clause
-	// to relay (a day-of-week toggle beside the brush).
+	// The writes to the target group run untracked: tracked, they made this
+	// effect re-run itself without end once the source had a clause to relay
+	// (a day-of-week toggle beside the brush).
 	$effect(() => {
-		const relay = relayClauses;
-		const items = sourceGroup.items;
+		const enabled = relayClauses;
 		const fieldStr = resolvedField ?? '';
-		untrack(() => relayItems(relay ? items : null, fieldStr));
+		sourceGroup.selection.forEach(track);
+		untrack(() => relay.sync(enabled, fieldStr));
 	});
 
-	/** Mirror the source's clauses, but the axis range, into the target group. */
-	function relayItems(items: typeof sourceGroup.items | null, fieldStr: string) {
-		const currentKeys = new Set<string>();
-		for (const item of items ?? []) {
-			// Skip the range clause on the axis column — we replace it with the shifted version
-			if (item.schema?.kind === 'range' && item.schema?.column === fieldStr) continue;
-
-			if (item.predicate) {
-				const key = `relay:${item.sourceId}`;
-				currentKeys.add(key);
-				targetGroup.upsertManual(
-					key,
-					item.predicate,
-					item.value,
-					new Set<string>(),
-					item.schema ?? undefined
-				);
-			}
-		}
-
-		// Remove stale relayed clauses
-		for (const key of relayedKeys) {
-			if (!currentKeys.has(key)) targetGroup.removeManual(key);
-		}
-		relayedKeys = currentKeys;
-	}
-
 	onMount(() => {
 		return () => {
 			targetGroup.removeManual(sourceKey);
-			for (const key of relayedKeys) targetGroup.removeManual(key);
-			relayedKeys = new Set();
+			relay.clear();
 		};
 	});
 </script>