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

package/cli/page.js

@@ -0,0 +1,317 @@
+// Given to every page lamp dev serves, before any script of its own. The server puts `LAMP` in front of it: `gen` the
+// last change the page's files had when they were served, `run` which run of the server served them.
+(() => {
+  // The browser's own functions, kept before the page changes them. The game runtime takes away the timers the
+  // game's code left running each time that code runs again, and a timer of lamp's set through the page's
+  // `setTimeout` would go with them, and the log with it.
+  const later = window.setTimeout.bind(window), ask = window.fetch.bind(window);
+  const unlater = window.clearTimeout.bind(window), every = window.setInterval.bind(window), unevery = window.clearInterval.bind(window);
+  // A page opened again to show its beginning (`lamp look --reopen`) says so to the game runtime, which then starts
+  // the game from its start, its saves kept (`window.lampFreshStart` in lamp-game.js).
+  const FRESH = 'lamp.dev.fresh';
+  try { if (sessionStorage.getItem(FRESH)) { sessionStorage.removeItem(FRESH); window.lampFreshStart = true; } } catch (e) {}
+  const id = Math.random().toString(36).slice(2, 10);
+  // The tab, which stays the same as its page opens again: how a change went is told of the tab.
+  let tab = id;
+  try { tab = sessionStorage.getItem('lamp.dev.tab') || id; sessionStorage.setItem('lamp.dev.tab', tab); } catch (e) {}
+  window.__lampTab = tab;
+  const post = (path, body, lasting) => {
+    try { ask('/__lamp/' + path, { method: 'POST', body: JSON.stringify({ page: id, ...body }), keepalive: !!lasting }).catch(() => {}); } catch (e) {}
+  };
+  const said = message => post('said', message, true);
+
+  // MARK: The page's AI
+  // LampAI in lamp.js reaches Lamp's app through a host bridge when the app shows the page; here lamp itself answers
+  // (`/__lamp/ai`, with the person's own Claude Code or Codex), through the same shape of bridge lamp.js takes from
+  // Lamp's Android app: postMessage of a request, an onmessage with its answer.
+  if (!window.lampGatewayHost && !(window.webkit && window.webkit.messageHandlers && window.webkit.messageHandlers.lampGateway)) {
+    const gateway = { onmessage: null };
+    gateway.postMessage = (text) => {
+      let asked;
+      try { asked = JSON.parse(text); } catch (e) { return; }
+      const answer = (status, body) => { if (typeof gateway.onmessage === 'function') gateway.onmessage({ data: JSON.stringify({ id: asked.id, status, body }) }); };
+      const stop = new AbortController();
+      const timer = later(() => stop.abort(), Math.max(1000, Number(asked.timeout) || 240000));
+      ask('/__lamp/ai', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Lamp-Page': '1' }, body: JSON.stringify({ path: asked.path, body: asked.body }), signal: stop.signal })
+        .then((r) => r.json()).then((r) => answer(r.status, r.body), () => answer(502, JSON.stringify({ error: 'lamp dev took too long to answer.' })))
+        .finally(() => unlater(timer));
+    };
+    try { Object.defineProperty(window, 'lampGatewayHost', { value: gateway, configurable: true }); } catch (e) {}
+  }
+
+  // MARK: The card on a change
+  // The same card Lamp's app puts on an open app as a change goes in (`LampTransition.Look`, TransitionLook.swift, which
+  // says how it looks: keep the two in step), at the foot of the page: Lamp's mark turning, "Updating" and what's
+  // changing (the words the coding agent gave with `lamp changing`, if it did), then "Updated" for a moment once the
+  // change is on screen, so every change is seen to land. It covers nothing but itself and lets every click through.
+  // The mark turns by the browser's compositor, so it keeps turning while the page is busy with the new code. Never in
+  // a picture lamp takes (`__lampLightHidden`), and still where less motion is asked for.
+  const light = (() => {
+    const HUES = ['#1f8a4a', '#7cbf3a', '#f6b81c', '#f08a1c', '#e2402a', '#d23778'];
+    // As in the Look: the card stays at least this long, "Updated" this long, and the mark turns once in this long.
+    const SHOWN_AT_LEAST = 1.2, HELD_AFTER = 1.4, SPIN_EVERY = 1.4;
+    const still = () => { try { return matchMedia('(prefers-reduced-motion: reduce)').matches; } catch (e) { return false; } };
+    let root = null, card = null, bands = null, title = null, detail = null, spinning = null, shownAt = 0, gone = null, hidden = false, safety = null;
+    // The card's way out ("Updated" fading, or a fade), which a change coming meanwhile stops.
+    let outgoing = null;
+    const make = () => {
+      if (root && root.isConnected) return;
+      root = document.createElement('div');
+      root.setAttribute('aria-hidden', 'true');
+      root.style.cssText = 'position:fixed;inset:0;pointer-events:none;z-index:2147483647;overflow:hidden;contain:strict';
+      card = document.createElement('div');
+      card.style.cssText = 'position:absolute;left:50%;bottom:min(20px,6vh);transform:translateX(-50%);display:flex;align-items:center;gap:8px;' +
+        'height:36px;box-sizing:border-box;padding:0 16px 0 12px;max-width:min(460px,calc(100vw - 32px));border-radius:18px;' +
+        'background:rgba(20,20,20,.86);border:1px solid rgba(255,255,255,.12);box-shadow:0 3px 12px rgba(0,0,0,.3);' +
+        'font:13px/17px -apple-system,BlinkMacSystemFont,"Segoe UI",system-ui,sans-serif;color:#fff;white-space:nowrap;opacity:0';
+      // Lamp's mark: its stripes on their slant, in a disc, which turns while the change is under way.
+      const mark = document.createElement('div');
+      mark.style.cssText = 'flex:none;width:18px;height:18px;border-radius:50%;overflow:hidden;position:relative';
+      bands = document.createElement('div');
+      bands.style.cssText = `position:absolute;left:-5.4px;top:-5.4px;width:28.8px;height:28.8px;transform:rotate(${-30}deg);` +
+        `background:linear-gradient(to bottom, ${HUES.map((hue, i) => `${hue} ${i * 100 / 6}% ${(i + 1) * 100 / 6}%`).join(', ')})`;
+      mark.appendChild(bands);
+      title = document.createElement('span');
+      title.style.cssText = 'flex:none;font-weight:600';
+      detail = document.createElement('span');
+      detail.style.cssText = 'min-width:0;overflow:hidden;text-overflow:ellipsis;opacity:.72';
+      card.append(mark, title, detail);
+      root.appendChild(card);
+      // Beside the body rather than in it: a game running its code again clears what its body held.
+      document.documentElement.appendChild(root);
+      if (hidden) root.style.visibility = 'hidden';
+    };
+    const goAfter = seconds => {
+      unlater(gone);
+      gone = later(() => { spinning = null; root && root.remove(); root = null; shownAt = 0; }, seconds * 1000);
+    };
+    const show = () => {
+      make();
+      unlater(gone);
+      if (outgoing) { outgoing.cancel(); outgoing = null; }
+      if (shownAt) return;
+      shownAt = performance.now();
+      card.animate([{ opacity: 0, transform: still() ? 'translateX(-50%)' : 'translate(-50%, 10px)' }, { opacity: 1, transform: 'translateX(-50%)' }],
+        { duration: 250, easing: 'ease-out', fill: 'forwards' });
+    };
+    const spin = () => {
+      if (still() || spinning) return;
+      spinning = bands.animate([{ transform: 'rotate(-30deg)' }, { transform: 'rotate(330deg)' }], { duration: SPIN_EVERY * 1000, iterations: Infinity });
+    };
+    // Never left over a page that doesn't say its change is on screen (a game stopped by an error): it goes after a
+    // minute, as the card in Lamp's app goes when Lamp stops renewing it.
+    const watch = () => { unlater(safety); safety = later(() => api.fade(), 60000); };
+    let words = '';
+    const api = {
+      // A change came: the card comes up with "Updating", what's changing, and the mark turning.
+      glow(given) {
+        if (typeof given === 'string') words = given;
+        show();
+        watch();
+        title.textContent = 'Updating';
+        detail.textContent = words;
+        spin();
+      },
+      // The game stands still taking it in: the card stays as it is until `reveal`.
+      turn() { api.glow(); },
+      // The change is on screen: "Updated" for a moment, then the card goes.
+      reveal() {
+        if (!root) return;
+        unlater(safety);
+        title.textContent = 'Updated';
+        if (spinning) { spinning.cancel(); spinning = null; }
+        if (!still()) bands.parentNode.animate([{ transform: 'scale(1.25)' }, { transform: 'scale(1)' }], { duration: 300, easing: 'ease-out' });
+        const wait = Math.max(HELD_AFTER, SHOWN_AT_LEAST - (performance.now() - shownAt) / 1000);
+        if (outgoing) outgoing.cancel();
+        outgoing = card.animate([{ opacity: 1 }, { opacity: 0 }], { duration: 300, delay: wait * 1000, fill: 'forwards', easing: 'ease-in-out' });
+        words = '';
+        goAfter(wait + 0.35);
+      },
+      // The change didn't go in now (held for a pause or a Reload): the card goes.
+      fade() {
+        unlater(safety);
+        if (!root) return;
+        if (outgoing) outgoing.cancel();
+        outgoing = card.animate([{ opacity: getComputedStyle(card).opacity }, { opacity: 0 }], { duration: 250, fill: 'forwards' });
+        words = '';
+        goAfter(0.3);
+      },
+      hide(on) { hidden = !!on; if (root) root.style.visibility = on ? 'hidden' : ''; },
+      get words() { return words; },
+    };
+    return api;
+  })();
+  // Left out of the pictures lamp takes of the page.
+  window.__lampLightHidden = on => light.hide(on);
+  // A page opening again for a change goes on saying so until its new code draws, with the same words.
+  const TURNING = 'lamp.dev.turning', WORDS = 'lamp.dev.words';
+  const turnAcross = () => { try { sessionStorage.setItem(TURNING, String(Date.now())); sessionStorage.setItem(WORDS, light.words); } catch (e) {} };
+  try {
+    const since = Number(sessionStorage.getItem(TURNING)), carried = sessionStorage.getItem(WORDS) || '';
+    sessionStorage.removeItem(TURNING);
+    sessionStorage.removeItem(WORDS);
+    if (since && Date.now() - since < 30000) light.glow(carried);
+  } catch (e) {}
+  // How the game said a change went, read for the card: it goes in now, stands still taking it in, waits, or is on screen.
+  const lit = message => {
+    const state = message && message.state;
+    if (state === 'swapped') light.reveal();
+    else if (state === 'rerun') light.turn();
+    else if (state === 'reloading') { light.turn(); turnAcross(); }
+    else if (state === 'held') light.fade();
+    // Once its new frames can show, as Lamp's app reads it (`PageLive`): a game put back where it was says so before its
+    // first frame and its shaders.
+    else if (state === 'shown') light.reveal();
+  };
+
+  // What Lamp's app around a page gives it: with these the game runtime knows changes come while it's played, and says
+  // how each one went and when the game is past its loading screen.
+  const handlers = {
+    lampLive: { postMessage: message => { lit(message); said(message); } }, lampPlaying: { postMessage: state => said({ state: 'page-' + state }) },
+    // The person played while lamp held the game's controller (`lamp use stick`), and has it back.
+    lampDriveTakenOver: { postMessage: why => said({ state: 'taken-over', why: String(why || '') }) },
+  };
+  try { window.webkit = window.webkit || {}; window.webkit.messageHandlers = Object.assign(window.webkit.messageHandlers || {}, handlers); }
+  catch (e) { try { Object.defineProperty(window, 'webkit', { value: { messageHandlers: handlers }, configurable: true }); } catch (e) {} }
+
+  // The page's log, sent on a few lines at a time.
+  let lines = [], timer = null;
+  const say = (level, parts) => {
+    let text;
+    try { text = parts.map(p => typeof p === 'string' ? p : p instanceof Error ? (p.stack || p.message) : JSON.stringify(p)).join(' '); } catch (e) { text = String(parts[0]); }
+    lines.push({ level, text: String(text).slice(0, 4000) });
+    if (!timer) timer = later(() => { timer = null; const batch = lines; lines = []; post('log', { lines: batch }); }, 250);
+  };
+  for (const level of ['log', 'info', 'warn', 'error']) {
+    const real = console[level];
+    console[level] = (...parts) => { real.apply(console, parts); say(level === 'info' ? 'log' : level, parts); };
+  }
+  // Whether the page runs on the game runtime (lamp-game.js), which says so. A game's page without it has `__lampLive`
+  // too (lamp-live.js, given after this script), so that alone doesn't tell; a runtime from before it said so does have
+  // its own `__lampLive`, never lamp-live.js's.
+  const runtime = () => !!window.__lampRuntime || (!!window.__lampLive && !window.__lampLive.lampHelper);
+  // A page with the game runtime logs its own errors; any other page's are logged here.
+  addEventListener('error', e => { if (!runtime()) say('error', [e.message + ' (' + (String(e.filename || '').split('/').pop() || 'the page') + ':' + e.lineno + ')']); });
+  addEventListener('unhandledrejection', e => { if (!runtime()) say('error', [String(e.reason && e.reason.message || e.reason)]); });
+  // A page without the game runtime is on screen once it has loaded.
+  addEventListener('load', () => { said({ state: 'page-loaded' }); if (!runtime()) light.reveal(); });
+
+  // Changes. The line says which change this copy's files had, so one saved while the page was opening comes as soon
+  // as the line is open; the browser says the last it heard when the line is opened again after a break.
+  // Opened again from where the player is, or from the game's beginning when that's asked: the page that opens next
+  // is told so before the runtime loads (see `FRESH` above). Any other page always starts over.
+  const reopen = e => {
+    if (e && e.data === 'fresh') {
+      try { sessionStorage.setItem(FRESH, '1'); } catch (e2) {}
+      return location.reload();
+    }
+    (window.__lampReloadNow || (() => location.reload()))();
+  };
+  const events = new EventSource('/__lamp/events?page=' + id + '&tab=' + tab + '&since=' + LAMP.gen);
+  // A server started again doesn't know what changed while it was away: the page opens again from the files as they are.
+  events.addEventListener('hello', e => { if (e.data !== LAMP.run) location.reload(); });
+  events.addEventListener('change', e => {
+    const change = JSON.parse(e.data);
+    light.glow(typeof change.words === 'string' ? change.words : '');
+    // A game takes the change and keeps the player's place (on the runtime, or where lamp-live.js can); any other page
+    // opens again.
+    let taken = false;
+    try { taken = !!(window.__lampLive && window.__lampLive(change)); } catch (e) {}
+    if (!taken) { light.turn(); turnAcross(); said({ gen: change.gen, state: 'reloading' }); location.reload(); }
+  });
+  events.addEventListener('reload', reopen);
+  // With no browser lamp can look into, the page says what's on it itself.
+  events.addEventListener('look', e => post('looked', { ask: e.data, seen: window.__lampLook() }));
+
+  // What's on the page, as text: each control and canvas with the point at its middle, and the words shown.
+  const CONTROLS = 'button, a[href], input, select, textarea, summary, [role=button], [role=link], [role=tab], [role=checkbox], [role=switch], [role=slider], [role=menuitem], [contenteditable=""], [contenteditable=true]';
+  const words = text => String(text || '').replace(/\s+/g, ' ').trim().slice(0, 90);
+  const kind = el => {
+    const tag = el.tagName.toLowerCase(), role = el.getAttribute('role');
+    if (role) return role;
+    if (tag === 'a') return 'link';
+    if (tag === 'select') return 'choice';
+    if (tag === 'textarea' || el.isContentEditable) return 'field';
+    if (tag === 'input') return ({ checkbox: 'checkbox', radio: 'radio', range: 'slider', button: 'button', submit: 'button' })[el.type] || 'field';
+    return 'button';
+  };
+  const named = el => `${kind(el)} "${words(el.getAttribute('aria-label') || el.innerText || el.getAttribute('title') || el.getAttribute('placeholder') || el.getAttribute('alt') || el.name)}"`;
+
+  window.__lampLook = () => {
+    const lines = [], width = innerWidth, height = innerHeight;
+    const box = el => {
+      const r = el.getBoundingClientRect();
+      return r.width < 2 || r.height < 2 || r.bottom <= 0 || r.right <= 0 || r.top >= height || r.left >= width ? null : r;
+    };
+    const middle = r => Math.round(Math.min(Math.max(r.left + r.width / 2, 0), width - 1)) + ',' + Math.round(Math.min(Math.max(r.top + r.height / 2, 0), height - 1));
+    const walk = parent => {
+      for (const el of parent.children) {
+        if (lines.length > 160) return;
+        const tag = el.tagName.toLowerCase();
+        if (tag === 'script' || tag === 'style' || tag === 'template' || tag === 'noscript') continue;
+        const look = getComputedStyle(el);
+        // What's faded out, or nearly (a loading screen on its way out), isn't on the screen.
+        if (look.display === 'none' || Number(look.opacity) < 0.1) continue;
+        const hidden = look.visibility === 'hidden', r = hidden ? null : box(el);
+        if (r && tag === 'canvas') {
+          // A canvas drawn at another size than it's shown (a game's stage) says how a point of what's drawn is found
+          // in the picture.
+          const scale = el.width ? r.width / el.width : 1, round = n => Math.round(n * 100) / 100;
+          const drawn = Math.abs(scale - 1) > 0.02 && el.width > 1 ? ` (drawn at ${el.width}×${el.height}: its point x,y is at ${Math.round(r.left)}+x×${round(scale)}, ${Math.round(r.top)}+y×${round(r.height / el.height)} in the picture)` : '';
+          lines.push(`canvas ${Math.round(r.width)}×${Math.round(r.height)} at ${middle(r)}${drawn}`);
+          continue;
+        }
+        if (r && el.matches(CONTROLS)) {
+          const holds = el.type === 'checkbox' || el.type === 'radio' ? (el.checked ? ' (on)' : ' (off)')
+            : 'value' in el && typeof el.value === 'string' && el.value && tag !== 'button' ? ` = "${words(el.value)}"` : '';
+          lines.push(`${named(el)}${holds}${el.disabled ? ' (off for now)' : ''} at ${middle(r)}`);
+          continue;
+        }
+        if (r && tag === 'img') { const alt = words(el.alt); if (alt) lines.push(`picture "${alt}"`); continue; }
+        if (r) {
+          // Words set in pieces (a number in a span of its own, a heading in two colors) are one line, as they read.
+          const pieces = [...el.children];
+          const whole = pieces.length && (/^h[1-6]$/.test(tag) ? !el.querySelector(CONTROLS + ', canvas')
+            : pieces.every(c => getComputedStyle(c).display.startsWith('inline') && !c.children.length && !c.matches(CONTROLS) && c.tagName.toLowerCase() !== 'canvas'));
+          const own = words(whole ? el.innerText : [...el.childNodes].filter(n => n.nodeType === 3).map(n => n.textContent).join(' '));
+          if (own) lines.push(`${/^h[1-6]$/.test(tag) ? 'heading' : 'text'} "${own}"`);
+          if (whole) continue;
+        }
+        walk(el);
+      }
+    };
+    if (document.body) walk(document.body);
+    if (lines.length > 160) lines.push('… and more');
+    // A game drawn on a stage of its own shape, fitted in the window with bars beside or above it: the stage's size.
+    // One that fills the window, whatever its shape, has none.
+    let stage = null;
+    if (runtime()) {
+      const canvas = [...document.querySelectorAll('canvas')].map(c => [c, c.getBoundingClientRect()]).sort((a, b) => b[1].width * b[1].height - a[1].width * a[1].height)[0];
+      if (canvas && canvas[0].width > 1 && canvas[0].height > 1 && (width - canvas[1].width >= 2 || height - canvas[1].height >= 2)) stage = [canvas[0].width, canvas[0].height];
+    }
+    return { tab, stage, title: document.title, path: location.pathname + location.search, width, height, dpr: devicePixelRatio || 1, game: runtime(), screen: lines.join('\n') };
+  };
+
+  // The point of the control called this in the screen as text (`button "Add"`, or just `Add`), for a click by name.
+  window.__lampPoint = called => {
+    const wanted = String(called).trim();
+    for (const el of document.querySelectorAll(CONTROLS)) {
+      const r = el.getBoundingClientRect(), look = getComputedStyle(el);
+      if (r.width < 2 || r.height < 2 || look.display === 'none' || look.visibility === 'hidden') continue;
+      const name = named(el), label = name.slice(name.indexOf('"') + 1, -1);
+      if (name === wanted || label === wanted) return [Math.round(r.left + r.width / 2), Math.round(r.top + r.height / 2)];
+    }
+    return null;
+  };
+
+  // What's at a point of the page, in the screen's own words, so a click says what it landed on.
+  window.__lampAt = (x, y) => {
+    const el = document.elementFromPoint(x, y);
+    if (!el || el === document.documentElement || el === document.body) return 'nothing: the page\'s background';
+    const control = el.closest(CONTROLS);
+    if (control) return named(control);
+    if (el.tagName.toLowerCase() === 'canvas') return 'the canvas';
+    const text = words(el.innerText).slice(0, 50);
+    return text ? `the text "${text}", which isn't a control` : 'nothing that\'s a control';
+  };
+})();

package/cli/place.mjs

@@ -0,0 +1,298 @@
+// A page on one of the person's devices: packaged for the device's own host, put there, opened, looked at, stopped
+// and taken off again, each through what the device's integration says (devices.mjs). An Xbox is the first: the page
+// goes in Lamp's host for the console's own Chromium (Resources/WebHost), in a Windows package lamp makes and signs
+// itself (msix.mjs), installed through the console's Device Portal. It's `DeviceApps` in Lamp's app, for a page.
+//
+// The package is made in lamp's own folder for the app, never in the app's: what goes to a device is what lamp read
+// of the page as it packaged it.
+
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Problem, RESOURCES, stateOf } from "./state.mjs";
+import { androidDeviceNamed, emulatorNamed, knowsAndroid, lookOnAndroid, putOnAndroid, removeFromAndroid, stopOnAndroid, useOnAndroid } from "./android.mjs";
+import { Away, Runner, StillWorking, allKept, answersOn, devicesHome, integrationOf, isReady, kept, look, takesPages } from "./devices.mjs";
+import { PUBLISHER, WEB_HOST, identityName, keptSigner, namesOf, packageOf, versionAfter } from "./msix.mjs";
+import { sizeOf, tile } from "./png.mjs";
+import { nameOf, pageFiles } from "./share.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const HOST = join(RESOURCES, "WebHost");
+const sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+// The most lamp sends a device.
+const PACKAGE_LIMIT = 1 << 30;
+
+function readJSON(file) { try { return JSON.parse(readFileSync(file, "utf8")); } catch { return null; } }
+
+/**
+ * The device a word names, among those lamp set up that take a page: by its own name ("Living Room Xbox"), its kind
+ * ("xbox") or its id. One that's only found on the network is never taken for the person's: it's set up first.
+ */
+export function deviceNamed(word, { command = "lamp" } = {}) {
+  const wanted = String(word).toLowerCase();
+  const mine = allKept().filter((device) => takesPages(integrationOf(device.integration)));
+  const setUp = `${command} devices add sets one up: run it in a terminal yourself, since it asks for what only you should type`;
+  if (!mine.length) throw new Problem(`lamp hasn't set up a device that takes a page yet. ${setUp}.`);
+  const named = mine.filter((device) => {
+    const integration = integrationOf(device.integration);
+    return device.id.toLowerCase() === wanted || device.name.toLowerCase() === wanted || integration.id.startsWith(wanted) || integration.name.toLowerCase() === wanted;
+  });
+  const found = named.length ? named : mine.filter((device) => device.name.toLowerCase().includes(wanted));
+  if (!found.length) throw new Problem(`lamp has no device called "${word}" set up. It has: ${mine.map((device) => device.name).join(", ")}.`);
+  if (found.length > 1) throw new Problem(`"${word}" could be ${found.map((device) => `"${device.name}"`).join(" or ")}: say which by its name.`);
+  if (!isReady(found[0], integrationOf(found[0].integration))) throw new Problem(`${found[0].name} isn't all set up yet. ${setUp}.`);
+  return found[0];
+}
+
+/**
+ * Where the word after --on says a page goes, each put on, looked at, stopped and taken off the same way: lamp's own
+ * Android emulator ("android", "android-tv"), a device lamp set up ("xbox", or its name), or an Android device of the
+ * person's that adb sees (its name, or adb's serial for it). Only an Android place can be tried (`use`): adb sends it
+ * taps and keys, where a console takes none.
+ */
+export async function placeNamed(word, { command = "lamp" } = {}) {
+  const android = (place) => ({
+    name: place.name, word: place.word,
+    put: (layout, options = {}) => putOnAndroid(layout, place, { ...options, command }),
+    look: (layout) => lookOnAndroid(layout, place, { command }),
+    use: (layout, moves) => useOnAndroid(layout, place, moves, { command }),
+    stop: (layout) => stopOnAndroid(layout, place),
+    remove: (layout) => removeFromAndroid(layout, place, { command }),
+  });
+  const emulator = emulatorNamed(word);
+  if (emulator) {
+    if (!knowsAndroid()) throw new Problem(process.platform === "darwin" ? "Lamp's Android app for a page isn't beside this copy of lamp: scripts/cli-files.sh writes it" : "lamp builds for Android on a Mac, so far");
+    return android(emulator);
+  }
+  let device, missing;
+  try { device = deviceNamed(word, { command }); } catch (error) { if (!(error instanceof Problem)) throw error; missing = error; }
+  if (device) {
+    return {
+      name: device.name, word,
+      put: async (layout, options = {}) => {
+        const put = await putOn(layout, device, options);
+        return { ...put, line: `${put.name} is open on ${device.name}${put.game ? ", installed as a game" : ""}: ${put.files} files, version ${put.identity.version}.` };
+      },
+      look: (layout) => lookOn(layout, device),
+      stop: (layout) => stopOn(layout, device),
+      remove: (layout) => removeFrom(layout, device),
+    };
+  }
+  const own = await androidDeviceNamed(word);
+  if (own) return android(own);
+  throw new Problem(`${missing.message}${knowsAndroid() ? ` lamp's Android emulator is --on android, and an Android device of the person's goes by its name once it's plugged in with USB debugging on (${command} devices lists them).` : ""}`);
+}
+
+/**
+ * Makes sure the device answers where lamp last found it, before anything is made for it. One that doesn't may have
+ * been given another address since: lamp looks for it once, and goes on at the address it answers from now.
+ */
+async function reached(runner) {
+  const device = runner.device, port = runner.integration.bridge?.install?.find((action) => action.http)?.http.port;
+  if (!port || (await answersOn(device.address, port, { reach: runner.reach }))) return;
+  await look().catch(() => []);
+  const now = kept(device.id);
+  if (now?.address && now.address !== device.address && (await answersOn(now.address, port, { reach: runner.reach }))) { device.address = now.address; return; }
+  throw new Problem(`${device.name} isn't answering (last at ${device.address}). Make sure it's on and in Developer Mode, then try again.`);
+}
+
+/** Where lamp keeps what it made of an app for one device: the package, its names, and which copy the device has. */
+const buildFolder = (layout, device) => join(stateOf(layout.folder), "device", createHash("sha256").update(device.id).digest("hex").slice(0, 8));
+
+/** The app's name to lamp, which its package is named for: its folder's own, so two apps never share a package. */
+const appID = (layout) => stateOf(layout.folder).split(/[\\/]/).pop();
+
+/**
+ * The package's name on the Xbox: the folder's name, cut so its hash always fits after it (`identityName` keeps 40
+ * characters), so two folders with the same long name are two apps there.
+ */
+const xboxName = (layout) => {
+  const id = appID(layout), hash = id.slice(id.lastIndexOf("-") + 1);
+  const name = [...id.slice(0, id.lastIndexOf("-"))].filter((c) => /[A-Za-z0-9-]/.test(c)).join("");
+  return identityName(`${name.slice(0, 40 - hash.length - 1)}-${hash}`);
+};
+
+/** What a game's page is told about the device it's on (`GamePage.descriptor`): its controller and what its keys are called. */
+export function deviceFile(integration) {
+  const input = integration.input ?? {}, facts = {};
+  if (input.controller) facts.controller = input.controller;
+  facts.keys = Object.fromEntries(Object.entries(input.keys ?? {}).sort(([a], [b]) => (a < b ? -1 : 1)));
+  if (input.layout) facts.layout = input.layout;
+  return `// Written by Lamp for the device this copy of the game is on (${integration.id}); don't edit.\nexport default ${JSON.stringify(facts)};\n`;
+}
+
+/** Whether the app is installed as a game: a device may give a game more than an app (an Xbox, about five times the memory and its whole GPU). */
+const isGame = (layout) => layout.game || readJSON(join(layout.folder, "capabilities.json"))?.game === true;
+
+/** The app's icon, where it has one lamp can draw from: Lamp's own for the app, or a page's. */
+function iconOf(layout) {
+  const candidates = [join(layout.folder, ".lamp", "AppIcon-square.png"), ...["apple-touch-icon.png", "icon.png", "favicon.png"].map((name) => join(layout.root, name))];
+  for (const file of candidates) {
+    try { const bytes = readFileSync(file); if (sizeOf(bytes)) return bytes; } catch {}
+  }
+  return null;
+}
+
+/**
+ * Makes the package of the page for a device, in lamp's folder: the page's files as they are now, with what a game is
+ * told of the device, in the device's host. Each one is a newer version than the last, so it replaces it.
+ */
+export function packageFor(layout, device, integration = integrationOf(device.integration)) {
+  if (!takesPages(integration)) throw new Problem(`lamp doesn't put a page on a ${integration?.name ?? "device like that"} yet`);
+  let host, library;
+  try { host = readFileSync(join(HOST, WEB_HOST.program)); library = readFileSync(join(HOST, WEB_HOST.library)); }
+  catch { throw new Problem(`Lamp's web host for the ${integration.name} isn't beside this copy of lamp`); }
+  const files = pageFiles(layout, { device: deviceFile(integration) });
+  if (files.reduce((sum, [, bytes]) => sum + bytes.length, 0) > PACKAGE_LIMIT) throw new Problem(`the page is bigger than lamp sends to a device (${PACKAGE_LIMIT >> 30} GB)`);
+  const payload = [[WEB_HOST.program, host], [WEB_HOST.library, library], ...files.map(([path, bytes]) => [`${WEB_HOST.folder}/${path}`, bytes])];
+  const folder = buildFolder(layout, device);
+  mkdirSync(folder, { recursive: true });
+  const identity = { name: xboxName(layout), publisher: PUBLISHER, version: versionAfter(readJSON(join(folder, "identity.json"))?.version), architecture: "x64" };
+  const signer = keptSigner(join(devicesHome(), "msix")), icon = iconOf(layout);
+  const made = packageOf({ payload, displayName: nameOf(layout), identity, entry: "webHost", logo: (width, height) => tile(icon, width, height), signer });
+  writeFileSync(join(folder, "package.msix"), made);
+  writeFileSync(join(folder, "certificate.cer"), signer.certificate);
+  writeFileSync(join(folder, "identity.json"), JSON.stringify(identity));
+  return { folder, identity, files: files.length, bytes: made.length, game: isGame(layout) };
+}
+
+/** lamp's values for the bridge: the app's id, whether it's a game, and the names Windows gives its package. */
+function valuesOf(layout, identity) {
+  const values = { appID: appID(layout), isGame: isGame(layout) ? "true" : "false" };
+  if (identity) { const names = namesOf(identity); values.packageFullName = names.fullName; values.appUserModelID = names.appUserModelID; }
+  return values;
+}
+
+/** The copy lamp last put on the device, by the record its install left; null when lamp never put one there. */
+const installed = (layout, device) => readJSON(join(buildFolder(layout, device), "installed.json"));
+
+// A device busy closing the app it's replacing can drop a connection, the upload's or the launch's just after it.
+const dropped = (error) => error instanceof Away && ["ECONNRESET", "EPIPE", "ECONNABORTED"].includes(error.code);
+
+/**
+ * Packages the page and puts it on the device: the copy there is ended, the new one installed and, unless `opens` is
+ * false, opened. `said` is told each stage as it starts.
+ */
+export async function putOn(layout, device, { opens = true, said = () => {}, runner } = {}) {
+  runner ??= new Runner({ integration: integrationOf(device.integration), device });
+  const integration = runner.integration, bridge = integration.bridge ?? {};
+  if (!bridge.install) throw new Problem(`${device.name}'s integration doesn't say how an app goes on it`);
+  await reached(runner);
+  said(`Packaging ${nameOf(layout)} for ${device.name}…`);
+  const made = packageFor(layout, device, integration), folder = made.folder;
+  let waited = false;
+  runner.onWaiting = () => { if (!waited) said(`Waiting for ${device.name} to finish with it…`); waited = true; };
+  const values = valuesOf(layout, made.identity), files = { package: join(folder, "package.msix"), certificate: join(folder, "certificate.cer") };
+  // The copy on the device now is ended first: a device can fail to open a package installed over its running copy.
+  const before = installed(layout, device);
+  if (opens && bridge.stop && before) await runner.run(bridge.stop, { extra: valuesOf(layout, before) }).catch(() => {});
+  // A setting the install changes for itself (an Xbox's "treat apps as games") stays changed until the app has been
+  // opened: the console settles the package's type then.
+  const changed = [];
+  const stillInstalling = `The ${integration.name} is still finishing installing ${nameOf(layout)}. Try again in a moment.`;
+  said(`Installing it on ${device.name} (${(made.bytes / 1_000_000).toFixed(1)} MB)…`);
+  for (let tries = 0; ; tries++) {
+    try {
+      // Noted as on its way before the upload, and as the installed one only once the device took it: an install cut
+      // short may still land on the device, and a removal then names both.
+      writeFileSync(join(folder, "pending.json"), JSON.stringify(made.identity));
+      await runner.run(bridge.install, { extra: values, files, changed });
+      writeFileSync(join(folder, "installed.json"), JSON.stringify(made.identity));
+      rmSync(join(folder, "pending.json"), { force: true });
+      if (opens && bridge.launch?.length) {
+        said(`Opening it…`);
+        waited = false;
+        const opened = await runner.open(bridge.launch, bridge.running, { extra: values, changed });
+        if (!opened.opened) {
+          throw new Problem(opened.launched
+            ? `The ${integration.name} is still finishing installing ${nameOf(layout)}, or it closed as it opened. Try again in a moment.`
+            : stillInstalling + (opened.refused ? `\n${opened.refused}` : ""));
+        }
+      }
+      break;
+    } catch (error) {
+      if (dropped(error) && tries < 2) { await sleep(3000); continue; }
+      await runner.putBack(changed);
+      if (error instanceof StillWorking) throw new Problem(stillInstalling);
+      throw error;
+    }
+  }
+  await runner.putBack(changed);
+  return { ...made, opened: opens && !!bridge.launch?.length, name: nameOf(layout) };
+}
+
+/**
+ * The device's screen now, kept as a picture in lamp's folder, with whether the app is the one open there and what
+ * it last logged: the only word from the device of how the page runs on it.
+ */
+export async function lookOn(layout, device, { runner } = {}) {
+  runner ??= new Runner({ integration: integrationOf(device.integration), device });
+  const bridge = runner.integration.bridge ?? {};
+  await reached(runner);
+  const mine = installed(layout, device), values = valuesOf(layout, mine);
+  const seen = { device: device.name, installed: !!mine, running: null, picture: null, log: null };
+  if (mine && bridge.running) seen.running = await openNow(runner, values);
+  if (bridge.look) {
+    const picture = (await runner.run(bridge.look, { extra: values })).picture;
+    if (picture?.length) {
+      const kind = picture.subarray(0, 3).equals(Buffer.from([0xff, 0xd8, 0xff])) ? "jpg" : "png";
+      seen.picture = join(buildFolder(layout, device), `look.${kind}`);
+      mkdirSync(dirname(seen.picture), { recursive: true });
+      writeFileSync(seen.picture, picture);
+      seen.size = kind === "png" ? sizeOf(picture) : null;
+    }
+  }
+  if (mine && bridge.log) seen.log = await runner.run(bridge.log, { extra: values }).then((outcome) => outcome.log ?? "", (error) => { if (error instanceof Problem) return null; throw error; });
+  return seen;
+}
+
+/** Whether the app is open on the device now, asked once: not whether it opens in a while. */
+function openNow(runner, values) {
+  const once = runner.integration.bridge.running.map((action) => (action.http ? { http: { ...action.http, until: undefined } } : action));
+  return runner.run(once, { extra: values }).then(() => true, (error) => { if (error instanceof Problem && !(error instanceof Away)) return false; throw error; });
+}
+
+/** Ends the app on the device; false when lamp never put it there. */
+export async function stopOn(layout, device, { runner } = {}) {
+  runner ??= new Runner({ integration: integrationOf(device.integration), device });
+  const bridge = runner.integration.bridge ?? {}, mine = installed(layout, device);
+  if (!mine || !bridge.stop) return false;
+  await reached(runner);
+  const values = valuesOf(layout, mine);
+  try {
+    await runner.run(bridge.stop, { extra: values });
+  } catch (error) {
+    // A device refuses to end an app that isn't open (an Xbox answers that it failed to): that's stopped already.
+    if (!(error instanceof Problem) || error instanceof Away || !bridge.running || (await openNow(runner, values))) throw error;
+    return true;
+  }
+  // A device goes on listing an app for a while after it's told to end it (an Xbox, about fifteen seconds): waited
+  // for, so a look right after says what's so.
+  for (let tries = 0; bridge.running && tries < 25 && (await openNow(runner, values)); tries++) await runner.pause(1000);
+  return true;
+}
+
+/** Takes the app off the device: the copy it took, and one that was on its way and may have landed. False when lamp never put it there. */
+export async function removeFrom(layout, device, { runner } = {}) {
+  runner ??= new Runner({ integration: integrationOf(device.integration), device });
+  const bridge = runner.integration.bridge ?? {}, folder = buildFolder(layout, device);
+  if (!bridge.remove) throw new Problem(`${device.name}'s integration doesn't say how an app comes off it`);
+  if (!readJSON(join(folder, "installed.json")) && !readJSON(join(folder, "pending.json"))) return false;
+  await reached(runner);
+  const asked = new Set();
+  let removed = false;
+  for (const record of ["installed.json", "pending.json"]) {
+    const identity = readJSON(join(folder, record));
+    if (!identity || asked.has(namesOf(identity).fullName)) continue;
+    asked.add(namesOf(identity).fullName);
+    const values = valuesOf(layout, identity);
+    if (bridge.stop) await runner.run(bridge.stop, { extra: values }).catch(() => {});
+    // The copy that was only on its way may never have landed: the device saying so is no failure.
+    if (record === "installed.json") await runner.run(bridge.remove, { extra: values });
+    else await runner.run(bridge.remove, { extra: values }).catch(() => {});
+    removed = true;
+    rmSync(join(folder, record), { force: true });
+  }
+  return removed;
+}