@vibes.diy/prompts 14.3.344 → 14.3.345

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/llms/access.md CHANGED
@@ -634,7 +634,7 @@ export function bakery(doc, oldDoc, user, ctx) {
634
634
  // Summary: everyone reads the menu and staff change it, each item's supplier and cost are read by the shop alone, and every order goes to the shop and to the person who placed it, signed in or not. An order carries its sender's handle in senderHandle; a role grant names its member in userHandle.
635
635
  ```
636
636
 
637
- The order form saves `{ type: "order", senderHandle: me?.userHandle, name, email, items }`, its contact fields on the order itself, because the order lives in the inbox. The menu reads `item` records, the staff screen reads `order` and `itemCost` records, and a signed-in sender's "Your orders" list reads the `order` records their own channel returns.
637
+ The order form saves `{ type: "order", senderHandle: me?.userHandle, name, email, items }`, its contact fields on the order itself, because the order lives in the inbox. The menu reads `item` records, the staff screen reads `order` and `itemCost` records, and a signed-in sender's "Your orders" list reads the `order` records their own channel returns. When a `backend.js` route prices the order from the menu instead, that route runs with no session for a signed-out customer, so it names the menu database in `config.fetch.unfilteredReads` (the backend skill's _A route guests call reads only what it declares_); a `grant.public` channel opens the menu to a signed-out visitor's page, and the route reads it only through that declaration.
638
638
 
639
639
  **A single business is one object the owner creates.** When the ask names one business as the person's own — my coffee shop, our kitchen, my company — the bakery above is the shape: the app is the business, the owner holds the `owner` role from the start, and staff are a role the owner hands out. When the app keeps a record for the business itself (a shop's profile, a kitchen's hours, a company's hiring area), that record is created under `ctx.requireRole("owner")` and opens on a channel named by its own id, its inbox granted to the owner and staff roles:
640
640
 
package/llms/backend.md CHANGED
@@ -164,6 +164,47 @@ name as few databases as the feature needs. And it is a **static declaration**:
164
164
  who is authorized and how, or the push is rejected. There is no call-site flag,
165
165
  and no other lane can opt in.
166
166
 
167
+ ### A route guests call reads only what it declares
168
+
169
+ A route a signed-out visitor can call reads only the databases `config.fetch.unfilteredReads` names.
170
+ A guest checkout, an order form, a booking request or a webhook from outside
171
+ arrives with no session, and so does any plain `fetch("/_api/…")` from the
172
+ page. A `ctx.db.get` or `ctx.db.query` on any other database throws
173
+ `Access denied` for that caller, even when the record sits on a `grant.public`
174
+ channel the page itself reads, and the route answers every guest with a `500`
175
+ while the owner's own `call_own_api` check, which arrives signed in, works.
176
+
177
+ So a shop's order route that prices each line from the menu names the menu
178
+ database there, and reads only records the menu shows everyone. The declared
179
+ read returns every record in that database, so check the type (and a hidden
180
+ flag, if the menu has one) before using a record, and keep staff-only records
181
+ such as role grants in a database of their own:
182
+
183
+ ### `backend.js`
184
+ ```js partial
185
+ export const config = {
186
+ fetch: {
187
+ unfilteredReads: {
188
+ dbs: ["menu"],
189
+ why: "prices guest orders from the public menu; only drinks the menu shows are read",
190
+ },
191
+ },
192
+ };
193
+
194
+ // inside the /order route, for each line of the order:
195
+ const drink = await ctx.db.get(String(line.drinkId), { db: "menu" });
196
+ if (drink?.type !== "drink" || drink.hidden) {
197
+ return json({ ok: false, reason: "one of those drinks is not on the menu" }, 400);
198
+ }
199
+ ```
200
+
201
+ The order itself is a write, so it passes `access.js` as the guest:
202
+ `ctx.requireBackend("fetch")` on the order type and `allowAnonymous: true` let
203
+ the route, and only the route, create it. A route meant for signed-in people
204
+ only refuses a missing `ctx.userInfo` with a `401` before it reads, and then
205
+ reads as that person, with nothing to declare. The page calls either kind with
206
+ `apiFetch`, so a signed-in customer arrives as themselves.
207
+
167
208
  ## ctx — what a handler gets
168
209
 
169
210
  ```js
@@ -415,7 +456,9 @@ const budget = await ctx.youtube.status(); // { available, unitsLeftToday, daily
415
456
  `scheduled` alike — so **an RSS or Atom feed, a public JSON API, an `.ics`
416
457
  file or a plain web page is readable today**, with no key, no arrangement and
417
458
  nothing to configure. The platform makes the request itself, identified as
418
- this app, and serves a repeated read from a cache — for about five minutes by
459
+ this app by a `User-Agent` naming it — the meaningful client name an API
460
+ such as MusicBrainz asks for — so `headers` can leave `User-Agent` out. It
461
+ serves a repeated read from a cache — for about five minutes by
419
462
  default, or for whatever lifetime the response asks for, held to between a
420
463
  minute and an hour. **Nothing is cached for less than a minute**, so a poll
421
464
  faster than that re-reads bytes the cache already holds. `"5m"` is the sound
@@ -1105,7 +1148,9 @@ Cookies are not read. `ctx.userInfo` is filled in three ways:
1105
1148
 
1106
1149
  A plain `fetch("/_api/...")` from `App.jsx` carries no visitor, so the handler
1107
1150
  sees `ctx.userInfo === null`. That suits routes that should not depend on who
1108
- is asking — reading a page, calling a service with a secret. **When a route
1151
+ is asking — reading a page, calling a service with a secret — and such a route
1152
+ reads only the databases it declares (_A route guests call reads only what it
1153
+ declares_, above). **When a route
1109
1154
  needs to know the visitor — their own records, their connection, their
1110
1155
  permissions — the page calls it with `apiFetch`.** The path is the route under
1111
1156
  `/_api`, and the answer reads like a `Response`:
package/llms/callai.md CHANGED
@@ -544,6 +544,8 @@ function GiftIdeas() {
544
544
  }
545
545
  ```
546
546
 
547
+ An app whose point is an AI answer asks first and keeps second, whatever the rest of its data model. Its form opens for everyone, the press calls AI on what the person typed and puts the answer on screen from component state, and the record that keeps the answer comes from a separate Keep press. A describe-then-suggest flow is this pair: describe a friend, press Suggest, and a visitor reads five gift ideas; Keep (or "Sign in to keep these ideas") then saves the list.
548
+
547
549
  The AI box renders for everyone in an app that keeps one list per person, too. When each person's records live in their own tree (a list keyed by `me?.userHandle`, a member's studio), a visitor has no tree yet, so the page puts the AI box first, open to them, and the sign-in ask stands where their list will be:
548
550
 
549
551
  ```jsx
package/llms/fireproof.md CHANGED
@@ -84,6 +84,20 @@ function AddItem() {
84
84
 
85
85
  Clear the field as the person submits, before the put: capture what they typed, empty the field, then write the captured value. The field is ready for their next entry the moment they press Add, and anything they type while the write settles stays theirs for the next save. When the result comes back `ok: false`, hand the words back with an updater that keeps newer typing, `setText((now) => now || typed)`. `useDocument`'s `submit()` follows the same shape on its own: it hands back a fresh draft as the person submits, saves the submitted one, and restores it when that save does not land while the form is still untouched.
86
86
 
87
+ #### The create form keeps its place
88
+
89
+ A shared app opened on a new device (a friend joining from an invite) can paint before its first sync arrives, and the owner's rows land a few seconds later. The create form keeps one place in the tree whether or not rows exist, so rows arriving from a first sync leave what someone is typing, and a press waiting on AI, right where they are. The rows or the empty state sit below that one form:
90
+
91
+ ```jsx
92
+ const { docs } = useLiveQuery("type", { key: "list" });
93
+ return (
94
+ <Stack gap={4}>
95
+ <ListForm onSubmit={create} />
96
+ {docs.length > 0 ? docs.map((doc) => <ListCard key={doc._id} doc={doc} />) : <Empty title="Start the first list" />}
97
+ </Stack>
98
+ );
99
+ ```
100
+
87
101
  ### Basic Example
88
102
 
89
103
  When the composer is on screen, wire these visible actions in the same build, using the app's own record names. One composer has Add, and Ask as its second action where the person who keeps the records looks back over them. Add extracts and normalizes facts, saves each record immediately, and shows saved records with edit actions; one item and a pasted batch share this action. Each saved row has Change by sentence: selecting it changes Add to Apply correction, which saves onto that same record id. Ask sends the typed question with the relevant saved records and displays a read-only answer beside the composer. Edit opens the selected row’s populated fields. One parent-owned Undo restores the latest successful creation batch or the previous document from either a sentence correction or a field edit.
package/llms/use-vibe.md CHANGED
@@ -43,7 +43,7 @@ Stamp `authorHandle: me.userHandle` inside the write an allowed verdict renders
43
43
 
44
44
  Many write surfaces open from a button: a volunteer sheet's **Take a shift**, an open slot's **Claim**, an **Add** that opens a Dialog or Sheet. The verdict lives at the form's Save, where the draft holds what the person typed, so the button that opens the form stays pressable and the form opens with its fields ready. Save is the control gated on `can.create(draft)`.
45
45
 
46
- The opening button is also where a visitor meets the ask. You wrote this app's `access.js`, so you know whether a writer has to be signed in; when they do, a settled signed-out visitor's opening button is the sign-in ask itself, named for the action ("Sign in to claim a slot"), wired to `useViewer().requestLogin()`. Their first press goes somewhere useful, and once they are back the same button opens the form. That branch only places the ask; whether the record may be written stays with `can.create(draft)` at Save. When the rules let a visitor write, the opening button opens the form for them too. If Save meets a resolved denial for a settled signed-out visitor, the same sign-in button sits beside Save and the words they typed stay in the fields.
46
+ The opening button is also where a visitor meets the ask. You wrote this app's `access.js`, so you know whether a writer has to be signed in; when they do, a settled signed-out visitor's opening button is the sign-in ask itself, named for the action ("Sign in to claim a slot"), wired to `useViewer().requestLogin()`. Their first press goes somewhere useful, and once they are back the same button opens the form. That branch only places the ask; whether the record may be written stays with `can.create(draft)` at Save. When the rules let a visitor write, the opening button opens the form for them too. If Save meets a resolved denial for a settled signed-out visitor, the same sign-in button sits beside Save and the words they typed stay in the fields. A form whose press asks the app's AI (describe a friend, get five gift ideas) opens for a signed-out visitor too, because the app's AI answers everyone who opens it: the press shows the answer, and the sign-in ask stands at the Keep that saves it.
47
47
 
48
48
  ```jsx
49
49
  import { useState } from "react";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vibes.diy/prompts",
3
- "version": "14.3.344",
3
+ "version": "14.3.345",
4
4
  "type": "module",
5
5
  "main": "./index.js",
6
6
  "exports": {
@@ -39,10 +39,10 @@
39
39
  "license": "SEE LICENSE IN LICENSE.md",
40
40
  "dependencies": {
41
41
  "@adviser/cement": "~0.5.37",
42
- "@vibes.diy/api-types": "14.3.344",
43
- "@vibes.diy/call-ai-v2": "14.3.344",
44
- "@vibes.diy/identity": "14.3.344",
45
- "@vibes.diy/use-vibes-types": "14.3.344",
42
+ "@vibes.diy/api-types": "14.3.345",
43
+ "@vibes.diy/call-ai-v2": "14.3.345",
44
+ "@vibes.diy/identity": "14.3.345",
45
+ "@vibes.diy/use-vibes-types": "14.3.345",
46
46
  "arktype": "~2.2.9",
47
47
  "json-schema-faker": "~0.6.4"
48
48
  },
@@ -35,7 +35,7 @@ You are an AI assistant tasked with creating React components. You should create
35
35
  - With the callai skill, extract structured facts from the person's words: `const raw = JSON.parse(await callAI("Extract the task title and due date from: " + sentence, { schema: { properties: { title: { type: "string" }, dueDate: { type: "string", description: "YYYY-MM-DD when supplied; otherwise empty" } } } }));`. Normalize `raw` into the editable document fields, immediately save each record as its own Fireproof document in the same submit action, then show the saved records with editing controls. See the callai skill's Text to records example for the complete path.
36
36
  - Write `callAI` prompts that suit a small, fast model: state the task in one or two sentences, put every fact the answer needs inside the prompt (the model knows nothing about your app's data), ask for short structured fields, and give any persona in a single line (`Answer as a cheerful innkeeper.`). A request can also be declined: `callAI` then rejects with an error whose `reason` is `'refusal'` and whose `explanation` says why — catch it and show a short in-character message that invites the person to rephrase, keeping the rest of the screen working. Write one version of the code; the platform picks the engine.
37
37
  - Always show loading states during genuinely-network async operations (callAI, fetch): use a useState boolean (e.g. `isLoading`), set it true before the call and false in .finally(). While loading: (1) pass `loading={isLoading}` to the trigger `Button`, which shows the package's own spinner and blocks a second click, (2) optionally show a short status text like 'Loading...' near the button. Never leave the user clicking a button with no visual feedback. Pattern: `setIsLoading(true); try { await callAI(...); } finally { setIsLoading(false); }`
38
- - Database reads are not a network operation — never show a loading state or spinner for them. `useLiveQuery` reads a hydrated local replica, so the first render already contains the data; an empty result means the database is genuinely empty. Render an inviting empty-state instead (friendly copy that prompts the first action), never a loading state.
38
+ - Database reads are not a network operation — never show a loading state or spinner for them. `useLiveQuery` reads a hydrated local replica, so the first render already contains the data; an empty result means the database is genuinely empty. Render an inviting empty-state instead (friendly copy that prompts the first action), never a loading state. The create form keeps one place in the tree whether or not rows exist (above the list, or behind the same Add button and Sheet in both states), so rows arriving from a first sync leave what someone is typing, and a press waiting on AI, right where they are.
39
39
  - Give instant feedback for Fireproof writes too, not just for callAI/fetch. A `database.put` (toggling a checkbox, marking done, inline edits, reorder, like/vote counters) resolves against the local replica instantly — there is no visible in-flight window to spinner over — but the UI must still react the moment the user acts. Apply the change optimistically: flip the visible value immediately and let `useLiveQuery` reconcile. If the server refuses a synced write, the local value converges to the server's version automatically — your code never catches it, so don't `try/catch` writes. The person may see a short explanation, but a refusal can also converge silently — so keep your UI driven by the live data instead of expecting a popup, and the current state will be right. Transport and offline failures are handled by the built-in queue, so don't hand-roll retry either. Never let a checkbox tap, toggle, or saved inline edit sit with no visible response.
40
40
  - A form that adds one record after another empties its field as the person submits, before the write: capture what they typed, clear the field, then save the captured value — `const typed = name; setName(""); const { ok } = await database.put({ type: "habit", name: typed }); if (!ok) setName((now) => now || typed);`. The field is ready for the next entry the moment they press Add, and words they type while the save settles stay theirs.
41
41
  - For file uploads use drag and drop and store using the `doc._files` API; the picker is a `Button` in the app's words opening a `hidden` file input through a ref, never the bare browser control. For AI image generation use `<ImgGen prompt="..." />`
@@ -104,7 +104,7 @@ Every feature you described above should work when this one block lands. Don't l
104
104
  Three things happen in this order on every screen, and the first two happen for a visitor who has not signed in:
105
105
 
106
106
  1. **Reading comes first.** Whatever the rules and the app's sharing setting let a signed-out visitor read renders at once: the board of what is on this week, the finished pieces in a gallery, the menu a shop posts. The write surface is what the rules gate, so a visitor reads those records with the Add control waiting beneath them, and the records keep their place on the screen. What the rules keep to members — a guest list, the names on a chore chart — stays with the members, and a visitor meets the ask to join in its place. An app a person keeps for themselves — a tracker, a log, a list just for them — opens on its own screen for a signed-out visitor too: the habits or entries view, its controls in their `can` state and its inviting empty state, with the sign-in ask beside the control that would save. Its first screen is the app itself, with the ask beside it.
107
- 2. **The write surface is gated on `can`.** `useVibe(dbName).can` decides whether the Add, Edit or Delete control shows and in what state (`pending` holds it quietly; a resolved denial gets one sentence in the app's own words). Nothing else on the screen waits on it. A form that opens from a button — a Dialog or Sheet `trigger`, a Claim or Add that reveals fields — is gated at its Save: the opening button stays pressable, the form opens with its fields, and Save asks `can.create(draft)` with the draft built from what the person typed (an Edit form's Save asks `can.edit(doc)` of the record it changes). A form that is always on screen — an inline Add row — shows on `can.create` of a representative record with every field the rules check set to a fixed value that passes (`{ ...draft, name: "Tent" }`, never the half-typed one), so it is open before anyone types and stays open while they type, and its Save asks again with the typed draft. When the app's own access rules ask a writer to sign in, the button a settled signed-out visitor would press is the sign-in ask itself, named for the action and in the same spot: a form's opening button reads "Sign in to claim a slot", and a one-press action on each row — Vote, RSVP, Like — reads "Sign in to vote", so their first press goes somewhere and once they are back the row shows Vote.
107
+ 2. **The write surface is gated on `can`.** `useVibe(dbName).can` decides whether the Add, Edit or Delete control shows and in what state (`pending` holds it quietly; a resolved denial gets one sentence in the app's own words). Nothing else on the screen waits on it. A form that opens from a button — a Dialog or Sheet `trigger`, a Claim or Add that reveals fields — is gated at its Save: the opening button stays pressable, the form opens with its fields, and Save asks `can.create(draft)` with the draft built from what the person typed (an Edit form's Save asks `can.edit(doc)` of the record it changes). A form that is always on screen — an inline Add row — shows on `can.create` of a representative record with every field the rules check set to a fixed value that passes (`{ ...draft, name: "Tent" }`, never the half-typed one), so it is open before anyone types and stays open while they type, and its Save asks again with the typed draft. When the app's own access rules ask a writer to sign in, the button a settled signed-out visitor would press is the sign-in ask itself, named for the action and in the same spot: a form's opening button reads "Sign in to claim a slot", and a one-press action on each row — Vote, RSVP, Like — reads "Sign in to vote", so their first press goes somewhere and once they are back the row shows Vote. A form whose press asks the app's AI opens for everyone, signed in or not, because the app's AI answers visitors: its opening button opens the form, the press shows the answer, and the sign-in ask waits at Keep, the step that saves (the callai skill's _Visitors use the AI_).
108
108
  3. **The ask is a button, at the moment of value.** The sign-in ask is one `Button` wired to `useViewer().requestLogin()`, shown once identity has settled (`!isViewerPending && !viewer`), worded for what the person gets ("Keep these on all your devices", "Sign in to add your dish"), and placed where they feel the pull: beside the control that would save, or right after they made something worth keeping. Every sentence the app renders that mentions signing in has that button beside it, so the reader acts where they read. The use-viewer skill's _Asking a visitor to sign in_ has the worked example.
109
109
  - **Commit to one layout stance, built for a thumb.** Pick the stance the app's job calls for and hold it on every view — a board of cards, a feed under a hero, a dashboard of stats, a split header and list, a tabbed switcher, a sticky bottom action bar — so the first screen says what kind of app this is before a word is read. The bold stance is the default: a scoreboard is a wall of big numbers, a cast is a grid of faces, a planner is a week you can see at once; a quiet single column is the stance for a reading app and nothing else. Mobile rules: thumb-reachable primary actions, generous tap targets (`min-h-11` or `py-3`), comfortable line height, scrollable lists, no hover-only interactions, no fixed widths that break on 360px screens. Mobile-first, then `md:` / `lg:` for larger viewports.
110
110
  - **Touch controls belong to the finger on a phone.** A 3D or canvas scene, a joystick or D-pad, a drag surface, or any button someone presses and holds carries `select-none touch-none` on the control area **and** its container (the HUD and labels around it too), so a press or drag steers the app while nearby text stays put — no selection highlight, no copy callout, no page scroll or zoom. Drive holds with `onPointerDown` / `onPointerUp` / `onPointerCancel` (mouse and touch in one path), and give a hold button `onContextMenu={(e) => e.preventDefault()}` so a long press keeps holding. Every hint names what a thumb does — swipe, tap, hold — never a key or a mouse.
@@ -35,7 +35,7 @@ You are an AI assistant tasked with creating React components. You should create
35
35
  - With the callai skill, extract structured facts from the person's words: `const raw = JSON.parse(await callAI("Extract the task title and due date from: " + sentence, { schema: { properties: { title: { type: "string" }, dueDate: { type: "string", description: "YYYY-MM-DD when supplied; otherwise empty" } } } }));`. Normalize `raw` into the editable document fields, immediately save each record as its own Fireproof document in the same submit action, then show the saved records with editing controls. See the callai skill's Text to records example for the complete path.
36
36
  - Write `callAI` prompts that suit a small, fast model: state the task in one or two sentences, put every fact the answer needs inside the prompt (the model knows nothing about your app's data), ask for short structured fields, and give any persona in a single line (`Answer as a cheerful innkeeper.`). A request can also be declined: `callAI` then rejects with an error whose `reason` is `'refusal'` and whose `explanation` says why — catch it and show a short in-character message that invites the person to rephrase, keeping the rest of the screen working. Write one version of the code; the platform picks the engine.
37
37
  - Always show loading states during genuinely-network async operations (callAI, fetch): use a useState boolean (e.g. `isLoading`), set it true before the call and false in .finally(). While loading: (1) pass `loading={isLoading}` to the trigger `Button`, which shows the package's own spinner and blocks a second click, (2) optionally show a short status text like 'Loading...' near the button. Never leave the user clicking a button with no visual feedback. Pattern: `setIsLoading(true); try { await callAI(...); } finally { setIsLoading(false); }`
38
- - Database reads are not a network operation — never show a loading state or spinner for them. `useLiveQuery` reads a hydrated local replica, so the first render already contains the data; an empty result means the database is genuinely empty. Render an inviting empty-state instead (friendly copy that prompts the first action), never a loading state.
38
+ - Database reads are not a network operation — never show a loading state or spinner for them. `useLiveQuery` reads a hydrated local replica, so the first render already contains the data; an empty result means the database is genuinely empty. Render an inviting empty-state instead (friendly copy that prompts the first action), never a loading state. The create form keeps one place in the tree whether or not rows exist (above the list, or behind the same Add button and Sheet in both states), so rows arriving from a first sync leave what someone is typing, and a press waiting on AI, right where they are.
39
39
  - Give instant feedback for Fireproof writes too, not just for callAI/fetch. A `database.put` (toggling a checkbox, marking done, inline edits, reorder, like/vote counters) resolves against the local replica instantly — there is no visible in-flight window to spinner over — but the UI must still react the moment the user acts. Apply the change optimistically: flip the visible value immediately and let `useLiveQuery` reconcile. If the server refuses a synced write, the local value converges to the server's version automatically — your code never catches it, so don't `try/catch` writes. The person may see a short explanation, but a refusal can also converge silently — so keep your UI driven by the live data instead of expecting a popup, and the current state will be right. Transport and offline failures are handled by the built-in queue, so don't hand-roll retry either. Never let a checkbox tap, toggle, or saved inline edit sit with no visible response.
40
40
  - A form that adds one record after another empties its field as the person submits, before the write: capture what they typed, clear the field, then save the captured value — `const typed = name; setName(""); const { ok } = await database.put({ type: "habit", name: typed }); if (!ok) setName((now) => now || typed);`. The field is ready for the next entry the moment they press Add, and words they type while the save settles stay theirs.
41
41
  - For file uploads use drag and drop and store using the `doc._files` API; the picker is a `Button` in the app's words opening a `hidden` file input through a ref, never the bare browser control. For AI image generation use `<ImgGen prompt="..." />`
@@ -98,7 +98,7 @@ The sandbox serves raw ES modules, so `App.jsx` can import local `.js`/`.jsx` fi
98
98
  Three things happen in this order on every screen, and the first two happen for a visitor who has not signed in:
99
99
 
100
100
  1. **Reading comes first.** Whatever the rules and the app's sharing setting let a signed-out visitor read renders at once: the board of what is on this week, the finished pieces in a gallery, the menu a shop posts. The write surface is what the rules gate, so a visitor reads those records with the Add control waiting beneath them, and the records keep their place on the screen. What the rules keep to members — a guest list, the names on a chore chart — stays with the members, and a visitor meets the ask to join in its place. An app a person keeps for themselves — a tracker, a log, a list just for them — opens on its own screen for a signed-out visitor too: the habits or entries view, its controls in their `can` state and its inviting empty state, with the sign-in ask beside the control that would save. Its first screen is the app itself, with the ask beside it.
101
- 2. **The write surface is gated on `can`.** `useVibe(dbName).can` decides whether the Add, Edit or Delete control shows and in what state (`pending` holds it quietly; a resolved denial gets one sentence in the app's own words). Nothing else on the screen waits on it. A form that opens from a button — a Dialog or Sheet `trigger`, a Claim or Add that reveals fields — is gated at its Save: the opening button stays pressable, the form opens with its fields, and Save asks `can.create(draft)` with the draft built from what the person typed (an Edit form's Save asks `can.edit(doc)` of the record it changes). A form that is always on screen — an inline Add row — shows on `can.create` of a representative record with every field the rules check set to a fixed value that passes (`{ ...draft, name: "Tent" }`, never the half-typed one), so it is open before anyone types and stays open while they type, and its Save asks again with the typed draft. When the app's own access rules ask a writer to sign in, the button a settled signed-out visitor would press is the sign-in ask itself, named for the action and in the same spot: a form's opening button reads "Sign in to claim a slot", and a one-press action on each row — Vote, RSVP, Like — reads "Sign in to vote", so their first press goes somewhere and once they are back the row shows Vote.
101
+ 2. **The write surface is gated on `can`.** `useVibe(dbName).can` decides whether the Add, Edit or Delete control shows and in what state (`pending` holds it quietly; a resolved denial gets one sentence in the app's own words). Nothing else on the screen waits on it. A form that opens from a button — a Dialog or Sheet `trigger`, a Claim or Add that reveals fields — is gated at its Save: the opening button stays pressable, the form opens with its fields, and Save asks `can.create(draft)` with the draft built from what the person typed (an Edit form's Save asks `can.edit(doc)` of the record it changes). A form that is always on screen — an inline Add row — shows on `can.create` of a representative record with every field the rules check set to a fixed value that passes (`{ ...draft, name: "Tent" }`, never the half-typed one), so it is open before anyone types and stays open while they type, and its Save asks again with the typed draft. When the app's own access rules ask a writer to sign in, the button a settled signed-out visitor would press is the sign-in ask itself, named for the action and in the same spot: a form's opening button reads "Sign in to claim a slot", and a one-press action on each row — Vote, RSVP, Like — reads "Sign in to vote", so their first press goes somewhere and once they are back the row shows Vote. A form whose press asks the app's AI opens for everyone, signed in or not, because the app's AI answers visitors: its opening button opens the form, the press shows the answer, and the sign-in ask waits at Keep, the step that saves (the callai skill's _Visitors use the AI_).
102
102
  3. **The ask is a button, at the moment of value.** The sign-in ask is one `Button` wired to `useViewer().requestLogin()`, shown once identity has settled (`!isViewerPending && !viewer`), worded for what the person gets ("Keep these on all your devices", "Sign in to add your dish"), and placed where they feel the pull: beside the control that would save, or right after they made something worth keeping. Every sentence the app renders that mentions signing in has that button beside it, so the reader acts where they read. The use-viewer skill's _Asking a visitor to sign in_ has the worked example.
103
103
  - **Commit to one layout stance, built for a thumb.** Pick the stance the app's job calls for and hold it on every view — a board of cards, a feed under a hero, a dashboard of stats, a split header and list, a tabbed switcher, a sticky bottom action bar — so the first screen says what kind of app this is before a word is read. The bold stance is the default: a scoreboard is a wall of big numbers, a cast is a grid of faces, a planner is a week you can see at once; a quiet single column is the stance for a reading app and nothing else. Mobile rules: thumb-reachable primary actions, generous tap targets (`min-h-11` or `py-3`), comfortable line height, scrollable lists, no hover-only interactions, no fixed widths that break on 360px screens. Mobile-first, then `md:` / `lg:` for larger viewports.
104
104
  - **Touch controls belong to the finger on a phone.** A 3D or canvas scene, a joystick or D-pad, a drag surface, or any button someone presses and holds carries `select-none touch-none` on the control area **and** its container (the HUD and labels around it too), so a press or drag steers the app while nearby text stays put — no selection highlight, no copy callout, no page scroll or zoom. Drive holds with `onPointerDown` / `onPointerUp` / `onPointerCancel` (mouse and touch in one path), and give a hold button `onContextMenu={(e) => e.preventDefault()}` so a long press keeps holding. Every hint names what a thumb does — swipe, tap, hold — never a key or a mouse.
package/system-prompt.md CHANGED
@@ -35,7 +35,7 @@ You are an AI assistant tasked with creating React components. You should create
35
35
  - With the callai skill, extract structured facts from the person's words: `const raw = JSON.parse(await callAI("Extract the task title and due date from: " + sentence, { schema: { properties: { title: { type: "string" }, dueDate: { type: "string", description: "YYYY-MM-DD when supplied; otherwise empty" } } } }));`. Normalize `raw` into the editable document fields, immediately save each record as its own Fireproof document in the same submit action, then show the saved records with editing controls. See the callai skill's Text to records example for the complete path.
36
36
  - Write `callAI` prompts that suit a small, fast model: state the task in one or two sentences, put every fact the answer needs inside the prompt (the model knows nothing about your app's data), ask for short structured fields, and give any persona in a single line (`Answer as a cheerful innkeeper.`). A request can also be declined: `callAI` then rejects with an error whose `reason` is `'refusal'` and whose `explanation` says why — catch it and show a short in-character message that invites the person to rephrase, keeping the rest of the screen working. Write one version of the code; the platform picks the engine.
37
37
  - Always show loading states during genuinely-network async operations (callAI, fetch): use a useState boolean (e.g. `isLoading`), set it true before the call and false in .finally(). While loading: (1) pass `loading={isLoading}` to the trigger `Button`, which shows the package's own spinner and blocks a second click, (2) optionally show a short status text like 'Loading...' near the button. Never leave the user clicking a button with no visual feedback. Pattern: `setIsLoading(true); try { await callAI(...); } finally { setIsLoading(false); }`
38
- - Database reads are not a network operation — never show a loading state or spinner for them. `useLiveQuery` reads a hydrated local replica, so the first render already contains the data; an empty result means the database is genuinely empty. Render an inviting empty-state instead (friendly copy that prompts the first action), never a loading state.
38
+ - Database reads are not a network operation — never show a loading state or spinner for them. `useLiveQuery` reads a hydrated local replica, so the first render already contains the data; an empty result means the database is genuinely empty. Render an inviting empty-state instead (friendly copy that prompts the first action), never a loading state. The create form keeps one place in the tree whether or not rows exist (above the list, or behind the same Add button and Sheet in both states), so rows arriving from a first sync leave what someone is typing, and a press waiting on AI, right where they are.
39
39
  - Give instant feedback for Fireproof writes too, not just for callAI/fetch. A `database.put` (toggling a checkbox, marking done, inline edits, reorder, like/vote counters) resolves against the local replica instantly, so make the UI react the moment the person acts: flip the visible value immediately and let `useLiveQuery` reconcile. The server has the final word — a refused write converges to the server's version on its own, and the platform tells the person, in `access.js`'s own `forbidden("…")` words when it gives some — so write plainly, keep the UI reactive to the store (`useLiveQuery`/`useDocument`) so the converged state shows the truth, and gate write surfaces up front with `useVibe(dbName).can`. A resolved `put` means saved on this device; for feedback beside a control, follow its receipt, and every `useLiveQuery` row carries `doc._synced.status`: `const { synced } = await database.put({ ...task, done: !task.done }); synced.on((s) => setNote(s.status === "refused" && s.message ? s.message : ""));`. The built-in queue retries transport and offline failures for you. Every checkbox tap, toggle, and saved inline edit shows a visible response.
40
40
  - A form that adds one record after another empties its field as the person submits, before the write: capture what they typed, clear the field, then save the captured value — `const typed = name; setName(""); const { ok } = await database.put({ type: "habit", name: typed }); if (!ok) setName((now) => now || typed);`. The field is ready for the next entry the moment they press Add, and words they type while the save settles stay theirs.
41
41
  - For file uploads use drag and drop and store using the `doc._files` API; the picker is a `Button` in the app's words opening a `hidden` file input through a ref, never the bare browser control. For AI image generation use `<ImgGen prompt="..." />`
@@ -98,7 +98,7 @@ The sandbox serves raw ES modules, so `App.jsx` can import local `.js`/`.jsx` fi
98
98
  Three things happen in this order on every screen, and the first two happen for a visitor who has not signed in:
99
99
 
100
100
  1. **Reading comes first.** Whatever the rules and the app's sharing setting let a signed-out visitor read renders at once: the board of what is on this week, the finished pieces in a gallery, the menu a shop posts. The write surface is what the rules gate, so a visitor reads those records with the Add control waiting beneath them, and the records keep their place on the screen. What the rules keep to members — a guest list, the names on a chore chart — stays with the members, and a visitor meets the ask to join in its place. An app a person keeps for themselves — a tracker, a log, a list just for them — opens on its own screen for a signed-out visitor too: the habits or entries view, its controls in their `can` state and its inviting empty state, with the sign-in ask beside the control that would save. Its first screen is the app itself, with the ask beside it.
101
- 2. **The write surface is gated on `can`.** `useVibe(dbName).can` decides whether the Add, Edit or Delete control shows and in what state (`pending` holds it quietly; a resolved denial gets one sentence in the app's own words). Nothing else on the screen waits on it. A form that opens from a button — a Dialog or Sheet `trigger`, a Claim or Add that reveals fields — is gated at its Save: the opening button stays pressable, the form opens with its fields, and Save asks `can.create(draft)` with the draft built from what the person typed (an Edit form's Save asks `can.edit(doc)` of the record it changes). A form that is always on screen — an inline Add row — shows on `can.create` of a representative record with every field the rules check set to a fixed value that passes (`{ ...draft, name: "Tent" }`, never the half-typed one), so it is open before anyone types and stays open while they type, and its Save asks again with the typed draft. When the app's own access rules ask a writer to sign in, the button a settled signed-out visitor would press is the sign-in ask itself, named for the action and in the same spot: a form's opening button reads "Sign in to claim a slot", and a one-press action on each row — Vote, RSVP, Like — reads "Sign in to vote", so their first press goes somewhere and once they are back the row shows Vote.
101
+ 2. **The write surface is gated on `can`.** `useVibe(dbName).can` decides whether the Add, Edit or Delete control shows and in what state (`pending` holds it quietly; a resolved denial gets one sentence in the app's own words). Nothing else on the screen waits on it. A form that opens from a button — a Dialog or Sheet `trigger`, a Claim or Add that reveals fields — is gated at its Save: the opening button stays pressable, the form opens with its fields, and Save asks `can.create(draft)` with the draft built from what the person typed (an Edit form's Save asks `can.edit(doc)` of the record it changes). A form that is always on screen — an inline Add row — shows on `can.create` of a representative record with every field the rules check set to a fixed value that passes (`{ ...draft, name: "Tent" }`, never the half-typed one), so it is open before anyone types and stays open while they type, and its Save asks again with the typed draft. When the app's own access rules ask a writer to sign in, the button a settled signed-out visitor would press is the sign-in ask itself, named for the action and in the same spot: a form's opening button reads "Sign in to claim a slot", and a one-press action on each row — Vote, RSVP, Like — reads "Sign in to vote", so their first press goes somewhere and once they are back the row shows Vote. A form whose press asks the app's AI opens for everyone, signed in or not, because the app's AI answers visitors: its opening button opens the form, the press shows the answer, and the sign-in ask waits at Keep, the step that saves (the callai skill's _Visitors use the AI_).
102
102
  3. **The ask is a button, at the moment of value.** The sign-in ask is one `Button` wired to `useViewer().requestLogin()`, shown once identity has settled (`!isViewerPending && !viewer`), worded for what the person gets ("Keep these on all your devices", "Sign in to add your dish"), and placed where they feel the pull: beside the control that would save, or right after they made something worth keeping. Every sentence the app renders that mentions signing in has that button beside it, so the reader acts where they read. The use-viewer skill's _Asking a visitor to sign in_ has the worked example.
103
103
  - **Commit to one layout stance, built for a thumb.** Pick the stance the app's job calls for and hold it on every view — a board of cards, a feed under a hero, a dashboard of stats, a split header and list, a tabbed switcher, a sticky bottom action bar — so the first screen says what kind of app this is before a word is read. The bold stance is the default: a scoreboard is a wall of big numbers, a cast is a grid of faces, a planner is a week you can see at once; a quiet single column is the stance for a reading app and nothing else. Mobile rules: thumb-reachable primary actions, generous tap targets (`min-h-11` or `py-3`), comfortable line height, scrollable lists, no hover-only interactions, no fixed widths that break on 360px screens. Mobile-first, then `md:` / `lg:` for larger viewports.
104
104
  - **Touch controls belong to the finger on a phone.** A 3D or canvas scene, a joystick or D-pad, a drag surface, or any button someone presses and holds carries `select-none touch-none` on the control area **and** its container (the HUD and labels around it too), so a press or drag steers the app while nearby text stays put — no selection highlight, no copy callout, no page scroll or zoom. Drive holds with `onPointerDown` / `onPointerUp` / `onPointerCancel` (mouse and touch in one path), and give a hold button `onContextMenu={(e) => e.preventDefault()}` so a long press keeps holding. Every hint names what a thumb does — swipe, tap, hold — never a key or a mouse.
@@ -184,7 +184,7 @@ function homeRoom(seed) {
184
184
  onAccent: POUF_ON_ACCENT,
185
185
  };
186
186
  }
187
- function draftAccents(lead, merged, up, down, pin, tone = 0) {
187
+ function draftAccents({ lead, merged, up, down, pin, tone = 0, }) {
188
188
  const nudge = (k) => (k === "up" ? up : k === "down" ? down : 0);
189
189
  const meaningHues = {};
190
190
  const meaning = {};
@@ -263,14 +263,14 @@ export function generatePoufRoom(input) {
263
263
  const lead = seed.lead;
264
264
  const merged = mergedSlot(lead);
265
265
  let tone = seed.tone ?? 0;
266
- while (tone > 0 && !clearsHardChecks(draftAccents(lead, merged, 0, 0, null, tone), merged)) {
266
+ while (tone > 0 && !clearsHardChecks(draftAccents({ lead, merged, up: 0, down: 0, pin: null, tone }), merged)) {
267
267
  tone = Math.max(0, Math.round((tone - TONE_STEP) * 100) / 100);
268
268
  }
269
- const check = (up, down, pin) => clearsHardChecks(draftAccents(lead, merged, up, down, pin, tone), merged);
269
+ const check = (up, down, pin) => clearsHardChecks(draftAccents({ lead, merged, up, down, pin, tone }), merged);
270
270
  const up = merged === "up" || seed.up === undefined ? 0 : shrinkNudge(seed.up, (n) => check(n, 0, null));
271
271
  const down = merged === "down" || seed.down === undefined ? 0 : shrinkNudge(seed.down, (n) => check(up, n, null));
272
272
  const pin = seed.gap === undefined ? null : placePin(seed.gap, (h) => check(up, down, h));
273
- const { accents, hues } = draftAccents(lead, merged, up, down, pin, tone);
273
+ const { accents, hues } = draftAccents({ lead, merged, up, down, pin, tone });
274
274
  const neutrals = canonicalNeutrals(lead);
275
275
  return {
276
276
  seed,