@lampdotdev/lamp 0.0.0-stage → 0.35.0

package/Resources/skills/finder-files/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: finder-files
+description: A Mac app that takes files or folders from Finder - dropped on its icon, Open With, a Quick Action - with what it declares in capabilities.json, how to try it, and Quick Actions that survive a move. Read before writing any of it.
+---
+
+# Files and folders from Finder
+
+An app that takes files or folders from Finder (dropped on its icon, Open With, a Quick Action) says what it opens in
+`capabilities.json` at the app's root: `{"opens": ["folder", "png", "public.image"]}`, with "folder", "file" for any
+file, file extensions or type identifiers. Lamp declares them for the app; without that macOS hands it nothing. It is
+only ever offered for a kind another app opens, never put in that app's place; a kind nothing else opens (your own
+extension) is the app's to open.
+
+To try it, make test files in the app's folder or a temporary folder and hand them over with the `open` command
+`look_at_app` then gives you, which does what Finder does.
+
+A Finder Quick Action is a workflow the app writes into ~/Library/Services, and it stores the app's full path: it
+stops working when the app is moved or renamed, until the app runs again and rewrites it. So have the app write it at
+every launch from `Bundle.main.bundlePath`, never once.

package/Resources/skills/game/SKILL.md

@@ -0,0 +1,414 @@
+---
+name: game
+description: Games, 2D or 3D, made either way - what makes one fun and playtesting it, the frame loop, controls (a controller, keys, touch, a TV remote), sound, saves, keeping every frame smooth and light rendering - with the tools for each (Lamp's game runtime in a web page, a Samsung or LG TV app's page, in 2D or with three.js, for a game played with phones, SpriteKit and Lamp's blocks in Swift, an integration's own), and turning an app into a game. Read before writing or changing a game; a new web game at home on the Mac starts from the web-game guide and game-feel instead, and the parts of this it needs come as the skills that guide names.
+---
+
+# Games
+
+A game is something played in real time, rather than used. What follows holds for every game, whichever way it's
+made; each part then names the tools for each make. For a game in 2D, open the 2d-game skill too (Phaser or SpriteKit,
+and which to choose); for one in 3D, the 3d-game skill (or scene-3d for RealityKit in Swift). Before designing its
+opening, title, menus, level select, HUD, pause or results, read the game-ui skill: a new game picks its screen flow
+there before any screen is drawn, however it's made.
+
+The tools Lamp has for games:
+
+- **Web**: Lamp's game runtime, `Web/lamp-game.js`, with Phaser for 2D (through `Web/lamp-phaser.js`) or three.js for
+  3D, in a game `make_app_for` made with `kind` "game". It's a game's default make, 2D or 3D, wherever Lamp has a host
+  for a page, and the same on every one of them. Read lamp-game.js first, all of it (and lamp-phaser.js for 2D): their
+  comments are the whole interface. (A new game at home on the Mac starts from the web-game guide, which needs neither read whole.) Below, "Web" means this runtime.
+- **TypeScript**: a game whose source is TypeScript (one brought in from a Vite project, or when the person asks for
+  it) keeps it in `src/` with `src/main.ts` as its entry, and Lamp bundles it into `Web/app/` before every build and
+  look (types stripped, not checked): `Web/index.html` loads `app/main.js` (and `app/main.css` when the source imports
+  CSS), and its import map names the bare imports, `three` and `lamp-game` (`./lamp-game.js`) among them. As in a
+  Vite build, `import.meta.env` reads as a published build's, and a worker is a `src/**/*.worker.ts` file, started with
+  `new Worker(new URL("./<name>.worker.js", import.meta.url), { type: "module" })` (`.js`: every file is bundled flat
+  into `Web/app/`; a module worker, since what it shares with the page comes as an import). Edit `src/`,
+  never `Web/app/`. A game in plain JavaScript stays as it is, its modules in `Web/`.
+- **Phones as players**: a game on the runtime takes phones on the Wi‑Fi with `Lamp.controllers` (Web/lamp.js) and
+  its page for them in Phone/ (the phone-controllers and phone-pages skills), on the Mac, in the TV preview, on a
+  Samsung or LG TV and on the Xbox; elsewhere `Lamp.controllers` says it can't start, so the game stays whole with a controller,
+  the keys or touch. Lamp plays the game with a controller of its own, never as a phone: only the person's phones
+  join. Read a phone's buttons in `frame(f)` from `f.phones`, as the pads are read (`frame().phones`
+  in a Phaser scene): one `{ player, down, pressed, released }` for each phone joined, each button by the name the phone
+  page gave it, so `for (const p of f.phones) if (p.pressed.go) start()`. `pressed` and `released` last the one frame after
+  it happened, and a press let go again between two frames is still a press. `onButton` runs between frames, so a flag
+  it sets and `frame` clears is lost: keep it for what can't wait for a frame. Sticks and messages still come by
+  `onAxis` and `onMessage`, so the game keeps its own queue for them (the phone-pages skill's "Views and moves").
+- **A TV app's page**: a game made as a Samsung or LG TV app before games took phones (`kind` "app") has no
+  lamp-game.js: it follows the TV rules and lamp.js instead, with its own `requestAnimationFrame`. The rest of this
+  skill holds for it wherever it doesn't name the runtime.
+- **Native Apple** (Mac, iPhone, iPad, Apple TV): SpriteKit for 2D, SwiftUI for menus and scores, and Lamp's blocks
+  in LampSupport.swift: a game made natively, where the person asked for that, it needs what only Apple's apps have
+  (Game Center, a widget, a place inside an app of theirs) or the device has no host for a page (an Apple TV). It stays
+  on Apple's devices: it can't go to Android, the Xbox, a TV's browser or the web later. For 3D in Swift, LampSceneView (the scene-3d skill) is for a Mac app made natively; a native 3D game
+  on iPhone, iPad or Apple TV writes its own 3D with that device's frameworks (RealityKit or SceneKit).
+- **Native Android**: Lamp has no game help in Kotlin yet: write the game's own frame loop on a SurfaceView or a
+  Canvas, and its controls, sound and saves with Android's own APIs.
+- **An integration's device** (Roku…): what its integration declares; read the device-integrations skill.
+- **Apple Watch**: Lamp has no game help there.
+
+## Fun
+
+A game is for fun, and fun is designed from the first build, not added at the end:
+
+- **A clear core loop.** One thing the player does again and again (jump, aim, steer, match) that feels good on its
+  own, and a reason to do it once more: a score to beat, the next level, something new just ahead.
+- **Quick feedback.** Every action answers at once, in sight and sound: a hit flashes and pops, a coin chimes and
+  leaps to the score, a landing squashes. This is the game's juice: particles, a little screen shake on the big
+  moments (never on every frame, and less on a TV across the room), a tween in place of a jump cut, a short freeze on
+  a big hit.
+- **A learning curve.** The first minute teaches by playing, never by a page of rules; then it gets harder in steps the
+  player feels coming, with a breather after each rise.
+- **Variety.** New enemies, places, rules or tools keep coming, so the tenth minute isn't the first again.
+- **Surprise and delight the player frequently.** Small things nobody asked for: a character that waves back, a
+  secret, a joke in a name, a combo that does something special, weather that changes, a celebration that's over the
+  top. Many small ones beat one big one.
+
+What's in it is made in code (3D models from three.js shapes, the 3d-game skill; pictures drawn in code or painted with
+`make_art`) or ready-made from Lamp's free assets: models, characters with their animations, sprite sheets, tilesets,
+textures, sound effects and music, fetched and credited by the `assets` tool (the assets skill says when each suits and
+how to keep one style). Sound looks in those assets first ("Sound", below). Either way it's the person's to share. Any other file only when the person gives it or names where it comes from and its license allows sharing; it goes into the game's own
+folder, credited as the rules say. The game never loads anything from the network while it's played.
+
+When asked to make a game more fun, look at it first and find what's flat (a loop that doesn't pull, a curve that's
+too easy or too hard, an action that answers with nothing), then work on those four: the loop and the curve, the
+juice, the surprises, and the variety. Keep what the person likes about it, and its controls.
+
+## The frame loop
+
+Everything that moves is moved by the time since the last frame, never by a fixed step per frame: devices draw at
+different rates, and a slow frame must not slow the game.
+
+- Web (the runtime): `game({ renderer, init, frame })` from lamp-game.js, moving by `f.dt`; in 2D, Phaser's scenes
+  through `phaser({ scenes })` from lamp-phaser.js, moving by `update`'s `delta`, on the same one loop. Never requestAnimationFrame, timers, the
+  clock, Math.random or localStorage: `random()`, `save()` and `load()` from the runtime, which keep through a change
+  of the code.
+  Physics is the one exception to moving by `f.dt`: it steps at a fixed 1/60 s inside the frame, through `fixedStep`
+  from lamp-game.js, so it behaves the same at any frame rate (Rapier for 3D, in the 3d-game skill).
+- SpriteKit: in a SpriteView, one SKScene subclass for each screen with `scaleMode = .resizeFill`; movement in
+  `update(_:)` scaled by the time since the last frame; collisions with SKPhysicsBody, its category and contact masks,
+  and an SKPhysicsContactDelegate. An SKCameraNode follows the player through a world bigger than the screen.
+
+## Controls
+
+Controls follow the input the player has, not the device: the same player may pick up an Xbox, PlayStation or
+Switch controller, the keyboard or the touch screen, and switch while playing.
+
+- **Web**: lamp-game.js reads all of them as one pad, `f.pads[0]` (`pad()` in a Phaser scene). Write the controls once, as actions mapped to the
+  pad (`const CONTROLS = { jump: BUTTON.A, pause: BUTTON.MENU, move: STICK.LEFT, gas: TRIGGER.RT }`), and read the pad
+  through them. `input()` says what the player holds (`kind` is `controller`, with its `family`: `xbox`,
+  `playstation`, `switch` or `other`; or `keyboard`, or `touch`); `onInput(draw)` draws now and again each time they
+  take up another. Build every prompt and help screen inside it from the actions: `label(CONTROLS.jump)` is the
+  button's name on that input ("A", "✕", "Space") and `glyph(CONTROLS.jump)` its badge, an element to put in the text.
+  Both are null where the input has nothing for that action: leave the line out. Never write a key's or a button's
+  name yourself; a page that reads the keys itself (`keyboard: false`) names its own keys by their codes,
+  `label('KeyH')`. When the person names the keys to move with, the hints use them: `keyboardHints: { leftStick:
+  'arrows' }` to `game()` or `phaser()` makes `label(STICK.LEFT)` and `glyph(STICK.LEFT)` name the arrow keys (`'wasd'`
+  is the default). Both sets of keys still move the player.
+- **Swift**: GameController's `GCController` for a controller, with the button's name from the controller itself
+  (`localizedName`, `sfSymbolsName`) rather than a fixed letter; keys on a Mac with
+  `NSEvent.addLocalMonitorForEvents`.
+- **Touch**: big targets for thumbs, and few of them. Web: the runtime draws a stick and the buttons `touch` names;
+  keep the game playable with those few.
+- **A TV remote**: arrows and OK, and a back key; a game that needs more wants a controller, or phones (the
+  phone-controllers skill).
+
+B (or Esc, or Back) is the game's own back or cancel; Menu pauses.
+
+## Sound
+
+Every game has sound: a short effect (under a second) for each thing the player does or meets, and music only when it
+suits, quiet (0.3 to 0.4) under effects at 0.6 to 0.8. Settings or the pause menu turn sound and music on and off.
+
+**Look in the `assets` tool before writing any sound.** List what the game needs to sound like (each thing the player
+does or meets, and its music), then see the whole catalog: `assets` with `kind: sound`, `limit: 30` and no `find` lists
+every effect, and `kind: music` every loop. Fetch one for every moment it can serve, by name and notes (the assets
+skill's "Sounds and music" has more). Only files the person gave come before this. Write a sound in code only for a
+moment nothing in those lists fits, or one that has to follow the game as it's played (an engine's pitch, notes on a
+scale), and name each of those in your report. They're chosen as the game is made, and every one ships inside it.
+
+- Web: `sound` in lamp-game.js. A file loads with `await sound.load('assets/…')`. Written in code, effects come from
+  `sound.tone`, and music from a loop of a few bars written out note by note into `sound.samples` (a bass line, chords,
+  a melody, in one key). Either way `sound.play` plays an effect and `sound.music` a loop, a calmer one for menus and a
+  livelier one for play.
+- Swift: files in Assets/ (.wav, .m4a or .mp3, and what the `assets` tool brought in) play with an
+  `AVAudioPlayer(contentsOf: LampAssets.url(name)!)` made once and `prepareToPlay()`ed, a few of them for an effect
+  that overlaps itself; music is one looping (`numberOfLoops = -1`). Written in code, effects come from one
+  `AVAudioEngine` started at launch with an `AVAudioPlayerNode`, each effect a few hundredths of a second of a wave
+  written once into an `AVAudioPCMBuffer`, with soft ends so it doesn't click. On iPhone set the session to
+  `.ambient`, so the silent switch mutes the game and the person's own music keeps playing.
+
+## Saves
+
+Scores, progress and settings are kept on the device, and only ever added to: a new field gets a default where it's
+read, so an update never loses a player's progress. Web: `save(name, value)` and `load(name)` from lamp-game.js.
+Swift: LampStore.
+
+## Changes while it's played
+
+Lamp puts each change into the game while the person plays it (Web: lamp-game.js, "Changes while it's played"), so a
+game is written to keep the player's place through one:
+
+- **Everything that has to last is registered, by name, once.** That's how every new game is written, and the scaffold
+  starts that way. Web, with `const live = hot(import.meta)` from lamp-game.js:
+
+  ```js
+  const renderer = live.renderer(() => new THREE.WebGLRenderer({ antialias: true }));
+  const camera = live.camera('main', () => {
+      const c = new THREE.PerspectiveCamera(60, 16 / 9, 0.1, 500);
+      c.position.set(0, 4, 12);   // its starting pose and lens are made here, and nowhere else
+      return c;
+  }, { target: () => controls.target });
+  const play = live.state('play', {
+      version: 1,
+      start: () => ({ mode: 'opening', menu: null, level: 1, score: 0, lives: 3, player: { x: 0, z: 0, heading: 0, speed: 0 } }),
+  });
+  ```
+
+  - `live.renderer(build)`: new code gets the renderer the game has before it could make another, so there's one, with
+    its compiled shaders. It's made again only when `build` itself changes. An async build (the 3d-game skill's
+    WebGPU) is awaited.
+  - `live.camera(id, build, { target })`: keeps the camera's pose, lens and what it looks at (`target` gives anything
+    with x, y and z that new code makes again, as OrbitControls' `target`). At the first frame it's where the player
+    left it, whatever the start set. A change to `build` gives the new lens at the old pose.
+  - `live.state(id, { version, start, migrate })`: everything that says where the game is goes in one plain object,
+    the mode (playing, paused, a menu), which menu, overlay or card is open, the level, the player's position, heading
+    and speed, what they ride or hold, the score, lives, the clock, the time of day. Change its fields and never
+    replace it. Lamp snapshots it as plain JSON by itself, so it holds no objects of three.js or Phaser, and nothing
+    derived from it is kept elsewhere. A field added to `start()` takes its start value, and every other field keeps its value.
+    Raise `version` when a field changes its meaning, with `migrate(old, oldVersion)` to carry the old state over; with
+    none, that state starts over from `start()`.
+  - Each part of the world is kept with `live.keep` (below).
+
+  Only what's registered is kept. A renderer or camera the game's code makes for itself, or a variable of its own,
+  starts again with the code.
+- **One start path.** Everything registered is back before `init` runs and before the first frame, at a fresh start
+  it's `start()`, and the same object stays the whole time. So `init` (in a 2D game, the first scene's `init` or
+  `create`) reads the state and builds exactly that screen: that mode, that menu or overlay open, and nothing a fresh
+  start shows (a title card, an intro, a tutorial prompt, a fade in) built or shown at all. Never start fresh and then
+  put the place back, which leaves the opening over the game and input in the opening's mode. A later restart (a new
+  round, a death) sets the state's fields back itself. A 2D game registers its state; Phaser's game and cameras are made
+  again from it.
+- **A game from before this**, or one brought in, may use `snapshot()` in game() (or phaser()), plain JSON of where it
+  is, with `pendingRestore()` (the state while it starts, null for a fresh start and once it has started) or
+  `restore(state)` (called after init when it didn't read pendingRestore()). They're still taken, and a change keeps
+  its place through them. Without either it starts again, from its saves. When you're asked to change such a game, register what your change
+  touches as you make it, and leave the rest for the changes that touch it: move its renderer into `live.renderer` first, its
+  main camera into `live.camera`, then its state, field by field out of snapshot() into `live.state`.
+- **Lamp checks and says.** With your request comes what the game hasn't registered. A change that would start play over
+  (no state registered, and no snapshot() it reads back) waits for the person's Reload rather than going in, and the
+  look names what's missing: register it in the same turn, and Reload takes both in. Those are the one change a game
+  needs to adopt this: after that, changes go in as it's played. After a run of the code, a look says what was kept, built again and reset,
+  and what isn't registered. Anything reset that you didn't mean to reset is the place the person lost: register it
+  now, so the next change keeps it.
+- A game with phones keeps them through all of this: they stay joined with their numbers, and the code never stops or
+  starts `Lamp.controllers` for a change. So the state holds which player owns which slot (the seat, side, color or
+  team each player number has), and the new code restores those slots before it sits anyone down. As its first frame
+  nears, `onLeave` and `onJoin` are called again for who left and who is here, so `onJoin` for a player who already has
+  a slot leaves the slot alone, and only a new player takes a free one. What a phone has held down stays in
+  `f.phones`' `down`; a press or message from before the new code started isn't sent again and isn't in `pressed`, so
+  anything read while held is read from `down` (or `isHeld`), not remembered from `onButton`.
+- Pictures, models, sounds and data load through the runtime (`texture()`, `model()`, `sound.load()`, `asset()`), never
+  by a URL of the game's own: a new copy of one of those goes into the running game with no reload. What the game makes
+  of a file itself (a material from shader source, clones of a model, a mixer for its animations, a level from JSON) is
+  made again in `assetChanged(path)`, which returns true when it has.
+- Code goes into the running game too, never by opening the page again, in one of two ways, and the log says which,
+  what was kept and how long it took:
+  - **Swapped**, at once: a change to the methods of a class in a module that ends with `hot(import.meta).accept()`
+    from lamp-game.js. Every object the game made of that class runs the new methods with its fields kept.
+  - **Run again in place**, for anything else (the HTML, the module that starts the game, a class's constructor or
+    fields, an exported function, a new module): the page is put back as the new HTML has it, every module of the game
+    runs again, and the game starts straight from what it registered, as a reload would but without one. What's
+    registered stays: the renderer and its compiled shaders, the cameras, the state, and each part kept with
+    `hot(import.meta).keep(key, build, { inputs, from, background })`, and so do the files the runtime loaded, so the change costs only
+    what's built again, and a part built in the background costs the person nothing. The listeners,
+    timers, sound contexts and workers the old code started are taken away by Lamp, and so are its `Lamp.controllers`
+    callbacks, which the new code sets again as it starts; `dispose` in game() is for anything else it must let go of,
+    and never stops the phones (a `stop()` there is ignored).
+
+  So a game is written in parts, each in a module of its own:
+
+  - **The module that starts the game only puts the parts together** (`game.js`; New York's `main.js`). It registers
+    the renderer, the cameras and the state, and keeps each part of the world:
+
+    ```js
+    import { game, hot } from './lamp-game.js';
+    const live = hot(import.meta);
+    const renderer = live.renderer(() => new THREE.WebGLRenderer({ antialias: true }));
+    const ground = live.keep('ground', () => buildGround());
+    const trees = live.keep('trees', () => buildTrees(ground.heights), { inputs: [ground] });
+    scene.add(ground.group, trees.group);
+    ```
+
+    A kept part is built again only when its own module (or one it imports) changed, its build function changed, one
+    of its `inputs` (the parts it's built from) was built again, or a file it read as it was built changed. So build
+    each part of the world (the ground, the buildings, the trees and street details, the props, the traffic) in a
+    module of its own, into a group of its own that's added to the scene at each start, and do everything to it
+    (setting it on the ground, cutting it for culling) inside its build, never to a kept part afterwards. The build
+    function in the starting module names the module it builds from (`buildTrees`), since that's how Lamp tells which
+    change is its own. Declare the data each part is built from in its `from` (files beside the page, a module of
+    generated data, or a folder ending in /), so a change to that data builds the part again in place, with the rest
+    of the world and the player's place kept:
+
+    ```js
+    const streets = live.keep('streets', () => buildStreets(), { from: ['js/map-data.js'] });
+    const paint = live.keep('roadPaint', () => buildRoadPaint(streets.network), { inputs: [streets], from: ['js/map-data.js'] });
+    ```
+
+    A part that takes more than a frame or two to build (a city from its map data, a terrain, a road network, the
+    traffic on it) is built in the background with `background: true`, so a change to it never holds the game still:
+    the person plays on with the part they have, "Building…" shows over the game, and once the new part is built its
+    shaders are compiled and it swaps in, in about a frame. Until then the game's logic and the controller use the old
+    part, so code that reads a part works with either. Its build is either a generator that yields every few
+    milliseconds of work (a row of blocks, a chunk of terrain), which Lamp steps between frames, or an async function
+    that hands the pure data work (parsing, the arrays geometry is made from) to a worker with `work()` from
+    lamp-game.js and makes only the three.js objects from what comes back:
+
+    ```js
+    const city = live.keep('city', function* () {
+        const group = new THREE.Group();
+        for (const block of MAP.blocks) { group.add(buildBlock(block)); yield; }
+        return { group };
+    }, { from: ['js/map-data.js'], background: true });
+
+    const ground = live.keep('ground', async () => {
+        const { positions, normals } = await work('js/ground-worker.js', { size: MAP.size });   // posted back with their buffers as transfer
+        return { group: groundMesh(positions, normals) };
+    }, { from: ['js/elevation.js'], background: true });
+    ```
+
+    Data the person asked to come live from the network (today's weather, road closures, a feed) is fetched inside the
+    build of the part made from it, and declared in its `from` when a file stands in for it offline, never awaited on its
+    own in the module that starts the game: a part keeps what it fetched when the code runs again, while a fetch outside
+    every part is waited for again at each change, with the game standing still. The log after each run says how long
+    the game's own start took outside its kept parts.
+
+    The first build, as the game starts, is built whole. A part built from one being built (its `inputs`) is built
+    again from the new one once that's in, so parts that must change together are one part. Keep a part's three.js
+    objects in the value it returns (one object, or a plain object of them, as `{ group }`), so Lamp can compile them
+    ahead and let go of the old ones. Make a part's materials once, in a kept part of their own
+    (`live.keep('cityMaterials', () => makeCityMaterials())`), and build only its geometry in the background: a
+    material made anew is a shader to compile, which holds the frames on screen while it compiles (about a third of a
+    second each in WebKit), and the old part goes without taking the materials the new one still uses.
+
+    After a run, the look says which parts were built again, how long each took, which are still being built in the
+    background, how long the game stood still, and what of the change nothing read again, which shows only after
+    Reload. A look shows the person's open game as it is: a change built into a part that was kept isn't in it until
+    that part is built again.
+
+    A big 3D world on three.js's `WebGPURenderer` keeps its scene and lights the same way, as its camera is. For a new one of
+    them it works out how to draw every object again, which holds a big world still for a second at each change. Empty
+    the kept scene at each start (`scene.clear()`), then add back the kept lights and each part's group, so what the
+    last run added doesn't stay.
+  - **The HUD and menus are made at each start**, from the page's HTML or built in code, and their elements found
+    there (in init, or the function that starts the game), never once at a module's top level: the page they find is
+    the one the new HTML put back.
+  - **What changes as the person plays is a class the game makes an object of** (a vehicle and its tuning, the
+    player's moves, missions, enemies, the HUD's code, the camera, a shader's settings), its state in the object and
+    the module ending with `hot(import.meta).accept()`, so most changes are swapped:
+
+    ```js
+    import { hot } from '../lamp-game.js';
+    const CAR = { topSpeed: 36, acceleration: 4.5 };   // tuning, read where it's used
+    export class Car {
+        constructor(scene) { this.mesh = buildCar(); scene.add(this.mesh); this.speed = 0; }
+        update(dt, pad) { this.speed = Math.min(CAR.topSpeed, this.speed + pad.rt * CAR.acceleration * dt); … }
+    }
+    hot(import.meta).accept();
+    ```
+
+    Export every class a module defines and the game calls (one kept to itself keeps its old methods), read tuning
+    where it's used rather than copying it into fields in the constructor, and keep state in the objects, not in
+    variables at the module's top. An exported plain object (`export const TUNING = {…}`) takes the values a change
+    changed and keeps the rest. What a constructor built once stays as built through a swap: give
+    `accept((next, { changed }) => …)` the rebuild, or have it return false to run the code again.
+    **What's at a module's top level outlives it.** The page keeps every version of a module for as long as it's open,
+    with whatever its variables point at, so a list of objects or a memo at a module's top level holds the old run's
+    world, and each run of the code gets slower. Release what the module gathered in `hot(import.meta).dispose(…)`, and
+    have the run or the part that owns a system drop it where it's registered (the game's `dispose` for what a run made,
+    a part's own `dispose` for what it keeps, which stays registered while the part is kept). A kept renderer doesn't
+    manage what a run builds around it: every render pipeline, pass and effect made in a run gets an explicit teardown in
+    the game's `dispose`, the pipeline first and the scene pass it reads last, each step safe if an earlier one throws,
+    and never `renderer.dispose()`. A build hands on only the data a later consumer needs: one closure kept at a module's
+    top level holds everything the function that made it gathered. A reusable generated texture needs an explicit kept
+    owner and what invalidates it (a `keep` with `from`, or the kept object it's made from); a transient one needs
+    teardown, and not every texture at a module's top level belongs in `keep`. Keeping a compound object doesn't dispose
+    what's nested in it, so its `keep` takes a `dispose`, and a custom `dispose` spares what another owner still uses,
+    since it replaces the runtime's own. A big table that doesn't
+    change as it's played is built inside `keep`, with what it's read from in `from`, so a run reuses it; what changes
+    as it's played stays out of `keep`. Name the file's address outside the build (`const address = new URL('./x.bin',
+    import.meta.url)`): the runtime writes `import.meta` out differently each run, so a build that names it is built
+    again every time.
+    `hot(import.meta).dispose(data => …)` takes away what a version made at its top level, keeping in `data` what the
+    next version reads as `hot(import.meta).data`.
+
+  A stylesheet is swapped by itself. Where running again can't be done (a change to the import map or to a script that
+  isn't a module, modules that import each other in a circle) the change waits for the person's Reload, which opens the
+  page again from what's registered; so does new code that fails as it starts, before its first frame or in its first
+  second, at once. A game bundled from TypeScript is one
+  file, so its changes run it again, and what it keeps is built again with each change.
+- `busy()` is true while a match, race or round is on: a change that runs the code again then waits for the next
+  pause, and the person can put it in at once with Reload. A swap goes in at once.
+- On a phone, Android, a TV or the Xbox a change arrives when Lamp installs the game again, and the runtime puts what's
+  registered back then, once, as it does the last snapshot.
+
+Swift: a change reopens the app; what it keeps is what it saved.
+
+## Keeping every frame smooth
+
+A frame has about 16 ms, and anything that runs during play takes from it, so a slow piece is a stutter:
+
+- load each picture, model and sound once and reuse it; prepare a level before it starts;
+- reuse what comes and goes (bullets, enemies, particles) rather than making new ones each time;
+- allocate nothing per frame, and keep per-frame work to what moves;
+- many copies of one thing are one draw (THREE.InstancedMesh, `LampScene.copies` in a Mac-only app).
+
+The request's device line names the slowest device the game is played on and its budget; the log says how frames kept
+to time. When frames are late, draw less.
+
+## The look
+
+Sprites, characters and backgrounds are art from `make_art` or one ready-made pack (the assets skill), all in one
+style, on a transparent background where they move. Shapes and colors made in code, well lit, look better than
+mismatched models. Score, pause and menus are large and easy to read, over the game (SwiftUI over a SpriteView; HTML
+over the canvas in a page), and made for its world: the game-ui skill says how to choose the screens a game needs and
+give them its theme.
+
+After changing anything that moves, look_at_app with `motion` shows what changes frame to frame and catches flicker a
+single picture hides.
+
+## Playtesting
+
+`use_app` plays the game in front of the person, so play it only when they ask you to try, play or test it; then play it
+the way they would, since a game that only looks right isn't done. For a request to change it, build and look, and say
+in your report what you didn't play rather than calling it checked. On Lamp's game runtime, `use_app` plays the game in its window on this Mac, the one the person has open, with Lamp's own controller (`stick`,
+`button` and `wait`), in plain sight and from wherever the game is: a menu, a pause screen, the middle of a level. A
+button or field the game's page shows (a menu, a mode switch, a name) is used with `click`, `double_click` or `type` by
+its id from the screen as text; `key` isn't taken there, so what a key does in play is a `button` or a `stick`. A click
+is only sent: the next picture and the log say whether the game took it. Read
+the last picture first and get to what you mean to check; to begin again, look with `reopen` (which asks the person
+first while they play). Play a whole round: start, learn the controls, score, get hit, lose, win, pause. Ask of each
+stretch whether it's fun: is there always something to do, does each action answer, is it too easy or too hard, does
+anything surprise. Fix what isn't, and play it again.
+
+A fix goes into the open game as you save it (or with a look), so play on after one with `use_app`; nothing replays the
+moves before it, and the game's random numbers differ each time, so play to the same place again rather than expecting
+the same frames. The person playing takes the game back at once: then use_app is off until their next message.
+
+A C++ game (played on the Xbox), SpriteKit in a Swift app and a page with a loop of its own take no controller from Lamp:
+`use_app` there acts as that place takes it, where the person sees it, so it waits for them to ask. Without that, keep to
+what `look_at_app` shows, and say what you didn't play rather than calling it checked.
+
+## A game and the project's other apps
+
+When the person wants an app to become a game ("actually, make it a game"), change its code in place: the same app,
+now played. If they might want both (the app they use and a game beside it), ask once whether to keep the app as well
+or replace it. Turning it into a game is a change to that app: `make_app_for` with its folder in `app` and `kind`
+"game" (made as the table's defaults say unless the person names a make: web wherever Lamp has a host for a page),
+keeping its folder and data, and its code changed into a
+game. A game beside
+the app is one more app, only when they say they want both and the game is of another kind than the app:
+`make_app_for` with `another` and `kind` "game", in a folder of its own, once they chose that when you asked. Two apps
+of one kind can't be in one project yet (the `more-apps` skill), and a game is never made web only to get around that. A
+game that becomes an app again is the same in reverse.

package/Resources/skills/game-3d/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: game-3d
+description: For a web game at home on the Mac that's drawn in 3D (a world with depth, a camera that moves through or around it, models and light) - three.js on Lamp's game runtime, models, light and materials, and what costs the most. Choose it by how the game is drawn, not by the word 3D. Not for a flat game with depth effects. Things that move as bodies are game-physics.
+sections: 3d-game#; 3d-game#A game on Lamp's runtime; 3d-game#Models, light and materials; 3d-game#What costs the most
+---
+
+# A web game in 3D on the Mac
+
+The web-game guide and game-feel hold for a game in 3D as for one in 2D; this is how it draws. Where it names Physics,
+that's the game-physics skill.
+
+{{sections}}

package/Resources/skills/game-art/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: game-art
+description: For a web game at home on the Mac whose look is part of what's asked - a style the person named (pixel art, hand-drawn, neon, cozy), a game that's mostly its look, or drawn art beyond shapes - authored screens and titles, a theme carried into how screens are built, and drawing the art. Not for every game: the guide's How it looks and game-feel's feedback are the baseline.
+sections: game-ui#Authored, not defaulted; game-ui#Theme in the composition; 2d-game#Drawing the art; 2d-game#Pixel art or smooth
+---
+
+# A look that's this game's own
+
+The web-game guide and game-feel hold; this is for when the look itself is asked for.
+
+{{sections}}

package/Resources/skills/game-feel/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: game-feel
+description: What makes a web game at home on the Mac good to play, beside the web-game guide's runtime rules - fun and feedback, sound, saves that never lose progress, a flow that starts and restarts cleanly, a finished look, and teaching in play. Playing it, checking it and judging it are the game-playtest skill's, when the person asks. Lamp hands it over with the guide when the game is made; open it in a later conversation before changing how the game plays, teaches or looks.
+sections: game#Fun; game#Sound; game#Saves; game-ui#What every flow keeps; game-ui#A finished look; game-ui#Teaching and input; game-ui#Feedback and layout
+---
+
+# What makes the game good to play
+
+The web-game guide says how the game runs on Lamp's runtime; this says what makes it worth playing, and every game
+needs it. Where the two touch the runtime (files, input, how sound loads), the guide holds. A section below that points
+to the game or game-ui skill means the part that's here; open another skill only when the guide says the game needs it.
+
+{{sections}}

package/Resources/skills/game-levels/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: game-levels
+description: For a web game at home on the Mac with more than one round to it - levels, stages or worlds, unlocks and a level select, a menu that's a place to walk through, a story, a pause menu with options - choosing the flow before drawing the screens. Not for one round with a score: title, play and results are the guide's flow, and game-feel keeps what every flow needs.
+sections: game-ui#A short brief; game-ui#Pick the flow first; game-ui#A menu that's a place, where it suits
+---
+
+# Levels and the screens between them
+
+The web-game guide and game-feel hold; this is for a game whose rounds add up to more. Saves that keep each unlocked
+level are game-feel's Saves.
+
+{{sections}}

package/Resources/skills/game-live/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: game-live
+description: For a web game at home on the Mac that's open while you change it, when the change is structural - new or split modules, a world that streams in parts, what has to last moved or renamed, or a change that won't go in, needs Reload or loses the player's place. Not for a color, a number, text or a tweak to how something moves: those go in as they are, with the guide's rules for keeping the player's place.
+sections: game#Changes while it's played
+---
+
+# Structural changes to a game that's open
+
+The web-game guide's "Keeping the player's place" is what every change keeps; this is the whole of how changes go into
+a running game, for the ones that move its structure.
+
+{{sections}}

package/Resources/skills/game-physics/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: game-physics
+description: For a web game at home on the Mac whose fun is things behaving as bodies - they fall, roll, stack, topple, bounce off each other, ride on wheels, swing on joints, or a board tilts under them - with Rapier in 3D, or Phaser's Matter in a flat game. Choose it by the mechanics, not the words: a car that drives on its wheels needs it, stars that fall to be caught don't. Not for steering, simple gravity or checking what touches what: the guide's setup does those.
+sections: 3d-game#Physics
+---
+
+# Things that behave like things
+
+The web-game guide and game-feel hold; this is the physics a game of bodies needs, with Rapier, which Lamp ships for a
+game drawn in 3D. A flat game whose things must tumble, stack or swing on joints uses Phaser's Matter instead
+(`physics: { default: 'matter' }` to `phaser()`), with the same reasons for when it's worth it.
+
+{{sections}}

package/Resources/skills/game-playtest/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: game-playtest
+description: For a web game at home on the Mac, only when the person asks to play it, test it, check that it works or judge how it looks - playing a round in its window, seeing the real opening, proving a flow and its screens, and one short critique. Open it then, and do only what was asked. Never for a request that only changes the game.
+sections: game#Playtesting; game-ui#Check the real opening; game-ui#Proof; 3d-game#Checking it
+---
+
+# Playing and checking the game, when asked
+
+Lamp builds this game and opens it at the end of every turn, and says whether its window drew. Playing it, looking at
+it and judging it happen only when the person asks, and only as far as they asked:
+
+- **Play it, test it, check it works:** one `use_app` round as the person would play it: start, steer both ways,
+  take a hit, wait out the round to the results, press A to restart. Fix what fails and play that part again.
+- **How it looks:** one `look_at_app` (with `reopen` for the opening, `motion` for what moves), without playing a
+  round. It's the game's window as the person has it; how it fits a smaller window is checked by reading its layout
+  against the stage's (the web-game guide).
+- **Check the code:** read it, without opening or playing the game.
+- **A critique:** look at the opening, a moment of play and the results in the pictures you already have, against
+  what the person asked for. Name at most one thing a player would trip on or that reads as a template, and fix it,
+  or say nothing is worth changing. A screen that works isn't restyled for this.
+
+A request to check once doesn't reach later changes: the next change is written and finished as the guide says. The
+sections below hold for this game only inside what the person asked; where one says "before you finish", read "when
+asked". Say what you didn't try.
+
+{{sections}}