@fjader/svelte 0.2.4 → 0.2.5

package/dist/gpu/GPUCoordinator.svelte.js

@@ -1,5 +1,7 @@
+import { observeTransitions } from '../animation/transition-log';
 import { setContext, getContext } from 'svelte';
 import { AnimationLoop } from '../animation';
+import { TransitionClock, ENTRANCE_FADE_STIFFNESS, ENTRANCE_GROW_STIFFNESS } from '../animation/TransitionClock';
 import { scaleTemplateSystem, CHART_SCALE_IMMEDIATE_SIZE } from './ScaleTemplateSystem';
 import { isCategoricalScale } from '../scales/scale-categories';
 import { MAX_SIZE_SLOTS } from './SizeScaleShaderLib';
@@ -19,8 +21,23 @@ export const COLOR_RAMP_RESOLUTION = 256;
 function layerCanDraw(layer, chartScalesKnown) {
     return (!!layer.renderer?.perDataBindGroup && (chartScalesKnown || layer.readsChartScales === false));
 }
+/** A guide (a grid line) rather than data: it neither enters nor starts the entrance. */
+function isGuideLayer(layer) {
+    return layer.markType.startsWith('grid-line-');
+}
 /** No fields to pack, for a coordinator without filter groups. */
 const NO_FIELDS = [];
+/**
+ * A chart's entrance once the viewer's preference is applied: under reduced
+ * motion, 'auto' fades rather than grows. Opacity is not motion, so a fade
+ * stays; an author's explicit 'fade' or 'none' is kept as is.
+ */
+function resolveEntrance(mode) {
+    const chosen = mode ?? 'auto';
+    if (chosen !== 'auto' || typeof matchMedia === 'undefined')
+        return chosen;
+    return matchMedia('(prefers-reduced-motion: reduce)').matches ? 'fade' : 'auto';
+}
 // =============================================================================
 // HELPER CLASSES
 // =============================================================================
@@ -477,10 +494,6 @@ export class GPUCoordinator {
             usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
         });
     }
-    /**
-     * Fill CPU buffer with current scale GPU state.
-     * Zero-allocation hot path.
-     */
     /**
      * Buffers for the slot table and its per-frame resolve.
      *
@@ -746,8 +759,115 @@ export class GPUCoordinator {
         this.#device.queue.writeBuffer(buffer, 0, view);
         last.set(view);
     }
-    /** Reused per pass: the chart's x and y ScaleParam, pushed as immediates. */
+    /** Reused per pass: the chart's x and y ScaleParam and entrance, pushed as immediates. */
     #chartScaleImmediates = new Float32Array(CHART_SCALE_IMMEDIATE_SIZE / 4);
+    /** Debug listeners for chart entrances (observeEntrances). */
+    #entranceObservers = new Set();
+    /**
+     * Listen to every chart's entrance as it starts: when its marks have their
+     * first data and it first draws. For measuring load (how soon charts enter);
+     * returns the unsubscribe. Costs nothing while no one listens.
+     */
+    observeEntrances(listener) {
+        this.#entranceObservers.add(listener);
+        return () => this.#entranceObservers.delete(listener);
+    }
+    /**
+     * Begin a chart's entrance on the first pass that draws data in it.
+     *
+     * Per chart, not per mark: every mark in the chart reads the same immediate,
+     * so a bar chart and the line drawn over it enter together. Marks normally
+     * land in one query batch; one landing mid-entrance joins at the current t,
+     * and one landing after it simply appears.
+     *
+     * Started here rather than on registration, so an off-screen chart enters
+     * when it is first drawn, which is when it can be seen.
+     */
+    #startEntranceIfDrawing(chart, scalesKnown) {
+        // Every mark's first data first, so the chart enters once, whole. Only
+        // this chart's marks: a chart sharing a scale that lands later springs
+        // the domain to the combined extent, as any later data would.
+        const gate = chart.entranceGate;
+        if (gate) {
+            if (!gate.canEnter)
+                return;
+            gate.open();
+        }
+        const plan = chart.renderPlan;
+        let drawing = false;
+        for (let i = 0; i < plan.length; i++) {
+            // Data marks only: a grid line draws as soon as the scales exist, which
+            // is usually before the query has answered, and would start the
+            // entrance with nothing in it.
+            if (isGuideLayer(plan[i]))
+                continue;
+            if (layerCanDraw(plan[i], scalesKnown)) {
+                drawing = true;
+                break;
+            }
+        }
+        if (!drawing)
+            return;
+        chart.entranceStarted = true;
+        if (this.#entranceObservers.size > 0) {
+            const entrance = {
+                chartId: chart.chartId,
+                canvas: chart.canvas,
+                time: performance.now()
+            };
+            for (const observe of this.#entranceObservers) {
+                try {
+                    observe(entrance);
+                }
+                catch (e) {
+                    console.error('[GPUCoordinator] entrance observer threw:', e);
+                }
+            }
+        }
+        if (chart.entranceMode === 'none')
+            return;
+        const clock = new TransitionClock({
+            loop: this,
+            stiffness: ENTRANCE_GROW_STIFFNESS,
+            charts: () => chart.entranceCharts,
+            onRest: () => {
+                if (chart.entranceClock === clock)
+                    chart.entranceClock = null;
+            }
+        });
+        chart.entranceClock = clock;
+        // Ease-out: growth should move from its first frame.
+        clock.restartEaseOut();
+        const fade = new TransitionClock({
+            loop: this,
+            stiffness: ENTRANCE_FADE_STIFFNESS,
+            charts: () => chart.entranceCharts,
+            onRest: () => {
+                if (chart.entranceFadeClock === fade)
+                    chart.entranceFadeClock = null;
+            }
+        });
+        chart.entranceFadeClock = fade;
+        // From rest: a soft S-curve for opacity.
+        fade.restart();
+    }
+    /**
+     * The entrance immediates: x = growth, y = a growing mark's opacity, z = a
+     * fading mark's opacity. The mode is folded in here, so a mark only says
+     * whether it grows or fades.
+     */
+    #writeEntrance(chart, view) {
+        // Before the entrance starts the chart draws nothing, so 0 is never
+        // seen; after it, the clocks are gone and everything is at 1.
+        const idle = chart.entranceStarted ? 1 : 0;
+        const grow = chart.entranceClock ? chart.entranceClock.t : idle;
+        const fade = chart.entranceFadeClock ? chart.entranceFadeClock.t : idle;
+        const mode = chart.entranceMode;
+        view[8] = mode === 'auto' ? grow : 1;
+        view[9] = mode === 'fade' ? fade : 1;
+        view[10] = mode === 'none' ? 1 : fade;
+        view[11] = 0;
+    }
     // =========================================================================
     // READBACK (test-only)
     // =========================================================================
@@ -996,6 +1116,9 @@ export class GPUCoordinator {
             // known: a layer that does not read them still needs every byte set
             // before it may draw.
             const scalesKnown = this.#writeChartScales(chartConfig, this.#chartScaleImmediates);
+            if (!chartConfig.entranceStarted)
+                this.#startEntranceIfDrawing(chartConfig, scalesKnown);
+            this.#writeEntrance(chartConfig, this.#chartScaleImmediates);
             passEncoder.setImmediates(0, this.#chartScaleImmediates);
             if (chartConfig.perFrameBindGroup) {
                 passEncoder.setBindGroup(0, chartConfig.perFrameBindGroup);
@@ -1501,8 +1624,19 @@ export class GPUCoordinator {
             renderPassDescriptor: null,
             msaa: null,
             _lastRenderFrame: -1,
-            _isDirty: false
+            _isDirty: false,
+            entranceMode: resolveEntrance(config.entrance),
+            entranceStarted: false,
+            entranceClock: null,
+            entranceFadeClock: null,
+            entranceCharts: [chartId],
+            entranceGate: config.entranceGate ?? null,
+            entranceGateOff: null
         };
+        // The gate opens on a mark's data or a timeout, neither of which need
+        // redraw this chart. Without a frame the entrance would wait for one.
+        chartConfig.entranceGateOff =
+            chartConfig.entranceGate?.onOpen(() => this.invalidateChart(chartId)) ?? null;
         this.#registeredCharts.set(chartId, chartConfig);
         // Observe canvas for viewport visibility
         if (this.#visibilityObserver) {
@@ -1552,6 +1686,12 @@ export class GPUCoordinator {
         const chartConfig = this.#registeredCharts.get(chartId);
         if (chartConfig) {
             chartConfig._isDirty = false;
+            chartConfig.entranceClock?.stop();
+            chartConfig.entranceClock = null;
+            chartConfig.entranceFadeClock?.stop();
+            chartConfig.entranceFadeClock = null;
+            chartConfig.entranceGateOff?.();
+            chartConfig.entranceGateOff = null;
             if (chartConfig.frameUniformsBuffer) {
                 chartConfig.frameUniformsBuffer.destroy();
             }
@@ -1580,13 +1720,30 @@ export class GPUCoordinator {
     // =========================================================================
     // VIEWPORT VISIBILITY
     // =========================================================================
+    /**
+     * Debug: every transition that starts, and whether it animates or lands at
+     * once (see transition-log). Returns the unsubscribe. Forwards to the
+     * page-wide log: records from every coordinator in the document arrive
+     * here, so filter by chart id.
+     */
+    observeTransitions(listener) {
+        return observeTransitions(listener);
+    }
+    /** Whether a registered chart is visible: in view (with the 200 px margin) and the page shown. */
+    isChartVisible(chartId) {
+        return this.#registeredCharts.get(chartId)?.visible ?? false;
+    }
     /**
      * Register a callback invoked when a chart's effective visibility changes.
      * Effective visibility = IntersectionObserver visible AND page visible.
-     * Used by ChartCell to toggle Mosaic client.enabled.
+     * Used by ChartCell to report into the chart's ChartVisibility.
      */
     setVisibilityCallback(chartId, callback) {
         this.#visibilityCallbacks.set(chartId, callback);
+        // Callbacks hear changes only. One set after the chart was already found
+        // off screen would otherwise go on assuming it visible.
+        if (this.#registeredCharts.get(chartId)?.visible === false)
+            callback(false);
         return () => this.#visibilityCallbacks.delete(chartId);
     }
     #handleVisibilityChange(chartId, ioVisible) {

package/dist/gpu/MorphedChannels.d.ts

@@ -1,4 +1,8 @@
 import { TransitionClock, type ClockLoop } from '../animation/TransitionClock';
+/**
+ * The coordinator's slice this needs. Structural, so tests can supply a fake.
+ * It is also the loop an owned clock joins — the clock does that itself.
+ */
 export interface MorphHost extends ClockLoop {
     registerComputeWork(key: string, fn: (encoder: GPUCommandEncoder) => void): void;
     removeComputeWork(key: string): void;
@@ -30,6 +34,10 @@ export interface MorphedChannelsOptions {
  * travelling to its neighbour's value and back. So the claim is checked, and a
  * change snaps rather than interpolates. A hash rather than a comparison
  * because it costs one pass and no retained copy.
+ *
+ * Over the values' bits, read through a view of the same buffer: a
+ * histogram's rows are keyed by bin edges, fractions a sum would truncate
+ * away, so a re-bin could otherwise hash like the bins it replaced.
  */
 export declare function alignmentKey(ids: ArrayLike<number>): number;
 export declare class MorphedChannels {
@@ -58,9 +66,10 @@ export declare class MorphedChannels {
      * `land`: bindings whose new values take effect at once while the rest
      * travel. For a channel whose change is shown some other way at that moment
      * (an Other bar's split, when both sides of it look the same): sliding it
-     * would draw a movement nothing asked for.
+     * would draw a movement nothing asked for. `'all'`: the whole update lands,
+     * for a catch-up result (MarkHandle.resultCause).
      */
-    write(rowIds: ArrayLike<number>, channels: readonly (readonly [number, AllowSharedBufferSource])[], land?: readonly number[]): boolean;
+    write(rowIds: ArrayLike<number>, channels: readonly (readonly [number, AllowSharedBufferSource])[], land?: readonly number[] | 'all'): boolean;
     /**
      * Stop morphing a channel and release its buffers. Returns whether it was
      * morphing, in which case the caller's binding has lost its buffer.

package/dist/gpu/MorphedChannels.js

@@ -1,3 +1,4 @@
+import { noteTransition, transitionsObserved } from '../animation/transition-log';
 import { RESOLVE_IMMEDIATE_SIZE, RESOLVE_WORKGROUP, resolvePipelineFor } from './ResolveShader';
 import { TransitionClock } from '../animation/TransitionClock';
 import { immediatesSupported } from './immediates';
@@ -28,10 +29,6 @@ import { immediatesSupported } from './immediates';
  * finishes growing. It OWNS one otherwise. Adoption is safe across marks because
  * a mark with no new data folds to where it already is and does not move.
  */
-/**
- * The coordinator's slice this needs. Structural, so tests can supply a fake.
- * It is also the loop an owned clock joins — the clock does that itself.
- */
 /** No bindings: the default for `write`'s `land`. */
 const NO_BINDINGS = [];
 /**
@@ -43,11 +40,16 @@ const NO_BINDINGS = [];
  * travelling to its neighbour's value and back. So the claim is checked, and a
  * change snaps rather than interpolates. A hash rather than a comparison
  * because it costs one pass and no retained copy.
+ *
+ * Over the values' bits, read through a view of the same buffer: a
+ * histogram's rows are keyed by bin edges, fractions a sum would truncate
+ * away, so a re-bin could otherwise hash like the bins it replaced.
  */
 export function alignmentKey(ids) {
-    let hash = ids.length;
-    for (let i = 0; i < ids.length; i++)
-        hash = (hash * 31 + ids[i]) | 0;
+    const bits = ids instanceof Float32Array ? new Uint32Array(ids.buffer, ids.byteOffset, ids.length) : ids;
+    let hash = bits.length;
+    for (let i = 0; i < bits.length; i++)
+        hash = (Math.imul(hash, 31) + bits[i]) | 0;
     return hash;
 }
 export class MorphedChannels {
@@ -124,7 +126,8 @@ export class MorphedChannels {
      * `land`: bindings whose new values take effect at once while the rest
      * travel. For a channel whose change is shown some other way at that moment
      * (an Other bar's split, when both sides of it look the same): sliding it
-     * would draw a movement nothing asked for.
+     * would draw a movement nothing asked for. `'all'`: the whole update lands,
+     * for a catch-up result (MarkHandle.resultCause).
      */
     write(rowIds, channels, land = NO_BINDINGS) {
         const key = alignmentKey(rowIds);
@@ -138,7 +141,7 @@ export class MorphedChannels {
                 reallocated = true;
             }
             channel.count = data.byteLength >> 2;
-            channel.land = land.includes(binding);
+            channel.land = land === 'all' || land.includes(binding);
             this.#device.queue.writeBuffer(channel.to, 0, data);
         }
         // A fresh buffer holds nothing that was ever on screen, so there is
@@ -146,10 +149,29 @@ export class MorphedChannels {
         if (reallocated)
             travels = false;
         this.#dirty = true;
-        if (travels)
+        // Every channel landing travels nothing, so it starts no transition: on
+        // a shared band clock a restart would set every sibling folding for a
+        // transition with nowhere to go.
+        // A loop, not `every`: this runs on each data update of a brush, and
+        // the callback would allocate per write.
+        let allLand = land === 'all';
+        if (land !== 'all' && land.length > 0) {
+            allLand = true;
+            for (let i = 0; i < channels.length; i++) {
+                if (!land.includes(channels[i][0])) {
+                    allLand = false;
+                    break;
+                }
+            }
+        }
+        if (travels && !allLand)
             this.#startTransition();
-        else
+        else if (!travels)
             this.#snapPending = true;
+        if (transitionsObserved()) {
+            // Snaps when the row set changed or a buffer grew, or every channel lands.
+            noteTransition('morph', !travels || allLand, this.#affectedCharts, this.#label);
+        }
         if (!this.#registered) {
             this.#registered = true;
             this.#host.registerComputeWork(this.#label, (encoder) => this.encode(encoder));

package/dist/gpu/ScaleTemplateSystem.d.ts

@@ -33,14 +33,14 @@ interface ShaderResult {
 }
 /**
  * Bytes of immediate data every render pipeline declares: the chart's x and y
- * `ScaleParam`, 16 bytes each. Every layout declares the same size because a
+ * `ScaleParam`, 16 bytes each, and its entrance, a vec4. Every layout declares the same size because a
  * draw requires every declared byte to have been set, and the pass sets them
  * once, before its first draw.
  *
  * Immediates carry state shared across the pass and read by several marks: the
  * chart's scales and settings. 64 bytes are available on M-series Macs.
  */
-export declare const CHART_SCALE_IMMEDIATE_SIZE = 32;
+export declare const CHART_SCALE_IMMEDIATE_SIZE = 48;
 /**
  * Main template system class
  */
@@ -69,6 +69,24 @@ export declare class ScaleTemplateSystem {
      * @private
      */
     _buildDeclarations(xFragment: ScaleFragment, yFragment: ScaleFragment): string;
+    /**
+     * The chart's entrance, for marks to apply in the vertex stage.
+     *
+     * A mark either GROWS along one axis (bars, histograms and areas, from the
+     * value 0 on their measure axis) or FADES (everything else). Which one is
+     * the mark's to say, as `axis`: 0 fades, 1 grows along x, 2 along y. The
+     * chart's mode is already folded into the immediates, so a chart set to
+     * fade hands a growing mark g = 1 and its opacity instead.
+     *
+     * The base a mark grows from is where 0 sits on screen, clamped to the plot:
+     * a domain that leaves 0 out grows from the edge, which is where its bars
+     * visibly start anyway. A log axis has no 0 and grows from its low edge.
+     * Decided per scale type here, so no shader evaluates log(0).
+     */
+    _buildEntranceHelpers(scaleTypes: {
+        x: string;
+        y: string;
+    }): string;
     /**
      * `bandActivityX(value, group)` and `bandActivityY(value, group)`: how
      * selected a band or point axis's category is in the mark's filter group,

package/dist/gpu/ScaleTemplateSystem.js

@@ -280,14 +280,14 @@ function _scaleFunctionName(scaleType, axis) {
 }
 /**
  * Bytes of immediate data every render pipeline declares: the chart's x and y
- * `ScaleParam`, 16 bytes each. Every layout declares the same size because a
+ * `ScaleParam`, 16 bytes each, and its entrance, a vec4. Every layout declares the same size because a
  * draw requires every declared byte to have been set, and the pass sets them
  * once, before its first draw.
  *
  * Immediates carry state shared across the pass and read by several marks: the
  * chart's scales and settings. 64 bytes are available on M-series Macs.
  */
-export const CHART_SCALE_IMMEDIATE_SIZE = 32;
+export const CHART_SCALE_IMMEDIATE_SIZE = 48;
 /**
  * Main template system class
  */
@@ -376,6 +376,7 @@ export class ScaleTemplateSystem {
       // ===== 3. HELPER FUNCTIONS =====
       
       ${this._buildSlotTableHelpers()}
+      ${this._buildEntranceHelpers(scaleTypes)}
       ${this._buildBandActivityHelpers(scaleTypes)}
       ${bandHelpers}
       ${implementations}
@@ -413,6 +414,10 @@ export class ScaleTemplateSystem {
       struct ChartScales {
         x: ScaleParam,
         y: ScaleParam,
+        // The chart's entrance, written per pass from its entrance clock:
+        // x = how far a growing mark has grown, y = a growing mark's opacity,
+        // z = a fading mark's opacity. All 1 once the chart has entered.
+        entrance: vec4<f32>,
       };
       var<immediate> chartScales: ChartScales;
 
@@ -448,6 +453,57 @@ export class ScaleTemplateSystem {
     `;
         return `${structDef}\n${chartScaleDeclaration}`;
     }
+    /**
+     * The chart's entrance, for marks to apply in the vertex stage.
+     *
+     * A mark either GROWS along one axis (bars, histograms and areas, from the
+     * value 0 on their measure axis) or FADES (everything else). Which one is
+     * the mark's to say, as `axis`: 0 fades, 1 grows along x, 2 along y. The
+     * chart's mode is already folded into the immediates, so a chart set to
+     * fade hands a growing mark g = 1 and its opacity instead.
+     *
+     * The base a mark grows from is where 0 sits on screen, clamped to the plot:
+     * a domain that leaves 0 out grows from the edge, which is where its bars
+     * visibly start anyway. A log axis has no 0 and grows from its low edge.
+     * Decided per scale type here, so no shader evaluates log(0).
+     */
+    _buildEntranceHelpers(scaleTypes) {
+        const base = (axis, type) => {
+            const a = axis.toLowerCase();
+            const lo = `frameUniforms.rangeMin.${a}`;
+            const hi = `frameUniforms.rangeMax.${a}`;
+            if (type === 'band' || type === 'point')
+                return '0.0';
+            // Screen y runs downward: the low edge of a y axis is rangeMax.
+            if (type === 'log')
+                return axis === 'X' ? lo : hi;
+            return `clamp(${_scaleFunctionName(type, axis)}From(0.0, chartScale${axis}()), ${lo}, ${hi})`;
+        };
+        return `
+    // ===== ENTRANCE =====
+    fn entranceBaseX() -> f32 {
+      return ${base('X', scaleTypes.x)};
+    }
+    fn entranceBaseY() -> f32 {
+      return ${base('Y', scaleTypes.y)};
+    }
+    // A screen position as it is during the entrance: pulled toward the base
+    // on the growing axis, untouched otherwise.
+    fn entrancePosition(p: vec2<f32>, axis: u32) -> vec2<f32> {
+      let g = chartScales.entrance.x;
+      if (axis == 1u) {
+        return vec2<f32>(mix(entranceBaseX(), p.x, g), p.y);
+      }
+      if (axis == 2u) {
+        return vec2<f32>(p.x, mix(entranceBaseY(), p.y, g));
+      }
+      return p;
+    }
+    fn entranceAlpha(axis: u32) -> f32 {
+      return select(chartScales.entrance.z, chartScales.entrance.y, axis != 0u);
+    }
+    `;
+    }
     /**
      * `bandActivityX(value, group)` and `bandActivityY(value, group)`: how
      * selected a band or point axis's category is in the mark's filter group,

package/dist/index.d.ts

@@ -1,4 +1,11 @@
-import type { DuckDBConnection } from './query-engine';
+import type { DuckDBConnection, InitDuckDBOptions, QueryEngineOptions } from './query-engine';
+export interface FjaderOptions extends InitDuckDBOptions {
+    /** An existing connection (or a promise of one); skips internal DuckDB-WASM init. */
+    connection?: DuckDBConnection | Promise<DuckDBConnection>;
+    /** Advanced: query engine tuning (see QueryEngineOptions). */
+    engine?: QueryEngineOptions;
+}
+type FjaderInit = DuckDBConnection | Promise<DuckDBConnection> | FjaderOptions;
 /**
  * Initialize Fjader: QueryEngine, ScaleRegistry, GPUCoordinator, FilterGroups.
  * Call once in a top-level component's <script> block.
@@ -6,10 +13,14 @@ import type { DuckDBConnection } from './query-engine';
  *   import { initFjader } from '@fjader/svelte';
  *   const { queryEngine } = initFjader();
  *
- * Pass an existing DuckDB connection to skip internal DuckDB-WASM init:
- *   const { queryEngine } = initFjader(myConnection);
+ * Serve the DuckDB-WASM bundles yourself instead of loading them from jsDelivr:
+ *   initFjader({ bundles: { mvp: { mainModule, mainWorker }, eh: { … } } });
+ *
+ * Pass an existing DuckDB connection to skip internal DuckDB-WASM init, e.g. to
+ * keep the AsyncDuckDB instance for registerFileBuffer:
+ *   const { queryEngine } = initFjader(connectionFrom(await db.connect()));
  */
-export declare function initFjader(connection?: DuckDBConnection | Promise<DuckDBConnection>): {
+export declare function initFjader(init?: FjaderInit): {
     queryEngine: import("./query-engine").QueryEngine;
     filterGroups: import("./query-engine").FilterGroupRegistry;
     scaleRegistry: import("./scales").ScaleRegistry;
@@ -20,6 +31,8 @@ export * from './transforms';
 export * from './sql/bin';
 export * from './types';
 export { getFilterGroups } from './query-engine';
+export { connectionFrom } from './query-engine';
+export type { DuckDBConnection, InitDuckDBOptions } 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

@@ -2,6 +2,14 @@
 import { setScaleRegistry } from './scales';
 import { setGPUCoordinator } from './gpu';
 import { setQueryContext, initDuckDB } from './query-engine';
+/** A connection has query(), a promise has then(); anything else is options. */
+function toOptions(init) {
+    if (!init)
+        return {};
+    if ('query' in init || 'then' in init)
+        return { connection: init };
+    return init;
+}
 /**
  * Initialize Fjader: QueryEngine, ScaleRegistry, GPUCoordinator, FilterGroups.
  * Call once in a top-level component's <script> block.
@@ -9,11 +17,16 @@ import { setQueryContext, initDuckDB } from './query-engine';
  *   import { initFjader } from '@fjader/svelte';
  *   const { queryEngine } = initFjader();
  *
- * Pass an existing DuckDB connection to skip internal DuckDB-WASM init:
- *   const { queryEngine } = initFjader(myConnection);
+ * Serve the DuckDB-WASM bundles yourself instead of loading them from jsDelivr:
+ *   initFjader({ bundles: { mvp: { mainModule, mainWorker }, eh: { … } } });
+ *
+ * Pass an existing DuckDB connection to skip internal DuckDB-WASM init, e.g. to
+ * keep the AsyncDuckDB instance for registerFileBuffer:
+ *   const { queryEngine } = initFjader(connectionFrom(await db.connect()));
  */
-export function initFjader(connection) {
-    const { queryEngine, filterGroups } = setQueryContext(connection ?? initDuckDB());
+export function initFjader(init) {
+    const { connection, bundles, engine } = toOptions(init);
+    const { queryEngine, filterGroups } = setQueryContext(connection ?? initDuckDB({ bundles }), engine);
     const scaleRegistry = setScaleRegistry();
     const gpuCoordinator = setGPUCoordinator({ msaaSampleCount: 4 });
     gpuCoordinator.setScaleRegistry(scaleRegistry);
@@ -28,5 +41,7 @@ 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';
+// DuckDB: adapt an app-owned duckdb-wasm connection for initFjader(connection).
+export { connectionFrom } from './query-engine';
 // Spec-driven rendering API
 export { Fjader, render } from './spec';

package/dist/interactors/TooltipManager.svelte.js

@@ -186,7 +186,16 @@ export class TooltipManager {
                 if (!sql)
                     continue;
                 queryPromises.push(this.#queryEngine
-                    .query(sql, { callerId: 'tooltip' })
+                    // Per mark: one shared caller id let execute-latest drop every
+                    // lookup but the first and last when a chart has three or more
+                    // marks. Not cached: the tooltip table is rewritten on each data
+                    // change while a lookup's SQL can stay the same.
+                    .query(sql, {
+                    callerId: `tooltip:${markId}`,
+                    cache: false,
+                    // The tooltip table is TEMP, on the main connection.
+                    connectionLocal: true
+                })
                     .then((result) => {
                     const rows = Array.from(result);
                     return rows.length > 0 ? { markId, config, rows } : null;
@@ -500,10 +509,6 @@ export class TooltipManager {
     // =========================================================================
     // LABEL RESOLUTION
     // =========================================================================
-    /**
-     * Resolve band indices, time offsets, and color indices back to human-readable labels.
-     * Renames columns from aliases (x, y, color) to original field names.
-     */
     /** Resolve a single value: band index → label, time offset → formatted date. */
     #resolveValue(axis, key, value, config) {
         const { scaleTypes, bandDomains } = config;
@@ -534,6 +539,10 @@ export class TooltipManager {
         }
         return String(value ?? '');
     }
+    /**
+     * Resolve band indices, time offsets, and color indices back to human-readable labels.
+     * Renames columns from aliases (x, y, color) to original field names.
+     */
     #resolveLabels(row, config) {
         const { scaleTypes, channelFields, bandDomains, colorDomain, columns } = config;
         const point = {};

package/dist/query-engine/CrossfilterSelection.svelte.d.ts

@@ -16,6 +16,7 @@
  * Both are computed when asked, from the clause, the mark's route and the
  * live registrations: nothing is cached, so nothing goes stale.
  */
+import type { SelectionResponse } from '../components/rendering/activity-reads';
 import type { ExprNode } from '@uwdata/mosaic-sql';
 export type FilterExpr = ExprNode | string | boolean;
 export interface FilterSchema {
@@ -53,12 +54,13 @@ export interface Clause {
  * faceted chart's cells have ids of their own, but share one config.
  * `response` 'filter' makes every selection filter the mark, and a click
  * control's (a discrete registration's) in its own chart too; brushes still
- * skip their own chart.
+ * skip their own chart. 'ignore' makes no selection filter it, so no clause
+ * change re-queries it and preagg builds nothing for it.
  */
 export interface MarkRoute {
     readonly reads: readonly string[];
     readonly chart: object | null;
-    readonly response?: 'auto' | 'filter';
+    readonly response?: SelectionResponse;
 }
 /**
  * What routing reads from one registration of a source: the chart it skips,

package/dist/query-engine/CrossfilterSelection.svelte.js

@@ -57,6 +57,8 @@ export class CrossfilterSelection {
      * no allocation, as it runs per mark per clause on every brush frame.
      */
     filters(route, sourceId, key) {
+        if (route.response === 'ignore')
+            return false;
         if (key !== null && route.reads.includes(key))
             return false;
         const chart = route.chart;