@vibes.diy/prompts 14.3.120 → 14.3.122

package/llms/fireproof.md

@@ -259,110 +259,91 @@ Address an existing record by its `_id`. `useDocument(task)` above holds the sel
 
 ## Required starting records
 
-When a request names records the app must already have — the three projects in a
-studio, a template's starter rows, the rooms in a planner — those records are
-created by the app's own first render through the ordinary write path. That is
-the mechanism, and it is the same one described below for starter content.
-`seed.json` is a separate thing: an optional import a person runs by hand from
-the Data tab. Its sample records also populate the temporary, view-only preview
-while saving is being prepared; they become real saved records only through an
-explicit import. In that file, give each item a stable `key`; its derived identity
-is `seed:<key>`. References to another item use that derived identity. An `_id`
-that repeats the item's own derived identity is equivalent to leaving it out.
-Explicit singleton identities such as `config:board` remain available.
-
-Four rules make it hold:
+A person's own action — a tap, a submit, a pick — is what starts a write; nothing in the app writes on load or on mount. Starting state comes in three kinds, and none of them is written by the app's own code:
+
+- **A person's own starting state needs no record.** Their records live on the channel named by their handle (see `access.md`), so the app opens on their tree with nothing to create first, and the view renders its defaults — a name, a setting, an empty list's invitation — from constants until the person's own action saves one.
+- **App-wide named containers or participants the request requires** — the pottery studio and its named apprentice, the three projects in a studio, the rooms in a planner — are written by the agent building the app, with `put_doc` as the owner, once the build whose rules admit them is saved, then read back. That save is the owner's own action. The app's opening view shows them when they are there and an inviting add flow until they are.
+- **Example content stays the optional `seed.json` import** — believable entries the screenshot renders and the owner adds with one ask. A name present only in `seed.json` describes an offered import, not an existing record or grant. In that file, give each item a stable `key`; its derived identity is `seed:<key>`. References to another item use that derived identity. An `_id` that repeats the item's own derived identity is equivalent to leaving it out. Explicit singleton identities such as `config:board` remain available. The file also populates the temporary, view-only preview while saving is being prepared.
+
+Four rules make the required records hold:
 
 - **Each required record gets a fixed `_id` you choose** (`"project:atlas"`), so
-  a second write of it lands on the same document instead of minting another.
-- **Create them after `ready` and after `can.create` says yes**, so a write that
-  the enforced access rules do not admit yet is skipped quietly and retried on a
-  later run.
-- **Restrict their creation to the owner in `access.js`** when the records
-  describe the app itself rather than a visitor's own work.
-- **Write parents and membership grants before the records that depend on
-  them**, so a dependent document never lands against a container or a grant
-  that does not exist yet.
-
-Fixed ids are also what makes two tabs safe. Two browsers opening the app for the
-first time at the same moment both see an empty query and both write; with fixed
-ids those are two writes of the same document, and last-writer-wins converges on
-one copy. Reading the query first and then deciding whether to write is the shape
-that races — the read is empty in both tabs before either write lands.
+  a second save of it lands on the same document instead of minting another.
+- **Gate their creation on a role in `access.js`** — `ctx.requireRole("owner")`,
+  or a role the owner hands out with a role record — when the records describe the
+  app itself rather than a visitor's own work.
+- **List parents and membership or role grants before the records that depend on
+  them**, so a dependent document never lands against a container or a grant that
+  does not exist yet.
+- **Leave the app's render paths write-free.** A write in an effect that fires when
+  a query reads empty runs on every fresh load, on every device and for every
+  visitor, because the live query renders empty before data arrives.
+
+Fixed ids are also what makes a repeated save safe: two devices saving the same
+record write the same document, and last-writer-wins converges on one copy.
 
 ### Match sample records to the owner's opening query
 
-The initial build's `<app-owner>` context supplies the app owner's handle.
-Use it to evaluate the opening query's group ID when writing `seed.json`.
-For an owner named `mira`, the runtime expression below selects `default-mira`,
-so every sample card in this opening board carries that exact `boardId`:
+The initial build's `<app-owner>` context supplies the app owner's handle. A
+sample record in the owner's own tree names that tree with `"@owner"` as the whole
+field value, which the platform fills in for whoever applies the seed. The opening
+view reads the signed-in person's own tree by their handle, so every sample card
+carries `"ownerHandle": "@owner"`:
 
 ```jsx
-const boardId = pickedBoardId ?? `default-${me?.userHandle}`;
-const { docs: cards } = useLiveQuery("boardId", { key: boardId });
+const { docs: cards } = useLiveQuery("ownerHandle", { key: me?.userHandle });
 ```
 
 ```json
 {
   "boards": [
-    { "key": "tent", "type": "card", "boardId": "default-mira", "text": "Blue tent, sleeps four" },
-    { "key": "stove", "type": "card", "boardId": "default-mira", "text": "Two-burner camp stove" },
-    { "key": "lantern", "type": "card", "boardId": "default-mira", "text": "Two rechargeable lanterns" },
-    { "key": "cooler", "type": "card", "boardId": "default-mira", "text": "Wheeled cooler" }
+    { "key": "tent", "type": "card", "ownerHandle": "@owner", "authorHandle": "@owner", "text": "Blue tent, sleeps four" },
+    { "key": "stove", "type": "card", "ownerHandle": "@owner", "authorHandle": "@owner", "text": "Two-burner camp stove" },
+    { "key": "lantern", "type": "card", "ownerHandle": "@owner", "authorHandle": "@owner", "text": "Two rechargeable lanterns" },
+    { "key": "cooler", "type": "card", "ownerHandle": "@owner", "authorHandle": "@owner", "text": "Wheeled cooler" }
   ]
 }
 ```
 
-Use the supplied owner handle in these parent IDs; keep the app's query
-and real writes driven by the current viewer and selected object. The database
-name, record type, parent references and query filters agree across the sample
-file and opening view. Later access rules preserve those parent references.
-The platform labels the temporary preview as sample data; those records reach
-persistent storage only through the person's explicit import.
+An id that only contains the handle (`settings-mira`) is not a whole value, so
+write the supplied owner handle into it literally; keep the app's query and real
+writes driven by the current viewer and selected object. The database name,
+record type, parent references and query filters agree across the sample file and
+opening view. Later access rules preserve those parent references. The platform
+labels the temporary preview as sample data; those records reach persistent
+storage only through the person's explicit import.
 
 ### Seeding starter data — give each seed a deterministic `_id`
 
-When an app ships with default content — starter slides, template rows, example cards — and writes it into the database on first load, give **each seed document a deterministic `_id`** (`"seed:intro"`, `"seed:" + key`). This makes the seeding write **idempotent**: if it ever runs again, it overwrites the same documents instead of creating fresh copies.
+When an app ships with default content — starter slides, template rows, example cards — the content is a set of `seed.json` items, each with a **deterministic identity** (a stable `key`, or `_id: "seed:intro"`). This makes adding it **idempotent**: a second add overwrites the same documents instead of creating fresh copies.
 
-The trap is the live-query empty state. `useLiveQuery` renders empty before data arrives, so `docs.length === 0` is briefly true on **every** fresh load — and a `useRef`/`useState` "already seeded" flag only guards the current session, never the next reload, a second device, or another collaborator. With **auto-generated** `_id`s, each of those re-seeds the full set and duplicate copies pile up without bound. Deterministic `_id`s collapse every re-seed back onto the same N documents.
+The app itself writes no copy. `useLiveQuery` renders empty before data arrives, so `docs.length === 0` is briefly true on **every** fresh load, and a "seed when empty" effect re-runs on every reload, every device and for every visitor. The empty view instead invites the person's own first action, and that action writes the record it checked:
 
 ### `App.jsx`
-```jsx
-import React from "react";
-import { useFireproof } from "use-fireproof";
-import { useVibe } from "use-vibes";
-
-// Stable _id per seed, and no Date.now()/random fields — keep the payload
-// constant so a redundant seed is a true no-op, not a churning rewrite.
-const SEED = [
-  { _id: "seed:intro", type: "slide", title: "Welcome", position: 1000 },
-  { _id: "seed:problem", type: "slide", title: "The problem", position: 2000 },
-  { _id: "seed:ask", type: "slide", title: "The ask", position: 3000 },
-];
-
-export default function App() {
+```jsx partial
+function Deck() {
   const { useLiveQuery, database } = useFireproof("deck");
   const { ready, can } = useVibe("deck");
   const { docs: slides } = useLiveQuery("position");
-
-  React.useEffect(() => {
-    if (slides.length > 0) return; // already has content — don't seed
-    // Ask the access rules before writing. A doc type the currently-enforced
-    // access rules don't allow yet (e.g. one this very edit just introduced —
-    // the update binds only after the whole turn lands) would be rejected:
-    // skip quietly now and seed on a later run instead of spamming errors.
-    if (!ready || !can.create(SEED[0]).ok) return;
-    // Deterministic _id → idempotent. Even if this runs again (another load or
-    // device before the query resolves), it overwrites the same docs instead of
-    // minting new ones, so seed slides never duplicate.
-    SEED.forEach((s) => database.put(s).catch((e) => console.error(e)));
-  }, [slides.length, ready, can, database]);
-
-  return <Deck slides={slides} />;
+  // The person's own tap writes the first slide: the control checks this exact record.
+  const first = { type: "slide", title: "Welcome", position: 1000 };
+  const allowed = ready && can.create(first).ok;
+
+  if (slides.length === 0) {
+    return (
+      <Stack gap={2}>
+        <Text>Your deck is ready for its first slide.</Text>
+        <Button type="button" disabled={!allowed} onClick={() => allowed && database.put(first)}>
+          Add the first slide
+        </Button>
+      </Stack>
+    );
+  }
+  return <Slides slides={slides} />;
 }
 ```
 
-Don't stamp `Date.now()` or other changing values into seed documents — that makes each re-seed rewrite the doc with new content, churning revisions even though the `_id` is stable. Resource-like docs — channels, profiles, **seeds** — get deterministic `_id`s; event/content docs let `_id` auto-generate.
+Don't stamp `Date.now()` or other changing values into seed documents — that makes each re-add rewrite the doc with new content, churning revisions even though the `_id` is stable. Resource-like docs — channels, profiles, **seeds** — get deterministic `_id`s; event/content docs let `_id` auto-generate.
 
 ### Updating Documents in Event Handlers
 
@@ -454,7 +435,7 @@ A drag that touches many documents (painting pixels, drawing on a shared board)
 
 Keep each cell its own document with a deterministic `_id` (`pixel-<x>-<y>`). Never fold the canvas into one document every visitor saves: the server keeps whichever save arrives last, so one visitor's save erases everyone else's strokes. An unsaved draft drops out for peers about 12 seconds after it stops updating.
 
-A draft reaches only the peers already subscribed to its channel, and a channel's grant comes from a saved document. Create a fixed-id room record on that channel (see Required starting records) so even the first stroke on an empty canvas is seen live.
+A draft reaches only the peers already subscribed to its channel, and a channel's grant comes from a saved document. The painter's own pointer-down saves a fixed-id room record on that channel before the first stroke is drawn, so the stroke is seen live; nothing writes on load or on mount.
 
 ### `App.jsx`
 ```jsx
@@ -485,12 +466,6 @@ function Canvas({ me }) {
   const cellsRef = useRef([]);
   const canvasRef = useRef(null);
 
-  useEffect(() => {
-    // The room record grants the channel, so peers subscribe before the first stroke.
-    const room = { _id: "canvas:main", type: "canvas" };
-    if (ready && can.create(room).ok) database.put(room);
-  }, [ready, can, database]);
-
   useEffect(() => {
     const ctx = canvasRef.current.getContext("2d");
     ctx.fillStyle = "#ffffff";
@@ -504,6 +479,13 @@ function Canvas({ me }) {
     for (const [x, y] of stroke.cells) fill(x, y, stroke.color);
   }, [pixels, strokes, stroke, me]);
 
+  function startStroke(e) {
+    // The painter's own pointer-down saves the room record that grants the channel; the
+    // fixed id makes every later save the same document.
+    const room = { _id: "canvas:main", type: "canvas" };
+    if (ready && can.create(room).ok) database.put(room);
+    extendStroke(e);
+  }
   function extendStroke(e) {
     if (!canPaint) return;
     const r = canvasRef.current.getBoundingClientRect();
@@ -532,7 +514,7 @@ function Canvas({ me }) {
         className="w-full max-w-lg aspect-square touch-none"
         onPointerDown={(e) => {
           e.currentTarget.setPointerCapture(e.pointerId);
-          extendStroke(e);
+          startStroke(e);
         }}
         onPointerMove={(e) => e.buttons && extendStroke(e)}
         onPointerUp={endStroke}

package/llms/richtext.js

@@ -6,7 +6,8 @@ export const richtextConfig = {
         "edits with the last editor named, meeting notes with action items, a recipe book with real pages, " +
         "a journal with one entry per day. Covers every Tiptap package pinned to one version by its esm.sh " +
         "URL (one ProseMirror, no second React), an editor module with createEditor, load, flush, run and " +
-        "destroy, a saved note as its JSON plus plain text and a derived title, saving after typing pauses " +
+        "destroy, a saved note as its JSON plus plain text and a derived title, a title field beside the " +
+        "page saved with the body (after its own pause and on close, so drafts keep their titles), saving after typing pauses " +
         "with flush on blur and switch, loading a document without a save echo (setContent with emitUpdate " +
         "false), destroy in the effect's cleanup, the page styled from the host with arbitrary variants, " +
         "toolbar commands and active states, and images as _files. " +

package/llms/richtext.js.map

@@ -1 +1 @@
-{"version":3,"file":"richtext.js","sourceRoot":"","sources":["../../jsr/llms/richtext.ts"],"names":[],"mappings":"AAKA,MAAM,CAAC,MAAM,cAAc,GAAc;IACvC,IAAI,EAAE,UAAU;IAChB,KAAK,EAAE,oBAAoB;IAC3B,WAAW,EACT,oGAAoG;QACpG,gGAAgG;QAChG,oGAAoG;QACpG,oGAAoG;QACpG,mGAAmG;QACnG,oGAAoG;QACpG,oGAAoG;QACpG,kGAAkG;QAClG,4DAA4D;QAC5D,sGAAsG;QACtG,2FAA2F;IAC7F,IAAI,EAAE;QACJ,UAAU;QACV,WAAW;QACX,aAAa;QACb,aAAa;QACb,YAAY;QACZ,SAAS;QACT,OAAO;QACP,MAAM;QACN,iBAAiB;QACjB,YAAY;QACZ,WAAW;QACX,WAAW;QACX,aAAa;QACb,SAAS;QACT,aAAa;QACb,eAAe;QACf,iBAAiB;QACjB,eAAe;QACf,gBAAgB;QAChB,oBAAoB;QACpB,iBAAiB;QACjB,oBAAoB;QACpB,cAAc;QACd,QAAQ;QACR,aAAa;QACb,OAAO;QACP,SAAS;QACT,cAAc;QACd,WAAW;KACZ;CACF,CAAC"}
+{"version":3,"file":"richtext.js","sourceRoot":"","sources":["../../jsr/llms/richtext.ts"],"names":[],"mappings":"AAKA,MAAM,CAAC,MAAM,cAAc,GAAc;IACvC,IAAI,EAAE,UAAU;IAChB,KAAK,EAAE,oBAAoB;IAC3B,WAAW,EACT,oGAAoG;QACpG,gGAAgG;QAChG,oGAAoG;QACpG,oGAAoG;QACpG,mGAAmG;QACnG,kGAAkG;QAClG,uHAAuH;QACvH,oGAAoG;QACpG,kGAAkG;QAClG,4DAA4D;QAC5D,sGAAsG;QACtG,2FAA2F;IAC7F,IAAI,EAAE;QACJ,UAAU;QACV,WAAW;QACX,aAAa;QACb,aAAa;QACb,YAAY;QACZ,SAAS;QACT,OAAO;QACP,MAAM;QACN,iBAAiB;QACjB,YAAY;QACZ,WAAW;QACX,WAAW;QACX,aAAa;QACb,SAAS;QACT,aAAa;QACb,eAAe;QACf,iBAAiB;QACjB,eAAe;QACf,gBAAgB;QAChB,oBAAoB;QACpB,iBAAiB;QACjB,oBAAoB;QACpB,cAAc;QACd,QAAQ;QACR,aAAa;QACb,OAAO;QACP,SAAS;QACT,cAAc;QACd,WAAW;KACZ;CACF,CAAC"}

package/llms/richtext.md

@@ -357,6 +357,55 @@ 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.
 
+## A title field saves with the body
+
+**A title field beside the editor saves through the same write as the body:
+one `write` helper merges every change into the open document and puts it,
+one put at a time, so the title saves after its own pause and closing the
+document waits for the page and the title to land together.** A blog with
+drafts, a journal with named entries or a recipe book with a name field
+keeps the title in an `Input` above the page, and the writer expects both to
+be there when they step back to the list. Publishing then changes `status`
+and nothing else, so a private draft keeps every word its writer typed,
+title included.
+
+```jsx
+const [title, setTitle] = useState(post.title);
+const docRef = useRef(post); // the open document as last written
+const queue = useRef(Promise.resolve()); // puts to one _id run in turn
+
+// The page's onChange and the title both write here: the change merges into
+// the open document at once, and its put waits for the one before it.
+function write(changes) {
+  docRef.current = { ...docRef.current, ...changes, updatedAt: Date.now() };
+  const next = docRef.current;
+  queue.current = queue.current.then(() => database.put(next));
+  return queue.current;
+}
+
+// The title waits for its own pause, like the page.
+useEffect(() => {
+  if (title === docRef.current.title) return;
+  const timer = setTimeout(() => write({ title }), 600);
+  return () => clearTimeout(timer);
+}, [title]);
+
+// Back to the list: flush the page, add the title, and wait for both.
+async function close() {
+  surfaceRef.current?.flush();
+  if (title !== docRef.current.title) write({ title });
+  await queue.current;
+  onClose();
+}
+```
+
+The page's `onChange` calls the same helper, `write({ body: json, text })`.
+Because each change merges into `docRef` before its put is queued, the last
+put carries the page and the title together, and puts to one `_id` never
+overlap (overlapping puts collide on the document's sequence, as in the
+saving section above). The `Input` stays `onChange={setTitle}`; the effect
+does the saving.
+
 ## Loading a document lands without a save
 
 **A document arriving from the database is loaded with `setContent` and
@@ -604,6 +653,10 @@ warning.
   derived. `titleOf(json)` on every save.
 - **Typing is lost when switching notes** — the debounce had not fired.
   `flush()` before changing the open note.
+- **Every draft comes back as "Untitled draft"** — the title field lives in
+  React state and only Publish writes it. Save the title after its own
+  pause and in the close step, through the same queued `write` as the page,
+  and let the close step wait for it.
 - **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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibes.diy/prompts",
-  "version": "14.3.120",
+  "version": "14.3.122",
   "type": "module",
   "main": "./index.js",
   "exports": {
@@ -39,10 +39,10 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@adviser/cement": "~0.5.34",
-    "@vibes.diy/api-types": "14.3.120",
-    "@vibes.diy/call-ai-v2": "14.3.120",
-    "@vibes.diy/identity": "14.3.120",
-    "@vibes.diy/use-vibes-types": "14.3.120",
+    "@vibes.diy/api-types": "14.3.122",
+    "@vibes.diy/call-ai-v2": "14.3.122",
+    "@vibes.diy/identity": "14.3.122",
+    "@vibes.diy/use-vibes-types": "14.3.122",
     "arktype": "~2.2.6",
     "json-schema-faker": "~0.6.3"
   },

package/system-prompt-initial-instant.md

@@ -97,6 +97,7 @@ export default function App() {
 - **The named interaction works end to end**: the person's sentence names it, and the app builds that and only that, with realistic data. Sharing, invitations, roles, scheduled jobs, emails and outside services come in a later pass, and so does the line about who can see the data, which sits beside the share control that pass adds; the title, subtitle and hero say what the app is for.
 - **Seed content** is realistic and specific to the app's world, with a `key` per item and the exact fields the app reads.
 - **Layout comes from the components** (`Stack`, `Row`, `Grid`, `Card`) and their `tone`, `size` and `variant` props; plain spacing like `p-6` sits on your own wrapping elements only. The look brief below says how the page is composed.
+- **A bar fixed to the bottom of the screen — a tab bar, a nav, a save bar — rides above the platform's controls**, so every tab and button on it stays tappable: `BottomNav` sits there by itself, and a bar of your own puts `bottom: 'var(--vibes-controls-inset, 0px)'` in its `style` instead of using `bottom-0`.
 - **Tapping a person opens their profile**: `<ViewerTag userHandle={m.userHandle} onClick={() => setProfile(m.userHandle)} />` binds the handle the tag shows, and a hero header is `<ViewerTag userHandle={profile} size={120} avatarOnly />` — the tag itself is the button, drawn natively. Opening a profile follows nobody.
 
 # Fireproof on vibes.diy — the short version