@homie-rocks/studio 0.32.1 → 0.33.0

package/shop/SHOP.md

@@ -14,8 +14,7 @@ At the studio's root, reviewed in git. Nothing secret is ever in it.
 {
   "till": "stripe",
   "currency": "usd",
-  "refundDays": 14,
-  "capPerPlayerMonth": 5000,
+  "policy": { "preset": "protective" },
   "items": [
     { "id": "supporter", "kind": "supporter", "name": "Supporter", "price": 500, "days": 365,
       "gives": ["badge:supporter", "credits-name"], "badge": "Supporter" },
@@ -30,38 +29,78 @@ At the studio's root, reviewed in git. Nothing secret is ever in it.
 | Field | Meaning |
 |---|---|
 | `till` | `stripe`: the studio is the seller, Stripe Tax on (`automatic_tax`). `stripe-managed`: Stripe Managed Payments, Stripe's Link, LLC is the seller of record and files the tax (3.5% more; turn it on in Stripe first). `off`. |
-| `currency` | one currency with cents (`usd`, `cad`, `eur`, `gbp`, `aud`…). |
-| `refundDays` | 14 to 60: a player refunds an unused item themselves within it. |
-| `capPerPlayerMonth` | cents one player may spend here in a month: 100 to 5000. Lower it, never remove it. |
-| `items[].kind` | `cosmetic` (a look), `supporter` (a badge, thanks), `pass` (a season), `unlock` (a mode, a chapter, the full game), `tip` (pay what you want, `min` to `max`). |
-| `items[].price` | whole cents, real money. Under 300 the check warns (fees eat it). |
+| `currency` | one Stripe presentment currency, including zero-decimal currencies such as `jpy`. |
+| `refundDays` | Optional days for self-service refunds of unused items. No default or ceiling; omitted or null means ask the studio. |
+| `capPerPlayerMonth` | Optional amount one player may spend per calendar month, in Stripe currency units. No default or ceiling; omit or null for no cap. |
+| `items[].kind` | Any nonempty label chosen by the studio. `tip` uses a buyer-chosen amount, with an optional studio `max`. Other kinds use a fixed price; a label does not add recurring billing or fulfillment. |
+| `items[].price` | whole Stripe currency units. No Homie maximum. Stripe minimums and currency rules apply. |
 | `items[].gives` | the entitlement keys the game reads: `skin:ember`, `badge:supporter`. A `badge:` key shows beside the player's name in rooms and on their account page. |
-| `items[].days` / `starts` / `ends` | how long it lasts; a season's dates (shown as dates, never a countdown). |
+| `items[].days` / `starts` / `ends` | Optional duration or sale dates, without a Homie duration ceiling. Fractional days are allowed; end times are rounded to whole milliseconds and must fit safe arithmetic and the JavaScript timestamp range. |
 | `items[].game` | only in that game's shop (left out: every game's). |
-| `items[].advantage` | `true` when it changes how the game plays: never offered, and never counted as owned, on a beginner or kids server. |
+| `items[].advantage` | `true` when it changes how the game plays. The studio policy decides whether it is offered or counted on beginner and kids servers. |
 | `items[].taxCode` | a Stripe product tax code. Managed Payments needs one: by default `txcd_10201000` (video games, downloaded, permanent) or `txcd_10201001` (limited time). |
 | `referrals` | what this studio pays a referrer for a new player's purchase (left out: nothing). |
 | `catalog` | where the items are Products in Stripe: `["test"]`, `["test", "live"]`. `homie-studio shop catalog` writes it once Stripe's catalog matches; the Worker's checkouts then name each item's Product (0.24.3). |
 
-`homie-studio shop check`, and every `homie-studio build`, refuse: anything that names chance, odds, random, a
-crate, a box, a mystery, loot, a gacha, a spin or a roll; fields for odds or drop pools; a countdown, timer or
-"hurry" field; gems, coins, points or any currency of the studio's own; subscriptions and paid services (later
-versions); a cap over 5000 or a refund window under 14 days. A studio whose studio.json says
-`"audience": "kids"` sells nothing at all.
+## The studio decides
 
-## Who may buy
+There is no Homie ceiling on item prices, tips, catalog size, entitlement count, text lengths, durations,
+refund days, monthly spending or referral terms. The existing amount fields keep their meaning: a cap or
+refund window already written in shop.json stays in effect until the studio edits or removes it.
+No migration or rewrite is needed. `shop init` writes an explicit protective policy and no spending cap,
+refund window or referral agreement. Settings are public, readable and editable in shop.json.
 
-The Worker decides, for every item and every player (`worker/shop-rules.mjs` `wayFor`):
+The studio is responsible for applicable law and its payment provider's terms wherever it sells. These settings
+are choices, not a statement that a sale is legal or permitted by Stripe. This is information, not legal advice.
 
-| The player | What happens |
-|---|---|
-| on a kids server, or in a kids studio | no shop at all: nothing listed, `shop.open()` says nothing is sold here |
-| a guest (no passkey) | "make an account first" (a purchase would be lost with a cookie) |
-| an account that has not answered | the one neutral age question: the year they were born, no default, nothing hinting which answer opens anything; kept only as a band |
-| an account that said under 13 | nothing, ever; the account is treated as a kids account from then on |
-| 13 to 17 | "ask a grown-up": a one-time link (a week) the teen passes on; the parent opens it on their own device, sees what and for whom, ticks that they are the parent or guardian, and pays in their own name on Stripe's page; the item lands on the teen's account |
-| an adult | Stripe's own hosted Checkout, one item at a time, with the real-money price and its own confirm |
-| over the monthly cap | not until next month |
+### Policy presets
+
+`policy.preset` selects `protective`, `adults-only` or `custom`. An absent policy uses `protective`, preserving
+the existing protections. Override any row directly in `policy`; `shop init` writes all rows so they are easy
+to read and edit. Explicit overrides take precedence when you change presets; remove an override to inherit
+the preset value. Invalid values fail validation rather than silently relaxing a rule.
+
+| Setting | protective (new shop default) | adults-only | custom |
+|---|---|---|---|
+| `withdrawalAcknowledgement` | true | true | true |
+| `childAge`, `adultAge` | 13, 18 | 13, 18 | 13, 18 |
+| `requireAccount` | true | true | false |
+| `ageQuestion` | true | true | false |
+| `children` (under 13) | deny | deny | allow |
+| `teens` (13–17) | parent | deny | allow |
+| `kidsStudio`, `kidsServer` | false | false | true |
+| `kidsAdvantages`, `beginnerAdvantages` | false | false | true |
+| `paidRandomRewards`, `countdownOffers`, `virtualCurrency` | false | false | true |
+| `supporterAdvantages`, `repeatPurchases`, `refundUsedItems`, `televisionCheckout` | false | false | true |
+
+`children` and `teens` each accept `deny`, `parent`, or `allow`. The neutral age question stores only a band,
+never the birth year. `childAge` and `adultAge` set the band thresholds (13 and 18); the neutral picker spans 120 years. A parent's link lasts a week as a security expiry. Account-free purchases use a guest
+session in this browser; clearing its cookie loses access, so buyers can add a passkey to keep their purchases.
+The protective preset hides the shop on kids servers and kids studios, blocks purchases under 13, requires
+parent checkout for teens, hides game advantages on beginner and kids servers, refuses paid randomness and
+countdowns, and sends TV shoppers to a phone. Nothing relaxes those protections without a studio setting.
+
+For example, `{ "policy": { "preset": "protective", "repeatPurchases": true } }` changes only repeat purchases.
+The custom preset deliberately enables all policies; choose it only as a considered studio decision.
+`kind` is descriptive, not a whitelist: services and subscription labels still use the existing one-time checkout.
+Virtual-currency keys and random-reward metadata do not implement a wallet or random-reward fulfillment engine.
+
+### Currency and abuse protection
+
+Amounts use Stripe's API units: `500` USD is $5; `500` JPY is ¥500. ISK and UGX retain Stripe's two-decimal API
+representation but require multiples of 100. BHD, JOD, KWD, OMR and TND use scale 1000. Stripe's current currency documentation does not state a divisible-by-ten charge rule; the toolkit does not refuse those amounts and shows Stripe's error if Stripe refuses a checkout. The check warns about the documented settlement-currency minimum where
+known; Stripe decides the actual minimum after conversion and any payment-method maximum at checkout.
+Errors name Stripe as the source. See [Stripe currencies](https://docs.stripe.com/currencies).
+Zero-price Checkout orders are supported and can be revoked without a Stripe refund. Every amount setting accepts only nonnegative whole minor units (numbers or decimal numeric strings); a fractional amount stops the build, names the setting and says what to write. No amount is rounded. All amounts must fit JavaScript safe integer arithmetic. Homie does not impose its own price ceiling or fee floor.
+
+`purchaseAttemptsPerMinute` defaults to 6 per account and `purchaseAttemptsPerAddressPerMinute` to 600 per
+address. Both accept positive whole numbers (including decimal numeric strings). The larger address rate
+allows households, schools and venues to share a connection; rotating addresses still hits the account rate.
+`guestBuyersPerAddressPerHour` defaults to 600 new guest buyers per address per hour, allowing a venue or school to arrive together. It must be a positive whole number; 0 cannot disable it accidentally. The existing `PLAYER_LIMIT_DAILY` also applies.
+Checkout, parent links and parent payments have separate counts, per Worker instance. Referral statements use
+`REFERRAL_STATEMENTS_PER_MINUTE` (30 per address), `REFERRAL_STATEMENTS_GLOBAL_PER_MINUTE` (30 globally), and
+`REFERRAL_STATEMENT_BYTES` (65536). Written values must be positive whole decimal numbers; invalid values produce a named settings error. Security
+checks for origins, sessions, signed webhooks and request sizes remain. They protect the studio's money.
 
 ## In a game
 
@@ -72,10 +111,10 @@ await shop.ready;                        // { open, kids, screen }
 if (shop.has('skin:ember')) useEmber();  // synchronous: fine in a render loop
 shop.on('change', (owns) => redraw());   // a purchase landed, or a refund took one back
 buyButton.onclick = () => shop.open('ember-skin');   // the store sheet (a code to scan on a TV)
-shop.used('skin:ember');                 // equipped: it leaves the player's own refund window
+shop.used('skin:ember');                 // marks it used; the studio refund policy applies
 ```
 
-Rules for the game: open the shop only from a button the player pressed, never from the play, start or wake
+The protective preset recommends opening the shop only from a button the player pressed, never from the play, start or wake
 button, never on a timer; show prices in real money; never draw a countdown; never sell randomness; do nothing
 differently for a supporter on a beginner server.
 
@@ -85,7 +124,7 @@ keeps running, and the shell looks again when the tab comes back: `change` fires
 
 **Badges in rooms.** A player whose account owns a `badge:` key carries it on their seat: `net.players()` gives
 `peer.badge` ("Supporter"), set by the studio's Worker from what the account owns when the player connects (a
-hello can never claim one). None on a kids server, none for an AI.
+hello can never claim one). Kids-server badges follow `policy.kidsServer`; AI seats have no purchases.
 
 ## The money path
 
@@ -96,8 +135,33 @@ Stripe ─ signed webhook ─► POST /api/shop/hook: order paid → entitlement
 homie.rocks: not involved at any step.
 ```
 
-- The order row is written before Stripe is called; the Checkout Session carries the order, the player and the
+- The order row atomically reserves against the studio monthly cap before Stripe is called. Reservations are
+  released on confirmed expiry, failure, missing session or refund, or an explicit owner release, never merely because a webhook is late; the Checkout Session carries the order, the player and the
   item in its metadata; the hook checks the session matches the order (player, price) before it grants anything.
+- A sessionless reservation stops counting after its 31-minute creation window plus a one-minute margin.
+  A session with no final result, including a bank payment still processing, keeps counting even past expiry.
+  Shop GETs never call Stripe. With a cap configured, only a purchase refused by the atomic cap check waits
+  for reconciliation: up to three rows in parallel, each with a two-second timeout. Successful purchases continue
+  reconciliation in `waitUntil` (the shop has no scheduled handler). Rows are atomically claimed before reading
+  [Stripe's session and expanded payment](https://docs.stripe.com/api/checkout/sessions/retrieve).
+  Successful reads set a per-row interval of one minute (five minutes for processing bank payments),
+  growing with age to one hour. Failed reads retry after a short backoff of about one minute and log the order and reason. With more than three lost rows, a refusal may need another purchase attempt.
+  Paid counts in the month of [the Stripe charge's creation time](https://docs.stripe.com/api/charges/object#charge_object-created);
+  missing payment time, pending or unreachable keeps counting. Confirmed expiry or failure releases it.
+  Stripe's [404 resource_missing](https://docs.stripe.com/error-codes#resource-missing) means this key's account
+  has no such session, not that no payment can follow: the row stops reserving the cap and is shown as `missing` in the office.
+  The office lists unresolved orders first, with Next orders for more. Release reservation records the confirming
+  owner's account (or a fingerprint of the owner's office sign-in session) and time in the office-only note, and asks Stripe to
+  [expire an open Checkout Session](https://docs.stripe.com/api/checkout/sessions/expire). It does not refund a payment.
+  A verified payment still grants the item and counts toward spending, including after a missing mark or release,
+  and can be refunded from the office. Duplicate events change nothing. Players see their previous unfinished
+  order state, never the internal mark or note.
+  An owner release or missing mark can free space for another purchase before a late payment counts again;
+  new reservations still obey the configured cap. Test orders never count toward a live
+  cap. Free orders remain available if an owner lowers a cap below prior spending. Partial refunds keep the whole
+  price counted; full refunds and lost disputes release it. No spending SUM runs when the cap is absent.
+  Deploy applies `0010_shop_reservations.sql` and `0011_shop_statements.sql`; readiness names these migrations
+  if the required schema is absent.
 - The webhook's `Stripe-Signature` is checked (HMAC-SHA256 of `<t>.<payload>` with the endpoint's `whsec_`
   secret, within five minutes); each event id is handled once; a test event never touches a live shop.
 - Paid: the entitlements are granted. Refunded: that one order's entitlements are revoked. A dispute: nothing
@@ -107,7 +171,7 @@ homie.rocks: not involved at any step.
   page lists the player's orders and badges; `/api/player/export` includes them; deleting an account asks first
   when it owns things, and keeps the order rows without the player.
 - Each Checkout Session says beside the pay button that the item is delivered at once (the EU and UK withdrawal
-  acknowledgement) and that an unused item can still be refunded.
+  acknowledgement) and the studio's configured refund terms. `policy.withdrawalAcknowledgement` is true in every preset, restoring the existing wording, and is editable. Stripe caps product names at 5000 characters, descriptions at 40000 and submit wording at 1200; the build reports these provider constraints without truncation.
 
 ## Setting it up (the AI does the commands; the owner only uses Stripe's pages and one page here)
 
@@ -180,8 +244,33 @@ Approvals), and the webhook finishes it. Reconnect with a plain restricted key t
 "How are sales?": `homie-studio shop` and `shop orders` (the studio's own books, no names), and through Stripe's MCP,
 read-only, `stripe_analytics` or `stripe_api_read` on the balance, payouts and checkout sessions.
 
+## Referral pages
+
+`/api/shop?cursor=...` serves 100 items per page and returns `nextCursor`. The shop page and in-game sheet offer the next page.
+The office's `/_studio/api/shop?cursor=...` pages by referrer, with exact SQL totals and sale counts shown once per referrer and currency.
+`/_studio/api/shop/lines?via=...&currency=...&cursor=...` pages the sales inside that book without repeating its totals.
+Statement pages use `/_studio/api/shop/statements?period=YYYY-MM&cursor=...`; `shop statements --cursor ...` reads the next page.
+One signed statement per referrer and currency has its totals on the first page only; continuation pages carry lines. A new first page replaces all previously received pages for that period and currency.
+Read-only statement views read the current lines without making stored editions.
+`shop statements --send` and the office's Send statements button save their progress and immutable lines in D1.
+Keep the command or tab open to continue; close midway and start again to resume safely, without doubles or skipped
+pages. After completion, starting again sends a fresh edition safely. Failed pages retry three times with exponential
+backoff (at least a minute for rate refusals). Persistent failures name the referrer, stop its remaining pages and
+continue the rest; starting a fresh run retries those referrers. The CLI reuses one office key, renewing its expiry
+near ten minutes. Mark paid applies only to the selected currency and cannot change the edition being sent.
+Received signed pages are available at `/_studio/api/shop/received?seller=...&period=...&cursor=...`. No row is hidden by a row cap.
+
+
+
 ## Referrals
 
+The studio sets `rate` (a nonnegative share, including values over 100%), `windowDays`, `capPerPlayer`,
+`holdDays`, `minimumInvoice` and accepted invoice methods. No ceilings or forced relation between hold and
+refund days. Omitted window and per-player cap impose neither; omitted hold means no hold and omitted minimum
+invoice imposes no minimum. `rate` keeps the existing 10% suggestion when referrals are explicitly enabled.
+An absent `referrals` pays nothing. Published invoice terms are settled by the studio, outside Homie.
+
+
 - A link with `?via=<host>` (another studio, homie.rocks, anywhere) opened by a person whose browser has never
   been to this studio leaves a signed cookie with the host and the time (only on a studio that pays referrals;
   never a prefetch, a crawler, this site, or a server's page or room).

package/shop/shop.ts

@@ -15,10 +15,8 @@
  * answers this module by postMessage, only for THIS game. The Worker decides: an item bought with the studio's own
  * Stripe, paid (the signed webhook said so), not refunded, not ended. A game never sees a card, an email or an order.
  *
- * THE KIDS RULES (the kit's, not the game's to change): on a kids server there is no shop (`open` is false, `kids` is
- * true, `open()` shows "nothing is sold here"); on a beginner or kids server anything with a play advantage counts as
- * NOT owned; on a television `open()` shows only a code to scan and buy on a phone. A game never shows a countdown, a
- * random reward for money, or a buy button on its play button.
+ * STUDIO POLICIES: the shell follows shop.json. The protective preset closes kids shops, hides advantages on
+ * beginner and kids servers, and shows a code to buy on a phone from a TV. The studio can edit each policy.
  *
  * Without a shell (a game opened as a file, a dev server, a studio with no shop) everything is empty and `open()` does
  * nothing, so the same code runs everywhere. It has no imports and uses only erasable TypeScript.
@@ -57,14 +55,14 @@ export interface Shop {
   /** Show the store sheet, at one item if given. Call it from a button the player pressed, never on a timer. */
   open(item?: string): void;
   close(): void;
-  /** The player used something (equipped it, played with it): it leaves the player's own refund window. */
+  /** Mark an item used; the studio's refundUsedItems policy decides whether self-service refunds still apply. */
   used(key: string): Promise<boolean>;
   on(ev: 'change', fn: (owns: string[]) => void): () => void;
   on(ev: 'closed', fn: () => void): () => void;
 }
 
 type Msg = Record<string, unknown> & { t?: string; q?: number; ev?: string; ok?: boolean };
-const KEY = /^[a-z0-9][a-z0-9_.:-]{0,63}$/;
+const KEY = /^[^\u0000-\u001f\u007f]+$/;
 
 export function createShop(opts: ShopOptions = {}): Shop {
   const g = globalThis as unknown as { HOMIE_NET?: { shop?: boolean }; parent?: unknown; addEventListener?: typeof addEventListener };
@@ -87,9 +85,9 @@ export function createShop(opts: ShopOptions = {}): Shop {
   };
   const setOwns = (next: unknown): boolean => {
     const list = Array.isArray(next) ? next.map(String).filter((k) => KEY.test(k)) : [];
-    const before = owns.slice().sort().join(',');
+    const before = JSON.stringify(owns.slice().sort());
     owns = list;
-    return list.slice().sort().join(',') !== before;
+    return JSON.stringify(list.slice().sort()) !== before;
   };
   if (target && g.addEventListener) {
     g.addEventListener('message', (e: MessageEvent) => {

package/site/SITE.md

@@ -398,8 +398,7 @@ A studio with a `shop.json` ([../shop/SHOP.md](../shop/SHOP.md)) has `/shop/` (i
 one neutral age question, Buy on Stripe's own page, or a link for a parent), `/shop/thanks`, `/shop/refunds/` (the
 refund policy every seller publishes) and `/shop/parent/<link>` (what a parent opens). The account page lists the
 player's purchases and badges, with the self-serve refund of an unused item. A play page whose game the studio
-sells something for carries the store sheet (the game's `shop.open()`, and Shop in the room sheet); on a kids server
-there is none, and the big screen's sheet is a code to buy on a phone. With a `shop.json`, `/shop/` belongs to the
+sells something for carries the store sheet (the game's `shop.open()`, and Shop in the room sheet); the protective shop policy hides it on kids servers and sends big-screen shoppers to a phone. The studio can edit these policies in shop.json. With a `shop.json`, `/shop/` belongs to the
 shop (a `site/pages/shop/` is not served); without one it is the studio's own. The directory manifest says only
 whether the shop is open and its till.
 
@@ -474,3 +473,121 @@ posts to a `/cdn-cgi/rum` a Worker does not serve). Generated pages are never fr
 strict-origin-when-cross-origin` (another studio's stats see which site sent a visitor, never the path). The
 play page and the game may be framed by the site itself and by the https origins studio.json lists in
 `"site": { "frameAncestors": ["https://…"] }`.
+
+## Play from a post
+
+Post a public game's landing link (`/<id>/`) or Play link (`/<id>/play`) on X.
+When X shows a player card, its phone apps show the game's picture with a play
+button; one tap opens `/<id>/play/embed` full screen inside X's in-app browser.
+The player goes straight into a public room with a guest name and seat. On X's
+website, third-party game cards open the posted link in a new tab. Post the player
+address itself when that new tab should go straight into the game.
+
+The player address uses the same Play code with a layout flag. Opened as a page
+of its own on a phone, the game, the room button and the room sheet keep to the
+screen's safe area; cross-origin frames also work when the host permits them. Open
+Graph tags keep their previous picture for other platforms. An owner's hand-written
+Twitter tags on a custom landing take precedence as a set.
+
+The switch is on by default. The tags go out on an HTTPS site for a game with a
+local picture the build has measured: it tries the wide landing still, the landing
+cover, the game's cover, then the studio's social picture, and takes the first one
+X's reference says will render: JPG, PNG, WEBP or GIF, at least 68,600 pixels
+(262×262, or 350×196), under 5 MB. A picture that fails one of those, or that the
+build cannot read whole, produces a warning naming the file and the rule, and the
+page keeps the picture card it had. Remote pictures cannot be measured by the build.
+Starters do not include a cover: supply one before expecting player tags.
+
+The player is advertised as 480×480. That is Homie's choice, not a rule of X's: the
+two game pages whose posts showed a play button when this was written both
+advertise 480×480, and a square player at a phone's post width (about 358 pixels)
+leaves a framed game room for its own dialogs, where a 16:9 one is 201 pixels tall.
+X's reference says the picture "should" have the player's dimensions; it does not
+make that a condition, and both of those pages use wider pictures (1200×628 and
+1200×800). So any shape gets the card: a standard 1200×630 social picture, a 16:9
+still or a square. X's website draws the picture as a small square thumbnail
+whatever its shape.
+
+`"twitterSite": "@yourstudio"` in `studio.json`'s `site` object adds `twitter:site`
+to the tags. It is optional: X's reference lists the tag, neither of those two
+pages carries it, and Homie never withholds a card for the lack of it.
+
+Play, Watch and the player address carry the card's tags (and Open Graph tags beside
+them) only when the game has a player card; without one they carry no social tags.
+
+To switch it off, set `"playerCard": false` inside `studio.json`'s `site` object,
+or in `games/<id>/game.json` for one game. Remove the switch or set it to `true`
+to turn it back on; studio-wide off wins. A television game with no single-screen
+view must set `"screen": { "singleScreen": false }` (keep its other settings).
+Private and invite-only games never advertise or serve the player address.
+
+`site.playerCardOrigins` replaces the embed's allowed HTTPS ancestors, including
+intermediate frames. The default is
+`["https://x.com", "https://*.x.com", "https://twitter.com", "https://*.twitter.com"]`.
+An empty list denies framing. At most eight valid origins are kept. Wildcards must
+name a domain; paths, credentials, invalid ports and arbitrary CSP text are refused.
+This changes neither ordinary pages nor `site.frameAncestors`. The player's CSP
+is Play's policy with the frame ancestors changed; its inner game remains isolated
+from the studio's cookies and storage.
+
+Blocked or cleared storage still permits a guest seat. Opened as a page of its
+own, and while the tab's storage works, a reload, Back or Forward comes back to the
+same room, seat and guest name; in a frame every instance is a new guest (two posts
+of one game on a page are two players). If the lobby does not answer, the player
+joins the room `main`, exactly as Play does. Saves may not follow a guest back to
+the studio site. Sound starts on the first press, including when a game requested
+sound during startup. Pointer lock, fullscreen and gamepads depend on the host's
+permissions; use keys or touch if unavailable.
+
+The room button reads **Room N · Site**, and the first row of its sheet is **Open on
+the studio's site**, a 44-pixel link carrying the room to Play: it is in view when
+the sheet opens, in a frame 201 pixels tall too. The sheet scrolls in short frames
+and says when there is more below. In a frame, account, purchases, Game and
+big-screen links open a tab of their own, and words about tabs and "this post" are
+shown only there; as a page of its own the same links navigate the tab. Signing in
+from the player comes back to Play in the same room, never to the guests-only
+player. No purchase starts in the player. If popups are blocked, the sheet shows
+the address to copy. A host that removes same-origin permission gets a clear
+connection message and exit instead of an endless loader.
+
+With `homie-studio dev` running, open `/<id>/play/preview` locally. It uses a different
+loopback hostname and X's observed sandbox: `allow-scripts allow-same-origin
+allow-popups allow-popups-to-escape-sandbox`, `allow="autoplay; fullscreen; web-share"`,
+and `scrolling="no"`. Preview-only loopback ancestors never apply to deployed sites.
+Also open `/<id>/play/embed` directly at phone and desktop sizes.
+
+From the toolkit checkout,
+`CHROME_PATH=/path/to/chrome node --test packages/studio/test/embed*.test.mjs`
+runs the five starters at the player address in real Chrome, as a page of its own
+and framed. The starter run also needs Wrangler: installed in the toolkit's
+`node_modules`, or `WRANGLER_PATH` pointing to an installed
+`wrangler/bin/wrangler.js`. Without `CHROME_PATH` the browser checks skip, and
+without Wrangler the starter run skips; all bindings run locally without
+credentials.
+
+**Evidence and limits (2026-10-08):**
+
+- X's archived player-card reference (developer.x.com, "Cards: player card")
+  documents the phone-app picture/play button and top-level in-app browser, the
+  tags (`twitter:site` among them), HTTPS, and the picture conditions above. Its
+  written policy reserves this card for linear audio/video and explicitly excludes
+  gaming and sign-in requirements. This is not a supported game API. The URL may
+  now redirect; the
+  [official sample](https://github.com/xdevplatform/cards-player-samples/blob/main/player/page.html)
+  also shows the tags.
+- X's [public web-client bundle](https://abs.twimg.com/x-web/x-web/assets/article-card-DEH89WAV.js),
+  release `8063dc2e55869d8eae1c30e18f913da88bca1582`, only sets a frame URL for
+  YouTube, SoundCloud and Periscope player hosts. Other hosts get a new-tab link
+  to the posted URL. That observation is from code, not a signed-in session;
+  server flags could vary by account. The same code supplies the sandbox above,
+  enables fullscreen, and clamps tall player ratios to square.
+- Two live game pages, read as X's crawler: `snekarena.com/r/main` and a game page
+  on `www.spawn.co`. Both carry the player tags with a 480×480 player, pictures of
+  1200×628 and 1200×800, and no `twitter:site`; the first allows the X and Twitter
+  domain families as frame ancestors. They show what X accepted that week; they do
+  not prove X frames arbitrary games. No exhaustive current official ancestor list
+  was found.
+
+X decides what it shows, may cache tags, and may change or stop this behavior.
+Local success does not prove that X will display a card. The studio can use the
+off switch above if it does not want to offer a game through a video-oriented card.

package/starters/coin-dash/game.json

@@ -0,0 +1,11 @@
+{
+  "id": "coin-dash",
+  "name": "Coin Dash",
+  "blurb": "Run for the coins before the others do. Sixty-second rounds, and the score is kept on the server, where nobody can change it.",
+  "players": { "min": 1, "max": 8 },
+  "entry": "src/view.ts",
+  "example": true,
+  "netplay": { "v": 1, "public": true },
+  "room": { "host": "server" },
+  "landing": { "pitch": "Run for the coins. First one there takes it.", "controls": { "phone": "Drag to run.", "computer": "WASD or arrows to run." } }
+}

package/starters/coin-dash/index.html

@@ -0,0 +1,17 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover, user-scalable=no">
+<title>Coin Dash</title>
+<link rel="icon" href="data:,">
+<style>
+  html, body { margin: 0; height: 100%; background: #0b1020; overflow: hidden; overscroll-behavior: none; -webkit-user-select: none; user-select: none; -webkit-touch-callout: none; }
+  canvas { position: fixed; inset: 0; width: 100%; height: 100%; display: block; touch-action: none; }
+</style>
+</head>
+<body>
+<canvas id="c"></canvas>
+<script type="module" crossorigin src="./assets/main.js"></script>
+</body>
+</html>

package/starters/coin-dash/map/main.json

@@ -0,0 +1,16 @@
+{
+  "bounds": { "min": [-12, -7], "max": [12, 7] },
+  "boxes": [
+    { "min": [-6.5, 1.5], "max": [-4.5, 3.5] },
+    { "min": [4.5, -3.5], "max": [6.5, -1.5] },
+    { "min": [-1, -0.5], "max": [1, 0.5] }
+  ],
+  "circles": [
+    { "at": [5.5, 3], "r": 1 },
+    { "at": [-5.5, -3], "r": 1 }
+  ],
+  "spots": {
+    "start": [[-10, 5], [10, -5], [-10, -5], [10, 5], [0, 5.5], [0, -5.5], [-10, 0], [10, 0]],
+    "coins": [[-8, 2.5], [-8, -2.5], [8, 2.5], [8, -2.5], [-3, 4.5], [3, 4.5], [-3, -4.5], [3, -4.5], [-2.5, 0], [2.5, 0], [0, 2.5], [0, -2.5], [-6, 0], [6, 0], [-9, 6], [9, -6]]
+  }
+}

package/starters/coin-dash/src/move.ts

@@ -0,0 +1,27 @@
+/*
+ * COIN DASH — how a runner moves. Its own file, because two places run it: the server, for every body it moves, and
+ * each player's browser, for that player's own body. So it reads only what both have: the body's own position,
+ * velocity, heading and `motion`, this step's input, the static map and the public tunables (`ctx.tune`). It sees no
+ * other entity, no score and no dice.
+ */
+import { defineMove } from '@homie-rocks/studio/rules';
+
+export const move = defineMove({
+  runner(body, input, ctx) {
+    const M = ctx.math;
+    // A runner stands still through the break between rounds (the rules set `frozenUntil`).
+    const speed = ctx.tick < body.motion.frozenUntil ? 0 : ctx.tune.speed;
+    // A diagonal is no faster: the stick is held to length 1.
+    body.vel = M.scale(M.clampLen({ x: input.ax / 127, y: input.ay / 127, z: 0 }, 1), speed);
+    if (speed > 0 && M.len(body.vel) > 0.5) body.heading = M.norm(body.vel);
+    const step = M.scale(body.vel, ctx.dt);
+    const from = body.pos;
+    const wall = ctx.map.sweep(body, step);   // moves body.pos, and stops at the first wall
+    if (wall) {
+      // Slide: what is left of the step, along the wall.
+      const whole = M.len(step);
+      const left = whole > 0 ? 1 - M.len(M.sub(body.pos, from)) / whole : 0;
+      ctx.map.sweep(body, M.scale(M.sub(step, M.scale(wall.normal, M.dot(step, wall.normal))), left));
+    }
+  },
+});

package/starters/coin-dash/src/rules.ts

@@ -0,0 +1,86 @@
+/*
+ * COIN DASH — the rules: the example of a game whose rules run on the server.
+ *
+ * What is true in the game is decided here, in one place, on the studio's own Cloudflare: who took which coin, every
+ * score, when a round starts and ends. A player's browser sends what the player presses and draws what it is told
+ * (src/view.ts); it cannot change a score.
+ *
+ * HOW RULES ARE WRITTEN. Every entity owns its own state, in declared fields. A handler may write only the entity it
+ * runs for (`self`); everything else it reads is read-only. To affect another entity it sends an event, which arrives
+ * on a later tick. So a runner does not take a coin: it asks the coin (`take`), the coin answers the first one that
+ * asked (`score`) and is gone, and a second `take` finds nobody there.
+ *
+ * In this release a person's runner moves as today: its own browser says where it is, and the server holds each claim
+ * to the body's top speed (`move: 'owner'`). The server moves the bots with the same code (src/move.ts).
+ */
+import { defineRules, f } from '@homie-rocks/studio/rules';
+import { move } from './move';
+
+export default defineRules({
+  contract: 2,
+  space: { dims: 2 },
+  move,
+  shapes: {
+    events: { take: { by: f.ref() }, score: {} },
+    commands: {},
+    effects: { ding: {} },
+  },
+  entities: {
+    runner: {
+      player: { away: 'think', leave: 'bot' },
+      fields: { score: f.u16({ score: true }) },
+      motion: { frozenUntil: f.tick() },
+      input: { ax: f.i8(), ay: f.i8() },
+      body: { shape: 'circle', radius: 0.5, maxSpeed: 6, move: 'owner' },
+      tick(world, self) {
+        if (world.round.phase !== 'live') return;
+        // A second `take` sent before the coin is gone is dropped: the coin no longer exists.
+        for (const coin of world.near(self.pos, 1, 'coin')) world.send(coin.id, 'take', { by: self.id });
+      },
+      think(world, self) {                 // a bot, and a player who is away
+        const coin = world.near(self.pos, 64, 'coin')[0];
+        if (!coin) return { ax: 0, ay: 0 };
+        const d = world.math.norm(world.math.sub(coin.pos, self.pos));
+        return { ax: Math.round(d.x * 127), ay: Math.round(d.y * 127) };
+      },
+      on: {
+        score(world, self) { self.score += 1; },
+        arrive(world, self) {              // joined during a break: stand still with the others
+          if (world.round.phase === 'over') self.motion.frozenUntil = world.round.endsAt;
+        },
+      },
+      onRoom: {
+        roundStart(world, self) {
+          const spots = world.map.spots('start');
+          self.score = 0;
+          self.motion.frozenUntil = 0;
+          world.place(self, spots[self.seat % spots.length]);
+        },
+        roundOver(world, self) { self.motion.frozenUntil = world.round.endsAt; },   // stand still through the break
+      },
+    },
+    coin: {
+      on: {
+        take(world, self, e) {             // first taker wins: a despawned coin hears nothing more this tick
+          world.send(e.by, 'score', {});
+          world.emit('ding', self.pos, {});
+          world.despawn(self);
+        },
+      },
+      onRoom: { roundOver(world, self) { world.despawn(self); } },
+    },
+  },
+  shared: {},
+  room: {
+    rounds: { seconds: 60, breakSeconds: 8 },
+    bots: { keep: 4 },
+    join(ctx, player) {
+      const spots = ctx.map.spots('start');
+      return { kind: 'runner', at: spots[player.seat % spots.length] };
+    },
+    on: {
+      roundStart(world) { for (const spot of world.map.spots('coins')) world.spawn('coin', spot, {}); },
+    },
+  },
+  map: './map',
+});