@vibes.diy/prompts 14.3.83 → 14.3.84

package/llms/richtext.md

@@ -0,0 +1,612 @@
+# Rich text — notebooks, journals, wikis and documents with Tiptap
+
+When someone asks for a notebook, a journal, a wiki, a notes app, a document
+editor, a place to write with headings, lists, checklists, links and images,
+a shared page a team edits, meeting notes, a recipe book with real pages, or
+any app whose heart is writing more than a sentence, this is the recipe.
+Tiptap (MIT, on ProseMirror) is the editor: the app mounts it on a plain
+element through a small helper module, keeps each document as Tiptap's JSON
+in Fireproof, saves after typing pauses, loads a document without echoing it
+back as a save, and styles the written text with Tailwind on the host.
+
+The sibling boundary: a short field (a title, a comment, a caption) is
+pouf's `Textarea` in a `Field`; a feed of posts is `pouf-feed`; a pipeline
+of stories with stages is `pouf-editorial`. Rich text is the right call when
+the person is writing a page.
+
+The worked examples below were built and measured for this doc (Chromium,
+2026-10-07, Tiptap `3.31.4` from esm.sh): a notebook with a list of notes
+and one editor, and a shared page a team edits together.
+
+## Project shape
+
+```
+App.jsx          the notebook: a list of documents, one editor, a toolbar, save state
+lib/editor.js    createEditor(host, …): the pinned imports, change events, load, flush, commands, destroy
+access.js        who may write which documents
+```
+
+## One ProseMirror, pinned
+
+**Import every Tiptap package by its full esm.sh URL, and every Tiptap
+package is pinned to the same version**, in `lib/editor.js` at the top of
+the file. ProseMirror is unforgiving about copies: two versions of
+`@tiptap/pm` in one editor throw on the first keyed plugin, and nothing in
+the runtime keeps a family of packages on one version (each bare import
+resolves to its own latest). Measured: with `@tiptap/core`, `starter-kit`,
+`extension-placeholder`, `extension-task-list`, `extension-task-item`,
+`extension-link` and `extension-image` all at `3.31.4`, the editor's state
+and view are instances of the one `@tiptap/pm` the pinned URLs share, and
+the whole set arrives in about 2 s cold. The core entry is the one to use:
+`new Editor({ element })` mounts into a ref with no React of its own, so
+the app's one React stays the only one. (`@tiptap/react` exists; the core
+entry does the same job here with one fewer thing to keep in step.)
+
+### `lib/editor.js`
+```js app=notebook
+// lib/editor.js — a Tiptap editor behind a small surface: create it on a host element, hear about
+// changes as JSON plus plain text (debounced for saving), load a document without echoing it back
+// as a change, run toolbar commands, and destroy it on unmount. One ProseMirror: every package is
+// pinned to the same version so esm.sh serves one copy of @tiptap/pm.
+import { Editor } from "https://esm.sh/@tiptap/core@3.31.4";
+import StarterKit from "https://esm.sh/@tiptap/starter-kit@3.31.4";
+import Placeholder from "https://esm.sh/@tiptap/extension-placeholder@3.31.4";
+import TaskList from "https://esm.sh/@tiptap/extension-task-list@3.31.4";
+import TaskItem from "https://esm.sh/@tiptap/extension-task-item@3.31.4";
+import Link from "https://esm.sh/@tiptap/extension-link@3.31.4";
+import Image from "https://esm.sh/@tiptap/extension-image@3.31.4";
+
+export const EMPTY_DOC = { type: "doc", content: [{ type: "paragraph" }] };
+
+/** The first heading's text, else the first words of the body: what a document list shows. */
+export function titleOf(json, fallback = "Untitled") {
+  const blocks = json?.content ?? [];
+  const heading = blocks.find((b) => b.type === "heading");
+  const text = (node) => (node.content ?? []).map((n) => n.text ?? text(n)).join("");
+  const fromHeading = heading ? text(heading).trim() : "";
+  if (fromHeading) return fromHeading.slice(0, 80);
+  const first = blocks.map(text).find((t) => t.trim());
+  return first ? first.trim().slice(0, 80) : fallback;
+}
+
+/**
+ * createEditor(host, { content, placeholder, editable, onChange, debounceMs })
+ * `onChange(json, text)` fires after typing pauses for `debounceMs`; `load(json)` replaces the
+ * document without firing it, so a document arriving from the database lands as a load, with no save.
+ */
+export function createEditor(host, { content = EMPTY_DOC, placeholder = "Start writing…", editable = true, onChange, debounceMs = 600 } = {}) {
+  let timer = 0;
+  let loading = false;
+  const editor = new Editor({
+    element: host,
+    editable,
+    content,
+    extensions: [
+      StarterKit,
+      Placeholder.configure({ placeholder }),
+      TaskList,
+      TaskItem.configure({ nested: true }),
+      Link.configure({ openOnClick: false, autolink: true }),
+      Image.configure({ inline: false }),
+    ],
+    onUpdate: ({ transaction }) => {
+      if (loading || !transaction.docChanged || !onChange) return;
+      clearTimeout(timer);
+      timer = setTimeout(() => {
+        timer = 0; // the pause has landed; flush has nothing left to send
+        onChange(editor.getJSON(), editor.getText());
+      }, debounceMs);
+    },
+  });
+  const surface = {
+    editor,
+    /** Replace the document (from the database); no change event follows. Declined while dirty unless forced. */
+    load(json, { force = false } = {}) {
+      if (JSON.stringify(json) === JSON.stringify(editor.getJSON())) return true;
+      if (timer && !force) return false; // words are waiting to save: the person's keystrokes win
+      clearTimeout(timer);
+      timer = 0;
+      loading = true;
+      editor.commands.setContent(json ?? EMPTY_DOC, { emitUpdate: false });
+      loading = false;
+      return true;
+    },
+    /** True while a pause's words are still waiting to be saved. */
+    isDirty() {
+      return timer !== 0;
+    },
+    /** Save now, ahead of the debounce (on blur, on switching documents, on unmount). */
+    flush() {
+      if (!timer) return;
+      clearTimeout(timer);
+      timer = 0;
+      onChange?.(editor.getJSON(), editor.getText());
+    },
+    setEditable(on) {
+      editor.setEditable(on);
+    },
+    focus() {
+      editor.commands.focus();
+    },
+    /** Toolbar commands by name, so buttons stay dumb. */
+    run(command, value) {
+      const c = editor.chain().focus();
+      ({
+        bold: () => c.toggleBold(),
+        italic: () => c.toggleItalic(),
+        heading: () => c.toggleHeading({ level: value ?? 2 }),
+        bullets: () => c.toggleBulletList(),
+        numbers: () => c.toggleOrderedList(),
+        tasks: () => c.toggleTaskList(),
+        quote: () => c.toggleBlockquote(),
+        code: () => c.toggleCodeBlock(),
+        link: () => (value ? c.setLink({ href: value }) : c.unsetLink()),
+        image: () => c.setImage({ src: value }),
+        undo: () => c.undo(),
+        redo: () => c.redo(),
+      })[command]?.().run();
+    },
+    isActive(name, attrs) {
+      return editor.isActive(name, attrs);
+    },
+    destroy() {
+      clearTimeout(timer);
+      editor.destroy();
+    },
+  };
+  return surface;
+}
+```
+
+## The notebook
+
+### `App.jsx`
+```jsx app=notebook
+import React, { useEffect, useMemo, useRef, useState } from "react";
+import { useFireproof } from "use-fireproof";
+import { useVibe, useViewer } from "use-vibes";
+import { Badge, Button, Card, Heading, IconButton, Row, Skeleton, Spacer, Stack, Text } from "@vibes.diy/pouf";
+import { EMPTY_DOC, createEditor, titleOf } from "./lib/editor.js";
+
+// The written page is styled from the host: Tailwind reaches into the editor with arbitrary
+// variants, so the app ships no stylesheet and the JSX stays class-only.
+const PAGE =
+  "min-h-64 [&_.tiptap]:outline-none [&_h1]:text-2xl [&_h1]:font-bold [&_h1]:mt-4 [&_h2]:text-xl [&_h2]:font-semibold [&_h2]:mt-3 " +
+  "[&_p]:my-2 [&_ul]:list-disc [&_ul]:pl-6 [&_ol]:list-decimal [&_ol]:pl-6 [&_blockquote]:border-l-4 [&_blockquote]:pl-3 [&_blockquote]:text-muted-foreground " +
+  "[&_a]:underline [&_a]:text-primary [&_pre]:bg-muted [&_pre]:p-3 [&_pre]:rounded [&_img]:max-w-full [&_img]:rounded " +
+  "[&_ul[data-type=taskList]]:list-none [&_ul[data-type=taskList]]:pl-0 [&_li[data-type=taskItem]]:flex [&_li[data-type=taskItem]]:gap-2 " +
+  "[&_.is-editor-empty:first-child::before]:content-[attr(data-placeholder)] [&_.is-editor-empty:first-child::before]:text-muted-foreground [&_.is-editor-empty:first-child::before]:float-left [&_.is-editor-empty:first-child::before]:pointer-events-none";
+
+const TOOLS = [
+  ["bold", "B", "Bold"],
+  ["italic", "I", "Italic"],
+  ["heading", "H", "Heading"],
+  ["bullets", "•", "Bullet list"],
+  ["tasks", "☑", "Checklist"],
+  ["quote", "❝", "Quote"],
+];
+
+export default function App() {
+  const { database, useLiveQuery } = useFireproof("notebook");
+  const { me, can, ready } = useVibe("notebook");
+  const { requestLogin } = useViewer();
+  const { docs } = useLiveQuery("type", { key: "note" });
+  const notes = useMemo(() => [...docs].sort((a, b) => (b.updatedAt ?? 0) - (a.updatedAt ?? 0)), [docs]);
+
+  const [openId, setOpenId] = useState(null);
+  const [saved, setSaved] = useState("idle"); // idle | typing | saved
+  const [, bump] = useState(0); // re-render after a command so active states follow the cursor
+  const hostRef = useRef(null);
+  const surfaceRef = useRef(null);
+  const openRef = useRef(null); // the open note as last saved, read by the save callback
+  const open = notes.find((n) => n._id === openId) ?? null;
+
+  // One editor for the page's life: created once, destroyed in the effect's cleanup. The save
+  // callback reads the open note through a ref, so one editor serves every note without a rebuild.
+  useEffect(() => {
+    const surface = createEditor(hostRef.current, {
+      placeholder: "Write your note…",
+      onChange: async (json, text) => {
+        const current = openRef.current;
+        if (!current) return;
+        // Each save carries its own id, so the copy the live query hands back is recognised as ours
+        // whatever the clocks say.
+        const next = { ...current, title: titleOf(json), body: json, text, updatedAt: Date.now(), writeId: crypto.randomUUID() };
+        openRef.current = next;
+        await database.put(next);
+        setSaved("saved");
+      },
+    });
+    surface.editor.on("transaction", () => bump((n) => n + 1));
+    surface.editor.on("update", () => setSaved("typing"));
+    surfaceRef.current = surface;
+    return () => {
+      surface.flush();
+      surface.destroy();
+      surfaceRef.current = null;
+    };
+  }, []);
+
+  // A note arrives from the list (opened, or changed elsewhere): load it without a save echo. The
+  // app's own save comes back with the writeId it sent and is left alone; another device's save
+  // loads when nothing here is waiting to save, and otherwise waits for the next delivery (the
+  // words typed here land first; theirs arrive on the round trip after).
+  useEffect(() => {
+    const surface = surfaceRef.current;
+    if (!surface) return;
+    if (!open) {
+      openRef.current = null;
+      surface.load(EMPTY_DOC, { force: true });
+      surface.setEditable(false);
+      return;
+    }
+    const switched = !openRef.current || openRef.current._id !== open._id;
+    const theirs = !switched && open.writeId !== openRef.current.writeId;
+    if (switched) {
+      openRef.current = open;
+      surface.load(open.body ?? EMPTY_DOC, { force: true });
+    } else if (theirs && surface.load(open.body ?? EMPTY_DOC)) {
+      openRef.current = open;
+    }
+    surface.setEditable(Boolean(ready && can.edit(open).ok));
+  }, [open, ready]);
+
+  async function newNote() {
+    const draft = { type: "note", title: "Untitled", body: EMPTY_DOC, text: "", authorHandle: me?.userHandle };
+    if (!can.create(draft).ok) return;
+    surfaceRef.current?.flush();
+    const doc = { ...draft, _id: crypto.randomUUID(), updatedAt: Date.now(), writeId: crypto.randomUUID() };
+    await database.put(doc);
+    setOpenId(doc._id);
+    surfaceRef.current?.focus();
+  }
+
+  function pick(id) {
+    surfaceRef.current?.flush();
+    setOpenId(id);
+  }
+
+  const surface = surfaceRef.current;
+  const editable = Boolean(open && ready && can.edit(open).ok);
+
+  return (
+    <main className="min-h-screen bg-background text-foreground p-4 md:p-8">
+      <div className="grid gap-4 md:grid-cols-4">
+        <div className="md:col-span-1">
+        <Card variant="tight">
+          <Stack gap={2}>
+            <Row gap={2} align="center">
+              <Heading level={1}>Notebook</Heading>
+              <Spacer />
+              {ready && me && <Button size="sm" onClick={newNote}>New</Button>}
+            </Row>
+            {!ready && <div aria-busy="true"><Skeleton variant="row" count={3} /></div>}
+            {ready && !me && <Row gap={2} align="center" wrap><Text muted>Sign in and your notes stay with you.</Text><Button size="sm" variant="quiet" onClick={requestLogin}>Sign in</Button></Row>}
+            {notes.map((n) => (
+              <Button key={n._id} size="sm" variant={n._id === openId ? "solid" : "quiet"} onClick={() => pick(n._id)}>
+                {n.title || "Untitled"}
+              </Button>
+            ))}
+          </Stack>
+        </Card>
+        </div>
+
+        <div className="md:col-span-3">
+        <Card variant="tight">
+          <Stack gap={3}>
+            <Row gap={1} align="center" wrap>
+              {TOOLS.map(([command, glyph, label]) => (
+                <IconButton key={command} label={label} tone={surface?.isActive(command === "heading" ? "heading" : command === "bullets" ? "bulletList" : command === "tasks" ? "taskList" : command === "quote" ? "blockquote" : command) ? "blue" : undefined} disabled={!editable} onClick={() => surface?.run(command)}>
+                  {glyph}
+                </IconButton>
+              ))}
+              <Spacer />
+              {open && <Badge tone={saved === "saved" ? "up" : "idle"}>{saved === "typing" ? "Typing…" : saved === "saved" ? "Saved" : editable ? "Ready" : "Read only"}</Badge>}
+              {open && can.delete(open).ok && <Button size="sm" variant="quiet" tone="down" onClick={() => database.del(open._id).then(() => setOpenId(null))}>Delete</Button>}
+            </Row>
+            {!open && ready && <Text muted>Pick a note, or start a new one.</Text>}
+            <div ref={hostRef} className={PAGE} onBlur={() => surfaceRef.current?.flush()} />
+          </Stack>
+        </Card>
+        </div>
+      </div>
+    </main>
+  );
+}
+```
+
+### `access.js`
+```js app=notebook
+// note: a page in someone's notebook. Its author reads, edits and removes it.
+export function notebook(doc, oldDoc, user, ctx) {
+  if (!user) throw { forbidden: "sign in to keep notes" };
+  if (doc.type === "note" || (doc._deleted && oldDoc && oldDoc.type === "note")) {
+    const author = oldDoc ? oldDoc.authorHandle : doc.authorHandle;
+    if (author !== user.userHandle) throw { forbidden: "notes are kept as yourself" };
+    if (oldDoc && !doc._deleted && doc.authorHandle !== oldDoc.authorHandle) throw { forbidden: "a note keeps its author" };
+    return { channels: [`notes:${user.userHandle}`], grant: { users: { [user.userHandle]: [`notes:${user.userHandle}`] } } };
+  }
+  throw { forbidden: "unknown document type" };
+}
+```
+
+## A saved note is its JSON plus the plain text
+
+**A saved note is its JSON plus the plain text: `body` holds
+`editor.getJSON()` (what the editor loads back, marks and attributes
+intact), `text` holds `editor.getText()` (what search, previews and an AI
+summary read), and `title` holds the first heading or the first words.**
+HTML is a rendering, so it is not what gets kept: JSON survives a change of
+extensions, diffs cleanly, and is what `setContent` takes back without a
+parse. The list shows `title`; a search box filters on `text`; `callAI`
+gets `text`. The whole document is one Fireproof document, which is right
+for a page a person edits alone; a page several people edit at once wants
+the shared-page shape below.
+
+## Saving waits for typing to pause
+
+**Saving waits for typing to pause: the editor's `onUpdate` resets a timer
+and the save runs once the keys have been quiet for 600 ms, with `flush()`
+saving at once on blur, on switching documents and on unmount.** A
+`database.put` on every keystroke floods the server with writes to one
+`_id`, which collide on the document's sequence and get rejected; one save
+per pause keeps writes rare and sequential (measured: three insertions in a
+burst produced one change event, and `flush` produced the next one at
+once). The timer clears itself when it fires, so a blur after a save sends
+nothing twice. The save callback reads the open note through a ref rather
+than a closure, so the editor is created once and switching notes costs
+nothing.
+
+## Loading a document lands without a save
+
+**A document arriving from the database is loaded with `setContent` and
+`emitUpdate: false`** (Tiptap 3 emits by default; Tiptap 2 did not), and
+the helper also compares the incoming JSON with the editor's own, so a live
+query delivering the note the app just saved is a no-op (measured: loading
+a document produced zero change events, loading the same one again produced
+none, typing after it produced one). The app decides what counts as new: a
+different `_id` is a switch and loads at once; the same `_id` with a
+different `writeId` is another device's save, and it loads only when
+nothing here is waiting to save (`load` returns `false` while a pause's
+words are pending, and the effect tries again on the next delivery). A
+save is recognised by the `writeId` it carried out and back, which holds
+whatever the two devices' clocks say. Words typed here land first; theirs
+arrive on the round trip after, which is the honest order for one person on
+two devices.
+
+## Destroy the editor in the effect's cleanup
+
+**Create the editor once in `useEffect(() => {…}, [])` and destroy the
+editor in the effect's cleanup**, flushing first so the last pause's words
+land. An editor that outlives its host keeps ProseMirror listeners on a
+detached node and keeps the debounce timer alive; a remount without a
+destroy is two editors on one element. The one editor serves every note:
+the open note travels through a ref, and only the content is swapped.
+
+## Styling the page
+
+The editor renders real elements (`h1`, `p`, `ul`, `li[data-type=taskItem]`)
+inside a `.tiptap` root with no styles of its own, and a multi-file app
+ships no stylesheet, so **the host element's `className` styles the page
+through Tailwind's arbitrary variants**: `[&_h1]:text-2xl`,
+`[&_ul]:list-disc`, `[&_a]:underline`, and the placeholder through
+`[&_.is-editor-empty:first-child::before]:content-[attr(data-placeholder)]`.
+The JSX stays class-only and the theme tokens (`text-primary`,
+`text-muted-foreground`, `bg-muted`) carry the owner's restyle into the
+written page. Measured: the pouf lint passes a host carrying these classes.
+
+## Commands and the toolbar
+
+`surface.run("bold")`, `run("heading", 2)`, `run("tasks")`,
+`run("link", href)`, `run("image", src)`, `run("undo")`: the toolbar is
+buttons calling `run`, and `surface.isActive("bold")` colours the one that
+applies at the cursor. Tiptap's own shortcuts work out of the box (`Mod+B`,
+`Mod+I`, `Mod+Shift+8` for a bullet list, `#` then space for a heading,
+`[ ]` then space for a task, `Mod+Z`). A global shortcut of the app's own
+checks `event.target.isContentEditable` first, so typing stays typing. An
+image is `run("image", url)` with a URL from the note's `_files` after a
+save (`doc._files.photo.url`, the stable platform-minted address), so a
+picture is bytes on the document rather than a base64 string in the JSON.
+
+## A shared page
+
+### `lib/editor.js`
+```js app=page
+// The same helper module as the notebook, kept once per app; shown here in the part the shared
+// page uses. Every Tiptap package is pinned to one version.
+import { Editor } from "https://esm.sh/@tiptap/core@3.31.4";
+import StarterKit from "https://esm.sh/@tiptap/starter-kit@3.31.4";
+import Placeholder from "https://esm.sh/@tiptap/extension-placeholder@3.31.4";
+
+export const EMPTY_DOC = { type: "doc", content: [{ type: "paragraph" }] };
+
+export function createEditor(host, { content = EMPTY_DOC, placeholder = "Start writing…", editable = true, onChange, debounceMs = 600 } = {}) {
+  let timer = 0;
+  let loading = false;
+  const editor = new Editor({
+    element: host,
+    editable,
+    content,
+    extensions: [StarterKit, Placeholder.configure({ placeholder })],
+    onUpdate: ({ transaction }) => {
+      if (loading || !transaction.docChanged || !onChange) return;
+      clearTimeout(timer);
+      timer = setTimeout(() => {
+        timer = 0; // the pause has landed; flush has nothing left to send
+        onChange(editor.getJSON(), editor.getText());
+      }, debounceMs);
+    },
+  });
+  return {
+    editor,
+    load(json, { force = false } = {}) {
+      if (JSON.stringify(json) === JSON.stringify(editor.getJSON())) return true;
+      if (timer && !force) return false; // words are waiting to save: the person's keystrokes win
+      clearTimeout(timer);
+      timer = 0;
+      loading = true;
+      editor.commands.setContent(json ?? EMPTY_DOC, { emitUpdate: false });
+      loading = false;
+      return true;
+    },
+    /** True while a pause's words are still waiting to be saved. */
+    isDirty() {
+      return timer !== 0;
+    },
+    flush() {
+      if (!timer) return;
+      clearTimeout(timer);
+      timer = 0;
+      onChange?.(editor.getJSON(), editor.getText());
+    },
+    setEditable(on) {
+      editor.setEditable(on);
+    },
+    destroy() {
+      clearTimeout(timer);
+      editor.destroy();
+    },
+  };
+}
+```
+
+### `App.jsx`
+```jsx app=page
+import React, { useEffect, useRef, useState } from "react";
+import { useFireproof } from "use-fireproof";
+import { useVibe, useViewer } from "use-vibes";
+import { Badge, Button, Card, Heading, Row, Spacer, Stack, Text } from "@vibes.diy/pouf";
+import { EMPTY_DOC, createEditor } from "./lib/editor.js";
+
+const PAGE_ID = "page:home";
+const PAGE =
+  "min-h-64 [&_.tiptap]:outline-none [&_h1]:text-2xl [&_h1]:font-bold [&_h2]:text-xl [&_h2]:font-semibold [&_p]:my-2 [&_ul]:list-disc [&_ul]:pl-6 [&_ol]:list-decimal [&_ol]:pl-6 " +
+  "[&_.is-editor-empty:first-child::before]:content-[attr(data-placeholder)] [&_.is-editor-empty:first-child::before]:text-muted-foreground [&_.is-editor-empty:first-child::before]:float-left";
+
+export default function App() {
+  const { database, useDocument } = useFireproof("teampage");
+  const { me, can, ready } = useVibe("teampage");
+  const { requestLogin, ViewerTag } = useViewer();
+  const { doc: page } = useDocument({ _id: PAGE_ID, type: "page", body: EMPTY_DOC, text: "" });
+  const [saved, setSaved] = useState("idle");
+  const hostRef = useRef(null);
+  const surfaceRef = useRef(null);
+  const pageRef = useRef(page); // the latest page and identity, read by the save callback
+  const meRef = useRef(me);
+  const lastWriteRef = useRef(null);
+  pageRef.current = page;
+  meRef.current = me;
+
+  useEffect(() => {
+    const surface = createEditor(hostRef.current, {
+      placeholder: "The team's page. Anyone signed in can write here.",
+      onChange: async (json, text) => {
+        const writeId = crypto.randomUUID();
+        lastWriteRef.current = writeId;
+        await database.put({ ...pageRef.current, _id: PAGE_ID, type: "page", body: json, text, updatedAt: Date.now(), writeId, editedBy: meRef.current?.userHandle });
+        setSaved("saved");
+      },
+    });
+    surface.editor.on("update", () => setSaved("typing"));
+    surfaceRef.current = surface;
+    return () => {
+      surface.flush();
+      surface.destroy();
+      surfaceRef.current = null;
+    };
+  }, []);
+
+  // Someone else's save lands here when nothing of ours is waiting; our own save (the writeId we
+  // sent) is left alone.
+  useEffect(() => {
+    const surface = surfaceRef.current;
+    if (!surface || !page) return;
+    if (page.writeId && page.writeId !== lastWriteRef.current) surface.load(page.body ?? EMPTY_DOC);
+    surface.setEditable(Boolean(ready && me && can.edit(page).ok));
+  }, [page, ready, me]);
+
+  return (
+    <main className="min-h-screen bg-background text-foreground p-4 md:p-8">
+      <Stack gap={4}>
+        <Row gap={2} align="center" wrap>
+          <Heading level={1}>Team page</Heading>
+          <Spacer />
+          {page?.editedBy && <Row gap={1} align="center"><Text size="sm" muted>last edited by</Text><ViewerTag userHandle={page.editedBy} /></Row>}
+          <Badge tone={saved === "saved" ? "up" : "idle"}>{saved === "typing" ? "Typing…" : saved === "saved" ? "Saved" : ready && me ? "Ready" : "Read only"}</Badge>
+        </Row>
+        {ready && !me && <Row gap={2} align="center" wrap><Text muted>Sign in to write on the page.</Text><Button size="sm" variant="quiet" onClick={requestLogin}>Sign in</Button></Row>}
+        <Card variant="tight">
+          <div ref={hostRef} className={PAGE} onBlur={() => surfaceRef.current?.flush()} />
+        </Card>
+      </Stack>
+    </main>
+  );
+}
+```
+
+### `access.js`
+```js app=page
+// page: the one shared page. Everyone reads it; anyone signed in writes it and is named as the editor.
+export function teampage(doc, oldDoc, user, ctx) {
+  if (doc.type === "page" || (oldDoc && oldDoc.type === "page")) {
+    if (!user) throw { forbidden: "sign in to write on the page" };
+    if (doc.editedBy !== user.userHandle) throw { forbidden: "a page edit is signed as yourself" };
+    return { channels: ["page"], grant: { public: ["page"] } };
+  }
+  throw { forbidden: "unknown document type" };
+}
+```
+
+A shared page is last-writer-wins at the pause: two people typing in the
+same minute each save their whole document, and the later save replaces
+the earlier one, with the other person's editor loading it on the next
+tick. That is honest for a team page edited in turns; say so in the app's
+copy ("saves as you pause; one writer at a time lands"), and for true
+simultaneous editing keep one document per section so two people on
+different sections land independently.
+
+## Mobile
+
+The editor is a plain `contenteditable`, so the phone keyboard works as it
+does anywhere; keep the toolbar as `IconButton`s in a row that wraps under
+the page, and the page itself full width. Tiptap's input rules (`#` for a
+heading, `-` for a list, `[ ]` for a task) matter more on a phone than the
+toolbar does. Flush on blur, because a phone backgrounds the tab without
+warning.
+
+## Shapes a rich text vibe takes
+
+- **A notebook** — a list of notes and one editor, each note its own
+  document, saved as you pause. The starter.
+- **A journal** — one note per day, `_id: "day:YYYY-MM-DD"`, a calendar
+  strip picking the day, yesterday's page one tap away.
+- **A shared page or wiki** — one document per page, everyone reads,
+  signed-in people write, last editor named. The second example; several
+  pages are several `_id`s with a page list.
+- **Meeting notes with action items** — a checklist in the page, and a
+  query over `text` for lines that start with a box, listed in a sidebar.
+- **A recipe book** — a page per recipe with a heading, an ingredients
+  checklist and numbered steps, the list filtered by `text`.
+- **A writing app with an AI pass** — `callAI` over `text` for a summary or
+  a continuation, inserted with `editor.commands.insertContent` at the end.
+
+## Gotchas
+
+- **The editor throws on the first key, about a keyed plugin** — two
+  copies of ProseMirror, from Tiptap packages at different versions. One
+  version across every import.
+- **Every keystroke writes to the database** — the save sits in
+  `onUpdate`. The debounce and `flush`.
+- **Opening a note saves it again, forever** — `setContent` emitted an
+  update (Tiptap 3's default) and the save loaded it back. `emitUpdate:
+  false` in `load`.
+- **The list shows "Untitled" for every note** — the title is waiting to be
+  derived. `titleOf(json)` on every save.
+- **Typing is lost when switching notes** — the debounce had not fired.
+  `flush()` before changing the open note.
+- **Two editors after a hot reload** — the effect's cleanup did not destroy
+  the editor.
+- **The page has no styles** — Tiptap ships none, and a multi-file app
+  ships no stylesheet. The host's arbitrary-variant classes.
+- **A pasted image makes the document huge** — a base64 image in the JSON.
+  Bytes go in `_files`; the JSON holds the URL.

package/llms/strudel.md

@@ -31,8 +31,14 @@ the platform rewrites bare specifiers only in the top-of-file import region,
 so a lazy import carries the complete versioned URL. Laziness is the point —
 first paint owes nothing to a 165 KB engine plus a drum kit, and the
 AudioContext wants a user gesture anyway, which the play button is.
-`initStrudel` installs its own first-click unlock, so the loader running
-inside the click handler is the whole iOS story.
+**The loader makes the `AudioContext` itself, synchronously, before its
+first `await`**, resumes it, and hands it to the engine with
+`setAudioContext` ahead of `initStrudel`. The engine's own first-click
+unlock is registered only once the download finishes, by which time the
+press that started it has passed; a context made and resumed inside that
+press is what iOS asks of sound (measured 2026-10-07: the handed-in context
+is the one the engine plays through, `running`, events firing after a
+1.7 s load).
 
 Strudel is AGPL-licensed. The app links to the engine at its own address the
 way a browser links to any page, so the two programs stay separate:
@@ -78,12 +84,17 @@ const DRUM_KIT_URL = "https://cdn.jsdelivr.net/gh/tidalcycles/Dirt-Samples@maste
 const DRUM_MACHINES_URL = "https://cdn.jsdelivr.net/gh/felixroos/dough-samples@main/tidal-drum-machines.json";
 
 let enginePromise;
+let audioContext;
 const listeners = new Set();
 
 /** One fetch of the engine and the drum kit, however many times play is pressed. */
 export function loadStrudel() {
   enginePromise ??= (async () => {
+    // Runs inside the press that called play(): the context is made and resumed in the gesture.
+    audioContext = new AudioContext();
+    audioContext.resume();
     const web = await import(ENGINE_URL);
+    web.setAudioContext(audioContext);
     const repl = await web.initStrudel({
       prebake: () => Promise.all([web.samples(DRUM_KIT_URL), web.samples(DRUM_MACHINES_URL)]),
       onEvalError: (error) => {
@@ -107,6 +118,8 @@ export function onPatternError(fn) {
  * the `false` keeps the engine's own sound output in place beside the callback.
  */
 export async function play(code, onEvent) {
+  // Still inside the press: a context the browser suspended while the tab was away resumes here.
+  if (audioContext?.state === "suspended") audioContext.resume();
   const { web, repl } = await loadStrudel();
   const pattern = await web.evaluate(code, false);
   if (!pattern) return null;
@@ -219,10 +232,11 @@ export default function App() {
 
   async function handlePlay(source = code) {
     setProblem(null);
-    if (state === "idle") setState("loading");
+    const wasPlaying = state === "playing"; // read once: `state` is this render's value
+    if (!wasPlaying) setState("loading");
     const pattern = await play(source);
     if (pattern) setState("playing");
-    else if (state === "loading") setState("idle");
+    else if (!wasPlaying) setState("idle");
   }
 
   async function handleStop() {
@@ -636,8 +650,8 @@ the kits: `samples({ kick: "https://…/kick.wav", snare: "…" })` inside
 
 Play is a large button near the top; nothing sounds until it is pressed. A
 grid's steps are `IconButton`s whose label names the row, the step and its
-state, and a tempo slider sits beside play rather than in a settings drawer. The engine's own
-first-click unlock covers iOS as long as the loader runs inside the tap.
+state, and a tempo slider sits beside play rather than in a settings drawer. The loader makes
+and resumes the audio context inside the tap, which is what iOS asks of sound.
 
 ## Shapes a Strudel vibe takes