@cardstack/boxel-cli 0.10.0 → 0.10.1-unstable.0

package/bundled-realms/pretui/internal/media-library.gts

@@ -0,0 +1,14 @@
+// Pretui — shared vocabulary for AssetWell and Gallery.
+import type { AssetKind } from './media-viewer';
+
+export const KIND_WORD: Readonly<Record<AssetKind, string>> = {
+  image: 'Image',
+  video: 'Video',
+  audio: 'Audio',
+  model: '3D model',
+  unknown: 'File',
+};
+
+/** Least-wrong frame for an asset whose dimensions nobody recorded. Stated
+ * once so the well and the rail cannot disagree about it. */
+export const FALLBACK_RATIO = '4 / 3';

package/bundled-realms/pretui/internal/media-viewer.gts

@@ -0,0 +1,322 @@
+// Pretui — the media asset vocabulary and the adapter registry, with the built-in adapters registered at load.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { AudioPlayer } from '../components/audio-player';
+import { VideoPlayer } from '../components/video-player';
+import type { MediaTrackSpec, TranscriptCue } from '../components/media-player';
+import { ImageFrame } from '../components/image-frame';
+
+// ── The asset vocabulary ─────────────────────────────────────────────────
+
+/** Every kind the shell can name. `'unknown'` is a real answer, not an
+ * error: it routes to the fallback, which says what it could not open. */
+export type AssetKind = 'image' | 'video' | 'audio' | 'model' | 'unknown';
+
+/** What a caller hands the viewer. Only `src` is required. */
+export interface MediaAssetSpec {
+  /** URL of the asset. Passed through untouched. */
+  src: string;
+  /** Display name. Also the accessible name of the viewer region. */
+  name?: string;
+  /** Force the kind, skipping detection. */
+  kind?: AssetKind;
+  /** MIME type, if the host knows it. Beats the extension. */
+  mimeType?: string;
+  /** Poster for video; also the grid thumbnail when `thumbnail` is absent. */
+  poster?: string;
+  /** Small preview image for grids. */
+  thumbnail?: string;
+  /** Alt text for image assets. An empty string marks it decorative. */
+  alt?: string;
+  /** Text tracks for time-based assets. */
+  tracks?: readonly MediaTrackSpec[];
+  /** Seekable transcript for time-based assets. */
+  transcript?: readonly TranscriptCue[];
+  /** Intrinsic width in pixels, used to reserve space before load. */
+  width?: number;
+  /** Intrinsic height in pixels, used to reserve space before load. */
+  height?: number;
+  /** Duration in seconds, for grid badges. */
+  duration?: number;
+  /** File size in bytes, for grid badges and the inspector. */
+  bytes?: number;
+  /** Free-form metadata; rendered as key/value rows where a surface has
+   * room for it. */
+  meta?: Readonly<Record<string, string>>;
+}
+
+/** A spec with the derived fields filled in. Adapters receive this, never
+ * the raw spec, so no adapter re-derives a kind or an aspect ratio. */
+export interface ResolvedMediaAsset extends MediaAssetSpec {
+  kind: AssetKind;
+  /** Always a usable display name — the file's basename when nothing else. */
+  label: string;
+  /** A CSS `aspect-ratio` value when width and height are both known. */
+  aspectRatio?: string;
+}
+
+const EXT_KIND: Readonly<Record<string, AssetKind>> = {
+  apng: 'image',
+  avif: 'image',
+  bmp: 'image',
+  gif: 'image',
+  heic: 'image',
+  jpeg: 'image',
+  jpg: 'image',
+  png: 'image',
+  svg: 'image',
+  tif: 'image',
+  tiff: 'image',
+  webp: 'image',
+  m4v: 'video',
+  mkv: 'video',
+  mov: 'video',
+  mp4: 'video',
+  ogv: 'video',
+  webm: 'video',
+  aac: 'audio',
+  flac: 'audio',
+  m4a: 'audio',
+  mp3: 'audio',
+  oga: 'audio',
+  ogg: 'audio',
+  opus: 'audio',
+  wav: 'audio',
+  weba: 'audio',
+  fbx: 'model',
+  glb: 'model',
+  gltf: 'model',
+  obj: 'model',
+  usdz: 'model',
+};
+
+const MIME_KIND: Readonly<Record<string, AssetKind>> = {
+  image: 'image',
+  video: 'video',
+  audio: 'audio',
+  model: 'model',
+};
+
+/** The MIME type of a `data:` URL, or `''`. Worth handling explicitly: a
+ * generated fixture has no extension at all, and half of this kit's media
+ * examples are data URLs so they work with no network. */
+function dataUrlMime(src: string): string {
+  if (!src.startsWith('data:')) {
+    return '';
+  }
+  const head = src.slice(5, 5 + 120);
+  const stop = Math.min(
+    head.includes(';') ? head.indexOf(';') : head.length,
+    head.includes(',') ? head.indexOf(',') : head.length,
+  );
+  return head.slice(0, stop);
+}
+
+/** The lowercase extension of a URL, with query and fragment stripped. */
+export function extensionOf(src: string): string {
+  const cut = src.split('#')[0].split('?')[0];
+  const slash = cut.lastIndexOf('/');
+  const name = slash >= 0 ? cut.slice(slash + 1) : cut;
+  const dot = name.lastIndexOf('.');
+  return dot > 0 ? name.slice(dot + 1).toLowerCase() : '';
+}
+
+/** Explicit kind, then MIME type, then extension. Deterministic, no
+ * network, no sniffing — a `HEAD` request would be a lie in a realm anyway,
+ * where every asset is behind header auth. */
+export function kindForAsset(asset: MediaAssetSpec): AssetKind {
+  if (asset.kind) {
+    return asset.kind;
+  }
+  const mime = asset.mimeType || dataUrlMime(asset.src);
+  if (mime) {
+    const top = mime.split('/')[0].trim().toLowerCase();
+    const mapped = MIME_KIND[top];
+    if (mapped) {
+      return mapped;
+    }
+  }
+  return EXT_KIND[extensionOf(asset.src)] ?? 'unknown';
+}
+
+/** The basename of a URL, for when the caller gave no name. */
+export function basenameOf(src: string): string {
+  if (src.startsWith('data:')) {
+    return 'Untitled asset';
+  }
+  const cut = src.split('#')[0].split('?')[0];
+  const slash = cut.lastIndexOf('/');
+  const name = slash >= 0 ? cut.slice(slash + 1) : cut;
+  if (name.length === 0) {
+    return 'Untitled asset';
+  }
+  try {
+    return decodeURIComponent(name);
+  } catch {
+    // a malformed escape such as `100%.png` names the file as written
+    return name;
+  }
+}
+
+const DATA_IMAGE = /^data:image\//i;
+
+/** `src` as a link target, or undefined when its scheme could run code
+ * (`javascript:`, `data:text/html`, …). http(s) and blob URLs link; with
+ * `images`, so do `data:image/` URLs, which a gallery may legitimately hold. */
+export function safeHref(
+  src: string | undefined,
+  { images = false }: { images?: boolean } = {},
+): string | undefined {
+  if (!src) {
+    return undefined;
+  }
+  if (images && DATA_IMAGE.test(src.trim())) {
+    return src;
+  }
+  try {
+    let base = globalThis.location?.href ?? 'http://localhost/';
+    let { protocol } = new URL(src, base);
+    return protocol === 'http:' || protocol === 'https:' || protocol === 'blob:'
+      ? src
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Fill in kind, label and aspect ratio once, at the shell, so no adapter
+ * and no grid tile ever repeats the work. */
+export function resolveAsset(asset: MediaAssetSpec): ResolvedMediaAsset {
+  const width = asset.width;
+  const height = asset.height;
+  const ratio =
+    width && height && width > 0 && height > 0
+      ? `${Math.round(width)} / ${Math.round(height)}`
+      : undefined;
+  return {
+    ...asset,
+    kind: kindForAsset(asset),
+    label: asset.name ?? basenameOf(asset.src),
+    aspectRatio: ratio,
+  };
+}
+
+/** Bytes as a short human string. Binary units, because that is what a file
+ * manager shows and an asset panel that disagrees with Finder is noise. */
+export function formatBytes(bytes: number | undefined): string {
+  if (!bytes || !Number.isFinite(bytes) || bytes < 0) {
+    return '';
+  }
+  const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+  let value = bytes;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value = value / 1024;
+    unit = unit + 1;
+  }
+  const rounded = value >= 100 || unit === 0 ? Math.round(value) : Math.round(value * 10) / 10;
+  return `${rounded} ${units[unit]}`;
+}
+
+// ── The adapter registry ─────────────────────────────────────────────────
+
+/** What every adapter component is handed. */
+export interface MediaAdapterSignature {
+  Args: { asset: ResolvedMediaAsset };
+  Element: HTMLElement;
+}
+
+/* eslint-disable-next-line @typescript-eslint/no-explicit-any -- Glint's
+   `ComponentLike` lives in `@glint/template`, which realm code cannot
+   import, and a structural constructor type is not invocable in a strict
+   template. `iconFor` in icon-registry.gts makes the same trade for the
+   same reason. Adapters are checked at their definition site instead, by
+   typing each one as TemplateOnlyComponent<MediaAdapterSignature>. */
+export type MediaAdapterComponent = any;
+
+export interface MediaAdapter {
+  /** Stable id. Registering the same id twice replaces the first. Also
+   * lands on the shell as `data-adapter`, which is how a test says which
+   * viewer ran without reaching into its markup. */
+  id: string;
+  /** Human name, used by the fallback when it explains what it wanted. */
+  label: string;
+  /** Does this adapter want the asset? Checked in registration order,
+   * newest first. */
+  handles: (asset: ResolvedMediaAsset) => boolean;
+  /** The component to render, invoked with `@asset`. */
+  component: MediaAdapterComponent;
+}
+
+const ADAPTERS: MediaAdapter[] = [];
+
+/** Register an adapter. The most recently registered adapter that claims an
+ * asset wins, so a consumer overrides a built-in by registering after this
+ * module loads — no patching, no fork. */
+export function registerMediaAdapter(adapter: MediaAdapter): void {
+  const existing = ADAPTERS.findIndex((a) => a.id === adapter.id);
+  if (existing >= 0) {
+    ADAPTERS.splice(existing, 1);
+  }
+  ADAPTERS.unshift(adapter);
+}
+
+/** Every registered adapter, newest first. */
+export function mediaAdapters(): readonly MediaAdapter[] {
+  return ADAPTERS;
+}
+
+/** The adapter that will run for this asset, if any. */
+export function adapterFor(
+  asset: ResolvedMediaAsset,
+): MediaAdapter | undefined {
+  return ADAPTERS.find((a) => a.handles(asset));
+}
+
+// ── The built-in adapters ────────────────────────────────────────────────
+
+const VideoAdapter: TemplateOnlyComponent<MediaAdapterSignature> = <template>
+  <VideoPlayer
+    @src={{@asset.src}}
+    @label={{@asset.label}}
+    @poster={{@asset.poster}}
+    @aspectRatio={{@asset.aspectRatio}}
+    @tracks={{@asset.tracks}}
+    @transcript={{@asset.transcript}}
+    ...attributes
+  />
+</template>;
+
+const AudioAdapter: TemplateOnlyComponent<MediaAdapterSignature> = <template>
+  <AudioPlayer
+    @src={{@asset.src}}
+    @label={{@asset.label}}
+    @title={{@asset.name}}
+    @cover={{@asset.thumbnail}}
+    @tracks={{@asset.tracks}}
+    @transcript={{@asset.transcript}}
+    ...attributes
+  />
+</template>;
+
+
+// Registered newest-first, so the array reads video, audio, image after
+// these three calls — the order is immaterial because the predicates are
+// mutually exclusive, but the rule is worth knowing when you override one.
+registerMediaAdapter({
+  id: 'image',
+  label: 'Image frame',
+  handles: (asset) => asset.kind === 'image',
+  component: ImageFrame,
+});
+registerMediaAdapter({
+  id: 'audio',
+  label: 'Audio player',
+  handles: (asset) => asset.kind === 'audio',
+  component: AudioAdapter,
+});
+registerMediaAdapter({
+  id: 'video',
+  label: 'Video player',
+  handles: (asset) => asset.kind === 'video',
+  component: VideoAdapter,
+});

package/bundled-realms/pretui/internal/media-wave.gts

@@ -0,0 +1,270 @@
+// Pretui — the wavesurfer engine and keyboard geometry shared by Waveform and TrimBar.
+//
+//   <Waveform @src={{url}} @label='Lot B-1180' />
+//   <TrimBar  @src={{url}} @start={{1}} @end={{4}} @onChange={{this.take}} />
+//
+// wavesurfer.js 7.12.11 (BSD-3-Clause, vendored at ./wavesurfer — see that
+// folder's README for the licence, the provenance and the audit) decodes the
+// audio and paints the peaks. Everything else here is Pretui's.
+//
+// Four decisions worth stating:
+//
+//   1. **The engine is created in a modifier and destroyed in its
+//      destructor** — the rAF ruling, exactly. wavesurfer runs one
+//      `requestAnimationFrame` loop while playing and holds an AudioContext,
+//      a fetch, a ResizeObserver and a media element; `destroy()` releases all
+//      of them and it is called on teardown and whenever the engine key
+//      changes (`@src`, height, bar geometry). Nothing here constructs an engine in a getter, where the realm
+//      indexer could reach it outside a browser.
+//   2. **Construction is wrapped in try/catch and failure is a state, not a
+//      crash.** A waveform lives or dies on a decode, and a headless browser
+//      has no real media pipeline. `phase` is part of the public contract —
+//      `idle → loading → ready`, or `error` — so a caller and a test can both
+//      assert on what happened without asserting that a decode succeeded.
+//   3. **The waveform is a `role='slider'`, not a canvas you can only click.**
+//      wavesurfer gives pointer seeking and nothing else: no tab stop, no
+//      arrow keys, no announced position. The keyboard floor is met here,
+//      not in the library: one tab stop, ←/→ by step, Shift for a coarse step,
+//      PageUp/PageDown, Home/End, Space to play, and an `aria-valuetext` that
+//      says "0:03 of 0:06" rather than reading out a float.
+//   4. **`TrimBar` owns its own handles.** The regions plugin paints the
+//      selection and holds the range, but its handles are pointer-only divs
+//      inside wavesurfer's shadow root — unreachable by keyboard and
+//      unstylable from here. So the region is created with `drag:false,
+//      resize:false` and the two handles are real focusable elements in the
+//      light DOM, each a `role='slider'` with its own min, max and value. One
+//      visual, one interaction model, and the in-point cannot cross the out.
+//
+// BETTER THAN THE INSPIRATION: every wavesurfer example on the web is
+// `WaveSurfer.create({container: '#waveform'})` with a play button and no
+// keyboard path at all. The trimmer examples are worse — a draggable region
+// with no announced value, which is unusable without a mouse.
+import { modifier } from 'ember-modifier';
+import WaveSurfer, { RegionsPlugin } from '../wavesurfer/index.js';
+
+/** Where a waveform is. `error` is a first-class outcome: an undecodable
+ * source is normal (a headless browser, a 404, a codec nobody has). */
+export type WavePhase = 'idle' | 'loading' | 'ready' | 'error';
+
+/** What both components hand the shared engine modifier. */
+interface WaveHost {
+  /** Pixel height of the drawing area. */
+  height: number;
+  /** Bar rendering, or a continuous wave when `barWidth` is 0. */
+  barWidth: number;
+  barGap: number;
+  /** Normalize peaks to the tallest sample. */
+  normalize: boolean;
+  /** Let wavesurfer handle pointer seeking. `TrimBar` says no — its pointer
+   * gestures belong to its handles. */
+  interact: boolean;
+  /** Create a region and hand it back. */
+  wantsRegions: boolean;
+  onEngine: (engine: WaveEngine | null) => void;
+  onPhase: (phase: WavePhase, message: string) => void;
+  onDuration: (seconds: number) => void;
+  onTime: (seconds: number) => void;
+  onPlaying: (playing: boolean) => void;
+  onRegionReady: (region: WaveRegion | null) => void;
+}
+
+/* eslint-disable @typescript-eslint/no-explicit-any -- the vendored bundle
+   ships no type declarations (the same trade `surfaces-preview.gts` makes for
+   `./surfaces/index.js`). The surface actually used is narrow and is described
+   by the two interfaces below, which is where the checking happens. */
+type AnyEngine = any;
+/* eslint-enable @typescript-eslint/no-explicit-any */
+
+/** The slice of wavesurfer this module uses. */
+export interface WaveEngine {
+  play: () => void;
+  pause: () => void;
+  isPlaying: () => boolean;
+  setTime: (seconds: number) => void;
+  getDuration: () => number;
+  getCurrentTime: () => number;
+  destroy: () => void;
+  on: (event: string, handler: (...args: unknown[]) => void) => void;
+}
+
+/** The slice of a regions-plugin region this module uses. */
+export interface WaveRegion {
+  start: number;
+  end: number;
+  setOptions: (options: { start?: number; end?: number }) => void;
+  remove: () => void;
+}
+
+/** Read a Pretui token off the live element as a concrete colour. wavesurfer
+ * paints into a canvas, and a canvas cannot resolve `var(--primary)` — so the
+ * theme is resolved once, at construction. A theme switch shows on the next
+ * rebuild (a new `@src`, height or bar geometry), not live. */
+function tokenColor(styles: CSSStyleDeclaration, name: string, fallback: string): string {
+  const raw = styles.getPropertyValue(name).trim();
+  return raw.length > 0 ? raw : fallback;
+}
+
+/**
+ * Own one wavesurfer instance for the life of the element.
+ *
+ * The third positional is a plain key string: change `@src`, the height or the
+ * bar geometry and the key changes, ember-modifier tears the
+ * engine down and it is rebuilt. wavesurfer reads its colours into a canvas
+ * gradient at construction and has no setter for most of them, so a rebuild is
+ * the honest answer rather than a pretend-live one.
+ */
+export const waveEngine = modifier(
+  (el: HTMLElement, [host, src, _key]: [WaveHost, string, string]) => {
+    let engine: AnyEngine = null;
+    let region: WaveRegion | null = null;
+    let torn = false;
+
+    const styles = getComputedStyle(el);
+    // Law 5: consent before motion. Auto-scrolling the waveform under a
+    // moving playhead is motion; reduced motion pins it.
+    const reduced =
+      typeof window !== 'undefined' &&
+      typeof window.matchMedia === 'function' &&
+      window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+    try {
+      const plugins = [];
+      let regions: AnyEngine = null;
+      if (host.wantsRegions) {
+        regions = RegionsPlugin.create();
+        plugins.push(regions);
+      }
+      host.onPhase('loading', 'Decoding audio');
+      engine = WaveSurfer.create({
+        container: el,
+        url: src,
+        height: host.height,
+        waveColor: tokenColor(styles, '--muted-foreground', '#9aa0a8'),
+        progressColor: tokenColor(styles, '--primary', '#5b7cfa'),
+        cursorColor: tokenColor(styles, '--foreground', '#16181d'),
+        cursorWidth: 2,
+        barWidth: host.barWidth > 0 ? host.barWidth : undefined,
+        barGap: host.barWidth > 0 ? host.barGap : undefined,
+        barRadius: host.barWidth > 0 ? Math.round(host.barWidth / 2) : undefined,
+        normalize: host.normalize,
+        interact: host.interact,
+        dragToSeek: host.interact,
+        autoScroll: !reduced,
+        // No autoplay, ever. Stated rather than defaulted.
+        autoplay: false,
+        plugins,
+      });
+      host.onEngine(engine as WaveEngine);
+
+      engine.on('decode', (duration: number) => {
+        if (!torn) {
+          host.onDuration(duration);
+        }
+      });
+      engine.on('ready', (duration: number) => {
+        if (torn) {
+          return;
+        }
+        // Phase BEFORE duration: `onDuration` is what forwards `@onReady`,
+        // and it only does so once the component is actually ready. Set the
+        // duration first and the callback is swallowed.
+        host.onPhase('ready', '');
+        host.onDuration(duration);
+        if (regions) {
+          // A region covering the middle half, which is a better starting
+          // guess than "everything" (nothing to trim) or "nothing" (a
+          // zero-width handle stack the user has to prise apart).
+          region = regions.addRegion({
+            id: 'pretui-trim',
+            start: duration * 0.25,
+            end: duration * 0.75,
+            drag: false,
+            resize: false,
+            color: 'rgba(91, 124, 250, 0.18)',
+          }) as WaveRegion;
+          host.onRegionReady(region);
+        }
+      });
+      engine.on('timeupdate', (time: number) => {
+        if (!torn) {
+          host.onTime(time);
+        }
+      });
+      engine.on('play', () => !torn && host.onPlaying(true));
+      engine.on('pause', () => !torn && host.onPlaying(false));
+      engine.on('finish', () => !torn && host.onPlaying(false));
+      engine.on('error', (err: unknown) => {
+        if (!torn) {
+          host.onPhase(
+            'error',
+            err instanceof Error ? err.message : 'This audio could not be decoded.',
+          );
+        }
+      });
+    } catch (err) {
+      host.onPhase(
+        'error',
+        err instanceof Error ? err.message : 'A waveform could not be created here.',
+      );
+    }
+
+    return () => {
+      torn = true;
+      host.onEngine(null);
+      host.onRegionReady(null);
+      region = null;
+      try {
+        // Aborts the in-flight fetch, cancels the rAF playback loop, closes
+        // the AudioContext, disconnects the ResizeObserver, unsubscribes every
+        // emitter and drops the media element wavesurfer created.
+        engine?.destroy();
+      } catch {
+        // A destroy that throws during teardown must not take the teardown
+        // with it — there is nothing left to salvage either way.
+      }
+    };
+  },
+);
+
+/** How far one key press moves, in seconds. Fine step for arrows, coarse for
+ * Shift, page for PageUp/PageDown — the standard slider triple. */
+export interface WaveSteps {
+  fine: number;
+  coarse: number;
+  page: number;
+}
+
+export function stepsFor(duration: number, fine: number): WaveSteps {
+  const safe = duration > 0 ? duration : 1;
+  return {
+    fine,
+    coarse: fine * 5,
+    page: Math.max(fine * 10, safe / 10),
+  };
+}
+
+/** Resolve a key press to a delta in seconds, or `null` for "not ours". */
+export function waveDelta(
+  event: KeyboardEvent,
+  steps: WaveSteps,
+): number | null {
+  const step = event.shiftKey ? steps.coarse : steps.fine;
+  switch (event.key) {
+    case 'ArrowRight':
+    case 'ArrowUp':
+      return step;
+    case 'ArrowLeft':
+    case 'ArrowDown':
+      return -step;
+    case 'PageUp':
+      return steps.page;
+    case 'PageDown':
+      return -steps.page;
+    default:
+      return null;
+  }
+}
+
+export function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}