@jackuait/blok 0.19.1 → 0.20.0

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;
 

package/src/tools/audio/ui.ts

@@ -1,10 +1,11 @@
-import { IconMusic } from '../../components/icons';
 import type { AudioData } from '../../../types/tools/audio';
+import { IconImage } from '../../components/icons';
 
 export interface NowPlayingOptions {
   editable: boolean;
   titlePlaceholder?: string;
   artistPlaceholder?: string;
+  coverChangeLabel?: string;
 }
 
 export interface NowPlayingElements {
@@ -15,6 +16,7 @@ export interface NowPlayingElements {
   waveformMount: HTMLElement;
   title: HTMLElement;
   artist: HTMLElement;
+  coverButton?: HTMLButtonElement;
 }
 
 function editableLine(role: string, value: string | undefined, editable: boolean, placeholder?: string): HTMLElement {
@@ -32,6 +34,15 @@ export function renderNowPlaying(data: AudioData, opts: NowPlayingOptions): NowP
   figure.setAttribute('data-role', 'audio-figure');
   figure.style.margin = '0';
 
+  // Zero-size marker pinned to the top of the card. The editor's toolbar centers
+  // the +/tunes buttons on the *first line* of the anchor it's handed; anchoring
+  // to this top marker (instead of the whole figure) lands those buttons flush
+  // with the top of the cover art rather than a line-height below it.
+  const toolbarAnchor = document.createElement('span');
+  toolbarAnchor.className = 'blok-audio-toolbar-anchor';
+  toolbarAnchor.setAttribute('data-role', 'audio-toolbar-anchor');
+  toolbarAnchor.setAttribute('aria-hidden', 'true');
+
   const cover = document.createElement('div');
   cover.className = 'blok-audio-cover';
   cover.setAttribute('data-role', 'audio-cover');
@@ -41,10 +52,18 @@ export function renderNowPlaying(data: AudioData, opts: NowPlayingOptions): NowP
     img.alt = '';
     cover.appendChild(img);
   } else {
+    // No artwork: stand a glossy black vinyl record in the panel instead of a
+    // flat "missing image" glyph. The disc (grooves + cream label + spindle, with
+    // a fixed specular it shimmers under) is pure CSS; its rotation is driven by
+    // disc.ts, which spins the platter up when the track plays and lets it coast
+    // down on pause — like a real turntable with mass.
     const placeholder = document.createElement('span');
     placeholder.className = 'blok-audio-cover__placeholder';
     placeholder.setAttribute('aria-hidden', 'true');
-    placeholder.innerHTML = IconMusic;
+    const disc = document.createElement('span');
+    disc.className = 'blok-audio-cover__disc';
+    disc.setAttribute('data-role', 'audio-cover-disc');
+    placeholder.append(disc);
     cover.appendChild(placeholder);
   }
 
@@ -62,6 +81,22 @@ export function renderNowPlaying(data: AudioData, opts: NowPlayingOptions): NowP
   });
   cover.appendChild(eq);
 
+  const coverButton = ((): HTMLButtonElement | undefined => {
+    if (!opts.editable) {
+      return undefined;
+    }
+
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.className = 'blok-audio-cover__change';
+    button.setAttribute('data-role', 'audio-cover-change');
+    button.setAttribute('aria-label', opts.coverChangeLabel ?? 'Change cover');
+    button.innerHTML = IconImage;
+    cover.appendChild(button);
+
+    return button;
+  })();
+
   const title = editableLine('audio-title', data.title, opts.editable, opts.titlePlaceholder);
   title.className = 'blok-audio-title';
   const artist = editableLine('audio-artist', data.artist, opts.editable, opts.artistPlaceholder);
@@ -83,8 +118,8 @@ export function renderNowPlaying(data: AudioData, opts: NowPlayingOptions): NowP
   audio.tabIndex = 0;
   if (data.loop) audio.loop = true;
 
-  figure.append(cover, body, audio);
-  return { figure, audio, cover, body, waveformMount, title, artist };
+  figure.append(toolbarAnchor, cover, body, audio);
+  return { figure, audio, cover, body, waveformMount, title, artist, coverButton };
 }
 
 export interface CaptionRowOptions {

package/types/api/tooltip.d.ts

@@ -1,7 +1,46 @@
 /**
  * Tooltip API
  */
-import {TooltipContent, TooltipOptions} from '../../src/components/utils/tooltip';
+
+/**
+ * Tooltip supported content
+ */
+export type TooltipContent = HTMLElement | DocumentFragment | Node | string;
+
+/**
+ * Base options interface for tooltips
+ */
+export interface TooltipOptions {
+  /**
+   * Tooltip placement: top|bottom|left|right
+   */
+  placement?: string;
+
+  /**
+   * Tooltip top margin
+   */
+  marginTop?: number;
+
+  /**
+   * Tooltip left margin
+   */
+  marginLeft?: number;
+
+  /**
+   * Tooltip right margin
+   */
+  marginRight?: number;
+
+  /**
+   * Tooltip bottom margin
+   */
+  marginBottom?: number;
+
+  /**
+   * Timeout before showing
+   */
+  delay?: number;
+}
 
 export interface Tooltip {
   /**

package/types/data-formats/output-data.d.ts

@@ -6,9 +6,12 @@ import { BlockId } from './block-id';
  * Output of one Tool
  *
  * @template Type - the string literal describing a tool type
- * @template Data - the structure describing a data object supported by the tool
+ * @template Data - the structure describing a data object supported by the tool.
+ *   Defaults to `Record<string, unknown>` (matching {@link BlockToolData}) so
+ *   reading saved block data is type-guarded: property access yields `unknown`,
+ *   not `any`. Pass a concrete shape for fully-typed access.
  */
-export interface OutputBlockData<Type extends string = string, Data extends object = any> {
+export interface OutputBlockData<Type extends string = string, Data extends object = Record<string, unknown>> {
   /**
    * Unique Id of the block
    */