@homie-rocks/studio 0.20.0 → 0.22.0

package/lib/directory.mjs

@@ -5,12 +5,20 @@
  * nobody can list games under someone else's site.
  */
 import { request } from './net.mjs';
-import { readStudio, siteUrl } from './studio.mjs';
+import { listGames, readStudio, siteUrl } from './studio.mjs';
+import { licenceProblems, readManifest } from './asset-manifest.mjs';
 
 export async function publish(root, { homie, site } = {}) {
   const studio = readStudio(root);
   const directory = (homie || studio.homie?.directory || 'https://homie.rocks').replace(/\/+$/, '');
   const url = site || siteUrl(root, studio);
+  // Licences first: a public game may ship only assets with a licence record that allows it.
+  const refused = [];
+  for (const g of listGames(root)) {
+    if (g.launch === 'private' || g.launch === 'invite') continue;
+    for (const p of licenceProblems(root, g.id, readManifest(root, g.id), { public: g.share?.source !== false })) if (p.level === 'refuse') refused.push({ game: g.id, ...p });
+  }
+  if (refused.length) return { ok: false, command: 'publish', refused, why: `not listed: ${refused.length} asset licence problem${refused.length === 1 ? '' : 's'}:\n${refused.map((p) => `  ${p.game}/${p.asset}: ${p.problem}${p.fix ? ` (${p.fix})` : ''}`).join('\n')}\nhomie-studio assets check <id> says the same; fix them, deploy, then publish again.` };
   if (!url) return { ok: false, command: 'publish', why: 'this studio has no live site yet: run `npm run deploy` first' };
   const sent = await request(`${directory}/api/studio/publish`, {
     method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ site: url }),

package/lib/library.mjs

@@ -0,0 +1,169 @@
+/**
+ * THE HOMIE STARTER LIBRARY, from a studio: free CC0 models, materials and skies (Kenney, KayKit, Poly
+ * Haven, ambientCG), each optimised to Homie's phone budgets, with a thumbnail, its measurements, its licence, its
+ * origin and its SHA-256. Hosted by homie.rocks (https://homie.rocks/api/library/v0/); built by the repository's
+ * scripts/library.mjs.
+ *
+ *   searchLibrary(index, "fox forest", { kind, family })   ranked items (free, no account)
+ *   addFromLibrary(root, game, itemId, { as, height })       the item COPIED into games/<id>/public/models/ (checked by
+ *                                                            SHA-256 and the safety rules), with its manifest entry:
+ *                                                            route library, licence cc0, origin, pack, measurements
+ *
+ * A game never loads anything from homie.rocks at runtime: what it uses is copied in, so it works if the library moves.
+ * HOMIE_LIBRARY (a folder, or another address) points the studio at another copy of the library, such as a local one.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { LIMITS, checkGlb } from '../assets/safety.mjs';
+import { recordAsset } from './asset-manifest.mjs';
+import { GAME_ID } from './studio.mjs';
+
+export const LIBRARY_URL = 'https://homie.rocks/api/library/v0';
+const CACHE = join(homedir(), '.cache', 'homie-studio', 'library');
+const INDEX_MAX = 16 * 1024 * 1024;
+const FILE_MAX = 16 * 1024 * 1024;
+
+/** Where the library is: HOMIE_LIBRARY (a folder or an address), else homie.rocks. */
+export function libraryBase(from = process.env.HOMIE_LIBRARY) {
+  const v = String(from ?? '').trim();
+  if (!v) return { kind: 'url', base: LIBRARY_URL };
+  if (/^https?:\/\//i.test(v)) return { kind: 'url', base: v.replace(/\/+$/, '') };
+  const dir = resolve(v.replace(/^~(?=$|\/)/, homedir()));
+  return { kind: 'dir', base: dir };
+}
+
+async function getBytes(lib, rel, cap) {
+  if (!/^[A-Za-z0-9._/-]+$/.test(rel) || rel.split('/').includes('..')) throw new Error(`not a library path: ${rel}`);
+  if (lib.kind === 'dir') {
+    const file = join(lib.base, rel);
+    if (!existsSync(file)) throw new Error(`the library at ${lib.base} has no ${rel}`);
+    if (statSync(file).size > cap) throw new Error(`${rel} is over ${Math.round(cap / 1024 / 1024)} MB`);
+    return readFileSync(file);
+  }
+  const res = await fetch(`${lib.base}/${rel}`, { headers: { 'user-agent': 'homie-studio' }, signal: AbortSignal.timeout(30_000) });
+  if (!res.ok) throw new Error(`the library answered ${res.status} for ${rel}${res.status === 404 && rel === 'index.json' ? ' (it is not online at this address yet; HOMIE_LIBRARY can point at a local copy)' : ''}`);
+  const bytes = Buffer.from(await res.arrayBuffer());
+  if (bytes.byteLength > cap) throw new Error(`${rel} is over ${Math.round(cap / 1024 / 1024)} MB`);
+  return bytes;
+}
+
+/** The library's index: from the folder, or fetched (kept a day in the home folder's .cache/homie-studio/library). */
+export async function loadIndex({ lib = libraryBase(), fresh = false } = {}) {
+  let text = null;
+  if (lib.kind === 'url') {
+    const cached = join(CACHE, `${createHash('sha256').update(lib.base).digest('hex').slice(0, 12)}-index.json`);
+    if (!fresh && existsSync(cached) && Date.now() - statSync(cached).mtimeMs < 24 * 3600_000) text = readFileSync(cached, 'utf8');
+    else { text = (await getBytes(lib, 'index.json', INDEX_MAX)).toString('utf8'); mkdirSync(CACHE, { recursive: true }); writeFileSync(cached, text); }
+  } else text = (await getBytes(lib, 'index.json', INDEX_MAX)).toString('utf8');
+  const index = JSON.parse(text);
+  if (index?.kind !== 'homie-starter-library' || !Array.isArray(index.items)) throw new Error('that is not a Homie starter library index');
+  return { index, lib };
+}
+
+const words = (s) => String(s ?? '').toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim().split(/\s+/).filter(Boolean);
+const stem = (w) => w.replace(/(ies)$/, 'y').replace(/(es)$/, '').replace(/s$/, '');
+
+/**
+ * Ranked matches for `query`: [{ item, score, why }]. Every word counts: a tag or name hit beats a pack hit; `kind`,
+ * `family`, `pack` and `rigged` filter; a smaller file wins a tie (phones).
+ */
+export function searchLibrary(index, query, { kind = null, family = null, pack = null, rigged = null, limit = 12 } = {}) {
+  const q = words(query).map(stem);
+  const out = [];
+  for (const it of index.items) {
+    if (kind && it.kind !== kind) continue;
+    if (family && it.family !== family) continue;
+    if (pack && it.pack !== pack) continue;
+    if (rigged !== null && Boolean(it.rigged) !== Boolean(rigged)) continue;
+    const tags = new Set((it.tags ?? []).flatMap(words).map(stem));
+    const name = new Set(words(`${it.name} ${it.item}`).map(stem));
+    const packWords = new Set(words(`${it.pack} ${it.family}`).map(stem));
+    let score = 0;
+    const why = [];
+    for (const w of q) {
+      if (name.has(w)) { score += 3; why.push(w); } else if (tags.has(w)) { score += 2; why.push(w); } else if (packWords.has(w)) score += 0.5;
+      else if ([...name, ...tags].some((t) => t.length > 3 && (t.startsWith(w) || w.startsWith(t)))) { score += 1; why.push(`${w}~`); }
+    }
+    if (!q.length) score = 1;
+    if (score > 0) out.push({ item: it, score: score - Math.min(0.4, (it.files?.[0]?.bytes ?? 0) / 4_000_000), why });
+  }
+  return out.sort((a, b) => b.score - a.score || a.item.id.localeCompare(b.item.id)).slice(0, limit);
+}
+
+/** One item's file bytes, checked by SHA-256 against the index and by the GLB safety rules. */
+export async function fetchItemFile(lib, item, file = item.files?.find((f) => f.role === 'model') ?? item.files?.[0]) {
+  if (!file) throw new Error(`${item.id} has no file`);
+  const bytes = await getBytes(lib, file.path, FILE_MAX);
+  const sum = createHash('sha256').update(bytes).digest('hex');
+  if (file.sha256 && sum !== file.sha256) throw new Error(`${file.path}: its SHA-256 does not match the library's index (refused)`);
+  if (/\.glb$/i.test(file.path)) { const s = checkGlb(bytes, LIMITS.game); if (!s.ok) throw new Error(`${file.path}: ${s.problems.join('; ')}`); }
+  return { bytes, sha256: sum };
+}
+
+/** A library item's thumbnail as bytes (for cards), or null. */
+export async function itemThumb(lib, item) {
+  if (!item.thumb) return null;
+  try { return await getBytes(lib, item.thumb, 512 * 1024); } catch { return null; }
+}
+
+const KIND_DIR = { texture: 'tex', sky: 'sky' };
+
+/**
+ * Copy one library item into a game and record it (assets/manifest.json, RIGHTS.md, credits.json). `as`: the asset's
+ * id in the game (default: the item's own name); `height`: metres to scale it to (models; default its suggested size).
+ * Returns { ok, asset, files, pinned }.
+ */
+export async function addFromLibrary(root, game, itemId, { as = null, height = null, card = null, lib = libraryBase(), index = null } = {}) {
+  if (!GAME_ID.test(String(game ?? ''))) throw new Error(`"${game}" is not a game id`);
+  const gdir = join(root, 'games', game);
+  if (!existsSync(gdir)) throw new Error(`no game "${game}"`);
+  const idx = index ?? (await loadIndex({ lib })).index;
+  const item = idx.items.find((x) => x.id === itemId) ?? idx.items.find((x) => x.item === itemId);
+  if (!item) throw new Error(`no library item "${itemId}" (assets find <words> lists them)`);
+  if (item.license !== 'cc0') throw new Error(`${item.id} is not CC0; the starter library holds only CC0`);
+  const id = String(as ?? item.item).toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48);
+  const files = [];
+  let measured = null;
+  if (item.kind === 'texture' || item.kind === 'sky') {
+    for (const f of item.files ?? []) {
+      const { bytes, sha256 } = await fetchItemFile(lib, item, f);
+      const rel = `public/${KIND_DIR[item.kind]}/${id}/${f.path.split('/').pop()}`;
+      mkdirSync(dirname(join(gdir, rel)), { recursive: true });
+      writeFileSync(join(gdir, rel), bytes);
+      files.push({ role: f.role, path: rel, bytes: bytes.byteLength, sha256 });
+    }
+  } else {
+    let { bytes, sha256 } = await fetchItemFile(lib, item);
+    const rel = `public/models/${id}.glb`;
+    mkdirSync(dirname(join(gdir, rel)), { recursive: true });
+    const want = Number(height ?? item.suggestM ?? 0);
+    let ops = [];
+    if (want > 0 && item.heightM && Math.abs(want / item.heightM - 1) > 0.02) {
+      // Scaled to the game's size here (the library's own file is unchanged; its SHA-256 is in from.sha256).
+      const { optimiseModel } = await import('./optimise.mjs');
+      const r = await optimiseModel(bytes, { height: want, triangles: 0, texture: Math.max(16, item.texturePx || 512), rigged: Boolean(item.rigged), metal: true });
+      bytes = Buffer.from(r.glb);
+      sha256 = r.sha256;
+      ops = r.ops;
+      measured = r.after;
+    }
+    writeFileSync(join(gdir, rel), bytes);
+    files.push({ role: 'model', path: rel, bytes: bytes.byteLength, sha256 });
+    if (ops.length) files[0].ops = ops;
+  }
+  const entry = {
+    id, kind: item.kind === 'creature' ? 'creature' : item.kind, tier: item.tier ?? 'prop', card, route: 'library',
+    from: { library: 'homie-starter', version: idx.version ?? 'v0', pack: item.pack, packLabel: idx.packs?.find((p) => p.id === item.pack)?.label ?? item.pack, packUrl: idx.packs?.find((p) => p.id === item.pack)?.url ?? null, item: item.id, author: item.author ?? null, origin: item.origin ?? null, sha256: item.files?.[0]?.sha256 ?? null, paletteSwap: Boolean(item.paletteSwap) },
+    files,
+    license: { kind: 'cc0', spdx: 'CC0-1.0', owner: item.author ?? null, attribution: null, remix: 'include', notes: `From the Homie starter library (${item.pack}); the pack's own licence text: ${idx.packs?.find((p) => p.id === item.pack)?.licenseFile ?? 'licenses/'}` },
+    measured: measured ? { tris: measured.triangles, materials: measured.materials, drawCalls: measured.drawCalls, textures: measured.textures.map((t) => ({ px: t.px, format: t.mimeType, gpuKB: Math.round(t.gpuBytes / 1024) })), bones: measured.bones, clips: measured.clips.length, heightM: measured.heightM, box: measured.box, glbKB: Math.round(files[0].bytes / 1024), flat: Boolean(item.paletteSwap) }
+      : { tris: item.tris ?? null, materials: item.materials ?? null, drawCalls: item.drawCalls ?? null, bones: item.bones ?? 0, clips: (item.clips ?? []).length, heightM: item.heightM ?? null, box: item.box ? { size: item.box } : null, glbKB: Math.round((files[0]?.bytes ?? 0) / 1024), flat: Boolean(item.paletteSwap) },
+    made: { steps: [{ what: 'library', item: item.id, sha256: item.files?.[0]?.sha256 ?? null }, ...(files[0]?.ops ? [{ what: 'optimise', tool: '@gltf-transform/functions', ops: files[0].ops }] : [])] },
+    review: { state: 'auto' },
+  };
+  const { entry: e, pinned } = recordAsset(root, game, entry);
+  return { ok: true, command: 'assets add', game, asset: e.id, item: item.id, files: files.map((f) => f.path), pinned, license: 'CC0 1.0' };
+}
+

package/lib/mcp-tools.mjs

@@ -35,6 +35,7 @@ import { pinnedVersion } from './upgrade.mjs';
 import { AgentSeat } from './agent-seat.mjs';
 import { LAB_PORT, runningLab } from './lab.mjs';
 import { pictureFor } from './pictures.mjs';
+import { ART_UI, artToolDefs } from './art-tools.mjs';
 
 export const UI = Object.freeze({
   setup: 'ui://homie-studio/setup',
@@ -42,6 +43,7 @@ export const UI = Object.freeze({
   studio: 'ui://homie-studio/studio',
   codex: 'ui://homie-studio/codex',
   lab: 'ui://homie-studio/lab',
+  ...ART_UI,
 });
 
 const inside = (base, p) => p === base || p.startsWith(base.endsWith(sep) ? base : `${base}${sep}`);
@@ -698,7 +700,7 @@ export function toolDefs(ctx, avail = {}) {
     },
     {
       name: 'game_make', title: 'Make a multiplayer game',
-      description: 'Make a game in the studio from a multiplayer starter, under the id you choose, to change into the person\'s game: gem-rush (an arena: every browser renders, one hosts the rules, bots fill empty seats, rounds restart) or ember-vale (a hero who lasts for days, with cloud saves: for persistent games). In a new studio only once their game is planned (game_plan), or when they ask for a copy of a working starter; never as a first step. A planned game\'s codex stays.',
+      description: 'Make a game in the studio from a multiplayer starter, under the id you choose, to change into the person\'s game: gem-rush (an arena: every browser renders, one hosts the rules, bots fill empty seats, rounds restart), gem-rush-3d (the same arena in three.js, dressed with free CC0 models through @homie-rocks/studio/assets: the start for a 3D game) or ember-vale (a hero who lasts for days, with cloud saves: for persistent games). In a new studio only once their game is planned (game_plan), or when they ask for a copy of a working starter; never as a first step. A planned game\'s codex stays.',
       inputSchema: { type: 'object', properties: { id: str('The game\'s id (lowercase, digits, hyphens): its address'), name: str('The game\'s display name'), from: str('Starter id (default gem-rush)'), ...STUDIO_ARG }, required: ['id', 'name'] },
       annotations: { title: 'Make a game', ...RW },
       run: async (a) => {
@@ -707,7 +709,21 @@ export function toolDefs(ctx, avail = {}) {
         const r = await cli(ctx, root, `game new ${a.id}`, ['game', 'new', a.id, '--from', String(a.from ?? 'gem-rush'), '--name', String(a.name ?? a.id).slice(0, 60)]);
         if (!r.ended) return stillRunning(r.job, 'Making the game');
         if (r.job.code !== 0) return fail(`Not made: ${whyOf(r.job)}`);
-        return ok(`games/${a.id} is ${a.name}, from the ${a.from ?? 'gem-rush'} starter (${(r.result?.files ?? []).length} files). Change it in games/${a.id}/src/main.ts (file_read, file_edit), then build and preview_run; check proves two browsers finish a round.`, { kind: 'game', ...r.result });
+        // A starter that needs a library the studio did not have (game.json "needs", e.g. three.js): it is in the
+        // studio's package.json now, and nothing builds until it is installed, so the install starts here.
+        let install = '';
+        if (r.result?.installNeeded) {
+          const libs = (r.result.needsAdded ?? []).map((n) => `${n.name} ${n.version}`).join(', ');
+          if (ctx.install) {
+            const running = runningJobs(root).find((j) => j.label.startsWith('npm install'));
+            let job = running ?? null;
+            if (!job) { try { job = installJob(root); } catch (error) { install = ` It needs ${libs}, added to the studio's package.json, but the install did not start (${error.message}): studio_install installs it.`; } }
+            if (job) install = ` It needs ${libs}, added to the studio's package.json; npm install is running (job ${job.id}): build once studio_job says it is done.`;
+          } else install = ` It needs ${libs}, added to the studio's package.json: studio_install installs it before the first build.`;
+        }
+        const m = r.result?.models;
+        const got = m ? ` Its models: ${m.fetched} from the starter library${m.missing.length ? `; ${m.missing.length} could not be fetched (${m.why ?? m.missing[0].why}), and it draws stand-ins for those` : ''}.` : '';
+        return ok(`games/${a.id} is ${a.name}, from the ${a.from ?? 'gem-rush'} starter (${(r.result?.files ?? []).length} files).${got}${install} Change it in games/${a.id}/src/main.ts (file_read, file_edit), then build and preview_run; check proves two browsers finish a round.`, { kind: 'game', ...r.result });
       },
     },
     {
@@ -1152,6 +1168,8 @@ export function toolDefs(ctx, avail = {}) {
       },
     },
   ];
+  // Art direction, the cast, the starter library, generated props, checks, the lineup and the rights (lib/art-tools.mjs).
+  tools.push(...artToolDefs(ctx, { ok, fail, cli, stillRunning, whyOf, needsInstall, ui, str, STUDIO_ARG, RO, RW, pictureFor, findNode, startJob, waitJob }));
   const topics = guideTopics(ctx);
   if (topics.length) {
     tools.push({
@@ -1173,7 +1191,7 @@ export function toolDefs(ctx, avail = {}) {
     });
   }
   // The media skills' own scripts, where their provider (or the free tool they need) is set up on this computer.
-  for (const [name, title, needs] of [['music', 'Music (ElevenLabs)', 'elevenlabs'], ['sound', 'Sound effects and a theme (free)', 'ffmpeg'], ['art', 'Art: covers, frames, painted art', 'ffmpeg'], ['video', 'Video: trailers and clips', 'ffmpeg']]) {
+  for (const [name, title, needs] of [['music', 'Music (ElevenLabs)', 'elevenlabs'], ['sound', 'Sound effects and a theme (free)', 'ffmpeg'], ['art', 'Art: covers, frames, painted art', 'ffmpeg'], ['video', 'Video: trailers and clips', 'ffmpeg'], ['models', 'Models: generated 3D props (paid, on your fal account)', 'node']]) {
     const script = ctx.skillsDir ? join(ctx.skillsDir, name, 'scripts', `${name}.mjs`) : null;
     if (!script || !existsSync(script) || !avail[needs]) continue;
     tools.push({
@@ -1201,7 +1219,7 @@ export function toolDefs(ctx, avail = {}) {
 
 /** What the media tools need, cheaply (no network): ffmpeg on the PATH, ElevenLabs' CLI or key. */
 export function availability(env = process.env) {
-  return { ffmpeg: Boolean(which(process.platform === 'win32' ? 'ffmpeg.exe' : 'ffmpeg')), elevenlabs: Boolean(env.ELEVENLABS_API_KEY || which(process.platform === 'win32' ? 'elevenlabs.exe' : 'elevenlabs')) };
+  return { node: true, ffmpeg: Boolean(which(process.platform === 'win32' ? 'ffmpeg.exe' : 'ffmpeg')), elevenlabs: Boolean(env.ELEVENLABS_API_KEY || which(process.platform === 'win32' ? 'elevenlabs.exe' : 'elevenlabs')) };
 }
 
 /** The codex page small enough to hand a card (a tool result over ~150,000 characters is not shown). */

package/lib/mcp.mjs

@@ -48,10 +48,12 @@ Links are the person's to open: give them in your reply (the cards have their ow
 
 To make one mechanic of a game feel better (a jump, a hit, a dash), game_lab opens the Game Lab: New beside Today, one take, its phases and sliders (studio_guide { "topic": "lab" }).
 
+A game's look is a set of decisions (render style, palette, light, camera, fonts, the cast and its budgets), automatic from the person's words until they steer or lock one (studio_guide { "topic": "style" }). style_explore draws three directions with the game engine for free; decision_set picks, steers and locks; assets_find searches the free CC0 starter library and asset_add copies a model in with its licence; asset_make makes a prop on the person's own fal account only after they agreed to its price; asset_check, asset_lineup and asset_rights keep it one game, phone-sized and properly licensed (studio_guide { "topic": "models" }).
+
 Long work (npm install, check, playtest, deploy, renders) runs in the background: the tool answers at once with a card that follows it, and build_progress or studio_job reads where it is. studio_guide has Homie's full guide for each job (game, plan, port, playtest, publish, music, sound, art, video). Never put a key or password in a file or the chat. If Homie's homie.rocks connector is connected too, its tools of the same names say what to run; these run it.`;
 
-const CARD_FILES = { [UI.setup]: 'setup.js', [UI.build]: 'build.js', [UI.studio]: 'studio.js', [UI.codex]: 'codex.js', [UI.lab]: 'lab.js' };
-const CARD_TITLES = { [UI.setup]: 'Studio setup', [UI.build]: 'Build progress', [UI.studio]: 'Studio', [UI.codex]: 'Game Codex', [UI.lab]: 'Game Lab' };
+const CARD_FILES = { [UI.setup]: 'setup.js', [UI.build]: 'build.js', [UI.studio]: 'studio.js', [UI.codex]: 'codex.js', [UI.lab]: 'lab.js', [UI.style]: 'style.js', [UI.decision]: 'decision.js', [UI.cast]: 'cast.js', [UI.lineup]: 'lineup.js', [UI.rights]: 'rights.js' };
+const CARD_TITLES = { [UI.setup]: 'Studio setup', [UI.build]: 'Build progress', [UI.studio]: 'Studio', [UI.codex]: 'Game Codex', [UI.lab]: 'Game Lab', [UI.style]: 'Style board', [UI.decision]: 'Look decision', [UI.cast]: 'Cast', [UI.lineup]: 'Lineup', [UI.rights]: 'Rights' };
 const UI_DIR = join(PACKAGE_ROOT, 'mcp', 'ui');
 
 /** One card's whole document: the shared look and bridge, and the card's own script, as the files are. */
@@ -67,7 +69,8 @@ export function cardHtml(uri) {
 
 /** What a card may load: nothing from the network, except the codex page's Google Fonts. */
 export function cardCsp(uri) {
-  if (uri === UI.codex) return { connectDomains: [], resourceDomains: ['https://fonts.googleapis.com', 'https://fonts.gstatic.com'] };
+  // The codex page, and the style board's type samples in each direction's fonts: Google Fonts only.
+  if (uri === UI.codex || uri === UI.style) return { connectDomains: [], resourceDomains: ['https://fonts.googleapis.com', 'https://fonts.gstatic.com'] };
   return { connectDomains: [], resourceDomains: [] };
 }
 

package/lib/office.mjs

@@ -10,6 +10,7 @@
  *   homie-studio office invite <game> [--label "<who>"] [--uses 1|<n>|any] [--count 1] [--days <n>]
  *   homie-studio office launch <game> private|invite|public [--remixable on|off] [--max <n>|game]
  *   homie-studio office kick <game> <room> <seat number | name> [--minutes 10]
+ *   homie-studio office mute <game> <room> <seat number | name> [--minutes 10] [--off]
  *   homie-studio office close <game> <room> [--minutes 10] [--reopen]
  *   homie-studio office revoke                         every office key ends; every play ticket and pending ask too
  *
@@ -121,21 +122,42 @@ export async function officeLaunch(root, game, state, { url, remixable, max } =
   return askedFor(root, url, r, 'office launch');
 }
 
+/** One player of one live room, by seat number (from 1) or name: { room, client } or { message }. */
+async function playerIn(call, game, room, who) {
+  const office = await call('/_studio/api/office');
+  const g = (office.games ?? []).find((x) => x.id === game);
+  const rm = (g?.rooms ?? []).find((x) => x.room === room || x.label.toLowerCase() === String(room).toLowerCase());
+  if (!rm) return { message: `nobody is in ${room} of ${game} now (homie-studio office lists the rooms)` };
+  const seat = /^\d+$/.test(String(who)) ? Number(who) - 1 : null;
+  const c = rm.clients.find((x) => (seat !== null && x.seat === seat) || String(x.name).toLowerCase() === String(who).toLowerCase());
+  if (!c) return { message: `no "${who}" in ${rm.label} (seats are numbered from 1)` };
+  return { room: rm, client: c };
+}
+
 export async function officeKick(root, game, room, who, { url, minutes } = {}) {
   if (!GAME.test(String(game ?? '')) || !room || who === undefined) return { ok: false, command: 'office kick', why: 'usage: homie-studio office kick <game> <room> <seat number | name> [--minutes 10]' };
   const r = await withKey(root, url, async (call) => {
-    const office = await call('/_studio/api/office');
-    const g = (office.games ?? []).find((x) => x.id === game);
-    const rm = (g?.rooms ?? []).find((x) => x.room === room || x.label.toLowerCase() === String(room).toLowerCase());
-    if (!rm) return { ok: false, message: `nobody is in ${room} of ${game} now (homie-studio office lists the rooms)` };
-    const seat = /^\d+$/.test(String(who)) ? Number(who) - 1 : null;
-    const c = rm.clients.find((x) => (seat !== null && x.seat === seat) || String(x.name).toLowerCase() === String(who).toLowerCase());
-    if (!c) return { ok: false, message: `no "${who}" in ${rm.label} (seats are numbered from 1)` };
-    return call('/_studio/api/kick', { game, room: rm.room, id: c.id, minutes: Number(minutes) || 10 });
+    const p = await playerIn(call, game, room, who);
+    if (!p.client) return { ok: false, message: p.message };
+    return call('/_studio/api/kick', { game, room: p.room.room, id: p.client.id, minutes: Number(minutes) || 10 });
   });
   return askedFor(root, url, r, 'office kick');
 }
 
+/**
+ * `office mute <game> <room> <seat | name> [--minutes 10] [--off]`: the player's chat and emotes reach nobody for a
+ * while (`--off` lifts it). Like a kick, it is only ASKED for: the owner confirms with one tap.
+ */
+export async function officeMute(root, game, room, who, { url, minutes, off = false } = {}) {
+  if (!GAME.test(String(game ?? '')) || !room || who === undefined) return { ok: false, command: 'office mute', why: 'usage: homie-studio office mute <game> <room> <seat number | name> [--minutes 10] [--off]' };
+  const r = await withKey(root, url, async (call) => {
+    const p = await playerIn(call, game, room, who);
+    if (!p.client) return { ok: false, message: p.message };
+    return call('/_studio/api/mute', { game, room: p.room.room, id: p.client.id, minutes: Number(minutes) || 10, ...(off ? { off: true } : {}) });
+  });
+  return askedFor(root, url, r, 'office mute');
+}
+
 export async function officeClose(root, game, room, { url, minutes, reopen } = {}) {
   if (!GAME.test(String(game ?? '')) || !room) return { ok: false, command: 'office close', why: 'usage: homie-studio office close <game> <room> [--minutes 10] [--reopen]' };
   const r = await withKey(root, url, (call) => call('/_studio/api/close', { game, room, minutes: Number(minutes) || 10, reopen: Boolean(reopen) }));