@homie-rocks/studio 0.32.0 → 0.33.0

package/CHANGELOG.md

@@ -17,9 +17,92 @@ 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.33.0] - 2026-10-08
+
+**Plugin 0.34.0** · [#57](https://github.com/homie-rocks/homie/pull/57)
+
+A game's rules can run on your own Cloudflare instead of in a player's browser. This is the first piece of it: the format, the server that runs it, and one example game. Your existing games are not touched.
+
+### Added
+
+- Public games can offer X a picture with a play button: its phone apps open the game full screen inside X; its website opens the posted link in a new tab. X decides what it shows, and its written card policy is for audio/video, so this may change. Studio and game switches turn it off.
+- The player joins a public room without sign-in or storage and works as a page of its own and framed; opened as its own page, a reload keeps the room, seat and guest name. Account and purchase links leave a frame, and no purchase starts in the player.
+- The build measures the card's picture and offers the card for any picture X's reference says will render (JPG, PNG, WEBP or GIF, at least 68,600 pixels, under 5 MB), whatever its shape; a refused picture is a warning naming the file and the rule. `site.twitterSite` is optional.
+- Ember Vale's new-hero card fits a short screen: a phone on its side, or a small frame.
+- **A room survives restarts and updates.** Server-hosted games save the whole match, including seats, scores, AI companions and pending decisions. Players reconnect to the same room after a restart; with the default settings, at most one second of play is replayed from the last successful save. If storage is unavailable, play continues and the office reports that recovery may lose more.
+- **Updates keep a running match when its saved state still fits.** Players and watchers load the new game and reclaim their seats. A change to the shape of the saved state starts a fresh match. A game that is slow to load after an update is given up to a minute. A load that fails is tried again a few times, the page says what it is doing while it waits, and it asks you to reload if it has to give up. Older browser-hosted games still update at the round break.
+- **A game written as rules plus view.** The rules (`src/rules.ts`, with the movement code in `src/move.ts`) say what is true in the game: who took which coin, every score, when a round ends. The view (`src/view.ts`) draws what it is told and sends what the player presses. `@homie-rocks/studio/rules` is the format (`defineRules`, `defineMove`, `f` for the type of every piece of state) and `@homie-rocks/studio/rules/view` is what a view uses (`openRoom()`).
+- **The server is the room's host.** The rules of such a game run in the room's own server object on your Cloudflare. No player's browser is in charge, so a changed browser cannot change a score, a pickup or a round, and closing any one tab does not interrupt the others. Seats, chat, votes, watchers and the owner's controls work as before.
+- **Homie checks the rules before they go anywhere.** The build refuses rules that use anything outside a short list of safe operations and names the line (no clock, no network, no `Math.sin` that two machines may round differently, no state outside the declared fields). It then adds a guard, so a rule that never ends or grabs memory is stopped while the room carries on, and a room whose rules keep failing is closed and named in the log.
+- **Every room feature works with the server in charge.** Seats and coming back into the same body, waiting for a seat, watching, chat, votes, your owner controls, servers and their policies, AI seats with a pass, the skill dial, and a game's own decisions (`world.ask`) all behave in a server-hosted room as they do in a browser-hosted one. On a hybrid or beginner server the AI companions keep their reserved seats and their own names, and a guide in such a room follows the goals and lines in your `agents.json`.
+- **`coin-dash`, an example.** Copy it with `homie-studio game new <id> --from coin-dash` to see the two halves. It is an example, not yet a starter the chat offers: see the upgrade notes.
+- **The deploy plan says it.** For each such game: that its rules run on Cloudflare, and roughly what an hour of play in one full room uses of the free plan's daily allowances.
+- **The netplay contract is revision 10** (`netplay/NETPLAY.md`, section 29): the server as a host, input as steps stamped with the room's tick, and the life of such a room. Nothing a game written before sends or receives has changed.
+
+### Changed
+
+- **Your shop, your prices.** Studios choose their own shop prices, tips, catalog size, item kinds, durations, refunds and referral terms. Homie no longer sets sales or spending ceilings. Optional spending caps and refund windows belong to the studio; Stripe currency requirements still apply, including currencies without cents.
+- **Your shop policies are editable.** Shop policies are readable and editable presets: protective, adults-only and custom. New shops start protective, including the existing protections for younger players. Existing shops keep their written settings and protective policies unless they choose otherwise. Purchase flood protection now checks both the account and the address, with separate rates the studio can change.
+- **Any name is yours to use in the directory.** The directory no longer keeps a list of Homie's own games' names. A studio, game, song, video or part is listed under whatever plain-text name you gave it, and `studio_request_grant` and `studio_grant_status` are gone from the Homie MCP server.
+- **The toolkit comes from npm only.** homie.rocks no longer serves `homie-studio-<version>.tgz`. A studio pins the npm registry's exact version, as every studio made since 0.10.0 already does.
+- A room of such a game pauses when the last person leaves and ends a minute later if nobody returns. An empty room uses nothing.
+- `homie-studio perf` accepts a room with no browser host.
+- A new studio's `site/src/worker.mjs` hands the Worker the rules of its server-hosted games (`site/src/rules/`, written by every build and committed with the studio), and its `wrangler.jsonc` turns off code made from text while the Worker starts.
+
+### Fixed
+
+- A goal, a line, an ask or an argument named after something every JavaScript object has (`constructor`, `toString` and the like) is no longer taken for one of your vocabulary's. Before, an AI guide could be made to "say" such a line, which threw an error in every player's browser, in browser-hosted games too.
+- Only the room's host can speak as a guide. A player or a watcher sending a line marked as the guide's is ignored.
+- An AI pass opened twice keeps one seat: the newer connection takes it, and reconnecting is paced so a copied pass cannot be used to flood a room.
+
+### Upgrade notes
+
+- **Check settings you left out of shop.json.** Written settings keep working; no limit is set unless the studio sets one. Omitted settings no longer receive the toolkit's old defaults. To keep those old choices, write `"capPerPlayerMonth": 5000` (monthly spending), `"refundDays": 14` (self-service refunds), `"min": 200, "max": 5000` on each tip, and `"windowDays": 30, "capPerPlayer": 1000, "holdDays": 30, "minimumInvoice": 2500` inside `referrals`. Without them there is no monthly spending cap, no self-service refund window (buyers ask the studio), no tip range beyond provider currency units, no referral window or per-player referral cap, no hold and no minimum invoice. Older `shop init` wrote these amounts explicitly; hand-edited files may have omitted them. All amounts are minor units of your currency.
+- **Write whole amounts.** Fractional minor-unit amounts now stop the build with the setting's name and an example, before publication. For example, replace `"capPerPlayerMonth": 2500.7` with the whole amount you intend, such as `2500`. Every amount setting follows this rule; none is silently rounded. Decimal numeric strings remain accepted; padded strings, hexadecimal strings, lists and booleans now stop the build. Fractional `days` and `refundDays` retain their fraction, rounded to milliseconds, instead of being floored to whole days.
+- **Flood protection allows shared addresses.** `purchaseAttemptsPerMinute` is the account rate (6 by default); `purchaseAttemptsPerAddressPerMinute` is the separate address rate (600 by default, to allow households, schools and venues). Checkout, parent-link and parent-payment attempts have separate counts. Rotating addresses does not bypass the account rate. Referral statements retain a global rate of 30 per minute as well as 30 per address; both are settings in the site configuration; invalid values produce a named error. New guest buyers have a configurable address rate, `guestBuyersPerAddressPerHour`, defaulting to 600 an hour so venues and schools can share a connection; guest buyers and ordinary new players have separate counters.
+- **The withdrawal acknowledgement stays.** Existing checkout and refund-page wording is restored. `policy.withdrawalAcknowledgement` is true in every preset; edit it only as a considered studio policy. Account and younger-player protections remain in the protective preset. `policy.childAge` and `policy.adultAge` default to 13 and 18 and can be edited.
+- **Large shops and referral books use pages.** The shop, in-game sheet and office offer navigation. The office lists referrers with exact totals once each; sales page inside each referrer. `shop statements --send` and the office button send all statements in one action, saving immutable pages and progress in D1. Keep the command or tab open; restart after closing to resume safely. Failed pages retry three times with backoff; persistent failures name the referrer and the rest continue. One CLI office key is renewed during a run. Signed continuation pages contain lines without repeating totals; a new statement replaces the old pages for that period and currency. Mark paid selects one currency and does not change an edition already being sent. Read-only statement views allocate no editions. Sends use Workers-compatible manual redirects and refuse every redirect response.
+- **The optional spending cap retains unresolved payments.** Sessionless rows age out after 32 minutes; sessions past expiry and bank payments still processing count until Stripe confirms payment, expiry or failure. Shop GETs never call Stripe. Only a cap-refused purchase waits for up to three parallel reads with two-second timeouts; successful purchases continue in the background. Atomic claims and per-row intervals (one minute, five for processing payments, growing with age to an hour) bound successful reads; failed reads retry after about one minute and log the order and reason. More than three lost rows can require another attempt. Paid rows use Stripe's charge time; pending, missing payment time or unreachable rows keep counting. Stripe's [resource_missing](https://docs.stripe.com/error-codes#resource-missing) means this key's account has no such session; it frees the reservation and shows the missing row in the office. The office also offers a release recorded with the confirming owner's account (or a fingerprint of the office sign-in session) and time, and asks Stripe to [expire an open Checkout Session](https://docs.stripe.com/api/checkout/sessions/expire). Neither mark prevents a verified payment from granting the item, counting toward spending again and being refundable, even if the freed space has been spent. Internal states and notes stay out of player account data. Late events are idempotent; test rows never count toward live spending. Free orders remain available after an owner lowers a cap. Partial refunds keep the full price counted; full refunds release it. No cap means no spending SUM. Deploy applies `0010_shop_reservations.sql` and `0011_shop_statements.sql`; missing schema reports not ready with the migration names.
+- **Guest checkouts can answer the age question.** A valid answer creates a guest session when the studio permits guests. A refused Stripe checkout returns the guest cookie so retrying uses the same account. Idle guest cleanup keeps owners, including future entitlements, and continues removing other unused guests.
+- Allowed odds and countdown fields that are not published now produce a warning telling the studio to put buyer-facing terms in `blurb`. Three-decimal amounts using the smallest minor unit warn, without an undocumented divisible-by-ten refusal; Stripe's error is shown if it refuses them, with the failure note in the office order row. Free orders can be taken back without contacting Stripe. Stripe settlement minimums remain warnings.
+- A studio made before 0.10.0 pins an address on homie.rocks that no longer answers, so `npm install` in it fails until it is upgraded. Run `npx -y @homie-rocks/studio@latest upgrade --apply`, then `npm install`: the upgrade replaces the address with the registry's exact version. Nothing else about the studio changes.
+- **Nothing to do for the games you have.** A game with no `src/rules.ts` builds and runs exactly as before, in a player's browser. The build says so in one line. Asking for the server on such a game (`"room": { "host": "server" }`) stops the build with the reason.
+- **Do not put a game of your own on this yet.** A server-hosted room has no save in this version: a restart of the room, or any deploy of your site, starts its match again, where today's rooms carry on. That arrives in a later version, and `coin-dash` is offered as a starter only then.
+- In this version a player's own character still moves as today: their browser says where it is and the server holds it to its top speed. A changed browser cannot move faster than that, but it can walk through a wall. Scores and pickups are decided on the server either way.
+- Rules with 3D bodies, rules hosted by a player's browser, offline play of a rules game, and AI guides driven by the server are not in this version.
+- An existing studio gets the new `site/src/worker.mjs` and the empty `site/src/rules/index.mjs` from `homie-studio upgrade --apply` (a Worker file you changed yourself is kept, and the upgrade shows the three lines to add). The next deploy writes the new `wrangler.jsonc`.
+- This version has been run on a local Cloudflare runtime only. It has not been run or measured on Cloudflare itself.
+
+## [0.32.1] - 2026-10-07
+
+**Plugin 0.33.1** · [#55](https://github.com/homie-rocks/homie/pull/55) · [release-2026-10-07-studio-0.32.1](https://github.com/homie-rocks/homie/releases/tag/release-2026-10-07-studio-0.32.1)
+
+A standalone game can be put on your own iPhone or iPad with one command, and the guide says what has now been run on a real phone and corrects what an older site means for a copy.
+
+### Added
+
+- **`homie-studio standalone run <game> --for ios --device`** builds the game for the one iPhone or iPad plugged in to your Mac, signs it for your Apple team, installs it over the cable, starts it, and then looks for it among the phone's running programs. It says the game is running only when it found it there. In chat it is `game_standalone` with `device: true`.
+- **`--device` is your yes to what that changes outside your computer.** It adds the phone to your Apple team's list of development devices (a team may register a limited number a year, and a device stays on the list until the membership year renews) and lets Xcode make a development profile for the app. The app is signed for that phone only: a build to try, never one for the store.
+- Every way it can stop is an answer with what to do: no phone connected, more than one (it lists them by model and builds nothing), Developer Mode off (on the phone: Settings, Privacy & Security, Developer Mode; the phone restarts), a phone that does not trust the Mac, a locked phone (it waits a minute for you to unlock it), no Apple account signed in to Xcode, a team with no registered phone, a build that failed. It never says or returns the phone's id, its name or your team's id.
+- The team is `HOMIE_APPLE_TEAM`, else the one team among your keychain's development identities; it says which it used. With none, or more than one, it stops and asks for `HOMIE_APPLE_TEAM`.
+- `setup status` and `standalone plan` have a row for a phone to try a build on: which model is connected and whether its Developer Mode is on, or "could not check".
+
+### Fixed
+
+- **What an older site means for a copy was said too broadly.** Only **Quick play** needs your live site on 0.32.0 or later: it asks the site which room to join, and an older site does not let an app read the answer. A room made in the app or joined by its code connects through an older site too. We saw that against a site on 0.31.0; it is not promised for every older version. The plan, the build, the chat tool, the skill and the guide now say this.
+
+### Changed
+
+- The guide's "What has been run and what has not" now has what was run on 2026-10-07: an iOS build on a real iPhone, signed for a development team and installed over the cable, playing offline with its bots, and an online private room from that phone through a studio's live site. The new command built, signed and installed a game on that iPhone; the phone was locked, so its last two steps (starting the game and finding it running) have been run against stand-ins only. Still never run: anything under Steam, Developer ID signing and notarization, the iOS archive for the App Store, the GitHub workflow, the Windows and Linux builds started on any computer, a real Android phone, and Quick play online from a phone.
+
+### Upgrade notes
+
+- A run on a phone needs a Mac with Xcode signed in to your Apple account, and the phone unlocked, trusting the Mac, with Developer Mode on.
+- There is no `--device` for an Android phone yet: `standalone run <game> --for android` hands over to Capacitor, which asks which phone or emulator. That has been run on an emulator only.
+
 ## [0.32.0] - 2026-10-06
 
-**Plugin 0.33.0** · [#54](https://github.com/homie-rocks/homie/pull/54)
+**Plugin 0.33.0** · [#54](https://github.com/homie-rocks/homie/pull/54) · [release-2026-10-06-studio-0.32.0](https://github.com/homie-rocks/homie/releases/tag/release-2026-10-06-studio-0.32.0)
 
 A game can now be an app of its own: a desktop app for macOS, Windows and Linux and a phone app for iOS and Android, the same web game in a thin shell that still plays through your studio's own site.
 
@@ -46,7 +129,7 @@ A game can now be an app of its own: a desktop app for macOS, Windows and Linux
 
 ### Upgrade notes
 
-- **Upgrade and deploy before a standalone copy can find rooms.** A copy talks to your live site, and only a site deployed with 0.32.0 or later answers it. Until then every copy plays offline.
+- **Upgrade and deploy before Quick play can find a room in a standalone copy.** Quick play asks your live site which room to join, and only a site deployed with 0.32.0 or later lets an app read the answer. Until then Quick play is offline with the game's bots. (Corrected in 0.32.1: a room made or joined by its code connects through an older site too.)
 - The address of your site is built into every copy and cannot be changed in a copy that has shipped. Put the studio on its own domain before you ship: a workers.dev address belongs to the Cloudflare account.
 - Before you ship, name the game's revision in `game.json` (`"netplay": { "version": "1" }`) and raise it with every change an older copy cannot play with. Older copies then keep playing with each other, and say "Update <Name> to play online with everyone." when they meet a newer one.
 - In an app the game's code is trusted with everything the app's page has, and on phones with Capacitor's native bridge. That is fine for your own code; do not load scripts from the network in a game you ship as an app.

package/README.md

@@ -207,6 +207,24 @@ the owner's session), so `localStorage` throws inside it: a setting or a persona
 `net.link` says whether the browser is in its room, reconnecting, or playing alone because the room
 never answered; `guardGestures()` stops a long press on a phone from selecting text in a touch game.
 
+## A game's rules on the server (an example, 0.33.0)
+
+A game can be written as **rules plus view**: `src/rules.ts` and `src/move.ts` say what is true in the game and run
+in the room's own server object on the studio's Cloudflare; `src/view.ts` draws what it is told and sends what the
+player presses. No player's browser is the room's host, so a changed browser cannot change a score, a pickup or a
+round. `homie-studio build` checks the rules first and refuses anything outside a short list of safe operations,
+naming the line, then guards them so a rule that never ends is stopped while the room carries on
+(`netplay/NETPLAY.md` section 29).
+
+```sh
+npx --no-install homie-studio game new coin-dash --from coin-dash   # the example
+npx --no-install homie-studio dev                                   # its rules run in the local room object
+```
+
+`coin-dash` is an example, not yet a starter to build your own game on: a server-hosted room has no save in this
+version, so a deploy of the site restarts its match. A game with no `src/rules.ts` is not touched by any of this and
+runs in a player's browser exactly as before. So far this has run on a local Cloudflare runtime only.
+
 ## Player accounts and cloud saves
 
 A game whose progress must last (a character that levels up for days, unlocks, a collection, a hardcore mode)
@@ -433,13 +451,14 @@ npx homie-studio lounge mod <player id>                                 # a mode
 
 A studio sells items for its games (0.24.0; Stripe's own agent tools since 0.24.3) with **its own Stripe account**: the studio is the seller, money goes
 straight from players to its Stripe, and homie.rocks never sees, holds or moves it (Homie takes no cut; no shared
-currency; not a Connect platform). Real-money prices only, nothing random, the kids rules built in (no shop on a kids
-server, spending off until a neutral age question says adult, nothing for under-13s, 13-17 through a parent's own
-checkout, a monthly cap), and the television only shows a code to buy on a phone.
+currency; not a Connect platform). The studio chooses its prices, item kinds and optional spending and refund
+settings, with no Homie ceiling. New shops start with the editable `protective` policy: accounts and an age
+question, no purchases for under-13s, parent checkout for teens, no shop on kids servers, and no paid randomness.
+The studio can inspect and change each rule in shop.json; [shop/SHOP.md](shop/SHOP.md) explains every preset.
 
 ```sh
 npx homie-studio shop init --supporter        # shop.json with a US$5 Supporter pack, and SELLING.md (the owner's plain words)
-npx homie-studio shop check                   # the kit's rules; every build checks them too
+npx homie-studio shop check                   # the studio settings and provider requirements; every build checks them too
 npx homie-studio shop catalog [--have <file>] # the items as Products in Stripe: the read, then the exact writes (Stripe's MCP)
 npx homie-studio shop connect                 # a page on THIS computer: the owner pastes one restricted key; it makes the webhook
 npx homie-studio shop                         # open (test or live) or what is missing
@@ -823,12 +842,19 @@ every other target says "built, not started on this computer".
 
 **What the standalone game does not have (v1):** player accounts and sign-in, cloud saves (saves stay on the
 device and are lost when the app is uninstalled), the shop, room chat, watching and the big screen, servers
-other than the public one, automatic updates, and a signed Windows build. A studio must be on 0.32.0 or later
-**and deployed** before a copy can find rooms.
+other than the public one, automatic updates, and a signed Windows build. For Quick play to find a room, a
+studio must be on 0.32.0 or later **and deployed**; a room made or joined by its code works with an older site
+too (seen against 0.31.0, not promised for every older version).
+
+**On your own iPhone or iPad:** `standalone run <id> --for ios --device` builds the game for the one phone
+plugged in, signs it for your Apple team, installs it over the cable, starts it and looks for it among the
+phone's running programs. `--device` is your yes to what it changes: it adds the phone to your Apple team's list
+of development devices.
 
 **What has not been run:** the Windows and Linux builds have never been started; nothing has been started by
 Steam (its overlay, which Electron apps often do not show, included); a Developer ID signature, notarization and
-the iOS archive have never been made; nothing has run on a real phone. The guide lists it all.
+the iOS archive have never been made; nothing has run on a real Android phone, and Quick play has not been seen
+online from a phone. The guide lists it all.
 
 ## How it feels: the Game Lab (`homie-studio lab`)
 
@@ -1193,8 +1219,7 @@ npx homie-studio port check my-game --url http://127.0.0.1:8787   # the owner te
 Versions are immutable: a published version never changes, so a studio that pinned one
 never changes by surprise. A change ships as a new `version` on the npm registry as
 `@homie-rocks/studio`, which is what `homie-studio new` pins (the exact version; package-lock.json keeps its
-integrity). The registry is what Workers Builds and a Claude Code cloud session reach by default. Older studios
-pinned a tarball at `https://homie.rocks/npm/homie-studio-<version>.tgz`, which stays.
+integrity). The registry is what Workers Builds and a Claude Code cloud session reach by default.
 
 ## Beta
 

package/agents/agents.ts

@@ -24,7 +24,7 @@
  * vocabulary line with arguments that fit, on a server whose AI may talk).
  * =============================================================================
  */
-import { aiName, stripAi, type Netplay, type NetEvent, type Policy, type Slot } from '../netplay/netplay';
+import { aiName, stripAi, type Netplay, type NetEvent, type Policy, type Slot } from '../netplay/netplay.ts';
 
 /* ------------------------------------------------------------------ the vocabulary (agents.json) */
 
@@ -56,6 +56,13 @@ export interface GoalEvent { slot: number; goal: Goal; prev: Goal | null; askAt:
 export interface AskButton { k: string; args: Record<string, unknown>; text: string }
 
 export interface AgentsOptions {
+  /** Runtime integration: a room clock and an explicit beat replace the browser timer. */
+  now?: () => number;
+  manual?: boolean;
+  /** Keep an asked-for goal through scripted floor decisions until completion or sixty seconds. */
+  carryFloor?: boolean;
+  restore?: AgentsSaved;
+
   /** Host: what a guide in this slot sees. Game state only: never an account, an address or typed text. Under 2 KB. */
   view: (slot: number) => Record<string, unknown>;
   /** The scripted floor: runs with no AI, over budget, and between AI decisions. Synchronous; never waits. */
@@ -70,7 +77,14 @@ export interface AgentsOptions {
 
 export interface AgentsStats { views: number; dos: number; says: number; asks: number; drops: number; floors: number; viewBytes: number }
 
+export interface AgentsSaved { goals: [number, Goal][]; asks: [number, Ask[]][]; avoid: [number, [number, number][]][]; sayAt: [number, number][]; viewAt: [number, number][]; floorAt: [number, number][]; askAt: [number, number][] }
 export interface Agents {
+  tick(): void;
+  save(): AgentsSaved;
+  forget(slot: number): void;
+  /** Drop one slot's goal so its floor may run at once. Its pacing, its asks and who asked to be left alone all stay. */
+  dropGoal(slot: number): void;
+
   readonly vocab: Vocabulary;
   /** Whether this server's AI may talk (its brain is workers-ai or owner-key, and speech is not off). */
   readonly talking: boolean;
@@ -95,6 +109,7 @@ export interface Agents {
   stop(): void;
 }
 
+const own = <T>(table: Record<string, T> | undefined, key: unknown): T | undefined => table && typeof key === 'string' && Object.hasOwn(table, key) ? table[key] : undefined;
 const TALK = ['workers-ai', 'owner-key'];
 export const AGENT_RULES = Object.freeze({ viewMs: 2050, floorMs: 1000, quietMs: 8000, leaveMs: 10 * 60_000, askMs: 30_000, holdMs: 45_000, askWaitMs: 4000, carryMs: 60_000, viewBytes: 1900 });
 const VIEW_ARG = /^view\.([A-Za-z][A-Za-z0-9_]{0,23})$/;
@@ -127,7 +142,7 @@ export function argsWhy(types: Record<string, ArgType> | undefined, args: unknow
   return null;
 }
 
-export const labelOf = (vocab: Vocabulary, value: unknown): string => vocab.labels?.[String(value)] ?? String(value ?? '').replace(/[-_]+/g, ' ');
+export const labelOf = (vocab: Vocabulary, value: unknown): string => own(vocab.labels, String(value)) ?? String(value ?? '').replace(/[-_]+/g, ' ');
 
 /* ------------------------------------------------------------------ useAgents */
 
@@ -145,7 +160,15 @@ export function useAgents(net: Netplay<any, any, any>, vocab: Vocabulary, opts:
   const askAt = new Map<number, number>();
   const handlers = { say: new Set<(e: SayEvent) => void>(), goal: new Set<(e: GoalEvent) => void>(), ask: new Set<(e: Ask & { slot: number }) => void>() };
   const st: AgentsStats = { views: 0, dos: 0, says: 0, asks: 0, drops: 0, floors: 0, viewBytes: 0 };
-  const wall = (): number => Date.now();
+  const wall = opts.now ?? (() => Date.now());
+  if (opts.restore) {
+    const entries = (v: unknown): [number, any][] => Array.isArray(v) ? v.slice(0, 256).filter((e) => Array.isArray(e) && e.length === 2 && Number.isSafeInteger(e[0]) && e[0] >= 0) : [];
+    const stamp = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= wall();
+    for (const [k, v] of entries(opts.restore.goals)) if (v && own(vocab.goals, v.goal) && stamp(v.at) && v.args && typeof v.args === 'object' && !Array.isArray(v.args)) goals.set(k, { ...v });
+    for (const [k, v] of entries(opts.restore.asks)) if (Array.isArray(v)) asks.set(k, v.slice(0, 3).filter((a) => a && own(vocab.asks, a.k) && stamp(a.at) && Number.isSafeInteger(a.from) && a.from >= 0 && a.args && typeof a.args === 'object' && !Array.isArray(a.args)));
+    for (const [k, v] of entries(opts.restore.avoid)) avoid.set(k, new Map(entries(v).filter(([, until]) => typeof until === 'number' && Number.isFinite(until) && until > wall() && until <= wall() + AGENT_RULES.leaveMs)));
+    for (const [dst, src] of [[sayAt, opts.restore.sayAt], [viewAt, opts.restore.viewAt], [floorAt, opts.restore.floorAt], [askAt, opts.restore.askAt]] as const) for (const [k, v] of entries(src)) if (stamp(v)) dst.set(k, v);
+  }
 
   const guides = (): Slot[] => (net.slots ?? []).filter((s) => s.agent && roles.includes(s.agent.role as 'guide' | 'party'));
   const slotOf = (slot: number): Slot | undefined => guides().find((s) => s.slot === slot);
@@ -171,7 +194,7 @@ export function useAgents(net: Netplay<any, any, any>, vocab: Vocabulary, opts:
   };
 
   function render(id: string, args: Record<string, unknown>, slot: number | null, kind: 'lines' | 'asks' = 'lines'): string | null {
-    const def = kind === 'asks' ? vocab.asks?.[id] : vocab.lines?.[id];
+    const def = kind === 'asks' ? own(vocab.asks, id) : own(vocab.lines, id);
     if (!def) return null;
     const s = slot === null ? undefined : (net.slots ?? []).find((x) => x.slot === slot);
     const me = s ? stripAi(s.name) : 'Guide';
@@ -180,7 +203,7 @@ export function useAgents(net: Netplay<any, any, any>, vocab: Vocabulary, opts:
 
   /** A line the host lets a guide say: from the vocabulary, its arguments fit, not within 8 s of its last. */
   function say(slot: number, line: string, args: Record<string, unknown>): boolean {
-    const def = vocab.lines?.[line];
+    const def = own(vocab.lines, line);
     const now = wall();
     if (!def || !talksOn(net.policy) || now - (sayAt.get(slot) ?? -Infinity) < AGENT_RULES.quietMs) { st.drops += 1; return false; }
     if (argsWhy(def.args, args, lastView.get(slot) ?? null, people()) || touchesAvoided(def.args, args, slot)) { st.drops += 1; return false; }
@@ -197,7 +220,7 @@ export function useAgents(net: Netplay<any, any, any>, vocab: Vocabulary, opts:
 
   function setGoal(slot: number, d: Decision, from: 'brain' | 'floor', answering = true): boolean {
     if (!d.goal) return false;
-    const def = vocab.goals[d.goal];
+    const def = own(vocab.goals, d.goal);
     const args = (d.args ?? {}) as Record<string, unknown>;
     if (!def || argsWhy(def.args, args, lastView.get(slot) ?? opts.view(slot), people()) || touchesAvoided(def.args, args, slot)) { st.drops += 1; return false; }
     const prev = goals.get(slot) ?? null;
@@ -216,13 +239,13 @@ export function useAgents(net: Netplay<any, any, any>, vocab: Vocabulary, opts:
     // A person's ask is answered the way agents.json says (its `goal`): a brain's decision that does something else
     // leaves the ask open, and the floor answers it once the brain has had askWaitMs (a fixed rule, not the model's).
     const open = askAt.has(slot) ? (asks.get(slot) ?? []).at(-1) ?? null : null;
-    const want = open ? vocab.asks?.[open.k]?.goal : undefined;
-    const answering = !open || from === 'floor' || !want || want === d.goal;
+    const want = open ? own(vocab.asks, open.k)?.goal : undefined;
+    const answering = !open || !want || (want === d.goal && Object.entries(open.args).every(([k, v]) => !own(own(vocab.goals, want)?.args, k) || d.args?.[k] === v));
     // What a person asked for is carried through until it is done (or 60 s): a brain's other goal waits.
     const cur = goals.get(slot);
-    if (!open && from === 'brain' && cur && cur.asked && cur.state === 'active' && wall() - cur.at < AGENT_RULES.carryMs && d.goal !== cur.goal) { st.drops += 1; if (speak && d.say) say(slot, d.say, (d.sayArgs ?? {}) as Record<string, unknown>); return; }
+    if (!open && from === 'brain' && cur && cur.asked && cur.state === 'active' && wall() - cur.at < AGENT_RULES.carryMs && (d.goal !== cur.goal || JSON.stringify(d.args ?? {}) !== JSON.stringify(cur.args))) { st.drops += 1; if (speak && d.say) say(slot, d.say, (d.sayArgs ?? {}) as Record<string, unknown>); return; }
     setGoal(slot, d, from, answering);
-    if (open && answering) { askAt.delete(slot); asks.set(slot, []); const g = goals.get(slot); if (g && d.goal === g.goal) g.asked = true; }
+    if (open && answering && goals.get(slot)?.goal === d.goal && JSON.stringify(goals.get(slot)?.args) === JSON.stringify(d.args ?? {})) { askAt.delete(slot); asks.set(slot, []); const g = goals.get(slot); if (g && d.goal === g.goal) { g.asked = true; g.at = wall(); } }
     if (speak && d.say) say(slot, d.say, (d.sayArgs ?? {}) as Record<string, unknown>);
   }
 
@@ -242,21 +265,23 @@ export function useAgents(net: Netplay<any, any, any>, vocab: Vocabulary, opts:
 
   /** The floor for one slot: the game's own decide, on its view. */
   function floor(slot: number, held: boolean): void {
-    if (!opts.decide) return;
+    if (!opts.decide) { floorAt.set(slot, wall()); askAt.delete(slot); asks.set(slot, []); return; }
     const v = viewOf(slot);
     lastView.set(slot, v);
     let d: Decision | null = null;
     try { d = opts.decide(v, { slot, goal: goals.get(slot) ?? null, asks: asksFor(slot) }); } catch { d = null; }
     floorAt.set(slot, wall());
-    if (!d) return;
+    // One floor attempt settles an ask, even if it declines or fails.
+    if (!d) { askAt.delete(slot); asks.set(slot, []); return; }
     st.floors += 1;
     // The floor speaks only for a guide no AI holds (a held guide's own brain speaks for it).
     apply(slot, d, 'floor', !held);
+    askAt.delete(slot); asks.set(slot, []);
   }
 
   /** A person's ask reached the host (theirs, or its own player's). */
   function onAsk(slot: number, k: string, args: Record<string, unknown>, from: number): void {
-    const def = vocab.asks?.[k];
+    const def = own(vocab.asks, k);
     const s = slotOf(slot);
     if (!def || !s || argsWhy(def.args, args, lastView.get(slot) ?? viewOf(slot), null)) { st.drops += 1; return; }
     const now = wall();
@@ -267,7 +292,7 @@ export function useAgents(net: Netplay<any, any, any>, vocab: Vocabulary, opts:
     emit('ask', { slot, k, args, from, at: now });
     const held = s.agent?.seat !== null && s.agent?.seat !== undefined;
     // No AI holds this guide: the floor answers at once. Held: its brain has askWaitMs to answer first.
-    if (!held) floor(slot, false);
+    if (!held) { if (opts.manual) floorAt.delete(slot); else floor(slot, false); }
   }
 
   const offEvent = net.on('event', (e: NetEvent) => {
@@ -286,12 +311,13 @@ export function useAgents(net: Netplay<any, any, any>, vocab: Vocabulary, opts:
       if (ask && e.from !== null && !net.isAgent(e.from) && Number.isInteger(d['slot'])) { onAsk(d['slot'] as number, ask, (d['args'] ?? {}) as Record<string, unknown>, e.from); return; }
       return;
     }
+    if (k === 'agent:offer' && e.from === net.host?.seat && Number.isInteger(d['slot']) && d['view'] && typeof d['view'] === 'object') { lastView.set(d['slot'] as number, d['view'] as Record<string, unknown>); return; }
     // Every other browser: a guide's line the host relayed (Quiet AI already dropped it in the helper). Its words are
     // this browser's own copy of the vocabulary; an argument is a seat, a value of the line's list, or an id.
     const line = /^say:([a-z][a-z0-9_]{0,31})$/.exec(k)?.[1];
-    if (line && d['ai'] === true && Number.isInteger(d['slot'])) {
+    if (e.from === net.host?.seat && line && d['ai'] === true && Number.isInteger(d['slot'])) {
       const args = (d['args'] ?? {}) as Record<string, unknown>;
-      const def = vocab.lines?.[line];
+      const def = own(vocab.lines, line);
       const ids = Object.fromEntries(Object.entries(def?.args ?? {}).map(([n, t]) => [n, t]).filter(([, t]) => typeof t === 'string' && VIEW_ARG.test(t)).map(([n, t]) => [VIEW_ARG.exec(t as string)![1], /^[a-z0-9][a-z0-9_-]{0,39}$/.test(String(args[n as string] ?? '')) ? [args[n as string]] : []]));
       if (!def || argsWhy(def.args, args, ids, null)) { st.drops += 1; return; }
       const text = render(line, args, d['slot'] as number);
@@ -300,7 +326,7 @@ export function useAgents(net: Netplay<any, any, any>, vocab: Vocabulary, opts:
   });
 
   // The host's beat: views to the guides an AI holds (at most one every 2 s each), the floor for the rest.
-  const timer = setInterval(() => {
+  const beat = (): void => {
     if (!net.isHost || net.offline) return;
     const now = wall();
     for (const s of guides()) {
@@ -322,21 +348,27 @@ export function useAgents(net: Netplay<any, any, any>, vocab: Vocabulary, opts:
       const waiting = held && askAt.has(s.slot) && now - (askAt.get(s.slot) as number) < askWaitMs;
       // The floor decides for a guide with no AI's decision in force, at most once a second; an ask an AI left
       // unanswered for askWaitMs is answered by the floor (silently: a held guide's lines are its brain's).
-      if ((!brainFresh && !waiting && now - (floorAt.get(s.slot) ?? -Infinity) >= AGENT_RULES.floorMs) || (held && askAt.has(s.slot) && !waiting)) floor(s.slot, held);
+      const carried = opts.carryFloor && g?.asked && g.state === 'active' && now - g.at < AGENT_RULES.carryMs && !askAt.has(s.slot);
+      if (!carried && ((!brainFresh && !waiting && now - (floorAt.get(s.slot) ?? -Infinity) >= AGENT_RULES.floorMs) || (held && askAt.has(s.slot) && !waiting))) floor(s.slot, held);
     }
     // Slots no longer an AI's: forget them.
     const live = new Set(guides().map((s) => s.slot));
-    for (const k of [...goals.keys()]) if (!live.has(k)) goals.delete(k);
-  }, 250);
+    for (const map of [goals, asks, avoid, sayAt, viewAt, floorAt, askAt, lastView]) for (const k of [...map.keys()]) if (!live.has(k)) map.delete(k);
+  };
+  const timer = opts.manual ? null : setInterval(beat, 250);
 
   const agents: Agents = {
+    tick: beat,
+    forget: (slot) => { for (const map of [goals, asks, avoid, sayAt, viewAt, floorAt, askAt, lastView]) map.delete(slot); },
+    dropGoal: (slot) => { goals.delete(slot); floorAt.delete(slot); },
+    save: () => ({ goals: [...goals], asks: [...asks], avoid: [...avoid].map(([k, v]) => [k, [...v]]), sayAt: [...sayAt], viewAt: [...viewAt], floorAt: [...floorAt], askAt: [...askAt] }),
     vocab,
     get talking() { return talksOn(net.policy); },
     guides,
     goalOf: (slot) => goals.get(slot) ?? null,
     asksFor,
     ask(slot, k, args = {}) {
-      const def = vocab.asks?.[k];
+      const def = own(vocab.asks, k);
       const s = slotOf(slot);
       if (!def || !s) return false;
       const seat = s.agent?.seat ?? null;
@@ -353,6 +385,7 @@ export function useAgents(net: Netplay<any, any, any>, vocab: Vocabulary, opts:
       return true;
     },
     askButtons(slot, offer = {}) {
+      if (!slotOf(slot)) return [];
       const out: AskButton[] = [];
       const view = { ...(lastView.get(slot) ?? {}), ...offer };
       for (const [k, def] of Object.entries(vocab.asks ?? {})) {
@@ -362,7 +395,7 @@ export function useAgents(net: Netplay<any, any, any>, vocab: Vocabulary, opts:
         const name = names[0] as string;
         const type = (def.args as Record<string, ArgType>)[name];
         const m = typeof type === 'string' ? VIEW_ARG.exec(type) : null;
-        const values = Array.isArray(type) ? [...type] : m ? (Array.isArray(view[m[1] as string]) ? (view[m[1] as string] as unknown[]) : []) : [];
+        const values = Array.isArray(type) ? [...type] : type === 'player' ? (net.seat === null ? [] : [net.seat]) : m ? (Array.isArray(view[m[1] as string]) ? (view[m[1] as string] as unknown[]) : []) : [];
         for (const v of values.slice(0, 4)) {
           const value = v && typeof v === 'object' ? (v as { id?: unknown }).id : v;
           const text = render(k, { [name]: value }, slot, 'asks');
@@ -378,7 +411,7 @@ export function useAgents(net: Netplay<any, any, any>, vocab: Vocabulary, opts:
       g.at = wall();
       const s = slotOf(slot);
       // A guide no AI holds decides again at once; one an AI holds hears it in its next view.
-      if (s && (s.agent?.seat ?? null) === null) floor(slot, false);
+      if (s && (s.agent?.seat ?? null) === null) { if (opts.manual) floorAt.delete(slot); else floor(slot, false); }
     },
     render,
     on(kind: 'say' | 'goal' | 'ask', fn: (e: never) => void) {
@@ -386,7 +419,7 @@ export function useAgents(net: Netplay<any, any, any>, vocab: Vocabulary, opts:
       return () => { (handlers[kind] as Set<unknown>).delete(fn); };
     },
     stats: () => ({ ...st }),
-    stop() { clearInterval(timer); offEvent(); },
+    stop() { if (timer) clearInterval(timer); offEvent(); },
   } as Agents;
   return agents;
 }

package/bin/homie-studio.mjs

@@ -169,7 +169,7 @@
  *                                          spent from the guides' day; --model compares a model before setting it)
  *   homie-studio shop                     is the studio's shop selling (its own Stripe), and if not, what is missing
  *   homie-studio shop init [--supporter] [--currency usd] [--price 500] [--managed]   shop.json and SELLING.md
- *   homie-studio shop check               shop.json against the kit's rules (real money, nothing random, the kids rules)
+ *   homie-studio shop check               shop.json against studio settings and provider requirements
  *   homie-studio shop connect [--managed] [--live]   a page on THIS computer where the owner pastes the studio's
  *                                         restricted Stripe key; with it this makes the webhook (0.24.3), and the key
  *                                         and the webhook's secret go straight to the Worker secrets, never a chat or a
@@ -295,6 +295,13 @@
  *                                          id, and an unsigned release is said as UNSIGNED and is not a success); run:
  *                                          the built copy, here; steam: Steam's build file; ci: a GitHub workflow that
  *                                          builds all five. Nothing is ever uploaded to Steam or a store
+ *   homie-studio standalone run <game> --for ios --device
+ *                                         the game on the ONE iPhone or iPad plugged in to this Mac: built, signed for
+ *                                          your Apple team (HOMIE_APPLE_TEAM, else the keychain's only one), installed
+ *                                          over the cable, started, and then looked for among the phone's running
+ *                                          programs. --device is your yes to what it changes outside this computer: it
+ *                                          adds the phone to your Apple team's list of development devices. A phone with
+ *                                          Developer Mode off, locked, or not trusting this Mac is said with its fix
  *
  *   homie-studio statusline               the current build in one line (what Claude Code's status line shows)
  *   homie-studio statusline --install [--project <folder>]
@@ -361,7 +368,7 @@ import { standaloneDeployNotes } from '../lib/standalone.mjs';
 
 const argv = process.argv.slice(2);
 const flags = new Map();
-const BOOL_FLAGS = ['off', 'revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open', 'reopen', 'kids', 'remote-ai', 'dry-run', 'verify', 'maps', 'profile', 'hands-on', 'automatic', 'unlock', 'confirm', 'no-library', 'no-validate', 'rigged', 'no-rig', 'supporter', 'managed', 'live', 'send', 'accept-tos', 'quiet', 'no-local-ai', 'timestamps', 'overwrite', 'own-route', 'before', 'release'];
+const BOOL_FLAGS = ['off', 'revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open', 'reopen', 'kids', 'remote-ai', 'dry-run', 'verify', 'maps', 'profile', 'hands-on', 'automatic', 'unlock', 'confirm', 'no-library', 'no-validate', 'rigged', 'no-rig', 'supporter', 'managed', 'live', 'send', 'accept-tos', 'quiet', 'no-local-ai', 'timestamps', 'overwrite', 'own-route', 'before', 'release', 'device'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
@@ -803,9 +810,11 @@ const OUTWARD_FLAGS = {
   'lounge mod': ['url', 'remove'], 'lounge remove': ['url', 'all'],
   'chat remove': ['url', 'all'], 'chat budget': ['url'],
   'servers close': ['url', 'reopen'], 'servers level': ['url'], 'servers member': ['url', 'role', 'remove'],
-  'shop connect': ['url', 'managed', 'live'], 'shop disconnect': ['url'], 'shop refund': ['url', 'reason', 'note'], 'shop statements': ['url', 'period', 'send'],
+  'shop connect': ['url', 'managed', 'live'], 'shop disconnect': ['url'], 'shop refund': ['url', 'reason', 'note'], 'shop statements': ['url', 'period', 'send', 'cursor'],
   'agents pass': ['url', 'label', 'server', 'hands', 'role', 'days'], 'agents revoke': ['url'], 'agents brain': ['url', 'budget', 'remove'],
   'agents sit': ['url', 'server', 'pass', 'label', 'brain'],
+  // With --device it adds a phone to the person's Apple team and installs on it: a flag it does not know stops it.
+  'standalone run': ['for', 'device', 'site'],
 };
 /** Every command takes these: how it answers, never what it does. */
 const ANY_COMMAND = ['json', 'help', 'version'];
@@ -1046,7 +1055,7 @@ async function main() {
     }
     if (sub === 'orders') return shopOrders(root, { url });
     if (sub === 'refund') return shopRefund(root, positional[2], { url, reason: flags.get('reason'), note: flags.get('note') });
-    if (sub === 'statements') return shopStatements(root, { url, period: flags.get('period'), send: flags.has('send') });
+    if (sub === 'statements') return shopStatements(root, { url, period: flags.get('period'), cursor: flags.get('cursor') ?? '', send: flags.has('send') });
     return { ok: false, command: 'shop', why: `unknown: shop ${sub} (init, check, connect, disconnect, catalog, orders, refund, statements)` };
   }
   if (cmd === 'agents') {