@homie-rocks/studio 0.35.1 → 0.37.0

package/netplay/rules-output.mjs

@@ -0,0 +1,85 @@
+import { takeRulesToken } from '../worker/limits.mjs';
+
+/**
+ * The hosting page's one way out for what its rules make. Reliable frames keep one order and each leaves as soon as
+ * its own kind has a token; only a snapshot may be superseded, and only a snapshot waits for the snapshot's token.
+ * Giving the role up is part of the same order: `handOver` follows the checkpoint through the queue and holds what
+ * is made after it until the relay answers, and `leave` sends the last checkpoint before the page goes.
+ */
+export function rulesOutput({ rates, send, now, setTimer = setTimeout, clearTimer = clearTimeout }) {
+  const buckets = new Map();
+  const queue = [];
+  let snapshot = null, timer = null, stopped = false, finishing = false, held = false;
+  function budget(m, force = false) {
+    const rate = rates[m.t];
+    if (!rate) throw new Error(`Unknown rules output: ${m.t}`);
+    // The relay drops a surplus snapshot and nothing else, so snapshots spend its whole rate: an on-time tick's leaves
+    // with the tick. Reliable kinds keep a fifth of theirs clear of transport jitter and late timers.
+    const ms = m.t === 'snap' ? takeRulesToken(buckets, m.t, rate, now(), 2) : takeRulesToken(buckets, m.t, rate * 0.8, now(), rate);
+    // The relay's bucket holds twice this one: a forced last checkpoint is inside it.
+    if (ms && force) { buckets.get(m.t).tokens -= 1; return 0; }
+    return ms;
+  }
+  function drain() {
+    if (timer !== null) { clearTimer(timer); timer = null; }
+    if (stopped || held) return;
+    let wait = Infinity;
+    while (queue.length) {
+      const m = queue[0];
+      if (m.rules !== true) { queue.shift(); held = true; send(m); return; }
+      const ms = budget(m);
+      if (ms) { wait = ms; break; }
+      send(queue.shift());
+    }
+    if (snapshot) {
+      const ms = budget(snapshot);
+      if (ms) wait = Math.min(wait, ms);
+      else { const m = snapshot; snapshot = null; send(m); }
+    }
+    if (finishing && !queue.length) { stopped = true; return; }
+    if (wait !== Infinity) timer = setTimer(drain, Math.max(1, wait));
+  }
+  return {
+    push(frame) {
+      if (stopped || finishing) return;
+      const m = { ...frame, rules: true };
+      if (m.t === 'snap') snapshot = m; else queue.push(m);
+      drain();
+    },
+    finish(frame) {
+      if (stopped || finishing) return;
+      finishing = true; held = false; snapshot = null; queue.push({ ...frame, rules: true });
+      drain();
+    },
+    /** `yield`, in its place behind the checkpoint. What the rules make after it waits for the relay's answer. */
+    handOver(frame) {
+      if (stopped || finishing) return;
+      queue.push({ ...frame, t: 'yield' });
+      drain();
+    },
+    /** True from `handOver` until its `yield` is on the wire: the relay must hear nothing else that moves the role. */
+    get handing() { return !stopped && queue.some((m) => m.rules !== true); },
+    /** True while a yield is queued or unanswered. */
+    get waiting() { return !stopped && (held || queue.some((m) => m.rules !== true)); },
+    /** The relay kept this page as the host: what was held goes out, in order. */
+    release() { if (held) { held = false; drain(); } },
+    /**
+     * The page is going (it closes, or its rules host is closed). Everything its allowance permits is sent, in order;
+     * a frame that cannot be is covered by the checkpoint, which goes last and always goes.
+     */
+    leave() {
+      if (stopped) return;
+      if (timer !== null) { clearTimer(timer); timer = null; }
+      let last = null, blocked = held;
+      for (const m of queue) {
+        if (m.t === 'ckpt') { last = m; continue; }
+        if (m.rules !== true) { blocked = true; continue; }
+        if (!blocked && !budget(m)) send(m); else blocked = true;
+      }
+      if (last) { budget(last, true); send(last); }
+      held = false; queue.length = 0; snapshot = null;
+    },
+    /** The relay moved the role: it takes nothing more from this page as the host. */
+    stop() { stopped = true; if (timer !== null) clearTimer(timer); timer = null; queue.length = 0; snapshot = null; },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.35.1",
+  "version": "0.37.0",
   "description": "A studio for games, music and video on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects and D1, all on the free Workers plan, no payment method), a site with the hub's sections (Home, Games, Music, Videos, Rooms, Posts with feeds) in the studio's own look, an epic landing page for every game, big songs and videos in the studio's own R2 once it has storage (uploaded, checked by SHA-256, served at the same addresses), deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",
@@ -75,7 +75,15 @@
       "default": "./rules/host.ts"
     },
     "./worker": "./worker/index.mjs",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./links": {
+      "types": "./links/links.d.ts",
+      "default": "./links/links.mjs"
+    },
+    "./apps": {
+      "types": "./apps/apps.ts",
+      "default": "./apps/apps.ts"
+    }
   },
   "files": [
     "bin/",
@@ -99,7 +107,10 @@
     "README.md",
     "CHANGELOG.md",
     "LICENSE",
-    "NOTICE"
+    "NOTICE",
+    "links/",
+    "apps/",
+    "app-starters/"
   ],
   "engines": {
     "node": ">=22"
@@ -119,7 +130,8 @@
     "meshoptimizer": "1.3.0",
     "puppeteer-core": "25.8.0",
     "sharp": "0.35.5",
-    "three": "0.185.1"
+    "three": "0.185.1",
+    "typescript": "5.9.3"
   },
   "scripts": {
     "test": "node --test test/*.test.mjs"

package/parts/PARTS.md

@@ -1,6 +1,6 @@
-# Game parts
+# Studio parts
 
-Games build on each other by sharing **parts**: a piece of a game that its studio chooses to share, so somebody
+Studios build on each other by sharing **parts**: a reusable piece of a game, app, music or video that its studio chooses to share, so somebody
 making another game can use it. A creature from one game, a level from another, a bot brain from a third. That is
 the whole idea. Without parts, a creator's AI has to come up with everything on its own.
 
@@ -8,7 +8,7 @@ Mashing up is not a command: it is making a game with parts from several games.
 
 ## The rules
 
-1. **A part is a piece of a game, never the whole game.** Remix, which handed over an entire game, is retired;
+1. **A part is a reusable piece, never a whole game or app.** Remix, which handed over an entire game, is retired;
    parts are what replaces it.
 2. **A part can take any form** that suits the piece: code, assets, data, a JSON description, a tuned config, or a
    mix. Form is not restricted.
@@ -89,10 +89,11 @@ named after it):
 | Field | What it is |
 | --- | --- |
 | `id`, `name`, `kind`, `version`, `summary` | `version` is three numbers; a shared version never changes, so a change is a new version. `summary` is one sentence. |
-| `kind` | `character`, `rig`, `clips`, `environment`, `effect`, `sound`, `ui`, `mechanic`, `shader`, `level-generator`, `bot-brain`, `audio-pack`, `set-piece`. There is no kind for a whole game. |
+| `kind` | `character`, `rig`, `clips`, `environment`, `effect`, `sound`, `ui`, `mechanic`, `shader`, `level-generator`, `bot-brain`, `audio-pack`, `set-piece`. `quiz`, `menu-board`, `waitlist`, `live-total`, `loop`, `stem`, `track`, `video-intro`, `video-template` also name parts. There is no kind for a whole game or app. |
 | `license`, `attribution` | Needed to share: an SPDX identifier, and who a game using the part credits. |
 | `share` | **Default `false`.** The part's own switch, and the only thing that decides whether it is shared. |
-| `from` | The game and studio the part came out of. Written when a part is lifted out of a game. |
+| `uses` | Optional intended uses: `game`, `app`, `venue`, `cause`, `music`, `video`. Describe the purpose, independently of licence and any future pricing. |
+| `from` | The source and studio: `game`, `app`, `music` or `video` with its id. Written when a part is lifted out of a game. |
 | `entry` | For a part with code: the module a game imports. A part of assets or data has none. |
 | `files` | Every file with its SHA-256 and size, **written by the tool, never by hand**. A file may carry `"rights"` (below). |
 | `preview` | `page`: a self-contained HTML page shown in a sandboxed frame. `image`: a still. `aspect`: the frame's shape as `"W:H"` (whole numbers 1 to 32, no flatter than 3:1, no taller than 1:2; default `"16:9"`). `phoneAspect`: the shape when the frame is narrower than 600 px. |
@@ -167,3 +168,7 @@ build, whether or not the add named the game.
   A package the studio's own `package.json` already names at a version npm says does not fit is explained and left
   alone.
 - The plumbing behind the tools is `homie-studio parts find | new | add | share | unshare | check`.
+
+App parts use the same lift/import/credit paths as game parts. Music and video parts can start empty with the corresponding kind; add their selected files, licence and provenance before sharing. `uses` describes what they are for, not permission to use them: the licence controls that. No price or checkout behavior is introduced; future commercial metadata can be added separately without changing the meaning of `share`.
+
+For example: `homie-studio parts new welcome-queue --kind waitlist --uses app,venue`, or `parts new gala-loop --kind loop --uses venue,cause`. A source app is selected by the existing `--from <id>` and `--game <id>` options.

package/rules/browser.ts

@@ -0,0 +1,100 @@
+/*
+ * The browser's adapter for the one host runtime. The build puts it with the guarded rules, either in a browser
+ * host's bundle or in a server game's optional offline module. netplay owns elections and the transport; this file
+ * supplies the clock and translates the runtime's saved bytes to the relay's existing JSON checkpoint.
+ */
+import { createHost } from './host.ts';
+import { compileMap, compileRules } from './rules.ts';
+import type { RoomSettings, RulesDef } from './rules.ts';
+import { fromBytes, toBytes } from './pack.ts';
+import { lab } from '../lab/lab.ts';
+import type { RulesHostFactory, Peer } from '../netplay/netplay.ts';
+
+export interface BrowserGame {
+  id: string; build: string; tune: Record<string, unknown>; map: Parameters<typeof compileMap>[0];
+  settings: RoomSettings; seats: number; vocab?: import('../agents/agents.ts').Vocabulary;
+}
+
+/** The rules and their private tunables stay inside this factory: the view is handed only the loader. */
+export function browserHost(def: RulesDef, game: BrowserGame): RulesHostFactory {
+  return (o) => {
+    const tune = lab.rulesTune(game.tune);
+    const compiled = compileRules(def, { ...game, tune, map: compileMap(game.map, String((game.map as { name?: string }).name ?? 'main')) });
+    const checkpoint = o.restore as { rules?: string; data?: any } | null;
+    if (o.restore && (checkpoint?.rules !== game.build || !checkpoint.data || typeof checkpoint.data !== 'object')) throw new Error('invalid checkpoint');
+    // Check depth iteratively before clone/encoding can recurse on untrusted checkpoint data.
+    if (checkpoint) {
+      const pending: [unknown, number][] = [[checkpoint.data, 0]];
+      let nodes = 0;
+      while (pending.length) {
+        const [value, depth] = pending.pop()!;
+        if (depth > 64 || ++nodes > 500000) throw new Error('invalid checkpoint depth or size');
+        if (value && typeof value === 'object') for (const child of Object.values(value)) pending.push([child, depth + 1]);
+      }
+    }
+    const saved = checkpoint ? structuredClone(checkpoint.data) : null;
+    if (saved && o.peers && Array.isArray(saved.core?.ents) && Array.isArray(saved.core?.seats)) {
+      // Identity is the relay's word. The previous host's save can preserve game state, never seat authority.
+      const peers = new Map([...o.peers, ...(o.held ?? [])].filter((p) => p.seat !== null).map((p) => [p.seat, p]));
+      const policy = o.policy;
+      const count = (n: unknown): number => typeof n === 'number' && Number.isFinite(n) ? Math.max(0, Math.min(game.seats - 1, Math.floor(n))) : 0;
+      const reserved = policy?.kind === 'hybrid' || policy?.kind === 'beginner' ? Math.min(game.seats - 1, count(policy.aiSeats) + (policy.kind === 'beginner' ? count(policy.guides) : 0)) : 0;
+      const identity = (seat: number): [string, string] => {
+        const peer = peers.get(seat);
+        return peer ? [peer.agent ? 'ai' : 'person', `p${peer.occ ?? peer.id}`] : seat >= game.seats - reserved && seat < game.seats ? ['ai', 'reserved'] : ['bot', ''];
+      };
+      const sameHolder = (q: any): boolean => !Array.isArray(q) || saved.core.seats.some((s: any) => Array.isArray(s) && s[0] === q[0] && s[1] === identity(q[0])[0] && s[2] === identity(q[0])[1]);
+      if (Array.isArray(saved.queues)) saved.queues = saved.queues.filter(sameHolder);
+      if (Array.isArray(saved.inputs)) saved.inputs = saved.inputs.filter(sameHolder);
+      if (Array.isArray(saved.names)) saved.names = saved.names.filter((row: any) => {
+        if (!Array.isArray(row)) return true;
+        const previous = saved.core.seats.find((s: any) => Array.isArray(s) && s[0] === row[0]);
+        return !(previous && previous[2] !== 'reserved' && identity(row[0])[1] === 'reserved');
+      });
+      for (const w of [...saved.core.ents, ...(Array.isArray(saved.core.spawns) ? saved.core.spawns : [])]) {
+        if (!Array.isArray(w)) throw new Error('invalid checkpoint entity');
+        const next = identity(w[11]);
+        if (w[12] !== next[0] || w[13] !== next[1]) w[15] = null;
+        [w[12], w[13]] = next;
+      }
+      for (const w of saved.core.seats) { if (!Array.isArray(w)) throw new Error('invalid checkpoint seat'); [w[1], w[2]] = identity(w[0]); }
+      for (const item of Array.isArray(saved.core.queue) ? saved.core.queue : []) {
+        if (Array.isArray(item) && item[6] === 'roundOver' && Array.isArray(item[7]?.results))
+          for (const row of item[7].results) if (row && typeof row === 'object') row.driver = identity(row.seat)[0];
+      }
+      saved.core.ops = [];
+    }
+    // A new authority rebases every player's input clock. Timers, dice, entities and round still come from the save.
+
+    const host = createHost({
+      game: game.id, build: game.build, compiled, send: o.send, restore: saved ? toBytes(saved) : null,
+      stage: lab.stage ?? undefined, startPaused: false, restoreEpoch: (Math.floor(Math.random() * 4294967296) >>> 0) || 1,
+      clock: { now: o.now, setTimer: (fn, ms) => setTimeout(fn, ms), clearTimer: (h) => clearTimeout(h as ReturnType<typeof setTimeout>) },
+      onEnd: o.onEnd,
+    });
+    if (game.vocab) host.frame({ t: 'vocabulary', vocab: game.vocab });
+    const present = new Set<number>();
+    const sync = (peers: Peer[]): void => {
+      const next = new Set(peers.flatMap((p) => p.seat === null ? [] : [p.seat]));
+      for (const seat of present) if (!next.has(seat)) host.frame({ t: 'leave', seat });
+      for (const body of host.core.bodies()) if (body.driver !== 'bot' && body.owner !== 'reserved' && !next.has(body.seat)) host.core.seatAway(body.seat, true);
+      for (const peer of peers) if (peer.seat !== null) host.frame({ t: 'join', peer });
+      present.clear(); for (const seat of next) present.add(seat);
+    };
+    return {
+      frame: (m) => {
+        if (m.t === 'join') { const p = m.peer as { seat?: number }; if (typeof p?.seat === 'number') present.add(p.seat); }
+        if (m.t === 'leave' || m.t === 'free') present.delete(Number(m.seat));
+        host.frame(m);
+      },
+      sync,
+      // A restored room may be behind what its last host told the relay: the shared state is said again with the round.
+      start: () => { host.start(); if (saved) o.send({ t: 'state', k: 'shared', d: host.core.shared() }); },
+      stop: () => host.stop(),
+      pause: () => host.pause(), resume: () => host.resume(), announce: () => host.announce(),
+      save: () => ({ rules: game.build, data: fromBytes(host.save()) }),
+      get tick() { return host.tick; },
+      facts: () => host.facts(),
+    };
+  };
+}