@vibes.diy/prompts 14.3.36 → 14.3.38

package/llms/d3.draft.md

@@ -0,0 +1,154 @@
+# D3 — the first draft: a small live bar chart
+
+A D3 app's first draft is the whole page around the chart — the title, the
+card that frames it, a tiny form that adds a row, the seeded documents the
+chart reads — with one small, correct chart actually drawn by d3 inside the
+card: a bar chart of the seeded rows with a band scale, a linear scale and both
+axes, following the theme through its CSS variables. Add a row and the bar appears.
+Transitions, tooltips, brushing, maps and force layouts are the next pass. What
+the draft owes that pass is the right skeleton: d3 owns one `<svg>` through a
+ref, the width comes from the host through a `ResizeObserver`, and the draw
+effect is a select → data join → `join("rect")` that re-runs when `docs`
+change — so the next pass adds marks and interactions to that effect rather
+than rewriting the file.
+
+### `App.jsx`
+```jsx
+import React, { useEffect, useRef, useState } from "react";
+import { useFireproof } from "use-fireproof";
+import * as d3 from "d3";
+import { Button, Input, Badge, Card, CardHeader, CardTitle, CardContent } from "@vibes.diy/look";
+
+const HEIGHT = 260;
+const MARGIN = { top: 12, right: 12, bottom: 32, left: 40 };
+
+// One pass of the D3 pattern: select the svg, bind the rows, transform the marks.
+// Called on every data or width change; the join keeps it idempotent.
+function drawChart(svgEl, rows, width) {
+  const innerW = Math.max(0, width - MARGIN.left - MARGIN.right);
+  const innerH = HEIGHT - MARGIN.top - MARGIN.bottom;
+  const x = d3.scaleBand().domain(rows.map((d) => d.label)).range([0, innerW]).padding(0.2);
+  const y = d3.scaleLinear().domain([0, d3.max(rows, (d) => d.value) || 1]).nice().range([innerH, 0]);
+
+  const svg = d3.select(svgEl).attr("width", width).attr("height", HEIGHT).attr("viewBox", `0 0 ${width} ${HEIGHT}`);
+  const g = svg.selectAll("g.plot").data([null]).join("g").attr("class", "plot").attr("transform", `translate(${MARGIN.left},${MARGIN.top})`);
+
+  g.selectAll("rect.bar")
+    .data(rows, (d) => d._id)
+    .join("rect")
+    .attr("class", "bar")
+    .attr("x", (d) => x(d.label))
+    .attr("width", x.bandwidth())
+    .attr("y", (d) => y(d.value))
+    .attr("height", (d) => innerH - y(d.value))
+    .attr("rx", 3)
+    .style("fill", "var(--primary, currentColor)"); // the theme's primary, so a restyle recolors it
+
+  g.selectAll("g.x-axis").data([null]).join("g").attr("class", "x-axis").attr("transform", `translate(0,${innerH})`).call(d3.axisBottom(x));
+  g.selectAll("g.y-axis").data([null]).join("g").attr("class", "y-axis").call(d3.axisLeft(y).ticks(5));
+}
+
+export default function App() {
+  const { database, useLiveQuery } = useFireproof("bakeryShelf");
+  const { docs } = useLiveQuery("type", { key: "loaf" });
+  const hostRef = useRef(null);
+  const svgRef = useRef(null);
+  const [width, setWidth] = useState(0);
+  const [label, setLabel] = useState("");
+  const [value, setValue] = useState("");
+
+  // The width follows the card, not the window.
+  useEffect(() => {
+    const host = hostRef.current;
+    const observer = new window.ResizeObserver(([entry]) => setWidth(Math.floor(entry.contentRect.width)));
+    observer.observe(host);
+    return () => observer.disconnect();
+  }, []);
+
+  // Redraw whenever the rows or the width change.
+  useEffect(() => {
+    if (!svgRef.current || width === 0) return;
+    const rows = [...docs].sort((a, b) => a.createdAt - b.createdAt);
+    drawChart(svgRef.current, rows, width);
+  }, [docs, width]);
+
+  const addRow = () => {
+    const n = Number(value);
+    if (label.trim().length === 0 || !Number.isFinite(n) || n < 0) return;
+    database.put({ type: "loaf", label: label.trim(), value: n, createdAt: Date.now() });
+    setLabel("");
+    setValue("");
+  };
+
+  const total = docs.reduce((sum, d) => sum + d.value, 0);
+
+  return (
+    <main className="min-h-screen bg-background text-foreground font-sans p-6">
+      <h1 className="text-3xl font-bold">Morning Loaves</h1>
+      <p className="mt-1 text-muted-foreground">What left the shelf at Crumb &amp; Co. before ten. Add a bake and watch its bar rise.</p>
+
+      <Card className="mt-6 max-w-2xl">
+        <CardHeader>
+          <CardTitle>Sold by 10am</CardTitle>
+        </CardHeader>
+        <CardContent>
+          <div className="flex items-center gap-2">
+            <Badge variant="secondary">{docs.length} bakes</Badge>
+            <Badge variant="secondary">{total} loaves</Badge>
+          </div>
+          <div ref={hostRef} className="mt-4 w-full">
+            <svg ref={svgRef} className="block text-muted-foreground" role="img" aria-label="Loaves sold by bake" />
+          </div>
+          {/* TODO(next pass): bars grow in with a transition, a tooltip per bar, brushing a range, and other chart kinds (maps, force layouts) */}
+          <div className="mt-4 flex flex-wrap gap-2">
+            <Input className="flex-1" value={label} onChange={(e) => setLabel(e.target.value)} placeholder="Bake, e.g. Rye" />
+            <Input className="w-28" type="number" min={0} value={value} onChange={(e) => setValue(e.target.value)} placeholder="Loaves" />
+            <Button onClick={addRow}>Add bake</Button>
+          </div>
+        </CardContent>
+      </Card>
+    </main>
+  );
+}
+```
+
+### `seed.json`
+```json
+{
+  "bakeryShelf": [
+    { "key": "sourdough", "type": "loaf", "label": "Sourdough", "value": 42, "createdAt": 1758400000000 },
+    { "key": "baguette", "type": "loaf", "label": "Baguette", "value": 35, "createdAt": 1758400060000 },
+    { "key": "rye", "type": "loaf", "label": "Rye", "value": 18, "createdAt": 1758400120000 },
+    { "key": "brioche", "type": "loaf", "label": "Brioche", "value": 24, "createdAt": 1758400180000 },
+    { "key": "focaccia", "type": "loaf", "label": "Focaccia", "value": 29, "createdAt": 1758400240000 },
+    { "key": "seeded", "type": "loaf", "label": "Seeded", "value": 15, "createdAt": 1758400300000 }
+  ]
+}
+```
+
+Draft note: the next pass adds bars that grow in with transitions, a tooltip per bar, brushing a range, and richer chart kinds like maps and force layouts.
+
+## What stays the same in a D3 draft
+
+- **The import is the namespace**: `import * as d3 from "d3"`, and d3 owns
+  exactly one `<svg>` reached through a ref. React renders the svg element and
+  the page around it; d3 renders everything inside it.
+- **The D3 pattern, idempotent**: select the svg, bind with
+  `.data(rows, (d) => d._id)`, and `.join("rect")`; the group and each axis are
+  joined the same way (`.data([null]).join("g")`), so a redraw updates in place
+  and never appends a second chart.
+- **Scales and axes**: `scaleBand` for categories, `scaleLinear().nice()` from
+  zero for values, `axisBottom` and `axisLeft` called into their own groups
+  inside a margin.
+- **Width from the host**: a `ResizeObserver` on the wrapper sets `width` in
+  React state; the height is a constant; the observer disconnects in cleanup.
+- **Redraw on data**: the draw effect depends on `[docs, width]`, and the rows
+  come from `useLiveQuery`, so a row added by the form appears as a bar with no
+  extra wiring.
+- **Theme colors, never hex**: bars fill with `var(--primary, currentColor)`
+  as a style, and the axes draw in the svg's `text-muted-foreground` through
+  d3's own `currentColor` defaults, so a restyle recolors the chart with no
+  redraw.
+- **What waits for the next pass** is named in the `TODO(next pass)` comment
+  and the draft note: transitions, tooltips, brushing, maps, force layouts. The
+  draft draws none of it.

package/llms/d3.js

@@ -21,6 +21,7 @@ export const d3Config = {
         "maps",
         "geographic",
     ],
+    draftVariant: true,
     importModule: "d3",
     importName: "d3",
     importType: "namespace",

package/llms/d3.js.map

@@ -1 +1 @@
-{"version":3,"file":"d3.js","sourceRoot":"","sources":["../../jsr/llms/d3.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,QAAQ,GAAc;IACjC,IAAI,EAAE,IAAI;IACV,KAAK,EAAE,OAAO;IACd,WAAW,EACT,oRAAoR;IACtR,IAAI,EAAE;QACJ,OAAO;QACP,QAAQ;QACR,OAAO;QACP,QAAQ;QACR,MAAM;QACN,OAAO;QACP,IAAI;QACJ,eAAe;QACf,eAAe;QACf,SAAS;QACT,UAAU;QACV,SAAS;QACT,WAAW;QACX,SAAS;QAGT,KAAK;QACL,MAAM;QACN,YAAY;KACb;IACD,YAAY,EAAE,IAAI;IAClB,UAAU,EAAE,IAAI;IAChB,UAAU,EAAE,WAAW;CACxB,CAAC"}
+{"version":3,"file":"d3.js","sourceRoot":"","sources":["../../jsr/llms/d3.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,QAAQ,GAAc;IACjC,IAAI,EAAE,IAAI;IACV,KAAK,EAAE,OAAO;IACd,WAAW,EACT,oRAAoR;IACtR,IAAI,EAAE;QACJ,OAAO;QACP,QAAQ;QACR,OAAO;QACP,QAAQ;QACR,MAAM;QACN,OAAO;QACP,IAAI;QACJ,eAAe;QACf,eAAe;QACf,SAAS;QACT,UAAU;QACV,SAAS;QACT,WAAW;QACX,SAAS;QAGT,KAAK;QACL,MAAM;QACN,YAAY;KACb;IAGD,YAAY,EAAE,IAAI;IAClB,YAAY,EAAE,IAAI;IAClB,UAAU,EAAE,IAAI;IAChB,UAAU,EAAE,WAAW;CACxB,CAAC"}

package/llms/image-gen.md

@@ -161,6 +161,7 @@ function Gallery() {
 - Same prompt produces a deterministic `_id` (hash-based), so results are cached across reloads.
 - Each image has a regenerate button that appends a new version (writes a new `_files.v<N>` entry).
 - Prev / next controls navigate between stored versions.
+- In the Vibes iPhone app, on iPhones with Apple Intelligence, pictures come from Apple's Image Playground, free. A picture started by a tap — ↻, or a button that shows the `<ImgGen>` — opens Image Playground with its prompt (and the `images` input picture, for an edit), and the image the person confirms is saved as a version like any other. A picture that starts on its own shows a **Create with Image Playground** button that does the same. Your code stays the same, and everywhere else pictures are made as usual. Passing `model` keeps that picture on the platform's cloud generation.
 - Set `showControls={false}` to hide regenerate and version navigation.
 
 ## Private drafts and public images

package/llms/p5.draft.md

@@ -0,0 +1,179 @@
+# p5.js — the first draft: a small seeded sketch that moves
+
+A p5 app's first draft is the whole page around the piece — the title, the
+card that frames it, the button that re-seeds it, the seeded document it reads
+— with one small generative sketch actually running inside the card: a handful
+of dots wandering on Perlin noise, each leaving a soft trail, seeded from the
+document so the same seed always draws the same drift. The real piece (the
+flow field, the kaleidoscope, the thousand-particle study), saving still
+renders, palettes and drawing with a finger are the next pass. What the draft
+owes that pass is the right skeleton: the pinned import, instance mode with a
+sketch factory that receives its host element, the canvas sized from the host,
+`pixelDensity` set, the seed read through a ref, and `instance.remove()` on
+cleanup — so the next pass grows `makeSketch` rather than rewriting the file.
+
+### `App.jsx`
+```jsx
+import React, { useEffect, useRef } from "react";
+import { useFireproof } from "use-fireproof";
+import p5 from "https://esm.sh/p5@1.11.13";
+import { Button, Badge, Card, CardHeader, CardTitle, CardContent } from "@vibes.diy/look";
+
+const WANDERERS = 7;
+
+// Canvas pixels cannot follow a CSS variable, so resolve a theme token to a
+// concrete color once per mount. The fallback covers an app with no theme.
+function cssColor(host, token, fallback) {
+  const probe = document.createElement("span");
+  probe.style.display = "none";
+  probe.style.color = `var(${token}, ${fallback})`;
+  host.appendChild(probe);
+  const resolved = window.getComputedStyle(probe).color;
+  probe.remove();
+  return resolved || fallback;
+}
+
+// The sketch is a pure function of its host and the seed it reads. The host is
+// passed in; the current seed arrives through seedRef, so a new seed restarts
+// the drift without rebuilding the instance.
+function makeSketch({ host, seedRef }) {
+  return (p) => {
+    let w = 0;
+    let h = 0;
+    let seed = null;
+    let t = 0;
+    let dots = [];
+    let bg = null;
+    let fade = null;
+    let ink = null;
+
+    const start = () => {
+      seed = seedRef.current;
+      p.randomSeed(seed);
+      p.noiseSeed(seed);
+      t = 0;
+      dots = Array.from({ length: WANDERERS }, (_, i) => ({ x: p.random(w), y: p.random(h), r: 6 + i * 2, off: p.random(1000) }));
+      p.background(bg);
+    };
+
+    p.setup = () => {
+      w = Math.max(120, host.clientWidth || 320);
+      h = Math.max(120, host.clientHeight || 320);
+      const c = p.createCanvas(w, h);
+      c.elt.style.display = "block";
+      p.pixelDensity(Math.min(window.devicePixelRatio || 1, 2));
+      bg = p.color(cssColor(host, "--card", "#fdfaf4"));
+      fade = p.color(cssColor(host, "--card", "#fdfaf4"));
+      fade.setAlpha(24);
+      ink = p.color(cssColor(host, "--primary", "#3b5bdb"));
+      ink.setAlpha(170);
+      p.noStroke();
+      start();
+    };
+
+    p.draw = () => {
+      if (seedRef.current !== seed) start(); // the button wrote a new seed
+      t += 0.004;
+      p.fill(fade); // trails: dim what is there instead of erasing it
+      p.rect(0, 0, w, h);
+      p.fill(ink);
+      for (const d of dots) {
+        d.x = p.noise(d.off, t) * w;
+        d.y = p.noise(d.off + 50, t) * h;
+        p.circle(d.x, d.y, d.r);
+      }
+    };
+
+    p.windowResized = () => {
+      w = Math.max(120, host.clientWidth);
+      h = Math.max(120, host.clientHeight);
+      p.resizeCanvas(w, h);
+      p.background(bg);
+    };
+  };
+}
+
+export default function App() {
+  const { database, useLiveQuery } = useFireproof("driftStudio");
+  const { docs: pieces } = useLiveQuery("type", { key: "piece" });
+  const piece = pieces[0];
+  const hostRef = useRef(null);
+  const seedRef = useRef(piece?.seed ?? 1234);
+
+  // The sketch reads the seed from the ref on its next frame.
+  useEffect(() => {
+    if (piece) seedRef.current = piece.seed;
+  }, [piece?.seed]);
+
+  // The instance, built once into the host element, removed on unmount.
+  useEffect(() => {
+    const node = hostRef.current;
+    if (!node) return undefined;
+    const instance = new p5(makeSketch({ host: node, seedRef }), node);
+    return () => instance.remove();
+  }, []);
+
+  const reseed = () => {
+    if (!piece) return;
+    database.put({ ...piece, seed: Math.floor(Math.random() * 100000), reseededAt: Date.now() });
+  };
+
+  return (
+    <main className="min-h-screen bg-background text-foreground font-sans p-6">
+      <h1 className="text-3xl font-bold">{piece?.title ?? "Drift"}</h1>
+      <p className="mt-1 text-muted-foreground">Seven dots wander on Perlin noise. Every seed is its own dance, and the same seed always plays it again.</p>
+
+      <Card className="mt-6 max-w-xl">
+        <CardHeader>
+          <CardTitle>{piece?.subtitle ?? "Study no. 1"}</CardTitle>
+        </CardHeader>
+        <CardContent>
+          <div ref={hostRef} className="aspect-square w-full overflow-hidden rounded-lg border border-border touch-none" />
+          <div className="mt-4 flex items-center gap-3">
+            <Button onClick={reseed}>New seed</Button>
+            <Badge variant="secondary">seed {piece?.seed ?? "…"}</Badge>
+          </div>
+        </CardContent>
+      </Card>
+
+      {/* TODO(next pass): grow makeSketch into the real piece, save still renders of a seed, palette picker, drawing with a finger */}
+    </main>
+  );
+}
+```
+
+### `seed.json`
+```json
+{
+  "driftStudio": [
+    { "key": "drift", "type": "piece", "title": "Drift", "subtitle": "Study no. 1 — seven wanderers", "seed": 4417 }
+  ]
+}
+```
+
+Draft note: the next pass adds the real generative piece, saving still renders of a favourite seed, a palette picker, and drawing into the sketch with a finger.
+
+## What stays the same in a p5 draft
+
+- **The import is pinned**: `import p5 from "https://esm.sh/p5@1.11.13"`,
+  exactly — never a bare `"p5"`, which resolves to the 2.x line.
+- **Instance mode, built once**: `new p5(makeSketch({ host, ... }), host)`
+  inside `useEffect(() => {...}, [])`, and the cleanup returns
+  `instance.remove()` so a remount never leaves a second draw loop running.
+  Every hook is assigned on `p` (`p.setup`, `p.draw`, `p.windowResized`).
+- **The host is passed in and sizes the canvas**: `createCanvas` reads
+  `host.clientWidth`/`clientHeight`, the host is an `aspect-square` (or
+  `aspect-video`) box inside a Card, and `p.pixelDensity(Math.min(devicePixelRatio, 2))`
+  is set in setup.
+- **The seed lives in a document and reaches the sketch through a ref**:
+  the button writes a new `seed` with `database.put`, an effect copies it into
+  `seedRef`, and `draw` notices the change and restarts with
+  `randomSeed`/`noiseSeed`, so the instance is never rebuilt for a new seed and
+  a seed always redraws the same piece.
+- **The colors come from the theme**: `cssColor` resolves `--card` and
+  `--primary` into canvas colors; the page itself uses semantic classes.
+- **The hello is small and visibly generative**: a few noise-driven dots with
+  a soft trail, never a blank canvas and never a placeholder picture.
+- **What waits for the next pass** is named in the `TODO(next pass)` comment
+  and the draft note: the real piece, still renders, palettes, touch drawing.
+  The draft draws none of it.

package/llms/p5.js

@@ -21,6 +21,7 @@ export const p5Config = {
         "kaleidoscope",
         "screensaver",
     ],
+    draftVariant: true,
     importModule: "https://esm.sh/p5@1.11.13",
     importName: "p5",
     importType: "default",

package/llms/p5.js.map

@@ -1 +1 @@
-{"version":3,"file":"p5.js","sourceRoot":"","sources":["../../jsr/llms/p5.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,QAAQ,GAAc;IACjC,IAAI,EAAE,IAAI;IACV,KAAK,EAAE,OAAO;IACd,WAAW,EACT,uFAAuF;QACvF,wFAAwF;QACxF,sFAAsF;QACtF,wFAAwF;QACxF,0FAA0F;QAC1F,uFAAuF;QACvF,yFAAyF;IAC3F,IAAI,EAAE;QACJ,IAAI;QACJ,OAAO;QACP,YAAY;QACZ,QAAQ;QACR,gBAAgB;QAChB,iBAAiB;QACjB,YAAY;QACZ,cAAc;QACd,gBAAgB;QAChB,cAAc;QACd,aAAa;KACd;IAID,YAAY,EAAE,2BAA2B;IACzC,UAAU,EAAE,IAAI;IAChB,UAAU,EAAE,SAAS;CACtB,CAAC"}
+{"version":3,"file":"p5.js","sourceRoot":"","sources":["../../jsr/llms/p5.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,QAAQ,GAAc;IACjC,IAAI,EAAE,IAAI;IACV,KAAK,EAAE,OAAO;IACd,WAAW,EACT,uFAAuF;QACvF,wFAAwF;QACxF,sFAAsF;QACtF,wFAAwF;QACxF,0FAA0F;QAC1F,uFAAuF;QACvF,yFAAyF;IAC3F,IAAI,EAAE;QACJ,IAAI;QACJ,OAAO;QACP,YAAY;QACZ,QAAQ;QACR,gBAAgB;QAChB,iBAAiB;QACjB,YAAY;QACZ,cAAc;QACd,gBAAgB;QAChB,cAAc;QACd,aAAa;KACd;IAMD,YAAY,EAAE,IAAI;IAClB,YAAY,EAAE,2BAA2B;IACzC,UAAU,EAAE,IAAI;IAChB,UAAU,EAAE,SAAS;CACtB,CAAC"}

package/llms/spotify.draft.md

@@ -0,0 +1,179 @@
+# Spotify catalog — the first draft: search that works on sample tracks
+
+A Spotify catalog page's first draft is the finished page, painted from seeded
+`track` documents shaped like the rows the real search route returns: a search
+box and button that filter those tracks right in the browser by track name,
+artist or album, result cards with the fields a real row carries, and the setup
+card that walks the owner through registering a Spotify app. A Badge on the
+header reads "sample data until the key is set", so searching works from the
+first paint and the page says plainly where the live catalog comes from.
+
+The next pass writes `backend.js`: it mints a client-credentials token from
+`SPOTIFY_CLIENT_ID` and `SPOTIFY_CLIENT_SECRET`, holds it in memory, and
+searches the catalog through the app's own `/_api/search` route. What the draft
+owes that pass is the row shape: each `track` document carries the fields
+`trackRow` returns (`id`, `name`, `artists` as one joined string, `album`,
+`image`, `url`) plus `durationMs`, so the next pass swaps the filter for the
+route and keeps every card. The draft writes no `backend.js`, makes no network
+call, reads no secret, and never asks a visitor for a token: the credentials
+are the owner's, set once in the vibe's settings.
+
+### `App.jsx`
+```jsx
+import React, { useState } from "react";
+import { useFireproof } from "use-fireproof";
+import { Button, Card, CardHeader, CardTitle, CardContent, Badge, Input } from "@vibes.diy/look";
+
+// The owner's one-time trip to the Spotify developer dashboard, carried in the app.
+const SETUP_STEPS = [
+  "Open the Spotify developer dashboard and log in with a Spotify account.",
+  "Create an app with any name and description; put this page's URL in if the form asks for a redirect URI.",
+  "Open the app's settings and copy the Client ID.",
+  "Reveal and copy the Client secret.",
+  "Set both on this vibe as SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET in the vibe's settings page.",
+];
+const SECRET_NAMES = ["SPOTIFY_CLIENT_ID", "SPOTIFY_CLIENT_SECRET"];
+
+function formatDuration(ms) {
+  const total = Math.round(ms / 1000);
+  return `${Math.floor(total / 60)}:${String(total % 60).padStart(2, "0")}`;
+}
+
+function matches(track, terms) {
+  const haystack = `${track.name} ${track.artists} ${track.album ?? ""}`.toLowerCase();
+  return terms.every((t) => haystack.includes(t));
+}
+
+function TrackCard({ track }) {
+  return (
+    <Card>
+      <CardContent>
+        <div className="flex items-center gap-4">
+          {track.image ? (
+            <img src={track.image} alt="" className="h-16 w-16 rounded-md object-cover" />
+          ) : (
+            <div className="flex h-16 w-16 items-center justify-center rounded-md bg-muted text-2xl font-bold text-muted-foreground">
+              {track.name.charAt(0)}
+            </div>
+          )}
+          <div className="min-w-0 flex-1">
+            <p className="truncate font-semibold">
+              {track.url ? <a href={track.url} target="_blank" rel="noreferrer" className="underline">{track.name}</a> : track.name}
+            </p>
+            <p className="truncate text-muted-foreground">{track.artists}</p>
+            <p className="truncate text-muted-foreground">{track.album}</p>
+          </div>
+          <span className="tabular-nums text-muted-foreground">{formatDuration(track.durationMs)}</span>
+        </div>
+      </CardContent>
+    </Card>
+  );
+}
+
+export default function App() {
+  const { useLiveQuery } = useFireproof("spotifyCatalog");
+  const { docs: tracks } = useLiveQuery("type", { key: "track" });
+  const [query, setQuery] = useState("");
+  const [applied, setApplied] = useState("");
+
+  const terms = applied.toLowerCase().split(/\s+/).filter(Boolean);
+  const results = terms.length === 0 ? tracks : tracks.filter((t) => matches(t, terms));
+  const search = () => setApplied(query.trim());
+
+  return (
+    <main className="min-h-screen bg-background text-foreground font-sans p-6">
+      <div className="flex flex-wrap items-center gap-3">
+        <h1 className="text-3xl font-bold">Crate Digger</h1>
+        <Badge variant="secondary">sample data until the key is set</Badge>
+      </div>
+      <p className="mt-1 text-muted-foreground">Search Spotify's catalog by song, artist or album.</p>
+
+      <form
+        className="mt-6 flex gap-2"
+        onSubmit={(e) => {
+          e.preventDefault();
+          search();
+        }}
+      >
+        <Input value={query} onChange={(e) => setQuery(e.target.value)} placeholder="Try “harbor” or “Juniper Static”" />
+        <Button type="submit">Search</Button>
+      </form>
+      {/* TODO(next pass): the server handler mints the client-credentials token from SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET and searches the catalog through /_api/search; these cards render its rows */}
+
+      <p className="mt-4 text-muted-foreground">
+        {applied ? `${results.length} tracks for “${applied}”` : `${results.length} tracks to explore`}
+      </p>
+      <div className="mt-3 grid gap-3">
+        {results.map((track) => (
+          <TrackCard key={track.id} track={track} />
+        ))}
+      </div>
+      {applied && results.length === 0 && (
+        <p className="mt-3 text-muted-foreground">Try a different word from a song, artist or album.</p>
+      )}
+
+      <Card className="mt-8">
+        <CardHeader>
+          <CardTitle>Search the whole Spotify catalog</CardTitle>
+        </CardHeader>
+        <CardContent>
+          <p className="text-muted-foreground">Register a Spotify app once, and this search reaches every track on Spotify.</p>
+          <ol className="mt-3 grid list-decimal gap-2 pl-5">
+            {SETUP_STEPS.map((step) => (
+              <li key={step}>{step}</li>
+            ))}
+          </ol>
+          <p className="mt-3">
+            Both secrets, {SECRET_NAMES.map((name, i) => (
+              <span key={name}>
+                {i > 0 && " and "}
+                <code className="rounded bg-muted px-1">{name}</code>
+              </span>
+            ))}, stay on the server.
+          </p>
+        </CardContent>
+      </Card>
+    </main>
+  );
+}
+```
+
+### `seed.json`
+```json
+{
+  "spotifyCatalog": [
+    { "key": "t1", "type": "track", "id": "4kXq0sample1Harbor", "name": "Harbor Lights at Low Tide", "artists": "Juniper Static", "album": "Saltwater Radio", "image": null, "url": null, "durationMs": 214000 },
+    { "key": "t2", "type": "track", "id": "7bRt2sample2Tangerine", "name": "Tangerine Freeway", "artists": "The Velvet Hours, Mara Quill", "album": "Summer in Reverse", "image": null, "url": null, "durationMs": 187500 },
+    { "key": "t3", "type": "track", "id": "2mPz9sample3Lantern", "name": "Lantern Song", "artists": "Juniper Static", "album": "Saltwater Radio", "image": null, "url": null, "durationMs": 243800 },
+    { "key": "t4", "type": "track", "id": "9cWe4sample4Paper", "name": "Paper Planets", "artists": "Odessa Bloom", "album": "Small Weather", "image": null, "url": null, "durationMs": 198200 },
+    { "key": "t5", "type": "track", "id": "1hVn6sample5Midnight", "name": "Midnight Laundromat", "artists": "Kit Arden", "album": "Quarters", "image": null, "url": null, "durationMs": 226400 }
+  ]
+}
+```
+
+Draft note: the next pass adds backend.js, which mints the client-credentials token from `SPOTIFY_CLIENT_ID` and `SPOTIFY_CLIENT_SECRET` and searches the public catalog, so the same cards show live tracks with album art and Spotify links.
+
+## What stays the same in a Spotify draft
+
+- **The whole page paints on the first draft**: header, search, result cards
+  and the setup card. Searching already works, filtering the seeded tracks in
+  the browser by track name, artist and album.
+- **Seeded rows mirror the backend's rows**: each `track` document carries
+  `trackRow`'s fields (`id`, `name`, `artists` joined into one string, `album`,
+  `image`, `url`) plus `durationMs`, so the next pass swaps the source and keeps
+  every card. A card handles a missing `image` or `url` gracefully.
+- **The capability is labeled, never hidden**: a Badge on the header reads
+  "sample data until the key is set", and the setup card names the Spotify
+  developer dashboard, `SPOTIFY_CLIENT_ID` and `SPOTIFY_CLIENT_SECRET` in so
+  many words.
+- **The credentials are the owner's**: the setup steps are for the owner, once.
+  No input asks a visitor for a token, and no visitor is sent to a developer
+  console.
+- **The page reads the public catalog**: search, artists, albums and tracks. A
+  listener's own top tracks, playlists and saved songs belong to their own
+  Spotify account, which is a connection and not this flow, so the draft draws
+  no section for them.
+- **What waits for the next pass** is named in the `TODO(next pass)` comment and
+  the draft note: `backend.js`, the client-credentials token held in memory, the
+  `/_api/search` route and its refusal reasons. The draft writes no
+  `backend.js`, makes no network call and reads no secret.

package/llms/spotify.js

@@ -2,6 +2,7 @@ export const spotifyConfig = {
     name: "spotify",
     label: "Spotify catalog",
     description: "Reading Spotify's public catalog with the owner's own Spotify app credentials: the setup steps the app shows when SPOTIFY_CLIENT_ID/SPOTIFY_CLIENT_SECRET are missing, the client-credentials token minted in backend.js and cached in memory rather than stored, searching artists/albums/tracks, the boundary that a listener's own top tracks and playlists need a connection instead, and keeping every refusal's reason",
+    draftVariant: true,
     cues: [
         "spotify",
         "spotify search",

package/llms/spotify.js.map

@@ -1 +1 @@
-{"version":3,"file":"spotify.js","sourceRoot":"","sources":["../../jsr/llms/spotify.ts"],"names":[],"mappings":"AAKA,MAAM,CAAC,MAAM,aAAa,GAAc;IACtC,IAAI,EAAE,SAAS;IACf,KAAK,EAAE,iBAAiB;IACxB,WAAW,EACT,8ZAA8Z;IACha,IAAI,EAAE;QACJ,SAAS;QACT,gBAAgB;QAChB,WAAW;QACX,cAAc;QACd,eAAe;QACf,eAAe;QACf,gBAAgB;KACjB;CACF,CAAC"}
+{"version":3,"file":"spotify.js","sourceRoot":"","sources":["../../jsr/llms/spotify.ts"],"names":[],"mappings":"AAKA,MAAM,CAAC,MAAM,aAAa,GAAc;IACtC,IAAI,EAAE,SAAS;IACf,KAAK,EAAE,iBAAiB;IACxB,WAAW,EACT,8ZAA8Z;IAGha,YAAY,EAAE,IAAI;IAClB,IAAI,EAAE;QACJ,SAAS;QACT,gBAAgB;QAChB,WAAW;QACX,cAAc;QACd,eAAe;QACf,eAAe;QACf,gBAAgB;KACjB;CACF,CAAC"}