@jackuait/blok 0.19.2 → 0.21.0

package/src/styles/tables.css

@@ -152,3 +152,13 @@
 [data-blok-theme="dark"] [data-blok-interface] [data-blok-table-haze="right"] {
   background-image: linear-gradient(to left, var(--blok-dark), transparent);
 }
+
+/* Table card pins its top toolbar anchor absolutely to the (position:relative)
+   wrapper top, so the +/tunes buttons sit flush with the table's top edge while
+   the marker stays out of the flow — it never becomes the wrapper's firstChild,
+   which the grid/scroll structure relies on. */
+[data-blok-tool="table"] .blok-toolbar-top-anchor {
+  position: absolute;
+  top: 0;
+  left: 0;
+}

package/src/tools/audio/constants.ts

@@ -19,3 +19,9 @@ export const COVER_DATA_URL_CAP_BYTES = 150 * 1024;
 
 /** Direct links to a playable audio file. */
 export const URL_PATTERN = /^https?:\/\/\S+\.(mp3|wav|ogg|oga|m4a|aac|flac|weba)(\?\S*)?$/i;
+
+/** Accepted cover-image MIME types (family wildcard). */
+export const COVER_TYPES = ['image/*'] as const;
+
+/** Max cover-image size in bytes. */
+export const COVER_MAX_SIZE = 10 * 1024 * 1024; // 10 MiB

package/src/tools/audio/controls.ts

@@ -1,4 +1,5 @@
 import {
+  IconMinus,
   IconPlayerLoop,
   IconPlayerPause,
   IconPlayerPlay,
@@ -6,7 +7,9 @@ import {
   IconPlayerSpeed,
   IconPlayerVolume,
   IconPlayerVolumeMute,
+  IconPlus,
 } from '../../components/icons';
+import { createPlatterSpin } from './disc';
 import type { AudioData } from '../../../types/tools/audio';
 
 /** Minimal storage seam (localStorage-shaped) for volume + position persistence. */
@@ -99,11 +102,17 @@ export function attachControls({
 
   const state = { playing: false, selectedRate: 1 };
 
+  // Inertial spin for the no-cover vinyl record (no-op when a cover image is
+  // shown — the disc only exists in the placeholder). Spins up on play, coasts
+  // down on pause.
+  const platter = createPlatterSpin(figure);
+
   const setPlaying = (next: boolean): void => {
     state.playing = next;
     figure.setAttribute('data-playing', String(next));
     playToggle.innerHTML = next ? IconPlayerPause : IconPlayerPlay;
     playToggle.setAttribute('aria-label', next ? 'Pause' : 'Play');
+    if (next) platter.start(); else platter.stop();
   };
   setPlaying(false);
 
@@ -139,7 +148,10 @@ export function attachControls({
     muteToggle.innerHTML = muted ? IconPlayerVolumeMute : IconPlayerVolume;
     muteToggle.setAttribute('aria-label', muted ? 'Unmute' : 'Mute');
     volumeInput.value = muted ? '0' : String(media.volume);
-    volumeInput.style.setProperty('--blok-vol-pct', `${Number(volumeInput.value) * 100}%`);
+    // audio.css paints the filled track from --blok-audio-vol-pct (same naming
+    // as the speed slider's --blok-audio-speed-pct); writing any other name
+    // freezes the fill at its 100% default, so muted looks identical to full.
+    volumeInput.style.setProperty('--blok-audio-vol-pct', `${Number(volumeInput.value) * 100}%`);
   };
 
   // ----- persistence -----
@@ -207,6 +219,20 @@ export function attachControls({
   speedReadout.setAttribute('aria-hidden', 'true');
   speedReadout.textContent = speedLabel(state.selectedRate);
 
+  // − [slider] ＋ — flat steppers flank the track, mirroring the video player.
+  // Identified by class only (no data-role) so the generic button[data-role]
+  // control-button rule doesn't size them into 30px pills.
+  const speedStepper = (icon: string, label: string): HTMLButtonElement => {
+    const btn = document.createElement('button');
+    btn.type = 'button';
+    btn.className = 'blok-audio-controls__speed-step';
+    btn.setAttribute('aria-label', label);
+    btn.innerHTML = icon;
+    return btn;
+  };
+  const speedDec = speedStepper(IconMinus, 'Decrease playback speed');
+  const speedInc = speedStepper(IconPlus, 'Increase playback speed');
+
   const speedSlider = document.createElement('input');
   speedSlider.type = 'range';
   speedSlider.className = 'blok-audio-controls__speed-slider';
@@ -216,6 +242,12 @@ export function attachControls({
   speedSlider.value = String(state.selectedRate);
   speedSlider.setAttribute('aria-label', 'Playback speed');
 
+  // Drive the elapsed-fill gradient from JS so the painted track tracks the
+  // native knob exactly (same approach as the volume + video sliders).
+  const speedFillPct = (rate: number): string =>
+    `${((rate - SPEED_MIN) / (SPEED_MAX - SPEED_MIN)) * 100}%`;
+  speedSlider.style.setProperty('--blok-audio-speed-pct', speedFillPct(state.selectedRate));
+
   const setRate = (rate: number): void => {
     const next = clampRate(rate);
     state.selectedRate = next;
@@ -223,11 +255,25 @@ export function attachControls({
     speedReadout.textContent = speedLabel(next);
     speedSlider.value = String(next);
     speedSlider.setAttribute('aria-valuetext', speedLabel(next));
+    speedSlider.style.setProperty('--blok-audio-speed-pct', speedFillPct(next));
+    speedDec.disabled = next <= SPEED_MIN;
+    speedInc.disabled = next >= SPEED_MAX;
   };
 
   const onSpeedSliderInput = (): void => setRate(Number(speedSlider.value));
   speedSlider.addEventListener('input', onSpeedSliderInput);
-
+  speedDec.addEventListener('click', () => setRate(state.selectedRate - SPEED_SLIDER_STEP));
+  speedInc.addEventListener('click', () => setRate(state.selectedRate + SPEED_SLIDER_STEP));
+  speedDec.disabled = state.selectedRate <= SPEED_MIN;
+  speedInc.disabled = state.selectedRate >= SPEED_MAX;
+
+  const speedSliderRow = document.createElement('div');
+  speedSliderRow.className = 'blok-audio-controls__speed-slider-row';
+  speedSliderRow.append(speedDec, speedSlider, speedInc);
+
+  // Quiet quick-jump presets (mirrors the video player): every chip reads the
+  // same muted weight, lifting only on hover. The live rate is communicated by
+  // the readout + slider knob, not a filled "selected" chip.
   const speedChipRow = document.createElement('div');
   speedChipRow.className = 'blok-audio-controls__speed-chips';
   SPEED_PRESETS.forEach((rate) => {
@@ -235,14 +281,13 @@ export function attachControls({
     chip.type = 'button';
     chip.className = 'blok-audio-controls__speed-chip';
     chip.textContent = `${rate}×`;
-    chip.addEventListener('click', () => {
-      setRate(rate);
-      closeSpeedMenu();
-    });
+    // Apply the preset but leave the menu open so the user can keep nudging the
+    // rate (slider/steppers/other presets) without re-opening it each time.
+    chip.addEventListener('click', () => setRate(rate));
     speedChipRow.appendChild(chip);
   });
 
-  speedMenu.append(speedReadout, speedSlider, speedChipRow);
+  speedMenu.append(speedReadout, speedSliderRow, speedChipRow);
 
   // Gear + menu share a positioned wrapper so the menu anchors directly above
   // the gear button (rather than the card corner).
@@ -391,6 +436,7 @@ export function attachControls({
 
   // ----- destroy -----
   const destroy = (): void => {
+    platter.destroy();
     closeSpeedMenu();
 
     playToggle.removeEventListener('click', togglePlay);

package/src/tools/audio/cover-picker.ts

@@ -0,0 +1,126 @@
+import { matchesMime } from '../../components/utils/mime-match';
+import type { I18nInstance } from '../../components/utils/tools';
+import { tr } from './i18n';
+import { COVER_TYPES, COVER_MAX_SIZE } from './constants';
+import { promoteToTopLayer, removeFromTopLayer } from '../../components/utils/top-layer';
+import {
+  renderMediaEmptyState,
+  type MediaEmptyStateElement,
+} from '../../components/utils/media-empty-state';
+
+/** Validate a chosen cover file. Returns an error message, or null when valid. */
+export function validateCoverFile(file: File, i18n?: I18nInstance): string | null {
+  if (file.type && !matchesMime(file.type, [...COVER_TYPES])) {
+    return tr(i18n, 'tools.audio.coverErrorType', 'Choose an image file');
+  }
+  if (file.size > COVER_MAX_SIZE) {
+    return tr(i18n, 'tools.audio.coverErrorTooLarge', 'Image is too large');
+  }
+  return null;
+}
+
+export interface OpenCoverPickerOptions {
+  anchor: HTMLElement;
+  onFile(file: File): void;
+  onUrl(url: string): void;
+  onClose?(): void;
+  i18n?: I18nInstance;
+}
+
+export interface CoverPickerHandle {
+  close(): void;
+  setError(message: string | null): void;
+}
+
+export function openCoverPicker(opts: OpenCoverPickerOptions): CoverPickerHandle {
+  const dialog = document.createElement('div');
+  dialog.className = 'blok-audio-cover-picker';
+  dialog.setAttribute('data-role', 'audio-cover-picker');
+  dialog.setAttribute('role', 'dialog');
+  dialog.setAttribute('aria-label', tr(opts.i18n, 'tools.audio.coverSet', 'Set cover image'));
+
+  const surface: MediaEmptyStateElement = renderMediaEmptyState({
+    acceptTypes: [...COVER_TYPES],
+    onFile: opts.onFile,
+    onUrl: opts.onUrl,
+    // The picker is a floating popover, so the inline height tween only reads as
+    // lag here. Slide the incoming panel in from the travel direction instead —
+    // the swap keeps its personality while the popover resizes instantly.
+    swap: 'slide',
+    labels: {
+      add: tr(opts.i18n, 'tools.audio.coverAdd', 'Add a cover'),
+      upload: tr(opts.i18n, 'tools.audio.coverUpload', 'Upload'),
+      embed: tr(opts.i18n, 'tools.audio.coverLink', 'Link'),
+      chooseFile: tr(opts.i18n, 'tools.audio.coverChooseFile', 'Choose file'),
+      orDropHere: tr(opts.i18n, 'tools.audio.coverOrDropHere', 'or drop an image here'),
+      dropToUpload: tr(opts.i18n, 'tools.audio.coverDropToUpload', 'Drop to upload'),
+      urlPlaceholder: tr(opts.i18n, 'tools.audio.coverUrlPlaceholder', 'Paste an image URL…'),
+      urlAria: tr(opts.i18n, 'tools.audio.coverUrlAria', 'Image URL'),
+      submit: tr(opts.i18n, 'tools.audio.coverInsert', 'Insert'),
+      sourceAria: tr(opts.i18n, 'tools.audio.coverSourceAria', 'Cover source'),
+    },
+  });
+  dialog.appendChild(surface);
+
+  document.body.appendChild(dialog);
+  promoteToTopLayer(dialog);
+  position(dialog, opts.anchor);
+
+  const state = { detached: false };
+
+  const detach = (): void => {
+    if (state.detached) return;
+    state.detached = true;
+    document.removeEventListener('keydown', onKeyDown, true);
+    document.removeEventListener('mousedown', onOutside);
+    window.removeEventListener('resize', reposition);
+    window.removeEventListener('scroll', reposition, true);
+    removeFromTopLayer(dialog);
+    dialog.remove();
+  };
+
+  const close = (): void => {
+    detach();
+    opts.onClose?.();
+  };
+
+  const onKeyDown = (event: KeyboardEvent): void => {
+    if (event.key === 'Escape') {
+      event.preventDefault();
+      event.stopPropagation();
+      close();
+    }
+  };
+
+  const onOutside = (event: MouseEvent): void => {
+    const target = event.target as Node | null;
+    if (target && (dialog.contains(target) || opts.anchor.contains(target))) return;
+    close();
+  };
+
+  function reposition(): void {
+    if (state.detached) return;
+    position(dialog, opts.anchor);
+  }
+
+  // Capture phase for Escape so it beats the editor's own key handling.
+  document.addEventListener('keydown', onKeyDown, true);
+  document.addEventListener('mousedown', onOutside);
+  window.addEventListener('resize', reposition);
+  window.addEventListener('scroll', reposition, true);
+
+  return {
+    close,
+    setError: (message) => surface.setError(message),
+  };
+}
+
+function position(dialog: HTMLElement, anchor: HTMLElement): void {
+  const rect = anchor.getBoundingClientRect();
+  const gap = 8;
+  const { style } = dialog;
+  style.position = 'fixed';
+  style.top = `${rect.bottom + gap}px`;
+  style.left = `${Math.max(8, rect.left)}px`;
+  style.right = 'auto';
+}

package/src/tools/audio/disc.ts

@@ -0,0 +1,137 @@
+/**
+ * Inertial platter spin for the no-cover vinyl record.
+ *
+ * With the tonearm gone, the disc is the whole show — so it shouldn't just snap
+ * on and off. A real platter has mass: it spins UP when the motor engages and
+ * COASTS DOWN when power is cut. We model that with an angular velocity that
+ * eases toward a target (full speed while playing, 0 when stopped) and integrate
+ * it into an accumulated angle each animation frame, driving the disc's
+ * `transform: rotate()` directly. Spin-up is brisk; the wind-down uses a longer
+ * time constant, so pausing reads as a heavy record slowing to rest rather than
+ * stopping dead.
+ *
+ * The velocity easing is exponential (frame-rate independent — see stepPlatter),
+ * so it behaves identically on a 60Hz or 120Hz display. All of it is gated on
+ * prefers-reduced-motion: the record simply holds still.
+ */
+
+/** Platter motion state: accumulated angle (deg, wrapped) + angular speed (deg/s). */
+export interface PlatterState {
+  angle: number;
+  velocity: number;
+}
+
+/** Target speed at a 33⅓-feel — one full turn every ~4s. */
+export const PLATTER_FULL_DPS = 90;
+/** Time constant (s) for the motor coming up to speed — brisk. */
+export const PLATTER_SPINUP_TAU = 0.5;
+/** Time constant (s) for the platter coasting to rest — heavier, slower. */
+export const PLATTER_SPINDOWN_TAU = 1.2;
+/** Below this speed (deg/s) the coast is over — snap to rest and park the loop. */
+const PLATTER_REST_DPS = 0.5;
+/** Clamp per-frame dt so a backgrounded tab doesn't fling the disc on return. */
+const MAX_FRAME_S = 0.05;
+
+/**
+ * Advance the platter one frame (pure). Velocity eases toward `targetDps` with an
+ * exponential approach over `tauSec`, then the angle integrates that velocity.
+ *
+ * The approach uses `1 - e^(-dt/tau)`, which composes exactly across substeps
+ * (one step of 2·dt equals two steps of dt), so the spin speed is frame-rate
+ * independent. A non-positive dt is treated as a no-op.
+ */
+export function stepPlatter(
+  state: PlatterState,
+  dtSec: number,
+  targetDps: number,
+  tauSec: number,
+): PlatterState {
+  if (dtSec <= 0) return { angle: state.angle, velocity: state.velocity };
+  const approach = 1 - Math.exp(-dtSec / tauSec);
+  const velocity = state.velocity + (targetDps - state.velocity) * approach;
+  const angle = ((state.angle + velocity * dtSec) % 360 + 360) % 360;
+  return { angle, velocity };
+}
+
+export interface PlatterHandle {
+  /** Engage the motor — the disc spins up to full speed. */
+  start(): void;
+  /** Cut the motor — the disc coasts down to rest. */
+  stop(): void;
+  /** Permanent teardown — cancels the frame loop. */
+  destroy(): void;
+}
+
+function prefersReduced(): boolean {
+  return globalThis.matchMedia?.('(prefers-reduced-motion: reduce)').matches ?? false;
+}
+
+/**
+ * Drive the no-cover record's spin with inertia. `start()`/`stop()` set the
+ * target speed; a single rAF loop eases velocity toward it and writes the disc's
+ * rotation each frame, parking itself once the platter has fully coasted to rest.
+ */
+export function createPlatterSpin(figure: HTMLElement): PlatterHandle {
+  // Mutable state on a const record (the repo bans `let`).
+  const state: {
+    angle: number;
+    velocity: number;
+    target: number;
+    raf: number | null;
+    last: number;
+  } = { angle: 0, velocity: 0, target: 0, raf: null, last: 0 };
+
+  const disc = (): HTMLElement | null => figure.querySelector('.blok-audio-cover__disc');
+
+  const tick = (now: number): void => {
+    const dt = state.last ? Math.min((now - state.last) / 1000, MAX_FRAME_S) : 0;
+    state.last = now;
+    // Spin-up while accelerating toward the target; the heavier coast on the way down.
+    const tau = state.target > state.velocity ? PLATTER_SPINUP_TAU : PLATTER_SPINDOWN_TAU;
+    const next = stepPlatter({ angle: state.angle, velocity: state.velocity }, dt, state.target, tau);
+    state.angle = next.angle;
+    state.velocity = next.velocity;
+
+    const el = disc();
+    if (el) el.style.transform = `rotate(${state.angle.toFixed(2)}deg)`;
+
+    // Coasted to a halt — snap clean and let the loop sleep until the next start().
+    if (state.target === 0 && state.velocity < PLATTER_REST_DPS) {
+      state.velocity = 0;
+      state.raf = null;
+      return;
+    }
+    state.raf = globalThis.requestAnimationFrame(tick);
+  };
+
+  const ensureRunning = (): void => {
+    if (state.raf !== null) return;
+    state.last = 0; // first frame measures dt=0, so no jump from a stale timestamp
+    state.raf = globalThis.requestAnimationFrame(tick);
+  };
+
+  const start = (): void => {
+    if (prefersReduced()) return; // reduced motion: the record holds still
+    if (!disc()) return; // cover image shown (no placeholder disc) — nothing to spin
+    state.target = PLATTER_FULL_DPS;
+    ensureRunning();
+  };
+
+  const stop = (): void => {
+    state.target = 0;
+    // Keep the loop alive to animate the wind-down; if it's already at rest
+    // (or never spun up under reduced motion) there's nothing to coast.
+    if (state.velocity > 0) ensureRunning();
+  };
+
+  const destroy = (): void => {
+    if (state.raf !== null) {
+      globalThis.cancelAnimationFrame(state.raf);
+      state.raf = null;
+    }
+    state.velocity = 0;
+    state.target = 0;
+  };
+
+  return { start, stop, destroy };
+}

package/src/tools/audio/index.ts

@@ -18,15 +18,18 @@ import {
   IconCaption,
   IconCopy,
   IconDownload,
+  IconImage,
   IconMusic,
   IconPlayerLoop,
   IconReplace,
+  IconTrash,
 } from '../../components/icons';
 import { renderUploadingState, type UploadingStateElement } from '../image/uploading-state';
 import { DEFAULT_CAPTION_PLACEHOLDER, URL_PATTERN } from './constants';
 import { renderEmptyState, type EmptyStateElement } from './empty-state';
 import { tr } from './i18n';
 import { renderCaptionRow, renderNowPlaying } from './ui';
+import { openCoverPicker, validateCoverFile, type CoverPickerHandle } from './cover-picker';
 import { attachControls, type ControlsHandle } from './controls';
 import { attachWaveform, decodePeaks, type WaveformHandle } from './waveform';
 import { readTrackMetadata, resolveCover } from './metadata';
@@ -52,6 +55,7 @@ export class AudioTool implements BlockTool {
   private controlsHandle: ControlsHandle | null = null;
   private waveformHandle: WaveformHandle | null = null;
   private destroyed = false;
+  private coverPicker: CoverPickerHandle | null = null;
   /** Pending fallback timer for the caption collapse-out animation. */
   private captionExitTimer: ReturnType<typeof setTimeout> | null = null;
 
@@ -124,7 +128,13 @@ export class AudioTool implements BlockTool {
   }
 
   public getToolbarAnchorElement(): HTMLElement | undefined {
-    return this.root?.querySelector<HTMLElement>('[data-role="audio-figure"]') ?? undefined;
+    // Anchor on the top-of-card marker so the +/tunes buttons sit flush with the
+    // top of the cover art. Fall back to the figure if the marker isn't present.
+    return (
+      this.root?.querySelector<HTMLElement>('[data-role="audio-toolbar-anchor"]') ??
+      this.root?.querySelector<HTMLElement>('[data-role="audio-figure"]') ??
+      undefined
+    );
   }
 
   public setReadOnly(state: boolean): void {
@@ -182,6 +192,22 @@ export class AudioTool implements BlockTool {
         closeOnActivate: true,
         onActivate: (): void => this.transitionToEmpty(),
       },
+      {
+        icon: IconImage,
+        title: tr(i18n, 'tools.audio.coverSet', 'Set cover image'),
+        name: 'audio-cover-set',
+        closeOnActivate: true,
+        onActivate: (): void => this.openCoverPicker(),
+      },
+      ...(this.data.coverUrl
+        ? [{
+          icon: IconTrash,
+          title: tr(i18n, 'tools.audio.coverRemove', 'Remove cover'),
+          name: 'audio-cover-remove',
+          closeOnActivate: true,
+          onActivate: (): void => this.removeCover(),
+        }]
+        : []),
       {
         icon: IconDownload,
         title: tr(i18n, 'tools.audio.download', 'Download'),
@@ -209,6 +235,11 @@ export class AudioTool implements BlockTool {
     if (this.data.url.startsWith('blob:')) {
       URL.revokeObjectURL(this.data.url);
     }
+    if (this.data.coverUrl?.startsWith('blob:')) {
+      URL.revokeObjectURL(this.data.coverUrl);
+    }
+    this.coverPicker?.close();
+    this.coverPicker = null;
   }
 
   private startUpload(file: File): void {
@@ -373,10 +404,11 @@ export class AudioTool implements BlockTool {
     const titlePlaceholder = tr(this.api.i18n, 'tools.audio.titlePlaceholder', 'Track title');
     const artistPlaceholder = tr(this.api.i18n, 'tools.audio.artistPlaceholder', 'Artist');
 
-    const { figure, audio, waveformMount, title, artist, body } = renderNowPlaying(this.data, {
+    const { figure, audio, waveformMount, title, artist, body, coverButton } = renderNowPlaying(this.data, {
       editable: !this.readOnly,
       titlePlaceholder,
       artistPlaceholder,
+      coverChangeLabel: tr(this.api.i18n, 'tools.audio.coverChange', 'Change cover'),
     });
 
     // Waveform (if peaks are available)
@@ -418,6 +450,8 @@ export class AudioTool implements BlockTool {
       }
     });
 
+    coverButton?.addEventListener('click', () => this.openCoverPicker());
+
     this.root.appendChild(figure);
   }
 
@@ -480,9 +514,11 @@ export class AudioTool implements BlockTool {
       return;
     }
     const row = this.createCaptionRow();
+    // Appended at full height immediately (a single layout step); is-collapsed
+    // only offsets/fades the inner, so the reveal animates on the compositor.
     row.classList.add('is-collapsed');
     figure.appendChild(row);
-    // Force a reflow so the collapsed state is committed, then expand into view.
+    // Commit the collapsed start frame, then settle the inner into place.
     void row.offsetHeight;
     row.classList.remove('is-collapsed');
   }
@@ -493,11 +529,13 @@ export class AudioTool implements BlockTool {
     row.classList.add('is-collapsed');
     const finish = (): void => {
       if (this.captionExitTimer) { clearTimeout(this.captionExitTimer); this.captionExitTimer = null; }
+      row.removeEventListener('transitionend', onEnd);
       row.remove();
     };
-    row.addEventListener('transitionend', (e) => {
-      if (e.propertyName === 'grid-template-rows') finish();
-    }, { once: true });
+    const onEnd = (e: TransitionEvent): void => {
+      if (e.propertyName === 'opacity') finish();
+    };
+    row.addEventListener('transitionend', onEnd);
     // Fallback in case transitionend never fires (display:none, interrupted, etc.).
     this.captionExitTimer = setTimeout(finish, 360);
   }
@@ -534,4 +572,74 @@ export class AudioTool implements BlockTool {
       void clip.writeText(this.data.url);
     }
   }
+
+  private openCoverPicker(): void {
+    if (this.readOnly) return;
+    const anchor = this.root?.querySelector<HTMLElement>('[data-role="audio-cover"]');
+    if (!anchor) return;
+    this.coverPicker?.close();
+    // Keep the cover's hover affordance (scrim + change icon) lit while the
+    // picker is open — the pointer has left the cover for the popup, so :hover
+    // alone would drop it.
+    anchor.classList.add('is-picker-open');
+    this.coverPicker = openCoverPicker({
+      anchor,
+      i18n: this.api.i18n,
+      onFile: (file) => this.applyCoverFile(file),
+      onUrl: (url) => this.applyCoverUrl(url),
+      onClose: () => {
+        anchor.classList.remove('is-picker-open');
+        this.coverPicker = null;
+      },
+    });
+  }
+
+  private applyCoverFile(file: File): void {
+    const error = validateCoverFile(file, this.api.i18n);
+    if (error) {
+      this.coverPicker?.setError(error);
+      return;
+    }
+    const uploader = this.config.uploader;
+    const upload = uploader?.uploadByFile
+      ? uploader.uploadByFile(file).then((res) => res.url)
+      : Promise.resolve(URL.createObjectURL(file));
+    void upload
+      .then((url) => {
+        if (this.destroyed) {
+          // Block was removed mid-upload: a no-uploader blob URL would otherwise
+          // leak (it was never assigned to coverUrl, so removed() can't revoke it).
+          if (url.startsWith('blob:')) URL.revokeObjectURL(url);
+          return;
+        }
+        this.setCover(url);
+        this.coverPicker?.close();
+      })
+      .catch(() => {
+        this.coverPicker?.setError(
+          tr(this.api.i18n, 'tools.audio.errorUploadFailed', 'Upload failed')
+        );
+      });
+  }
+
+  private applyCoverUrl(url: string): void {
+    this.setCover(url);
+    this.coverPicker?.close();
+  }
+
+  private setCover(url: string): void {
+    const prev = this.data.coverUrl;
+    if (prev && prev !== url && prev.startsWith('blob:')) URL.revokeObjectURL(prev);
+    this.data.coverUrl = url;
+    this.renderState();
+    this.block.dispatchChange();
+  }
+
+  private removeCover(): void {
+    const prev = this.data.coverUrl;
+    if (prev?.startsWith('blob:')) URL.revokeObjectURL(prev);
+    this.data.coverUrl = undefined;
+    this.renderState();
+    this.block.dispatchChange();
+  }
 }

package/src/tools/audio/liveliness.ts

@@ -70,10 +70,21 @@ export function ambientWave(index: number, timeSeconds: number): number {
   return a * 0.6 + b * 0.4;
 }
 
+/** Comet-body lift at the playhead, tapering out along the wake/leading edge. */
+const COMET_FLOOR = 0.34;
+/** Extra lift layered onto the tight head spike right under the playhead. */
+const HEAD_FLOOR = 0.5;
+/**
+ * How hard the comet pulses, as a fraction of its floor. Kept < 1 so the
+ * downward half of the swing never drops a bar below its lifted base — the
+ * dance reads as a strong pump, never a hole punched into the waveform.
+ */
+const DANCE_THROW = 0.82;
+
 /** Ambient swing applied to every bar (the faint preview-side breath). */
-const AMBIENT_BASE = 0.035;
+const AMBIENT_BASE = 0.04;
 /** Extra ambient swing layered onto the played side (the shimmering wake). */
-const AMBIENT_PLAYED = 0.06;
+const AMBIENT_PLAYED = 0.17;
 /** Bars ahead of the playhead over which the played-side shimmer fades out. */
 const AMBIENT_AHEAD_FADE = 26;
 
@@ -119,16 +130,23 @@ export function liveAmplitude(opts: LiveAmplitudeOptions): number {
   if (reduced || energy <= 0) return basePeak;
 
   const distance = index - playheadIndex;
-
-  // Layer 1 — focal comet near the playhead.
   const env = cometEnvelope(distance);
   const head = headFocus(distance);
-  const comet = env * 0.15 + head * 0.2 + env * 0.28 * barWobble(index, timeSeconds);
 
-  // Layer 2 — global ambient ripple. Full strength behind the playhead (the
-  // played wake), fading across AMBIENT_AHEAD_FADE bars into the preview ahead.
+  // Layer 1 — focal comet. A guaranteed-positive "alive" floor blooms at the
+  // playhead and tapers along the wake, lifting even silent bars into view. A
+  // vigorous bidirectional pulse then rides on top — but its swing is capped at
+  // DANCE_THROW of the floor, so the trough stays at/above the lifted base. Big
+  // visible motion, yet it can never gouge a bar back down to a flat dot.
+  const floor = env * COMET_FLOOR + head * HEAD_FLOOR;
+  const comet = floor * (1 + DANCE_THROW * barWobble(index, timeSeconds));
+
+  // Layer 2 — global ambient breath. Rectified to [0, 1] so it only adds, it
+  // keeps the whole field shimmering: full strength on the played wake, fading
+  // across AMBIENT_AHEAD_FADE bars into the preview ahead.
   const playedBias = distance <= 0 ? 1 : Math.max(0, 1 - distance / AMBIENT_AHEAD_FADE);
-  const ambient = ambientWave(index, timeSeconds) * (AMBIENT_BASE + AMBIENT_PLAYED * playedBias);
+  const ripple = (ambientWave(index, timeSeconds) + 1) / 2;
+  const ambient = ripple * (AMBIENT_BASE + AMBIENT_PLAYED * playedBias);
 
   const amp = basePeak + (comet + ambient) * energy;