seqeyes-python 0.3.2__tar.gz → 0.3.4__tar.gz

{seqeyes_python-0.3.2 → seqeyes_python-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: seqeyes-python
-Version: 0.3.2
+Version: 0.3.4
 Summary: Interactive Pulseq MRI sequence viewer for Jupyter — lightweight, beautiful, replaces seq.plot() in pypulseq.
 Project-URL: Homepage, https://github.com/bughht/seqeyes_plugin
 Project-URL: Repository, https://github.com/bughht/seqeyes_plugin

{seqeyes_python-0.3.2 → seqeyes_python-0.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "seqeyes-python"
-version = "0.3.2"
+version = "0.3.4"
 description = "Interactive Pulseq MRI sequence viewer for Jupyter — lightweight, beautiful, replaces seq.plot() in pypulseq."
 readme = "README.md"
 license = {text = "MIT"}

{seqeyes_python-0.3.2 → seqeyes_python-0.3.4}/src/seqeyes/__init__.py

@@ -29,4 +29,4 @@ from seqeyes._plot import set, reset
 from seqeyes._renderer import SeqEyesViewer
 
 __all__ = ["set", "reset", "SeqEyesViewer"]
-__version__ = "0.3.2"
+__version__ = "0.3.4"

{seqeyes_python-0.3.2 → seqeyes_python-0.3.4}/src/seqeyes/resources/pulseq-bundle.js

@@ -23,7 +23,12 @@ var Pulseq = (() => {
   // web/pulseq-browser.ts
   var pulseq_browser_exports = {};
   __export(pulseq_browser_exports, {
+    BAND_DETAIL_SAMPLES: () => BAND_DETAIL_SAMPLES,
+    EXACT_DETAIL_SAMPLES: () => EXACT_DETAIL_SAMPLES,
     INTERACTIVE_COMPUTE_LIMITS: () => INTERACTIVE_COMPUTE_LIMITS,
+    MAX_DETAIL_PTS: () => MAX_DETAIL_PTS,
+    MAX_DISPLAY_PTS: () => MAX_DISPLAY_PTS,
+    MAX_ENVELOPE_COLUMNS: () => MAX_ENVELOPE_COLUMNS,
     MAX_RF_RESPONSE_BANDS: () => MAX_RF_RESPONSE_BANDS,
     MAX_RF_RESPONSE_FFT_POINTS: () => MAX_RF_RESPONSE_FFT_POINTS,
     MAX_RF_RESPONSE_SAMPLES: () => MAX_RF_RESPONSE_SAMPLES,
@@ -36,10 +41,13 @@ var Pulseq = (() => {
     calculatePns: () => calculatePns,
     calculatePnsCoarse: () => calculatePnsCoarse,
     computeGradSpectrumParity: () => computeGradSpectrumParity,
+    computeGradientEnvelope: () => computeGradientEnvelope,
     computeGradientSpectrogram: () => computeGradientSpectrogram,
     computeGradientSpectrumAverage: () => computeGradientSpectrumAverage,
     computeGradientSpectrumSlice: () => computeGradientSpectrumSlice,
     countBandsOutsideRange: () => countBandsOutsideRange,
+    countExactDetailSamples: () => countExactDetailSamples,
+    countGradientSamples: () => countGradientSamples,
     createSequenceDecodeContext: () => createSequenceDecodeContext,
     decodeAllBlocks: () => decodeAllBlocks,
     decodeBlockRange: () => decodeBlockRange,
@@ -64,6 +72,8 @@ var Pulseq = (() => {
     hasPulseqBinaryMagic: () => hasPulseqBinaryMagic,
     isEmptyAscProfile: () => isEmptyAscProfile,
     kspaceExceedsInteractiveBudget: () => kspaceExceedsInteractiveBudget,
+    packGradientEnvelope: () => packGradientEnvelope,
+    packSequenceBlockRange: () => packSequenceBlockRange,
     packSequenceBlocks: () => packSequenceBlocks,
     parseAcousticResonancesAsc: () => parseAcousticResonancesAsc,
     parseAscProfile: () => parseAscProfile,
@@ -74,6 +84,7 @@ var Pulseq = (() => {
     parseSequenceText: () => parseSequenceText,
     physicalGradientValueAt: () => physicalGradientValueAt,
     resamplePhysicalGradients: () => resamplePhysicalGradients,
+    resolveDetailBlockRange: () => resolveDetailBlockRange,
     resolveSpectrogramParams: () => resolveSpectrogramParams,
     rotateGradient: () => rotateGradient,
     safePnsModel: () => safePnsModel,
@@ -86,7 +97,7 @@ var Pulseq = (() => {
   });
 
   // package.json
-  var version = "0.3.2";
+  var version = "0.3.4";
 
   // src/pulseq/decompressor.ts
   function decompressShape(compressed, numSamples) {
@@ -2426,40 +2437,55 @@ var Pulseq = (() => {
   }
 
   // src/pulseq/displayDownsampling.ts
-  function reduceM4(time, values, maxPoints, emit) {
-    const n = Math.min(time.length, values.length);
+  function reduceM4Range(time, values, start, end, maxPoints, emit) {
+    const n = Math.max(0, end - start);
     if (n === 0 || maxPoints <= 0) return 0;
     if (n <= maxPoints) {
-      let kept2 = 0;
-      for (let index = 0; index < n; index++) {
-        emit(time[index], values[index]);
-        kept2++;
-      }
-      return kept2;
+      for (let index = start; index < end; index++) emit(time[index], values[index]);
+      return n;
     }
     const bucketCount = Math.max(1, Math.floor(maxPoints / 4));
     let kept = 0;
     for (let bucket = 0; bucket < bucketCount; bucket++) {
-      const start = Math.floor(bucket * n / bucketCount);
-      const end = Math.max(start + 1, Math.floor((bucket + 1) * n / bucketCount));
-      kept += emitBucket(time, values, start, Math.min(n, end), emit);
+      const bucketStart = start + Math.floor(bucket * n / bucketCount);
+      const bucketEnd = Math.max(bucketStart + 1, start + Math.floor((bucket + 1) * n / bucketCount));
+      kept += emitBucket(time, values, bucketStart, Math.min(end, bucketEnd), emit);
     }
     return kept;
   }
-  function reduceUniform(time, values, maxPoints, emit) {
-    const n = Math.min(time.length, values.length);
+  function reduceUniformRange(time, values, start, end, maxPoints, emit) {
+    const n = Math.max(0, end - start);
     if (n === 0 || maxPoints <= 0) return 0;
     if (n <= maxPoints) {
-      for (let index = 0; index < n; index++) emit(time[index], values[index]);
+      for (let index = start; index < end; index++) emit(time[index], values[index]);
       return n;
     }
     const step = n / maxPoints;
     for (let index = 0; index < maxPoints; index++) {
-      const source = Math.floor(index * step);
-      emit(time[source], values[source]);
+      emit(time[start + Math.floor(index * step)], values[start + Math.floor(index * step)]);
     }
     return maxPoints;
   }
+  function clipIndexRange(time, startSec, endSec, length) {
+    const n = Math.max(0, Math.min(length, time.length));
+    if (n === 0) return { start: 0, end: 0 };
+    let lo = 0;
+    let hi = n;
+    while (lo < hi) {
+      const mid = lo + hi >> 1;
+      if (time[mid] < startSec) lo = mid + 1;
+      else hi = mid;
+    }
+    const start = Math.max(0, lo - 1);
+    lo = start;
+    hi = n;
+    while (lo < hi) {
+      const mid = lo + hi >> 1;
+      if (time[mid] <= endSec) lo = mid + 1;
+      else hi = mid;
+    }
+    return { start, end: Math.min(n, lo + 1) };
+  }
   function emitBucket(time, values, start, end, emit) {
     let minIndex = start;
     let maxIndex = start;
@@ -2486,24 +2512,36 @@ var Pulseq = (() => {
   // src/editor/blockTransport.ts
   var MAX_DISPLAY_PTS = 500;
   var MIN_DISPLAY_PTS = 8;
+  var MAX_DETAIL_PTS = 4096;
+  var EXACT_DETAIL_SAMPLES = 5e4;
+  var BAND_DETAIL_SAMPLES = INTERACTIVE_COMPUTE_LIMITS.derivedRasterSamples;
+  var WINDOW_DETAIL_SAMPLE_LIMIT = 2e6;
   var TAU2 = 2 * Math.PI;
   var EMPTY_PAIR = { o: 0, n: 0 };
   var CountingSink = class {
-    constructor(cap) {
+    constructor(cap, window = null) {
       __publicField(this, "cap", cap);
+      __publicField(this, "window", window);
       __publicField(this, "buildEnvelope", false);
       __publicField(this, "total", 0);
     }
     pair(time, values, useM4) {
-      this.total += useM4 ? reduceM4(time, values, this.cap, discard) : reduceUniform(time, values, this.cap, discard);
+      const { start, end } = clipPair(time, values, this.window);
+      this.total += useM4 ? reduceM4Range(time, values, start, end, this.cap, discard) : reduceUniformRange(time, values, start, end, this.cap, discard);
       return EMPTY_PAIR;
     }
   };
+  function clipPair(time, values, window) {
+    const n = Math.min(time.length, values.length);
+    if (!window) return { start: 0, end: n };
+    return clipIndexRange(time, window.startSec, window.endSec, n);
+  }
   var WritingSink = class {
-    constructor(cap, times, values) {
+    constructor(cap, times, values, window = null) {
       __publicField(this, "cap", cap);
       __publicField(this, "times", times);
       __publicField(this, "values", values);
+      __publicField(this, "window", window);
       __publicField(this, "buildEnvelope", true);
       __publicField(this, "cursor", 0);
       __publicField(this, "wrapPhase", false);
@@ -2518,12 +2556,13 @@ var Pulseq = (() => {
       return this.cursor;
     }
     pair(time, values, useM4, wrapPhase) {
-      const start = this.cursor;
+      const origin = this.cursor;
+      const clipped = clipPair(time, values, this.window);
       this.wrapPhase = wrapPhase;
-      if (useM4) reduceM4(time, values, this.cap, this.emit);
-      else reduceUniform(time, values, this.cap, this.emit);
+      if (useM4) reduceM4Range(time, values, clipped.start, clipped.end, this.cap, this.emit);
+      else reduceUniformRange(time, values, clipped.start, clipped.end, this.cap, this.emit);
       this.wrapPhase = false;
-      return { o: start, n: this.cursor - start };
+      return { o: origin, n: this.cursor - origin };
     }
   };
   function discard() {
@@ -2563,11 +2602,52 @@ var Pulseq = (() => {
       notice: cap < MAX_DISPLAY_PTS ? `Large sequence: waveform detail was reduced to ${cap} points per event (normally ${MAX_DISPLAY_PTS}) to stay inside the display transfer budget.` : null
     };
   }
-  function packBlocksAtCap(blocks, cap, knownTotal) {
-    const total = knownTotal ?? countSamples(blocks, cap);
+  function packSequenceBlockRange(seq, startBlock, endBlock, context = createSequenceDecodeContext(seq), requestedCap = MAX_DISPLAY_PTS, sampleLimit = WINDOW_DETAIL_SAMPLE_LIMIT, window = null) {
+    const start = Math.max(0, Math.min(seq.blocks.length, Math.floor(startBlock)));
+    const end = Math.max(start, Math.min(seq.blocks.length, Math.ceil(endBlock)));
+    const seriesCount = countSequenceWaveformSeriesRange(seq, start, end);
+    const safeSampleLimit = Number.isFinite(sampleLimit) && sampleLimit >= 0 ? Math.floor(sampleLimit) : WINDOW_DETAIL_SAMPLE_LIMIT;
+    const safeRequestedCap = Number.isFinite(requestedCap) && requestedCap > 0 ? Math.floor(requestedCap) : MAX_DISPLAY_PTS;
+    if (seriesCount * MIN_DISPLAY_PTS > safeSampleLimit) {
+      throw new Error(
+        `The waveform detail window needs at least ${seriesCount * MIN_DISPLAY_PTS} samples; zoom in further.`
+      );
+    }
+    const cap = seriesCount > 0 ? Math.max(
+      MIN_DISPLAY_PTS,
+      Math.min(safeRequestedCap, Math.floor(safeSampleLimit / seriesCount))
+    ) : safeRequestedCap;
+    const decoded = decodeBlockRange(seq, start, end, context);
+    const clip = window && window.endSec > window.startSec ? window : null;
+    const exactTotal = countSamples(decoded, Number.MAX_SAFE_INTEGER, clip);
+    if (exactTotal <= Math.min(EXACT_DETAIL_SAMPLES, safeSampleLimit)) {
+      return packBlocksAtCap(decoded, Number.MAX_SAFE_INTEGER, exactTotal, clip);
+    }
+    return packBlocksAtCap(decoded, cap, void 0, clip);
+  }
+  function resolveDetailBlockRange(blockStartTimes, blockCount, startSec, endSec) {
+    const lowerBound = (target) => {
+      let lo = 0;
+      let hi = blockStartTimes.length;
+      while (lo < hi) {
+        const mid = lo + hi >> 1;
+        if (blockStartTimes[mid] < target) lo = mid + 1;
+        else hi = mid;
+      }
+      return lo;
+    };
+    const start = Math.max(0, Math.min(blockCount, lowerBound(startSec) - 1));
+    const end = Math.max(start, Math.min(blockCount, lowerBound(endSec) + 1));
+    return { start, end };
+  }
+  function countExactDetailSamples(blocks, window = null) {
+    return countSamples(blocks, Number.MAX_SAFE_INTEGER, window);
+  }
+  function packBlocksAtCap(blocks, cap, knownTotal, window = null) {
+    const total = knownTotal ?? countSamples(blocks, cap, window);
     const times = new Float64Array(total);
     const values = new Float32Array(total);
-    const sink = new WritingSink(cap, times, values);
+    const sink = new WritingSink(cap, times, values, window);
     const envelope = new Array(blocks.length);
     for (let index = 0; index < blocks.length; index++) {
       envelope[index] = walkBlock(blocks[index], sink);
@@ -2611,8 +2691,8 @@ var Pulseq = (() => {
       if (gradient) gradient.o += delta;
     }
   }
-  function countSamples(blocks, cap) {
-    const sink = new CountingSink(cap);
+  function countSamples(blocks, cap, window = null) {
+    const sink = new CountingSink(cap, window);
     for (const block of blocks) walkBlock(block, sink);
     return sink.total;
   }
@@ -2717,6 +2797,95 @@ var Pulseq = (() => {
     return { peak, area, blockPulse };
   }
 
+  // src/pulseq/gradientEnvelope.ts
+  var GRADIENT_CHANNELS = ["gx", "gy", "gz"];
+  var MAX_ENVELOPE_COLUMNS = 8192;
+  function emptyChannel(columns) {
+    const min = new Float32Array(columns).fill(Infinity);
+    const max = new Float32Array(columns).fill(-Infinity);
+    return { min, max, filled: new Uint8Array(columns) };
+  }
+  function accumulate(channel, grad, startSec, endSec, columns) {
+    const time = grad.timePoints;
+    const values = grad.waveform;
+    const n = Math.min(time.length, values.length);
+    if (n === 0) return;
+    const span = endSec - startSec;
+    if (!(span > 0)) return;
+    const toColumn = (t) => (t - startSec) / span * columns;
+    const put = (column, value) => {
+      if (column < 0 || column >= columns || !Number.isFinite(value)) return;
+      if (value < channel.min[column]) channel.min[column] = value;
+      if (value > channel.max[column]) channel.max[column] = value;
+      channel.filled[column] = 1;
+    };
+    if (n === 1) {
+      put(Math.floor(toColumn(time[0])), values[0]);
+      return;
+    }
+    for (let i = 1; i < n; i++) {
+      const t0 = time[i - 1];
+      const t1 = time[i];
+      if (t1 < startSec || t0 > endSec) continue;
+      const c0 = toColumn(t0);
+      const c1 = toColumn(t1);
+      const lo = Math.max(0, Math.floor(Math.min(c0, c1)));
+      const hi = Math.min(columns - 1, Math.floor(Math.max(c0, c1)));
+      const dc = c1 - c0;
+      const valueAt = (column) => {
+        if (dc === 0) return values[i];
+        const f = (column - c0) / dc;
+        return values[i - 1] + f * (values[i] - values[i - 1]);
+      };
+      for (let column = lo; column <= hi; column++) {
+        const from = Math.max(Math.min(c0, c1), column);
+        const to = Math.min(Math.max(c0, c1), column + 1);
+        if (to < from) continue;
+        put(column, valueAt(from));
+        put(column, valueAt(to));
+      }
+    }
+  }
+  function computeGradientEnvelope(blocks, startSec, endSec, columns) {
+    const width = Math.max(1, Math.min(MAX_ENVELOPE_COLUMNS, Math.floor(columns)));
+    const channels = {
+      gx: emptyChannel(width),
+      gy: emptyChannel(width),
+      gz: emptyChannel(width)
+    };
+    for (const block of blocks) {
+      for (const key of GRADIENT_CHANNELS) {
+        const grad = block[key];
+        if (!grad || grad.type === "none") continue;
+        accumulate(channels[key], grad, startSec, endSec, width);
+      }
+    }
+    return { startSec, endSec, columns: width, channels };
+  }
+  function countGradientSamples(blocks) {
+    let total = 0;
+    for (const block of blocks) {
+      for (const key of GRADIENT_CHANNELS) {
+        const grad = block[key];
+        if (grad && grad.type !== "none") total += grad.timePoints.length;
+      }
+    }
+    return total;
+  }
+  function packGradientEnvelope(envelope) {
+    const { columns } = envelope;
+    const out = new Float32Array(columns * 6);
+    let cursor = 0;
+    for (const key of GRADIENT_CHANNELS) {
+      const channel = envelope.channels[key];
+      for (let c = 0; c < columns; c++) out[cursor + c] = channel.filled[c] ? channel.min[c] : NaN;
+      cursor += columns;
+      for (let c = 0; c < columns; c++) out[cursor + c] = channel.filled[c] ? channel.max[c] : NaN;
+      cursor += columns;
+    }
+    return { startSec: envelope.startSec, endSec: envelope.endSec, columns, values: out.buffer };
+  }
+
   // src/pulseq/physicalGradients.ts
   var GRADIENT_ENDPOINT_TOLERANCE_SEC = 1e-12;
   function rotateGradient(block, gx, gy, gz) {

{seqeyes_python-0.3.2 → seqeyes_python-0.3.4}/src/seqeyes/resources/webview-bundle.js

@@ -113,6 +113,243 @@ function deserializeGradientSound(payload){
   };
 }
 
+/* ── Viewport waveform detail ─────────────────────────────────────────────
+   The initial payload is one bounded overview of the whole sequence: every
+   waveform is reduced to at most a few hundred points so a large sequence can
+   cross the transport at all.  That is the right trade for the first paint and
+   for wide views, but it is irreversible — zooming into 0.5 ms of a 48 ms
+   readout leaves the renderer connecting a handful of surviving extrema, which
+   draws as straight polygonal segments instead of the real waveform.
+
+   So when the view is zoomed far enough that it holds fewer transported
+   samples than it has pixels, the host is asked to decode that block range
+   again and reduce it against the visible interval instead of the whole event.
+   The reply replaces only the blocks it covers, and only while it covers the
+   view; everything outside keeps the overview.  Requests are debounced so a
+   drag issues one decode at rest rather than one per frame, and each reply
+   carries the sequence generation it was packed from so a load that lands
+   mid-flight cannot paint the previous sequence's samples. */
+
+/** Detail currently held: {blocks,startBlock,endBlock,startSec,endSec,generation}. */
+var waveformDetail = null;
+/**
+ * Band held for windows carrying more samples than can be drawn one segment
+ * each: {startSec,endSec,columns,values,generation}.  `values` is six runs of
+ * `columns` floats — gxMin, gxMax, gyMin, gyMax, gzMin, gzMax — NaN where a
+ * column holds no gradient, so a gap cannot be read as a zero.
+ */
+var waveformBand = null;
+/** Set for one drawBlocks pass when the band, not samples, describes the view. */
+var activeWaveformBand = null;
+/**
+ * Narrowest window the host refused as beyond its decode budget.  Anything at
+ * least this wide would be refused too, so it is not asked for again; zooming
+ * in narrows the request and lifts the block on its own.
+ */
+var waveformDetailRefusedSec = Infinity;
+/** Set for the duration of one drawBlocks pass when detail covers the view. */
+var activeWaveformDetail = null;
+var waveformDetailPending = null;
+var waveformDetailTimer = 0;
+var waveformDetailRequestId = 0;
+/** Bumped by the host on every sequence load; stale replies are dropped. */
+var waveformDetailGeneration = 0;
+/**
+ * Installed by each host: VS Code posts a message to the extension, the
+ * standalone web app packs the range in this same heap.  Receives
+ * {requestId, generation, startSec, endSec, columns}.
+ */
+var requestWaveformDetailWindow = null;
+/**
+ * Installed by each host to surface a detail failure.  This bundle's notice
+ * state is not what the standalone web app renders, so the message has to go
+ * back out to whichever viewer is actually on screen.
+ */
+var waveformDetailNotice = null;
+
+function reportWaveformDetail(message){
+  if(typeof waveformDetailNotice==='function')waveformDetailNotice(message);
+}
+
+var WAVEFORM_DETAIL_DEBOUNCE_MS = 160;
+/**
+ * Refetch once the held window is this many times wider than the view.
+ *
+ * Time coverage alone is not enough: a window fetched for a 5 ms view still
+ * covers a 0.5 ms view, so without this the detail would freeze at whatever
+ * zoom first requested it and never sharpen as the user keeps zooming in.  A
+ * fresh request pads to 1.5x the view, comfortably inside this bound, so
+ * refetching settles in one step instead of oscillating.
+ */
+var WAVEFORM_DETAIL_REFINE_FACTOR = 2;
+/** Mirrors the host's block ceiling so a hopeless request is never sent. */
+var WAVEFORM_DETAIL_BLOCK_LIMIT = 20000;
+
+/**
+ * Discard detail and in-flight requests; call whenever BL is replaced.
+ *
+ * VS Code passes the extension host's own sequence generation so both sides
+ * agree on which load a reply belongs to; the standalone web app owns the
+ * counter itself and just advances it.
+ */
+function resetWaveformDetail(generation){
+  waveformDetail=null;activeWaveformDetail=null;waveformDetailPending=null;
+  waveformBand=null;activeWaveformBand=null;waveformDetailRefusedSec=Infinity;
+  clearTimeout(waveformDetailTimer);waveformDetailTimer=0;
+  waveformDetailGeneration=(typeof generation==='number'&&isFinite(generation))
+    ?generation:waveformDetailGeneration+1;
+}
+
+function waveformDetailCovers(detail,vs,ve){
+  return !!(detail&&detail.generation===waveformDetailGeneration
+    &&detail.startSec<=vs+1e-12&&detail.endSec>=ve-1e-12);
+}
+
+/**
+ * Whether a window is not just valid for this view but sharp enough for it.
+ * A window far wider than the view spent most of its point budget off screen.
+ */
+function waveformWindowServes(win,vs,ve){
+  if(!waveformDetailCovers(win,vs,ve))return false;
+  return (win.endSec-win.startSec)<=(ve-vs)*WAVEFORM_DETAIL_REFINE_FACTOR;
+}
+
+/**
+ * The block the renderer should draw for index `bi`.  Detail blocks carry the
+ * same identity and timing as their overview counterparts and differ only in
+ * waveform resolution, so substituting one is transparent to every caller.
+ *
+ * `blocks` is passed in rather than read from a global because the standalone
+ * web app runs its renderer inside an IIFE with its own `BL`; every function
+ * this bundle shares with it has to take the state it operates on.
+ */
+function blockAt(blocks,bi){
+  var detail=activeWaveformDetail;
+  if(detail&&bi>=detail.startBlock&&bi<detail.endBlock){
+    var block=detail.blocks[bi-detail.startBlock];
+    if(block)return block;
+  }
+  return blocks[bi];
+}
+
+/**
+ * Decide whether detail applies to this view and, if it would help, ask for it.
+ * Returns the detail to draw from, or null to keep the overview.
+ */
+function waveformDetailForView(vs,ve,pixelBudget,startBlock,endBlock){
+  // Draw from any detail that covers the view, even while a sharper window is
+  // in flight: coarse detail still beats the whole-sequence overview.
+  activeWaveformDetail=waveformDetailCovers(waveformDetail,vs,ve)?waveformDetail:null;
+  // Anything not already served by exact samples or a band is being drawn from
+  // the reduced transport, which is the representation to get away from — so
+  // ask, whatever the point count.  Held data is refetched once its window is
+  // wider than the view deserves.  Loops are prevented by the coverage test and
+  // by remembering a refusal, not by withholding the request.
+  var wants=activeWaveformDetail
+    ? !waveformWindowServes(waveformDetail,vs,ve)
+    : (waveformDetailCovers(waveformBand,vs,ve)
+      ? !waveformWindowServes(waveformBand,vs,ve)
+      : true);
+  if(wants&&endBlock-startBlock<=WAVEFORM_DETAIL_BLOCK_LIMIT)
+    scheduleWaveformDetail(vs,ve,pixelBudget);
+  return activeWaveformDetail;
+}
+
+/**
+ * The band gradients should be drawn from, or null when exact samples are
+ * available or the view is beyond what the host will decode.  Kept separate
+ * from the sample path so a stale band is never drawn beside fresher samples.
+ */
+function waveformBandForView(vs,ve){
+  activeWaveformBand=(!activeWaveformDetail&&waveformDetailCovers(waveformBand,vs,ve))
+    ?waveformBand:null;
+  return activeWaveformBand;
+}
+
+/** One column's [min,max] for a channel, or null where it holds nothing. */
+function bandColumn(band,channelIndex,column){
+  if(!band||column<0||column>=band.columns)return null;
+  var base=channelIndex*2*band.columns;
+  var lo=band.values[base+column],hi=band.values[base+band.columns+column];
+  if(!(lo===lo)||!(hi===hi))return null;   // NaN marks an empty column
+  return{lo:lo,hi:hi};
+}
+
+function scheduleWaveformDetail(vs,ve,pixelBudget){
+  if(typeof requestWaveformDetailWindow!=='function'||!(ve>vs))return;
+  var pad=(ve-vs)*0.25,start=Math.max(0,vs-pad),end=ve+pad;
+  if(end-start>=waveformDetailRefusedSec)return;
+  // Enough columns that the part inside the view still gets about one per
+  // pixel once the padding either side is discounted.
+  var columns=Math.max(1,Math.ceil((pixelBudget||1)*((end-start)/(ve-vs))));
+  // Same adequacy test as the held detail, so an in-flight wide request cannot
+  // suppress the narrower one a deeper zoom now needs.
+  if(waveformWindowServes(waveformDetailPending,vs,ve))return;
+  clearTimeout(waveformDetailTimer);
+  waveformDetailTimer=setTimeout(function(){
+    waveformDetailPending={startSec:start,endSec:end,generation:waveformDetailGeneration};
+    waveformDetailRequestId++;
+    try{
+      requestWaveformDetailWindow({
+        requestId:waveformDetailRequestId,
+        generation:waveformDetailGeneration,
+        startSec:start,endSec:end,
+        columns:columns
+      });
+    }catch(err){waveformDetailPending=null;
+      reportWaveformDetail('Waveform detail was not calculated: '+(err&&err.message||String(err))+'.');}
+  },WAVEFORM_DETAIL_DEBOUNCE_MS);
+}
+
+/** Accept a detail reply. Ignores stale generations and superseded requests. */
+function applyWaveformDetail(payload){
+  if(!payload||payload.generation!==waveformDetailGeneration)return false;
+  if(payload.requestId!==waveformDetailRequestId)return false;
+  waveformDetailPending=null;
+  waveformDetail={
+    blocks:payload.blocks,startBlock:payload.startBlock,endBlock:payload.endBlock,
+    startSec:payload.startSec,endSec:payload.endSec,generation:payload.generation
+  };
+  reportWaveformDetail(null);
+  return true;
+}
+
+/** Accept a band for a window too dense to draw sample by sample. */
+function applyWaveformBand(payload){
+  if(!payload||payload.generation!==waveformDetailGeneration)return false;
+  if(payload.requestId!==waveformDetailRequestId)return false;
+  waveformDetailPending=null;
+  waveformDetail=null;activeWaveformDetail=null;
+  waveformBand={
+    startSec:payload.startSec,endSec:payload.endSec,columns:payload.columns,
+    values:payload.values,generation:payload.generation
+  };
+  reportWaveformDetail(null);
+  return true;
+}
+
+/** Remember that this window exceeds the decode budget and stop asking. */
+function refuseWaveformDetail(payload){
+  if(!payload||payload.generation!==waveformDetailGeneration)return false;
+  if(payload.requestId!==waveformDetailRequestId)return false;
+  waveformDetailPending=null;
+  var width=payload.endSec-payload.startSec;
+  if(width>0&&width<waveformDetailRefusedSec)waveformDetailRefusedSec=width;
+  return true;
+}
+
+/**
+ * Record a failed detail request without discarding the overview.  Checks the
+ * request id as well as the generation so a superseded failure cannot clear a
+ * newer in-flight request or leave a notice about a window nobody is viewing.
+ */
+function failWaveformDetail(payload){
+  if(!payload||payload.generation!==waveformDetailGeneration)return;
+  if(payload.requestId!==waveformDetailRequestId)return;
+  waveformDetailPending=null;
+  reportWaveformDetail('Waveform detail was not calculated: '+(payload.message||'unknown error')+'.');
+}
+
 
 /* ══ state.js ══ */
 /* ═══════════════════════════════════════════════════════════════════════
@@ -144,7 +381,7 @@ var kTraj=null,kAdc=null,kTime=null,kAdcTime=null;
 var m1Data=null,m1WindowData=null,m1WindowPending=null,m1WindowRequestId=0,pnsData=null,pnsWindowData=null,pnsWindowPending=null,pnsWindowRequestId=0,pnsBusy=false,m1Busy=false,m1RequestedChannel=8,m1ReferenceMode=readM1ReferenceMode(),m1RestoreChannels=null;
 var viewerNotices={},viewerNoticesCollapsed=readViewerNoticesCollapsed();
 var kspaceSafetyWarning=null,kspaceSafetyBusy=false,kspaceSafetyPopupTimer=0;
-var derivedRenderPointCount=0,derivedEnvelopeCurveCount=0,derivedRawCurveCount=0,waveformOverviewActive=false,rfRenderPointCount=0,rfRawCurveCount=0,rfReducedCurveCount=0,rfOverviewBucketCount=0,lastDrawDurationMs=0,viewerDrawCount=0,viewerCursorDrawCount=0;
+var derivedRenderPointCount=0,derivedEnvelopeCurveCount=0,derivedRawCurveCount=0,waveformOverviewActive=false,rfRenderPointCount=0,rfRawCurveCount=0,rfReducedCurveCount=0,rfOverviewBucketCount=0,gradViewPointCount=0,lastDrawDurationMs=0,viewerDrawCount=0,viewerCursorDrawCount=0;
 var viewerDrawFrame=0,viewerDrawMinimap=false;
 function isMobileSafetyLayout(){return !!(window.matchMedia&&window.matchMedia('(max-width: 768px), (pointer: coarse)').matches);}
 function viewerNoticeMessages(value){
@@ -245,6 +482,19 @@ var blockPos=[];
 /* VS Code API — acquired once, used for postMessage to extension host */
 var vscApi=(typeof acquireVsCodeApi!=='undefined')?acquireVsCodeApi():null;
 
+/* Viewport waveform detail crosses the extension boundary; the standalone web
+   app installs its own in-heap implementation instead. */
+waveformDetailNotice=function(message){setViewerNotice('waveformDetail',message);};
+if(vscApi)requestWaveformDetailWindow=function(request){
+  vscApi.postMessage({
+    command:'requestWaveformDetail',
+    requestId:request.requestId,
+    sequenceGeneration:request.generation,
+    startSec:request.startSec,endSec:request.endSec,
+    columns:request.columns
+  });
+};
+
 function normalizeM1ReferenceMode(mode){return mode==='observationTime'?'observationTime':'rfCenter';}
 function readM1ReferenceMode(){
   try{localStorage.removeItem('seqeyes.m1ReferenceMode');}catch(_){}
@@ -402,7 +652,7 @@ function applySerializedKspace(payload){
    much as the message: the progress overlay reaches "Ready" either way, so
    leaving stale blocks on screen would read as a successful load. */
 function showSequenceLoadFailure(message){
-  BL=[];waveformOverview=null;blockPos=[];mmCache=null;
+  BL=[];waveformOverview=null;blockPos=[];mmCache=null;resetWaveformDetail();
   setViewerNotice('sequence',message);
   setExportButtonEnabled(false);
   draw();drawMinimap();
@@ -430,6 +680,7 @@ window.addEventListener('message',function(e){
     return;
   }
   if(m.type==='sequenceData'){
+    resetWaveformDetail(m.sequenceGeneration);
     try{
       BL=unpackSequenceBlocks(m.blocks,m.sampleTimes,m.sampleValues,m.sampleCount||0);
     }catch(err){
@@ -456,6 +707,35 @@ window.addEventListener('message',function(e){
     setExportButtonEnabled(true);
     SeqEyesPanel.onSequenceLoaded();
     requestAnimationFrame(function(){refreshLayout();draw();drawKs();drawMinimap();});
+  }else if(m.type==='waveformDetailData'){
+    var detailBlocks;
+    try{
+      detailBlocks=unpackSequenceBlocks(m.blocks,m.sampleTimes,m.sampleValues,m.sampleCount||0);
+    }catch(err){
+      failWaveformDetail({requestId:m.requestId,generation:m.sequenceGeneration,message:(err&&err.message||String(err))});
+      return;
+    }
+    if(applyWaveformDetail({
+      requestId:m.requestId,generation:m.sequenceGeneration,
+      startBlock:m.startBlock,endBlock:m.endBlock,
+      startSec:m.startSec,endSec:m.endSec,blocks:detailBlocks
+    }))draw();
+  }else if(m.type==='waveformBandData'){
+    var bandValues=asTypedView(m.values,Float32Array);
+    if(!bandValues){
+      failWaveformDetail({requestId:m.requestId,generation:m.sequenceGeneration,
+        message:'the waveform band did not arrive as binary data'});
+      return;
+    }
+    if(applyWaveformBand({
+      requestId:m.requestId,generation:m.sequenceGeneration,
+      startSec:m.startSec,endSec:m.endSec,columns:m.columns,values:bandValues
+    }))draw();
+  }else if(m.type==='waveformDetailUnavailable'){
+    if(refuseWaveformDetail({requestId:m.requestId,generation:m.sequenceGeneration,
+      startSec:m.startSec,endSec:m.endSec}))draw();
+  }else if(m.type==='waveformDetailError'){
+    failWaveformDetail({requestId:m.requestId,generation:m.sequenceGeneration,message:m.message});
   }else if(m.type==='loadError'){
     showSequenceLoadFailure(m.message||'The sequence could not be loaded.');
   }else if(m.type==='kspaceData'){
@@ -1424,7 +1704,7 @@ var panelMarkerTimeSec=NaN;
    Main draw loop
    ═══════════════════════════════════════════════════════════════════════ */
 function draw(){
-  var drawStarted=performance.now();derivedRenderPointCount=0;derivedEnvelopeCurveCount=0;derivedRawCurveCount=0;rfRenderPointCount=0;rfRawCurveCount=0;rfReducedCurveCount=0;rfOverviewBucketCount=0;viewerDrawCount++;
+  var drawStarted=performance.now();derivedRenderPointCount=0;derivedEnvelopeCurveCount=0;derivedRawCurveCount=0;rfRenderPointCount=0;rfRawCurveCount=0;rfReducedCurveCount=0;rfOverviewBucketCount=0;gradViewPointCount=0;viewerDrawCount++;
   var w=mc.width/(window.devicePixelRatio||1),h=mc.height/(window.devicePixelRatio||1);
   var s=getComputedStyle(document.body);
   ctx.clearRect(0,0,w,h);
@@ -1714,18 +1994,37 @@ function drawBlocks(vs,ve,s){
   var pixelBudget=Math.max(1,Math.floor(plotWidth()));
   var overview=selectWaveformOverview(waveformOverview,range.start,range.end,pixelBudget);
   function useOverview(key){return !!overview&&waveformVisiblePointCount(waveformOverview,key,range.start,range.end)>pixelBudget;}
-  function useGradientOverview(key){return !!overview&&waveformVisibleGradientPointCount(BL,key,range.start,range.end,vs,ve)>pixelBudget*8;}
+  var gradVisible={gx:waveformVisibleGradientPointCount(BL,'gx',range.start,range.end,vs,ve),
+    gy:waveformVisibleGradientPointCount(BL,'gy',range.start,range.end,vs,ve),
+    gz:waveformVisibleGradientPointCount(BL,'gz',range.start,range.end,vs,ve)};
+  function useGradientOverview(key){return !!overview&&gradVisible[key]>pixelBudget*8;}
   var rfPoints=waveformVisiblePointCount(waveformOverview,'rf',range.start,range.end),rfEvents=waveformVisiblePointCount(waveformOverview,'rfEvents',range.start,range.end);
   var aggregateRf=!!overview&&rfEvents>pixelBudget*2,reduceRf=aggregateRf||rfPoints>pixelBudget*8;
   var overviewUse={rf:reduceRf,phase:useOverview('phase'),gx:useGradientOverview('gx'),gy:useGradientOverview('gy'),gz:useGradientOverview('gz'),adc:useOverview('adc')};
   var dense=overviewUse.rf||overviewUse.phase||overviewUse.gx||overviewUse.gy||overviewUse.gz||overviewUse.adc;
   waveformOverviewActive=dense;
   setViewerNotice('dense',dense?'Dense overview mode is active. Zoom in for full waveform detail.':null);
+  // Raw level draws whatever the transport delivered, so this is where an
+  // over-reduced view has to be refilled with samples clipped to the viewport.
+  // Keyed on the waveform rows specifically: phase or ADC switching to the
+  // overview says nothing about the gradients, which may still be drawing
+  // transported samples and still be the thing that looks wrong.
+  var rawWaveformRows=!(overviewUse.gx&&overviewUse.gy&&overviewUse.gz&&reduceRf);
+  if(rawWaveformRows)waveformDetailForView(vs,ve,pixelBudget,range.start,range.end);
+  else activeWaveformDetail=null;
   if(rows[0]>=0){if(aggregateRf)drawRfOverview(overview,rows[0],ch,colors,vs,ve);else drawRfBlocks(range.start,range.end,rows[0],ch,colors,vs,ve,pixelBudget*8);}
   if(rows[1]>=0){if(overviewUse.phase)drawPhaseSampled(range.start,range.end,rows[1],ch,colors,vs,ve,pixelBudget);else drawPhaseBlocks(range.start,range.end,rows[1],ch,colors,vs,ve);}
-  if(rows[2]>=0){if(overviewUse.gx)drawGradientOverview(overview,'gx',rows[2],2,ch,colors.gx,vs,ve);else drawGradientBlocks(range.start,range.end,'gx',rows[2],2,ch,colors.gx,vs,ve);}
-  if(rows[3]>=0){if(overviewUse.gy)drawGradientOverview(overview,'gy',rows[3],3,ch,colors.gy,vs,ve);else drawGradientBlocks(range.start,range.end,'gy',rows[3],3,ch,colors.gy,vs,ve);}
-  if(rows[4]>=0){if(overviewUse.gz)drawGradientOverview(overview,'gz',rows[4],4,ch,colors.gz,vs,ve);else drawGradientBlocks(range.start,range.end,'gz',rows[4],4,ch,colors.gz,vs,ve);}
+  // Band first: where it covers the view it is the accurate representation, and
+  // the block polyline would be drawing an already-reduced transport instead.
+  var band=waveformBandForView(vs,ve);
+  var gradKeys=['gx','gy','gz'];
+  for(var gi=0;gi<3;gi++){
+    var row=rows[2+gi],key=gradKeys[gi];
+    if(row<0)continue;
+    if(band)drawGradientBand(band,gi,key,row,2+gi,ch,colors[key],vs,ve);
+    else if(overviewUse[key])drawGradientOverview(overview,key,row,2+gi,ch,colors[key],vs,ve);
+    else drawGradientBlocks(range.start,range.end,key,row,2+gi,ch,colors[key],vs,ve);
+  }
   if(rows[5]>=0){if(overviewUse.adc)drawAdcOverview(overview,rows[5],ch,colors,vs,ve);else drawAdcBlocks(range.start,range.end,rows[5],ch,colors,vs,ve);}
   if(rows[6]>=0&&range.end-range.start<=pixelBudget)drawTriggerBlocks(range.start,range.end,rows[6],ch,colors,vs,ve);
 }
@@ -1830,7 +2129,7 @@ function drawRfBlocks(start,end,vi,ch,colors,vs,ve,maxPoints){
   rowClip(vi,ch,function(){
     var visibleEvents=[];
     for(var bi=start;bi<end;bi++){
-      var rf=BL[bi].rf;if(!rf||rf.s+rf.d<vs||rf.s>ve)continue;
+      var rf=blockAt(BL,bi).rf;if(!rf||rf.s+rf.d<vs||rf.s>ve)continue;
       visibleEvents.push(rf);
     }
     var pointBudget=Math.max(4,Math.floor((maxPoints||Infinity)/Math.max(1,visibleEvents.length)));
@@ -1855,7 +2154,7 @@ function drawPhaseBlocks(start,end,vi,ch,colors,vs,ve){
   rowClip(vi,ch,function(){
     ctx.strokeStyle=colors.rf;ctx.lineWidth=.8;ctx.beginPath();var hasRf=false;
     for(var bi=start;bi<end;bi++){
-      var rf=BL[bi].rf,phaseTime=rf&&(rf.pt||rf.t);if(!rf||!rf.p||!phaseTime||rf.s+rf.d<vs||rf.s>ve)continue;
+      var rf=blockAt(BL,bi).rf,phaseTime=rf&&(rf.pt||rf.t);if(!rf||!rf.p||!phaseTime||rf.s+rf.d<vs||rf.s>ve)continue;
       var n=Math.min(phaseTime.length,rf.p.length);
       for(var i=0;i<n;i++){
         var sx=t2x(phaseTime[i]),sy=y+ch*.45-rf.p[i]*scale;
@@ -1885,18 +2184,51 @@ function drawPhaseBlocks(start,end,vi,ch,colors,vs,ve){
   });
 }
 
+/**
+ * Draw one gradient channel as a min/max band.
+ *
+ * Used where the view holds more samples than pixels: each column is filled
+ * between the extremes the waveform actually reached while crossing it, so the
+ * shape stays truthful without asserting a path between samples that are not
+ * adjacent.  Empty columns break the shape rather than being drawn at zero.
+ */
+function drawGradientBand(band,channelIndex,key,vi,ci,ch,color,vs,ve){
+  var y=cy(vi),scale=ch*.4/channelRange(ci);
+  var span=band.endSec-band.startSec;if(!(span>0))return;
+  var perColumn=span/band.columns;
+  var first=Math.max(0,Math.floor((vs-band.startSec)/perColumn));
+  var last=Math.min(band.columns-1,Math.ceil((ve-band.startSec)/perColumn));
+  rowClip(vi,ch,function(){
+    ctx.fillStyle=color;ctx.globalAlpha=.55;ctx.beginPath();var drew=false;
+    for(var c=first;c<=last;c++){
+      var col=bandColumn(band,channelIndex,c);if(!col)continue;
+      var x0=t2x(band.startSec+c*perColumn),x1=t2x(band.startSec+(c+1)*perColumn);
+      var w=Math.max(x1-x0,.75);
+      var yTop=y-col.hi*scale,yBottom=y-col.lo*scale;
+      // A flat run would be an invisible zero-height rectangle.
+      ctx.rect(x0,yTop,w,Math.max(yBottom-yTop,.75));drew=true;
+      gradViewPointCount++;
+    }
+    if(drew)ctx.fill();
+    ctx.globalAlpha=1;
+  });
+}
+
 function drawGradientBlocks(start,end,key,vi,ci,ch,color,vs,ve){
   var y=cy(vi),scale=ch*.4/channelRange(ci);
   rowClip(vi,ch,function(){
     ctx.strokeStyle=color;ctx.lineWidth=1;ctx.beginPath();var hasPath=false;
     for(var bi=start;bi<end;bi++){
-      var g=BL[bi][key];if(!g||g.ty==='none'||!g.t||!g.w||g.t.length<2)continue;
+      var g=blockAt(BL,bi)[key];if(!g||g.ty==='none'||!g.t||!g.w||g.t.length<2)continue;
       var n=Math.min(g.t.length,g.w.length);
       if(n<2)continue;
       if(g.t[n-1]<vs||g.t[0]>ve)continue;
       for(var i=0;i<n;i++){
         var sx=t2x(g.t[i]),sy=y-g.w[i]*scale;
         if(i===0)ctx.moveTo(sx,sy);else ctx.lineTo(sx,sy);
+        // Counted per visible point, not per event: an over-reduced waveform
+        // still draws a whole long event, it just has almost nothing in view.
+        if(g.t[i]>=vs&&g.t[i]<=ve)gradViewPointCount++;
       }
       hasPath=true;
     }
@@ -4823,7 +5155,16 @@ var SeqEyesPanel = (function () {
       if (e.key === 'Escape' && isFinite(markerTimeSec)) { setMarkerTime(NaN); syncControls(); }
     });
     document.addEventListener('visibilitychange', function () {
-      if (document.hidden) stopPlayback();
+      if (document.hidden) {
+        // Web Audio can keep rendering in a background tab, but animation frames
+        // cannot. Preserve the audition and suspend only its visual updates.
+        stopPlayheadLoop();
+        return;
+      }
+      if (panelMode !== 'spectrogram') return;
+      if (SeqEyesAudio.isPlaying()) startPlayheadLoop();
+      syncTransport();
+      render();
     });
     window.addEventListener('pagehide', function () { SeqEyesAudio.dispose(); });
     window.addEventListener('resize', function () { if (panelMode === 'spectrogram') resize(); });