@lampdotdev/lamp 0.0.0-stage → 0.35.0

package/cli/share.mjs

@@ -0,0 +1,202 @@
+// A link to the page on lamp.dev: anyone who opens it plays the page there, and can send its maker an idea. The page
+// zipped as the site takes it, then the link's words and picture and the page sent in parts, through the site's API
+// as link.mjs speaks it (the same for Lamp's app's Share Link card).
+//
+// The link's secret, which is what lets it be changed or taken down, is kept with lamp's own state for the folder,
+// never in the folder: a folder is committed and published, and the secret is whoever shared it's alone.
+
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { deflateRawSync } from "node:zlib";
+import { Problem, stateOf } from "./state.mjs";
+import { ANY_BROWSER, CONTROLLERS, CONTROLLERS_FILE, DEVICE_FILE, lampJS, LIBRARIES } from "./dev.mjs";
+import { LIMITS, FILE_LIMITS, PAGE_LIMITS } from "../site/lib/shared-wishes.js";
+import { ideasOf, publishLink, removeFile, removeIdea, removeLink, sendFile, siteOrigin } from "./link.mjs";
+import { exportApp } from "./lampapp.mjs";
+
+export { siteOrigin };
+
+const linkFileOf = (folder) => join(stateOf(folder), "link.json");
+
+/** The folder's link, as it was last shared: its address, its secret and the words it went out with. */
+export function readLink(folder) {
+  try { return JSON.parse(readFileSync(linkFileOf(folder), "utf8")); } catch { return null; }
+}
+function writeLink(folder, link) {
+  mkdirSync(stateOf(folder), { recursive: true });
+  writeFileSync(linkFileOf(folder), JSON.stringify(link, null, 2), { mode: 0o600 });
+}
+
+// MARK: The page, as a zip
+
+const CRC = Array.from({ length: 256 }, (_, n) => { let c = n; for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1; return c >>> 0; });
+function crc32(bytes) {
+  let c = 0xffffffff;
+  for (let i = 0; i < bytes.length; i++) c = CRC[(c ^ bytes[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+/** A zip of these files (`[path, bytes]`), each packed where that makes it smaller. */
+export function zipOf(files) {
+  const parts = [], listing = [];
+  let offset = 0;
+  for (const [path, bytes] of files) {
+    const name = Buffer.from(path, "utf8"), packed = deflateRawSync(bytes), stored = packed.length >= bytes.length;
+    const data = stored ? bytes : packed, sum = crc32(bytes);
+    const head = Buffer.alloc(30);
+    head.writeUInt32LE(0x04034b50, 0);
+    head.writeUInt16LE(20, 4);
+    head.writeUInt16LE(0x0800, 6);              // the name is UTF-8
+    head.writeUInt16LE(stored ? 0 : 8, 8);
+    head.writeUInt32LE(sum, 14);
+    head.writeUInt32LE(data.length, 18);
+    head.writeUInt32LE(bytes.length, 22);
+    head.writeUInt16LE(name.length, 26);
+    const entry = Buffer.alloc(46);
+    entry.writeUInt32LE(0x02014b50, 0);
+    entry.writeUInt16LE(20, 4);
+    entry.writeUInt16LE(20, 6);
+    head.copy(entry, 8, 6, 30);                 // the same flags, method, sum, sizes and name length
+    entry.writeUInt32LE(offset, 42);
+    parts.push(head, name, data);
+    listing.push(entry, name);
+    offset += 30 + name.length + data.length;
+  }
+  const directory = Buffer.concat(listing), end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0);
+  end.writeUInt16LE(files.length, 8);
+  end.writeUInt16LE(files.length, 10);
+  end.writeUInt32LE(directory.length, 12);
+  end.writeUInt32LE(offset, 16);
+  return Buffer.concat([...parts, directory, end]);
+}
+
+/**
+ * Every file of the page as it's played from the link: what's in its folder (nothing hidden, no link followed, the
+ * app's notes left out), and for a game Lamp's own files beside it, as Lamp's app puts them in a copy it publishes
+ * (`GamePage.stage`): the device a browser on any device is, the build's name, and what the folder has none of.
+ * A copy for one device (place.mjs) is given that device in its place.
+ */
+export function pageFiles(layout, { device = ANY_BROWSER } = {}) {
+  const files = new Map();
+  const walk = (dir, prefix) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const path = prefix + entry.name;
+      if (entry.name.startsWith(".") || entry.name === "node_modules" || path === "APP.md") continue;
+      if (entry.isDirectory()) walk(join(dir, entry.name), path + "/");
+      else if (entry.isFile()) files.set(path, readFileSync(join(dir, entry.name)));
+    }
+  };
+  walk(layout.root, "");
+  if (layout.game) {
+    files.set(DEVICE_FILE, Buffer.from(device));
+    if (!files.has(CONTROLLERS_FILE)) files.set(CONTROLLERS_FILE, readFileSync(CONTROLLERS));
+    if (!files.has("lamp.js")) files.set("lamp.js", Buffer.from(lampJS(true)));
+    // A library the page's import map names from beside it and the folder has none of: Lamp's copy.
+    const map = /<script[^>]*type=["']importmap["'][^>]*>([\s\S]*?)<\/script>/i.exec(String(files.get("index.html") ?? ""))?.[1] ?? "";
+    for (const name of ["three", "phaser", "rapier"]) {
+      if (!new RegExp(`:\\s*["'](?:\\./)?${name}/`).test(map) || [...files.keys()].some((path) => path.startsWith(`${name}/`))) continue;
+      const from = join(LIBRARIES, name);
+      if (!existsSync(from)) continue;
+      const copy = (dir, prefix) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+          if (entry.isDirectory()) copy(join(dir, entry.name), `${prefix}${entry.name}/`);
+          else if (entry.isFile() && !lstatSync(join(dir, entry.name)).isSymbolicLink()) files.set(prefix + entry.name, readFileSync(join(dir, entry.name)));
+        }
+      };
+      copy(from, `${name}/`);
+    }
+    // The build's name, for the runtime to tell a newer copy of the game by: named for the files as they are.
+    files.delete("lamp-build.js");
+    const hash = createHash("sha256");
+    for (const path of [...files.keys()].sort()) hash.update(path).update(files.get(path));
+    files.set("lamp-build.js", Buffer.from(`export default "${hash.digest("hex").slice(0, 16)}";\n`));
+  }
+  return [...files].sort(([a], [b]) => a.localeCompare(b));
+}
+
+// MARK: The site
+
+const megabytes = (bytes) => `${(bytes / 1_000_000).toFixed(bytes < 10_000_000 ? 1 : 0)} MB`;
+
+/**
+ * Shares the page, or sends it again to the link the folder has: the link's words and picture, then the page. `words`
+ * are what the link says (`name`, `words`, and `line`, `by` and `asks` when given), `picture` a PNG or JPEG of the
+ * page or null, `shape` "fill" or the page's width over its height. Answers the link and what went up.
+ */
+export async function share({ layout, words, picture = null, shape = "fill", site = siteOrigin(), said = () => {}, file = true, anyway = false }) {
+  // The app's own file goes with the link, as Lamp's Share Link sends it, so whoever follows the link can open it in
+  // Lamp too: made first, with Share…'s checks, so a page that can't be shared (a key in it) puts nothing up.
+  const app = file ? exportApp(layout.folder, { anyway }) : null;
+  const files = pageFiles(layout);
+  const unpacked = files.reduce((total, [, bytes]) => total + bytes.length, 0);
+  if (!files.some(([path]) => path === "index.html")) throw new Problem("the page has no index.html at its top");
+  if (files.length > PAGE_LIMITS.files) throw new Problem(`the page is ${files.length} files, and a link carries ${PAGE_LIMITS.files} at most`);
+  if (unpacked > PAGE_LIMITS.total) throw new Problem(`the page is ${megabytes(unpacked)}, and a link carries ${megabytes(PAGE_LIMITS.total)} at most`);
+  const zip = zipOf(files);
+  if (zip.length > FILE_LIMITS.total) throw new Problem(`the page is ${megabytes(zip.length)} packed, and a link carries ${megabytes(FILE_LIMITS.total)} at most`);
+  if (picture && picture.length > LIMITS.picture) picture = null;
+
+  const body = {
+    name: words.name, words: words.words, shape,
+    ...(words.line ? { line: words.line } : {}), ...(words.by ? { by: words.by } : {}),
+    ...(words.asks?.length ? { asks: words.asks } : {}), ...(picture ? { picture: picture.toString("base64") } : {}),
+  };
+  // The folder's own link when it has one on this site, changed in place; a link that's gone is made again.
+  let earlier = readLink(layout.folder);
+  if (earlier && earlier.site !== site) earlier = null;
+  // A file an earlier share sent stays on the record until it's taken away, so a retry after a failed removal tries again.
+  let link = { site, ...(await publishLink({ site, body, earlier })), ...words, shape, ...(earlier?.file ? { file: true } : {}) };
+  // Kept before the page goes up: a link whose page didn't make it is still this folder's to send again or take down.
+  writeLink(layout.folder, link);
+
+  // The file, or none: a link that carried one and shouldn't now has it taken away (and its page with it, sent next).
+  if (app) {
+    link.file = true;
+    writeLink(layout.folder, link);
+    await sendFile({ site, link, bytes: app.bytes, said });
+  } else if (link.file) {
+    await removeFile({ site, link });
+    link.file = false;
+    writeLink(layout.folder, link);
+  }
+  const version = await sendFile({ site, link, bytes: zip, page: true, said });
+  link = { ...link, version, shared: new Date().toISOString() };
+  writeLink(layout.folder, link);
+  return { url: link.url, version, files: files.length, bytes: zip.length, picture: !!picture, file: !!app };
+}
+
+/** Takes the folder's link down, with its page and the ideas sent to it. */
+export async function unshare(folder) {
+  const link = readLink(folder);
+  if (!link) throw new Problem("this folder has no link");
+  await removeLink({ site: link.site, link });
+  rmSync(linkFileOf(folder), { force: true });
+  return link.url;
+}
+
+/** The ideas people playing the link have sent its maker and that are still open: each with its number. */
+export async function ideas(folder) {
+  const link = readLink(folder);
+  if (!link) throw new Problem("this folder has no link: lamp share makes one");
+  return { url: link.url, ideas: await ideasOf({ site: link.site, link }) };
+}
+
+/** Says what became of an idea: it's in (the site writes to whoever asked to hear), or it's let go. */
+export async function finishIdea(folder, n, built) {
+  const link = readLink(folder);
+  if (!link) throw new Problem("this folder has no link");
+  return removeIdea({ site: link.site, link, n, built });
+}
+
+/** The page's name where nothing gave one: its title, or its folder's name. */
+export function nameOf(layout) {
+  try {
+    const title = /<title[^>]*>([^<]*)<\/title>/i.exec(readFileSync(join(layout.root, "index.html"), "utf8"))?.[1]?.trim();
+    if (title) return title.replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').slice(0, LIMITS.name);
+  } catch {}
+  return basename(layout.folder).slice(0, LIMITS.name);
+}
+
+export { LIMITS };

package/cli/skill/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: lamp
+description: Make, run, see and try an app with lamp's command line - a web app, a web game, or a Mac app Lamp made in Swift. Use when the person asks for a new web game, or when working in a folder made with Lamp (a page beside lamp-game.js or in Web/, or Package.swift with build.sh and Sources/LampSupport.swift) or in a plain site's folder and they ask to change the app, to see it, or to check that a change works. Every saved change goes into the open app, and a game keeps the player's place.
+---
+
+# Working on an app with lamp
+
+`{{lamp}}` runs the page in the app's folder and puts each change into it while it's open. Save a file and the change
+goes in. Never build, restart or reload anything for a change.
+
+Run the commands from the app's folder, or give the folder after the command (`{{lamp}} look path/to/app`).
+
+Most of this is about an app that is a web page: a web game, a web app, a plain site. An app Lamp made that way has
+the page in `Web/`, beside the Swift of the app around it, which stays as it is. An app whose own screens are Swift
+is a Mac app: "A Mac app" below says what's different for one.
+
+## A new game
+
+`{{lamp}} new path/to/folder --name "Its Name"` makes a new web game's folder from Lamp's starting files: the game
+runtime (`lamp-game.js`), three.js and Phaser, `APP.md`, and a page that shows a card until the game replaces it. The
+page is at the top of the folder: what Lamp's skills call `Web/` is the folder itself.
+
+Before writing, read Lamp's `web-game` and `game-feel` skills, which are for every game, and `game-playtest` when
+you're asked to play it; "Lamp's skills" below says what in them is Lamp's app's doing. The card's `game.js`,
+`world.js` and `making.js` are yours to replace, as `web-game` says.
+
+The card is a small game of its own, and the runtime keeps what it registered (a state called `play`, a camera)
+through a change, as it would the player's place. So write the whole game before the first look, and make that look
+with `--reopen` (`{{lamp}} look --reopen`): the game then opens from its beginning, not from the card's. If you
+looked earlier, `--reopen` puts it right.
+
+## A new web app
+
+`{{lamp}} new path/to/folder --web --name "Its Name"` makes a new web app's page from Lamp's starting files:
+`index.html`, `style.css` and `app.js`, which are yours to write, `APP.md`, and `lamp.js`, Lamp's building blocks for
+a page (saved data with `LampStore`, the app's files and more). Read Lamp's `web-app` skill before writing it, and
+the comments in `lamp.js` for how each block is used; never edit `lamp.js`. What a block asks of Lamp's app as the
+page runs (its AI) isn't answered here. A page that wants none of Lamp's needs no starting files: write its
+`index.html` in an empty folder.
+
+## A Mac app
+
+A folder with `Package.swift`, `build.sh` and `Sources/LampSupport.swift` and no page is a Mac app Lamp made in
+Swift. `{{lamp}} new path/to/folder --mac --name "Its Name"` makes a new one: Lamp's building blocks, and a card it
+shows until its code in `Sources/` is written. The same commands work on it, with these differences:
+
+- **Lamp's building blocks** are what the app is made with: saved data, AI, windows, the menu bar and the rest.
+  `{{lamp}} blocks` lists them with what each is for, and `{{lamp}} blocks LampStore` says how one is used: read the
+  ones the app needs before writing it. Lamp's `building-blocks` and `app-kinds` skills say which to reach for and
+  how such an app is laid out; where a skill points to rules of Lamp's own that aren't here (a base design), use
+  your judgment.
+- **A change is a build.** Each save to the app's code builds it again, a few seconds for a small change, and opens
+  it again: what was typed or open in it is gone, so change first and try after. `look` waits for the build.
+- **`look`** answers pictures of the app's windows (taken by the app itself, so nothing is asked of the person),
+  what it printed, and when it didn't build, the compiler's errors with their file and line: the app is then as it
+  was before the change. It answers the screen as text too once the app has been in front with the Mac unlocked;
+  without it, aim by the picture, whose points are the points to click. `look --reopen` quits the app and opens it
+  again first, as `{{lamp}} reload` does.
+- **`use`** takes `click` (a point of the picture, or a name or id from the screen as text: `{{lamp}} use click "Add"`),
+  `type`, `key` (`return`, `escape`, `cmd+a`…), `drag`, `scroll` and `wait`. It brings the app to the front. Only
+  when asked to try it.
+- **What you add while trying it is the app's real saved data**, kept under the app's own name in the person's
+  Application Support: take it out again, or tell them it's there.
+- **The app stays open** when you finish, as the person's to use. `{{lamp}} stop` quits it, when they only wanted it
+  checked.
+- **Lamp's own files** are `Sources/LampSupport.swift`, `build.sh` and `Package.swift`: never edit any of them.
+- **A change into the open app, without reopening it**, is Lamp's app's: when the person has Lamp open and wants that,
+  `{{lamp}} open --in-lamp` gives the app to it (Lamp shows them its review the first time). From then on `look`, `dev`
+  and `reload` say how each change went in (live, held for their Reload, reopened, not built), and the person tries it
+  there, and `use` tries the app Lamp has open, in plain sight. `{{lamp}} open --here` has lamp run its own copy again.
+- **Not here:** the app's AI (`LampAI`), and a link to one on lamp.dev (its Lamp app file is here: see "A Lamp app
+  file"). Those
+  are Lamp's app's: say so rather than working around it. What the app keeps secret (`LampSecrets`) is kept for it.
+
+## A game that's already there
+
+A web game from somewhere else runs as it is: every command here works on it, each change opens its page again from
+the start, and `look` can't know when it has finished loading. Putting it on Lamp's runtime is what lets it take
+changes while it's played and say when it's really playing. `{{lamp}} init` puts Lamp's own files beside its page and
+changes none of the page's; taking the runtime up in the game's code is the work. It goes in steps, each worth having
+by itself:
+
+1. **The runtime runs the game's loop** (`game()` in place of the game's own), with its renderer kept and the
+   player's place given and taken back. A change then runs the game's code again in place, where before it opened
+   the page again. A page laid out at the window's size that reads its own keys and touches says so to `game()`:
+   the options are in `lamp-game.js`'s comments on the frame.
+2. **The modules that get tuned accept their changes**, and those go in live.
+3. **What's slow to build is kept**, so running the code again doesn't build it again.
+
+Lamp's `game-live` skill says how each is done (its "A game from before this, or one brought in" is step 1), and
+`lamp-game.js`'s comments are the whole interface: read those, not `web-game`, which is for a new game. A game
+brought in reads its own input until its code reads the runtime's, so try it with keys, not Lamp's controller.
+
+Where Lamp's `github-projects` skill has Lamp's app keep the project's credit and licenses (`lampify`), nothing does
+here: keep its license file, its copyright headers and its author's credit on screen yourself.
+
+## The loop
+
+1. **Show the person the app** once, when you start, unless they don't want to watch: `{{lamp}} open`. It opens a
+   window they can use and play in while you work, and returns at once.
+2. **Change the files.**
+3. **Look**: `{{lamp}} look`. It waits for the change to go in, then answers how it went, a picture of the page (a
+   file: read it; the last forty are kept), the screen as text, and the errors and the log since your last look. Look
+   after every change, and read the errors and the picture before saying it works. `{{lamp}} look --reopen` opens the
+   page again from its beginning first, a game with its saves kept: what someone opening it sees. `--size 900x600`
+   looks at it as a window of that size shows it, for a layout that has to hold at any shape (with no window open).
+
+Nothing has to be running first. With no window open, `look` runs the app itself in a copy of the page nobody sees,
+opened from the files as they are, so the first look has no changes to report. The copy goes on running between
+commands, as a window would: what you clicked and typed is still there, and a game's clock doesn't wait for you. It
+closes by itself ten minutes after you last used it: there's nothing to stop when you finish.
+
+## Trying it
+
+Only when the person asks you to try, play or test the app: a request to change it is made and looked at, not played.
+
+- `{{lamp}} use click "Add"` clicks a control by its name in the screen as text, and `{{lamp}} use click 640 400` a
+  point of the picture, for what has no name there (a canvas, a drawing). The answer names what the click landed on.
+- `{{lamp}} use type hello` types into whatever has the keyboard: click a field first.
+- `{{lamp}} use key w 2` holds a key for two seconds (a letter, a digit, `space`, `enter`, `escape`, `up`, `left`…),
+  and `w+d` holds two at once.
+- `{{lamp}} use drag 400 300 700 300` presses at one point, moves to the other and lets go.
+- `{{lamp}} use scroll 600` scrolls down, and up with a negative number. A look shows only what's in the window.
+- `{{lamp}} use wait 3` waits, for something that takes time: thirty seconds at most, so wait again for longer.
+
+Several moves go in one command with `then` between them, one after another with nothing in between and one look at
+the end: `{{lamp}} use click 640 400 then key w 3 then key w+d 2`. Play anything with a clock that way, a whole
+stretch of it to a command, and end the stretch on the game's pause when it has one (`… then button menu`): the game
+runs on while you read a picture. Where a canvas is drawn at another size than it's shown, the screen as text says
+how a point of the game is found in the picture.
+
+A game on Lamp's runtime is played with Lamp's own controller, as Lamp's game skills say (`use_app`'s `stick` and
+`button`):
+
+- `{{lamp}} use stick left 1 0 2` holds the left stick to the right for two seconds: `left` or `right`, then x and y
+  from -1 to 1, right and up being 1. A button named after the seconds is held with it (`… 2 a`).
+- `{{lamp}} use button a` presses a button, `a 1.5` holds it, and `a+rt` holds two: `a`, `b`, `x`, `y`, `lb`, `rb`,
+  the triggers `lt` and `rt`, `menu`, `view`, `up`, `down`, `left`, `right`.
+
+It's the first player's controller, from wherever the game is. It isn't a controller plugged in, so the game's
+prompts go on naming keys. If the person plays meanwhile they have it back at once and the answer says so: the game
+is theirs until they ask again. A key works in a game here too.
+
+Each answers with a look. With the window open it happens in the person's own window, where they see it.
+
+## How a change went in
+
+`look` says one of these for each change since the last look:
+
+- **live**: swapped in while the page ran. Nothing was lost.
+- **reran**: the game's code ran again, with the player where they were. In a small game that takes a moment, and
+  is as good as live.
+- **reopened**: the page opened again. A game opens from the player's place. A plain page always takes a change this
+  way and starts over: what was typed or counted in it is gone, so change first and try after.
+- **held**: the change waits, and the page shows the person a Reload to apply button. Either it waits for a pause in
+  the game (the end of a round, a menu), and goes in by itself then: a later look says so. Or for that button, because
+  the page must open again for it: `{{lamp}} reload` presses it, so with a window open ask the person first.
+
+The reason given after one names the file that changed, where an `accept()` would have taken the change, and the
+module it's loaded through. A game that takes changes live is written for it. When a change won't go in, needs Reload
+or loses the player's place, read Lamp's `game-live` skill before working around it.
+
+## A Lamp app file
+
+A folder with `lamp-app.json` at its top (or in `.lamp-wish/`) is an app in Lamp's format, from GitHub or a shared file:
+every command here works on a web app, a game, a screen or a Mac app in one, and says so for a kind it doesn't run.
+
+- `{{lamp}} unpack Name.lampapp` unpacks a Lamp app file (what Lamp's Share… makes) into a new folder beside it, with
+  Lamp's own files put in, and says how to see it.
+- `{{lamp}} export` makes the app's Lamp app file beside its folder, for the person to send or open in Lamp: only when
+  they ask. It's refused when something in the app is shaped like a key, or a license its credits name is gone; when
+  it uses work that came with no license, ask the person before `--anyway`.
+
+## Sharing it
+
+Only when the person asks: a link is public, and anyone who has it can play the page.
+
+- `{{lamp}} share --words "What it is, in a sentence or a few"` puts the page on lamp.dev and answers its link. `--line`
+  is a line under its name, `--asks "Found a bug?|What's missing?"` what the box under the page asks people, and
+  `--by "Their Name"` who it's by: only a name the person gave you to show. A page that's logging errors isn't shared
+  until they're put right.
+- Again, after changes, it sends the page as it is now to the same link, with the same words unless you give new ones.
+- `{{lamp}} ideas` lists what people playing it have sent. Once one is in the game and the game shared again,
+  `{{lamp}} ideas in <number>` says so, and whoever asked to hear is written to; `{{lamp}} ideas dismiss <number>` lets
+  one go.
+- `{{lamp}} unshare` takes the link down.
+
+Tell the person the link, and that it's public.
+
+## On the person's Xbox
+
+A page goes on an Xbox in Developer Mode, in Lamp's own host for the console's browser: the same files, played with
+the console's controller. Only when the person asks for it there, and only on a device they set up.
+
+- `{{lamp}} devices` lists the devices set up with lamp and those found on the network. One only found may not be
+  theirs: never put anything on it.
+- Setting one up asks for the console's Device Portal password, which only the person types. Ask them to run
+  `{{lamp}} devices add` in a terminal themselves; never ask for the password, and never type one.
+- `{{lamp}} open --on xbox` packages the page as it is now, installs it and opens it on the console, in place of the
+  copy that was there. A change isn't live there: put the page on again once it works on this computer.
+- `{{lamp}} look --on xbox` is the console's screen as a picture, whether the app is open there, and what it logged
+  there. A game on Lamp's runtime logs how many frames a second it gets: that, never this computer's, says how it
+  runs on the console.
+- You can't press the controller there. Try the game in its window here (`stick`, `button`), where it's the same
+  code, and tell the person what's left for them to try with the controller in their hands.
+- `{{lamp}} stop --on xbox` ends it, and `{{lamp}} remove --on xbox` takes it off the console.
+
+## On Android
+
+A page goes on Android in Lamp's own Android app around it: the same files, on a phone, a tablet or a TV. It needs a
+Mac with Android's tools, which `{{lamp}} devices` says are there or not. If they aren't, ask the person to run
+`{{lamp}} devices add android` in a terminal themselves: it downloads Google's tools and accepts Google's terms for
+them, which is theirs to do.
+
+- `{{lamp}} open --on android` builds the app and opens it in lamp's Android emulator, a phone in a window on the Mac;
+  `--on android-tv` is its TV emulator. Use these when the person asks to see it on Android.
+- For a check of your own, add `--hidden`: the emulator starts with no window and no sound, and
+  `{{lamp}} stop --on android` closes it when you're done. Don't leave one running.
+- A phone, tablet or TV of the person's goes by its name (`{{lamp}} devices` lists those plugged in with USB debugging
+  on): only when they ask for it there. If it says to allow debugging, that's a tap on the device's own screen, theirs.
+- `{{lamp}} look --on android` is the device's screen as a picture, whether the app is open, and what the page logged
+  there: a game on Lamp's runtime logs how many frames a second it gets.
+- `{{lamp}} use --on android click <x> <y>` taps a point of that picture; `drag`, `type`, `key` and `button` work too,
+  one key or button at a time, with no stick. A game shows touch controls until a controller's button is pressed.
+- A change isn't live there: `{{lamp}} open --on android` again builds and installs it, in a few seconds.
+- `{{lamp}} remove --on android` takes it off.
+
+## Lamp's skills
+
+An app Lamp made (its page loads `lamp.js`) is built from Lamp's own building blocks, and Lamp has guidance for each
+kind of work on one: a new web game, 3D, how a game feels, a web app's page. `{{lamp}} skills game` lists those about a
+word, `{{lamp}} skills` all of them, and `{{lamp}} skill <name>` prints one. Read the ones that fit before changing what
+they cover: they are the one place that says which building blocks to use and how.
+
+Those skills are written for Lamp's app, which builds the game, opens it and looks at it for you when your turn
+ends, and so tells you to write and finish without looking or playing. Nothing does that here: you look after every
+change, as above, and that comes first. Where one names a tool of Lamp's:
+
+- `look_at_app` is `{{lamp}} look`, and its `reopen` is `--reopen`. There's no `motion`: look twice.
+- `use_app` is `{{lamp}} use`, one move to each of its actions. A control on the page is clicked at its point from the
+  screen as text, not by an id.
+- `read_skill` is `{{lamp}} skill <name>`, and `make_app_for` is `{{lamp}} new`, for a web game only.
+- `delete_file` is deleting the file, and putting a change in needs no tool.
+- `assets`, `make_art` and `lampify` aren't here: make what's needed in code, or say what's missing.
+
+A plain site, on neither `lamp.js` nor Lamp's runtime, uses none of them: skip the skills there.
+
+## Rules
+
+- Lamp's own files in the folder are rewritten by Lamp, so read them and never edit them: `lamp.js`, `lamp-game.js`,
+  `lamp-phaser.js`, `lamp-controllers.js`, and the `three/` and `phaser/` folders.
+- The page's whole log is the file `look` names.
+- lamp runs the page in a browser on this computer, and puts it on an Xbox ("On the person's Xbox") and on Android
+  ("On Android"). iPhones, Samsung and LG TVs,
+  and whatever needs Lamp's Mac app around the page, aren't here: say so rather than working around it.

package/cli/skills.mjs

@@ -0,0 +1,71 @@
+// Lamp's skills as `lamp skill` prints them: read from Lamp's own folder (Resources/skills), and put together the way
+// Lamp's app puts them together (`Skills.parse`, `Skills.assembled`, `Skills.section`). A skill made of sections of
+// others names them in its frontmatter ("game#Fun; game-ui#Proof") and has them put where its body says
+// `{{sections}}`, so each section is written in one place.
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { RESOURCES } from "./state.mjs";
+
+export const SKILLS = join(RESOURCES, "skills");
+
+/** A SKILL.md: frontmatter between `---` lines, a field a line, then the instructions. */
+function parse(text) {
+  const lines = text.split("\n");
+  const close = lines.indexOf("---", 1);
+  if (lines[0] !== "---" || close < 0) return null;
+  const fields = {};
+  for (const line of lines.slice(1, close)) {
+    const colon = line.indexOf(":");
+    if (colon > 0) fields[line.slice(0, colon).trim()] = line.slice(colon + 1).trim();
+  }
+  if (!fields.name || !fields.description) return null;
+  return { name: fields.name, description: fields.description, sections: fields.sections ?? null, body: lines.slice(close + 1).join("\n").trim() };
+}
+
+/** One section of a skill, as "skill#Heading": its heading, made a second-level one, and what's under it. */
+function section(name, skills) {
+  const at = name.indexOf("#");
+  const source = at < 0 ? null : skills.get(name.slice(0, at))?.body;
+  if (source == null) return null;
+  const title = name.slice(at + 1), lines = source.split("\n");
+  // A line of a code block is never a heading, whatever it starts with.
+  let fenced = false;
+  const headings = [];
+  lines.forEach((line, index) => {
+    if (line.startsWith("```")) { fenced = !fenced; return; }
+    const marks = /^(#+) /.exec(line);
+    if (!fenced && marks) headings.push({ index, level: marks[1].length, title: line.slice(marks[1].length).trim() });
+  });
+  if (!title) {
+    // The text before the skill's first section.
+    const first = headings.find((heading) => heading.level === 1), second = headings.find((heading) => heading.level === 2);
+    const start = first ? first.index + 1 : 0, end = second ? second.index : lines.length;
+    return lines.slice(start, Math.max(start, end)).join("\n").trim() || null;
+  }
+  const found = headings.findIndex((heading) => heading.title === title && heading.level > 1);
+  if (found < 0) return null;
+  const heading = headings[found], next = headings.slice(found + 1).find((later) => later.level <= heading.level);
+  return `## ${heading.title}\n\n${lines.slice(heading.index + 1, next ? next.index : lines.length).join("\n").trim()}`;
+}
+
+/** Every skill by name, each as Lamp's app hands it over. Empty when Lamp's skills aren't beside this copy of lamp. */
+export function allSkills() {
+  const skills = new Map();
+  if (!existsSync(SKILLS)) return skills;
+  for (const entry of readdirSync(SKILLS, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    let skill = null;
+    try { skill = parse(readFileSync(join(SKILLS, entry.name, "SKILL.md"), "utf8")); } catch {}
+    if (skill) skills.set(skill.name, skill);
+  }
+  // Sections come from the skills as they're written, never from one already put together.
+  const written = new Map(skills);
+  for (const skill of written.values()) {
+    if (!skill.sections) continue;
+    const text = skill.sections.split(";").map((name) => name.trim()).filter(Boolean).map((name) => section(name, written)).filter(Boolean).join("\n\n");
+    skills.set(skill.name, { ...skill, body: skill.body.includes("{{sections}}") ? skill.body.replaceAll("{{sections}}", text) : `${skill.body}\n\n${text}` });
+  }
+  return skills;
+}