@half-built/astro 0.1.0

package/src/scripts/path-player-paint.ts

@@ -0,0 +1,154 @@
+/* Canvas painters for the path-player timeline; each takes a Painter
+   and paints one thing at a given top. Pure over the context they are
+   handed, so tests drive them with a recording context (test/helpers.ts)
+   and never need a real canvas. The transport in path-player.ts composes
+   them once per layout onto an offscreen canvas. */
+import { normalizeSeries, brightChannel, columnIndex, seriesY } from "./path-player-math";
+import type { BandTrack, LinesTrack } from "./path-player";
+
+export const AXIS_STEP_S = 2;
+/* Theme-less defaults for the timeline's paper, ink, and rule, used when
+   a Painter carries none (the pure painter tests). The transport passes
+   the theme's --well, --ink, and --rule so the tracks follow day and
+   night like the rest of the plate (owner call 2026-08-26). */
+export const PAPER = "#ffffff";
+export const INK = "#111111";
+export const ink = (alpha: number): string => `rgba(17, 17, 17, ${alpha})`;
+
+/* Everything the static painters share: the context, the plate width,
+   the time-to-x map, a CSS custom property reader for series colors,
+   and the theme's paper, ink, and rule. */
+export interface Painter {
+  ctx: CanvasRenderingContext2D;
+  width: number;
+  xAt: (t: number) => number;
+  cssColor: (v: string) => string;
+  paper?: string;
+  ink?: string;
+  rule?: string;
+}
+
+const paperOf = (p: Painter): string => p.paper ?? PAPER;
+const ruleOf = (p: Painter): string => p.rule ?? INK;
+
+/* The ink at an alpha. Custom properties resolve to hex, which the
+   canvas cannot take with an alpha, so the hex is split here; any
+   other form falls back to the fixed ink. */
+export function inkOf(p: Painter, alpha: number): string {
+  const m = /^#([0-9a-f]{6})$/i.exec(p.ink ?? "");
+  if (!m) return ink(alpha);
+  const n = parseInt(m[1], 16);
+  return `rgba(${n >> 16}, ${(n >> 8) & 255}, ${n & 255}, ${alpha})`;
+}
+
+/* The 2px rule every track wears, inside its own edge, so a band and a
+   lines track sit in the same frame the window does. */
+function frameTrack(p: Painter, top: number, height: number): void {
+  p.ctx.strokeStyle = ruleOf(p);
+  p.ctx.lineWidth = 2;
+  p.ctx.strokeRect(1, top + 1, p.width - 2, height - 2);
+}
+
+/* Polyline of a series across the track, one point per pixel column,
+   held inside the track by pad on both edges. */
+export function strokeSeries(p: Painter, values: number[], top: number, height: number, pad: number, style: string): void {
+  const n = normalizeSeries(values);
+  p.ctx.beginPath();
+  for (let px = 0; px < p.width; px++) {
+    const y = seriesY(n.frac(values[columnIndex(px, p.width, values.length)]), top, height, pad);
+    if (px === 0) p.ctx.moveTo(px, y); else p.ctx.lineTo(px, y);
+  }
+  p.ctx.strokeStyle = style;
+  p.ctx.lineWidth = 1.5;
+  p.ctx.stroke();
+}
+
+/* A band track is a color strip, one sample per column, with the
+   envelope drawn over it in white. */
+export function paintBand(p: Painter, track: BandTrack, top: number, sampleCount: number): void {
+  for (let px = 0; px < p.width; px++) {
+    const c = track.colorAt(columnIndex(px, p.width, sampleCount));
+    p.ctx.fillStyle = `rgb(${brightChannel(c.r)}, ${brightChannel(c.g)}, ${brightChannel(c.b)})`;
+    p.ctx.fillRect(px, top, 1.5, track.height);
+  }
+  const env = Array.from({ length: sampleCount }, (_, i) => track.envelopeAt(i));
+  strokeSeries(p, env, top, track.height, 3, "rgba(255, 255, 255, 0.9)");
+  frameTrack(p, top, track.height);
+}
+
+/* A lines track is a paper panel: shaded regions, labeled ticks, one
+   polyline per series in its CSS color, series labels stacked at the
+   right edge. */
+export function paintLines(p: Painter, track: LinesTrack, top: number): void {
+  const { ctx, width, xAt } = p;
+  ctx.fillStyle = paperOf(p);
+  ctx.fillRect(0, top, width, track.height);
+  ctx.fillStyle = inkOf(p, 0.07);
+  for (const r of track.regions) {
+    ctx.fillRect(xAt(r.t0), top, xAt(r.t1) - xAt(r.t0), track.height);
+  }
+  ctx.strokeStyle = inkOf(p, 0.35);
+  ctx.fillStyle = inkOf(p, 0.55);
+  ctx.lineWidth = 1;
+  ctx.font = "8px sans-serif";
+  ctx.textAlign = "center";
+  for (const tick of track.ticks) {
+    ctx.beginPath();
+    ctx.moveTo(xAt(tick.t), top);
+    ctx.lineTo(xAt(tick.t), top + track.height);
+    ctx.stroke();
+    ctx.fillText(tick.label, xAt(tick.t), top + 8);
+  }
+  for (const s of track.series) {
+    strokeSeries(p, s.values, top, track.height, 5, p.cssColor(s.cssVar));
+  }
+  /* Series labels in series order, left to right, ending at the right
+     edge (X Y Z, owner call 2026-08-26; stacking from the edge read
+     backwards). */
+  ctx.font = "bold 9px sans-serif";
+  ctx.textAlign = "right";
+  const last = track.series.length - 1;
+  track.series.forEach((s, i) => {
+    ctx.fillStyle = p.cssColor(s.cssVar);
+    ctx.fillText(s.label.toUpperCase(), width - 4 - (last - i) * 14, top + track.height - 4);
+  });
+  frameTrack(p, top, track.height);
+}
+
+/* The chip names the track the way the caption does (FEED, PATH);
+   white ground so it reads over the band colors too. */
+export function paintLabelChip(p: Painter, label: string, top: number): void {
+  const { ctx } = p;
+  ctx.font = "bold 9px sans-serif";
+  ctx.textAlign = "left";
+  const labelW = ctx.measureText(label).width;
+  ctx.fillStyle = paperOf(p);
+  ctx.fillRect(2, top + 2, labelW + 8, 12);
+  ctx.strokeStyle = inkOf(p, 0.35);
+  ctx.lineWidth = 1;
+  ctx.strokeRect(2.5, top + 2.5, labelW + 7, 11);
+  ctx.fillStyle = inkOf(p, 0.8);
+  ctx.fillText(label, 6, top + 11);
+}
+
+/* Time axis under the last track: a tick and "Ns" label every
+   AXIS_STEP_S seconds. A label that would run off the canvas is
+   dropped; its tick stays (phone report 2026-08-27: the demo's "18s"
+   clipped to "18" on narrow plates, and flipping it left of the tick
+   crowded the neighbor, so the owner chose the empty end). */
+export function paintAxis(p: Painter, top: number, duration: number): void {
+  const { ctx, xAt, width } = p;
+  ctx.fillStyle = inkOf(p, 0.5);
+  ctx.strokeStyle = inkOf(p, 0.3);
+  ctx.font = "8px sans-serif";
+  ctx.textAlign = "left";
+  for (let t = 0; t < duration; t += AXIS_STEP_S) {
+    const x = xAt(t);
+    ctx.beginPath();
+    ctx.moveTo(x, top + 2);
+    ctx.lineTo(x, top + 6);
+    ctx.stroke();
+    const label = `${t}s`;
+    if (x + 2 + ctx.measureText(label).width <= width) ctx.fillText(label, x + 2, top + 11);
+  }
+}

package/src/scripts/path-player.ts

@@ -0,0 +1,341 @@
+/* Generic transport-and-timeline player over a plate-modal (spec
+   section 3). Knows nothing about fluids: samples, tracks, and the
+   sink come from the caller, and the sample type S is the caller's
+   too; the player only indexes the array and hands samples to the
+   sink. Scrubbing is implemented but ships off (owner call
+   2026-08-22); flip SCRUB to re-enable. */
+import { buildPlateModal } from "./plate-modal";
+import { createFrameLoop } from "./core/frame-loop";
+import { ICON_PLAY, ICON_PAUSE, ICON_ROTATE_CCW } from "./core/icons";
+import { playheadX, formatReadout, columnIndex } from "./path-player-math";
+import {
+  type Painter, paintBand, paintLines, paintLabelChip, paintAxis, INK,
+} from "./path-player-paint";
+
+/* Widened to `boolean` via assertion (not a `: boolean` annotation,
+   which no-inferrable-types rejects on a literal) so flipping this to
+   re-enable scrubbing is a one-line change: a literal type here would
+   make the `if (SCRUB)` below statically always-false and trip the
+   no-unnecessary-condition lint rule. Same widening idea as
+   src/scripts/henry-loose.ts's matchMedia guard. */
+const SCRUB = false as boolean;
+const AXIS_H = 14;
+const TRACK_GAP = 5;
+/* Caption ids: one player per page today, but aria-controls needs a
+   unique target if a second ever lands. */
+let captionSeq = 0;
+export interface BandTrack {
+  kind: "band";
+  height: number;
+  /* Painted as a small chip at the track's top-left, naming the track
+     the way the modal caption refers to it (FEED, PATH). */
+  label?: string;
+  colorAt: (i: number) => { r: number; g: number; b: number };
+  envelopeAt: (i: number) => number;
+}
+export interface LinesTrack {
+  kind: "lines";
+  height: number;
+  label?: string;
+  series: { label: string; values: number[]; cssVar: string }[];
+  regions: { t0: number; t1: number }[];
+  ticks: { t: number; label: string }[];
+}
+export type TrackSpec = BandTrack | LinesTrack;
+
+export interface PathPlayerConfig<S> {
+  title: string;
+  source: string;
+  caption: string;
+  duration: number;
+  samples: S[];
+  tracks: TrackSpec[];
+  buildStage: (viewbox: HTMLElement) => boolean | undefined;
+  sink: {
+    start: (s: S) => void; move: (s: S) => void; stop: () => void;
+    pause?: () => void; resume?: () => void;
+  };
+  /* Transport and caption-toggle text, defaulting to the English copy
+     this player shipped with. A caller with its own site voice (or a
+     future translation) overrides one, two, or all three. */
+  labels?: { play?: string; restart?: string; about?: string };
+}
+
+export interface PathPlayerHandle {
+  open: (opener: HTMLElement | null) => void;
+  close: () => void;
+  isPlaying: () => boolean;
+}
+
+/* Transport state shared with the optional scrub handlers. */
+interface TransportState { t: number; playing: boolean; lastIdx: number }
+
+/* Read-only timeline shipped (owner call 2026-08-22). When enabled:
+   pointer drag pauses the clock and paints the emitter along the path;
+   the fluid itself is never seekable, only the input. */
+function attachScrub(
+  timeline: HTMLElement, state: TransportState, duration: number,
+  applyCurrent: (useStart: boolean) => void, setPlaying: (playing: boolean) => void,
+): void {
+  let active = false;
+  let wasPlaying = false;
+  const seek = (ev: PointerEvent): void => {
+    const rect = timeline.getBoundingClientRect();
+    const frac = Math.max(0, Math.min(1, (ev.clientX - rect.left) / (rect.width || 1)));
+    state.t = frac * duration;
+  };
+  timeline.addEventListener("pointerdown", (ev) => {
+    active = true;
+    wasPlaying = state.playing;
+    state.playing = false;
+    timeline.setPointerCapture(ev.pointerId);
+    seek(ev);
+    applyCurrent(true);
+  });
+  timeline.addEventListener("pointermove", (ev) => {
+    if (!active) return;
+    seek(ev);
+    applyCurrent(false);
+  });
+  timeline.addEventListener("pointerup", () => {
+    active = false;
+    setPlaying(wasPlaying);
+  });
+}
+
+export function createPathPlayer<S>(doc: Document, config: PathPlayerConfig<S>): PathPlayerHandle {
+  const { play = "Play or pause", restart = "Restart", about = "ABOUT" } = config.labels ?? {};
+  const pm = buildPlateModal(doc, { ariaLabel: config.title });
+  pm.addLabel("topLeft", "pp-title").textContent = config.title;
+  pm.addLabel("bottomLeft", "pp-source").textContent = config.source;
+  const readout = pm.addLabel("bottomRight", "pp-readout");
+
+  const viewbox = doc.createElement("div");
+  viewbox.className = "pp-viewbox";
+  const stageReady = config.buildStage(viewbox) !== false;
+
+  /* Transport straddles the plate's bottom edge in the manner of the
+     boxed labels (owner call 2026-08-23); the timeline gets the full
+     plate width. */
+  const transport = doc.createElement("div");
+  transport.className = "pp-transport";
+  const playBtn = doc.createElement("button");
+  playBtn.type = "button";
+  playBtn.className = "pp-play icon-box press-box";
+  playBtn.setAttribute("aria-label", play);
+  const restartBtn = doc.createElement("button");
+  restartBtn.type = "button";
+  restartBtn.className = "pp-restart icon-box press-box";
+  restartBtn.setAttribute("aria-label", restart);
+  restartBtn.innerHTML = ICON_ROTATE_CCW;
+  if (!stageReady) { playBtn.disabled = true; restartBtn.disabled = true; }
+  const timeline = doc.createElement("div");
+  timeline.className = "pp-timeline";
+  const tracksCanvas = doc.createElement("canvas");
+  tracksCanvas.className = "pp-tracks";
+  timeline.append(tracksCanvas);
+  transport.append(playBtn, restartBtn);
+
+  const caption = doc.createElement("p");
+  caption.className = "pp-caption";
+  caption.id = `pp-caption-${String(++captionSeq)}`;
+  caption.textContent = config.caption;
+
+  /* Phones: the caption is the biggest discretionary block in the
+     plate (nine lines at xs), so it hides behind a toggle until asked
+     for (spec 2026-08-25, item 1). Wider viewports never see the
+     toggle (path-player.css) and always see the caption. */
+  const captionToggle = doc.createElement("button");
+  captionToggle.type = "button";
+  captionToggle.className = "pp-caption-toggle boxed-label micro-label press-box";
+  captionToggle.textContent = about;
+  captionToggle.setAttribute("aria-controls", caption.id);
+  /* Same widening as henry-loose.ts: jsdom has no matchMedia, and a
+     bare typeof check reads as always-true to the lint. The query list
+     type is widened too so a test stub without addEventListener is
+     still valid. */
+  interface PhoneQuery { matches: boolean; addEventListener?: (type: "change", cb: (ev: { matches: boolean }) => void) => void }
+  const phoneQuery = (): PhoneQuery | null => {
+    const mediaQuery = (globalThis as { matchMedia?: (q: string) => PhoneQuery }).matchMedia;
+    return mediaQuery ? mediaQuery.call(globalThis, "(max-width: 768px)") : null;
+  };
+  const phone = (): boolean => phoneQuery()?.matches ?? false;
+  const setCaptionShown = (shown: boolean): void => {
+    caption.hidden = !shown;
+    captionToggle.setAttribute("aria-expanded", String(shown));
+  };
+  captionToggle.addEventListener("click", () => { setCaptionShown(caption.hidden); });
+  /* Rotating with the modal open crosses the breakpoint: follow it so
+     a caption hidden in portrait is not stranded behind a toggle that
+     landscape no longer shows (final review 2026-08-26). */
+  phoneQuery()?.addEventListener?.("change", (ev) => { setCaptionShown(!ev.matches); });
+
+  /* pp-plate scopes the player's narrow-viewport flex reflow without
+     touching the lightbox's shared pm-plate rules. */
+  pm.plate.classList.add("pp-plate");
+  pm.plate.append(viewbox, timeline, captionToggle, caption, transport);
+
+  const state: TransportState = { t: 0, playing: false, lastIdx: -1 };
+  /* All tracks, their gaps, and the axis: the canvas's CSS height. */
+  const timelineHeight = config.tracks.reduce((h, tr) => h + tr.height + TRACK_GAP, 0) + AXIS_H;
+  let staticTracks: HTMLCanvasElement | null = null;
+
+  const dpr = (): number => doc.defaultView?.devicePixelRatio ?? 1;
+  const sampleIndexAt = (t: number): number => columnIndex(t, config.duration, config.samples.length);
+  const cssColor = (v: string): string =>
+    (doc.defaultView?.getComputedStyle(doc.documentElement).getPropertyValue(v).trim() ?? "") || INK;
+
+  /* The tracks, axis, chips, and labels never change while the modal
+     is open, so they paint once to an offscreen canvas at layout time;
+     drawFrame stamps it and draws the playhead over it. */
+  function paintStatic(width: number, scale: number): HTMLCanvasElement | null {
+    const off = doc.createElement("canvas");
+    off.width = Math.floor(width * scale);
+    off.height = Math.floor(timelineHeight * scale);
+    const ctx = off.getContext("2d");
+    if (!ctx) return null; // jsdom: geometry is tested; painting is not
+    ctx.scale(scale, scale);
+    /* The tracks follow the theme: paper is the field well, ink and rule
+       the theme's own, so the strip reads as part of the plate by day
+       and by night (owner call 2026-08-26). */
+    const p: Painter = {
+      ctx, width, xAt: (t) => playheadX(t, config.duration, width), cssColor,
+      paper: cssColor("--well"), ink: cssColor("--ink"), rule: cssColor("--rule"),
+    };
+    let top = 0;
+    for (const track of config.tracks) {
+      if (track.kind === "band") paintBand(p, track, top, config.samples.length);
+      else paintLines(p, track, top);
+      if (track.label) paintLabelChip(p, track.label, top);
+      top += track.height + TRACK_GAP;
+    }
+    paintAxis(p, top, config.duration);
+    return off;
+  }
+
+  function layoutTracks(): void {
+    const scale = dpr();
+    const w = timeline.clientWidth || 600;
+    tracksCanvas.style.height = `${timelineHeight}px`;
+    tracksCanvas.width = Math.floor(w * scale);
+    tracksCanvas.height = Math.floor(timelineHeight * scale);
+    staticTracks = paintStatic(w, scale);
+  }
+
+  function drawFrame(): void {
+    const ctx = tracksCanvas.getContext("2d");
+    if (!ctx || !staticTracks) return;
+    const scale = dpr();
+    ctx.clearRect(0, 0, tracksCanvas.width, tracksCanvas.height);
+    ctx.drawImage(staticTracks, 0, 0);
+    const px = playheadX(state.t, config.duration, tracksCanvas.width / scale);
+    ctx.save();
+    ctx.scale(scale, scale);
+    ctx.strokeStyle = cssColor("--ink");
+    ctx.lineWidth = 2;
+    ctx.beginPath();
+    ctx.moveTo(px, 0);
+    ctx.lineTo(px, timelineHeight - AXIS_H);
+    ctx.stroke();
+    ctx.restore();
+  }
+
+  function applyCurrent(useStart: boolean): void {
+    const idx = sampleIndexAt(state.t);
+    if (idx === state.lastIdx && !useStart) return;
+    state.lastIdx = idx;
+    const s = config.samples[idx];
+    if (useStart) config.sink.start(s); else config.sink.move(s);
+  }
+
+  /* Old shape of this function was tick(now): computed dt itself from
+     now/state.lastNow and re-armed its own requestAnimationFrame. The
+     frame loop now owns the clock and the scheduling; this is just the
+     per-frame body. dt is 0 on the first frame after any loop.start(),
+     which preserves the old skip-first-frame behavior without a
+     dedicated lastNow field. */
+  function frame(dt: number): void {
+    if (state.playing) {
+      state.t += dt;
+      if (state.t >= config.duration) {
+        state.t -= config.duration;
+        applyCurrent(true); // teleport at the wrap, no smear
+      } else {
+        applyCurrent(false);
+      }
+    }
+    drawFrame();
+    readout.textContent = formatReadout(state.t, config.duration);
+  }
+
+  /* Cast, not an optional fallback: this player is always built against
+     a live document (same idiom the reduced-motion check below uses for
+     doc.defaultView). Only the frame loop's own rAF/cAF calls need this;
+     jsdom's stub in tests supplies them on the same window object. */
+  const win = doc.defaultView as Window;
+  const loop = createFrameLoop(win, frame, { clamp: 0.1, firstDt: 0 });
+
+  /* Visibility pause (step 10): the loop halts while the tab is hidden
+     and resumes when it returns with the dialog still open. Playback
+     state is untouched; the frame loop's clock reset means the hidden
+     gap never arrives as one giant dt. Registered once at build and
+     never removed: the player has no destroy path and stays reopenable
+     for the life of the page. */
+  function onVisibility(): void {
+    if (doc.hidden) loop.stop();
+    else if (pm.dialog.hasAttribute("open")) loop.start();
+  }
+  doc.addEventListener("visibilitychange", onVisibility);
+
+  function setPlaying(playing: boolean): void {
+    state.playing = playing;
+    playBtn.innerHTML = playing ? ICON_PAUSE : ICON_PLAY;
+    playBtn.setAttribute("aria-pressed", `${playing}`);
+    if (playing) applyCurrent(true); else config.sink.stop();
+  }
+
+  playBtn.addEventListener("click", () => { setPlaying(!state.playing); });
+  restartBtn.addEventListener("click", () => {
+    state.t = 0;
+    applyCurrent(true);
+  });
+  pm.dialog.addEventListener("keydown", (ev) => {
+    /* Space on a button is its native activation; handling it here too
+       would toggle twice in one stroke. */
+    if (ev.key === " " && !(ev.target instanceof HTMLButtonElement)) {
+      ev.preventDefault();
+      setPlaying(!state.playing);
+    }
+  });
+  pm.dialog.addEventListener("close", () => {
+    setPlaying(false);
+    loop.stop();
+    config.sink.pause?.();
+  });
+
+  if (SCRUB) attachScrub(timeline, state, config.duration, applyCurrent, setPlaying);
+
+  return {
+    open: (opener) => {
+      loop.stop();
+      pm.open(opener);
+      setCaptionShown(!phone());
+      layoutTracks();
+      readout.textContent = formatReadout(state.t, config.duration);
+      config.sink.resume?.();
+      /* Reduced motion: open paused; the transport still plays on demand.
+         jsdom has no matchMedia, hence the widened type (same guard as
+         henry-loose.ts). Kept separate from the frame loop's `win`,
+         which is cast non-null: this one must stay optional so a
+         matchMedia-less jsdom does not throw. */
+      const mmWin = doc.defaultView as { matchMedia?: typeof window.matchMedia } | null;
+      const reduced = mmWin?.matchMedia
+        ? mmWin.matchMedia("(prefers-reduced-motion: reduce)").matches
+        : false;
+      if (stageReady && !reduced) setPlaying(true);
+      loop.start();
+    },
+    close: () => { pm.close(); },
+    isPlaying: () => state.playing,
+  };
+}

package/src/scripts/plate-modal.ts

@@ -0,0 +1,91 @@
+/* Shared plate-window chrome (spec
+   docs/superpowers/specs/2026-08-22-fluid-path-player-design.md):
+   dialog + veil, corner-stroked zone, ink plate, boxed labels, close.
+   Consumers: the image lightbox (legacyPrefix "lb" keeps its old class
+   names alive) and the path player. */
+
+import { ICON_X } from "./core/icons";
+
+export interface PlateModalRefs {
+  dialog: HTMLDialogElement;
+  zone: HTMLDivElement;
+  plate: HTMLDivElement;
+  closeBtn: HTMLButtonElement;
+  addLabel: (pos: "topLeft" | "bottomLeft" | "bottomRight", className?: string) => HTMLSpanElement;
+  open: (opener: HTMLElement | null) => void;
+  close: () => void;
+  isOpen: () => boolean;
+}
+
+const POS_CLASS = { topLeft: "pm-label-tl", bottomLeft: "pm-label-bl", bottomRight: "pm-label-br" } as const;
+
+export function buildPlateModal(
+  doc: Document,
+  opts: { ariaLabel: string; legacyPrefix?: string; closeLabel?: string },
+): PlateModalRefs {
+  const { closeLabel = "Close" } = opts;
+  const legacy = (name: string): string[] =>
+    opts.legacyPrefix ? [`pm-${name}`, `${opts.legacyPrefix}-${name}`] : [`pm-${name}`];
+
+  const dialog = doc.createElement("dialog");
+  dialog.classList.add(...legacy("dialog"));
+  dialog.setAttribute("aria-label", opts.ariaLabel);
+
+  const zone = doc.createElement("div");
+  zone.classList.add(...legacy("zone"));
+  for (const c of ["tl", "tr", "bl", "br"]) {
+    const corner = doc.createElement("div");
+    corner.classList.add(...legacy("corner"), ...legacy(`c-${c}`));
+    zone.append(corner);
+  }
+
+  const plate = doc.createElement("div");
+  plate.classList.add(...legacy("plate"), "bracket-frame");
+
+  const closeBtn = doc.createElement("button");
+  closeBtn.type = "button";
+  closeBtn.classList.add(...legacy("close"), "icon-box");
+  closeBtn.setAttribute("aria-label", closeLabel);
+  closeBtn.innerHTML = ICON_X;
+  plate.append(closeBtn);
+
+  zone.append(plate);
+  dialog.append(zone);
+  doc.body.append(dialog);
+
+  let opener: HTMLElement | null = null;
+  /* The page scroll lock (overflow: hidden via html.pm-open, see
+     plate-modal.css). Cleared on the dialog's close event so every
+     path out (close box, veil click, Escape, a consumer's close())
+     unlocks it. */
+  const root = doc.documentElement;
+  closeBtn.addEventListener("click", () => { dialog.close(); });
+  dialog.addEventListener("close", () => {
+    root.classList.remove("pm-open");
+    opener?.focus();
+  });
+  /* The dialog fills the viewport; a veil click targets the dialog
+     element itself (everything inside the zone targets a descendant).
+     Checked by identity, not zone.contains: a handler that swaps a
+     button's innerHTML detaches the click's target mid-bubble, and a
+     detached node is contained by nothing, which read as a veil click
+     and closed the dialog under the pause button (found 2026-08-23). */
+  dialog.addEventListener("click", (ev) => {
+    if (ev.target === dialog) dialog.close();
+  });
+
+  const addLabel = (pos: "topLeft" | "bottomLeft" | "bottomRight", className?: string): HTMLSpanElement => {
+    const span = doc.createElement("span");
+    span.classList.add("pm-label", POS_CLASS[pos], "boxed-label", "micro-label");
+    if (className) span.classList.add(...className.split(" "));
+    plate.append(span);
+    return span;
+  };
+
+  return {
+    dialog, zone, plate, closeBtn, addLabel,
+    open: (o) => { opener = o; dialog.showModal(); root.classList.add("pm-open"); },
+    close: () => { dialog.close(); },
+    isOpen: () => dialog.open,
+  };
+}

package/src/scripts/scroll-top.ts

@@ -0,0 +1,32 @@
+import { claim, release, type Island, type IslandHandle } from "./core/island";
+import { docOf } from "./core/dom";
+
+/* Scroll-to-top floater island (step 9), born from Base.astro's inline
+   script: shows once the header leaves the viewport. */
+
+export interface ScrollTopOptions {
+  buttonId?: string;
+  watchId?: string;
+}
+
+export const mountScrollTop: Island<ScrollTopOptions> = (root, options = {}): IslandHandle => {
+  const { buttonId = "scroll-to-top", watchId = "masthead" } = options;
+  const doc = docOf(root);
+  // Scroll-to-top floater: shows once the header leaves the viewport.
+  const toTop = doc.getElementById(buttonId);
+  const masthead = doc.getElementById(watchId);
+  let observer: IntersectionObserver | null = null;
+  if (toTop && masthead && claim(toTop, "scroll-top")) {
+    observer = new IntersectionObserver(([entry]) => {
+      toTop.classList.toggle("show", !entry.isIntersecting);
+    });
+    observer.observe(masthead);
+  }
+
+  return {
+    destroy(): void {
+      observer?.disconnect();
+      if (toTop && observer) release(toTop, "scroll-top");
+    },
+  };
+};