@homie-rocks/studio 0.21.0 → 0.22.0

package/CHANGELOG.md

@@ -17,9 +17,47 @@ To bring a studio up to date, tell Claude: "Upgrade my studio to the newest Homi
 `npx -y @homie-rocks/studio@latest upgrade`, which shows what's new since the version your studio pins (from this
 file) and what the upgrade would change, and changes nothing until you agree.
 
+## [0.22.0] - 2026-10-02
+
+**Plugin 0.23.0** · [#32](https://github.com/homie-rocks/homie/pull/32)
+
+Your game's look as decisions you can steer and lock, a style board the engine draws for free, free CC0 3D models, props made on your own fal account, and every asset licensed and checked for phones.
+
+### Added
+
+- `homie-studio style`: your game's look as about thirty decisions (render style, palette, shape, proportions, materials, light, camera, fonts, effects; the cast, its library family, scale and phone budgets; rigs and animation for later). `style init <game> --prompt "…"` picks each from your words, the codex and the genre, with a one-line why, and the Game Codex's Art direction tab draws them. `style steer` nudges one in your words ("warmer", "closer", "golden hour"), `style lock` freezes one for you, and the first model built on an automatic decision pins it.
+- `homie-studio style board <game>`: three coherent directions, each drawn by the game's own engine (its palette, light, camera, material model, fonts and proportions, with the starter library's pieces re-tinted into its palette). Free, in about 20 seconds. Pick one, mix rows from several, steer, lock. A painted mood image per direction is optional and paid, on your own fal account, and labelled a target.
+- Changing a locked decision shows its blast radius first (`style blast`): every model made under it that would go stale, what remaking each would cost, and what a free palette re-tint fixes. Nothing is ever remade by itself.
+- `homie-studio assets`: every model, texture and sky a game ships is recorded in `games/<id>/assets/manifest.json` with where it came from, each step that made it, its licence and what a remix gets. `assets rights` writes `RIGHTS.md` in plain words, credits go on the game's landing, and `assets remove` takes a model out with the copy the game ships.
+- Homie's starter library: free CC0 models, materials and skies from Kenney, KayKit, Poly Haven and ambientCG, made phone-sized, with thumbnails and their licences. `assets find "pine tree"` searches it and `assets add <game> <item>` copies one into the game (never hot-linked). It is served from homie.rocks; `HOMIE_LIBRARY` points at another copy.
+- `assets add <game> --file <model> --license <kind>`: your own models, checked first (a file that loads anything from an address, or is too big, is refused), made phone-sized (meshopt geometry, WebP pictures, the pivot at the bottom centre, scaled to metres) and recorded. The raw file stays in `art/<slug>/raw/`, which git ignores, and `assets redo <game> <asset>` makes it again from there for free. Unless the game's render style is `pbr`, models are made non-metal: metal with nothing to reflect draws black on a phone.
+- `assets check <game>`: every model against phone budgets (triangles, draw calls, picture memory, the first-play download), the Khronos glTF-Validator, its licence, and whether a decision it was made under has changed. `assets lineup <game>` draws them side by side at true scale on a 1 m grid, with their silhouettes and how far their colours drift from the palette. The first-play download counts one file per sound (a browser fetches the .ogg or its .wav fallback, never both).
+- `@homie-rocks/studio/assets`: one model loader for three.js games. It refuses unsafe or oversized files before three.js reads them, decodes meshopt, clones skinned models properly, and says in development when a model is over its budget. `stylize` draws a model in the game's material model and ink outline from `style.json`, the way the style board drew it.
+- A starter in 3D: `game new <id> --from gem-rush-3d` is Gem Rush's rules drawn with three.js and dressed with models from the starter library. `game new` fetches them, checked by SHA-256 (the repository holds no model file), and a game you already planned keeps its decisions, its `style.json` and its own models. Its light, ground and materials follow the style board: faceted low-poly ground and grass in the palette's greens, every model drawn in the style's materials and outline, the gem in the palette's gold, the animals' colours pulled toward the palette, and the sun's real shadows on a computer (soft discs on a phone). The camera looks past the clearing into the woods; a phone held upright follows its player from closer and lower, so the action fills it. The game opens on a short title card with its name, and its HUD, results and name labels share one paper-and-ink look that reads in any palette. The meadow is a clearing with a campfire at its heart and a few solid rocks, bushes and a tree players move round; game.json `"scoring": "together"` turns the ranking into one total the room fills, for a cozy game. `assets lineup` draws each model at the height and in the colours the game gives it.
+- A remix now arrives with its models: the original site serves `/games/<id>/assets.json`, and `game remix` fetches every model its licence lets a remix carry, checked by SHA-256, with a grey placeholder of the same size for the rest. It adds three.js when the game needs it, and no other package by itself.
+- Homie for Claude Desktop: the tools `style_explore`, `style_board`, `decision_set`, `assets_plan`, `assets_find`, `asset_add`, `asset_make`, `asset_check`, `asset_lineup` and `asset_rights`, with style board, look decision, cast, lineup and rights cards.
+- Plugin: the `style` skill (decisions, the board, locks and the blast radius) and the `models` skill (the starter library, your own models, and generated props: a concept in the locked style, then Tripo P1 image-to-3D, on your own fal account under a budget with a receipt per call, about US$0.54 a prop). The plan asks whether you want to steer the look and what art budget you have.
+- Plugin: the Studio mod's Art tab and its commands `/look`, `/lock`, `/assets`, `/lineup` and `/rights`; it refuses a hand edit to a locked decision, a deploy that ships an unlicensed model, and a commit of a big binary under `games/`, and holds a paid prop past the budget.
+- `games/<id>/style.json`: the palette, fonts, light and camera a game draws with. Its landing takes its accents from it, and the video skill's title cards (`card --game <id>`) wear its palette and font.
+
+### Changed
+
+- A game with an art direction gets its play page's buttons in its own paper and ink (from `style.json`), so they match its HUD.
+- Gather games pick a low three-quarter camera: down among the players, the woods beyond the clearing in view.
+- Local development never shows a phone an address it cannot open: the TV view drops its join card, the landing drops its code, and the room button's sheet says to deploy to share (every starter: the page is the studio's).
+- `publish` refuses to list a studio while a public game ships a model with no licence record, or one whose licence forbids it.
+- `check` refuses a game with a binary over 5 MB committed under `games/` (it belongs in R2).
+- The remix source leaves out each game's `codex/` folder (its decisions and style board), like `CODEX.md`.
+- `@homie-rocks/studio` now depends on three.js, @gltf-transform, meshoptimizer, sharp and the Khronos glTF-Validator (about 60 MB more in a studio's `node_modules`).
+
+### Upgrade notes
+
+- `homie-studio upgrade --apply` adds the art section to AGENTS.md and `.gitignore` lines for raw 3D files (`art/**/raw/`, `*.blend`, `*.fbx`). Commit no raw model file: move any already committed into `art/<slug>/raw/`.
+- The starter library is served from homie.rocks once it is online; until then `assets find` says so, and `HOMIE_LIBRARY` can point at a local copy.
+
 ## [0.21.0] - 2026-10-02
 
-**Plugin 0.22.0** · [#31](https://github.com/homie-rocks/homie/pull/31)
+**Plugin 0.22.0** · [#31](https://github.com/homie-rocks/homie/pull/31) · [release-2026-10-02-studio-0.21.0](https://github.com/homie-rocks/homie/releases/tag/release-2026-10-02-studio-0.21.0)
 
 The Homie mod for Claude Code: your studio, its rooms and a real seat in a live game beside the chat, with a look
 before protected files, deploys and spending, and keys kept out of what Claude reads.

package/README.md

@@ -17,6 +17,9 @@ npx homie-studio dev                                   # the whole site locally
 npx homie-studio check crown-thief --url http://127.0.0.1:8787
 npx homie-studio perf crown-thief --url http://127.0.0.1:8787   # how fast it runs: a computer and an emulated phone, host and replica
 npx homie-studio lab crown-thief                       # the Game Lab: how a move feels, New beside Today, frame by frame
+npx homie-studio style board crown-thief               # its look as decisions: three directions drawn by the engine (free)
+npx homie-studio assets find "pine tree"               # free CC0 models from Homie's starter library, phone-sized
+npx homie-studio assets check crown-thief              # every model against phone budgets, the validator and its licence
 npx homie-studio deploy --plan                         # what deploy will create, and what it costs; changes nothing
 npx homie-studio deploy                                # the studio's own Cloudflare
 npx homie-studio publish                               # the homie.rocks directory
@@ -491,6 +494,58 @@ replay check), REPORT.md (New against Today), sheet.png (the lab at each phase's
 The local MCP's `game_lab` starts the lab and answers with a card. The Homie plugin's `lab` skill has the method:
 instrument and commit first (Today is the game as it is), then change how it feels, and keep what the person likes.
 
+## Art direction and models (`homie-studio style`, `homie-studio assets`)
+
+```sh
+npx homie-studio style init crown-thief --prompt "a cozy low-poly forest where foxes gather berries"
+npx homie-studio style crown-thief                       # every decision: · auto  ~ steered  ● pinned by use  ■ locked
+npx homie-studio style board crown-thief                 # three directions, drawn by the game engine: codex/board/*.jpg
+npx homie-studio style pick crown-thief b --mix style.camera=a
+npx homie-studio style steer crown-thief style.palette "warmer"
+npx homie-studio style lock crown-thief style.palette --words "keep that palette"
+npx homie-studio style blast crown-thief style.palette   # what a change would make stale, and what remaking costs
+npx homie-studio assets find "fox" --kind creature        # the starter library (HOMIE_LIBRARY: another copy)
+npx homie-studio assets add crown-thief kenney-cube-pets/animal-fox --height 0.7 --card "Characters/Fox"
+npx homie-studio assets add crown-thief --file ./lantern.glb --license own --height 0.6
+npx homie-studio assets check crown-thief                # budgets, the glTF-Validator, licences, staleness, big files
+npx homie-studio assets lineup crown-thief               # true scale, silhouettes, palette drift: .studio/art/<id>/
+npx homie-studio assets rights crown-thief               # games/<id>/assets/RIGHTS.md and the credits
+npx homie-studio assets redo crown-thief lantern         # made again from its kept raw file, free
+npx homie-studio assets remove crown-thief lantern       # the record and the copy the game ships
+```
+
+A game's look is a set of decisions (`games/<id>/codex/decisions.json`, private like the codex, drawn in its Art
+direction tab): render style, palette, shape, proportions, materials, light, camera, fonts and effects; the cast, its
+library family, scale and phone budgets; rigs and animation (later phases). Each starts as an automatic pick with a
+why. A person's nudge makes it steered, their lock freezes it, and the first asset built on an automatic one pins it.
+Every asset records the revision of each decision it was made under, so changing one lists exactly what went stale and
+what remaking it would cost; nothing is remade by itself. `games/<id>/style.json` (public) is the palette, fonts, light
+and camera the game, its landing and its title cards draw with.
+
+Every model, texture and sky a game ships has an entry in `games/<id>/assets/manifest.json`: its route (procedural,
+library, generated, imported), each step that made it, its licence and what a remix gets, its measurements. From it:
+`RIGHTS.md`, the credits on the game's landing, `assets check`, the licence check `publish` makes, and
+`/games/<id>/assets.json` on the site, from which `game remix` fetches every model its licence lets a remix carry
+(checked by SHA-256; a grey placeholder of the same size for the rest). Models are refused when they load anything
+from an address or are over the size caps; `assets add` makes them phone-sized (meshopt geometry, WebP pictures, the
+pivot at the bottom centre, scaled to metres) with @gltf-transform, meshoptimizer and sharp; raw files stay in
+`art/<slug>/raw/`, which git ignores.
+
+In a three.js game, `@homie-rocks/studio/assets` is the one loader:
+
+```ts
+import { createModels } from '@homie-rocks/studio/assets';
+const models = createModels();
+const fox = await models.instance('./models/fox.glb').catch(() => models.placeholder({ x: 0.6, y: 0.7, z: 0.9 }));
+```
+
+It checks every file before three.js parses it (no external URIs, no buffer over the cap, only extensions three.js
+reads), decodes meshopt, clones skinned models properly, and says in development when a model is over its budget
+(`stats()`, `window.__homieModels`). `game new <id> --from gem-rush-3d` is Gem Rush in 3D, dressed from the library.
+The local MCP's `style_explore`, `decision_set`, `assets_plan`, `assets_find`, `asset_add`, `asset_make`,
+`asset_check`, `asset_lineup` and `asset_rights` do the same with cards. Generated props (on the person's own fal
+account, under a budget, receipted) are the Homie plugin's `models` skill.
+
 ## Checks on a computer without a GPU
 
 `check`, `port check` and `look` run Chrome headless. On a Mac they use its GPU. On Linux (a Claude Code cloud

package/assets/assets.ts

@@ -0,0 +1,500 @@
+/*
+ * @homie-rocks/studio/assets — ONE MODEL LOADER FOR EVERY three.js GAME A STUDIO MAKES.
+ *
+ *   import { createModels } from '@homie-rocks/studio/assets';
+ *   const models = createModels();                         // one per game
+ *   const fox = await models.instance('./models/fox.glb');   // a copy to place (skinned models too)
+ *   scene.add(fox);
+ *
+ * Every model is a self-contained glTF binary (.glb) from the game's own files (games/<id>/public/models/), made
+ * phone-sized by `homie-studio assets add` or `assets optimise`: meshopt geometry and WebP pictures, decoded here.
+ * Before three.js parses a byte, the file is checked (assets/safety.mjs, the same rules `assets check` and
+ * `assets add` use): a file over the size cap, a buffer or picture loaded from an address (an external URI), an
+ * accessor reaching past its buffer or an extension three.js cannot read is REFUSED. A refused or missing model
+ * rejects with a plain-words Error; `models.placeholder()` is a grey box of the size it would have been, so a round
+ * never waits on a model.
+ *
+ * Models load from the game's own origin only (relative addresses): a game never depends on another site at
+ * runtime (homie.rocks's starter library is copied into the game, never hot-linked). `allowOrigins` opens one on
+ * purpose.
+ *
+ * In development (localhost, or ?debug=1) a model over its budget says so in the console, and `stats()` (also
+ * `window.__homieModels`) has the totals the perf skill reads: models, triangles, texture memory and refusals.
+ *
+ * KTX2 pictures (KHR_texture_basisu) need a transcoder (about 580 KB): pass your own KTX2Loader as `ktx2` when a
+ * game ships them (`assets check` says when); WebP, the default, needs nothing.
+ *
+ * Things a game repeats (trees, gems, a fence) are instanced, one draw call per mesh however many there are:
+ *
+ *   const copies = instancedCopies((await models.load('./models/tree.glb')).scene, 40);
+ *   copies.forEach((c) => { placeCopy(c, 0, where); c.mesh.count = 1; scene.add(c.mesh); });
+ *
+ * Never bake a mesh's own transform into its geometry for that (geometry.applyMatrix4): an optimised model's positions
+ * are meshopt-quantized int16, dequantized by its node's scale, and a baked scale clips everything past one metre.
+ *
+ * A flat-coloured model (a library item with `paletteSwap`: its colours in one tiny palette picture) is repainted
+ * into a game's own palette with `repaint(model, pick)`, once, on the loaded model, before it is copied.
+ *
+ * `stylize(model, style)` draws it the way the game's art direction says (style.json: `materials.model` toon, flat,
+ * hand-painted or pbr, and `materials.outline`), the same material model and ink line the style board was drawn with.
+ * Once, on the loaded model, after `repaint` and before it is copied: its outline hulls are instanced with it.
+ */
+import { BackSide, Box3, BoxGeometry, BufferGeometry, Float32BufferAttribute, CanvasTexture, Color, DataTexture, InstancedMesh, Matrix4, Mesh, MeshBasicMaterial, MeshLambertMaterial, MeshStandardMaterial, MeshToonMaterial, NearestFilter, RedFormat, SRGBColorSpace, Vector3, type AnimationClip, type Group, type Material, type Object3D, type Texture } from 'three';
+import { GLTFLoader, type GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { MeshoptDecoder } from 'three/examples/jsm/libs/meshopt_decoder.module.js';
+import { clone as cloneSkinned } from 'three/examples/jsm/utils/SkeletonUtils.js';
+import { mergeVertices } from 'three/examples/jsm/utils/BufferGeometryUtils.js';
+import { LIMITS, checkGlb, refusal } from './safety.mjs';
+
+export { LIMITS, checkGlb } from './safety.mjs';
+
+/** The size caps a file is checked against (assets/safety.mjs LIMITS.game unless a game narrows or widens them). */
+export interface ModelLimits { bytes: number; json: number; buffer: number; dataUri: number; vertices: number; meshes: number; nodes: number; materials: number; images: number; textures: number; animations: number; skins: number; accessors: number }
+
+/** What one model may cost on a phone (a prop 1,500 triangles and 512 px; a hero 8,000 and 1,024 px). */
+export interface ModelBudget { triangles?: number; texturePx?: number; materials?: number; bytes?: number }
+
+export interface LoadedModel {
+  url: string;
+  /** The model as loaded: never add this one to a scene twice; `instance()` gives copies. */
+  scene: Group;
+  animations: AnimationClip[];
+  bytes: number;
+  triangles: number;
+  textures: number;
+  /** GPU memory of its pictures, RGBA with mipmaps (what `gpuSize` in gltf-transform's inspect says). */
+  textureBytes: number;
+  warnings: string[];
+}
+
+export interface ModelsOptions {
+  /** Narrow or widen the file checks (LIMITS.game by default). */
+  limits?: Partial<ModelLimits>;
+  /** A per-model budget for the development warnings (the prop tier by default). */
+  budget?: ModelBudget;
+  /** A KTX2Loader the game set up (transcoder path, renderer support): only for models with KTX2 pictures. */
+  ktx2?: { load?: unknown } | null;
+  /** Origins a game deliberately loads models from, besides its own. */
+  allowOrigins?: string[];
+  /** Where development warnings go (console.warn by default; outside development, nowhere). */
+  onWarn?: (text: string) => void;
+  /** Say budget warnings even outside development. */
+  dev?: boolean;
+}
+
+export interface ModelStats { models: number; triangles: number; textureBytes: number; bytes: number; refused: { url: string; why: string }[] }
+
+export interface Models {
+  /** Load (once per address) and check one model. Rejects with a plain-words Error when it is refused or missing. */
+  load(url: string, opts?: { limits?: Partial<ModelLimits>; budget?: ModelBudget }): Promise<LoadedModel>;
+  /** A copy of a loaded model to place in the scene (skeletons cloned properly). */
+  instance(url: string, opts?: { limits?: Partial<ModelLimits>; budget?: ModelBudget }): Promise<Object3D>;
+  /** A grey box (metres), for a model that was refused, is missing or is still loading. */
+  placeholder(size?: { x: number; y: number; z: number }, colour?: number): Mesh;
+  /** Totals for the perf probe and the console. */
+  stats(): ModelStats;
+  /** Free every geometry, material and picture this loader made. */
+  dispose(): void;
+}
+
+const PROP_BUDGET: Required<ModelBudget> = { triangles: 1500, texturePx: 512, materials: 1, bytes: 300 * 1024 };
+const devHost = (): boolean => {
+  try { return /^(localhost|127\.0\.0\.1|\[::1\])$/.test(location.hostname) || new URLSearchParams(location.search).get('debug') === '1'; } catch { return false; }
+};
+
+/** Where an address points: relative ones resolve against the page; another origin is refused unless allowed. */
+function resolveUrl(url: string, allow: string[]): string {
+  const base = typeof location !== 'undefined' ? location.href : 'http://localhost/';
+  const u = new URL(url, base);
+  const own = typeof location !== 'undefined' ? location.origin : u.origin;
+  if (u.origin !== own && !allow.includes(u.origin)) throw new Error(`refused ${url}: a model from another site (${u.origin}); copy it into the game's own files (homie-studio assets add)`);
+  if (!/^https?:$/.test(u.protocol) && u.protocol !== 'blob:') throw new Error(`refused ${url}: not a web address`);
+  return u.href;
+}
+
+/** The file's bytes, refusing early when it says (or turns out) to be over the cap. */
+async function fetchCapped(url: string, cap: number): Promise<Uint8Array> {
+  const res = await fetch(url, { credentials: 'same-origin' });
+  if (!res.ok) throw new Error(`${url} answered ${res.status}`);
+  const said = Number(res.headers.get('content-length') ?? NaN);
+  // A served file may be compressed on the wire: the header is only trusted when the body is not.
+  if (Number.isFinite(said) && !res.headers.get('content-encoding') && said > cap) throw new Error(`refused ${url}: ${Math.ceil(said / 1024)} KB, over ${Math.ceil(cap / 1024)} KB`);
+  if (!res.body) { const b = new Uint8Array(await res.arrayBuffer()); if (b.byteLength > cap) throw new Error(`refused ${url}: over ${Math.ceil(cap / 1024)} KB`); return b; }
+  const reader = res.body.getReader();
+  const parts: Uint8Array[] = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > cap) { void reader.cancel(); throw new Error(`refused ${url}: over ${Math.ceil(cap / 1024)} KB`); }
+    parts.push(value);
+  }
+  const out = new Uint8Array(total);
+  let at = 0;
+  for (const p of parts) { out.set(p, at); at += p.byteLength; }
+  return out;
+}
+
+/** GPU bytes of one picture: RGBA8 with mipmaps (x 4/3), or the compressed size a KTX2 upload names. */
+function textureBytes(t: Texture): number {
+  const img = t.image as { width?: number; height?: number } | undefined;
+  const w = Number(img?.width ?? 0); const h = Number(img?.height ?? 0);
+  return Math.round(w * h * 4 * (4 / 3));
+}
+
+/** Instanced copies of one mesh of a model, and the mesh's own place in the model (`base`). */
+export interface Copies { mesh: InstancedMesh; base: Matrix4 }
+
+/**
+ * A loaded model (`(await models.load(url)).scene`, or a placeholder) as instanced copies: one InstancedMesh per mesh
+ * in it, `count` copies at most, sharing the file's geometry and materials. Place copy `i` with placeCopy (where it
+ * goes, times the mesh's own place in the model), then set `mesh.count`.
+ */
+export function instancedCopies(model: Object3D, count: number): Copies[] {
+  model.updateMatrixWorld(true);
+  const out: Copies[] = [];
+  model.traverse((o) => {
+    const m = o as Mesh;
+    if (m.isMesh) { const mesh = new InstancedMesh(m.geometry, m.material, count); mesh.name = m.name; out.push({ mesh, base: m.matrixWorld.clone() }); }
+  });
+  return out;
+}
+
+const placed = new Matrix4();
+/** Copy `i` of `copy` at `where` (a world matrix: position, turn, scale). */
+export function placeCopy(copy: Copies, i: number, where: Matrix4): void {
+  copy.mesh.setMatrixAt(i, placed.multiplyMatrices(where, copy.base));
+}
+
+/**
+ * Repaint a model's flat colours. `pick(r, g, b)` (sRGB, 0 to 255) returns the colour to paint instead, or null to
+ * keep it. It reaches each material's own colour and its base-colour picture when that is a small palette picture (at
+ * most `maxPx` a side: an optimised flat model's); a painted texture bigger than that is left as it is. Materials and
+ * pictures change in place, so call it once on the loaded model (`(await models.load(url)).scene`), before copying.
+ * Returns how many materials changed.
+ */
+export function repaint(model: Object3D, pick: (r: number, g: number, b: number) => [number, number, number] | null, { maxPx = 64 } = {}): number {
+  let changed = 0;
+  const seen = new Set<Material>();
+  const c = new Color();
+  model.traverse((o) => {
+    const m = o as Mesh;
+    if (!m.isMesh) return;
+    for (const mat of (Array.isArray(m.material) ? m.material : [m.material]) as MeshStandardMaterial[]) {
+      if (seen.has(mat)) continue;
+      seen.add(mat);
+      const tex = mat.map;
+      if (!tex) {
+        if (!mat.color) continue;
+        c.copy(mat.color).convertLinearToSRGB();
+        const to = pick(Math.round(c.r * 255), Math.round(c.g * 255), Math.round(c.b * 255));
+        if (to) { mat.color.setRGB(to[0] / 255, to[1] / 255, to[2] / 255, SRGBColorSpace); changed += 1; }
+        continue;
+      }
+      const img = tex.image as (CanvasImageSource & { width?: number; height?: number }) | undefined;
+      const w = Number(img?.width ?? 0); const h = Number(img?.height ?? 0);
+      if (!img || !w || !h || w > maxPx || h > maxPx || typeof document === 'undefined') continue;
+      const canvas = document.createElement('canvas'); canvas.width = w; canvas.height = h;
+      const g = canvas.getContext('2d', { willReadFrequently: true });
+      if (!g) continue;
+      g.drawImage(img, 0, 0);
+      const px = g.getImageData(0, 0, w, h);
+      let n = 0;
+      for (let i = 0; i < px.data.length; i += 4) {
+        const to = pick(px.data[i] as number, px.data[i + 1] as number, px.data[i + 2] as number);
+        if (to) { px.data[i] = to[0]; px.data[i + 1] = to[1]; px.data[i + 2] = to[2]; n += 1; }
+      }
+      if (!n) continue;
+      g.putImageData(px, 0, 0);
+      // The new picture samples exactly as the old one did (its orientation, wrapping and filters).
+      const t = new CanvasTexture(canvas);
+      Object.assign(t, { colorSpace: tex.colorSpace, flipY: tex.flipY, wrapS: tex.wrapS, wrapT: tex.wrapT, magFilter: tex.magFilter, minFilter: tex.minFilter, generateMipmaps: tex.generateMipmaps, channel: tex.channel });
+      mat.map = t; mat.needsUpdate = true;
+      changed += 1;
+    }
+  });
+  return changed;
+}
+
+/** Every geometry, material and picture under `obj`, freed. */
+/** What `stylize` reads from a game's style.json. */
+export interface StyleLike {
+  render?: string;
+  materials?: { model?: string; outline?: boolean };
+  palette?: { bg?: string; ink?: string };
+}
+
+let toonRamp: DataTexture | null = null;
+function rampOf(): DataTexture {
+  if (toonRamp) return toonRamp;
+  const data = new Uint8Array([Math.round(0.2 * 255), Math.round(0.53 * 255), Math.round(0.87 * 255)]);
+  toonRamp = new DataTexture(data, 3, 1, RedFormat);
+  toonRamp.minFilter = NearestFilter; toonRamp.magFilter = NearestFilter; toonRamp.needsUpdate = true;
+  return toonRamp;
+}
+
+/** One material in the style's material model (its colour, picture, vertex colours and transparency kept). */
+function styledMaterial(mat: Material, model: string): Material {
+  const src = mat as MeshStandardMaterial;
+  const base = { color: src.color ? src.color.clone() : new Color('#cccccc'), map: (src.map ?? null) as Texture | null, vertexColors: Boolean(src.vertexColors), transparent: src.transparent, opacity: src.opacity, side: src.side, alphaTest: src.alphaTest };
+  let out: Material;
+  if (model === 'toon') out = new MeshToonMaterial({ ...base, gradientMap: rampOf() });
+  else if (model === 'flat' || model === 'pixel') out = new MeshLambertMaterial({ ...base, flatShading: true });
+  else if (model === 'hand-painted') {
+    const m = new MeshStandardMaterial({ ...base, roughness: 0.95, metalness: 0 });
+    // A painted look: the top of every surface a little lighter, the bottom a little cooler.
+    m.onBeforeCompile = (sh) => {
+      sh.vertexShader = sh.vertexShader.replace('#include <common>', '#include <common>\nvarying float vH;').replace('#include <worldpos_vertex>', '#include <worldpos_vertex>\nvH = (modelMatrix * vec4(transformed, 1.0)).y;');
+      sh.fragmentShader = sh.fragmentShader.replace('#include <common>', '#include <common>\nvarying float vH;').replace('#include <color_fragment>', '#include <color_fragment>\ndiffuseColor.rgb *= mix(vec3(0.82, 0.86, 0.98), vec3(1.12, 1.06, 0.96), clamp(vH * 0.6 + 0.4, 0.0, 1.0));');
+    };
+    out = m;
+  } else return mat;
+  out.name = mat.name;
+  return out;
+}
+
+/**
+ * The outline's shell: the mesh's positions only, its corners welded, with smooth normals, so a flat-shaded low-poly
+ * model's line stays one unbroken shell instead of a black flake on every face. One per geometry.
+ */
+const hullGeometries = new WeakMap<BufferGeometry, BufferGeometry | null>();
+function hullGeometry(g: BufferGeometry): BufferGeometry | null {
+  if (hullGeometries.has(g)) return hullGeometries.get(g) ?? null;
+  let h: BufferGeometry | null;
+  const only = new BufferGeometry();
+  // Plain float positions (an optimised model's are quantized, often interleaved), read through the accessor.
+  const src = g.getAttribute('position');
+  const xyz = new Float32Array(src.count * 3);
+  for (let i = 0; i < src.count; i++) { xyz[i * 3] = src.getX(i); xyz[i * 3 + 1] = src.getY(i); xyz[i * 3 + 2] = src.getZ(i); }
+  only.setAttribute('position', new Float32BufferAttribute(xyz, 3));
+  if (g.index) only.setIndex(Array.from(g.index.array as ArrayLike<number>));
+  h = mergeVertices(only);
+  if (openShell(h) || paperThin(h)) h = null; else h.computeVertexNormals();
+  hullGeometries.set(g, h);
+  return h;
+}
+
+/**
+ * How thick a closed shell is, about (3 x volume / area: a slab of thickness t gives 1.5 t), in its own units.
+ */
+function thicknessOf(h: BufferGeometry): number {
+  const p = h.getAttribute('position'); const a = (h.index as NonNullable<BufferGeometry['index']>).array as ArrayLike<number>;
+  let vol = 0; let area = 0;
+  for (let i = 0; i + 2 < a.length; i += 3) {
+    const i0 = a[i] as number; const i1 = a[i + 1] as number; const i2 = a[i + 2] as number;
+    const ax = p.getX(i0); const ay = p.getY(i0); const az = p.getZ(i0);
+    const bx = p.getX(i1); const by = p.getY(i1); const bz = p.getZ(i1);
+    const cx = p.getX(i2); const cy = p.getY(i2); const cz = p.getZ(i2);
+    vol += (ax * (by * cz - bz * cy) - ay * (bx * cz - bz * cx) + az * (bx * cy - by * cx)) / 6;
+    const ux = bx - ax; const uy = by - ay; const uz = bz - az; const vx = cx - ax; const vy = cy - ay; const vz = cz - az;
+    area += Math.hypot(uy * vz - uz * vy, uz * vx - ux * vz, ux * vy - uy * vx) / 2;
+  }
+  return area > 0 ? (3 * Math.abs(vol)) / area : 0;
+}
+
+/** Two cards back to back (leaves, grass): closed, but with no inside, so a shell would z-fight it black. */
+function paperThin(h: BufferGeometry): boolean {
+  h.computeBoundingBox();
+  const size = (h.boundingBox as NonNullable<BufferGeometry['boundingBox']>).getSize(new Vector3());
+  return thicknessOf(h) < 0.01 * Math.max(size.x, size.y, size.z);
+}
+
+/** An open surface (cards of leaves, grass, a sail): many edges belong to one triangle only. No outline shell for it. */
+function openShell(h: BufferGeometry): boolean {
+  const idx = h.index;
+  if (!idx) return true;
+  const edges = new Map<string, number>();
+  const a = idx.array as ArrayLike<number>;
+  for (let i = 0; i + 2 < a.length; i += 3) {
+    for (const [u, v] of [[a[i], a[i + 1]], [a[i + 1], a[i + 2]], [a[i + 2], a[i]]] as [number, number][]) {
+      const k = u < v ? `${u}_${v}` : `${v}_${u}`;
+      edges.set(k, (edges.get(k) ?? 0) + 1);
+    }
+  }
+  let open = 0;
+  for (const n of edges.values()) if (n === 1) open += 1;
+  return edges.size > 0 && open / edges.size > 0.15;
+}
+
+/**
+ * The ink shell's vertex step: pushed out along its normal by `width` WORLD units (metres in a game), after every
+ * transform (the model's scale, a quantized mesh's node, an instance's matrix), so a line is as thick on a flower as on
+ * a tree and nothing about the model's own units matters.
+ */
+function inkShader(width: number): (sh: { vertexShader: string }) => void {
+  const w = Math.max(0, width).toExponential(4);
+  return (sh) => {
+    sh.vertexShader = sh.vertexShader.replace('#include <project_vertex>', [
+      'vec4 mvPosition = vec4( transformed, 1.0 );',
+      'vec3 inkN = normal;',
+      '#ifdef USE_INSTANCING',
+      'mvPosition = instanceMatrix * mvPosition; inkN = mat3( instanceMatrix ) * inkN;',
+      '#endif',
+      'vec4 inkW = modelMatrix * mvPosition;',
+      `inkW.xyz += normalize( mat3( modelMatrix ) * inkN ) * ${w};`,
+      'mvPosition = viewMatrix * inkW;',
+      'gl_Position = projectionMatrix * mvPosition;',
+    ].join('\n'));
+  };
+}
+
+const MODEL_OF_RENDER: Record<string, string> = { toon: 'toon', 'lowpoly-flat': 'flat', voxel: 'flat', 'pixel-hd2d': 'pixel', 'hand-painted': 'hand-painted', pbr: 'pbr', realistic: 'pbr' };
+
+/**
+ * Draw a loaded model the way the game's art direction says: its material model (style.json `materials.model`, else
+ * the render style's) on every mesh, and with `materials.outline` an ink line (an inverted hull: a back-faced copy
+ * pushed out along the normals, `line` metres in the world, as thick on a bush as on a tree, finer on something small:
+ * pass `scale`, the scale the game draws it at). Skinned meshes, open cards and paper-thin shells get the material,
+ * not the line. Call it once on the loaded model, after `repaint`; `instancedCopies` copies the line with it. Returns how many
+ * meshes changed.
+ */
+export function stylize(model: Object3D, style: StyleLike, { line = 0.05, scale = 1, ink }: { line?: number; scale?: number; ink?: string } = {}): number {
+  const kind = style.materials?.model ?? MODEL_OF_RENDER[String(style.render ?? '')] ?? 'pbr';
+  const swapped = new Map<Material, Material>();
+  const meshes: Mesh[] = [];
+  model.traverse((o) => { const m = o as Mesh; if (m.isMesh && m.name !== 'hull') meshes.push(m); });
+  for (const m of meshes) {
+    const swap = (x: Material): Material => { let y = swapped.get(x); if (!y) { y = styledMaterial(x, kind); swapped.set(x, y); } return y; };
+    m.material = Array.isArray(m.material) ? m.material.map(swap) : swap(m.material);
+  }
+  if (style.materials?.outline) {
+    const colour = new Color(ink ?? (style.palette?.bg ? `#${new Color(style.palette.bg).lerp(new Color('#000000'), 0.7).getHexString()}` : '#1a1410'));
+    // A small thing (a flower, a gem) gets a finer line: never more than 6% of its size as the game draws it (`scale`).
+    const box = new Box3().setFromObject(model).getSize(new Vector3());
+    const width = Math.min(line, 0.06 * Math.max(box.x, box.y, box.z) * scale);
+    const inkMaterial = new MeshBasicMaterial({ color: colour, side: BackSide });
+    inkMaterial.onBeforeCompile = inkShader(width);
+    inkMaterial.customProgramCacheKey = () => `ink:${width}`;
+    for (const m of meshes) {
+      // No line on a skinned mesh; cards of leaves and grass (open, or two faces back to back) get none from hullGeometry.
+      if ((m as unknown as { isSkinnedMesh?: boolean }).isSkinnedMesh) continue;
+      const shell = hullGeometry(m.geometry);
+      if (!shell) continue;
+      // A part too thin for the line (a flower's stem, a post) goes without: three widths of ink would make it a stick.
+      shell.computeBoundingBox();
+      const local = (shell.boundingBox as Box3).getSize(new Vector3());
+      const world = new Box3().setFromObject(m, true).getSize(new Vector3());
+      const units = Math.max(world.x, world.y, world.z) / Math.max(1e-9, local.x, local.y, local.z);
+      if (thicknessOf(shell) * units * scale < 3 * width) continue;
+      const hull = new Mesh(shell, inkMaterial);
+      hull.name = 'hull';
+      hull.castShadow = false; hull.receiveShadow = false;
+      m.add(hull);
+    }
+  }
+  return meshes.length;
+}
+
+export function disposeObject(obj: Object3D): void {
+  obj.traverse((o) => {
+    const m = o as Mesh;
+    if (m.geometry) m.geometry.dispose();
+    const mats = (Array.isArray(m.material) ? m.material : m.material ? [m.material] : []) as Material[];
+    for (const mat of mats) {
+      for (const v of Object.values(mat as unknown as Record<string, unknown>)) if (v && typeof v === 'object' && (v as Texture).isTexture) (v as Texture).dispose();
+      mat.dispose();
+    }
+  });
+}
+
+export function createModels(opts: ModelsOptions = {}): Models {
+  const limits = { ...LIMITS.game, ...(opts.limits ?? {}) } as ModelLimits;
+  const allow = (opts.allowOrigins ?? []).map((o) => new URL(o).origin);
+  const dev = opts.dev ?? devHost();
+  const warn = (text: string): void => { if (dev) (opts.onWarn ?? ((t: string) => console.warn(`[models] ${t}`)))(text); };
+  const loader = new GLTFLoader();
+  loader.setMeshoptDecoder(MeshoptDecoder);
+  if (opts.ktx2) loader.setKTX2Loader(opts.ktx2 as never);
+  const cache = new Map<string, Promise<LoadedModel>>();
+  const made: Object3D[] = [];
+  const refused: { url: string; why: string }[] = [];
+  const loaded: LoadedModel[] = [];
+
+  async function loadOnce(url: string, lim: ModelLimits, budget: Required<ModelBudget>): Promise<LoadedModel> {
+    let href: string;
+    try { href = resolveUrl(url, allow); } catch (error) { refused.push({ url, why: (error as Error).message }); throw error; }
+    let bytes: Uint8Array;
+    try { bytes = await fetchCapped(href, lim.bytes); } catch (error) { refused.push({ url, why: (error as Error).message }); throw error; }
+    const check = checkGlb(bytes, lim);
+    if (!check.ok) { const why = refusal(url, check); refused.push({ url, why }); throw new Error(why); }
+    if (check.info.extensions.required.includes('KHR_texture_basisu') && !opts.ktx2) {
+      const why = `refused ${url}: it has KTX2 pictures and this game set up no KTX2 loader (createModels({ ktx2 }))`;
+      refused.push({ url, why });
+      throw new Error(why);
+    }
+    const buffer = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
+    const gltf = await new Promise<GLTF>((resolve, reject) => loader.parse(buffer, href.replace(/[^/]*$/, ''), resolve, reject));
+    const scene = gltf.scene;
+    let triangles = 0; let textures = 0; let tex = 0; let materials = 0;
+    const seen = new Set<string>();
+    scene.traverse((o) => {
+      const m = o as Mesh;
+      if (!m.isMesh) return;
+      const g = m.geometry;
+      const count = g.index ? g.index.count : (g.attributes.position?.count ?? 0);
+      triangles += Math.floor(count / 3) * Number((m as unknown as { count?: number }).count ?? 1);
+      for (const mat of (Array.isArray(m.material) ? m.material : [m.material]) as Material[]) {
+        if (seen.has(mat.uuid)) continue;
+        seen.add(mat.uuid); materials += 1;
+        for (const v of Object.values(mat as unknown as Record<string, unknown>)) {
+          const t = v as Texture;
+          if (t && typeof t === 'object' && t.isTexture && !seen.has(t.uuid)) { seen.add(t.uuid); textures += 1; tex += textureBytes(t); }
+        }
+      }
+    });
+    const warnings = [...check.warnings];
+    if (triangles > budget.triangles) warnings.push(`${triangles.toLocaleString('en-US')} triangles (its budget is ${budget.triangles.toLocaleString('en-US')})`);
+    if (materials > budget.materials) warnings.push(`${materials} materials (its budget is ${budget.materials})`);
+    if (bytes.byteLength > budget.bytes) warnings.push(`${Math.ceil(bytes.byteLength / 1024)} KB (its budget is ${Math.ceil(budget.bytes / 1024)} KB)`);
+    const px = budget.texturePx * budget.texturePx * 4 * (4 / 3) * Math.max(1, textures);
+    if (tex > px) warnings.push(`${(tex / 1024 / 1024).toFixed(1)} MB of picture memory (pictures over ${budget.texturePx} px)`);
+    for (const w of warnings) warn(`${url}: ${w}`);
+    const model: LoadedModel = { url, scene, animations: gltf.animations ?? [], bytes: bytes.byteLength, triangles, textures, textureBytes: tex, warnings };
+    loaded.push(model);
+    made.push(scene);
+    return model;
+  }
+
+  const api: Models = {
+    load(url, o = {}) {
+      const key = url;
+      let p = cache.get(key);
+      if (!p) {
+        p = loadOnce(url, { ...limits, ...(o.limits ?? {}) } as ModelLimits, { ...PROP_BUDGET, ...(opts.budget ?? {}), ...(o.budget ?? {}) });
+        cache.set(key, p);
+        p.catch(() => cache.delete(key));
+      }
+      return p;
+    },
+    async instance(url, o) {
+      const m = await api.load(url, o);
+      let skinned = false;
+      m.scene.traverse((x) => { if ((x as unknown as { isSkinnedMesh?: boolean }).isSkinnedMesh) skinned = true; });
+      return skinned ? cloneSkinned(m.scene) : m.scene.clone(true);
+    },
+    placeholder(size = { x: 0.5, y: 0.5, z: 0.5 }, colour = 0x8a8f99) {
+      const geo = new BoxGeometry(size.x, size.y, size.z);
+      geo.translate(0, size.y / 2, 0);
+      const box = new Mesh(geo, new MeshStandardMaterial({ color: colour, roughness: 0.9 }));
+      box.name = 'placeholder';
+      made.push(box);
+      return box;
+    },
+    stats() {
+      return {
+        models: loaded.length,
+        triangles: loaded.reduce((n, m) => n + m.triangles, 0),
+        textureBytes: loaded.reduce((n, m) => n + m.textureBytes, 0),
+        bytes: loaded.reduce((n, m) => n + m.bytes, 0),
+        refused: refused.slice(),
+      };
+    },
+    dispose() {
+      for (const o of made) disposeObject(o);
+      made.length = 0; loaded.length = 0; cache.clear();
+    },
+  };
+  try { (globalThis as unknown as { __homieModels?: () => ModelStats }).__homieModels = () => api.stats(); } catch { /* not a browser */ }
+  return api;
+}