@homie-rocks/studio 0.51.5 → 0.51.6

package/CHANGELOG.md

@@ -17,6 +17,26 @@ To bring a studio up to date, tell Claude: "Upgrade my studio to the newest Homi
 `npx -y @homie-rocks/studio@latest upgrade`, which shows what's new since the version your studio pins (from this
 file) and what the upgrade would change, and changes nothing until you agree.
 
+## [0.51.6] - 2026-10-14
+
+**Plugin 0.51.6**
+
+Keep each customer's exact basket through payment, and check that your studio meets its needs across screens, AI jobs and handover.
+
+### Added
+
+- **Check the whole service:** Owner needs can call studio MCP tools as customer, staff or owner, assert returned results and saved records, invoke declared scheduled functions locally, read event feeds and MCP Events, check webhook delivery, and verify handover files. Checks keep role permissions and test-record isolation. Headless-only plans run without Chrome; missing tools, permissions, effects and text explain why a need is not met.
+
+### Fixed
+
+- **Exact rounds and baskets:** Opt-in keyless saved baskets keep the phone's exact items and quantities. One custom-amount Payment Link carries the saved total; signed payments are checked against the saved basket and report full payment or a shortfall for staff. Short payments grant no automatic entitlements. The Worker needs no Stripe API key, and existing adjustable Stripe menus keep their behavior.
+- **Clear acceptance and evidence:** Passing assertions mark a need met even when captures are absent or fail. Capture diagnostics identify the surface, explain the failure and show how to collect evidence with `--shots`.
+- **Reliable changing controls:** Click, fill and select actions retry detached elements within a bounded wait. The app skill, packaged guides and Codex template explain how updating controls in place preserves a held press across delayed refreshes.
+
+### Upgrade notes
+
+- Saved baskets are opt-in through `shop.json.basket` and require Stripe with tax-inclusive menu prices. Automatic tax and Managed Payments are refused for basket mode. Staff can use the reported basket total, actual payment and settlement status to collect a shortfall.
+
 ## [0.51.5] - 2026-10-14
 
 **Plugin 0.51.5**

package/apps/APPS.md

@@ -181,3 +181,18 @@ The phone remains its own surface; assert its confirmed gift after checkout. The
 checker brings each page forward before reading or capturing it. Use the real
 provider's controls, never a test-only app action. App sharing defaults to the top
 right, clear of bottom tabs; `screen.share` remains an author-controlled override.
+
+## Every owner need is executable
+
+The Codex `needs` block supports existing UI steps plus named-role MCP calls,
+returned-result assertions, simulated schedule ticks, record/results reads,
+event feed/MCP Events/webhook checks and handover file contents. See the packaged
+[needs format and examples](../guides/app/NEEDS.md). Passing assertions are **met**;
+captures are additional evidence. Missing captures name their surface, reason and
+how to rerun with `--shots .checks`. Detached action elements are re-queried for a
+bounded ten seconds; ambiguous post-dispatch failures are not replayed.
+
+Keep buttons connected during delayed refreshes: create the button once and set
+`button.textContent = label` when data arrives. Never replace a held button with
+`innerHTML` or `replaceWith`; that can cancel navigation between pointer down and
+up. The needs guide has a short complete example and explains outcome assertions.

package/guides/app/NEEDS.md

@@ -0,0 +1,160 @@
+# Check every owner need
+
+The JSON array in the app's `CODEX.md` fenced `needs` block is the acceptance
+source. Keep every owner statement, including AI jobs, reminders, results and
+handover. Each need has a unique `id`, `statement`, optional `role` and `steps`,
+and nonempty `assertions`. An unavailable capability stays as a need with an
+empty assertion list and a prose explanation; check reports it not met.
+
+Run `homie-studio check <app> --url http://localhost:8787 --shots .checks` with
+`homie-studio dev` running in the same studio. Headless-only needs require no
+Chrome. UI steps and headless steps can be combined in one need and run in order.
+Each need starts with its own saved results; records are shared across needs in
+the run. The default isolated record scope is shared by browsers, MCP calls and
+scheduled effects. `--no-isolate` explicitly uses existing records. Isolation is
+for app records, not a sandbox for external email/SMS/payment calls: use the
+service's test connection for those jobs.
+
+## Passing assertions and capture evidence
+
+Passing assertions mean **met**, with or without screenshots. A missing capture
+never changes that verdict. For every UI surface without a capture, the result
+names the surface, why it was unavailable (including the browser's error), and
+tells you to rerun with `--shots .checks`. Fix the reported disk/browser error
+first. Successful captures are listed in the saved needs report. Inspect them
+against the owner's scene: automation proves the assertions, not visual quality.
+Headless needs have no screenshots to collect.
+
+Click, fill and select actions re-query their selector for up to ten seconds when
+the browser reports a detached/stale element. A permanently unstable control
+reports its surface and selector. Other action failures are not replayed: a
+navigation error after dispatch does not prove that a purchase did not happen.
+
+## Customer and staff AI calls and returned results
+
+Headless actions require an explicit `role`, inherited from the need or overridden
+on a headless step/assertion. Use an app's declared role, or `owner` for owner-only
+operations. The dev-only signed identity enforces real MCP audiences and record
+capabilities; a customer is not silently promoted to owner. Production OAuth
+approval is unchanged. Missing dev credentials, tools or role permissions produce
+plain not-met reasons.
+
+```needs
+[
+  {"id":"ai-book","statement":"A customer's AI books in one call","role":"customer",
+   "steps":[{"mcp":{"tool":"book","arguments":{"name":"Ada"}},"save":"booking"}],
+   "assertions":[{"result":"booking","contains":{"ok":true}}]},
+  {"id":"open-roles","statement":"Staff AI can ask which roles are still open","role":"staff",
+   "steps":[{"mcp":{"tool":"open_roles"},"save":"open"}],
+   "assertions":[{"result":"open","path":"roles","contains":["cook"]}]}
+]
+```
+
+Use actual tool names, arguments and returned fields from this studio. `save`
+names the returned result; duplicate names fail. `result` reads it. `path` selects
+dot-separated object keys or array indexes, such as `records.0.data.name`.
+`equals` compares the full selected JSON value; `contains` matches a subset of
+object fields, each expected array entry against an actual entry, or a substring.
+`text` checks a string for one substring or every string in an array. Use `{"$result":"booking.id"}` anywhere in a subsequent step or assertion
+to refer to a saved value, without string interpolation. A missing
+result/path, wrong value or malformed assertion stays not met, naming the failed
+condition. Standard studio tool envelopes are unwrapped to their `data` value;
+other tools retain their structured content or MCP result.
+
+## Schedules, records and results
+
+A `schedule` step invokes a named declared scheduled function through the local
+MCP dispatcher, with a simulated timestamp in epoch milliseconds. It runs the
+handler headless and reports handler failures. This is a simulated tick, not
+proof that a deployed cron fired or an external message reached a person. Assert
+the actual resulting record or queue entry; do not just assert the trigger's ID.
+The handler still needs a declared role with the relevant record capabilities.
+
+```needs
+[
+  {"id":"remind","statement":"Daily reminders queue for booked guests","role":"owner",
+   "steps":[{"schedule":{"name":"reminders","at":1800000000000}}],
+   "assertions":[{"role":"staff","records":{"collection":"reminders"},
+                  "contains":{"records":[{"data":{"name":"Ada","state":"queued"}}]}}]},
+  {"id":"results","statement":"Staff can read the completed result","role":"staff",
+   "assertions":[{"records":{"collection":"results","id":"one"},
+                  "contains":{"data":{"status":"complete"}}}]}
+]
+```
+
+`records` uses the real `app_records` read tool, bound to this app, the named role
+and this check's isolation scope. Supply collection and optional ID as accepted by that tool. Use its actual response shape (a single record versus
+a list). Create fixtures with steps before asserting them; fresh runs start empty.
+
+## Owner AI events and webhook handoff
+
+Call `studio_events_read` to prove the feed contains the event, or use MCP Events
+`events/poll` with an explicit cursor to prove event retrieval. `events/list`
+checks discovery. `resources/read` also works and preserves its MCP `contents`
+array. These prove the studio exposes an event to the named role; they do not
+claim an external AI held a live connection or acted on it.
+
+```needs
+[
+  {"id":"owner-feed","statement":"The owner's AI can read new bookings","role":"owner",
+   "steps":[{"mcp":{"tool":"book","arguments":{"name":"Ada"}},"role":"customer"}],
+   "assertions":[{"mcp":{"tool":"studio_events_read","arguments":{"feed":"bookings"}},
+                  "contains":{"events":[{"type":"record.changed","data":{"data":{"name":"Ada"}}}]}}]},
+  {"id":"mcp-events","statement":"Owner AI retrieves booking events through MCP Events","role":"owner",
+   "assertions":[{"mcp":{"method":"events/poll","params":{"name":"bookings","cursor":"v1:bookings:0"}},
+                  "contains":{"events":[{"name":"bookings"}]}}]},
+  {"id":"webhook","statement":"The declared owner webhook accepts a signed test event","role":"owner",
+   "steps":[{"mcp":{"tool":"studio_events_webhook_test","arguments":{"feed":"bookings"}},"save":"delivery"}],
+   "assertions":[{"mcp":{"tool":"studio_events_webhook_status","arguments":{"feed":"bookings"}},
+                  "waitMs":5000,"contains":{"deliveries":[{"event":{"$result":"delivery.id"},"state":"complete"}]}}]}
+]
+```
+
+Declare the feed/audience and webhook first using the existing functions guide.
+The webhook test sends an explicitly synthetic event to the declared receiver;
+match the saved delivery ID to avoid mistaking an older delivery for this test.
+Use `studio_events_webhook_status` for subsequent attempts and errors.
+A status assertion proves the receiver's acknowledgement, not its downstream
+email/SMS or AI work. Read-only MCP/records assertions make one call by default. For asynchronous
+effects, set `waitMs` (0–10000) to re-read until the expected value appears.
+Tool/permission errors fail immediately. Saved results are immutable and are
+never retried. Never put a mutating tool in an assertion; use a step once and
+assert its saved result or durable effect. Unknown methods/tools and denied feeds
+fail explicitly. Secrets do not belong in the needs block.
+
+## Handover files
+
+```needs
+[
+  {"id":"handover","statement":"The owner has AI connection and reminder instructions",
+   "assertions":[{"file":"HANDOVER.md","text":["/mcp","Reminders run daily"]}]}
+]
+```
+
+`file` is relative to the studio root. The file must exist and be readable; `text`
+checks all requested contents. Without `text` it proves only existence/readability.
+Use this for handover instructions and exported text results; use `records` for
+live structured results. Missing files and missing text name the exact failure.
+
+## Keep controls connected during delayed refreshes
+
+Never replace a button under a press. A delayed fetch can finish between pointer
+down and pointer up; replacing the node cancels its click/navigation and loses
+focus. Create interactive nodes once, key repeated items by stable record IDs,
+and update text/attributes in place. Keep pending/disabled state deliberate.
+
+```js
+const choose = document.createElement('button');
+choose.textContent = 'Choose crew';
+choose.addEventListener('click', () => selectRole('crew'));
+controls.append(choose);
+async function refresh() {
+  const { open } = await loadRoles();
+  choose.textContent = `Choose crew (${open} places)`;
+  // Keep this same button connected; do not replace controls.innerHTML here.
+}
+```
+
+The runner can retry a detected stale handle before dispatch; it cannot infer
+that an app silently cancelled a press after dispatch. Both stable DOM updates
+and an assertion on the navigation's outcome are necessary.

package/guides/app/SKILL.md

@@ -100,7 +100,7 @@ The Codex's `needs` fenced block is a JSON array, one entry per need from the re
 
 Steps support `fill`, `select`, `click: true` and `reload: true`; surfaces are `wall`, `phone`, `phone-two`, `tablet`, `kiosk` and `staff` (a tablet viewport). Set a need’s `role` to the declared role to prove. Each assertion names its surface; only the named screens are required. Assertions use a visible selector with optional contained text, or an observed effect. An honestly unavailable capability remains in the block with no assertions and a plain explanation in the prose; check reports it not met. Do not delete, weaken or replace a need to get green. Static needs such as accurate prices may have no action steps. Use semantic attributes on real visible scene elements for testability, never hidden QA-only counters.
 
-Run build and the shared-action check, then the needs step runs on those real browsers. Save captures with `--shots .checks`. The result contains each statement, met/partly/not, the assertion result and captures of all named surfaces; `.studio/checks/<id>-needs.json` drives the Codex's Needs status. Redraw `codex <id>` after checking. Passing a selector assertion is evidence, not a visual judgement: read every capture and perform the full flows as owner and customer using the playtest skill. If the picture fails the words, it is not done even with green assertions.
+Run build and the shared-action check, then the needs step runs on those real browsers. Save captures with `--shots .checks`. The result contains each statement, met/partly/not, the assertion result and available captures of named surfaces; `.studio/checks/<id>-needs.json` drives the Codex's Needs status. Redraw `codex <id>` after checking. Passing a selector assertion is evidence, not a visual judgement: read every capture and perform the full flows as owner and customer using the playtest skill. If the picture fails the words, it is not done even with green assertions.
 
 For staff flows, sign in through the existing local owner link and prove the transition in real Chrome. Keep evidence in the Codex alongside the automated flows. Confirm unauthorized writes are refused and records remain after all screens close. Never call an untested privileged path passed. Before final handover, show the need table with evidence and explicit remaining gaps. If the starter or a board of boxes is still visible, return to the scene design and build it.
 
@@ -252,8 +252,8 @@ a notification or a person heard audio. Observations reset before each need.
 After reloads and rebuilt frames, check waits for online state, completed arrival,
 a hidden loading cover and two frames before assertions/captures. Timeout evidence
 names the surface and selector/effect it awaited. Dialogs are automatically accepted
-and reported. Read retries recover detached frames; dispatched actions are not
-silently repeated. `dev` rebuilds root HTML, CSS and JS as well as source and map
+and reported. Read retries recover detached frames. Click/fill/select retry detached elements by
+re-querying for up to ten seconds; other dispatched action failures are not replayed. `dev` rebuilds root HTML, CSS and JS as well as source and map
 changes. Unavailable sandbox Web Storage uses frame-local memory; use app records
 or `net.prefs` for persistence across reloads.
 
@@ -312,3 +312,19 @@ Issues and grant Notifications Write and Workers Observability Write. Cloudflare
 posts signed events to the client's webhook so new or recurring reliability
 problems reach the AI without polling; Homie hosts nothing for this. See
 [Cloudflare's announcement](https://developers.cloudflare.com/changelog/post/2026-10-13-cloudflare-mcp-events/).
+
+## Every need has a check
+
+Read [NEEDS.md](NEEDS.md) for the complete executable format and examples for UI,
+customer/staff MCP tools, owner event feeds and MCP Events, webhook delivery,
+simulated scheduled functions, records/results and handover files. Keep existing
+UI steps. Headless steps use an explicit named role and the local dev credential;
+assertions check actual returned values and effects. Missing capabilities stay
+not met with their reason. Passing assertions are met even without captures;
+missing evidence names each surface, its error and the `--shots .checks` remedy.
+
+Keep interactive DOM nodes connected across delayed refreshes. Update a button's
+text and attributes in place; never replace a button under a press. The short
+example in NEEDS.md preserves its click listener and focus. A stale-element retry
+helps a replaced handle before dispatch; it cannot recover a silently cancelled
+press. Assert the resulting navigation as well as the button's presence.

package/lib/app-needs.mjs

@@ -1,7 +1,8 @@
-import {waitInApp} from './app-ready.mjs';
+import {actInApp,waitInApp} from './app-ready.mjs';
 /** Opt-in acceptance evidence, sourced from the person's Codex, not starter labels. */
 import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, resolve, relative, isAbsolute } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
 import { createHash } from 'node:crypto';
 
 export function readAppNeeds(root, id) {
@@ -22,30 +23,38 @@ export function readAppNeeds(root, id) {
 }
 
 /** Run real UI actions. A failed or absent flow stays visible; continue collecting other needs. */
-export async function proveAppNeeds({ plan, surfaces, shots, report, ready = async () => {} }) {
+export async function proveAppNeeds({ plan, surfaces, shots, report, ready = async () => {}, root, headless }) {
   const results = [];
   const appBarrier=ready;
-  ready=async s=>{await s.page.bringToFront?.();if(s.external){s.frame=s.page.mainFrame();return;}await appBarrier(s);};
+  ready=async (s,options)=>{await s.page.bringToFront?.();if(s.external){s.frame=s.page.mainFrame();return;}await appBarrier(s,options);};
   let activeRole;
   const surface = name => { const s = surfaces.find(s => s.name === name && (!activeRole || s.role === activeRole)) ?? surfaces.find(s => s.name === name); if (!s) throw new Error(`unknown surface ${name}`); return s; };
   for (const need of plan.needs) {
     activeRole = need.role;
-    const names = [...new Set([...(need.steps ?? []), ...(need.assertions ?? [])].map(s => s.surface))];
+    const names = [...new Set([...(need.steps ?? []), ...(need.assertions ?? [])].map(s => s.surface).filter(Boolean))];
+    const saved = new Map();
+    const run = async item => { if (!headless) throw new Error('headless MCP proof requires local dev and its test credential'); return headless(item,item.role ?? need.role); };
     let waiting = 'validating assertions';
     const result = { id: need.id, statement: need.statement, status: 'not', captures: [] };
     try {
-      if (!Array.isArray(need.assertions) || !need.assertions.length) throw new Error('need requires assertions on its named surfaces');
+      if (!Array.isArray(need.assertions) || !need.assertions.length) throw new Error('need requires at least one assertion (UI, result, records or file)');
       const popupNames=new Set((need.steps??[]).map(s=>s.popup).filter(Boolean));
       for (const name of names) { if(popupNames.has(name))continue; const s = surface(name); if (need.role && s.role !== need.role) throw new Error(`${name} requires role ${need.role}, got ${s.role ?? 'unspecified'}`); }
       for (const name of new Set(need.assertions.filter(a => a.effect).map(a => a.surface))) await surface(name).frame.evaluate(() => { window.__homieNeedsEffects = []; });
-      for (const step of need.steps ?? []) {
+      for (const rawStep of need.steps ?? []) {
+        const step=resolveNeedResults(rawStep,saved);
+        if (step.mcp || step.schedule) {
+          waiting = step.mcp ? `MCP ${step.mcp.tool ?? step.mcp.method} as ${step.role ?? need.role ?? 'unspecified'}` : `schedule ${step.schedule.name}`;
+          const value = await run(step);
+          if (step.save) { if(saved.has(step.save))throw new Error(`duplicate saved result ${step.save}`); saved.set(step.save,value); }
+          continue;
+        }
         const target=surface(step.surface);
         if(!step.reload)await ready(target);
         const { page } = target;
         waiting = `${step.surface}: ${step.reload ? 'reload and arrival readiness' : step.selector}`;
         if (step.reload) { await page.reload({ waitUntil: 'domcontentloaded' }); await ready(surface(step.surface)); continue; }
-        await waitInApp(target,step.selector,f=>f.waitForSelector(step.selector, { visible: true, timeout:10000 }),{ready});
-        const frame=target.frame;
+        const act = fn => actInApp(target,step.selector,fn,{ready});
         if (step.click && step.popup) {
           let listener,timer;
           const opened=new Promise((resolve,reject)=>{
@@ -53,17 +62,42 @@ export async function proveAppNeeds({ plan, surfaces, shots, report, ready = asy
             timer=setTimeout(()=>reject(new Error('payment popup did not open')),10000);
           });
           try {
-            const [popup]=await Promise.all([opened,frame.click(step.selector)]);
+            const [popup]=await Promise.all([opened,act(frame=>frame.click(step.selector))]);
             surfaces.push({name:step.popup,page:popup,frame:popup.mainFrame(),external:true,role:target.role});
             await page.bringToFront();
           } finally {clearTimeout(timer);page.off('popup',listener);}
         }
-        else if (step.click) {await frame.click(step.selector);await page.bringToFront?.();}
-        else if (step.fill !== undefined) { await frame.$eval(step.selector, el => { el.value = ''; el.dispatchEvent(new Event('input', { bubbles: true })); }); await frame.type(step.selector, String(step.fill)); }
-        else if (step.select !== undefined) await frame.select(step.selector, String(step.select));
+        else if (step.click) {await act(frame=>frame.click(step.selector));await page.bringToFront?.();}
+        else if (step.fill !== undefined) { await act(async frame=>{ await frame.$eval(step.selector, el => { el.value = ''; el.dispatchEvent(new Event('input', { bubbles: true })); }); await frame.type(step.selector, String(step.fill)); }); }
+        else if (step.select !== undefined) await act(frame=>frame.select(step.selector, String(step.select)));
         else throw new Error('step needs click, fill, select or reload');
       }
-      for (const assertion of need.assertions) {
+      for (const rawAssertion of need.assertions) {
+        const assertion=resolveNeedResults(rawAssertion,saved);
+        if (assertion.result || assertion.records || assertion.file || assertion.mcp) {
+          waiting = assertion.file ? `file ${assertion.file}` : assertion.result ? `result ${assertion.result}${assertion.path ? '.'+assertion.path : ''}` : assertion.records ? `records ${assertion.records.collection}` : `MCP ${assertion.mcp.tool ?? assertion.mcp.method}`;
+          let value;
+          if (assertion.file) {
+            if (!root) throw new Error('file proof requires the studio root');
+            const file=resolve(root,assertion.file), rel=relative(resolve(root),file);
+            if(rel.startsWith('..') || isAbsolute(rel))throw new Error('handover file must be inside the studio');
+            value=readFileSync(file,'utf8');
+          } else if (assertion.result) {
+            if(!saved.has(assertion.result))throw new Error(`no saved result ${assertion.result}; add save to its step`);
+            value=saved.get(assertion.result);
+          } else {
+            const waitMs=assertion.waitMs??0;
+            if(!Number.isInteger(waitMs)||waitMs<0||waitMs>10000)throw new Error('waitMs must be an integer from 0 to 10000');
+            const end=Date.now()+waitMs;
+            for(;;) {
+              value=await run(assertion);
+              try {assertNeedValue(value,assertion);break;}
+              catch(error){if(Date.now()>=end)throw error;await new Promise(resolve=>setTimeout(resolve,100));}
+            }
+          }
+          assertNeedValue(value,assertion);
+          continue;
+        }
         waiting = `${assertion.surface}: ${assertion.effect ? assertion.effect + ' ' + (assertion.name ?? '') : assertion.selector + (assertion.text === undefined ? '' : ' containing ' + JSON.stringify(assertion.text))}`;
         const target=surface(assertion.surface);
         await ready(target);
@@ -77,13 +111,14 @@ export async function proveAppNeeds({ plan, surfaces, shots, report, ready = asy
         if (assertion.text !== undefined) await frame.waitForFunction((selector, text) => document.querySelector(selector)?.textContent.includes(text), { timeout: 10000 }, assertion.selector, String(assertion.text));
         },{ready});
       }
-      result.status = shots ? 'met' : 'partly';
-      result.why = shots ? 'UI assertions passed; inspect captures against the pictured scene' : 'Assertions passed but no captures saved';
+      result.status = 'met';
+      result.why = 'Assertions passed';
     } catch (error) { result.why = `Waiting for ${waiting}: ${error.message}`; }
+    if (!shots) for (const name of names) result.why += `; ${name} capture not requested: rerun check with --shots .checks and inspect the scene`;
     if (shots) for (const name of names) {
       const file = join(shots, `${need.id}-${name}.jpg`);
-      try { await ready(surface(name)); await surface(name).page.screenshot({ path: file, type: 'jpeg', quality: 85 }); result.captures.push(file); }
-      catch (error) { if (result.status === 'met') result.status = 'partly'; result.why += `; capture failed: ${error.message}`; }
+      try { mkdirSync(shots,{recursive:true}); await ready(surface(name)); await surface(name).page.screenshot({ path: file, type: 'jpeg', quality: 85 }); result.captures.push(file); }
+      catch (error) { result.why += `; ${name} capture failed: ${error.message}. Resolve this capture error and rerun check with --shots .checks`;  }
     }
     report?.check?.(`need-${need.id}`, result.status === 'met' ? 'pass' : 'fail', { label: need.statement, note: result.why });
     results.push(result);
@@ -96,3 +131,36 @@ export function saveAppNeeds(root, id, plan, needs) {
   const dir = join(root, '.studio', 'checks'); mkdirSync(dir, { recursive: true });
   writeFileSync(join(dir, `${id}-needs.json`), JSON.stringify({ at: new Date().toISOString(), codexHash: plan.hash, needs }, null, 2));
 }
+
+/** Partial structured matching: object keys must match; each expected array entry must occur. */
+export function containsValue(actual, expected) {
+  if (typeof expected === 'string') return typeof actual === 'string' && actual.includes(expected);
+  if (Array.isArray(expected)) return Array.isArray(actual) && expected.every(e=>actual.some(a=>containsValue(a,e)));
+  if (expected && typeof expected === 'object') return actual !== null && typeof actual === 'object' && Object.entries(expected).every(([k,v])=>Object.hasOwn(actual,k)&&containsValue(actual[k],v));
+  return isDeepStrictEqual(actual,expected);
+}
+export function assertNeedValue(value, assertion) {
+  if(assertion.path) for(const key of assertion.path.split('.')) value=value!=null&&Object.hasOwn(Object(value),key)?value[key]:undefined;
+  if(value === undefined)throw new Error('value does not exist');
+  if(Object.hasOwn(assertion,'equals')&&!isDeepStrictEqual(value,assertion.equals))throw new Error(`expected equals ${JSON.stringify(assertion.equals)}; got ${JSON.stringify(value)}`);
+  if(Object.hasOwn(assertion,'contains')&&!containsValue(value,assertion.contains))throw new Error(`expected contains ${JSON.stringify(assertion.contains)}; got ${JSON.stringify(value)}`);
+  if(assertion.text!==undefined)for(const text of [].concat(assertion.text))if(typeof value!=='string'||!value.includes(String(text)))throw new Error(`expected text ${JSON.stringify(text)}`);
+  if(!assertion.file&&!Object.hasOwn(assertion,'equals')&&!Object.hasOwn(assertion,'contains')&&assertion.text===undefined)throw new Error('result/records assertion requires equals, contains or text');
+}
+
+/** Explicit result references never evaluate code or interpolate arbitrary strings. */
+export function resolveNeedResults(value,saved) {
+  if(Array.isArray(value))return value.map(v=>resolveNeedResults(v,saved));
+  if(value && typeof value==='object') {
+    if(Object.keys(value).length===1 && typeof value.$result==='string') {
+      const [name,...path]=value.$result.split('.');
+      if(!saved.has(name))throw new Error(`no saved result ${name}`);
+      let result=saved.get(name);
+      for(const key of path)result=result!=null&&Object.hasOwn(Object(result),key)?result[key]:undefined;
+      if(result===undefined)throw new Error(`saved result path ${value.$result} does not exist`);
+      return result;
+    }
+    return Object.fromEntries(Object.entries(value).map(([key,v])=>[key,resolveNeedResults(v,saved)]));
+  }
+  return value;
+}

package/lib/app-ready.mjs

@@ -48,3 +48,24 @@ export function answerDialogs(page,surface,dialogs,report) {
   await dialog.accept().catch(()=>{});
  });
 }
+
+/** Retry only errors identifying a detached element, never an ambiguous navigation after dispatch. */
+export async function actInApp(surface, selector, action, {ready=appReady,timeout=10000}={}) {
+  const end=Date.now()+timeout;
+  let stale;
+  for (;;) {
+    try {
+      await waitInApp(surface,selector,frame=>frame.waitForSelector(selector,{visible:true,timeout:Math.max(1,end-Date.now())}),{ready,timeout:Math.max(1,end-Date.now())});
+      return await action(surface.frame);
+    } catch(error) {
+      if(!/node is detached|element.*(?:detach|stale)|stale.*element/i.test(error.message)) {
+        if(stale && Date.now()>=end)throw new Error(`${surface.name}: stale element ${selector} never settled within ${timeout}ms: ${error.message}`);
+        throw error;
+      }
+      stale=error;
+      if(Date.now()>=end)throw new Error(`${surface.name}: stale element ${selector} never settled within ${timeout}ms: ${error.message}`);
+      await new Promise(resolve=>setTimeout(resolve,Math.min(50,Math.max(1,end-Date.now()))));
+      await ready(surface,{timeout:Math.max(1,end-Date.now())});
+    }
+  }
+}

package/lib/check.mjs

@@ -1,5 +1,6 @@
+import {needsHeadless} from './needs-headless.mjs';
 import {randomBytes} from 'node:crypto';
-import {appReady,observeEffects,waitInApp,answerDialogs} from './app-ready.mjs';
+import {actInApp,appReady,observeEffects,waitInApp,answerDialogs} from './app-ready.mjs';
 import {localCredential,localCookie} from './local-test.mjs';
 import { readAppNeeds, proveAppNeeds, saveAppNeeds } from './app-needs.mjs';
 /**
@@ -148,6 +149,12 @@ export async function check({ isolate = true, root = null, url, game, roundTimeo
     if (meta?.rulesError) return { ok: false, command: 'check', why: meta.rulesError };
     if (meta?.kind === 'app') appMeta = meta;
   } catch { /* browser preflight below still names failures */ }
+  if(appMeta && !appMeta.check?.action) {
+    try {
+      const plan=readAppNeeds(root,game);
+      if(plan && !plan.needs.some(n=>[...(n.steps??[]),...(n.assertions??[])].some(i=>i.surface)))return checkApp({isolate,root,url:base,game,meta:appMeta,shots,log,report});
+    } catch(error) {return {ok:false,command:'check',kind:'app',why:error.message};}
+  }
   const chrome = findChrome();
   if (!chrome) return { ok: false, command: 'check', why: noChrome() };
   let puppeteer;
@@ -357,13 +364,13 @@ export async function checkApp({ isolate = true, root = null, url, game, meta, s
   const proof = meta.check??{};
   const baseline=typeof proof.action==='string'&&typeof proof.observe==='string';
   if (!baseline && !plan) return { ok: false, command: 'check', kind: 'app', why: 'app.json check needs action and observe CSS selectors for a real shared action' };
-  if (shots) mkdirSync(shots, { recursive: true });
+  const captureWarnings=[];
   const profile = mkdtempSync(join(tmpdir(), 'homie-app-check-'));
   let browser;
   const surfaces = [];
   const room = `check-${randomBytes(10).toString('hex')}`;
   try {
-    browser = await puppeteer.launch({ executablePath: chrome, headless: true, userDataDir: profile, timeout: LAUNCH_TIMEOUT_MS, args: chromeArgs() });
+    if(baseline || plan?.needs.some(n=>[...(n.steps??[]),...(n.assertions??[])].some(i=>i.surface))) browser = await puppeteer.launch({ executablePath: chrome, headless: true, userDataDir: profile, timeout: LAUNCH_TIMEOUT_MS, args: chromeArgs() });
     const openSurface = async (name, role) => {
       const dimensions={wall:[1280,720],phone:[390,844],'phone-two':[390,844],tablet:[1024,768],staff:[1024,768],kiosk:[1080,1920]};
       if(!dimensions[name])throw new Error(`Unknown needs surface ${name}`);
@@ -390,7 +397,7 @@ export async function checkApp({ isolate = true, root = null, url, game, meta, s
     await appReady(actor);
     await waitInApp(actor,proof.action,f=>f.waitForFunction((selector) => { const el = document.querySelector(selector); return el && !el.disabled && !el.hidden; }, {}, proof.action));
     before = await waitInApp(actor,proof.observe,textOf);
-    await actor.frame.click(proof.action);
+    await actInApp(actor,proof.action,f=>f.click(proof.action));
     await waitInApp(actor,proof.observe+' changes after action',f=>f.waitForFunction((selector, was) => document.querySelector(selector)?.textContent !== was, {}, proof.observe, before));
     after = await waitInApp(actor,proof.observe,textOf);
     for (const s of surfaces) await waitInApp(s,proof.observe+' equals '+after,f=>f.waitForFunction((selector, wanted) => document.querySelector(selector)?.textContent === wanted, {}, proof.observe, after));
@@ -402,19 +409,21 @@ export async function checkApp({ isolate = true, root = null, url, game, meta, s
     if (rooms.some((r) => r !== room)) throw new Error('surfaces did not retain the same room');
     for (const s of surfaces) {
       await appReady(s);
-      if (shots) await s.page.screenshot({ path: join(shots, `${s.name}.jpg`), type: 'jpeg', quality: 85 });
+      if (shots) try {mkdirSync(shots,{recursive:true});await s.page.screenshot({ path: join(shots, `${s.name}.jpg`), type: 'jpeg', quality: 85 });}
+      catch(error){const warning=`${s.name} capture failed: ${error.message}. Resolve this capture error and rerun check with --shots .checks`;captureWarnings.push(warning);log(warning);}
     }
     report?.check?.('app-action', 'pass', { note: 'action reached wall and both phones; reconnect retained it' });
     }
     for(const need of plan?.needs??[])for(const item of [...(need.steps??[]),...(need.assertions??[])]) {
+      if(!item.surface)continue;
       if(plan.needs.some(n=>(n.steps??[]).some(s=>s.popup===item.surface)))continue;
       const role=item.role??need.role??meta.surfaces?.[item.surface]??(item.surface==='staff'?'staff':undefined);
       if(!surfaces.some(s=>s.name===item.surface&&s.role===role))await openSurface(item.surface,role);
     }
-    const needs = plan ? await proveAppNeeds({ plan, surfaces, shots, report, ready:appReady }) : null;
+    const needs = plan ? await proveAppNeeds({ plan, surfaces, shots, report, ready:appReady, root, headless:needsHeadless({url,secret,app:game,meta,scope:isolate?room:null}) }) : null;
     if (plan) { saveAppNeeds(root, game, plan, needs); const { refreshCodexFile } = await import('./codex.mjs'); refreshCodexFile(root, game); }
     const ok = !needs || needs.every(n => n.status === 'met');
-    return { ok, ...(needs ? { needs, why: ok ? undefined : 'Some needs from the person’s Codex are not yet met; see needs and captures' } : {}), command: 'check', kind: 'app', isolatedRecords:isolate, dialogs, room, surfaces: surfaces.map((s) => s.name), action: proof.action, before, after, reconnect: baseline };
+    return { ok, ...(needs ? { needs, why: ok ? undefined : 'Some needs from the person’s Codex are not yet met; see needs and captures' } : {}), command: 'check', kind: 'app', isolatedRecords:isolate, captureWarnings, dialogs, room, surfaces: surfaces.map((s) => s.name), action: proof.action, before, after, reconnect: baseline };
   } catch (error) { return { ok: false, command: 'check', kind: 'app', dialogs, why: error.message }; }
   finally { await browser?.close().catch(() => {}); rmSync(profile, { recursive: true, force: true }); }
 }

package/lib/codex.mjs

@@ -318,7 +318,7 @@ function sectionHtml(section, emb, ctx) {
     if (block) {
       try {
         const needs = JSON.parse(block[1]);
-        if (Array.isArray(needs)) return `<section class="tab" id="${esc(section.id)}" data-key="needs"><h2>${esc(section.title)}</h2>${renderMarkdown(source.replace(block[0], '')).html}<div class="cards">${needs.map(n => `<article class="card"><h3>${esc(n.id)}</h3><p>${esc(n.statement)}</p><p class="meta">${Array.isArray(n.assertions) && n.assertions.length ? 'To demonstrate on the wall and phone' : 'Not yet demonstrable'}</p></article>`).join('')}</div></section>`;
+        if (Array.isArray(needs)) return `<section class="tab" id="${esc(section.id)}" data-key="needs"><h2>${esc(section.title)}</h2>${renderMarkdown(source.replace(block[0], '')).html}<div class="cards">${needs.map(n => `<article class="card"><h3>${esc(n.id)}</h3><p>${esc(n.statement)}</p><p class="meta">${Array.isArray(n.assertions) && n.assertions.length ? 'To demonstrate with check' : 'Not yet demonstrable'}</p></article>`).join('')}</div></section>`;
       } catch { /* Keep malformed source visible for correction. */ }
     }
   }
@@ -582,7 +582,7 @@ export function renderCodex(root, id, { mode = 'file', feed, now = new Date() }
       const r = JSON.parse(readFileSync(needReportFile, 'utf8'));
       const stale = r.codexHash !== createHash('sha256').update(readFileSync(file, 'utf8')).digest('hex');
       tabs.push('<a href="#needs-status">Needs status</a>');
-      needStatus = `<section class="tab" id="needs-status"><h2>Needs status</h2><p>${stale ? 'Plan changed: this evidence is stale; check again. ' : ''}Checked ${esc(r.at)}. Screen assertions are evidence; review the captures against Their words.</p>${r.needs.map(n => `<article><h3>${esc(n.statement)}</h3><p><strong>${stale ? 'not yet rechecked' : esc(n.status)}</strong> — ${esc(n.why ?? '')}</p>${(n.captures ?? []).map(p => figure(emb, n.statement, relative(root, resolve(root, p)), p)).join('')}</article>`).join('')}</section>`;
+      needStatus = `<section class="tab" id="needs-status"><h2>Needs status</h2><p>${stale ? 'Plan changed: this evidence is stale; check again. ' : ''}Checked ${esc(r.at)}. Assertions are evidence; review available captures against Their words.</p>${r.needs.map(n => `<article><h3>${esc(n.statement)}</h3><p><strong>${stale ? 'not yet rechecked' : esc(n.status)}</strong> — ${esc(n.why ?? '')}</p>${(n.captures ?? []).map(p => figure(emb, n.statement, relative(root, resolve(root, p)), p)).join('')}</article>`).join('')}</section>`;
     } catch { /* The next check repairs an incomplete receipt. */ }
   }
   const body = needStatus + sections.map((x) => sectionHtml(x, emb, ctx)).join('\n');
@@ -772,9 +772,11 @@ try: "Open the wall and phone. Follow a real request through the scene."
 <!-- What is sold or given, price and currency, once/monthly, and what payment fulfils. -->
 
 ## Needs
-<!-- Each statement is observable on a real screen. Fill this executable needs block.
-Each need: id, statement, steps (surface wall/phone/phone-two; click/fill/select and selector/value),
-assertions (surface, selector, optional text). Include wall and phone assertions and real flow steps.
+<!-- Each owner statement belongs in this executable needs block.
+Each need: id, statement, optional role, steps and assertions. UI: surface/selector with
+click/fill/select/reload; headless: mcp tool/arguments + save, or schedule name/at.
+Assert UI selectors, saved result/path/equals/contains, records, or file/text.
+See node_modules/@homie-rocks/studio/guides/app/NEEDS.md for complete examples.
 A missing flow is reported not met. Do not replace an unmet need with an easier one. -->
 \`\`\`needs
 []

package/lib/needs-headless.mjs

@@ -0,0 +1,34 @@
+import {localCookie} from './local-test.mjs';
+
+/** Each action has an explicit local identity, using the real MCP transport and permissions. */
+export function needsHeadless({url,secret,app,meta,scope}) {
+  return async (item,role) => {
+    if(!secret)throw new Error('Headless role proof requires homie-studio dev in this studio and its localhost URL');
+    if(!role || (role!=='owner'&&!Object.hasOwn(meta.roles??{},role)))throw new Error(`Name a declared role (or owner) for headless proof; got ${role??'none'}`);
+    const {Client,StreamableHTTPClientTransport}=await import('mcp-studio-client');
+    const client=new Client({name:'Homie needs check',version:'1.0.0'});
+    const transport=new StreamableHTTPClientTransport(new URL('/mcp',url),{requestInit:{headers:{authorization:`Bearer ${secret}`,cookie:`homie_test=${localCookie(secret,{app,role,scope})}`}}});
+    try {
+      await client.connect(transport);
+      let call=item.mcp;
+      if(item.records)call={tool:'app_records',arguments:{...item.records,app,role,operation:'read'}};
+      if(item.schedule)call={tool:'studio_schedule_fire',arguments:item.schedule};
+      if(call?.method) {
+        if(call.method==='resources/read')return await client.readResource(call.params);
+        // The extension's JSON-RPC result is intentionally preserved for path assertions.
+        if(['events/list','events/poll'].includes(call.method)) {
+          const {z}=await import('zod');
+          return await client.request({method:call.method,params:call.params??{}},z.object({}).passthrough(),{timeout:10000});
+        }
+        throw new Error(`Unsupported MCP proof method ${call.method}; use tools, resources/read, events/list or events/poll`);
+      }
+      if(!call?.tool)throw new Error('MCP step requires tool and optional arguments');
+      const result=await client.callTool({name:call.tool,arguments:call.arguments??{}},undefined,{timeout:item.schedule?15000:10000});
+      if(result.isError)throw new Error(result.content?.filter(c=>c.type==='text').map(c=>c.text).join('; ')||'MCP tool failed');
+      if(result.structuredContent!==undefined)return result.structuredContent;
+      const content=result.content?.filter(c=>c.type==='text');
+      if(content?.length===1) {try {const parsed=JSON.parse(content[0].text);return parsed.kind==='untrusted-tool-data'?parsed.data:parsed;}catch{}}
+      return result;
+    } finally {await client.close();}
+  };
+}

package/lib/shop-links.mjs

@@ -78,7 +78,7 @@ export async function reconcilePaymentLinks({ api, shop, slug, site, mode, booki
   const menuItems = shop.items.filter(i => typeof i.price === 'number' && i.price > 0 && !i.interval);
   const metadata = { homie: 'shop-links-v1', studio: slug, origin: site };
   const groups=Map.groupBy(menuItems,i=>i.game??'');
-  for(const group of groups.values()) for (let offset = 0; offset < group.length; offset += 10) {
+  for(const group of (shop.basket ? [] : groups.values())) for (let offset = 0; offset < group.length; offset += 10) {
     const items = group.slice(offset, offset + 10);
     if (items.length < 2) continue;
     const params = { ...customText, line_items: items.map(i => ({price:catalogPrices.get(i.id),quantity:1,adjustable_quantity:{enabled:true,minimum:0,maximum:shop.policy.repeatPurchases?999999:1}})),
@@ -93,6 +93,32 @@ export async function reconcilePaymentLinks({ api, shop, slug, site, mode, booki
     keepLinks.add(link.id);
     config.menus.push({id:link.id,url:link.url,revision,items:items.map(i=>({item:i.id,price:catalogPrices.get(i.id)}))});
   }
+  // One aggregate payment represents a frozen local basket, including one-item baskets.
+  // Runtime uses prefilled_amount, never a shared Price mutation: concurrent
+  // guests must receive their own saved totals.
+  if(shop.basket) for(const [game,items] of groups) {
+    const id=await productIdOf(slug,`basket-${game||'shop'}`);
+    keepProducts.add(id);
+    const fields={name:shop.basket.name,description:shop.basket.description,metadata,active:true};
+    const product=products.find(p=>p.id===id);
+    if(!product)await api('POST','/v1/products',{id,...fields},`product-${hash(id)}`);
+    else if(product.name!==fields.name || product.description!==fields.description || !product.active)await api('POST',`/v1/products/${id}`,fields);
+    const priceFields={product:id,currency:shop.currency,custom_unit_amount:{enabled:true},tax_behavior:'inclusive'};
+    const priceRevision=hash(priceFields);
+    let price=prices.find(p=>own(p)&&p.product===id&&p.metadata?.revision===priceRevision);
+    if(!price)price=await api('POST','/v1/prices',{...priceFields,metadata:{...metadata,revision:priceRevision}},`price-${hash({priceFields,metadata})}`);
+    if(!price.active)await api('POST',`/v1/prices/${price.id}`,{active:true});
+    keepPrices.add(price.id);
+    const params={line_items:[{price:price.id,quantity:1}],automatic_tax:{enabled:false},payment_intent_data:{metadata},
+      after_completion:{type:'redirect',redirect:{url:`${site}/shop/thanks?session_id={CHECKOUT_SESSION_ID}`}}};
+    const revision=hash(params);
+    let link=links.find(p=>own(p)&&p.metadata?.revision===revision);
+    if(!link)link=await api('POST','/v1/payment_links',{...params,metadata:{...metadata,revision}},`basket-${revision}`);
+    if(!link.active)await api('POST',`/v1/payment_links/${link.id}`,{active:true});
+    if(!paymentLinkURL(link.url))throw new Error('Invalid basket Payment Link');
+    keepLinks.add(link.id);
+    config.menus.push({id:link.id,url:link.url,revision,price:price.id,basket:true,items:items.map(i=>({item:i.id,price:catalogPrices.get(i.id)}))});
+  }
   config.slots=[];
   const pause=async link=>{
     if(link.active) await api('POST',`/v1/payment_links/${link.id}`,{active:false});

package/lib/template-history.json

@@ -3753,6 +3753,48 @@
      }
     }
    }
+  },
+  "0.51.6": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "29337e2ace95b2e7",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "1dbdf22c03a1e505",
+    "site/src/worker.mjs": "6cc5c6131eaf6fd0"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "394cbbe934e80722",
+     "## Version-matched authoring guides": "f6261a0e5801b96b",
+     "## Layout": "f3a280b8c96cd068",
+     "## Apps: one screen, roles and parts": "c10aa0441ea89702",
+     "## Commands (all through the pinned CLI in node_modules)": "c20d90de21cde0c7",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "bb715272fd1a615b",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "1ccfd549d2369a60",
+     "## Selling things (the shop)": "0df5a5fe1833c624",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "b2234d80f6cbe71d",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "8364e05cebefcba4"
+      }
+     }
+    }
+   }
   }
  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.51.5",
+  "version": "0.51.6",
   "description": "A studio for games, music and video on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects and D1, all on the free Workers plan, no payment method), a site with the hub's sections (Home, Games, Music, Videos, Rooms, Posts with feeds) in the studio's own look, an epic landing page for every game, big songs and videos in the studio's own R2 once it has storage (uploaded, checked by SHA-256, served at the same addresses), deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",

package/shop/SHOP.md

@@ -371,3 +371,47 @@ dev bindings and disposable studios when finished.
 See `apps/APPS.md`, “Real Stripe test checkout on this computer”, for the supported
 `shop connect --local` and Stripe CLI forwarding recipe. Every paid monthly cycle
 creates a paid order and `order.paid` with the subscription’s original app reference.
+
+## Preserve a local basket with keyless checkout
+
+For a venue that wants the phone's exact items and quantities, opt into a saved
+basket in `shop.json` before syncing Payment Links:
+
+```json
+"basket": {
+  "name": "Round for your table",
+  "description": "Enter the total shown on your pub basket. Any shortfall is settled at the bar."
+}
+```
+
+Use Stripe (`till: "stripe"`) and tax-inclusive menu prices (`automaticTax: false`).
+Sync creates one custom-amount Price and Payment Link per app, with one line and
+quantity one. `shop.checkout({reference: "table-7"})` saves the validated basket
+lines, quantities, total and reference in the studio's D1 before opening Stripe.
+Even a basket containing only one item keeps its exact quantity. The opaque order
+ID travels as `client_reference_id`; no Stripe API key or Homie payment relay is
+used by the Worker. Existing menus without `basket` retain their behavior.
+
+The link prefills the saved total using Stripe's documented
+[`prefilled_amount`](https://docs.stripe.com/payment-links/customize#customize-checkout-with-url-parameters)
+in minor currency units. The guest can edit it, so a preset is never payment proof.
+[`custom_unit_amount.preset`](https://docs.stripe.com/api/prices/create?query=custom_unit_amount)
+is the Price-level fallback, not a per-buyer setting. Never mutate that shared Price
+at checkout: concurrent baskets would race. Both the Price fallback and the URL
+override were verified in the Homie sandbox. Invalid overrides fall back to the
+stored preset or an empty amount; keep the expected total visible on the phone.
+
+After a signed paid session matches the frozen link, revision, mode, currency and
+order reference, `order.paid` contains the **saved basket lines**, `amount` (actual
+payment), `basketTotal` (expected total), and `settlement` (`paid` or `short`).
+Line `amount` is the saved extended amount (unit price × quantity); line `total`
+is its proportionally allocated share of the actual aggregate payment for refunds.
+A short payment emits the event so staff can resolve it, but grants no automatic
+entitlements. Apps must compare the actual payment with `basketTotal`, show a
+shortfall explicitly, and deduplicate by order ID. More than the total is paid.
+Reopening and paying the link creates another order for the same frozen basket;
+repeated delivery of the same session never creates another round.
+
+The Stripe heading is the connected Stripe account's business name. A sandbox
+account named “Homie sandbox” shows that name; a real pub's account shows the pub's
+name. The basket's product name and description use the pub's own wording.

package/worker/app-records.mjs

@@ -47,6 +47,7 @@ export async function appAccess(request, env, meta, url) {
   const caller = toolIdentity(request);
   if (caller) {
     if (caller.owner) return { ok: true, role, can: declared.can };
+    if(env.HOMIE_LOCAL_TEST_SECRET && caller.localTest && caller.roles?.[meta.id]?.includes(role))return {ok:true,role,can:declared.can};
     if (!caller.id) return { ok: false, status: 401, error: 'sign in to this studio' };
     const grant = await env.DB.prepare("SELECT player FROM app_roles WHERE app IN (?1, '*') AND role = ?2 AND player = ?3").bind(meta.id, role, caller.id).first();
     return grant ? { ok: true, role, can: declared.can } : { ok: false, status: 403, error: 'this account has no role grant' };

package/worker/build-id.mjs

@@ -1,2 +1,2 @@
 // Generated by lib/build-identity.mjs; identifies the bundled runtime sources.
-export const STUDIO_BUILD = Object.freeze({"version":"0.51.5","sha256":"1e11f3b33959ff475ed31b5e5e0b5b4e7a155be104d47db80901422409830b23"});
+export const STUDIO_BUILD = Object.freeze({"version":"0.51.6","sha256":"035298d6bd38bab86e0471ea08819786995a53cedb8da961b595506e5403b410"});

package/worker/event-resources.mjs

@@ -25,10 +25,16 @@ export async function readableFeed(env,cat,caller,name) {
   // Non-record events have no app read capability; they remain owner-only.
   return caller.owner===true;
 }
-export async function feedEvents(env,name,{after=0,through=Number.MAX_SAFE_INTEGER}={}) {
+export async function feedEvents(env,name,{after=0,through=Number.MAX_SAFE_INTEGER,caller}={}) {
   const feed=eventFeeds(env)[name];if(!feed)return [];
-  const rows=(await env.DB.prepare('SELECT seq,id,type,data,at FROM studio_events WHERE type=?1 AND seq>?2 AND seq<=?3 ORDER BY seq LIMIT 100').bind(feed.event,after,through).all()).results;
-  return rows.map(r=>({...r,data:JSON.parse(r.data)}));
+  const scopedApp=env.HOMIE_LOCAL_TEST_SECRET&&caller?.localTest&&caller.testScope&&feed.event==='record.changed'?`${feed.app}:check:${caller.testScope}`:null;
+  const rows=(await env.DB.prepare("SELECT seq,id,type,data,at FROM studio_events WHERE type=?1 AND seq>?2 AND seq<=?3 AND (?4 IS NULL OR json_extract(data,'$.app')=?4) ORDER BY seq LIMIT 100").bind(feed.event,after,through,scopedApp).all()).results;
+  const events=rows.map(r=>({...r,data:JSON.parse(r.data)}));
+  if(env.HOMIE_LOCAL_TEST_SECRET && caller?.localTest && caller.testScope && feed.event==='record.changed') {
+    const app=`${feed.app}:check:${caller.testScope}`;
+    return events.filter(e=>e.data.app===app).map(e=>({...e,data:{...e.data,app:feed.app}}));
+  }
+  return events;
 }
 export function matchesFeed(feed,event) {
   return feed.event===event.type && (feed.event!=='record.changed'||(event.data.app===feed.app&&event.data.collection===feed.collection));

package/worker/local-test.mjs

@@ -2,6 +2,10 @@
 const local = (request, env) => env.HOMIE_LOCAL_TEST_SECRET && ['localhost','127.0.0.1','[::1]'].includes(new URL(request.url).hostname);
 export async function localCaller(request, env) {
   if (!local(request, env) || request.headers.get('authorization') !== `Bearer ${env.HOMIE_LOCAL_TEST_SECRET}`) return null;
+  const session=await localSession(request,env);
+  // A supplied but invalid signed session must never fall back to owner.
+  if(request.headers.get('cookie')?.includes('homie_test=')&&!session)return null;
+  if(session)return {id:`local-test-${session.app}-${session.role}`,owner:session.role==='owner',client:null,localTest:true,roles:{[session.app]:[session.role]},testApp:session.app,testScope:session.scope??null};
   return {id:'local-test-owner',owner:true,client:null};
 }
 export async function localSession(request, env) {

package/worker/mcp-events.mjs

@@ -41,9 +41,9 @@ export async function pollEvents(env,cat,caller,params,now=Date.now()){
   const rows=(await env.DB.prepare(`SELECT seq,id,type,data,at FROM studio_events
     WHERE type=?1 AND seq>?2 AND seq<=?3
       AND (?4 IS NULL OR (json_extract(data,'$.app')=?4 AND json_extract(data,'$.collection')=?5))
-    ORDER BY seq LIMIT ?6`).bind(feed.event,start.after,start.through,feed.event==='record.changed'?feed.app:null,feed.collection??null,max+1).all()).results;
+    ORDER BY seq LIMIT ?6`).bind(feed.event,start.after,start.through,feed.event==='record.changed'?(env.HOMIE_LOCAL_TEST_SECRET&&caller.localTest&&caller.testScope?`${feed.app}:check:${caller.testScope}`:feed.app):null,feed.collection??null,max+1).all()).results;
   const hasMore=rows.length>max,page=rows.slice(0,max);
-  const events=page.map(row=>occurrence(params.name,{...row,data:JSON.parse(row.data)},cursorOf(params.name,row.seq)));
+  const events=page.map(row=>{const data=JSON.parse(row.data);if(env.HOMIE_LOCAL_TEST_SECRET&&caller.localTest&&caller.testScope&&feed.event==='record.changed')data.app=feed.app;return occurrence(params.name,{...row,data},cursorOf(params.name,row.seq));});
   const after=hasMore?page.at(-1).seq:start.through;
   return {events,cursor:cursorOf(params.name,after),truncated:start.truncated,hasMore,nextPollMs:5000};
 }

package/worker/mcp-tools.mjs

@@ -14,6 +14,7 @@ export async function allowed(audience, caller, env) {
   if (audience === 'signed-in') return true;
   if (audience === 'owner') return caller.owner === true;
   if (audience && typeof audience === 'object' && audience.app && audience.role) {
+    if(env.HOMIE_LOCAL_TEST_SECRET && caller.localTest)return caller.owner || Boolean(caller.roles?.[audience.app]?.includes(audience.role));
     return caller.owner || Boolean(await env.DB.prepare("SELECT player FROM app_roles WHERE app IN (?1,'*') AND role=?2 AND player=?3").bind(audience.app,audience.role,caller.id).first());
   }
   return false;
@@ -86,7 +87,7 @@ export function builtins(env,cat,origin) {
       const {readableFeed,feedEvents,matchesFeed,eventFeeds}=await import('./event-resources.mjs');
       if(!await readableFeed(env,cat,ctx.caller,feed))throw new Error('Event feed unavailable');
       if(!Number.isSafeInteger(after)||after<0)throw new Error('Invalid event cursor');
-      const page=await feedEvents(env,feed,{after});
+      const page=await feedEvents(env,feed,{after,caller:ctx.caller});
       return {kind:'untrusted-event-data',events:page.filter(e=>matchesFeed(eventFeeds(env)[feed],e)),next:page.length===100?page.at(-1).seq:null};
     }),
     tool('studio_events_webhook_status','Owner delivery attempts, last errors and next page for an outbound event webhook.','owner',object({feed:str,after:{type:'integer',minimum:0}},['feed']),async({feed,after},ctx)=>{
@@ -105,6 +106,23 @@ export function builtins(env,cat,origin) {
       const {replayFunction,runFunctions}=await import('./functions.mjs');
       await replayFunction(env,name);await runFunctions(env,cat,origin);return {ok:true};
     }),
+    tool('studio_schedule_fire','Locally invoke a named scheduled function at a simulated timestamp.','owner',object({name:str,at:{type:'integer',minimum:0}},['name','at']),async({name,at},ctx)=>{
+      if(!env.HOMIE_LOCAL_TEST_SECRET || !['localhost','127.0.0.1','[::1]'].includes(new URL(origin).hostname))throw new Error('Local dev testing only');
+      const {syncFunctions,emitEvent,runFunctions}=await import('./functions.mjs');
+      const definitions=await syncFunctions(env), fn=definitions.find(f=>f.name===name&&f.schedule);
+      if(!fn)throw new Error(`Unknown scheduled function ${name}; declare it and rebuild dev`);
+      const data={function:name,cron:fn.schedule,scheduledTime:at,...(ctx.caller.testScope?{app:`${ctx.caller.testApp}:check:${ctx.caller.testScope}`}:{})};
+      const id=await emitEvent(env,fn.event,data);
+      await runFunctions(env,cat,origin);
+      let run;const end=Date.now()+10000;
+      do {
+        run=await env.DB.prepare('SELECT outcome,error FROM function_runs WHERE event=?1 AND function=?2 ORDER BY started DESC LIMIT 1').bind(id,name).first();
+        if(run && !['running','interrupted'].includes(run.outcome))break;
+        await new Promise(resolve=>setTimeout(resolve,50));
+      }while(Date.now()<end);
+      if(!run || run.outcome!=='complete')throw new Error(`Schedule ${name}: ${run?.error??run?.outcome??'no handler run'}`);
+      return {id,name,scheduledTime:at,simulated:true};
+    }),
     tool('studio_function_fire','Fire an event locally through the durable function dispatcher.','owner',object({event:str,id:str,data:{type:'object'}},['event']),async(args)=>{
       if(!['localhost','127.0.0.1','[::1]'].includes(new URL(origin).hostname))throw new Error('Local testing only');
       const {emitEvent,runFunctions}=await import('./functions.mjs');

package/worker/mcp.mjs

@@ -82,7 +82,7 @@ export async function remoteMcp(request,env,ctx,{catalogueOf,definitions=[]}) {
         const readPage=async(resourceUri,after=0)=>read('events:'+name,async fresh=>{
           if(!await readableFeed(env,cat,fresh,name))throw new Error('Event resource unavailable');
           if(!Number.isSafeInteger(after)||after<0)throw new Error('Invalid event cursor');
-          const page=await feedEvents(env,name,{after});
+          const page=await feedEvents(env,name,{after,caller:fresh});
           const events=page.filter(e=>matchesFeed(eventFeeds(env)[name],e));
           return {contents:[{uri:String(resourceUri),mimeType:'application/json',text:JSON.stringify({kind:'untrusted-event-data',events,next:page.length===100?uri+'?after='+page.at(-1).seq:null})}]};
         });

package/worker/shop-links.mjs

@@ -9,7 +9,7 @@ export function linkConfig(env) {
 export const shopMode = (env) => hasStripeKey(env) ? modeOf(env.STRIPE_KEY) : linkConfig(env)?.mode ?? 'test';
 export function linkSettings(shop) {
   return JSON.stringify({ currency: shop.currency, till: shop.till, automaticTax: shop.automaticTax, policy: shop.policy,
-    cap: shop.capPerPlayerMonth, checkoutMinutes: shop.checkoutMinutes, items: shop.items });
+    cap: shop.capPerPlayerMonth, checkoutMinutes: shop.checkoutMinutes, items: shop.items, ...(shop.basket ? {basket:shop.basket} : {}) });
 }
 export function fullerReason(shop) {
   if (shop.items.some(item => item.interval && item.price === 'choose')) return 'A giver-chosen monthly amount needs a Stripe Checkout connection.';

package/worker/shop-rules.mjs

@@ -209,7 +209,10 @@ export function checkShop(raw, { games = null, audience = 'general', studioName
   const kids = audience === 'kids' && !policy.kidsStudio;
   const finalTill = kids ? 'off' : TILLS.includes(till) ? till : 'off';
   if (kids && till !== 'off') warnings.push({ at: 'till', message: 'studio.json says "audience": "kids": the studio sells nothing in its games (the till is off under policy.kidsStudio).' });
+  if (raw.basket !== undefined && (!isObj(raw.basket) || typeof raw.basket.name !== "string" || !raw.basket.name.trim() || raw.basket.name.length > 120 || typeof raw.basket.description !== "string" || raw.basket.description.length > 500)) errors.push({at:"basket",message:"A basket needs a name (1–120 characters) and description (up to 500 characters)."});
+  if (raw.basket && (raw.automaticTax || till !== "stripe")) errors.push({at:"basket",message:"Saved baskets use Stripe with tax already included in the menu prices."});
   const shop = {
+    ...(isObj(raw.basket) ? {basket:{name:raw.basket.name,description:raw.basket.description}} : {}),
     v: 1, ...(isObj(raw.giving) ? { giving: { receiptText: String(raw.giving.receiptText ?? '') } } : {}), policy, purchasesTill: TILLS.includes(raw.purchasesTill ?? till) ? (raw.purchasesTill ?? till) : 'off', ...(/^https:\/\/billing\.stripe\.com\/p\/login\/[A-Za-z0-9_]+$/.test(raw.purchasesPortalLogin ?? '') ? { purchasesPortalLogin: raw.purchasesPortalLogin } : {}), checkoutMinutes, requestBytes, automaticTax: raw.automaticTax === true, guestBuyersPerAddressPerHour, purchaseAttemptsPerMinute, purchaseAttemptsPerAddressPerMinute, till: finalTill, currency: CURRENCY.test(currency) ? currency : 'usd', refundDays, capPerPlayerMonth: cap, items,
     open: finalTill !== 'off' && items.length > 0, ...(kids ? { audience: 'kids' } : {}), ...(catalog.length ? { catalog } : {}),
   };

package/worker/shop.mjs

@@ -517,7 +517,7 @@ async function startCheckout(env, url, cat, shop, item, { player, game, amount,
   const keyless = (amount > 0 || lines.some(l => l.item.interval)) && !hasStripeKey(env);
   const config=linkConfig(env);
   if(booking && amount===0 && !hasStripeKey(env) && config?.slots?.some(l=>l.app===game&&l.slots===booking.slots&&l.slot===booking.slot))return {error:fail(409,'booking','Publish a separate local slot for a free booking; it cannot share a paid Stripe capacity budget.')};
-  const menu=keyless && !booking && lines.length>1 ? config?.menus?.find(m=>lines.every(l=>m.items.some(i=>i.item===l.item.id))) : null;
+  const menu=keyless && !booking && lines.length>0 ? config?.menus?.find(m=>(m.basket || lines.length>1)&&lines.every(l=>m.items.some(i=>i.item===l.item.id))) : null;
   const link=keyless ? booking ? config?.slots?.find(l=>l.app===game&&l.collection===booking.collection&&l.slots===booking.slots&&l.slot===booking.slot&&l.item===item.id) : menu ?? config?.items.find(l=>l.item===item.id) : null;
   if(keyless && lines.length>1 && !menu)return {error:fail(409,'menu','These items need separate Stripe menus. Custom amounts and monthly gifts use their own links.')};
   if(keyless && (!link || !paymentLinkURL(link.url)))return {error:fail(503,'payment-links','Ask the owner’s AI to sync the shop and published booking slots.')};
@@ -533,7 +533,7 @@ async function startCheckout(env, url, cat, shop, item, { player, game, amount,
   }
   if(keyless && item.price==='choose' && lines[0].quantity!==1)return {error:fail(400,'quantity','A tip is one chosen amount; choose it on Stripe.')};
   if(menu && menu.items.some(e=>{const i=shop.items.find(i=>i.id===e.item);return !i || i.game && i.game!==game;}))return {error:fail(409,'menu','This menu includes items from another app; sync separate menus for each app.')};
-  if(menu)lines=menu.items.map(entry=>{const i=shop.items.find(i=>i.id===entry.item);return {item:i,quantity:1,amount:i.price};});
+  if(menu && !menu.basket)lines=menu.items.map(entry=>{const i=shop.items.find(i=>i.id===entry.item);return {item:i,quantity:1,amount:i.price};});
   if(keyless)lines=lines.map(l=>({...l,item:{...l.item,paymentLink:link,stripePrice:menu?.items.find(i=>i.item===l.item.id)?.price??link.price}}));
   const order = { id: newOrderId(), player: player.id, amount, currency: shop.currency };
   if (booking && reference === null) reference = order.id;
@@ -575,6 +575,7 @@ async function startCheckout(env, url, cat, shop, item, { player, game, amount,
   }
   if (keyless) {
     const checkout = new URL(link.url); checkout.searchParams.set('client_reference_id', order.id);
+    if(menu?.basket)checkout.searchParams.set('prefilled_amount',String(amount));
     return { order, url: checkout.href, reconciled };
   }
   let session = null;
@@ -955,6 +956,7 @@ async function bindLinkSession(env, session, mode) {
   if (!source || source.mode !== mode) return false;
   const lines = await orderLines(env, source.id);
   if (!lines.length || !lines[0].snapshot) return false;
+  if(JSON.parse(lines[0].snapshot).paymentLink?.basket) return bindBasketSession(env,session,source,lines);
   if(JSON.parse(lines[0].snapshot).paymentLink?.items) {
     const saved=await env.DB.prepare('SELECT value FROM meta WHERE key=?1').bind(`shop-menu:${source.id}`).first();
     const original=saved?JSON.parse(saved.value).map(l=>({item:l.item.id,snapshot:JSON.stringify(l.item),unit_amount:l.amount})):lines;
@@ -990,6 +992,50 @@ async function bindLinkSession(env, session, mode) {
   return true;
 }
 
+/** A saved basket is immutable. A reopened link buys that same basket again. */
+async function bindBasketSession(env,session,source,lines) {
+  const link=JSON.parse(lines[0].snapshot).paymentLink;
+  if((session.payment_link?.id??session.payment_link)!==link.id || session.metadata?.revision!==link.revision || session.currency!==source.currency)return false;
+  if(session.payment_status!=='paid' || !Number.isSafeInteger(session.amount_total) || session.amount_total<=0 || session.amount_subtotal!==session.amount_total)return false;
+  await env.DB.prepare('UPDATE shop_orders SET session=?2 WHERE id=?1 AND session IS NULL').bind(source.id,session.id).run();
+  let order=await orderBySession(env,session.id);
+  if(!order) {
+    const id=`ord_${(await sha256Hex(session.id)).slice(0,20)}`;
+    await env.DB.batch([
+      env.DB.prepare("INSERT OR IGNORE INTO shop_orders(id,player,checkout_player,item,game,amount,currency,till,mode,status,parent,created_at,updated_at,session) SELECT ?2,player,checkout_player,item,game,amount,currency,till,mode,'started',parent,?4,?4,?3 FROM shop_orders WHERE id=?1").bind(source.id,id,session.id,Date.now()),
+      env.DB.prepare('INSERT OR IGNORE INTO meta(key,value) SELECT ?1,value FROM meta WHERE key=?2').bind(`shop-reference:${id}`,`shop-reference:${source.id}`),
+      ...lines.map((l,i)=>env.DB.prepare('INSERT OR IGNORE INTO shop_order_lines(id,order_id,position,item,quantity,unit_amount,amount,snapshot) VALUES(?1,?2,?3,?4,?5,?6,?7,?8)').bind(`${id}_${i}`,id,i,l.item,l.quantity,l.unit_amount,l.amount,l.snapshot)),
+    ]);
+    order=await orderBySession(env,session.id);
+  }
+  return Boolean(order);
+}
+
+// Keep the actual payment in financial totals and the ordered amounts in lines.
+// Aggregate refunds are allocated proportionally; they do not change quantities.
+async function paidBasket(env,shop,o,lines,session,paidAt) {
+  const total=session.amount_total;
+  if(session.payment_status!=='paid' || session.currency!==o.currency || !Number.isSafeInteger(total) || total<=0 || session.amount_subtotal!==total)return 'mismatch';
+  if(o.paid_at!==null)return 'already';
+  const expected=lines.reduce((n,l)=>n+Number(l.amount),0);
+  if(!Number.isSafeInteger(expected)||expected<=0)return 'mismatch';
+  const writes=[];let cumulative=0,allocated=0;
+  for(const l of lines) {
+    cumulative+=Number(l.amount);
+    const next=Number(BigInt(total)*BigInt(cumulative)/BigInt(expected));
+    const gross=next-allocated;allocated=next;
+    if(total>=expected && o.player)writes.push(...grantStatements(env,o,JSON.parse(l.snapshot),paidAt,l));
+    writes.push(env.DB.prepare("UPDATE shop_order_lines SET status='paid',total=?2 WHERE id=?1 AND EXISTS(SELECT 1 FROM shop_orders WHERE id=?3 AND paid_at IS NULL)").bind(l.id,gross,o.id));
+  }
+  const payment=typeof session.payment_intent==='string'?session.payment_intent:session.payment_intent?.id;
+  writes.push(env.DB.prepare("UPDATE shop_orders SET status='paid',amount=?2,total=?2,tax=0,payment=?3,paid_at=?4,updated_at=?4,attention=0,note=?5 WHERE id=?1 AND paid_at IS NULL").bind(o.id,total,payment??null,paidAt,total<expected?'Settle the difference at the bar':''));
+  // Enrich the trigger's durable event in this same transaction, before dispatch.
+  writes.push(env.DB.prepare("UPDATE studio_events SET data=json_set(data,'$.basketTotal',?2,'$.settlement',?3) WHERE id=?1").bind(`shop_orders:${o.id}:paid`,expected,total<expected?'short':'paid'));
+  const result=await env.DB.batch(writes);
+  if(payment)await syncRefunds(env,payment);
+  return result.at(-2)?.meta?.changes?'paid':'already';
+}
+
 /** Menu totals are never decoded into quantities. Only signed invoice lines are authoritative. */
 async function bindMenuSession(env,session,source,lines) {
   const first=JSON.parse(lines[0].snapshot),link=first.paymentLink;
@@ -1029,7 +1075,9 @@ export async function paid(env, shop, session, paidAt = Date.now()) {
   const o = await orderBySession(env, session.id);
   if (!o) return 'unknown-order';
   // The session must be the one this order opened, for this player and this price.
-  const linkOrder = (await orderLines(env, o.id)).some((l) => l.snapshot && JSON.parse(l.snapshot).paymentLink);
+  const savedLines=await orderLines(env,o.id);
+  if(savedLines[0]?.snapshot && JSON.parse(savedLines[0].snapshot).paymentLink?.basket)return paidBasket(env,shop,o,savedLines,session,paidAt);
+  const linkOrder = savedLines.some((l) => l.snapshot && JSON.parse(l.snapshot).paymentLink);
   if (!linkOrder && (session.metadata?.order !== o.id || ((o.checkout_player ?? o.player) && session.client_reference_id && session.client_reference_id !== (o.checkout_player ?? o.player)))) return 'mismatch';
   if (session.currency !== o.currency || !Number.isSafeInteger(session.amount_subtotal) || session.amount_subtotal !== Number(o.amount)) return 'mismatch';
   if (['refunded', 'lost', 'disputed'].includes(o.status)) {

package/worker/version.mjs

@@ -1,2 +1,2 @@
 /** The @homie-rocks/studio version this Worker code is (package.json's; a test keeps them equal). Cache-busts /_homie/site.js. */
-export const STUDIO_VERSION_TAG = '0.51.5';
+export const STUDIO_VERSION_TAG = '0.51.6';