@lampdotdev/lamp 0.0.0-stage → 0.36.2-nightly.16

package/Resources/skills/assets/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: assets
+description: Ready-made models, sprites, tilesets, UI, icons, textures, sound effects and music from Lamp's free index (the `assets` tool) - when to use them rather than making things in code or with make_art, keeping one style, loading them so a change shows in the running game, glTF scale, orientation, copies and animations in three.js, sprite sheets and tilesets in Phaser, sounds and music, pictures for apps, and their credit. Read before choosing how a game's or app's things will look or sound.
+---
+
+# Ready-made assets
+
+The `assets` tool searches Lamp's index of free work by people who publish it for anyone to use: low-poly 3D packs
+(Kenney's city, houses, furniture and survival kits, Quaternius's cars, nature, animals, people and monsters, KayKit's
+city bits, a few single models such as a taxi or a bus), Kenney's 2D packs (a platformer, a space shooter, a top-down
+racer, pixel-art towns and dungeons, cartoon characters, animals), UI pieces, icons, ambientCG's tileable materials,
+Kenney's interface sounds and SubspaceAudio's retro effects and music loops. Each is CC0, or CC-BY, which asks for
+credit. Lamp fetches what you choose into the app, checks it, makes its pictures smaller where the slowest place it's
+shown needs that, and writes its credit in credits.json. Nothing is
+loaded from the network while the app runs.
+
+## Ready-made or made yourself
+
+Ready-made, when the person wants things that look like real things and there are many of them, or that move in
+ways code can't easily give: a city of different buildings, real-looking cars, people and animals that walk and run
+(their skeletons and animations come with them, which code can't make), a forest of varied trees, a platformer's
+character with its run and jump frames, a tileset for a whole level, a UI that looks finished. And whenever the person
+asks for "the same game with different models" or another look for a game that exists (below).
+
+Made yourself, when the thing is simple or abstract (blocks, balls, a neon track), when the game moves its parts itself
+(a robot whose arms the player aims, a car whose doors open), when it must match something the person described or
+gave, when only one or two things are needed and code makes them well, or when nothing in the index fits the style.
+Three.js shapes or Phaser graphics for shapes; `make_art` for a picture in the app's own style (a hero, a boss, a
+backdrop, an illustration in an app). The two mix well when the code-made things take the pack's palette.
+
+Sounds and music have a rule of their own, below: the index comes first.
+
+Look first with `find` (and `kind`), `show: true` to see the candidates together, before deciding: it costs nothing.
+
+## One style
+
+Things seen together come from one pack, or from one author's packs, whose `style` matches: Kenney with Kenney,
+Quaternius with Quaternius. Different authors' low-poly flat-color work can sit together, but look at them side by side
+(`show`) first: a pastel KayKit house beside a sharp Google Poly taxi reads as two games. Fill what the pack lacks in
+code, in its colors and proportions, rather than with a third style. In 2D, pixel art at one size (16 px) never mixes
+with smooth vector art.
+
+## Bringing them in
+
+1. `assets` with `find` ("taxi", "low-poly tree", "platformer player") and `kind`, and `show: true`. Each line has an
+   id, its triangles, its box in its own units, its animations, its size, its pack, author, license and style.
+2. `assets` with `fetch` and the ids. They land in Web/assets/<pack>/ for a game or another page, or Assets/<pack>/ for
+   a Swift app (app/src/main/assets/<pack>/ for a native Android app, read with `LampAssets`), and the answer gives each
+   file's path as the app loads it.
+3. Load each through the runtime (below), then `look_at_app`: a model's size and the way it faces are only certain once
+   seen.
+
+The answer leaves out what's too heavy for the slowest place the app is shown (an Xbox One, a TV, a cheap Android
+phone): what's listed fits one copy. The scene's total is still yours to keep within the device line's budget: twenty
+cars of 3,000 triangles are 60,000.
+
+Keep every asset's path in one table at the top of the game (`const MODELS = { taxi: 'assets/poly-quaternius/car.glb', … }`),
+with each thing's real size beside it. Changing the look is then that table, which is also how "the same game with
+different models" is made: find a set in another style, fetch it, and point the table at it; the game's code stays.
+
+## In a three.js game
+
+Load with lamp-game.js, never a loader of your own, so a new copy of a file goes into the running game:
+`const taxi = await model(MODELS.taxi)` in `init` gives a `THREE.Group` holding the file's scene, with
+`taxi.animations`. Pictures: `texture(path, t => { t.colorSpace = THREE.SRGBColorSpace; })`.
+
+- **Scale.** Units differ by author: Kenney's are tiles (a building about 1 unit wide), Quaternius's and KayKit's are
+  near meters, Google Poly's are often centimeters (a taxi 90 units long). Scale each to its real size from its box,
+  once: a car is about 4.5 m long, a person 1.75 m tall, a door 2 m, a street lamp 5 m.
+
+  ```js
+  function fitted(group, meters, axis = 'longest') {
+      const size = new THREE.Box3().setFromObject(group).getSize(new THREE.Vector3());
+      const now = axis === 'height' ? size.y : Math.max(size.x, size.z);
+      group.scale.setScalar(meters / now);
+      return group;
+  }
+  ```
+
+- **Standing on the ground.** A model's origin may be at its center or its feet: after scaling, lift it by the box's
+  bottom (`group.position.y = -box.min.y`), inside a holder group that the game moves.
+- **Facing.** glTF is y up; most models face +z, some -z or +x. Find out by looking, then turn the holder (or the
+  group) once: `holder.add(taxi); taxi.rotation.y = Math.PI`. Never change the meshes inside the group: a new copy of
+  the file replaces them.
+- **Many copies.** The same model many times: `clone()` shares its geometry and materials (cheap in memory, one draw
+  per mesh per copy); for a whole street of one building or a forest of one tree, an `InstancedMesh` per mesh of the
+  model (walk it with `traverse`, take each mesh's `geometry` and `material` and its matrix within the model) is one
+  draw for all of them. A rigged character (one with `SkinnedMesh`es) is copied with `SkeletonUtils.clone` from
+  `three/addons/utils/SkeletonUtils.js`; a plain clone shares one skeleton and every copy moves as one. Copies and
+  instances are made again in `assetChanged(path)` (the game skill, "Changes while it's played").
+- **Animations.** One `THREE.AnimationMixer` per character, its clips found by the end of their names, which carry
+  the rig's name ("CharacterArmature|Walk"):
+
+  ```js
+  const clip = name => model.animations.find(a => a.name.split('|').pop() === name);
+  const mixer = new THREE.AnimationMixer(character);
+  const walk = mixer.clipAction(clip('Walk')), run = mixer.clipAction(clip('Run'));
+  walk.play();
+  // switching: run.reset().play(); walk.crossFadeTo(run, 0.25, false);
+  // in frame(f): mixer.update(f.dt);
+  ```
+
+  The fetch answer lists each model's animations. Mixers are made again in `assetChanged(path)`.
+- **Materials.** Packs come lit for MeshStandardMaterial. Where the device line names a slow place, swap each mesh's
+  material for a `MeshLambertMaterial` with the same `color` and `map` as the game starts. Shadows only where the budget
+  allows them: `castShadow` on each mesh through `traverse`.
+- **Textures** (ambientCG): color in sRGB, the normal and roughness maps as they are, all with
+  `wrapS = wrapT = THREE.RepeatWrapping` and `repeat` set so a tile is about its real size (a 1K brick map covers about
+  two meters).
+
+## In a Phaser game
+
+Load in a Boot scene's `preload`, by the path the fetch gave:
+
+- **A sprite sheet with an XML atlas** (most of Kenney's 2D packs):
+  `this.load.atlasXML('players', 'assets/kenney-platformer/spritesheet_players.png', 'assets/kenney-platformer/spritesheet_players.xml')`.
+  Its frames are named as the XML says ("alienBeige_walk1.png"); an animation is
+  `this.anims.create({ key: 'walk', frames: this.anims.generateFrameNames('players', { prefix: 'alienBeige_walk', start: 1, end: 2, suffix: '.png' }), frameRate: 8, repeat: -1 })`.
+  Read the XML (the fetch put it beside the sheet) for the frame names before writing them.
+- **A tilesheet** (the pixel-art packs): `this.load.spritesheet('tiles', path, { frameWidth: 16, frameHeight: 16, spacing: 1 })`
+  with the size and spacing the fetch answer gives, and in a tilemap
+  `map.addTilesetImage('tiles', 'tiles', 16, 16, 0, 1)` (margin, then spacing). Its tiles are numbered left to right,
+  top to bottom, from 0: look at the sheet before writing the level's rows.
+- **Pixel art** at 16 px wants `pixelArt: true` and a whole-number camera zoom (the 2d-game skill); smooth art is drawn
+  at its own size or smaller, never scaled up.
+
+A picture Phaser's loader read goes in again through `assetChanged(path)` in phaser() (the 2d-game skill).
+
+## Sounds and music
+
+Kinds `sound` (short effects) and `music` (loops). Each line has its length and says when it loops. `show` has nothing
+to show: a sound's name and notes are all you can judge it by, so try it in the game, and say in your report that you
+haven't heard it, since Lamp hears nothing of what plays.
+
+A game's sounds start here, whatever else it makes in code. List them all before writing any: `kind: sound`, `limit: 30`
+and no `find`, then `kind: music`, since one search stops at its own words. Go through each moment (a click, a flip, a
+coin, a hit, a win, a loss) and the music against those lists: "Coin", "Impact" or "Jump" may do for a flip. Make one in
+code (the game skill, "Sound") only when nothing here fits that moment, or when it must follow the game as it's played
+(an engine's pitch, notes on a scale), and say which and why in your report.
+
+Most sounds here are retro and chiptune. That's no reason to skip them, since a tone written in code is no less
+synthetic; a clip that's wrong for the moment is. One game keeps to one sound family as it keeps to one art style.
+
+Choose them as the game is made, and fetch them then: they ship inside it, so the game works offline. Load each once, as
+the game sets itself up, through the runtime, and play it with what the game skill names:
+
+```js
+const SOUNDS = { click: 'assets/subspace-retro-sfx/sfx_menu_select1.wav', coin: 'assets/subspace-retro-sfx/sfx_coin_single1.wav' };
+const click = await sound.load(SOUNDS.click);
+const theme = await sound.load('assets/subspace-music-loops/menu-relaxed.ogg');
+sound.play(click, { volume: 0.7 });
+sound.music(theme, 0.35);
+```
+
+Keep them in one table, as with models, and keep the mute setting and `sound.volume` as the game skill says: a fetched
+sound follows them like any other. A loop is decoded whole, about 20 MB of memory a minute: one or two on a phone or a
+TV, and the shortest that does. Native games read the same files: `lamp_sound_load` and `lamp_music` take
+`"<pack>/<file>"` from Assets/, and a Swift app `LampAssets.url("<pack>/<file>")`.
+
+Kenney's interface sounds and the music are Ogg Vorbis, which a page or `AVAudioPlayer` on Apple's devices decodes only
+from about macOS 15.4 and iOS 18.4: on an older one such a sound stays silent, and the page's log says it couldn't be
+loaded. SubspaceAudio's effects are WAV and play everywhere, so they carry a game's menus and what the player needs to
+hear; use them for those on an older Mac or iPhone.
+
+## In an app
+
+On Apple's devices, an SF Symbol comes before any icon file. Kenney's icons and UI pieces suit a game's menus, a web
+app or a page on a TV. An illustration in an app is `make_art`'s, in the app's own style. In a Swift app a fetched file
+is in Assets/<pack>/, read with `LampAssets.url("<pack>/<file>")` or `LampAssets.image(…)`; a .glb in a Mac app's
+RealityKit scene is turned into USD as the scene-3d skill says.
+
+## Credit
+
+Lamp writes each fetched asset, sounds and music included, into credits.json (its pack, author, license and files), which the app's info, its About
+window, a shared copy, a published page and its repository's README all show: never take an entry out. CC-BY work asks
+for more: name it where the game or app shows its credits too (a Credits line in the pause menu or the About screen:
+"Taxi by Poly by Google, CC BY 3.0"), which the fetch answer reminds you of. CC0 needs nothing, though a line thanking
+the pack's author is kind.
+
+## When nothing fits
+
+Make it in code, in the style of what's there, or with `make_art` for a picture. Lamp has no way to make a new model
+from words yet: don't promise one.

package/Resources/skills/building-blocks/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: building-blocks
+description: How to call LampSupport.swift's tested building blocks - notifications, schedules and work while the app is closed, text from documents and pictures, dropped files, folders, global shortcuts, the clipboard, login items, photos, location, weather, music, Spotlight, the home, the devices on the home network and a Roku. Read before using any of them.
+---
+
+# Lamp's building blocks
+
+LampSupport.swift has tested building blocks for common jobs, the same ones on a Mac and an iPhone where both have
+them. Use them instead of writing your own.
+
+## On both
+
+- `LampNotifications.send("Title", body: "…")`, also `at: date` to show it later, even with the app closed, `id:` to
+  replace or `cancel(id)` one, `actions: ["Done", "Snooze"]` for buttons that work without opening the app, handled by
+  `LampNotifications.onAction { action, id in … }` set where the app starts, and on iPhone `timeSensitive: true`,
+  with `{"timeSensitive": true}` in capabilities.json, for what can't wait, sparingly.
+- `LampSchedule.daily("briefing", hour: 7) { }` and `LampSchedule.every("inbox", minutes: 15) { }`: work at a time or
+  every so often, catching up after sleep; keep it alive. On an iPhone see "Work while the app is closed" below.
+- `await LampText.read(url)`: text from PDFs, scanned PDFs, images and screenshots via Live Text, RTF, Word, HTML,
+  plain text, all on the device and free; use it before sending documents to LampAI. `await LampText.recognize(in:
+  image)` for an `NSImage` on the Mac, a `UIImage` on iPhone.
+- `.lampDropFiles { urls in }` on any view and `LampDropZone("Drop screenshots here") { urls in }` for an empty state
+  (Finder files, images from other apps, links; on iPad, files and images dragged in from another app).
+- Photos: `LampPhotos` (`authorize()`, `photos(days:)`, `photos(near:_:km:)`, `favorites()`, `albums()`,
+  `photos(in:)`, `image(_:size:)`, `tags(of:)` for what a picture shows (empty in the simulator), `save(_:)`;
+  choosing one is SwiftUI's `PhotosPicker`).
+- Location: `LampLocation` (`current()` with a name from the map, `find(address)`, `distance(from:to:)`,
+  `shared.watch()` for big moves, `shared.watchVisits()` on the iPhone for where the person stops and for how long,
+  which needs `"backgroundModes": ["location"]`).
+- Weather: `LampWeather` (`now(latitude:longitude:)`, `hours`, `days`, `here()`), after `{"weather": true}` in
+  capabilities.json, for apps with an iPhone half only; the team also turns WeatherKit on for the app at
+  developer.apple.com once, and the call's message says so until then (otherwise, Open-Meteo through `connectors`).
+  Apple's terms ask for `LampWeatherAttribution()` (its Weather mark, linking to its sources) wherever its weather is
+  shown, allow forecasts to be kept only briefly (never saved with the app's data), and rule out apps meant for
+  emergencies or safety.
+- Music: `LampMusic` (`authorize()`, `recentlyPlayed()`, `library()`, `search(_:)`, `play(_:)`, `pause()`, and on the
+  iPhone `nowPlaying`), Apple Music only, with MusicKit turned on for the app at developer.apple.com the same way.
+- Spotlight: for the app's own things people would look for by name (notes, recipes, people, trips),
+  `LampSpotlight.index(id:title:details:keywords:)` when one is added or changed and `LampSpotlight.remove(id)` when
+  it's deleted, and `.lampSpotlightOpen { id in … }` on the view that shows them, to show the one tapped in Spotlight.
+
+- The home network: `LampNetwork`, for an app on the Mac or a phone that controls, plays to or reads the person's
+  devices (a remote for the TV and speakers, what's playing, a light). The system asks the person about the local
+  network before anything answers, so the app says why first, in its own words and on its own screen, and asks with
+  `await LampNetwork.requestAccess()` (`.allowed`, `.denied` with `LampNetwork.allowHint` saying where to turn it on,
+  or `.unknown` off a home network), never at launch. Then `await LampNetwork.find()`: every device that answers, each
+  with `address`, `name`, `maker`, `model`, what it answered SSDP for (`ssdp`, `server`, `location`) and its Bonjour
+  services (`bonjour`). An iPhone app sees only the Bonjour types in capabilities.json's `bonjourServices` (add the
+  types of the devices the app is for: `"_sonos._tcp"`, `"_googlecast._tcp"`), and the system's question shows
+  `"localNetwork"` there, the app's own reason ("TV Remote finds your TV and speakers to control them."). Work out how
+  to reach each device from what it says of itself; a Roku is `LampRoku`'s. Its maker and model say what a device is;
+  its services say only what it can do: a console and a TV both answer as media renderers, and a Mac offers AirPlay,
+  so none of them is a speaker for that.
+- Roku: `LampRoku`, for an app on the Mac or a phone that controls the person's Roku (a remote of its own, buttons
+  that open Netflix or a show, what's playing, a Roku TV's power, volume and input), with nothing installed on the
+  Roku. An app that runs on the Roku itself is a Roku app instead. `await LampRoku.find()` (every Roku that answers,
+  each with `name`, `isTV` and `canBeControlled`), then `launch(named:)` or `launch(appID:contentID:mediaType:)` for a
+  deep link, `press(.home)` and the other keys, `type(_:)` into its on-screen keyboard, `activeApp()`, `playing()`,
+  `apps()`, and on a Roku TV `power(on:)`, `press(.volumeUp)` and `input(.hdmi1)`. The one setup is on the Roku:
+  Settings, System, Advanced system settings, Control by mobile apps, Network access set to Enabled
+  (`LampRoku.setUp` says it); show that when `canBeControlled` is false or a call says so, and never suggest
+  Permissive. The first `find()` makes the system ask about the local network, so give the person a way to look
+  again; remember the Roku they chose by its `id`, and offer a choice when more than one answers.
+
+## On the Mac only
+
+These exist only in a Mac app's copy of the library (in an app for both, only under `#if os(macOS)`):
+
+- `LampFolderWatcher(folder) { changedURLs in }`: files added or changed in a folder; keep it alive.
+- `LampFolders`: downloads, desktop, documents, screenshots, `files(in:)` newest first.
+- `LampHotKey("cmd+shift+space") { }`: a shortcut that works from any app; keep it alive.
+- `LampLoginItem.isEnabled`: open at login. Offer it as a toggle in Settings, never turn it on yourself; an app that
+  declares `"background": true` is opened at login by Lamp.
+- `LampClipboardWatcher { item in }` (item.text / image / fileURLs; keep it alive) and
+  `LampClipboardWatcher.copy(text)`.
+
+## On iPhone only
+
+An iPhone app's copy of the library has none of the Mac-only blocks above, nor Mail, other apps, the menu bar or the
+permission screens: never call them there.
+
+- Home: `LampHome` (after `{"homekit": true}` in capabilities.json): `accessories()` (lights, locks, thermostats,
+  sensors, switches, each with its room and state), `set(_:on:)`, `set(_:brightness:)`, `set(_:locked:)`,
+  `read(_:)`. Apple's terms allow it only in an app whose job is controlling the home, and what it reads never
+  leaves the phone: not to LampAI, a server, LampSync or the Mac.
+
+### Work while the app is closed
+
+When the app should do something while it's closed (fetch the news before breakfast, check a price, tidy up,
+remind), declare `{"background": true}` in capabilities.json, put `.lampBackground()` on its WindowGroup, and make
+`@State private var check = LampSchedule.every("prices", minutes: 60) { … }` or
+`LampSchedule.daily("briefing", hour: 7) { … }` in the App, the same calls as on a Mac. iOS runs them while the app
+is closed when it judges best: near the time, not on the dot, at most a few times an hour, and less for an app the
+person rarely opens; while the app is open they run on time. Keep each run short (seconds) and tell the person what
+came of it with a notification. Something that must happen at an exact time and only needs to tell the person is a
+notification sent with `at:`, not a schedule. The simulator never wakes a closed app by itself, so try the work by
+running it from the app.

package/Resources/skills/device-control/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: device-control
+description: How an app controls, plays to or reads the person's own devices on their home network (a TV, speakers, a console, lights) when Lamp has no block for them - finding each one, working out its local API, writing it into the app, and asking the person before changing anything on a real device. Read before writing code that reaches one of their devices.
+---
+
+# Controlling the person's devices
+
+A remote for the TV and speakers, buttons that open the family's apps, what's playing in the menu bar: the app talks
+to devices that are really in the person's home. Work out each one from what it says about itself, and never change
+anything on a real one until the person has said you may.
+
+## What's there
+
+- Call `network_devices` first: what Lamp's own look found, with what it already has for each device. Start from
+  that, not from a question about what the person owns, and ask only about what it can't tell you.
+- In the app, find devices with `LampNetwork` (the building-blocks skill): `requestAccess()` after the app has said
+  why, then `find()`. Give capabilities.json a `localNetwork` reason in the app's own words, and the Bonjour types
+  of the devices it's for in `bonjourServices` (an iPhone app can look for no others).
+- A Roku is `LampRoku`'s. Use it rather than writing ECP yourself.
+- A device's maker and model say what it is. Its services say only what it can do: a console and a TV both answer as
+  media renderers, and a Mac offers AirPlay, so none of them is a speaker for that.
+
+## Working out a device
+
+For a device Lamp has no block for, find how its maker's own phone app talks to it on the home network, from what it
+says about itself: its SSDP answer and UPnP description (`location`), its Bonjour services and TXT record, its model.
+Most have a local API: an HTTP or SOAP service (Sonos on port 1400, UPnP's AVTransport and RenderingControl), a
+WebSocket (Samsung's remote channel, LG's second-screen socket), or a documented REST API. Read it from the device
+(its description, a status endpoint) before relying on it. Some can't be reached this way: pairing that needs
+cryptography of the maker's own (Apple TV, a Google TV's remote), or control only through the maker's cloud account.
+Say so plainly in a sentence instead of half-building it.
+
+## Writing it
+
+- One file per kind of device, behind one small protocol the rest of the app uses, so a new kind is one more file:
+  what it can do (keys, apps, text, volume, power, what's playing) and how. The screen asks a device what it can do,
+  never which kind it is: a TV without volume over the network shows no volume buttons.
+- Reach only addresses that discovery found, or one the person typed.
+- A device that signs its own secure socket (an LG's 3001, a Samsung's 8002) is trusted for that address alone,
+  never every certificate the app meets.
+- A token a device hands back after the person allows the app on its screen is kept with the device in LampStore:
+  it only lets an app on this network reach that one device, and the remote must work with Lamp closed, which
+  `LampSecrets` on a Mac doesn't. A sign-in to the maker's account is the person's: `LampSecrets`, never LampStore.
+- When the device asks the person on its own screen (Allow on a TV), the app says so while it waits, and what to do
+  if they missed it.
+- Example devices for exploring with nothing found, clearly marked, sending nothing.
+
+## Asking before changing a device
+
+Reading a device is always fine: what it is, its apps, what's playing, its volume. Changing one is the person's to
+allow: a key press, opening an app, the volume, the input, power, a setting. Before the first change on a device, by
+a command or by using the app (`use_app`), call `device_permission` with the device as the person knows it, its address,
+and what you'd do, and end your turn. Lamp shows the card and keeps the answer: "Allow once" covers this request, "Always for"
+the device covers the wish. Lamp refuses `use_app` on an app that reaches devices unless its `device` names one the person allowed,
+and every engine's check refuses a command that changes a device without it. When the answer is "Not now", leave the
+device alone and say how the person can try it themselves.

package/Resources/skills/device-integrations/SKILL.md

@@ -0,0 +1,278 @@
+---
+name: device-integrations
+description: A device Lamp has no kit for (a streaming stick, a photo frame, a TV, an appliance), described as data for device_integration - how Lamp finds it, reads who it is, sets it up step by step, and puts software on it. Read before writing or fixing an integration.
+---
+
+# Device integrations
+
+An integration is a JSON object handed to Lamp with `device_integration`. It is data, never code: Lamp acts on it with
+its own primitives, fills every value itself, draws every card the person sees, and checks each step on the device.
+Write it from the device's own documentation (its developer docs, its local API's reference). Lamp answers with what's
+wrong; fix exactly that and send it again.
+
+You never reach the device: no command, request or scan of yours. Lamp does that. You never walk the person through
+steps in the chat: the steps are cards Lamp draws from what you write here.
+
+## Shape
+
+```json
+{
+  "id": "roku",                        // lowercase letters, digits, dashes
+  "name": "Roku", "maker": "Roku", "kind": "streaming stick",
+  "sources": ["https://developer.roku.com/docs/developer-program/debugging/external-control-api.md"],
+  "find": [{ "ssdp": "roku:ecp" }],
+  "identity": { ... },
+  "steps": [ ... ],
+  "bridge": { ... },                   // how an app goes on it, opens, is seen and is used
+  "app": { ... }                       // what's built for it; needs bridge.install
+}
+```
+
+### find
+
+How the device announces itself; any one that matches finds it. Each entry has exactly one of:
+
+- `"ssdp": "<search target>"`, optionally `"contains"` for what the answer's SERVER line holds.
+- `"bonjour": "_service._tcp"`, optionally `"contains"` for the name.
+- `"http": {"port": 8060, "path": "/query/device-info", "contains": "<device-info>"}`: asked of every address that
+  answered Lamp's own SSDP scan.
+
+### identity
+
+Where each field of the device's record is read from its own answers. `os` is said once; the rest are reads. `id`
+(unique to this one device: a serial, a UDN) and `model` are required.
+
+```json
+"identity": {
+  "os": "Roku OS",
+  "id":        { "http": { "port": 8060, "path": "/query/device-info" }, "xml": "serial-number" },
+  "model":     { "http": { "port": 8060, "path": "/query/device-info" }, "xml": "model-name" },
+  "name":      { "http": { "port": 8060, "path": "/query/device-info" }, "xml": "user-device-name" },
+  "modelID":   { "http": { "port": 8060, "path": "/query/device-info" }, "xml": "model-number" },
+  "osVersion": { "http": { "port": 8060, "path": "/query/device-info" }, "xml": "software-version" }
+}
+```
+
+A read has `json` (a dotted path: `device.modelName`, `items.0.id`) or `xml` (an element, or `parent/child`). Reads are
+GETs. In place of `http`, `"description": true` reads the device's UPnP description wherever its SSDP answer points now
+(with `xml`), for a device whose description moves with its mode, as an Xbox's does. `contains` on a read says what the
+value must hold for the device to be this kind (`"contains": "Xbox"` on the model), when other devices answer the same
+search.
+
+### Requests
+
+Every request goes to the address the device was found at; you give only the port and path.
+
+```json
+{ "method": "POST", "port": 80, "path": "/plugin_install",
+  "auth": { "digest": true, "user": "rokudev", "password": "{field:password}" },
+  "form": { "mysubmit": "Install", "archive": "@{package}" } }
+```
+
+`https: true` for a device that only speaks HTTPS with a certificate of its own (Xbox's Device Portal): Lamp
+trusts that certificate the first time and holds the device to it after. `method` (GET, POST, PUT, DELETE), `headers`, `body` or `form` (a value `"@{package}"` sends the package file), `auth`
+(`digest` true or false for basic; the password is always one `{field:…}`), and `keep`: `"picture"` in `bridge.look`
+for the answer that is the screen's picture, `"screen"` in `bridge.screen` for the answer that is the screen as text (the
+tree of what the app shows, where the device describes it), `"log"` in `bridge.log` for the answer that is the app's log, `"key"` in a
+step's `run` for an SSH key the device gives this Mac.
+`poll` (seconds) asks again every two seconds while the device answers 204 (still working on an install), and `expect`
+(`json` or `xml`, with `equals` or `contains`) is what the answer must say for the step to count, else it fails with the
+device's words. In a `json` path, `*` is every element of a list, and the answer counts when any of them says it
+(`"InstalledPackages.*.PackageFullName"`); `equals` and `contains` may hold Lamp's values (`"{packageFullName}"`).
+`until` (seconds, with `expect`) asks again every two seconds until the answer says it: for a device that's done with an
+install a while before the app can be opened, end `install` with a request that waits until the device lists the app. A form value `"@{certificate}"` sends Lamp's certificate for a wrapped package (below).
+`restore` (a JSON field's name) on a PUT or POST that changes a setting only for its sequence: Lamp first reads the
+same path with a GET, takes that field's value, and when the sequence ends (in `bridge.install`, once the app has been
+launched after it), however it ends, sends `{"<field>": "<that value>"}` back the same way. For a device-wide setting an install needs (an Xbox installs a package as a game only while
+`/ext/settings/DefaultUWPContentTypeToGame` is `{"Value":"{isGame}"}`), so the person's own choice is left as it was.
+
+### Values Lamp fills
+
+Write `{name}`; Lamp fills it, checked to a safe alphabet. You never write a value yourself.
+
+- `{address}` the device's address, `{mac}` this Mac's address on that network, `{deviceID}` the device's id
+- `{package}` the built package's file, `{appID}` the app's id, `{key}` a remote key from `bridge.keys`, `{text}` one character being typed (only in `bridge.type`, in a path, form or body; in a path Lamp percent-encodes it)
+- `{callback}` the sign-in's address back (only in `vendorSignIn.page`), `{signIn}` what that sign-in returned
+- `{sshKey}` Lamp's public SSH key, for a device that must be told it
+- `{field:<key>}` what the person typed in a step's field: only in a sign-in, a form, a header or a body, never in a path
+  or command
+- `{read:<step>}` the value a step's check read
+- `{cookie:<name>}` a cookie the device set earlier in the same sequence, only in a header (a CSRF token: a GET first,
+  then `"X-CSRF-Token": "{cookie:CSRF-Token}"` on the POST)
+- `{packageFullName}` and `{appUserModelID}` a wrapped Windows package's names, and `{base64:<one of Lamp's values>}`
+  any of Lamp's values in base64, as some devices take an id in a query
+- `{isGame}` "true" when the app is a game (Lamp's native games, or `{"game": true}` in the app's capabilities.json or its icon.json),
+  else "false", for a device that installs games differently from apps
+
+### steps
+
+The setup, in order. Each step is done when its `check` passes, never because anyone said so.
+
+```json
+{
+  "id": "developer-mode",
+  "title": "Turn on developer mode",                 // at most 8 words
+  "lines": ["Press Home three times on the remote", "Then Up, Up, Right, Left, Right, Left, Right",
+            "Choose Enable installer and restart", "Set a developer password when it asks"],   // at most 8 lines, 16 words each
+  "wait": true,                                      // hands on the device: Lamp checks again until it passes
+  "accepts": ["softwareRisk"],
+  "check": [{ "http": { "port": 8060, "path": "/query/device-info" }, "xml": "developer-enabled", "equals": "true" },
+            { "tcp": 80 }],
+  "known": { "how": "read", "source": "https://developer.roku.com/docs/developer-program/getting-started/developer-setup.md" }
+}
+```
+
+- `show`: `[{"label": "This Mac", "value": "{mac}"}]`, Lamp's values shown large. `qr`: a value shown as a QR code.
+- `field`: `{"key": "password", "label": "Developer password", "secret": true}`, what the person types; kept for that
+  device only and sent only to it.
+- `link`: an https page to read. A step that roots, jailbreaks or unlocks a device is only ever a link the person
+  follows themselves.
+- `run`: what Lamp does when the person presses the step's button, in order (primitives below).
+- `check`: every condition must hold. Each is one of `http` (answers 2xx; with `json` or `xml`, the value `equals` or
+  `contains` something), `tcp` (a port that accepts a connection), `field` (the person typed it), `signedIn` (a
+  `vendorSignIn` came back).
+- `model`: `true` when the value the check reads is the device's model, finer than what it says before it's set up
+  (an Xbox's description says Xbox One on every console; Device Portal's `/api/os/info` names the console).
+- Every setting of the device's that the bridge needs is a step of its own, checked on the device, so it's found in
+  setup rather than when a builder first uses it: a Roku answers key presses only with Settings → System → Advanced
+  system settings → Control by mobile apps set to Enabled, which its device-info says
+  (`{"http": {"port": 8060, "path": "/query/device-info"}, "xml": "ecp-setting-mode", "equals": "enabled"}`; Roku's ECP
+  page doesn't list that field, but Rokus report it: enabled, limited, disabled or permissive). Never ask for a setting
+  looser than the bridge needs (a Roku's Permissive).
+- `accepts`: what doing it may cost, from Lamp's list; Lamp writes the sentences. `account` (an account with the
+  maker), `softwareRisk` (it may stop working until reset), `warranty`, `dataWiped`, `updatesStop`, `protectionsOff`,
+  `commandRuns` (required by any step that runs `ssh` or a downloaded `tool`).
+- `known`: only `{"how": "read", "source": "<https page>"}`. Lamp marks a step checked or done once it passes on a
+  device; the person sees "Not tried yet" until then.
+
+### Primitives
+
+A step's `run` and each bridge sequence are lists of these, one key each:
+
+- `http`: a request (above).
+- `probe`: `"tcp:8060"`, `"ssdp:<target>"` or `"bonjour:<type>"`; fails the sequence when the device doesn't answer.
+- `stream`: `{"port": 8085}`, the device's log read line by line into the app's log (bridge.logs only).
+- `ssh`: `{"user": "prisoner", "port": 9922, "command": "luna-send-pub -n 1 luna://… '{…}'", "explanation": "…"}`.
+  The person approves the exact command for that device first, with your explanation (plain words, at most 30). One
+  line; values are quoted by Lamp. Lamp pins the device's host key and forwards nothing.
+- `tool`: `{"name": "<Lamp's tool>"}`, from Lamp's list (`unlock-device-key`: unlocks a key kept with `keep: "key"`
+  with the field `passphrase`), or `{"download": "https://…", "sha256": "<64 hex>", "arguments": […], "explanation": "…"}`
+  for another program, which runs confined to its own folder and the network after the person approves it.
+- `vendorSignIn`: `{"page": "https://account.vendor.com/…?redirect_uri={callback}"}`, the vendor's page in the
+  browser; what comes back is `{signIn}`. Setup steps only.
+- `wait`: seconds to wait, 1 to 30.
+
+### bridge
+
+How software goes on the device once it's set up. Each is a sequence of primitives. With `app`, this is all Lamp has
+to make apps for the device with, and the builder of each app gets it as Lamp's own: `install` then `launch` when
+the person presses Play (and at the end of a turn, or Reload, while the app is on the device), `look` for a picture of
+its screen, `use` once for each of the remote's keys pressed (`{key}` is the device's name for it, from `keys`), `logs`
+read into the app's log while it's open. The builder of an app never looks at or presses anything on the device itself,
+only in its `preview` (below), so `look` and `use` are what Lamp's own test run of the integration (from the device's
+setup window) goes through. What the device answers to `install` is shown to the builder, so a device that says there what it
+made of the package (a compile error) needs nothing more. `stop` ends the app when the person stops it (Lamp presses
+`home` when there's no `stop`, or the device refuses it), and for a wrapped package it also ends the copy on the device
+before an update goes over it, with the values of the copy that's there. `running` says whether the app `launch` opened
+is running: a request whose `expect` finds it among the device's processes, with `until` a few seconds. Lamp launches
+again, with growing pauses, while the device refuses the launch or the app isn't running, and says so plainly when it
+never opens. `type` types into a keyboard on the device's
+screen, run once per character with `{text}` that character (a Roku's `/keypress/Lit_{text}`). `log` reads a log the app keeps on the device (a file) for the
+builder, for a device with no log to stream. `remove` takes the app off the device when its project is deleted. With `app`,
+each of `stop`, `remove` and `type` is there or named in `"lacks": ["type"]` when the device has no way to do it, so
+Lamp can tell one forgotten from one that can't be; and every picture the scaffold names is in `files` or `icons`, and
+`rules` names each library in `support`. `known` is Lamp's: once the device is set up, the person can have Lamp try the
+integration on it (a test app put on, opened, pictured, pressed, typed into, stopped, put on again while open, and taken
+off), and a run that passes marks the bridge with the device's model. What the run found comes back to you with the
+next request in the device's setup conversation: fix the integration from the device's own words and send it again.
+
+```json
+"bridge": {
+  "install": [{ "http": { "method": "POST", "port": 80, "path": "/plugin_install",
+                          "auth": { "digest": true, "user": "rokudev", "password": "{field:password}" },
+                          "form": { "mysubmit": "Install", "archive": "@{package}" } } }],
+  "launch":  [{ "http": { "method": "POST", "port": 8060, "path": "/launch/dev" } }, { "wait": 3 }],
+  "look":    [{ "http": { "method": "POST", "port": 80, "path": "/plugin_inspect",
+                          "auth": { "digest": true, "user": "rokudev", "password": "{field:password}" },
+                          "form": { "mysubmit": "Screenshot" } } },
+              { "http": { "port": 80, "path": "/pkgs/dev.jpg", "keep": "picture",
+                          "auth": { "digest": true, "user": "rokudev", "password": "{field:password}" } } }],
+  "use":     [{ "http": { "method": "POST", "port": 8060, "path": "/keypress/{key}" } }],
+  "type":    [{ "http": { "method": "POST", "port": 8060, "path": "/keypress/Lit_{text}" } }],
+  "stop":    [{ "http": { "method": "POST", "port": 8060, "path": "/exit-app/dev" } }],
+  "remove":  [{ "http": { "method": "POST", "port": 80, "path": "/plugin_install",
+                          "auth": { "digest": true, "user": "rokudev", "password": "{field:password}" },
+                          "form": { "mysubmit": "Delete", "archive": "" } } }],
+  "logs":    [{ "stream": { "port": 8085 } }],
+  "keys": { "home": "Home", "up": "Up", "down": "Down", "left": "Left", "right": "Right", "select": "Select", "back": "Back" }
+}
+```
+
+### app
+
+What's built for it: `{"lamp": "tv-web"}` for Lamp's own TV web app, or a kind you declare. A declared kind becomes
+a kind of app people can wish for ("a Roku app that…"): `files` is each new app's scaffold, where `{{NAME}}` is the
+app's name; `rules` is what its builder is told about writing for the device (the language, the layout, the screen,
+how input arrives, where its output is printed, and how it plays sound: the device's own way for short effects and
+for music, the formats it plays, and that a game keeps both quiet with a way to turn them off), as the only guide
+they get; `package` is the shell command that
+makes the package from the app's folder, run there in the app's sandbox with the system's own tools (`zip`, `tar`),
+never anything to download; `output` is where it leaves it, which `"@{package}"` sends.
+
+```json
+"app": { "declared": {
+  "files": { "manifest": "title={{NAME}}\nmajor_version=1\nmm_icon_focus_hd=pkg:/images/icon_focus_hd.png\n…", "source/main.brs": "sub Main()\n…\nend sub\n" },
+  "rules": "What a builder needs to know to write apps for it, in a few sentences.",
+  "package": "rm -f build/app.zip && mkdir -p build images && zip -qr build/app.zip manifest source components images",
+  "output": "build/app.zip",
+  "icons": { "images/icon_focus_hd.png": "290x218", "images/icon_focus_fhd.png": "540x405" }
+} }
+```
+
+The package step runs in the app's sandbox like every build.
+
+`"support"` gives the app Lamp's building blocks (AI through the person's Mac, saved data, the package's own files),
+by library to where they go in the app's folder: `"web": "Web/lamp.js"` for an app that's a web page (a script its
+`index.html` loads before the app's own), `"brightscript": "components/Lamp"` for a Roku channel (a folder its
+components include). Lamp writes them before every build, so keep them out of `files`, and make sure the package step
+takes them into the package. Lamp tells the app where it is and gives it its token on the device itself.
+
+`"icons"` gives the app its icon on the device, wherever the device shows one (a channel's poster on a Roku's home
+screen, a tile, a splash screen, a launcher): by path in the app's folder to its size in pixels,
+`"images/icon_focus_hd.png": "290x218"`, one for each picture the device's manifest names, at the sizes its maker
+documents. Lamp draws the icon it made for the app at each path before every build (a dark tile until there is one), so name those paths in the scaffold's manifest, keep them out of `files`, and make
+sure the package step takes them in. Never draw an icon in the scaffold or the package step. A device that shows no icon
+for an app needs none.
+
+`"support"` may also name `"three"`, three.js (the 3D library, with its light addons), as a folder in the app's web
+folder (`"three": "Web/three"`): for a device whose web view runs WebGL 2 and ES modules and whose apps may be games or 3D
+scenes. Lamp writes it with the others; say in the rules to load it through an import map (`"three"` to
+`./three/three.module.js`, `"three/addons/"` to `./three/addons/`) from a module script.
+
+`"preview": "Web"` is for a web app: the folder whose `index.html` Lamp opens at 1920x1080 in a window on the person's Mac,
+for the builder to look at and try as it works (a TV app's preview), since the device's own screen can only be pictured,
+not played. Play still puts the app on the device. Give one whenever the app is a web page; the rules should then say the
+app must also work with the keyboard (arrows, Enter, Escape for the device's Back), which is how the preview is used.
+
+`"wrap": "msix"` is for a device that takes Windows app packages (an Xbox in Developer Mode, through its Device
+Portal): the package step leaves a `.zip` of the app's files, and Lamp makes the package itself, writing its manifest
+(started at `start`, `index.html` unless said), its logos from the app's icon, and its signature with a certificate of
+Lamp's. Install it with the package and `"@{certificate}"` in one form, and launch it by `{base64:appUserModelID}` and
+`{base64:packageFullName}`. Never write a manifest or sign anything in the package step. With `"host": "webview2"` beside it, the
+pages are shown in Lamp's own host for Chromium's WebView2 rather than the system's older EdgeHTML: much faster, WebGL 2
+and current JavaScript, with the app's console in its log. Use it for a web app on an Xbox; `start` is then `index.html`.
+
+`"purpose"` says in a few words what the kind is for ("an app with menus and pages"), for a device that takes more than
+one kind. The integrations Lamp ships may offer more kinds beside `app` in `kinds` (the Xbox's native 3D games,
+`{"lamp": "native-game"}`); an integration you write has only `app`.
+
+`"runs"`, beside `app`, says in one plain sentence what the device runs ("Only its own channels, written in BrightScript
+and driven by the remote: no web pages, no 3D"). Lamp gives it as the reason when something the device can't run is asked
+of it, so write it for the person, from the device's documentation.
+
+## Checking it before you send
+
+- Every step has a check that asks the device (or a field the step itself asks for).
+- Every `{…}` is one of Lamp's values above, and a field is only in a sign-in, form, header or body.
+- Titles and lines are short and in plain words, for someone who has never done this.
+- A step written from documentation says where (`known.source`).