@fjader/svelte 0.2.4 → 0.2.5

package/dist/components/marks/lifecycle/MarkLifecycleV2.svelte.js

@@ -29,7 +29,7 @@ import { isBinExpression } from '../../../sql/bin';
 import { isRollingAvgExpression } from '../../../sql/rolling-avg';
 import { isWindowExpression } from '../../../sql/expression-utils';
 import { identityKeyFor } from '../../../query-engine/identity-key';
-import { activityReads, groupIndexForResponse, NO_READS, readsFor, readsForResponse, rendererForMark } from '../../rendering/activity-reads';
+import { activityReads, dimsBySelection, groupIndexForResponse, NO_READS, readsFor, readsForResponse, rendererForMark } from '../../rendering/activity-reads';
 import { AdaptiveBinRung } from '../../../lod/AdaptiveBinRung.svelte';
 /** A SQL identifier, quoted, with any double quote in it doubled. */
 function ident(name) {
@@ -143,13 +143,10 @@ export class MarkLifecycleV2 {
         // Resolve AutoBinNodes — reads #fieldStats ($state), #lastBinDomain ($state),
         // binStepMultiplier (reactive on chartContext)
         if (this.#autoBinNodes.size > 0 && this.#fieldStats) {
-            const binStepMultiplier = this.#chartContext.binStepMultiplier || 1.0;
             for (const [ch, value] of Object.entries(resolvedSelect)) {
                 if (isBinExpression(value)) {
-                    const axis = ch.startsWith('x') ? 'x' : 'y';
-                    const scaleType = axis === 'x' ? this.actualXScaleType : this.actualYScaleType;
-                    const currentDomain = this.#lastBinDomain[axis] ?? null;
-                    resolvedSelect[ch] = value.resolve(this.#fieldStats, scaleType, null, currentDomain, binStepMultiplier);
+                    const { fieldInfo, scaleType, currentDomain, multiplier } = this.#binArgs(ch);
+                    resolvedSelect[ch] = value.resolve(fieldInfo, scaleType, null, currentDomain, multiplier);
                 }
             }
         }
@@ -189,8 +186,40 @@ export class MarkLifecycleV2 {
         const nullDrops = this.#nullDrops(semanticSelect, resolvedSelect);
         if (nullDrops.length > 0)
             parts.nullDrops = nullDrops;
+        parts.bins = this.#binPadding();
         return parts;
     });
+    /**
+     * What a bin channel resolves with: the field's stats, the axis's scale
+     * type and last re-bin domain, and the chart's step multiplier. One place,
+     * so the bin expression and its padding cannot be resolved differently.
+     * Reactive reads, from the deriveds that call it.
+     */
+    #binArgs(channel) {
+        const axis = channel.startsWith('x') ? 'x' : 'y';
+        return {
+            axis,
+            fieldInfo: this.#fieldStats,
+            scaleType: axis === 'x' ? this.actualXScaleType : this.actualYScaleType,
+            currentDomain: this.#lastBinDomain[axis] ?? null,
+            multiplier: this.#chartContext.binStepMultiplier || 1.0
+        };
+    }
+    /** The bins of each numeric bin channel, for dense() to pad from; null without any. */
+    #binPadding() {
+        if (this.#autoBinNodes.size === 0 || !this.#fieldStats)
+            return null;
+        let out = null;
+        for (const [ch, value] of Object.entries(this.#config.select)) {
+            if (!isBinExpression(value))
+                continue;
+            const { axis, fieldInfo, scaleType, currentDomain, multiplier } = this.#binArgs(ch);
+            const padding = value.padding(fieldInfo, scaleType, currentDomain, multiplier, this.#timeOrigin(axis));
+            if (padding)
+                (out ??= {})[ch] = padding;
+        }
+        return out;
+    }
     /**
      * The mark's categorical channels, each with the source expression it draws:
      * a band or point axis, an ordinal colour, a separate series, and the facet
@@ -277,9 +306,27 @@ export class MarkLifecycleV2 {
     // --- Tooltip ---
     #tooltipTableName;
     #tooltipTableReady = $state(false);
+    /**
+     * True once a tooltip table write has started, so there may be a table to
+     * drop. Without it every lifecycle torn down before its first data (a mark
+     * that unmounts early, a rebuild) sent DuckDB a DROP for a table that never
+     * existed, one more statement in the single worker's queue during load.
+     */
+    #tooltipTableWritten = false;
     #tooltipWriteTimeout = null;
     // --- fitDomain ---
     #fitDomainTimeout = null;
+    /**
+     * The data version whose fit snaps instead of springing: the version the
+     * chart came back into view with, or its catch-up result's. A spring means
+     * the user just caused the change; a return to view is not that. Tied to a
+     * version rather than a flag waiting for the next fit: a fit issued for any
+     * other reason (a driving-axis zoom, later data) or skipped clears it, and
+     * a superseded fit for the same version keeps it.
+     */
+    #snapFitVersion = null;
+    /** Debounces a refit after a data change (#refitFromData). */
+    #refitTimeout = null;
     #fitDomainLastTarget = [0, 0];
     #fitDomainQuerySequence = 0;
     #fitDomainSuppressed = false;
@@ -292,6 +339,14 @@ export class MarkLifecycleV2 {
         this.#chartContext = chartContext;
         this.#markId = markId;
         this.#filterGroup = filterGroup;
+        // The chart's entrance waits for this mark's first data, unless the
+        // author has said not to (a mark known to be slow). Held by mark id, so
+        // a lifecycle rebuilt for the same mark holds the same hold. Released on
+        // first data, on failure, or when the mark unmounts.
+        this.#entranceGate = chartContext.config?.entrance ?? null;
+        if (config.table && untrack(() => reactiveConfig.holdsEntrance) !== false) {
+            this.#entranceGate?.hold(markId);
+        }
         // Tooltip table name
         this.#tooltipTableName = `_tt_${this.#markId.replace(/-/g, '_')}`;
         // Transform compiler
@@ -327,6 +382,7 @@ export class MarkLifecycleV2 {
             identity: () => this.#identity,
             identityKey: (axis) => this.#identityKey(axis)?.key ?? null,
             filtered: () => this.#reactiveConfig.selectionResponse === 'filter',
+            dims: () => dimsBySelection(this.#reactiveConfig.selectionResponse),
             plan: () => this.#splitPlan,
             colorKey: () => {
                 const color = this.#colorScaleState;
@@ -503,7 +559,20 @@ export class MarkLifecycleV2 {
             const scalesReady = (!this.#config.select?.[colorKey] || !!this.#colorScaleState) &&
                 (!seriesKey || seriesKey === colorKey || !!this.#seriesScaleState);
             untrack(() => {
-                this.#runSetup(scalesReady);
+                // A run already in flight against these same scales would produce
+                // the same result: don't send its queries again. A different scale
+                // starts a new run, and the generation guard retires the old one.
+                const inputs = [
+                    xScaleState,
+                    yScaleState,
+                    this.#colorScaleState,
+                    this.#seriesScaleState,
+                    scaleTypes.x,
+                    scaleTypes.y
+                ];
+                if (scalesReady && this.#setupInFlight && sameInputs(this.#setupInFlight, inputs))
+                    return;
+                this.#runSetup(scalesReady, inputs);
             });
         });
         // Registration: watches #resolvedQueryParts, registers with engine.
@@ -534,10 +603,37 @@ export class MarkLifecycleV2 {
                     parts,
                     schema,
                     transformCompiler: this.#transformCompiler,
-                    route: this.#route
+                    route: this.#route,
+                    // holdsEntrance={false}: the author knows this mark is slow.
+                    slow: this.#reactiveConfig.holdsEntrance === false
                 }, this.#filterGroup);
             });
         });
+        // Off screen, the engine stops re-querying this mark (after its first
+        // result) and queries it once when it is back; see MarkHandle.active.
+        //
+        // The one owner of a return to view. A fitted axis may have moved
+        // meanwhile (a shared axis zoomed from another chart), and the fit
+        // effects do not run off screen. If the mark came back stale, its
+        // catch-up result refits like any data change (#refitFromData, or
+        // #onTooltipTableWritten with JS transforms). Refitting here as well
+        // would fit to the old data first, then to the new: two fits.
+        // Otherwise its data is current and nothing else will refit, so
+        // refit now.
+        $effect(() => {
+            const handle = this.#handle;
+            const visible = this.#chartContext.visible ?? true;
+            if (!handle)
+                return;
+            untrack(() => {
+                const cameBack = visible && !handle.active;
+                const caughtUp = handle.setActive(visible);
+                if (!visible)
+                    this.#snapFitVersion = null;
+                if (cameBack && !caughtUp)
+                    this.#refitOnReturn();
+            });
+        });
         // Push per-mark params and trigger query. Runs immediately after
         // registration (Svelte flushes effects in creation order), providing
         // the initial query. On subsequent changes to sort/limit,
@@ -573,8 +669,16 @@ export class MarkLifecycleV2 {
             untrack(() => {
                 this.#handleDataDomains(dv);
                 this.otherRows.register();
+                // After the domains: the last release opens the gate, and the
+                // scales snap to every mark's extent only until then.
+                this.#releaseEntrance();
             });
         });
+        // A failed query has nothing to enter with; it must not hold the chart.
+        $effect(() => {
+            if (this.#handle?.error)
+                untrack(() => this.#releaseEntrance());
+        });
         // Tooltip: two effects, so a data update does not take the table away.
         //
         // This one owns the table's lifetime: it drops it when tooltips go from
@@ -592,11 +696,24 @@ export class MarkLifecycleV2 {
             return () => {
                 clearTimeout(this.#tooltipWriteTimeout);
                 this.#tooltipTableReady = false;
-                this.#queryEngine.exec(`DROP TABLE IF EXISTS "${this.#tooltipTableName}"`).catch(() => { });
+                this.#dropTooltipTable();
             };
         });
-        // And this one rewrites it when data updates (debounced). The old table
-        // stays readable until the rewrite replaces it.
+        // And this one rewrites it when data updates, but only when someone may
+        // hover it. The table is a second scan of the mark's data, often with a
+        // sort, and nobody hovers most charts after most changes (at load, or
+        // while another chart is brushed), so a write per data change was the
+        // largest cost after a table load.
+        //
+        // - The chart hovered: written after the data settles (debounced), as
+        //   before. The old table stays readable until the rewrite replaces it,
+        //   so a click right after a data update still finds its row.
+        // - Not hovered: the table is marked stale (not ready), which takes the
+        //   mark out of the tooltip manager, so no lookup reads old rows. It is
+        //   written when the pointer enters the chart, at once, as interaction:
+        //   it is what the first hover waits for.
+        // - fitDomain on a mark with JS transforms reads the table to fit
+        //   (#buildFitDomainQuery), so that mark writes eagerly, in background.
         $effect(() => {
             const tooltipConfig = this.#reactiveConfig.tooltip;
             const fitDomain = this.#reactiveConfig.fitDomain;
@@ -605,16 +722,71 @@ export class MarkLifecycleV2 {
             const dataVersion = this.dataVersion;
             if (dataVersion === 0)
                 return;
+            const hovered = this.#chartContext.hovered ?? true;
+            const eager = !!fitDomain && this.#transformCompiler.hasJSTransforms();
             untrack(() => {
+                if (dataVersion === this.#tooltipWrittenFor)
+                    return;
                 clearTimeout(this.#tooltipWriteTimeout);
-                this.#tooltipWriteTimeout = setTimeout(() => {
+                // A data change waits for the data to settle; hover arriving at a
+                // stale table writes at once.
+                const dataChanged = dataVersion !== this.#tooltipSeenVersion;
+                this.#tooltipSeenVersion = dataVersion;
+                if (!hovered && !eager) {
+                    this.#tooltipTableReady = false;
+                    return;
+                }
+                const cls = eager && !hovered ? 'background' : 'interaction';
+                const write = () => {
                     const data = this.data;
-                    if (data && data.length > 0)
-                        this.#writeTooltipTable(data);
-                }, 300);
+                    if (!data || data.length === 0)
+                        return;
+                    this.#tooltipWrittenFor = dataVersion;
+                    this.#writeTooltipTable(data, cls);
+                };
+                // Sent from this effect, not a timer, so it goes out before a preagg
+                // build the same pointer enter queues (see Preagg.activate).
+                // A catch-up result is one result, with nothing to settle.
+                const catchUp = this.#handle?.resultCause === 'catchUp';
+                if (dataChanged && !catchUp)
+                    this.#tooltipWriteTimeout = setTimeout(write, 300);
+                else
+                    write();
             });
             return () => clearTimeout(this.#tooltipWriteTimeout);
         });
+        // fitDomain after a data change (a brush on another chart, the first
+        // result): refit, debounced like the data settling. Marks with JS
+        // transforms refit after their tooltip table is written instead, which
+        // their fit reads (#onTooltipTableWritten). Off screen, like the mark's
+        // re-queries: the return to view refits (#refitOnReturn).
+        $effect(() => {
+            const fitDomain = this.#reactiveConfig.fitDomain;
+            if (!fitDomain)
+                return;
+            const dataVersion = this.dataVersion;
+            if (dataVersion === 0)
+                return;
+            // Untracked: a return to view refits from the setActive effect, which
+            // knows whether a catch-up result is coming.
+            if (!untrack(() => this.#chartContext.visible ?? true))
+                return;
+            // A catch-up result's fit snaps, and has no data to wait for.
+            const catchUp = untrack(() => this.#handle?.resultCause === 'catchUp');
+            this.#snapFitVersion = catchUp ? dataVersion : null;
+            // With JS transforms the fit reads the tooltip table, and a data change
+            // refits after its write (#onTooltipTableWritten).
+            if (this.#transformCompiler.hasJSTransforms())
+                return;
+            untrack(() => {
+                clearTimeout(this.#refitTimeout);
+                if (catchUp)
+                    this.#refitFromData();
+                else
+                    this.#refitTimeout = setTimeout(() => this.#refitFromData(), 300);
+            });
+            return () => clearTimeout(this.#refitTimeout);
+        });
         // fitDomain — query DuckDB for fitted axis extent on driving axis change.
         $effect(() => {
             const fitDomain = this.#reactiveConfig.fitDomain;
@@ -635,6 +807,16 @@ export class MarkLifecycleV2 {
             const fittedSS = fittedAxis === 'x' ? this.#chartContext.xScaleState : this.#chartContext.yScaleState;
             const fittedUserDriven = fittedSS?.userDriven ?? false;
             const drivingUserDriven = drivingSS.userDriven;
+            // Off screen, like the mark's re-queries (MarkHandle.active): no fit.
+            // Read untracked: the return to view fits once (#refitOnReturn, or
+            // the catch-up result), at the driving axis's domain then; tracking
+            // it here too sent a second fit for the same return. Checked only
+            // AFTER the driving domain is read: an effect re-runs on what its last
+            // run read, so returning before that left the effect deaf to the
+            // driving axis after any run off screen, and brushes made once the
+            // chart was back on screen sent no fit at all.
+            if (!untrack(() => this.#chartContext.visible ?? true))
+                return;
             if (fittedSS) {
                 fittedSS.fitDomainActive = true;
             }
@@ -645,6 +827,9 @@ export class MarkLifecycleV2 {
                 if (this.#fitDomainSuppressed && !drivingUserDriven) {
                     this.#fitDomainSuppressed = false;
                 }
+                // The driving axis moved: whatever fit follows is that zoom's, and
+                // springs.
+                this.#snapFitVersion = null;
                 if (this.#fitDomainSuppressed)
                     return;
                 clearTimeout(this.#fitDomainTimeout);
@@ -657,7 +842,11 @@ export class MarkLifecycleV2 {
     // ===========================================================================
     // PHASE 1: SETUP
     // ===========================================================================
-    async #runSetup(colorReady) {
+    /** Bumped by each setup run that queries; see #runSetup. */
+    #setupGeneration = 0;
+    /** The scales the latest querying setup run started with, while it is in flight. */
+    #setupInFlight = null;
+    async #runSetup(colorReady, inputs) {
         if (this.#destroyed)
             return;
         // Wait for the colour scale — and the series scale, which takes a dim the
@@ -693,9 +882,30 @@ export class MarkLifecycleV2 {
         // a chart that was never going to get a colour scale.
         if (!colorReady)
             return;
+        // The setup effect re-enters whenever a scale it reads settles, and an
+        // earlier run may still be awaiting its queries. Only the latest run
+        // may finish: a superseded one stops after its await, so it cannot
+        // register domains on a scale that has since been replaced, nor set
+        // setupComplete from stale scale state. Its queries are already sent.
+        const generation = ++this.#setupGeneration;
+        const superseded = () => this.#destroyed || generation !== this.#setupGeneration;
+        this.#setupInFlight = inputs;
+        try {
+            await this.#runSetupQueries(superseded);
+        }
+        finally {
+            if (generation === this.#setupGeneration)
+                this.#setupInFlight = null;
+        }
+    }
+    /** The querying part of #runSetup; `superseded` says a later run has started. */
+    async #runSetupQueries(superseded) {
         // Passive scales: skip domain fetching but still need schema for CAST decisions
         if (this.#config.passiveScales) {
-            this.#schema = buildSchemaMap(await this.#queryEngine.describe(this.#config.table));
+            const columns = await this.#queryEngine.describe(this.#config.table);
+            if (superseded())
+                return;
+            this.#schema = buildSchemaMap(columns);
             setScalesReady(this.#scaleMap, this.#channelsNeedingDataDomain, this.actualXScaleType, this.actualYScaleType, false, false);
             this.setupComplete = true;
             return;
@@ -709,12 +919,12 @@ export class MarkLifecycleV2 {
             const [schemaColumns, fetchCount, aggResult, fieldStats] = await Promise.all([
                 // Fetch table schema (cached on QueryEngine, needed for CAST type decisions)
                 this.#queryEngine.describe(this.#config.table),
-                fetchCategoricalDomains(this.#queryEngine, this.#config.table, this.#config.select, this.actualXScaleType, this.actualYScaleType, this.#bandScaleForDomain('x'), this.#bandScaleForDomain('y'), this.#chartContext.facetBandScale, this.#chartContext.fx, this.#config.colorChannel || 'fill', this.#colorScaleState, this.#config.sizeChannel || 'r', this.#sizeScaleState, this.#seriesScaleState, seriesKey, this.#bandDomainFromData, this.#markId, this.#reactiveConfig.domain, this.#reactiveConfig.nulls === 'drop'),
-                fetchGlobalAggregates(this.#queryEngine, this.#config.table, this.#config.select, this.#channelsNeedingDataDomain, this.#autoBinNodes.size, this.#buildQueryForAggregates.bind(this), this.#config, this.#chartContext.xScaleState, this.#chartContext.yScaleState, this.#colorScaleState, this.#markId),
+                fetchCategoricalDomains(this.#queryEngine, this.#config.table, this.#config.select, this.actualXScaleType, this.actualYScaleType, this.#bandScaleForDomain('x'), this.#bandScaleForDomain('y'), this.#chartContext.facetBandScale, this.#chartContext.fx, this.#config.colorChannel || 'fill', this.#colorScaleState, this.#config.sizeChannel || 'r', this.#sizeScaleState, this.#seriesScaleState, seriesKey, this.#bandDomainFromData, this.#markId, this.#reactiveConfig.domain, this.#reactiveConfig.nulls === 'drop', superseded),
+                fetchGlobalAggregates(this.#queryEngine, this.#config.table, this.#config.select, this.#channelsNeedingDataDomain, this.#autoBinNodes.size, this.#buildQueryForAggregates.bind(this), this.#config, this.#chartContext.xScaleState, this.#chartContext.yScaleState, this.#colorScaleState, this.#markId, superseded),
                 this.#fetchFieldStats(),
                 this.#ensureIdentityColumns()
             ]);
-            if (this.#destroyed)
+            if (superseded())
                 return;
             this.#schema = buildSchemaMap(schemaColumns);
             if (aggResult.globalAggregatesSet)
@@ -735,8 +945,15 @@ export class MarkLifecycleV2 {
             if (error?.name === 'AbortError')
                 return;
             console.error(`[MarkLifecycleV2] Setup failed for ${this.#markId}:`, error);
+            this.#releaseEntrance();
         }
     }
+    /** The chart's entrance gate, or null outside a chart (tests). */
+    #entranceGate = null;
+    /** Stop holding the chart's entrance. Idempotent: the gate ignores a second. */
+    #releaseEntrance() {
+        this.#entranceGate?.release(this.#markId);
+    }
     // ===========================================================================
     // QUERY HELPERS
     // ===========================================================================
@@ -832,13 +1049,10 @@ export class MarkLifecycleV2 {
             ['x', ['x', 'x1', 'x2']],
             ['y', ['y', 'y1', 'y2']]
         ]) {
-            const scaleType = axis === 'x' ? this.actualXScaleType : this.actualYScaleType;
-            if (scaleType !== 'time')
+            const t0Epoch = this.#timeOrigin(axis);
+            if (t0Epoch === null)
                 continue;
             const scaleState = this.#chartContext[`${axis}ScaleState`];
-            if (!scaleState?.t0)
-                continue;
-            const t0Epoch = Math.floor(scaleState.t0.getTime() / 1000);
             for (const ch of channels) {
                 if (!(ch in select))
                     continue;
@@ -854,6 +1068,20 @@ export class MarkLifecycleV2 {
             }
         }
     }
+    /**
+     * The time axis's origin in epoch seconds, which its channels are drawn
+     * relative to, or null when the axis is not a time scale or has no origin
+     * yet. Its channels are rewritten, and its time buckets padded, only with one.
+     */
+    #timeOrigin(axis) {
+        const scaleType = axis === 'x' ? this.actualXScaleType : this.actualYScaleType;
+        if (scaleType !== 'time')
+            return null;
+        const scaleState = this.#chartContext[`${axis}ScaleState`];
+        if (!scaleState?.t0)
+            return null;
+        return Math.floor(scaleState.t0.getTime() / 1000);
+    }
     /**
      * Fetch MIN/MAX stats for continuous scale fields.
      * Replaces Mosaic's queryFieldInfo (old Effect 5 fieldInfo path).
@@ -922,7 +1150,8 @@ export class MarkLifecycleV2 {
             }
         }
         const q = Query.from(this.#config.table).select(selectDef);
-        const result = await this.#queryEngine.query(q);
+        // Shared and cached: marks on one table ask the same ranges (see QueryOpts.cache).
+        const result = await this.#queryEngine.query(q, { cache: true, source: this.#config.table });
         const row = result.get(0);
         if (!row)
             return null;
@@ -969,8 +1198,7 @@ export class MarkLifecycleV2 {
             const additionalChannels = this.#transformCompiler.getAdditionalChannels();
             const xState = this.#chartContext.xScaleState;
             const yState = this.#chartContext.yScaleState;
-            const domainResult = registerDataDerivedDomains(data, this.#channelsNeedingDataDomain, additionalChannels, this.#skipDomainUpdateForAxis, this.#config.zeroBaseline, this.actualXScaleType, this.actualYScaleType, xState, yState, this.#bandDomainFromData, this.#bandScaleForDomain('x'), this.#bandScaleForDomain('y'), this.#markId, false, // isRebinning
-            this.#colorScaleState);
+            const domainResult = registerDataDerivedDomains(data, this.#channelsNeedingDataDomain, additionalChannels, this.#skipDomainUpdateForAxis, this.#config.zeroBaseline, this.actualXScaleType, this.actualYScaleType, xState, yState, this.#bandDomainFromData, this.#bandScaleForDomain('x'), this.#bandScaleForDomain('y'), this.#markId, this.#instantFor, this.#colorScaleState);
             this.#dataDerivedDomainsSet = domainResult.dataDerivedDomainsSet;
             this.#skipDomainUpdateForAxis = domainResult.skipDomainUpdateForAxis;
             markDeferredScalesReady(this.#scaleMap, this.#channelsNeedingDataDomain, this.actualXScaleType, this.actualYScaleType);
@@ -1084,6 +1312,13 @@ export class MarkLifecycleV2 {
         // the view. Failing here gives a message naming the mark and the fields;
         // continuing would fail at the binder with neither.
         await this.#queryEngine.ensureColumns(this.#config.table, { categorical });
+        // Torn down while the dims were built: the scales below may have been
+        // dropped with a ChartScales the chart has since replaced. Only a
+        // destroyed lifecycle, not a superseded setup run: identity goes to the
+        // scales read live from the chart context, so a live run handing it
+        // over is harmless.
+        if (this.#destroyed)
+            return;
         for (const { key } of categorical)
             this.#identityFields.add(key);
         // Tell the transforms which dim each categorical channel is identified by.
@@ -1330,6 +1565,11 @@ export class MarkLifecycleV2 {
      * never mixed, the other axis's channels morph, and the band scale owns the
      * clock both run on.
      *
+     * A histogram's binned axis aligns too: one row per bin, in bin order. Its
+     * channels are bin edges rather than ids, still never mixed, and with no
+     * slot clock on a linear scale the mark's channels run on a clock of their
+     * own.
+     *
      * The first channel of the transforms' alignment — `dense()`'s plan, over the
      * same select and facts its `apply()` sees — so the conditions are written
      * once. Derived rather than recorded at apply time: apply runs for every
@@ -1343,10 +1583,13 @@ export class MarkLifecycleV2 {
         void this.#identity;
         // Asked exactly as assembleQuery asks when it orders the query, so this and
         // the rows cannot disagree about which channel they are aligned on.
-        const band = this.#transformCompiler.alignment(Object.keys(parts.selectDef), {
-            groupKeys: parts.groupKeys
+        const aligned = this.#transformCompiler.alignment(Object.keys(parts.selectDef), {
+            groupKeys: parts.groupKeys,
+            bins: parts.bins ?? null
         })?.[0];
-        return band === 'x' || band === 'y' ? band : null;
+        // A band is `x` or `y`; a binned axis aligns on its lower edge, `x1`.
+        const axis = aligned?.[0];
+        return axis === 'x' || axis === 'y' ? axis : null;
     });
     /**
      * Build a query for fetchGlobalAggregates.
@@ -1421,9 +1664,10 @@ export class MarkLifecycleV2 {
     // --- Selection routing ---
     /**
      * The identity keys of the categorical fields this mark's renderer reads
-     * selection activity for, sorted: its ordinal colour and its band axes, as
-     * activity-reads.ts says the renderer reads them. A categorical selection on
-     * one of these dims the mark; on any other field it filters it.
+     * selection activity for, sorted: its ordinal colour, its band axes and a
+     * line's or area's own `z`, as activity-reads.ts says the renderer reads
+     * them. A categorical selection on one of these dims the mark; on any other
+     * field it filters it.
      */
     #reads = $derived.by(() => {
         const renderer = rendererForMark(this.#config.markType);
@@ -1437,10 +1681,15 @@ export class MarkLifecycleV2 {
             const band = this.#chartContext[`${axis}ScaleState`];
             return band?.identityKey ?? null;
         };
+        // The series is a field of its own only on a separate channel (`z`);
+        // without one, the series channel is the colour channel, read above.
+        const seriesChannel = this.#config._orderConfig?.seriesChannel ?? null;
+        const ownSeries = !!seriesChannel && seriesChannel !== (this.#config.colorChannel || 'fill');
         return readsForResponse(this.#reactiveConfig.selectionResponse, readsFor(activityReads(renderer, this.#config.ruleExtent ?? false), {
             color: color?.isOrdinal ? color.identityKey : null,
             x: bandKey('x'),
-            y: bandKey('y')
+            y: bandKey('y'),
+            series: ownSeries ? (this.#seriesScaleState?.identityKey ?? null) : null
         }));
     });
     /** `#reads` as one string, so the registration effect re-runs only on a real change. */
@@ -1455,6 +1704,24 @@ export class MarkLifecycleV2 {
         // NO_GROUP for selectionResponse 'filter', which never dims.
         return groupIndexForResponse(this.#reactiveConfig.selectionResponse, this.#filterGroup.index);
     }
+    /**
+     * The data version that lands without animating, or 0: a catch-up result
+     * (the chart came back into view stale), a change nobody just made. A
+     * version, not a flag: the cause stays set until the next result, and a
+     * renderer lands only its FIRST write of this version. Later writes of the
+     * same data (an Other split on a click, a JS transform's parameter) are
+     * changes someone just made, and animate. Reactive through `dataVersion`,
+     * which the cause is set with.
+     */
+    get landsFor() {
+        return this.#handle?.resultCause === 'catchUp' ? this.dataVersion : 0;
+    }
+    /**
+     * Whether a scale's change from the current result lands at once: a
+     * catch-up result, on a scale no other visible chart draws. Asked as the
+     * result is applied, since visibility moves during a scroll.
+     */
+    #instantFor = (scale) => this.#handle?.resultCause === 'catchUp' && !this.#chartContext.shownElsewhere(scale);
     get dataVersion() {
         return this.#handle?.dataVersion ?? 0;
     }
@@ -1600,8 +1867,14 @@ export class MarkLifecycleV2 {
     // ===========================================================================
     // TOOLTIP WRITE-BACK
     // ===========================================================================
-    async #writeTooltipTable(data) {
+    /** The data version the tooltip table was last written for. */
+    #tooltipWrittenFor = -1;
+    /** The data version the write effect last saw, to tell a data change from a hover. */
+    #tooltipSeenVersion = -1;
+    async #writeTooltipTable(data, cls) {
         const tableName = this.#tooltipTableName;
+        // Before any statement: a write that fails part way can leave a table.
+        this.#tooltipTableWritten = true;
         try {
             if (!this.#transformCompiler.hasJSTransforms()) {
                 // Path A: Build a query with original field names (not CAST-wrapped).
@@ -1644,11 +1917,17 @@ export class MarkLifecycleV2 {
                     replaceExprs.push(`CAST(${c} AS DOUBLE) AS ${c}`);
                 }
                 const replaceClause = replaceExprs.length > 0 ? ` REPLACE (${replaceExprs.join(', ')})` : '';
-                // Optional ORDER BY for zone-map skipping in bounding-box queries.
+                // ORDER BY x, so a hover lookup's bounding box could skip row groups
+                // (zone maps): only when asked (`tooltip: { sortTable: true }`). Since
+                // lazy writes the sort is hover latency, and the lookups did not get
+                // faster for it. Measured on a scatter, sorted against unsorted:
+                // 200k rows, write 41 against 12 ms, lookup median 2.2 against 2.9 ms;
+                // 2M rows (17 row groups), write 273 against 70 ms, lookup median 11.3
+                // against 11.4 ms, p90 35 against 30 ms. The lookup's box is wide and
+                // holds most of the cost on dense data, sorted or not.
                 let orderClause = '';
-                const tooltipSortTable = typeof this.#reactiveConfig.tooltip === 'object'
-                    ? this.#reactiveConfig.tooltip.sortTable !== false
-                    : true;
+                const tooltipSortTable = typeof this.#reactiveConfig.tooltip === 'object' &&
+                    this.#reactiveConfig.tooltip.sortTable === true;
                 if (tooltipSortTable) {
                     const orderCol = ['x', 'x1', 'x2'].find((c) => c in selectConfig);
                     if (orderCol)
@@ -1661,7 +1940,7 @@ export class MarkLifecycleV2 {
                 // lists are the only ones whose size grows with the field.
                 const withoutMembers = withoutOtherMembers(tooltipQuery);
                 // One statement: a hover query never finds the table missing.
-                await this.#queryEngine.exec(`CREATE OR REPLACE TEMP TABLE "${tableName}" AS SELECT *${replaceClause} FROM (${withoutMembers})${orderClause}`);
+                await this.#queryEngine.exec(`CREATE OR REPLACE TEMP TABLE "${tableName}" AS SELECT *${replaceClause} FROM (${withoutMembers})${orderClause}`, { class: cls, connectionLocal: true });
             }
             else {
                 // Path B: Serialize transformed data via SQL VALUES.
@@ -1703,13 +1982,13 @@ export class MarkLifecycleV2 {
                     `DROP TABLE IF EXISTS "${tableName}"`,
                     `CREATE TEMP TABLE "${tableName}" (${schemaDef})`,
                     `INSERT INTO "${tableName}" VALUES ${valueRows.join(', ')}`
-                ]);
+                ], { class: cls, connectionLocal: true });
             }
             // Merge tip expression extras (aggregates/windows) via sidecar query.
             const tipExtras = this.#getTipExtras();
             if (Object.keys(tipExtras).length > 0) {
                 try {
-                    await this.#mergeTipExtras(tableName, tipExtras);
+                    await this.#mergeTipExtras(tableName, tipExtras, cls);
                 }
                 catch (err) {
                     console.warn('Failed to merge tip extras into tooltip table:', err);
@@ -1772,7 +2051,7 @@ export class MarkLifecycleV2 {
      * DB query. Computes aggregates against the source table using the same
      * GROUP BY as the main query, then ALTER+UPDATE the temp table.
      */
-    async #mergeTipExtras(tableName, tipExtras) {
+    async #mergeTipExtras(tableName, tipExtras, cls) {
         if (!this.#resolvedQueryParts)
             return;
         // Identify non-aggregate channel columns — these are the join keys
@@ -1810,7 +2089,10 @@ export class MarkLifecycleV2 {
             .map((ch) => `${ident(tableName)}.${ident(ch)} = _s.${ident(ch)}`)
             .join(' AND ');
         const updateStmt = `UPDATE ${ident(tableName)} SET ${setClauses} FROM (${sidecarQuery.toString()}) _s WHERE ${joinCondition}`;
-        await this.#queryEngine.exec([...alterStmts, updateStmt]);
+        await this.#queryEngine.exec([...alterStmts, updateStmt], {
+            class: cls,
+            connectionLocal: true
+        });
     }
     // ===========================================================================
     // FIT DOMAIN
@@ -1843,7 +2125,9 @@ export class MarkLifecycleV2 {
         }
         return channels;
     }
-    async #issueFitDomainQuery(fittedAxis, drivingDomain, force = false) {
+    async #issueFitDomainQuery(fittedAxis, drivingDomain, force = false, 
+    /** A return-to-view fit (#snapFitVersion): lands without a spring. */
+    snap = false) {
         if (!force && drivingDomain) {
             const [lastLo, lastHi] = this.#fitDomainLastTarget;
             const lastWidth = lastHi - lastLo;
@@ -1862,7 +2146,11 @@ export class MarkLifecycleV2 {
                 return;
             const result = await this.#queryEngine.query(q.toString(), {
                 callerId: `${this.#markId}:fitDomain`,
-                cache: false
+                cache: false,
+                // With JS transforms the fit reads the TEMP tooltip table;
+                // otherwise the mark's base table, routed by it.
+                connectionLocal: this.#transformCompiler.hasJSTransforms(),
+                source: this.#config.table
             });
             if (seq !== this.#fitDomainQuerySequence)
                 return;
@@ -1887,11 +2175,14 @@ export class MarkLifecycleV2 {
             }
             const scaleState = fittedAxis === 'x' ? this.#chartContext.xScaleState : this.#chartContext.yScaleState;
             const scaleType = fittedAxis === 'x' ? this.actualXScaleType : this.actualYScaleType;
+            // Asked as it lands: a chart in view that shares the axis keeps the
+            // spring, and everything on the axis moves together through it.
+            const instant = snap && !!scaleState && !this.#chartContext.shownElsewhere(scaleState);
             if (scaleType === 'time' && scaleState && 'addOffsetExtent' in scaleState) {
-                scaleState.addOffsetExtent([lo, hi], this.#markId);
+                scaleState.addOffsetExtent([lo, hi], this.#markId, { instant });
             }
             else if (scaleState && 'addMark' in scaleState) {
-                scaleState.addMark([lo, hi], this.#markId);
+                scaleState.addMark([lo, hi], this.#markId, { instant });
             }
             if (drivingDomain)
                 this.#fitDomainLastTarget = [...drivingDomain];
@@ -1958,15 +2249,32 @@ export class MarkLifecycleV2 {
         return q;
     }
     /**
-     * Called after tooltip table is written. If fitDomain is active, issue a
-     * sidecar MIN/MAX query against the fresh tooltip table.
+     * A tooltip table was written. A fit over a mark with JS transforms reads that
+     * table (#buildFitDomainQuery), so its refit after a data change waits for
+     * the write; every other fit refits from the data itself (#refitFromData).
      */
     #onTooltipTableWritten() {
+        if (this.#transformCompiler.hasJSTransforms())
+            this.#refitFromData();
+    }
+    /**
+     * Refit the fitted axis to the mark's current data, at the driving axis's
+     * current domain. The data-driven trigger: the fitDomain effect reacts to the
+     * driving axis, not to new data, and returns for a band driving axis, so this
+     * is also a band-driven fit's only trigger, its first fit included.
+     */
+    #refitFromData() {
         const fitDomain = this.#reactiveConfig.fitDomain;
         if (!fitDomain)
             return;
+        // The fit for the snap's version, if this is it; a refit for any other
+        // version springs, and a skipped one gives the snap up.
+        const snap = this.#snapFitVersion !== null && this.#snapFitVersion === this.dataVersion;
+        this.#snapFitVersion = null;
         if (this.#fitDomainSuppressed)
             return;
+        if (snap)
+            this.#snapFitVersion = this.dataVersion;
         const fittedAxis = this.#resolveFittedAxis(fitDomain);
         if (!fittedAxis)
             return;
@@ -1975,19 +2283,37 @@ export class MarkLifecycleV2 {
         if (!drivingSS)
             return;
         if (drivingSS.scaleType === 'band') {
-            this.#issueFitDomainQuery(fittedAxis, null, true);
+            this.#issueFitDomainQuery(fittedAxis, null, true, snap);
             return;
         }
         const target = drivingSS.domain?.target;
         if (!target)
             return;
-        this.#issueFitDomainQuery(fittedAxis, target, true);
+        this.#issueFitDomainQuery(fittedAxis, target, true, snap);
+    }
+    /**
+     * The chart came back into view with current data: fit to the driving
+     * axis as it is now. Not debounced, since no data is settling. With JS
+     * transforms the fit reads the tooltip table; if its write is still
+     * pending, #onTooltipTableWritten fits after it instead.
+     */
+    #refitOnReturn() {
+        if (!this.#reactiveConfig.fitDomain || this.dataVersion === 0)
+            return;
+        this.#snapFitVersion = this.dataVersion;
+        if (this.#transformCompiler.hasJSTransforms() && !this.#tooltipTableReady)
+            return;
+        clearTimeout(this.#refitTimeout);
+        this.#refitFromData();
     }
     // ===========================================================================
     // CLEANUP
     // ===========================================================================
     destroy() {
         this.#destroyed = true;
+        // Not releasing the entrance here: a mark rebuilds its lifecycle when
+        // its scales resolve, and the rebuilt one re-holds the same id. The
+        // mark's unmount releases it (ChartConfig.unregisterMark).
         this.#identityResetOff?.();
         this.#identityResetOff = null;
         this.otherRows.unregister();
@@ -1995,6 +2321,7 @@ export class MarkLifecycleV2 {
             this.#releaseOther(scale);
         this.#handle?.destroy();
         clearTimeout(this.#fitDomainTimeout);
+        clearTimeout(this.#refitTimeout);
         clearTimeout(this.#tooltipWriteTimeout);
         if (this.#onMarkLOD) {
             this.#chartContext.config.unregisterMarkLOD(this.#markId);
@@ -2010,6 +2337,23 @@ export class MarkLifecycleV2 {
         // where destroy() is called synchronously before Svelte processes
         // effect teardown.
         this.#tooltipTableReady = false;
-        this.#queryEngine.exec(`DROP TABLE IF EXISTS "${this.#tooltipTableName}"`).catch(() => { });
+        this.#dropTooltipTable();
+    }
+    #dropTooltipTable() {
+        if (!this.#tooltipTableWritten)
+            return;
+        this.#tooltipTableWritten = false;
+        this.#queryEngine
+            .exec(`DROP TABLE IF EXISTS "${this.#tooltipTableName}"`, {
+            class: 'background',
+            // A TEMP table on the main connection, written and dropped only
+            // there, so a drop cannot overtake the next lifecycle's write.
+            connectionLocal: true
+        })
+            .catch(() => { });
     }
 }
+/** Same scale states and types, compared by identity. */
+function sameInputs(a, b) {
+    return a.length === b.length && a.every((v, i) => v === b[i]);
+}