@lampdotdev/lamp 0.0.0-stage → 0.35.0

package/Resources/skills/tv-design/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: tv-design
+description: Designing for a TV seen from across the room - type that reads at a distance, the edges a TV may cut off, contrast, focus that's unmistakable, layouts the remote's arrows move through the way they look, what to do instead of typing, glanceable pages, and motion a TV draws smoothly. For any app or game on a TV, web or native. Read before designing or restyling what a TV shows.
+---
+
+# Designing for a TV
+
+A TV is watched from a sofa three meters away, by people who aren't holding a mouse and may not be looking closely.
+Whatever the app is (a game, a family calendar, a photo album, a scoreboard, a remote for something) and however it's
+made, what the TV shows has to read at that distance and be driven with a few keys. Everything here is how to design
+for that; the person's own direction wins over any of it. How a page or an app gets its keys, focus and size is the
+technical guidance's (the TV rules, lamp.js's opening comment, the web-app skill, a native platform's own focus API):
+this skill is about what to do with them.
+
+## Reading at a distance
+
+- Text is large: about 28 px at 1080 lines tall as the smallest anything is (scale it with the screen's height, so
+  about 2.6% of it), headings much larger, and the one or two things that matter largest of all. Short lines; no
+  paragraphs to read.
+- High contrast. A dark background is the default on a TV: it's kinder in a dim room and hides how a TV blooms bright
+  areas. Avoid pure white fills and thin light text on a light ground; avoid fine lines, small icons and detail that
+  depends on color alone.
+- Keep everything that matters inside a margin of about 5% on every side: many TVs cut off their edges. Backgrounds and
+  pictures may run to the edge.
+- Less on the screen than on a desktop: a TV shows a few big things, not a dense layout. Where there's a lot, show the
+  most important part and let the rest be one step away.
+
+## Glanceable pages
+
+A page that's looked at rather than used (a dashboard, a calendar on the wall, a photo frame, a scoreboard, the day's
+weather) reads at a glance: what matters first and largest, details smaller below, nothing that needs choosing to be
+understood. It never scrolls as a whole; a long list scrolls inside its own box, or turns its own pages slowly. It
+stays on for hours, so avoid anything that flashes, and let content move only when it changes (a slow fade between
+photos, a number that updates in place).
+
+## The remote: focus
+
+There's no pointer. The person moves focus with the arrows and presses OK, so:
+
+- What has focus is unmistakable from across the room: a thick outline, or a scale and a glow, never just a slight
+  change of color. Exactly one thing has focus, and something always does when anything can be chosen; when a screen
+  opens, put focus on what the person most likely wants.
+- Lay things out on a clear grid or in rows, so pressing an arrow moves focus where the eye expects. Avoid scattered
+  layouts where "down" is ambiguous.
+- Targets are large and spaced apart; nothing depends on hover.
+- Back always goes back one step, and from the first screen leaves the app. Don't trap the person anywhere without a
+  way out with Back.
+- A dialog keeps focus inside itself until it's closed.
+
+## Typing
+
+Typing with a remote is slow and tiring. Avoid text fields unless the app can't work without one: offer choices to
+pick from, remember what was typed before, or let a phone do the typing (the phone-controllers and phone-pages skills).
+
+## Games on a TV
+
+Everyone on the sofa sees the same screen: the score, lives and prompts are large and near the edges' safe margin,
+not in small corners. Name the controls the way the controller in the players' hands names them. Pause on Back or the
+menu button, with focus on Resume.
+
+## Motion and speed
+
+A TV's browser and processor are far slower than a Mac's. Keep animations few, short and on `transform` and `opacity`
+in a page; avoid large blurs, shadows over big areas and video behind text. Pictures no larger than they're shown.
+
+## Native apps on a TV
+
+The same rules hold: Apple TV apps use the system's focus (focusable views, `.focusSection()` for rows) and its own
+large type styles; an Android TV app uses Compose for TV's focusable cards and rows, keeps everything about 48 dp in
+from the sides and 27 dp from the top and bottom, and body text at 16 sp and up with larger titles. Rows or a grid of
+large cards suit a TV better than long lists. Let the platform draw focus where it does, and make sure your own views
+show it as clearly.

package/Resources/skills/web-app/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: web-app
+description: Apps made as a web page Lamp shows on each device - lamp.js's building blocks (AI, saved data, the app's files, the project's other apps), the remote's focus and keys, what the person's own things need from the app around the page, and what each device's browser runs. Read before writing or changing an app's page.
+---
+
+# Web apps
+
+A web app is one page (HTML, CSS and JavaScript in Web/) that Lamp shows on each device it's on. The same page, so
+write it once for all of them and let each device's differences be handled where they are: lamp.js for what Lamp
+gives every page, a few lines of your own where a device needs something else. How a game's page runs is the game
+skill's; this one is about the page itself.
+
+## Lamp's building blocks: lamp.js
+
+`Web/lamp.js` is Lamp's, written before every build; index.html loads it before the app's own scripts. Read its
+opening comment for the whole list. What it gives:
+
+- **LampAI**: text, pictures and quick judgments, answered by Lamp on the person's Mac with the AI they set up.
+  Every call is a Promise. Text from outside the app goes in `data`, never into the prompt. Where a feature depends
+  on it, check `LampAI.isAvailable('text')` and show a short note when it can't answer: away from the Mac's Wi‑Fi, or
+  with Lamp closed, it can't.
+- **LampAI.act**: the person asks the app to do something in their own words, and the app's own reads and writes do
+  it; "Doing things for the person" below, with **LampVoice** and **LampAI.hear** for saying it.
+- **LampStore**: what the app saves, as JSON on the device. Once something is saved, only ever add to it: a new field
+  gets a default where it's read, and a saved one is never renamed or retyped, because people rely on their data
+  through every change.
+- **LampAssets**: the app's own files that come with it.
+- **Lamp.wish**: the project's other apps (an iPhone, Mac or Android app beside the page), messages and shared values;
+  the wish-links skill says how they share data.
+- **Lamp.controllers** and `Lamp.phonePage`: phones on the same Wi‑Fi as controllers or a second screen; the
+  phone-controllers skill first.
+
+## On the web, without Lamp
+
+Putting it on GitHub (Also put on GitHub, on its link's card) gives a web app a page anyone opens in a browser, with no Lamp anywhere: the page as it is, with
+lamp.js. There, `LampAI.isAvailable` answers false and its calls fail with a sentence saying the page is away from
+Lamp, `LampNative.available` is false, and `Lamp.wish` can't reach the project's other apps; `LampStore` and `LampAssets`
+work as they do everywhere. So every feature that leans on Lamp keeps the app usable without it: the app's own buttons
+for everything AI would do, example content where the person's own things would be, and a short line where something
+needs Lamp, never an error or an empty screen.
+
+## Doing things for the person
+
+`LampAI.act(request, { about, context, tools, history, onStep })` runs a short loop: the AI picks calls among the
+app's tools, the page runs them, the AI sees the results, until it replies (at most 4 AI calls and 6 writes a
+turn, and 25 seconds over OpenRouter or a minute through Claude Code, Codex or a model on the Mac). It works with
+whichever AI the person set up for apps' text, so don't tie it to voice: typing works wherever `act` does. Its comment in lamp.js has the shapes. This is the one recipe for it:
+
+- Show the feature where `LampAI.isAvailable('act')` is true, and keep the app's own buttons for everything: it only
+  adds a way in. Where it's false, keep it visible with a short reason and a way to set it up in Lamp, and keep what
+  was typed; don't send it by itself once setup is done. Whether AI belongs in the app at all, and the contract to
+  write in APP.md, are the app-ai skill's.
+- Tools are small reads and writes over the app's own data, ids in and ids out, never "do anything". A read has
+  `reads: true`; everything else is a write. Nothing destructive (a delete, a clear) without an Undo the person sees.
+- Every write has a `check` that looks its item up again by id and says in a sentence why it can't be done (gone,
+  already done, in the past, nobody of that name); `run` changes the data the way the app's own button does, and
+  returns the item as it is after. Fencing outside text helps the AI read it, but the checks are what hold the line.
+- Make the ids of what a write adds from `call.key`, or keep the key on the change, so the same request made again
+  finds it instead of adding a second.
+- Say what happened from the result's `done`, `failed` and `skipped`, which are what the page ran, never from the AI's
+  `reply`; add the reply only when it asks something (`ask`) or nothing was changed.
+- A question back may come with `choices` (two to four short answers): offer them as buttons with the first focused,
+  and take only the first answer, a button, what was heard or what was typed. With none, it's answered by voice or
+  typing; never guess choices from the question's wording.
+- Keep what each write changed for Undo, and undo only what's still as the write left it; say which ones it left.
+- Show each step while it runs (`onStep`), and cancel the turn (`turn.cancel()`) when the person closes it or the page
+  is hidden.
+- `about` says what the app is and its rules for asking back: which person, which day and time, which of two things
+  that both fit.
+
+Saying it instead of typing it: where the app around the page has a microphone (`LampVoice.status()`, which never
+prompts: the Mac, iPhone and iPad, Android and Android TV, a TV remote's microphone included) and Lamp can transcribe
+(`LampAI.isAvailable('hear')`), `LampVoice.listen({ session, onLevel })` records what's said and `LampAI.hear(audio)`
+turns it into text for `act`. Their comments in lamp.js have the details. The recipe:
+
+- One deliberate press starts listening (opening the app's Ask), never a key that means something else on the remote;
+  show the level as it's heard, a Stop that the opening press can't trigger, and "Type instead" wherever text can be
+  typed. Never hide a typed way in because there's no voice.
+- Float Ask over the page rather than replacing it, and keep the remote in it while it's open (`Lamp.scope`, Tab on
+  the Mac, and arrows consumed at its edges), with something in it always focused, the one the person moved to kept
+  across changes; give focus back to where it was when it closes. A button newly
+  focused ignores OK for a moment, so a held press doesn't press it.
+- Give every recording a session of the page's own, and cancel it (`LampVoice.cancel`) when the person closes or the
+  page hides; drop any recording, transcript or answer that comes back for a session that has ended, and a transcript
+  that comes back after the person has typed or talked again.
+- Act only on `quiet` and `stopped`: `cap` may have cut the person off, so ask them to say it again shorter; say so
+  plainly for `nothing` and `denied`.
+- Read the reply out with `LampVoice.speak`, and listen again for an answer only once it has finished, without moving
+  focus off the choices. Close by itself only after a finished answer read out to the end; any key, press or typing
+  calls that off, and never close over a draft, while a question waits or after a failure.
+
+## The person's own things
+
+A page can't read the person's mail, calendar, contacts, photos or where they are. Where Lamp's app is around the page
+(a Mac, an iPhone or iPad), that app can: register a call in Sources/Native.swift and ask for it from the page with
+`LampNative.call(name, args)`. Elsewhere `LampNative.available` is false and the calls reject, so the page shows
+example content then, never an error. When a web app that's to go on a TV, Android or the Xbox lives on the person's own
+things, say what a page can't reach there; when it needs what only native code does, offer it native (the web-or-native
+skill).
+
+## A remote: focus and keys
+
+On a TV, and anywhere a page is driven by arrows and OK, there's no pointer. lamp.js moves focus with the arrows
+between buttons, links, fields and anything marked `data-focus`, to the nearest in that direction, and OK clicks what
+has it, so most apps need no key code of their own:
+
+- give the first thing to focus with `Lamp.focus(...)` when a screen opens;
+- Back goes back a screen with `Lamp.onBack(fn)` (return true when handled); unhandled on the first screen, it leaves
+  the app;
+- other keys (play, pause, the color keys, numbers) come by name through `Lamp.onKey(fn)`;
+- keep the arrows inside a dialog with `Lamp.scope` while it's open; a game takes them over with
+  `Lamp.navigation = false`.
+
+On a phone or a Mac the same page is tapped or clicked, so a page that works with the remote works there too. How to
+design for the remote and for a TV across the room (what focus looks like, layouts it moves through, typing) is the
+tv-design skill's.
+
+## The browser a page meets
+
+Which devices take a page is `make_app_for`'s table. Where one does, the page meets one of these engines:
+
+| Device | What shows the page | Worth knowing |
+|---|---|---|
+| Mac, iPhone, iPad | Lamp's app around the page (WebKit) | Modern; LampNative reaches the person's things |
+| Android phone or tablet | Lamp's app around the page (Android's WebView, Chromium) | Modern on recent devices |
+| Samsung and LG TVs | The TV's own browser engine | Chromium 108 to 132 on recent models, older on older ones; WebGL 2 not on every Samsung |
+| Android TV, Google TV, Fire TV | Lamp's app around the page (Android's WebView), on the TV's home screen | As on Android phones |
+| Xbox | Lamp's web host (Edge WebView2) | Modern |
+
+A TV keeps the page's syntax to what its older browsers run, as the TV rules say when the app is for one. Designing
+what a TV shows, seen from across a room, is the tv-design skill's.
+
+## Speed
+
+A TV or a cheap phone draws far less than a Mac. Keep animations few and on `transform` and `opacity`, lists that
+scroll in their own box rather than the page, and pictures no larger than they're shown.

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

@@ -0,0 +1,95 @@
+---
+name: web-game
+description: The short guide to a new web game at home on the Mac, on Lamp's game runtime - the runtime's contract, the stage in the window, screens over the canvas, keeping the player's place, how it looks, and what's checked when. Lamp hands it over with make_app_for, with game-feel and the skills the call's `needs` named; for this game they stand in for the game, game-ui, 2d-game and 3d-game skills, which serve games elsewhere.
+---
+
+# A new web game on the Mac
+
+This guide holds how the game runs on Lamp's runtime; game-feel, handed with it, holds what makes it good to play. Both are for every game, and with the skills `needs` named they're what you write it from: don't open the game, game-ui, 2d-game or 3d-game skills, or read Web/lamp-game.js or Web/lamp-phaser.js in full: grep them for one export when you need it. In 2D the game is Phaser 3.90 scenes through `phaser()`. In 3D, game-3d says how it draws; the rest here holds. Write the first files together in one message, then finish: Lamp builds the game and opens it when your turn ends.
+
+## The runtime's contract
+
+- **Files.** Yours are `Web/index.html` (keep its head: lamp.js, the import map, then game.js as a module), `Web/game.js` and modules beside it; delete the scaffold's world.js and making.js with `delete_file` beside your writes. lamp-game.js, lamp-phaser.js, lamp-controllers.js, lamp.js, phaser/, three/, rapier/ and Sources/ are Lamp's: never edit them.
+- **One frame clock.** Phaser's loop is asleep; each of the runtime's frames steps it once. Use a scene's `update(time, delta)` (milliseconds), tweens and Phaser's timers. Never requestAnimationFrame, setTimeout, setInterval, Date, Math.random or localStorage: `random()`, `save(name, value)`, `load(name)`, so the preview replays a play exactly.
+- **Input.** `pad()` merges controllers, keys and touch: `lx ly rx ry` -1 to 1 (up positive), buttons as BUTTON bits in `down pressed released`. WASD and the arrows are the left stick, Space or Enter is A. Phaser's keyboard is off: never `addKey`. Name the controls once in CONTROLS; a prompt uses `label()` or `glyph()` inside `onInput(draw)`, never a key's name. Keys the person named: `keyboardHints: { leftStick: 'arrows' }`.
+- **Sound.** Phaser's is off. Before writing any, `assets` with `kind` sound and `limit` 30 lists every effect: fetch one for each thing the player does or meets, and use the paths it gives. Load each once with `await sound.load('assets/…')` at the top of game.js and `sound.play(s, { volume })` when things happen; `sound.tone({…})` only for what nothing there fits.
+- **Local files.** Nothing comes from the network. Pictures load in `preload`, or are drawn once with `this.make.graphics({ add: false })` and `generateTexture`.
+
+## The stage and the window
+
+The 1920x1080 stage is fitted to the window with black around it, from 480x270 up. Lay everything out in stage units, with the player, HUD and every control inside it, 96 px in from the sides and 54 from top and bottom. Nothing scrolls or zooms, and nothing listens for resize. HTML sizes itself from the stage as `#ui` below does, never in fixed CSS pixels.
+
+## Screens over the canvas
+
+The canvas is `position: fixed`, so anything without a stacking order of its own lies under it. Title, HUD and results live in one `#ui` box over the stage, above the canvas, passing clicks through except on buttons. Lamp's own layers start at z-index 10.
+
+```html
+<style>
+#ui { position: fixed; left: 50%; top: 50%; transform: translate(-50%, -50%); width: min(100vw, 177.78vh); aspect-ratio: 16 / 9;
+      z-index: 5; overflow: hidden; pointer-events: none; font-size: calc(min(100vw, 177.78vh) / 64); color: #fff; }
+#ui button { pointer-events: auto; font: inherit; }
+.hidden { display: none; }
+</style>
+<div id="ui"><div id="title"><h1>…</h1><button id="play">Play</button></div>
+<div id="hud" class="hidden">…</div><div id="results" class="hidden">…<button id="again">Play Again</button></div></div>
+```
+
+```js
+import * as Phaser from 'phaser';
+import { phaser, pad } from './lamp-phaser.js';
+import { BUTTON, STICK, sound, random, save, load, label, onInput, hot } from './lamp-game.js';
+
+const CONTROLS = { move: STICK.LEFT, start: BUTTON.A, pause: BUTTON.MENU };
+const play = hot(import.meta).state('play', { version: 1, start: () => ({ mode: 'title', score: 0, left: 30, x: 960 }) });
+const catchSound = await sound.load('assets/pack/coin.wav');   // the page path `assets` gave
+const el = id => document.getElementById(id);
+
+class Main extends Phaser.Scene {
+    constructor() { super('main'); }
+    create() {                                     // the one start: it reads the state and shows that screen
+        this.ship = this.physics.add.sprite(play.x, 940, 'ship').setCollideWorldBounds(true);
+        el('play').onclick = el('again').onclick = () => this.begin();
+        this.show();
+    }
+    begin() { Object.assign(play, { mode: 'play', score: 0, left: 30 }); this.show(); }
+    end() { play.mode = 'over'; save('best', Math.max(load('best') ?? 0, play.score)); this.show(); }
+    show() { for (const [id, mode] of [['title', 'title'], ['hud', 'play'], ['results', 'over']]) el(id).classList.toggle('hidden', play.mode !== mode); }
+    update(time, delta) {
+        const p = pad(), dt = delta / 1000;
+        if (play.mode !== 'play') { if (p.pressed & CONTROLS.start) this.begin(); this.ship.setVelocityX(0); return; }
+        this.ship.setVelocityX(p.lx * 900); play.x = this.ship.x;
+        if ((play.left -= dt) <= 0) this.end();
+    }
+}
+phaser({ scenes: [Main], physics: { default: 'arcade' }, busy: () => play.mode === 'play' });
+```
+
+## The flow
+
+Title, play, results, unless the request plainly suits another opening; keep it in a `Flow:` line in APP.md. The title has the name and one big Play; a click or A starts it, and it names no key or control: those come after the press, briefly, as the round begins. The HUD stays large through play. Results say what happened first, then Play Again, which goes straight into a round. Play and Play Again are really in view and clickable.
+
+## Keeping the player's place
+
+Changes go into the running game, and these rules keep the player's place through every one; game-live is for a change that moves the game's structure. Everything that says where the game is goes in the one `state` object, plain data: change its fields, never replace it. `create` reads it and builds that place, with no title over a game under way. HUD and menus are found at each start, never at a module's top level, and `busy()` is true while a round is on.
+
+## How it looks
+
+Decide before drawing: its world, one material its screens are made of, four to eight colors, one signature motion. Compose each screen for this game, not a centered stack of pills, emoji art or soft cards on a gradient. Every action answers at once in sight and sound, each with a short effect from the `assets` tool. The finished look in game-feel is the bar every screen meets. The HTML above shows how screens layer over the canvas and follow the state, not a finished design: style it for this game, keeping the fixed stage and the black around it.
+
+## What's checked, and when
+
+Lamp checks the game itself: its code parses, it builds, and it opens without crashing. A failure there comes back to you to fix, as another step. Lamp also tells the person whether its window drew. So write the change and finish, with no `look_at_app` or `use_app`, and nothing in the shell that plays, screenshots or runs the game in its place. Your last reply says in a sentence what you made; whether it's open and drew is Lamp's to say, after your reply, so never say it's built, open, working or tested.
+
+When the person asks you to play it, test it, check it or judge how it looks, open the game-playtest skill and do only what they asked. One such request doesn't reach the changes after it.
+
+## More, when the game calls for it
+
+What a game needs beyond this and game-feel follows from its mechanics and how it's drawn, not from the words of the request. The skills `make_app_for`'s `needs` named came with this guide; one the game turns out to need, now or in a later request, open with `read_skill` then. Most games need none.
+
+- **game-3d**: it's drawn in 3D, a world with depth and a camera in it.
+- **game-physics**: things move as bodies, falling, rolling, stacking, tilting, bouncing off each other. Steering, simple gravity and what touches what don't need it.
+- **game-levels**: more than one level or stage, unlocks and a level select, a menu that's a place.
+- **game-art**: the person asked for a look, or the game is mostly its look.
+- **2d-game**: tilemaps, a scrolling world, sprite-sheet animation.
+- **game-live**, never in `needs`: open it when a change to the open game moves its structure (new or split modules, a world that streams, what has to last renamed or moved) or won't go in. A color, a number or text needs only the rules above.
+- **assets**: choosing between packs.

package/Resources/skills/web-or-native/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: web-or-native
+description: Choosing how an app or game is made - as a web page Lamp's host shows on each device, or in the device's own code - from the default the table of devices gives (web wherever Lamp has a host for a page), the few things only native code does (a menu bar icon, widgets, Siri and Shortcuts, Health, share sheets), and on which devices, when to ask the person and what to tell them. Read before the first make_app_for of a project, and before changing how an app is made or adding a device.
+---
+
+# Web or native
+
+Every app and game Lamp makes is made one of two ways:
+
+- **Web**: one page (HTML and JavaScript) that Lamp's host shows on each device, the same page everywhere it goes.
+- **Native**: the device's own code. Swift for Apple's devices (one code for all of them), Kotlin for Android, and
+  what an integration declares for its device.
+
+`make_app_for`'s description has the table of devices: what each one runs, and how a build gets onto it. It refuses
+a make Lamp can't build on a device, with the reason, and the request's device line says what Lamp knows of the
+person's own devices. Those are the facts, and the only place they're kept; this skill doesn't repeat them.
+
+## The default
+
+A page is where every app and game starts. When the person names no make, an app or a game is **web** wherever Lamp
+has a host for a page: a Mac, an iPhone or iPad, an Android phone or tablet, a Samsung or LG TV, an Android TV and an
+Xbox. Where there's none (an Apple TV, an Apple Watch, a Roku), it's native. A game is on Lamp's game runtime (the game
+skill says what it's drawn with). One app across several devices is web where every one of them takes a page.
+
+A web app is one page that goes anywhere: the person can open it on another device later without it being written
+again, and putting it on GitHub gives it a link anyone can open in a browser without Lamp. On a Mac, an iPhone or an iPad the app around the page still reaches
+the person's mail, calendar, reminders, contacts, photos and location (`LampNative`, the web-app skill).
+
+Make it **native** only when it needs something a page can't be:
+
+- a Mac app that lives in the menu bar (the menu-bar skill), takes files from Finder (the finder-files skill), or is a
+  utility that works where the person already is or in the background (a global shortcut, the selection in another
+  app, opening at login: the app-kinds skill);
+- widgets, Live Activities or Control Center controls (the mac-widgets and iphone-widgets skills), or an Apple Watch
+  app (the apple-watch skill);
+- its actions in Siri, Shortcuts, Spotlight or the Action button (the app-intents skill), or a place in the share
+  sheet (the share-extension skill);
+- Apple Health, iCloud sync, work while an iPhone app is closed, or the phone's hardware beyond what a page has (the
+  iphone-hardware and icloud-sync skills);
+- 3D in Swift with RealityKit (the scene-3d skill), or a game inside an Apple thing (Game Center, a widget).
+
+When one of these is part of what was asked, choose native and say why in a sentence. When the person asks for one
+later in an app made web, say what it needs, and offer to make it native.
+
+The default is where you start, not a limit:
+
+- **A make the person names is theirs.** When they ask for a web app, or a native one, make it that way wherever Lamp
+  can build it; say in a sentence what that costs only when it matters.
+- **Nothing switches silently.** Devices found on the network aren't a request for one app across them: add a device
+  only once the person has said that's what they want, or answered so when you asked.
+- **An app the project has is never converted to follow the default.** It's for a new app, and for a change the person
+  asks for. An app made native before keeps its make.
+- **Separate apps that talk don't need the same make.** The project's apps reach each other through `LampWish` on
+  whichever devices they're on, however each is made (the wish-links skill).
+- **Never choose a make to get around a limit of Lamp's**: two apps of one code in one project, say (the more-apps
+  skill). Say what the limit is instead, and offer what can be done.
+- **Never refuse a make that works only because it isn't the default.** Only the table, and the refusal it gives,
+  says what can't be built.
+
+## What to weigh
+
+- **What the app needs from the device**: the list above. A page reaches the person's things only through Lamp's app
+  around it, where there is one (`LampNative`, the web-app skill): on a TV, Android or the Xbox it shows example content
+  instead. A game made native for an Apple thing is SpriteKit for 2D: say that it then stays on Apple's devices, where
+  a game on the runtime can go to Android, a TV, the Xbox or the web later without being written again.
+- **How it gets to the people who use it.** Read the table's way onto each device, for each make. On some devices a
+  page still comes inside an app of Lamp's that is installed the same way a native app is.
+- **Whose devices, and how many.** One person's own Mac or phone, a family's TV, every phone at a party: who has to
+  install or open what.
+- **What it's played or used with.** A remote, a controller, touch, phones in the room: the game skill and the
+  phone-controllers skill say what each takes.
+
+When the app needs several devices, it can be one app on all of them, or several of the project's apps, each made for its
+device, that talk through `LampWish`. Adding one more app to a project that has one is the person's to choose: the
+more-apps skill says how to ask.
+
+## When to ask
+
+Only when the answer really changes what you'd make, and only in one line about people and devices, never in the
+words "web" or "native": "Is this for your iPhone, or for everyone's phones at the party?" When the request already
+says, or a wrong guess is cheap to change, choose, build, and say in a sentence what you chose and how it gets onto
+their devices.
+
+## Saying how it gets there
+
+Tell the person how the build reaches each device, as `make_app_for` answers it ("each phone is paired with this Mac",
+"each phone joins the TV's game by a link"), so a choice that doesn't suit them shows at once.
+
+## Away from home
+
+Each way of connecting has its own reach, said where it's described: phones joining a TV app's page do it on the same
+Wi‑Fi with Lamp open on this Mac, and a game's on the Mac with Lamp open or closed (the phone-controllers skill); the project's own apps find each other on the home
+network, and once Lamp has introduced them go on talking with Lamp closed (the wish-links skill, which also says what
+reaching each other away from home takes). Lamp runs no relay of its own for players in other homes: when that's what
+the person wants, say so plainly, and offer what works (playing on one Wi‑Fi, or another way of connecting, as the
+wish-links skill says).
+
+## Changing it later
+
+`make_app_for` with an app's folder in `app` changes how that app is made: it keeps its folder and what it saved, but
+the new code doesn't read what the old one saved unless you write it to, and Lamp moves nothing across, so say so when
+it matters. One more app beside the others is `another`, only once the person chose that when you asked (the
+`more-apps` skill). `remove_app` takes one away, which the person can undo.

package/Resources/skills/wish-links/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: wish-links
+description: How the apps of a project, and one app open on several devices at once (two iPhones, a screen on an iPad and a TV), share data and send each other messages - Lamp's LampWish block and the shared collections built on it (LampStore.shared, LampStore.sharedFiles) for the same data on every device, what to do while another app of the project isn't made yet, and when another way fits better. Read before writing how they reach each other.
+---
+
+# The apps of a project, talking to each other
+
+A project of several apps (a Mac app and an Android app, a TV app and an iPhone app, a game and the phone app that
+sends it things to play with, a screen on the wall and the app that fills it) usually needs them to share something:
+a score, a list, a "next" button. So does one app open on several devices at once: the same app on two iPhones, or a
+screen shown on the kitchen iPad and the TV. There's more than one way to do it. Lamp gives every app one way built
+in, `LampWish`, and it's the one to use unless the wish or the person calls for another.
+
+## LampWish, built in
+
+Every app of the project has it, the same in each language: `LampWish.shared` in LampSupport.swift, `LampWish` in
+LampSupport.kt, `Lamp.wish` in lamp.js (a TV app's page, a game's and a screen's, in Web/lamp.js). Read the block's
+own comment there before using it.
+
+- Each app of the project is a peer named by its folder in the project, lowercased: "tv", "iphone", "apple" (an app for
+  iPhone and Mac), "mac", "android", "game", "screen".
+- `peers` lists the project's other apps that are open now (observable: @Published, a StateFlow, onPeers).
+- `peer("tv")` is that app, open or not, with its `status`: `state`, a `reason` in words to show as they are ("Open
+  the TV app on your TV.", "The TV app was last open 5 min ago. Open it on your TV.", "The TV app isn't ready yet."
+  for one Lamp hasn't made) and `lastSeen`. Every app the project asks for is there, even one not made yet. A reason
+  changes as time goes by: watch every app's (`apps`, observable as `peers` is; `onApps` in lamp.js), not only the open
+  ones.
+- `send(data, to: "tv")` sends JSON of 16 KB at most to one of them, `send(data)` to all; false, with why in the app's
+  log, when it wasn't sent. `onMessage { from, data in … }` hears what they send. A message is for apps open now.
+- `sendFile(data, name: "photo.jpg", type: "image/jpeg", to: "tv")` (`Lamp.wish.sendFile(data, 'iphone', { name,
+  type })` in lamp.js) sends a file of up to 64 MB to one app open now, two at a time to each; the transfer it gives
+  says how far it's got and why it failed, and can be cancelled. `onFile { from, file in … }` hears the files they send,
+  whole. Like a message, a file is for an app open now.
+- `values` is a small map of JSON every app of the project keeps on its device (each value 8 KB at most, all of them
+  64 KB). `set("list", value)` sets one here and in the others, at once if they're open or when they next meet; nil
+  (null) removes it. `onChange { key, value, from in … }` hears every change, this app's own included. Where two apps
+  set one while apart, the later setting wins in both.
+- `LampStore.shared` and `LampStore.sharedFiles` (below) keep lists and files the same on every copy of the app.
+- The app's own `status` says how its link stands, with a `reason` when something keeps it from the others (on a Mac
+  or iPhone, `localNetworkDenied`: the person turned off Local Network for it). An open app built by an earlier Lamp is
+  `outOfDate`: still open, with a reason saying to open it from Lamp. More states may come: treat any you don't name as
+  not connected.
+- An app can be open on several devices at once (a screen on the kitchen iPad, the TV and a photo frame, the same app
+  on two iPhones), in a project of one app as in a project of several: each is a copy of it, and every copy reaches the others and keeps the same `values`. `peer("screen").copies` lists where it's
+  open now (`id`, `device`, `since`); another copy of this same app shows in `peers` while it's open. A message to an app
+  goes to every copy of it; a file goes to one copy, the one opened last unless `to` names a copy's `id`. The third
+  argument of `onMessage` (`copy`) and `file.copy` say which copy sent it, to answer that one alone. Put what every
+  screen shows in `values`, so a copy opened later catches up by itself. An app with no other app in its project is
+  `alone` until another copy of it opens; its copies first meet through Lamp on the Mac, and after that also reach
+  each other straight with Lamp closed.
+- Where a copy can't reach the others, `Lamp.wish` is `away`, with a reason saying so. Write the sharing the same way
+  for every place, and keep the game or screen whole without it.
+- A Roku app (an app for a device through its integration) can't reach the others yet, nor they it: it's not in the
+  room's list, so the others don't see it at all, and its own `LampWish` (LampWish.brs) is always `away`. Don't write
+  the others to wait for it or send it anything; each keeps what it shows its own. An app on the Mac or an iPhone can
+  still steer it as a remote with `LampRoku` (keys, opening it by launching "dev"), which needs no link.
+- `LampWishStatus()` (SwiftUI, Compose) and `Lamp.wish.statusView()` (lamp.js) show all of that ready-made, a line
+  for each other app, or one app's line with its peer name. Use them, restyle them, or show the statuses your own way.
+
+## The same data on every device: shared collections
+
+When one app is open on several devices (a screen on the Mac, the kitchen iPad, the TV and an Android photo frame) and
+each should show the same shopping list, chores, calendar or photos, keep that data in a **shared collection**, not
+in `values`:
+
+- `LampStore.shared("groceries", of: Grocery.self)` in Swift (an ObservableObject: `items`, `put`, `get`, `delete`,
+  `publish`, `onChange { id, item, from in }`), `LampStore.shared<Grocery>("groceries") { it.id }` in Kotlin (`items`
+  is a StateFlow), `LampStore.shared('groceries')` in lamp.js (items are objects with an `id`; `all()`, `put`, `get`,
+  `delete`, `publish`, `onChange(fn(id, item, from))`). Each copy keeps the items on its device and works alone; copies
+  merge them item by item whenever they meet, through Lamp or straight on the home network with Lamp closed. While Lamp
+  runs on the Mac it keeps every shared collection too, so a copy that opens when no other is open still gets the
+  latest, and what it changes then reaches the others when they open. Lamp is never one of the copies or apps. Two copies
+  that changed different items while apart both keep both; where two changed the same item, the later change wins in
+  both; a deleted item stays deleted. An item is at most 8 KB as JSON, everything the app shares at most 1 MB
+  (thousands of small items).
+- Give each item a stable id of its own (a UUID made when it's added, or the id of what it stands for, such as a
+  calendar event's), and keep things that change apart in separate items: a list's items, not the list as one.
+- `publish(items)`, for what one copy can read and the others can't (the Mac's or the iPad's calendars, through
+  `LampNative` on a screen or a game): this copy's items become exactly these; unchanged ones cost nothing, and items
+  other copies put are left alone. Publish again each time it's read.
+- `LampStore.sharedFiles("photos")`: files kept on every copy (`put(name, data, type)`, `get(name)`, `url(name)`,
+  `files`/`all()` with whether each is here yet, `delete`, `onChange`). A copy that can read the album puts each
+  picture; every other copy fetches the bytes from a copy that has them or from Lamp, including copies that open later. 64 MB a
+  file, 256 MB in all. On a TV the bytes are kept in memory and fetched again each time the app opens.
+- Draw from the collection and redraw on `onChange`; never keep a copy of your own. Never split a list into `values`
+  by hand, or send the same data around with messages to keep copies in step.
+- A shared collection is the app's own, the same on all its copies, unless it's the **project's own**: with
+  `wish: true` (`LampStore.shared("events", of: Event.self, wish: true)` in Swift,
+  `LampStore.shared<Event>("events", wish = true) { it.id }` in Kotlin, `LampStore.shared('events', { wish: true })`
+  in lamp.js, and `sharedFiles(name, wish: true)` likewise) every app of the project keeps it the same: a Mac app and the
+  iPhone app beside it sharing one calendar, a TV game and the phone controllers sharing a scoreboard. Every app that
+  uses it gives the same name. It merges as above; each app's 1 MB counts only the items it set last.
+  Use the project's own collection whenever different apps of the project show the same records; never make one app the
+  keeper of them for the others, since that app is often closed or asleep.
+- A collection starts empty: the project's own and the app's own of the same name are separate, so switching a list to
+  `wish: true` doesn't bring its items along. When the person already has items there, copy them over.
+- Apps that share a collection agree on what an item looks like: the same fields with the same meaning. Add a field
+  as optional, so an app that doesn't know it yet still reads the item, and change every app that uses the collection
+  together.
+
+What it gives: the apps find each other on the home Wi‑Fi with nothing to sign up for, pair, host or pay for. While
+Lamp is open on the Mac it introduces them; with Lamp closed, the Mac asleep or Lamp updating they go on talking
+straight to each other on the same network. What they say is sealed with a key only the project's apps have, and none of
+it leaves the home network. What it doesn't do: reach an app on another network (a phone away from home), keep a
+message or a file for an app that isn't open, or hold more than a small amount in `values`.
+
+How to use it well:
+- Start it as each app opens.
+- Pick by what the data is. Something that happens now (a button pressed, "next round") is a message. A list or
+  records every copy of this app shows (groceries, chores, events, photos) is a shared collection, and the project's own
+  (`wish: true`) when the project's other apps show them too. Something another
+  app of the project should still see after being closed (a score, a setting, what's on the dashboard) fits `values`:
+  they catch up by themselves when they meet, so there's nothing to resend. Something big the other app should have
+  (a photo, a recording, a document, a game to play) is a file: send it when that app is open, show its progress, and
+  say so plainly when it fails. The app's own records belong in its own store (LampStore), with only what the other app
+  needs to show put in `values`.
+- Draw from `values` and redraw on `onChange`, rather than keeping a copy of your own that can drift. What an app kept
+  on its device can reach `values` a moment after it opens (on a TV, once it knows its project), so never set a default
+  because `values` looks empty at launch: show an empty state, and set a value when the person does something.
+- Keep values to a few names you reuse. Each name counts at least 32 bytes against the 64 KB, and a removed one keeps
+  counting for a month, so values aren't a queue of ever-new names: keep such records in the app's own store.
+- Several apps may change the same value while apart, and the later setting wins whole. Where both sides add to one
+  list, use a shared collection: the app's own between its copies, the project's own (`wish: true`) between different
+  apps, so neither undoes the other's.
+- Watch `peers` as it changes (onChange of it, collecting the StateFlow, onPeers), not by looking now and then: an app
+  closed and opened again quickly leaves and comes back between two looks.
+- Where something needs another app, show why it isn't there with its `reason` (or the status view), and keep every
+  control usable while it isn't open.
+- Never build a server, sockets, polling or pairing of your own beside it, and never put the app's token or Lamp's
+  addresses in the code.
+
+## While another app of the project isn't made yet
+
+A project can ask for an app this Mac can't build yet (Google's tools aren't set up, Xcode is missing). Lamp says which
+at the end of the request and makes it as soon as it can. The app you're building already has `LampWish`, and the
+missing one is in its list, not open. So:
+- Write the sharing with `LampWish` now, as if the other app were there. When it's made it has the same block, and the
+  two find each other with nothing more to do.
+- Until then show its `reason` where it matters, and make this app whole and useful on its own.
+- Don't stand in for the missing app with an online service, or leave the sharing out "for later".
+
+## When another way fits
+
+`LampWish` is the default, not the only way. Use another when:
+- **The person asks for one**: Tailscale, ntfy, their own server or database, a service they already pay for. Do it
+  their way.
+- **The apps must reach each other away from home**, not just on the same Wi‑Fi. For the Mac and the iPhone of one
+  person, iCloud (the icloud-sync skill) keeps their data the same anywhere. Anything else is a service outside the
+  home: ask first, with one `ask`, when it needs an account, costs money or sends the person's data off their network,
+  and say what that means in plain words.
+- **Both are needed**: `LampWish` at home for what's instant, and a service or iCloud for what must reach a device
+  away.
+
+A public relay such as an ntfy.sh topic is readable by anyone who guesses the topic's name: don't send anything
+personal through one in the clear, and tell the person. Whatever way you choose, keep it in one place in each app's
+code, so it can be changed later without touching the rest.