@brett_lamy/docstream 1.9.1 → 1.10.0

package/src/strudel/StrudelPlayer.tsx

@@ -0,0 +1,246 @@
+import { useEffect, useId, useRef, useState, useSyncExternalStore } from "react"
+import { Code2, Loader2, Pause, Play } from "lucide-react"
+import { HighlightedCode } from "../docs/HighlightedCode"
+import {
+  DEFAULT_SAMPLES,
+  getStrudelSnapshot,
+  playStrudel,
+  stopStrudel,
+  strudelNow,
+  subscribeStrudel,
+  type StrudelHap,
+  type StrudelPattern,
+} from "./engine"
+
+export interface StrudelPlayerProps {
+  /** Strudel pattern code (what you would type at strudel.cc). */
+  code?: string
+  /** URL of a `.strudel` file to load when `code` is absent. */
+  src?: string
+  title?: string
+  className?: string
+  /** Show the code under the player from the start. Defaults to false. */
+  showCode?: boolean
+  /** Sample banks to load before the first play. Defaults to the Tidal dirt-samples. */
+  samples?: readonly string[]
+}
+
+type Source = { kind: "loading" } | { kind: "error"; message: string } | { kind: "ready"; code: string }
+
+const NOTE = /^([a-g])([#bs]*)(-?\d+)?$/i
+const STEPS: Record<string, number> = { c: 0, d: 2, e: 4, f: 5, g: 7, a: 9, b: 11 }
+
+// A vertical position for an event: its pitch when it has one, else a stable lane per sample name.
+function pitch(value: unknown): number | null {
+  if (typeof value === "number") return value
+  if (!value || typeof value !== "object") return null
+  const v = value as Record<string, unknown>
+  if (typeof v.note === "number") return v.note
+  if (typeof v.note === "string") {
+    const m = NOTE.exec(v.note)
+    if (m) {
+      const accidental = [...m[2]!].reduce((n, c) => n + (c === "b" ? -1 : 1), 0)
+      return STEPS[m[1]!.toLowerCase()]! + accidental + (Number(m[3] ?? 3) + 1) * 12
+    }
+  }
+  if (typeof v.freq === "number") return 69 + 12 * Math.log2(v.freq / 440)
+  if (typeof v.n === "number" && typeof v.s !== "string") return v.n
+  if (typeof v.s === "string") {
+    let h = 0
+    for (const c of v.s) h = (h * 31 + c.charCodeAt(0)) | 0
+    return (Math.abs(h) % 24) + (typeof v.n === "number" ? v.n : 0)
+  }
+  return null
+}
+
+const num = (t: number | { valueOf(): number }) => Number(t.valueOf())
+
+// Scrolling piano roll: two cycles centered on the playhead, onsets only. Idle: quiet bars.
+function drawRoll(canvas: HTMLCanvasElement, pattern: StrudelPattern | null, now: number | null) {
+  const ctx = canvas.getContext("2d")
+  if (!ctx) return
+  const dpr = Math.min(window.devicePixelRatio || 1, 2)
+  const w = Math.max(1, Math.round(canvas.clientWidth * dpr))
+  const h = Math.max(1, Math.round(canvas.clientHeight * dpr))
+  if (canvas.width !== w || canvas.height !== h) {
+    canvas.width = w
+    canvas.height = h
+  }
+  ctx.clearRect(0, 0, w, h)
+  ctx.fillStyle = getComputedStyle(canvas).color
+  if (!pattern || now === null) {
+    ctx.globalAlpha = 0.18
+    const bars = 48
+    for (let i = 0; i < bars; i++) {
+      const bh = (0.2 + 0.6 * Math.abs(Math.sin(i * 1.7) * Math.cos(i * 0.6))) * h
+      ctx.fillRect((i / bars) * w + 1, (h - bh) / 2, w / bars - 3 * dpr, bh)
+    }
+    ctx.globalAlpha = 1
+    return
+  }
+  const begin = now - 1, end = now + 1
+  let haps: StrudelHap[]
+  try {
+    haps = pattern.queryArc(begin, end).filter((hap) => hap.whole && num(hap.whole.begin) === num(hap.part.begin))
+  } catch {
+    return
+  }
+  const pitches = haps.map((hap) => pitch(hap.value))
+  const known = pitches.filter((p): p is number => p !== null)
+  const lo = known.length ? Math.min(...known) : 0
+  const hi = known.length ? Math.max(...known) : 1
+  const range = Math.max(hi - lo, 11)
+  const pad = 4 * dpr
+  const lane = Math.max(3 * dpr, Math.min(10 * dpr, (h - 2 * pad) / (range + 1)))
+  const x = (t: number) => ((t - begin) / (end - begin)) * w
+  haps.forEach((hap, i) => {
+    const p = pitches[i] ?? lo
+    const s = num(hap.whole!.begin), e = num(hap.whole!.end)
+    const y = h - pad - lane - ((p - lo + (range - (hi - lo)) / 2) / range) * (h - 2 * pad - lane)
+    ctx.globalAlpha = s <= now && now < e ? 1 : s > now ? 0.45 : 0.25
+    ctx.fillRect(x(s), y, Math.max(2 * dpr, x(e) - x(s) - 1.5 * dpr), lane)
+  })
+  ctx.globalAlpha = 0.6
+  ctx.fillRect(w / 2 - dpr / 2, 0, dpr, h)
+  ctx.globalAlpha = 1
+}
+
+/** A live-coded music player: Strudel (strudel.cc) runs the pattern in this page, no iframe. */
+export function StrudelPlayer({ code, src, title, className, showCode = false, samples = DEFAULT_SAMPLES }: StrudelPlayerProps) {
+  const id = useId()
+  const [source, setSource] = useState<Source>(() => (code !== undefined ? { kind: "ready", code } : { kind: "loading" }))
+  const [codeOpen, setCodeOpen] = useState(showCode)
+  const [error, setError] = useState<string | null>(null)
+  const [cycle, setCycle] = useState(0)
+  const pattern = useRef<StrudelPattern | null>(null)
+  const canvasRef = useRef<HTMLCanvasElement>(null)
+  const snapshot = useSyncExternalStore(subscribeStrudel, getStrudelSnapshot, getStrudelSnapshot)
+  const status = snapshot.owner === id ? snapshot.status : "idle"
+
+  useEffect(() => {
+    if (code !== undefined) {
+      setSource({ kind: "ready", code })
+      return
+    }
+    if (!src) {
+      setSource({ kind: "error", message: "no pattern" })
+      return
+    }
+    let live = true
+    setSource({ kind: "loading" })
+    fetch(src)
+      .then((res) => {
+        if (!res.ok) throw new Error(`${res.status} ${res.statusText}`.trim())
+        return res.text()
+      })
+      .then((text) => live && setSource({ kind: "ready", code: text }))
+      .catch((err: unknown) => live && setSource({ kind: "error", message: err instanceof Error ? err.message : String(err) }))
+    return () => {
+      live = false
+    }
+  }, [code, src])
+
+  // Stop our pattern when the player unmounts or its code changes underneath it.
+  const ready = source.kind === "ready" ? source.code : null
+  useEffect(() => () => void stopStrudel(id), [id, ready])
+
+  useEffect(() => {
+    const canvas = canvasRef.current
+    if (!canvas) return
+    if (status !== "playing") {
+      drawRoll(canvas, null, null)
+      const resize = new ResizeObserver(() => drawRoll(canvas, null, null))
+      resize.observe(canvas)
+      return () => resize.disconnect()
+    }
+    let frame = 0
+    let shown = -1
+    const tick = () => {
+      const now = strudelNow()
+      drawRoll(canvas, pattern.current, now)
+      const whole = now === null ? 0 : Math.floor(now) + 1
+      if (whole !== shown) setCycle((shown = whole))
+      frame = requestAnimationFrame(tick)
+    }
+    tick()
+    return () => cancelAnimationFrame(frame)
+  }, [status])
+
+  const toggle = async () => {
+    if (source.kind !== "ready") return
+    if (status !== "idle") {
+      await stopStrudel(id)
+      return
+    }
+    setError(null)
+    try {
+      pattern.current = await playStrudel(id, source.code, samples)
+    } catch (err) {
+      if (err instanceof Error && err.message === "superseded") return
+      setError(err instanceof Error ? err.message : String(err))
+    }
+  }
+
+  const label = title ?? (src ? src.split(/[?#]/)[0]!.split("/").pop()! : "Strudel pattern")
+  const codeId = `${id}-code`
+  const sub =
+    source.kind === "error"
+      ? `Couldn't load: ${source.message}`
+      : source.kind === "loading"
+        ? "Loading…"
+        : status === "loading"
+          ? "Loading sounds…"
+          : status === "playing"
+            ? `Cycle ${cycle}`
+            : "Strudel"
+  return (
+    <figure className={`docstream-strudel ${className ?? ""}`.trim()} data-state={status}>
+      <div className="docstream-strudel__bar">
+        <button
+          type="button"
+          className="docstream-strudel__play"
+          onClick={toggle}
+          disabled={source.kind !== "ready"}
+          aria-label={status === "idle" ? `Play ${label}` : `Stop ${label}`}
+        >
+          {status === "loading" ? (
+            <Loader2 className="docstream-strudel__spin" size={18} />
+          ) : status === "playing" ? (
+            <Pause size={18} />
+          ) : (
+            <Play size={18} />
+          )}
+        </button>
+        <div className="docstream-strudel__meta">
+          <span className="docstream-strudel__title">{label}</span>
+          <span className="docstream-strudel__sub" aria-live="polite">
+            {sub}
+          </span>
+        </div>
+        <canvas ref={canvasRef} className="docstream-strudel__roll" aria-hidden="true" />
+        {source.kind === "ready" && (
+          <button
+            type="button"
+            className="docstream-strudel__toggle"
+            aria-expanded={codeOpen}
+            aria-controls={codeId}
+            aria-label={codeOpen ? "Hide code" : "Show code"}
+            onClick={() => setCodeOpen((open) => !open)}
+          >
+            <Code2 size={16} />
+          </button>
+        )}
+      </div>
+      {error && (
+        <div className="docstream-strudel__error" role="alert">
+          {error}
+        </div>
+      )}
+      {source.kind === "ready" && codeOpen && (
+        <div id={codeId} className="docstream-strudel__code">
+          <HighlightedCode code={source.code.trim()} language="javascript" />
+        </div>
+      )}
+    </figure>
+  )
+}

package/src/strudel/engine.ts

@@ -0,0 +1,98 @@
+// One Strudel runtime per page, loaded on the first play (@strudel/web is ~850 KB and touches
+// `window` at import). Players share it, so starting one stops whichever was playing.
+
+/** A scheduled event, as `Pattern.queryArc` returns it. */
+export interface StrudelHap {
+  whole?: { begin: number | { valueOf(): number }; end: number | { valueOf(): number } } | null
+  part: { begin: number | { valueOf(): number }; end: number | { valueOf(): number } }
+  value: unknown
+}
+
+export interface StrudelPattern {
+  queryArc(begin: number, end: number): StrudelHap[]
+}
+
+interface StrudelRepl {
+  evaluate(code: string, autostart?: boolean): Promise<StrudelPattern | undefined>
+  stop(): void
+  scheduler: { now(): number; started: boolean }
+  state: { evalError?: unknown }
+}
+
+interface StrudelWeb {
+  initStrudel(options?: { prebake?: () => unknown; onToggle?: (started: boolean) => void }): Promise<StrudelRepl>
+  samples(source: string): Promise<unknown>
+}
+
+/** Sample banks loaded before the first pattern, matching what strudel.cc code expects (`s("bd sd")`). */
+export const DEFAULT_SAMPLES = ["github:tidalcycles/dirt-samples"]
+
+export interface StrudelSnapshot {
+  /** The player id that owns the runtime right now, or null. */
+  owner: string | null
+  status: "idle" | "loading" | "playing"
+}
+
+let runtime: Promise<StrudelRepl> | null = null
+let loaded: StrudelRepl | null = null
+let snapshot: StrudelSnapshot = { owner: null, status: "idle" }
+const listeners = new Set<() => void>()
+
+function set(next: StrudelSnapshot) {
+  snapshot = next
+  listeners.forEach((fn) => fn())
+}
+
+export function subscribeStrudel(fn: () => void): () => void {
+  listeners.add(fn)
+  return () => listeners.delete(fn)
+}
+
+export function getStrudelSnapshot(): StrudelSnapshot {
+  return snapshot
+}
+
+function load(samples: readonly string[]): Promise<StrudelRepl> {
+  runtime ??= import("@strudel/web").then((mod: StrudelWeb) =>
+    mod.initStrudel({
+      prebake: () => Promise.all(samples.map((s) => mod.samples(s))),
+      onToggle: (started) => {
+        if (!started && snapshot.status === "playing") set({ owner: null, status: "idle" })
+      },
+    }),
+  ).then((repl) => (loaded = repl))
+  runtime.catch(() => {
+    runtime = null
+  })
+  return runtime
+}
+
+/** Evaluate `code` and start it, taking the runtime from any other player. Must run from a user gesture. */
+export async function playStrudel(owner: string, code: string, samples: readonly string[] = DEFAULT_SAMPLES): Promise<StrudelPattern> {
+  set({ owner, status: "loading" })
+  try {
+    const repl = await load(samples)
+    if (snapshot.owner !== owner) throw new Error("superseded")
+    const pattern = await repl.evaluate(code, true)
+    if (!pattern || repl.state.evalError) {
+      const err = repl.state.evalError
+      throw err instanceof Error ? err : new Error(String(err ?? "Strudel could not evaluate this pattern"))
+    }
+    if (snapshot.owner === owner) set({ owner, status: "playing" })
+    return pattern
+  } catch (err) {
+    if (snapshot.owner === owner) set({ owner: null, status: "idle" })
+    throw err
+  }
+}
+
+export async function stopStrudel(owner: string): Promise<void> {
+  if (snapshot.owner !== owner) return
+  set({ owner: null, status: "idle" })
+  ;(await runtime)?.stop()
+}
+
+/** The scheduler's position in cycles, for animation frames; null while stopped or not loaded. */
+export function strudelNow(): number | null {
+  return loaded?.scheduler.started ? loaded.scheduler.now() : null
+}

package/src/strudel/index.ts

@@ -0,0 +1,4 @@
+export { StrudelPlayer } from "./StrudelPlayer"
+export type { StrudelPlayerProps } from "./StrudelPlayer"
+export { DEFAULT_SAMPLES, playStrudel, stopStrudel } from "./engine"
+export { isStrudelFile, isStrudelLanguage } from "./url"

package/src/strudel/url.ts

@@ -0,0 +1,9 @@
+/** True for a URL whose path ends in `.strudel` (query string and hash ignored). */
+export function isStrudelFile(url: string): boolean {
+  return /\.strudel(?:[?#]|$)/i.test(url.trim())
+}
+
+/** Fence languages that render as a Strudel player. */
+export function isStrudelLanguage(language: string | null | undefined): boolean {
+  return !!language && /^strudel$/i.test(language)
+}

package/src/styles.css

@@ -450,6 +450,200 @@
   border-radius: 12px;
 }
 
+/* StlViewer: a WebGL preview of an .stl model ({% embed url="part.stl" %}). The model takes
+   its color from `color`, so it follows the theme's primary. */
+.docstream-stl,
+.docstream-strudel {
+  margin: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.docstream-stl__stage {
+  position: relative;
+  aspect-ratio: 16 / 9;
+  border: 1px solid var(--gb-border);
+  border-radius: 12px;
+  overflow: hidden;
+  color: var(--gb-primary, #6366f1);
+  background:
+    radial-gradient(circle at 50% 40%, color-mix(in srgb, var(--gb-muted, #f4f4f5) 40%, transparent), transparent 70%),
+    var(--gb-muted, #f4f4f5);
+}
+
+.docstream-stl__canvas {
+  display: block;
+  width: 100%;
+  height: 100%;
+  cursor: grab;
+  touch-action: none;
+}
+
+.docstream-stl__canvas:active {
+  cursor: grabbing;
+}
+
+.docstream-stl__canvas:focus-visible {
+  outline: 2px solid var(--gb-primary, #6366f1);
+  outline-offset: -2px;
+  border-radius: 12px;
+}
+
+.docstream-stl__status {
+  display: grid;
+  place-items: center;
+  height: 100%;
+  padding: 16px;
+  text-align: center;
+  font-size: 13px;
+  color: var(--gb-muted-foreground);
+}
+
+.docstream-stl__reset {
+  position: absolute;
+  top: 8px;
+  right: 8px;
+  padding: 3px 10px;
+  border: 1px solid var(--gb-border);
+  border-radius: 999px;
+  background: var(--gb-panel, #fff);
+  color: var(--gb-panel-foreground, inherit);
+  font: inherit;
+  font-size: 12px;
+  cursor: pointer;
+  opacity: 0.85;
+}
+
+.docstream-stl__reset:hover {
+  opacity: 1;
+  background: var(--gb-hover, var(--gb-accent));
+}
+
+.docstream-stl__caption {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: space-between;
+  gap: 4px 12px;
+  font-size: 12px;
+  color: var(--gb-muted-foreground);
+}
+
+.docstream-stl__caption a {
+  color: inherit;
+  font-weight: 500;
+}
+
+/* StrudelPlayer: a Strudel pattern as an audio player (```strudel fences, .strudel embeds). */
+.docstream-strudel__bar {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 10px 12px;
+  border: 1px solid var(--gb-border);
+  border-radius: 12px;
+  background: var(--gb-panel, #fff);
+  color: var(--gb-panel-foreground, inherit);
+}
+
+.docstream-strudel__play {
+  flex: none;
+  display: grid;
+  place-items: center;
+  width: 40px;
+  height: 40px;
+  border: 0;
+  border-radius: 999px;
+  background: var(--gb-primary, #6366f1);
+  color: var(--gb-primary-foreground, #fff);
+  cursor: pointer;
+}
+
+.docstream-strudel__play:disabled {
+  opacity: 0.5;
+  cursor: default;
+}
+
+.docstream-strudel__play:focus-visible,
+.docstream-strudel__toggle:focus-visible {
+  outline: 2px solid var(--gb-primary, #6366f1);
+  outline-offset: 2px;
+}
+
+.docstream-strudel__spin {
+  animation: docstream-strudel-spin 0.9s linear infinite;
+}
+
+@keyframes docstream-strudel-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+.docstream-strudel__meta {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  flex: 0 1 auto;
+  max-width: 40%;
+}
+
+.docstream-strudel__title {
+  font-weight: 600;
+  font-size: 14px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.docstream-strudel__sub {
+  font-size: 12px;
+  color: var(--gb-muted-foreground);
+  font-variant-numeric: tabular-nums;
+}
+
+.docstream-strudel__roll {
+  flex: 1 1 auto;
+  min-width: 60px;
+  height: 40px;
+  color: var(--gb-primary, #6366f1);
+}
+
+.docstream-strudel__toggle {
+  flex: none;
+  display: grid;
+  place-items: center;
+  width: 32px;
+  height: 32px;
+  border: 1px solid var(--gb-border);
+  border-radius: 8px;
+  background: transparent;
+  color: var(--gb-muted-foreground);
+  cursor: pointer;
+}
+
+.docstream-strudel__toggle[aria-expanded="true"],
+.docstream-strudel__toggle:hover {
+  background: var(--gb-hover, var(--gb-accent));
+  color: inherit;
+}
+
+.docstream-strudel__error {
+  font-size: 12px;
+  color: var(--gb-danger, #dc2626);
+  white-space: pre-wrap;
+}
+
+.docstream-strudel__code {
+  border: 1px solid var(--gb-border);
+  border-radius: 12px;
+  background: var(--gb-code-bg);
+  color: var(--gb-code-fg);
+  padding: 12px 14px;
+  overflow-x: auto;
+  font-size: 13px;
+}
+
 .docs-content-ref {
   display: flex !important;
   align-items: center;