@homie-rocks/studio 0.23.0 → 0.24.0

package/worker/office-page.mjs

@@ -10,7 +10,7 @@ import { SKILLS } from './agents.mjs';
 import { KIDS_LINE, POLICY_WORDS, SERVER_LIMITS } from './servers.mjs';
 import { esc } from './site.mjs';
 
-const PRIVATE = {
+export const PRIVATE = {
   'content-type': 'text/html; charset=utf-8',
   'cache-control': 'no-store, private',
   'x-robots-tag': 'noindex, nofollow',
@@ -832,7 +832,7 @@ async function officeScriptHash() {
   return scriptHash;
 }
 
-function shell(cat, title, body, { status = 200, script = null, extra = {} } = {}) {
+export function shell(cat, title, body, { status = 200, script = null, extra = {} } = {}) {
   return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
 <meta name="robots" content="noindex, nofollow"><title>${esc(title)}</title><style>:root{--accent:${accentOf(cat)}}${CSS}</style></head><body><div class="wrap">${body}</div>${script ? `<script>${script}</script>` : ''}</body></html>`;
 }
@@ -842,7 +842,7 @@ export async function officePage(cat, headers = {}) {
   const name = cat.studio?.name ?? 'Studio';
   const options = (cat.games ?? []).map((g) => `<option value="${esc(g.id)}">every room of ${esc(g.name)}</option>`).join('');
   const body = `<header class="top"><h1>${esc(name)} <small>Office</small></h1>
-<div class="links"><span class="live"><i class="dot" id="livedot"></i><span id="live">…</span></span><a href="/_studio/stats">Stats</a>
+<div class="links"><span class="live"><i class="dot" id="livedot"></i><span id="live">…</span></span><a href="/_studio/stats">Stats</a>${cat.shop ? '<a href="/_studio/office/shop">Shop</a>' : ''}
 <form method="post" action="/_studio/signout" style="display:inline"><button class="ghost small" type="submit">Sign out</button></form></div></header>
 <form class="bar" id="announce-all"><label for="announce-text">Announce</label><input type="text" id="announce-text" maxlength="280" placeholder="A line every player sees, in the game" autocomplete="off">
 <select id="announce-scope" aria-label="Who sees it"><option value="">every room of every game</option>${options}</select><button type="submit">Send</button>
@@ -871,7 +871,7 @@ export function lockedPage(cat, { what = 'office', ask = null } = {}) {
   return new Response(shell(cat, `${what === 'confirm' ? 'Confirm' : 'Office'} · private`, body), { status: 401, headers: { ...PRIVATE, 'content-security-policy': NO_SCRIPT_CSP } });
 }
 
-const VERB = { kick: 'Kick', mute: 'Mute', close: 'Close the room', announce: 'Announce', game: 'Change it', 'server-set': 'Change it', 'server-close': 'Close it', member: 'Remove', 'agents-brain': 'Let them talk' };
+const VERB = { refund: 'Refund it', 'shop-settle': 'Mark it paid', kick: 'Kick', mute: 'Mute', close: 'Close the room', announce: 'Announce', game: 'Change it', 'server-set': 'Change it', 'server-close': 'Close it', member: 'Remove', 'agents-brain': 'Let them talk' };
 
 /** The owner's one tap for what their AI asked, and what came of it. */
 export function confirmPage(cat, ask, { missing = false } = {}) {
@@ -883,7 +883,7 @@ export function confirmPage(cat, ask, { missing = false } = {}) {
     const verb = ask.action?.op === 'mute' && ask.action.off ? 'Unmute' : ask.action?.op === 'close' && ask.action.reopen ? 'Open it again' : VERB[ask.action?.op] ?? 'Yes';
     body = `<h1>${esc(name)} <small>Your AI asks</small></h1>
 <p style="font-size:19px;line-height:1.45;max-width:46ch">${esc(ask.what)}</p>
-<form method="post" class="bar" style="background:transparent;border:0;padding:0"><button type="submit" name="do" value="yes" class="${['kick', 'close', 'server-close', 'member'].includes(ask.action?.op) && !ask.action?.reopen ? 'armed' : ''}">${esc(verb)}</button><button type="submit" name="do" value="no" class="ghost">No</button></form>
+<form method="post" class="bar" style="background:transparent;border:0;padding:0"><button type="submit" name="do" value="yes" class="${['kick', 'close', 'server-close', 'member', 'refund'].includes(ask.action?.op) && !ask.action?.reopen ? 'armed' : ''}">${esc(verb)}</button><button type="submit" name="do" value="no" class="ghost">No</button></form>
 <p class="note">Only you can confirm this: your AI asked through the studio's office key, which cannot say yes. It lasts until ${esc(new Date(ask.expiresAt).toISOString().slice(11, 16))} UTC.</p>`;
   } else {
     const said = { done: 'Done.', failed: 'That did not work.', cancelled: 'Not done: you said no.', expired: 'This ask ran out (15 minutes). Your AI can ask again.', working: 'Working on it…' }[ask.state] ?? ask.state;

package/worker/office.mjs

@@ -49,6 +49,10 @@
  * reports players made (each the one message it is about) with Dismiss, and the review's day (Workers AI neurons).
  * From an office key, a change that opens chat up (more allowed, fewer checks) is an ASK; one that tightens it, or
  * taking a message down, happens at once.
+ *
+ * THE SHOP (0.24.0, worker/shop.mjs): /_studio/office/shop and /_studio/api/shop (sales, refunds, disputes, payouts as
+ * links to the studio's own Stripe, a CSV, the referral books and signed statements). A refund is the owner's one tap;
+ * from an office key it is ALWAYS an ask (the AI may only propose one), and so is marking a referrer paid.
  */
 import { SEAT_MAX, seatsOf } from './seats.mjs';
 import { PUBLIC_SERVER, SERVER_LIMITS, checkServer, levelName, narrows, policyOf, roomServer, rowFor, serverView, serversOf, serverPassCookie, writeServer } from './servers.mjs';
@@ -60,6 +64,8 @@ import { confirmPage, lockedPage, officePage } from './office-page.mjs';
 import { licenseOf } from './license.mjs';
 import { CHAT_MODES, CHAT_WHO, checkChatRules, publicChat } from './chat.mjs';
 import { chatDay, chatOf, chatRowsOf, clearChatRules, dismissReport, reportsOf, writeChatRules } from './chat-store.mjs';
+import { checkRefund, checkSettle, describeRefund, officeShopPage, ordersCsv, performRefund, settleReferrer, shopOffice, statementsOut, statementsSend } from './shop.mjs';
+import { orderById } from './shop-store.mjs';
 
 export { OFFICE_MIGRATION, OFFICE_MIGRATION_FILE } from './office-schema.mjs';
 
@@ -673,6 +679,8 @@ function checkAction(cat, op, body) {
       if (!(level >= 1 && level <= 5)) return bad('level is 1 to 5 (Rookie, Steady, Fair, Strong, Maxed)');
       return { ok: true, action: { op, game: meta.id, room, level } };
     }
+    case 'refund': return checkRefund(body);
+    case 'shop-settle': return checkSettle(body);
     case 'agents-brain': {
       if (!meta) return bad('game is one of this studio\'s game ids');
       if (typeof body.server !== 'string' || !(body.server === 'public' || /^[a-z0-9][a-z0-9-]{1,19}$/.test(body.server))) return bad('server is the server\'s id');
@@ -770,6 +778,8 @@ export function describe(cat, a) {
     case 'member': return a.remove ? `Remove ${a.name ?? 'that player'} from ${gname}'s server ${a.server} (they can join again unless its door keeps them out).` : `Make ${a.name ?? 'that player'} a ${a.role} of ${gname}'s server ${a.server}.`;
     case 'pass': return a.action === 'revoke' ? `Revoke the agent pass ${a.id}: that AI leaves every room and cannot sit again.` : `Issue an agent pass for an AI called "${a.label} · AI".`;
     case 'room-level': return `Set the AI in ${where} to ${levelName(a.level)} (level ${a.level}).`;
+    case 'refund': return describeRefund(cat, a, a.item ? { item: a.item, amount: a.amount, currency: a.currency } : null);
+    case 'shop-settle': return `Mark what this studio owes ${a.via} for referrals as paid${a.ref ? ` (${a.ref})` : ''}: its owed lines are settled in the books.`;
     case 'agents-brain': return ['workers-ai', 'owner-key'].includes(a.mode)
       ? `Let the AI guides on ${gname}'s server ${a.server} talk: they speak only the lines the game's own agents.json gives them (never free text), at most one line every 8 seconds, never about a person, and a player can quiet them. Their brain runs on ${a.mode === 'workers-ai' ? `this studio's own Workers AI (free allowance${a.budget !== undefined ? `; at most ${Math.round(a.budget).toLocaleString('en-US')} neurons a day` : ''})` : `your own AI provider key (claude-haiku-4-5, your money${a.budget !== undefined ? `, at most $${Number(a.budget).toFixed(2)} a day` : ', capped daily'})`}.`
       : `Set the AI guides' brain on ${gname}'s server ${a.server} to ${a.mode}.`;
@@ -800,6 +810,8 @@ export function describe(cat, a) {
 /** Whether an office key (the owner's AI) only ASKS for this (DESIGN D13): what takes something away, or consent. */
 export async function needsAsk(env, cat, a) {
   if (DESTRUCTIVE.has(a.op)) return true;
+  // Money: the owner's AI may only propose a refund or a settlement; the owner says yes.
+  if (a.op === 'refund' || a.op === 'shop-settle') return true;
   if (a.op === 'server-close') return !a.reopen;
   if (a.op === 'member') return a.remove === true;
   if (a.op === 'server-set') {
@@ -1020,6 +1032,8 @@ export async function perform(env, cat, a) {
       if (a.mode === 'off') notes.push('The guides are the game\'s plain bots.');
       return { ok: true, op: a.op, game: meta.id, server: sv.id, brain: sv.brain, budget: day.budget, note: `Saved. ${notes.join(' ')}`.trim() };
     }
+    case 'refund': return performRefund(env, cat, a);
+    case 'shop-settle': return settleReferrer(env, a);
     default: return { ok: false, error: 'op' };
   }
 }
@@ -1155,11 +1169,21 @@ async function api(request, env, url, cat) {
     const view = await officeView(env, { ...cat, games: metas }, url.origin);
     return json({ ok: true, day: view.chat, games: view.games.map((g) => ({ id: g.id, name: g.name, chat: g.chat, rooms: g.rooms.map((r) => ({ room: r.room, label: r.label, players: r.players, chat: r.chat })) })) });
   }
+  // The shop (0.24.0): the owner's view, the accountant's CSV, the referral statements.
+  if (path === '/_studio/api/shop' && request.method === 'GET') return json(await shopOffice(env, cat, url.origin));
+  if (path === '/_studio/api/shop/orders.csv' && request.method === 'GET') {
+    try {
+      return new Response(await ordersCsv(env), { headers: { 'content-type': 'text/csv; charset=utf-8', 'cache-control': 'no-store, private', 'content-disposition': `attachment; filename="orders-${today()}.csv"` } });
+    } catch { return json({ ok: false, error: 'not-migrated', message: 'The shop needs migration 0008_studio_shop.sql (npm run deploy).' }, 503); }
+  }
+  if (path === '/_studio/api/shop/statements' && request.method === 'GET') return json(await statementsOut(env, cat, url.origin, url.searchParams.get('period')));
+  if (path === '/_studio/api/shop/statements/send' && request.method === 'POST') return json(await statementsSend(env, cat, url.origin, body.period));
   const OPS = {
     '/_studio/api/chat/rules': 'chat-rules', '/_studio/api/chat/remove': 'chat-remove', '/_studio/api/chat/report': 'chat-report', '/_studio/api/chat/budget': 'chat-budget',
     '/_studio/api/kick': 'kick', '/_studio/api/mute': 'mute', '/_studio/api/close': 'close', '/_studio/api/announce': 'announce', '/_studio/api/game': 'game',
     '/_studio/api/servers': 'server-create', '/_studio/api/servers/set': 'server-set', '/_studio/api/servers/close': 'server-close', '/_studio/api/servers/member': 'member',
     '/_studio/api/agents/pass': 'pass', '/_studio/api/room-level': 'room-level', '/_studio/api/agents/brain': 'agents-brain',
+    '/_studio/api/shop/refund': 'refund', '/_studio/api/shop/settle': 'shop-settle',
   };
   const op = OPS[path];
   if (!op || request.method !== 'POST') return json({ ok: false, error: 'not-found' }, 404);
@@ -1167,6 +1191,12 @@ async function api(request, env, url, cat) {
   if (!checked.ok) return json(checked, 400);
   const action = checked.action;
   if (op === 'server-create' || op === 'pass') action.origin = url.origin;
+  if (op === 'refund') {
+    // The ask and the confirm page say what the order is (its item and price), read from the books now.
+    const o = await orderById(env, action.order);
+    if (!o) return json({ ok: false, error: 'order', message: 'No such order (homie-studio shop orders lists them).' }, 404);
+    Object.assign(action, { item: o.item, amount: Number(o.amount), currency: o.currency });
+  }
   // An office key (the owner's AI) only ASKS for what takes something away; the owner confirms with one tap.
   if (who === 'office' && await needsAsk(env, cat, action)) {
     if (op === 'kick' || op === 'mute') {
@@ -1199,6 +1229,12 @@ export async function officeRoutes(request, env, url, { catalogueOf }) {
     const secure = url.protocol === 'https:' ? '; Secure' : '';
     return officePage(cat, session ? { 'set-cookie': `${OWNER_COOKIE}=${session}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${30 * 24 * 3600}${secure}` } : {});
   }
+  if (path === '/_studio/office/shop' || path === '/_studio/office/shop/') {
+    const cat = await catalogueOf();
+    if (request.method !== 'GET') return new Response('method', { status: 405 });
+    if (!(await isOwner(request, env))) return lockedPage(cat, { what: 'office' });
+    return officeShopPage(cat);
+  }
   const confirm = /^\/_studio\/confirm\/(ask_[a-f0-9]{16})\/?$/.exec(path);
   if (confirm) {
     const cat = await catalogueOf();

package/worker/pages.mjs

@@ -8,6 +8,7 @@ import { SKILLS } from './agents.mjs';
 import { KIDS_LINE, POLICY_WORDS } from './servers.mjs';
 import { SAVES_SHELL_CSS, SAVES_SHELL_JS } from './saves-shell.mjs';
 import { CHAT_CSS, CHAT_JS, CHAT_OWNER_JS, chatBoot } from './chat-page.mjs';
+import { SHOP_SHELL_CSS, SHOP_SHELL_JS } from './shop-page.mjs';
 
 export { homePage, mediaIndexPage, notFoundPage, songPage, videoPage } from './site.mjs';
 
@@ -85,7 +86,7 @@ export function sharePlaces(value) {
  * the edge (game.json `screen.share`, per device: sharePlaces) opens Invite, Big screen and the room code; nothing
  * covers the middle of the screen or a thumb.
  */
-export function playPage(cat, g, { screen = false, joinUrl = null, qr = null, local = false, room = null, ticket = null, owner = false, launch = 'public', server = null, acct = false, member = false } = {}) {
+export function playPage(cat, g, { screen = false, joinUrl = null, qr = null, local = false, room = null, ticket = null, owner = false, launch = 'public', server = null, acct = false, member = false, shop = null } = {}) {
   const accent = cat?.studio?.theme?.accent ?? '#ffcf5a';
   const corner = (name, fallback) => (['top-left', 'top-right', 'bottom-left', 'bottom-right'].includes(g.screen?.[name]) ? g.screen[name] : fallback);
   const places = sharePlaces(g.screen?.share);
@@ -160,14 +161,14 @@ iframe.game { position: fixed; inset: 0; width: 100%; height: 100%; border: 0; d
 .notice .acts a { display: inline-flex; align-items: center; min-height: 44px; padding: 0 16px; border-radius: 12px; text-decoration: none; font-weight: 700; color: #eef1f8; border: 1px solid rgba(255,255,255,.18); }
 .notice .acts a.primary { background: var(--hot); color: #0b0b10; border-color: transparent; }
 [hidden] { display: none !important; }
-${SERVER_CSS}${CHAT_CSS}${g.saves && !screen ? SAVES_SHELL_CSS : ''}${pillUi}`;
+${SERVER_CSS}${CHAT_CSS}${g.saves && !screen ? SAVES_SHELL_CSS : ''}${shop ? SHOP_SHELL_CSS : ''}${pillUi}`;
   // The room button's place on each device (sharePlaces); the shell moves it to this browser's once it knows the device.
   // A ticket (a game that is not public) and the owner's overlay ride along only for the browser they are for.
   // The server this page plays on (0.16.0): its pool (the Lobby), its badge and line for the chip, its ceiling.
   const srv = server ? { id: server.id, name: server.name, badge: server.badge, line: server.line, policy: server.policy, kids: Boolean(server.kids), mentor: Boolean(server.mentor), levelMax: server.levelMax } : null;
   // game.json "agents": { "vote": "game" } draws its own vote card; false turns the vote off (section 17).
   const vote = g.agents?.vote === 'game' || g.agents?.vote === false ? g.agents.vote : 'shell';
-  const boot = { game: g.id, name: g.name, screen: Boolean(screen), share: places, ...(room ? { room } : {}), ...(ticket ? { t: ticket } : {}), ...(owner ? { owner: true, launch } : {}), ...(srv ? { server: srv } : {}), vote, skills: SKILLS.map((k) => ({ level: k.level, name: k.name, card: k.card })), words: POLICY_WORDS, kidsLine: KIDS_LINE };
+  const boot = { game: g.id, name: g.name, screen: Boolean(screen), share: places, ...(room ? { room } : {}), ...(ticket ? { t: ticket } : {}), ...(owner ? { owner: true, launch } : {}), ...(srv ? { server: srv } : {}), vote, skills: SKILLS.map((k) => ({ level: k.level, name: k.name, card: k.card })), words: POLICY_WORDS, kidsLine: KIDS_LINE, ...(shop ? { shop } : {}) };
   // game.json "screen": { "join": "top-left" | "top-right" | "bottom-left" | "bottom-right" } keeps the card off the game's own HUD.
   const joinCorner = corner('join', 'bottom-right');
   const first = places.desk;
@@ -190,7 +191,7 @@ ${SERVER_CSS}${CHAT_CSS}${g.saves && !screen ? SAVES_SHELL_CSS : ''}${pillUi}`;
       <a data-bigscreen target="_blank" rel="noopener" href="/${esc(g.id)}/tv"><svg viewBox="0 0 24 24" aria-hidden="true" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="2.5" y="4" width="19" height="13" rx="2"/><path d="M8 20.5h8"/></svg><span>Big screen</span></a>
     </div>
     <span class="link" data-room-link></span>
-    <div class="foot"><a href="/${esc(g.id)}/">← ${esc(g.name)}</a><button type="button" data-copy-link>Copy link</button></div>${g.saves ? `
+    <div class="foot"><a href="/${esc(g.id)}/">← ${esc(g.name)}</a>${shop ? '<button type="button" data-shop-open>Shop</button>' : ''}<button type="button" data-copy-link>Copy link</button></div>${g.saves ? `
     <div class="who-row" data-who hidden><span data-who-name></span><button type="button" data-who-act></button></div>` : ''}
   </div>
 </div>
@@ -206,7 +207,8 @@ ${joinCard}${share}
 <script>window.__HOMIE_CHAT=${JSON.stringify(chatBoot(g, { surface: screen ? 'tv' : 'play', owner, acct, member })).replace(/</g, '\\u003c')};</script>
 <script>${CHAT_JS}</script>
 <script>${SHELL_JS}</script>${g.saves && !screen ? `
-<script>${SAVES_SHELL_JS}</script>` : ''}${owner ? `<style>${OWNER_CSS}</style><script>${OWNER_JS}</script><script>${CHAT_OWNER_JS}</script>` : ''}`, css, frameAncestors(cat));
+<script>${SAVES_SHELL_JS}</script>` : ''}${shop ? `
+<script>${SHOP_SHELL_JS}</script>` : ''}${owner ? `<style>${OWNER_CSS}</style><script>${OWNER_JS}</script><script>${CHAT_OWNER_JS}</script>` : ''}`, css, frameAncestors(cat));
 }
 
 /*

package/worker/players.mjs

@@ -30,6 +30,7 @@ import { cookieValue } from './stats.mjs';
 import { adoptStatements, bumpPlayerStats, dropPlayerData, fall, fallenList, getSave, listSaves, playerData, readPlayerStats, SAVE_LIMITS, savesSummary, wipeSaves, writeSaves } from './saves.mjs';
 import { bytesToB64url, randomToken, sha256Hex, verifyAssertion, verifyRegistration } from './webauthn.mjs';
 import { ACCOUNT_JS, accountPage } from './account-page.mjs';
+import { forgetPlayerShop, livePurchases, shopDataOf } from './shop-store.mjs';
 
 export const PLAYERS_MIGRATION_FILE = '0004_players.sql';
 export const PLAYERS_MIGRATION = `-- Players and cloud saves (@homie-rocks/studio 0.12.0): accounts on this studio only (saves/SAVES.md).
@@ -323,6 +324,8 @@ async function removePlayer(env, id) {
   ]);
   // Their servers' memberships too (0.16.0); a studio before migration 0006 has none to delete.
   try { await env.DB.prepare('DELETE FROM server_members WHERE player = ?1').bind(id).run(); } catch { /* not migrated */ }
+  // What they bought goes with them; the orders stay, without the player (0.24.0; none before migration 0008).
+  try { await env.DB.batch(forgetPlayerShop(env, id)); } catch { /* not migrated */ }
   await data.after();
 }
 
@@ -508,6 +511,8 @@ async function apiRoute(request, env, ctx, url, parts, { catalogueOf, read, f })
       player: me,
       passkeys: keys.map((k) => ({ label: k.label, synced: Number(k.synced) === 1, createdAt: new Date(Number(k.created_at)).toISOString(), lastUsedAt: new Date(Number(k.used_at)).toISOString() })),
       games: await playerData(env, s.player.id),
+      // The shop (0.24.0): their orders, what they own and the age band they gave; never a card or an email.
+      ...(await shopDataOf(env, s.player.id).then((x) => (x ? { shop: x } : {}))),
       note: 'Everything this studio keeps about this player. A passkey\'s private key never left your device; this site keeps only its public key.',
     };
     return json(body, 200, { 'content-disposition': `attachment; filename="${s.player.id}.json"` });
@@ -770,6 +775,9 @@ async function apiRoute(request, env, ctx, url, parts, { catalogueOf, read, f })
 
   if (head === 'delete' && parts.length === 1) {
     if (body.confirm !== 'delete') return fail(400, 'confirm', 'send { "confirm": "delete" } to delete this player and everything they kept');
+    // Things they bought go with the account: say so first (the shop, 0.24.0).
+    const owned = await livePurchases(env, s.player.id).catch(() => 0);
+    if (owned && body.purchases !== 'forfeit') return fail(409, 'purchases', `This account owns ${owned} thing${owned === 1 ? '' : 's'} bought here; deleting it gives ${owned === 1 ? 'it' : 'them'} up for good (an unused item can be refunded first, from this page). Send { "confirm": "delete", "purchases": "forfeit" } to delete anyway.`, { owned });
     await removePlayer(env, s.player.id);
     return withCookies(json({ ok: true, deleted: s.player.id }), [clearCookie(url)]);
   }

package/worker/referrals.mjs

@@ -0,0 +1,328 @@
+/**
+ * REFERRALS (@homie-rocks/studio 0.24.0): one set of rules for every referrer, homie.rocks included.
+ *
+ *   arrival     A person's browser opens one of this studio's pages with ?via=<host> (a link from another studio,
+ *               from homie.rocks, from anywhere). If this browser has never been here (no player of this site), the
+ *               Worker keeps the host and the time in a signed cookie (HttpOnly, this site only, for the window).
+ *               Prefetches, crawlers, this site itself and server rooms are never recorded.
+ *   a sale      A paid order within the window, by an account made after that first visit, writes a referral line in
+ *               THIS studio's D1 (the seller's books): the pre-tax price, the published rate, the share, held for
+ *               `holdDays` (a refund or a lost dispute inside the hold voids it; after it, it nets off the next
+ *               statement). The referrer must prove itself: its own /.well-known/homie-studio.json says it takes
+ *               referral statements. No list anywhere says who is real; homie.rocks is not a registry.
+ *   statements  Monthly, signed with this studio's own Ed25519 key (its public half is in the manifest): the order
+ *               hashes, items, pre-tax amounts, dates and states, and what is owed. No player, name or email. POSTed
+ *               to the referrer's /api/referrals/statement, which checks the signature against the seller's manifest.
+ *   paying      Never through Homie. The referrer invoices the seller from its own Stripe (or PayPal, Wise, or the
+ *               seller's gift codes); the seller pays the invoice. The office shows both sides and links to Stripe.
+ */
+import { isVisit } from './stats.mjs';
+
+const DAY = 86_400_000;
+export const VIA_COOKIE = 'studio_via';
+const HOST = /^(?=.{3,80}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$/;
+export const STATEMENT_KIND = 'homie-referral-statement';
+
+const b64url = (bytes) => btoa(String.fromCharCode(...new Uint8Array(bytes))).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+const fromB64url = (s) => Uint8Array.from(atob(String(s).replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - (String(s).length % 4)) % 4)), (c) => c.charCodeAt(0));
+const enc = new TextEncoder();
+
+/** A host as a referrer names itself: lower-case, no port, no path, never an address. */
+export function hostOf(raw) {
+  const h = String(raw ?? '').trim().toLowerCase().replace(/^www\./, '');
+  return HOST.test(h) && !/^\d+\.\d+\.\d+\.\d+$/.test(h) ? h : null;
+}
+
+/** JSON with sorted keys: what a signature covers, byte for byte, on both sides. */
+export function canonicalJson(v) {
+  if (Array.isArray(v)) return `[${v.map(canonicalJson).join(',')}]`;
+  if (v && typeof v === 'object') return `{${Object.keys(v).sort().filter((k) => v[k] !== undefined).map((k) => `${JSON.stringify(k)}:${canonicalJson(v[k])}`).join(',')}}`;
+  return JSON.stringify(v ?? null);
+}
+
+/* ------------------------------------------------------------------ this studio's secrets in D1 meta */
+
+async function metaGet(env, key) {
+  try { return (await env.DB.prepare('SELECT value FROM meta WHERE key = ?1').bind(key).first())?.value ?? null; } catch { return null; }
+}
+async function metaPutOnce(env, key, value) {
+  await env.DB.prepare('INSERT INTO meta (key, value) VALUES (?1, ?2) ON CONFLICT(key) DO NOTHING').bind(key, value).run();
+  return metaGet(env, key);
+}
+
+let hmacCache = null;
+/** The key that signs the arrival cookie (random, in D1 meta, made on first use). */
+async function cookieKey(env) {
+  if (hmacCache?.env === env) return hmacCache.key;
+  let hex = await metaGet(env, 'referral_cookie_key');
+  if (!hex) {
+    const raw = new Uint8Array(32);
+    crypto.getRandomValues(raw);
+    hex = await metaPutOnce(env, 'referral_cookie_key', [...raw].map((b) => b.toString(16).padStart(2, '0')).join(''));
+  }
+  const bytes = Uint8Array.from(hex.match(/../g).map((h) => parseInt(h, 16)));
+  const key = await crypto.subtle.importKey('raw', bytes, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+  hmacCache = { env, key };
+  return key;
+}
+const macOf = async (env, text) => b64url(await crypto.subtle.sign('HMAC', await cookieKey(env), enc.encode(text))).slice(0, 22);
+
+let signingCache = null;
+/** This studio's Ed25519 statement key (private half in D1 meta, made on first use; public half in the manifest). */
+export async function signingKey(env) {
+  if (signingCache?.env === env) return signingCache.pair;
+  let stored = await metaGet(env, 'referral_signing_key');
+  if (!stored) {
+    const pair = await crypto.subtle.generateKey({ name: 'Ed25519' }, true, ['sign', 'verify']);
+    const jwk = await crypto.subtle.exportKey('jwk', pair.privateKey);
+    stored = await metaPutOnce(env, 'referral_signing_key', JSON.stringify({ kty: jwk.kty, crv: jwk.crv, d: jwk.d, x: jwk.x }));
+  }
+  const jwk = JSON.parse(stored);
+  const privateKey = await crypto.subtle.importKey('jwk', { ...jwk, key_ops: ['sign'], ext: true }, { name: 'Ed25519' }, false, ['sign']);
+  const pair = { privateKey, publicJwk: { kty: 'OKP', crv: 'Ed25519', x: jwk.x } };
+  signingCache = { env, pair };
+  return pair;
+}
+
+export async function signStatement(env, statement) {
+  const { privateKey, publicJwk } = await signingKey(env);
+  const sig = b64url(await crypto.subtle.sign({ name: 'Ed25519' }, privateKey, enc.encode(canonicalJson(statement))));
+  return { v: 1, kind: STATEMENT_KIND, statement, sig, key: publicJwk.x };
+}
+
+/** Check a statement's signature against a public key (the `x` of the seller's manifest key). */
+export async function verifyStatement(envelope, x) {
+  try {
+    if (envelope?.kind !== STATEMENT_KIND || typeof envelope.sig !== 'string' || typeof x !== 'string') return false;
+    const pub = await crypto.subtle.importKey('jwk', { kty: 'OKP', crv: 'Ed25519', x, ext: true }, { name: 'Ed25519' }, false, ['verify']);
+    return await crypto.subtle.verify({ name: 'Ed25519' }, pub, fromB64url(envelope.sig), enc.encode(canonicalJson(envelope.statement)));
+  } catch { return false; }
+}
+
+/* ------------------------------------------------------------------ arrival */
+
+/** Pages where an arrival may be recorded: the studio's own pages and Play; never a server's page or room. */
+const ARRIVAL_PAGE = /^\/(?:|games\/|shop\/|[a-z0-9][a-z0-9-]{0,39}\/(?:play)?)$/;
+
+/**
+ * A Set-Cookie for this arrival, or null. Only a person's real page load (not a prefetch, a crawler or this site's
+ * own link), with ?via=<host> of another site, from a browser with no player and no earlier arrival here, on a studio
+ * that sells and pays referrals, never on a server's page or room.
+ */
+export async function arrivalCookie(request, env, url, shop) {
+  if (!shop?.open || !shop.referrals || !env?.DB) return null;
+  const via = hostOf(url.searchParams.get('via'));
+  if (!via || via === hostOf(url.hostname)) return null;
+  if (!ARRIVAL_PAGE.test(url.pathname) || url.searchParams.has('room') || url.searchParams.has('server')) return null;
+  if (!isVisit(request)) return null;
+  const cookies = request.headers.get('cookie') ?? '';
+  // Been here before: a player of this site (a guest who saved, or an account), or an earlier arrival.
+  if (/(?:^|;\s*)(?:studio_player|studio_via)=/.test(cookies)) return null;
+  const at = Math.floor(Date.now() / 1000);
+  const value = `${via}.${at}.${await macOf(env, `${via}.${at}`)}`;
+  return `${VIA_COOKIE}=${value}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${shop.referrals.windowDays * 86400}${url.protocol === 'https:' ? '; Secure' : ''}`;
+}
+
+/** The arrival this request's browser carries ({ via, at }), checked, or null. */
+export async function arrivalOf(request, env) {
+  const raw = /(?:^|;\s*)studio_via=([^;]+)/.exec(request.headers.get('cookie') ?? '')?.[1];
+  const m = /^([a-z0-9.-]{3,80})\.(\d{9,11})\.([A-Za-z0-9_-]{22})$/.exec(raw ?? '');
+  if (!m || !hostOf(m[1])) return null;
+  try { if (m[3] !== await macOf(env, `${m[1]}.${m[2]}`)) return null; } catch { return null; }
+  return { via: m[1], at: Number(m[2]) * 1000 };
+}
+
+/* ------------------------------------------------------------------ is a referrer real? */
+
+const proven = new Map();
+/**
+ * Whether `host` takes referral statements: its own manifest says so (fetched over https, cached a day; a failure is
+ * cached an hour). `fetcher` is for tests.
+ */
+export async function referrerOk(host, { fetcher = fetch, now = Date.now() } = {}) {
+  const h = hostOf(host);
+  if (!h) return false;
+  const hit = proven.get(h);
+  if (hit && now - hit.at < (hit.ok ? DAY : 3_600_000)) return hit.ok;
+  let ok = false;
+  try {
+    const res = await fetcher(`https://${h}/.well-known/homie-studio.json`, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(3000) });
+    if (res.ok) {
+      const m = await res.json();
+      const st = String(m?.referrals?.statements ?? '');
+      ok = m?.referrals?.accepts === true && st.startsWith(`https://${h}/`);
+    }
+  } catch { ok = false; }
+  proven.set(h, { ok, at: now });
+  if (proven.size > 2000) proven.clear();
+  return ok;
+}
+/** For tests: forget what was proven. */
+export function resetReferrers() { proven.clear(); }
+
+/** What the manifest says about referrals: this studio takes statements (as a referrer) and, if it sells, its terms. */
+export async function manifestReferrals(env, origin, shop, studio) {
+  if (studio?.referrals === false || !env?.DB) return null;
+  let key = null;
+  try { key = (await signingKey(env)).publicJwk; } catch { key = null; }
+  return {
+    accepts: true,
+    statements: `${origin}/api/referrals/statement`,
+    ...(key ? { key } : {}),
+    // The seller's terms, the same for every referrer (homie.rocks included); absent: this studio pays no referrals.
+    ...(shop?.open && shop.referrals ? { terms: shop.referrals } : {}),
+  };
+}
+
+/* ------------------------------------------------------------------ the seller's books */
+
+/**
+ * A paid order with an arrival on it: its referral line (pending, held), or nothing when the terms say no (rate 0, out
+ * of the window, the per-player cap reached). Statements for D1's batch.
+ */
+export async function lineFor(env, order, shop, { touchAt = null, now = Date.now() } = {}) {
+  const terms = shop?.referrals;
+  if (!terms || !order.via || !(terms.rate > 0)) return [];
+  if (touchAt !== null && now - touchAt > terms.windowDays * DAY) return [];
+  let so = 0;
+  try { so = Number((await env.DB.prepare("SELECT COALESCE(SUM(l.share), 0) AS n FROM referral_lines l JOIN shop_orders o ON o.id = l.order_id WHERE o.player = ?1 AND l.via = ?2 AND l.state != 'void'").bind(order.player, order.via).first())?.n) || 0; } catch { so = 0; }
+  const share = Math.max(0, Math.min(Math.round(Number(order.amount) * terms.rate), terms.capPerPlayer - so));
+  if (share <= 0) return [];
+  const period = new Date(now).toISOString().slice(0, 7);
+  return [env.DB.prepare("INSERT INTO referral_lines (order_id, via, net, rate, share, currency, state, period, hold_until, settled_ref, created_at) VALUES (?1, ?2, ?3, ?4, ?5, ?6, 'pending', ?7, ?8, NULL, ?9) ON CONFLICT(order_id) DO NOTHING")
+    .bind(order.id, order.via, Number(order.amount), terms.rate, share, order.currency, period, now + terms.holdDays * DAY, now)];
+}
+
+/** A refund or a lost dispute: a held line is void; a settled one becomes a clawback that nets off the next statement. */
+export function voidLineStatements(env, orderId) {
+  return [
+    env.DB.prepare("UPDATE referral_lines SET state = 'void' WHERE order_id = ?1 AND state IN ('pending', 'owed')").bind(orderId),
+    env.DB.prepare("UPDATE referral_lines SET state = 'clawback' WHERE order_id = ?1 AND state = 'settled'").bind(orderId),
+  ];
+}
+
+const lineState = (r, now) => (r.state === 'pending' && Number(r.hold_until) <= now ? 'owed' : r.state);
+
+async function orderHash(seller, orderId) {
+  return [...new Uint8Array(await crypto.subtle.digest('SHA-256', enc.encode(`${seller}|${orderId}`)))].slice(0, 8).map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * The seller's books per referrer: { via, currency, pending, owed, clawback, lines } (lines not yet settled, and
+ * clawbacks), newest first. `period` (YYYY-MM) limits lines to sales up to the end of that month.
+ */
+export async function booksOf(env, { period = null, now = Date.now() } = {}) {
+  let rows = [];
+  try {
+    rows = (await env.DB.prepare("SELECT l.*, o.item, o.paid_at FROM referral_lines l JOIN shop_orders o ON o.id = l.order_id WHERE l.state IN ('pending', 'owed', 'clawback', 'void') ORDER BY l.created_at DESC LIMIT 2000").all()).results ?? [];
+  } catch { return []; }
+  const by = new Map();
+  for (const r of rows) {
+    if (period && r.period > period) continue;
+    const b = by.get(r.via) ?? { via: r.via, currency: r.currency, pending: 0, owed: 0, clawback: 0, lines: [] };
+    const state = lineState(r, now);
+    if (state === 'pending') b.pending += Number(r.share);
+    if (state === 'owed') b.owed += Number(r.share);
+    if (state === 'clawback') b.clawback += Number(r.share);
+    b.lines.push({ order: r.order_id, item: r.item, net: Number(r.net), rate: Number(r.rate), share: Number(r.share), state, period: r.period, date: new Date(Number(r.paid_at ?? r.created_at)).toISOString().slice(0, 10), holdUntil: Number(r.hold_until) });
+    by.set(r.via, b);
+  }
+  return [...by.values()].map((b) => ({ ...b, due: b.owed - b.clawback }));
+}
+
+/** One referrer's signed statement for a period (no player, name or email in it: order hashes only). */
+export async function statementFor(env, origin, book, period, terms) {
+  const seller = origin;
+  const lines = [];
+  for (const l of book.lines) lines.push({ order: await orderHash(seller, l.order), item: l.item, net: l.net, share: l.share, date: l.date, state: l.state });
+  const statement = {
+    seller, referrer: book.via, period, currency: book.currency, issued: new Date().toISOString(),
+    terms: terms ? { rate: terms.rate, holdDays: terms.holdDays, minimumInvoice: terms.minimumInvoice, basis: 'pre-tax' } : null,
+    totals: { pending: book.pending, owed: book.owed, clawback: book.clawback, due: book.due },
+    lines,
+    note: 'Invoice the seller for "due" from your own Stripe (or the way its terms accept). Nothing moves through Homie.',
+  };
+  return signStatement(env, statement);
+}
+
+/** The owner marks what was paid (an invoice paid by card, a PayPal transfer): those owed lines are settled. */
+export async function settle(env, via, ref, { now = Date.now() } = {}) {
+  const h = hostOf(via);
+  if (!h) return { ok: false, error: 'bad-request', message: 'via is the referrer\'s host' };
+  const note = String(ref ?? '').replace(/[^\w .:#/-]/g, '').slice(0, 80) || 'paid';
+  await env.DB.batch([
+    env.DB.prepare("UPDATE referral_lines SET state = 'settled', settled_ref = ?2 WHERE via = ?1 AND state = 'pending' AND hold_until <= ?3").bind(h, note, now),
+    env.DB.prepare("UPDATE referral_lines SET state = 'settled-clawback', settled_ref = ?2 WHERE via = ?1 AND state = 'clawback'").bind(h, note),
+  ]);
+  return { ok: true, via: h, ref: note };
+}
+
+/* ------------------------------------------------------------------ as a referrer */
+
+const received = [];
+/**
+ * POST /api/referrals/statement: a seller's signed statement to this studio. It must name this site as the referrer,
+ * and its signature must check against the key in the SELLER's own manifest (fetched now, over https). Kept per
+ * seller and period; a newer one replaces the older.
+ */
+export async function receiveStatement(request, env, url, { fetcher = fetch } = {}) {
+  const json = (b, s = 200) => new Response(`${JSON.stringify(b)}\n`, { status: s, headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' } });
+  if (request.method !== 'POST') return json({ ok: false, error: 'method' }, 405);
+  // A statement makes this Worker read the seller's manifest: a few a minute is all a real seller sends.
+  const now = Date.now();
+  while (received.length && received[0] < now - 60_000) received.shift();
+  if (received.length >= 30) return json({ ok: false, error: 'rate', message: 'too many statements; try again in a minute' }, 429);
+  received.push(now);
+  if (Number(request.headers.get('content-length') ?? 0) > 65_536) return json({ ok: false, error: 'too-large' }, 413);
+  const text = await request.text();
+  if (text.length > 65_536) return json({ ok: false, error: 'too-large' }, 413);
+  let env0 = null;
+  try { env0 = JSON.parse(text); } catch { return json({ ok: false, error: 'json' }, 400); }
+  const s = env0?.statement;
+  if (env0?.kind !== STATEMENT_KIND || !s || typeof s !== 'object') return json({ ok: false, error: 'not-a-statement' }, 400);
+  if (hostOf(s.referrer) !== hostOf(url.hostname)) return json({ ok: false, error: 'not-ours', message: 'this statement names another referrer' }, 400);
+  let seller = null;
+  try { const u = new URL(String(s.seller)); seller = u.protocol === 'https:' && hostOf(u.hostname) ? u.origin : null; } catch { seller = null; }
+  if (!seller || !/^\d{4}-\d{2}$/.test(String(s.period ?? ''))) return json({ ok: false, error: 'bad-statement' }, 400);
+  let x = null;
+  try {
+    const res = await fetcher(`${seller}/.well-known/homie-studio.json`, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(5000) });
+    x = res.ok ? (await res.json())?.referrals?.key?.x ?? null : null;
+  } catch { x = null; }
+  if (!x || x !== env0.key || !(await verifyStatement(env0, x))) return json({ ok: false, error: 'signature', message: 'the signature does not match the key in the seller\'s own manifest' }, 401);
+  const t = s.totals ?? {};
+  try {
+    await env.DB.prepare('INSERT INTO referral_statements (seller, period, owed, pending, currency, body, received_at) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7) ON CONFLICT(seller, period) DO UPDATE SET owed = excluded.owed, pending = excluded.pending, currency = excluded.currency, body = excluded.body, received_at = excluded.received_at')
+      .bind(seller, s.period, Math.max(0, Math.floor(Number(t.due ?? t.owed) || 0)), Math.max(0, Math.floor(Number(t.pending) || 0)), String(s.currency ?? 'usd').slice(0, 3), text.slice(0, 65_536), Date.now()).run();
+  } catch { return json({ ok: false, error: 'not-migrated', message: 'this studio has no referral tables yet (migration 0008)' }, 503); }
+  return json({ ok: true, seller, period: s.period });
+}
+
+/** The statements other studios sent this one: what each says it owes. */
+export async function statementsIn(env) {
+  try {
+    return ((await env.DB.prepare('SELECT seller, period, owed, pending, currency, received_at FROM referral_statements ORDER BY received_at DESC LIMIT 200').all()).results ?? [])
+      .map((r) => ({ seller: r.seller, period: r.period, due: Number(r.owed), pending: Number(r.pending), currency: r.currency, receivedAt: Number(r.received_at) }));
+  } catch { return []; }
+}
+
+/** Send each referrer its statement for `period` (to the address in its own manifest). */
+export async function sendStatements(env, origin, shop, period, { fetcher = fetch } = {}) {
+  const books = await booksOf(env, { period });
+  const sent = [];
+  for (const book of books) {
+    const env0 = await statementFor(env, origin, book, period, shop?.referrals);
+    let to = null;
+    try {
+      const m = await (await fetcher(`https://${book.via}/.well-known/homie-studio.json`, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(5000) })).json();
+      const st = String(m?.referrals?.statements ?? '');
+      to = st.startsWith(`https://${book.via}/`) ? st : null;
+    } catch { to = null; }
+    if (!to) { sent.push({ via: book.via, ok: false, why: 'no statement address in its manifest' }); continue; }
+    try {
+      const res = await fetcher(to, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(env0), signal: AbortSignal.timeout(8000) });
+      sent.push({ via: book.via, ok: res.ok, status: res.status, due: book.due });
+    } catch (error) { sent.push({ via: book.via, ok: false, why: String(error?.message ?? error).slice(0, 80) }); }
+  }
+  return sent;
+}

package/worker/room.mjs

@@ -319,6 +319,8 @@ export class NetRoom {
       watch: conn.watch === true, policy: WATCH_POLICIES.includes(conn.watchPolicy) ? conn.watchPolicy : 'follow', follow: null, followWhy: null,
       // An agent (section 17): only the Worker's word, from a verified pass, makes one; its hello cannot.
       agentWord: conn.agent && typeof conn.agent === 'object' ? conn.agent : null, agent: null, caps: new Set(), speechAt: [],
+      // A badge the studio's Worker verified (the shop: a supporter's); a hello cannot set one.
+      badge: typeof conn.badge === 'string' && conn.badge.length <= 16 ? conn.badge : null,
       // Revision 7: the latest view the host showed this AI (what its arguments are checked against), and its pace.
       lastView: null, viewAt: 0, doAt: 0,
     };
@@ -375,7 +377,7 @@ export class NetRoom {
   host() { return this.hostId ? this.clients.get(this.hostId) ?? null : null; }
   hostRef() { const h = this.host(); return h ? { id: h.id, seat: h.seat } : null; }
   roleOf(c) { return c.id === this.hostId ? 'host' : c.seat === null ? 'screen' : 'replica'; }
-  peer(c) { return { id: c.id, seat: c.seat, name: c.name, colour: c.colour, device: c.device, want: c.want, role: this.roleOf(c), ...(c.watch ? { watch: true } : {}), ...(c.agent ? { agent: { ...c.agent } } : {}), ...(this.muteOf(c) ? { muted: true } : {}) }; }
+  peer(c) { return { id: c.id, seat: c.seat, name: c.name, colour: c.colour, device: c.device, want: c.want, role: this.roleOf(c), ...(c.watch ? { watch: true } : {}), ...(c.agent ? { agent: { ...c.agent } } : {}), ...(this.muteOf(c) ? { muted: true } : {}), ...(c.badge && !c.agent ? { badge: c.badge } : {}) }; }
   /** A hands-`host` agent (section 17): no game client of its own, so no snapshots, checkpoints or state. */
   lite(c) { return Boolean(c.agent && c.agent.hands === 'host'); }
   seatedHumans() { return this.live().filter((c) => c.seat !== null && !c.agent); }