@lampdotdev/lamp 0.0.0-stage → 0.35.0

package/cli/network.mjs

@@ -0,0 +1,209 @@
+// Everything on the person's home network, one record per address, for when they're looking for devices: SSDP and the
+// integrations find what Lamp can work with (devices.mjs); this finds the rest, so a list can say what else is there.
+// It only reads: one small datagram to each address of this computer's own subnet, so its neighbor table fills (a
+// phone that ignores everything else still answers ARP), that table, and every Bonjour service on the network
+// (mdns.mjs). And the TVs: what a Samsung or an LG TV says of itself. Nothing is kept on disk: the names a network
+// holds are often people's ("…'s iPhone").
+
+import { execFile } from "node:child_process";
+import dgram from "node:dgram";
+import { readFileSync } from "node:fs";
+import { networkInterfaces } from "node:os";
+import { isPrivate, onNetwork, ownAddresses, send, xmlAt } from "./devices.mjs";
+import { everything } from "./mdns.mjs";
+
+const sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+
+/** What a system program says, or "" when it says nothing (it isn't there, or it failed). Never through a shell. */
+const said = (file, args) => new Promise((done) => execFile(file, args, { timeout: 5000 }, (error, out) => done(error ? "" : String(out))));
+
+// MARK: The subnet
+
+/** An IPv4 address as a number, or null. */
+export function valueOf(address) {
+  const parts = String(address).split(".");
+  if (parts.length !== 4 || !parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) < 256)) return null;
+  return parts.reduce((value, part) => (value * 256) + Number(part), 0);
+}
+const textOf = (value) => [24, 16, 8, 0].map((shift) => Math.floor(value / 2 ** shift) % 256).join(".");
+
+/**
+ * The subnet to sweep for an address and its mask: no more than the 256 addresses around this computer's on a bigger
+ * network, and none for an address that isn't on a home network.
+ */
+export function subnetOf(address, netmask) {
+  const mine = valueOf(address), mask = valueOf(netmask);
+  if (mine === null || mask === null) return null;
+  const actual = [...mask.toString(2)].filter((bit) => bit === "1").length;
+  if (actual < 8 || actual > 30 || !onNetwork(address)) return null;
+  const prefix = Math.max(actual, 24), size = 2 ** (32 - prefix);
+  return { network: textOf(mine - (mine % size)), prefix, actualPrefix: actual, mine: address };
+}
+
+const inSubnet = (subnet, address) => {
+  const value = valueOf(address), size = 2 ** (32 - subnet.prefix);
+  return value !== null && value - (value % size) === valueOf(subnet.network);
+};
+
+/** The default route: the interface it uses and the gateway it goes through. Null when there's none. */
+export async function defaultRoute() {
+  if (process.platform === "darwin") {
+    const text = await said("/sbin/route", ["-n", "get", "default"]);
+    const gateway = /^\s*gateway:\s*(\S+)/m.exec(text)?.[1], name = /^\s*interface:\s*(\S+)/m.exec(text)?.[1];
+    return name ? { interface: name, gateway: valueOf(gateway) === null ? null : gateway } : null;
+  }
+  if (process.platform === "linux") {
+    let table = "";
+    try { table = readFileSync("/proc/net/route", "utf8"); } catch { return null; }
+    for (const line of table.split("\n").slice(1)) {
+      const [name, destination, gateway, flags] = line.trim().split(/\s+/);
+      if (destination !== "00000000" || !(parseInt(flags, 16) & 2)) continue;
+      const bytes = gateway.match(/../g)?.reverse().map((byte) => parseInt(byte, 16));
+      return { interface: name, gateway: bytes?.length === 4 ? bytes.join(".") : null };
+    }
+  }
+  return null;
+}
+
+/** The subnet of the interface the default route uses, when it's a home network's. */
+export function subnetOn(name) {
+  const entry = (networkInterfaces()[name] ?? []).find((address) => address.family === "IPv4" && !address.internal);
+  return entry ? subnetOf(entry.address, entry.netmask) : null;
+}
+
+/** One datagram to each address of the subnet (one byte to the discard port, which nothing answers), a few at a time, paced, then a moment for the answers to ARP. */
+export async function sweep(subnet, { batch = 16, pause = 25, settle = 1500 } = {}) {
+  const socket = dgram.createSocket("udp4"), size = 2 ** (32 - subnet.prefix), network = valueOf(subnet.network);
+  socket.on("error", () => {});
+  await new Promise((done) => socket.bind(0, done));
+  const addresses = [];
+  for (let offset = 1; offset < size - 1; offset++) if (textOf(network + offset) !== subnet.mine) addresses.push(textOf(network + offset));
+  try {
+    for (let start = 0; start < addresses.length; start += batch) {
+      for (const address of addresses.slice(start, start + batch)) socket.send(Buffer.from([0]), 9, address, () => {});
+      await sleep(pause);
+    }
+    await sleep(settle);
+  } finally { try { socket.close(); } catch {} }
+}
+
+/** A hardware address with two digits to each part ("ae:b0:a9:01:eb:44"); null for a multicast or broadcast one, or none. */
+function hardware(text) {
+  const parts = String(text).toLowerCase().split(":");
+  if (parts.length !== 6 || !parts.every((part) => /^[0-9a-f]{1,2}$/.test(part))) return null;
+  const mac = parts.map((part) => part.padStart(2, "0"));
+  if (parseInt(mac[0], 16) & 1 || mac.every((part) => part === "ff")) return null;
+  return mac.join(":");
+}
+
+/**
+ * This computer's neighbor table: each neighbor's IPv4 address and hardware address, for those that answered. macOS
+ * shows it only to a process it lets on the local network: run on the runtime Lamp's app carries, it's empty, so
+ * Lamp's app reads its own (`Neighbours`).
+ */
+export async function neighbours() {
+  const table = {};
+  if (process.platform === "darwin") {
+    for (const [, address, mac] of (await said("/usr/sbin/arp", ["-an"])).matchAll(/\((\d+\.\d+\.\d+\.\d+)\) at ([0-9a-fA-F:]+) on /g)) {
+      const known = hardware(mac);
+      if (known) table[address] = known;
+    }
+  } else if (process.platform === "linux") {
+    let text = "";
+    try { text = readFileSync("/proc/net/arp", "utf8"); } catch {}
+    for (const line of text.split("\n").slice(1)) {
+      const [address, , flags, mac] = line.trim().split(/\s+/);
+      const known = (parseInt(flags, 16) & 2) && hardware(mac);
+      if (known && valueOf(address) !== null) table[address] = known;
+    }
+  }
+  return table;
+}
+
+/**
+ * The hosts of this computer's subnet, each with its hardware address and its Bonjour services, from a sweep, the
+ * neighbor table and every Bonjour service, browsed while the sweep runs. `swept` says which subnet was swept: on a
+ * network bigger than a /24 only the 256 addresses around this computer's are.
+ */
+export async function homeNetwork({ seconds = 3 } = {}) {
+  const services = everything({ seconds });
+  const route = await defaultRoute(), subnet = route ? subnetOn(route.interface) : null;
+  if (subnet) await sweep(subnet);
+  const table = await neighbours(), mine = ownAddresses();
+  const inside = (address) => (subnet ? inSubnet(subnet, address) : isPrivate(address)) || mine.has(address);
+  const hosts = new Map(), hostAt = (address) => hosts.get(address) ?? hosts.set(address, { address, mac: null, services: [] }).get(address);
+  for (const [address, mac] of Object.entries(table)) if (inside(address)) hostAt(address).mac = mac;
+  for (const { service, addresses } of await services) for (const address of addresses) if (inside(address)) hostAt(address).services.push(service);
+  for (const host of hosts.values()) {
+    host.isThisMac = mine.has(host.address);
+    host.isGateway = host.address === route?.gateway;
+  }
+  return { hosts: [...hosts.values()].sort((a, b) => (valueOf(a.address) ?? Infinity) - (valueOf(b.address) ?? Infinity)), swept: subnet, gateway: route?.gateway ?? null };
+}
+
+// MARK: TVs
+
+/** The service an LG TV announces for itself; the description it points at is the TV's own. */
+export const LG_TV = "urn:lge:device:tv:1";
+
+/** A page on the TV, read with every guard a request to a device has: its body, or null. */
+const fetched = (address) => (request) => send(request, address, {}, { timeout: 3000 }).then((answer) => (answer.status === 200 ? answer.body : null), () => null);
+
+/** A Samsung TV's own description of itself, from its local API; null when it isn't one. */
+export async function samsungAt(address, { get = fetched(address) } = {}) {
+  let device;
+  try { device = JSON.parse(String(await get({ port: 8001, path: "/api/v2/" }))).device; } catch { return null; }
+  if (device?.OS !== "Tizen") return null;
+  const modelID = typeof device.modelName === "string" ? device.modelName : "", frame = device.FrameTVSupport === "true";
+  // The size is in the model code (QN50…, UN65…).
+  const size = /^\d{2}$/.test(modelID.slice(2, 4)) ? modelID.slice(2, 4) : "";
+  const model = frame ? `The Frame${size ? ` ${size}` : ""}` : size ? `Smart TV ${size}` : modelID;
+  // The year is the first part of its internal model ("22_PONTUSM_FTV"), and each year has one Tizen.
+  const year = Number(String(device.model ?? "").slice(0, 2)) || 0;
+  const tizen = { 17: "3.0", 18: "4.0", 19: "5.0", 20: "5.5", 21: "6.0", 22: "6.5", 23: "7.0", 24: "8.0", 25: "9.0", 26: "10.0" }[year] ?? "";
+  const id = String(device.id ?? device.duid ?? address).replace("uuid:", "");
+  return { id: `samsung:${id}`, maker: "Samsung", name: typeof device.name === "string" ? device.name : "Samsung TV", model, modelID, address, os: "Tizen",
+    osVersion: tizen, resolution: typeof device.resolution === "string" ? device.resolution : "", frame,
+    developerIP: typeof device.developerIP === "string" ? device.developerIP : null, developerMode: device.developerMode === "1" };
+}
+
+/**
+ * An LG TV, from the UPnP descriptions its answers point at. It answers for several services, each with a
+ * description and an id of its own, and the first to answer is often one that says nothing of the TV (a streaming
+ * service's, a few bytes of "status=ok"), so each is tried until one is an LG TV's: the TV's own service first, which
+ * gives it the same id at every search. `udns` is every id it answered for, so a TV kept under another one is known.
+ */
+export async function lgAt(address, answers, { get = fetched(address) } = {}) {
+  const locations = [];
+  const own = answers.filter((answer) => String(answer.target).toLowerCase() === LG_TV).map((answer) => answer.location);
+  for (const location of [...own, ...answers.map((answer) => answer.location)]) {
+    let url;
+    try { url = new URL(location); } catch { continue; }
+    if (url.hostname === address && url.protocol === "http:" && !locations.includes(location)) locations.push(location);
+  }
+  // A USN is "uuid:<udn>" or "uuid:<udn>::<type>".
+  const udns = new Set(answers.map((answer) => String(answer.usn)).filter((usn) => usn.toLowerCase().startsWith("uuid:")).map((usn) => usn.slice(5).split("::")[0]).filter(Boolean));
+  for (const location of locations) {
+    const url = new URL(location), body = await get({ port: Number(url.port) || 80, path: (url.pathname || "/") + url.search });
+    if (!body) continue;
+    const tag = (name) => xmlAt(body, name) ?? null;
+    if (!(tag("manufacturer") ?? "").toUpperCase().startsWith("LG")) continue;
+    const udn = (tag("UDN") ?? address).replace("uuid:", "");
+    return { id: `lg:${udn}`, maker: "LG", name: tag("friendlyName") ?? "LG TV", model: tag("modelName") ?? "webOS TV", modelID: tag("modelNumber") ?? "",
+      address, os: "webOS", osVersion: "", resolution: "", udns: [...new Set([...udns, udn])].sort() };
+  }
+  return null;
+}
+
+/** The TVs among a search's answers, each asked who it is: one whose answers say Samsung, or webOS or LG. */
+export async function tvsIn(answers, { get } = {}) {
+  const byAddress = new Map();
+  for (const answer of answers) byAddress.set(answer.address, [...(byAddress.get(answer.address) ?? []), answer]);
+  const read = await Promise.all([...byAddress].map(([address, said]) => {
+    const words = said.map((answer) => `${answer.server}\n${answer.location ?? ""}\n${answer.target}`).join("\n").toLowerCase();
+    if (words.includes("samsung")) return samsungAt(address, get ? { get } : {});
+    if (words.includes("webos") || words.includes("lge")) return lgAt(address, said, get ? { get } : {});
+    return null;
+  }));
+  return read.filter(Boolean).filter((tv, index, all) => all.findIndex((other) => other.id === tv.id) === index);
+}

package/cli/outside.mjs

@@ -0,0 +1,140 @@
+// Lamp's app, reached the way the person's own coding agent reaches it (`OutsideServer`, Lamp's MCP endpoint): a Unix
+// socket in that Lamp's own folder, private to the person, a hello line each way, then JSON-RPC a line at a time. lamp
+// asks it to take a Mac app's folder on (`open_project`, which Lamp reviews with the person first), to put each change
+// into the app it has open (`apply_change`, which says how it went in: live, held for a Reload, reopened…), and to
+// look at it (`look_at_app`). What a change does to an open app is Lamp's app's to work out (`LiveReload`); this only
+// carries the folder's path there and the answer back.
+
+import { createConnection } from "node:net";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { Problem, stateOf } from "./state.mjs";
+
+// The handshake's version, as Lamp's helper sends it (`OutsideKit.protocolVersion`).
+const PROTOCOL = 1;
+
+/** What a Lamp is called where its folders are, by its bundle id (`OutsideKit.editionName`). */
+export function editionName(bundle) {
+  if (bundle === "dev.lamp.host.dev" || bundle.startsWith("dev.lamp.host.dev.")) {
+    const instance = bundle.startsWith("dev.lamp.host.dev.") ? bundle.slice("dev.lamp.host.dev.".length) : "";
+    return "Lamp Dev" + (instance ? ` ${instance}` : "");
+  }
+  return bundle === "dev.lamp.host.nightly" ? "Lamp Nightly" : "Lamp";
+}
+
+const socketOf = (bundle) => join(homedir(), "Library", "Application Support", editionName(bundle), "MCP", "lamp.sock");
+
+/** The Lamps lamp looks for, in order: the one LAMP_APP names (a bundle id), else the release and then Lamp Nightly. */
+const candidates = () => process.env.LAMP_APP ? [process.env.LAMP_APP] : ["dev.lamp.host", "dev.lamp.host.nightly"];
+
+/**
+ * A connection to a running Lamp, greeted: `call(tool, args)` answers what the tool said (its outcome, its words and
+ * its pictures). Null when no Lamp lamp knows of is answering.
+ */
+export async function reachLamp(bundles = candidates()) {
+  for (const bundle of bundles) {
+    if (!/^dev\.lamp\.host(\.[A-Za-z0-9-]+)*$/.test(bundle) || !existsSync(socketOf(bundle))) continue;
+    const lamp = await connected(bundle).catch(() => null);
+    if (lamp) return lamp;
+  }
+  return null;
+}
+
+function connected(bundle) {
+  return new Promise((done, failed) => {
+    const socket = createConnection(socketOf(bundle));
+    let buffer = "", greeted = false, next = 1, ended = null;
+    const waiting = new Map();
+    // Once the connection is gone, every call is refused with why, those under way and those asked later alike.
+    const fail = (problem) => {
+      ended ??= problem;
+      for (const { failed: no } of waiting.values()) no(problem);
+      waiting.clear();
+      failed(problem);
+    };
+    socket.setEncoding("utf8");
+    socket.on("error", (error) => fail(new Problem(`couldn't reach ${editionName(bundle)}: ${error.message}`)));
+    socket.on("close", () => fail(new Problem(`${editionName(bundle)} closed the connection`)));
+    socket.on("connect", () => socket.write(JSON.stringify({ lamp_hello: { protocol: PROTOCOL, client: "lamp" } }) + "\n"));
+    const send = (method, params) => new Promise((answered, no) => {
+      if (ended) return no(ended);
+      const id = next++;
+      waiting.set(id, { answered, failed: no });
+      socket.write(JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n");
+    });
+    socket.on("data", async (chunk) => {
+      buffer += chunk;
+      for (let at; (at = buffer.indexOf("\n")) >= 0; ) {
+        const line = buffer.slice(0, at);
+        buffer = buffer.slice(at + 1);
+        if (!line.trim()) continue;
+        let said;
+        try { said = JSON.parse(line); } catch { continue; }
+        if (!greeted) {
+          if (said.lamp_hello?.error) { socket.destroy(); return failed(new Problem(said.lamp_hello.error)); }
+          if (!said.lamp_hello) { socket.destroy(); return failed(new Problem(`${editionName(bundle)} didn't answer as Lamp does`)); }
+          greeted = true;
+          try {
+            await send("initialize", { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "lamp", version: "1" } });
+            socket.write(JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }) + "\n");
+          } catch (error) { return failed(error); }
+          done({
+            name: editionName(bundle), bundle,
+            async call(tool, args) {
+              const result = await send("tools/call", { name: tool, arguments: args });
+              return answerOf(result);
+            },
+            close() { ended ??= new Problem("the connection to Lamp was closed"); socket.removeAllListeners("close"); socket.end(); },
+          });
+          continue;
+        }
+        const one = waiting.get(said.id);
+        if (!one) continue;
+        waiting.delete(said.id);
+        if (said.error) one.failed(new Problem(said.error.message ?? "Lamp refused it"));
+        else one.answered(said.result ?? {});
+      }
+    });
+  });
+}
+
+/** A tool's answer as lamp reads it: the outcome its words lead with, the words after it, and its pictures. */
+export function answerOf(result) {
+  const content = Array.isArray(result?.content) ? result.content : [];
+  const text = content.filter((part) => part.type === "text").map((part) => part.text).join("\n");
+  const outcome = /^Outcome: ([a-z_]+)\./.exec(text)?.[1] ?? null;
+  // The facts are one line of JSON under the outcome: kept for whoever reads them, out of the words.
+  const lines = text.split("\n");
+  let facts = {};
+  if (outcome && lines[1]?.startsWith("{")) { try { facts = JSON.parse(lines[1]); } catch {} }
+  const words = (outcome ? lines.slice(lines[1]?.startsWith("{") ? 2 : 1) : lines).join("\n").trim();
+  const pictures = content.filter((part) => part.type === "image" && part.data).map((part) => Buffer.from(part.data, "base64"));
+  return { outcome, facts, words, pictures, failed: result?.isError === true };
+}
+
+// MARK: Which folders are Lamp's app's
+
+const markOf = (folder) => join(stateOf(folder), "in-lamp.json");
+
+/** The Lamp a folder was given to (`lamp open --in-lamp`), by its bundle id, or null for one lamp runs itself. */
+export function givenTo(folder) {
+  try { return JSON.parse(readFileSync(markOf(folder), "utf8")).bundle ?? null; } catch { return null; }
+}
+
+export function giveTo(folder, bundle) {
+  mkdirSync(stateOf(folder), { recursive: true });
+  writeFileSync(markOf(folder), JSON.stringify({ bundle }));
+}
+
+export function takeBack(folder) { rmSync(markOf(folder), { force: true }); }
+
+/** The pictures an answer brought, kept where lamp keeps a look's, by their paths. */
+export function keepPictures(folder, pictures) {
+  mkdirSync(stateOf(folder), { recursive: true });
+  return pictures.map((bytes, n) => {
+    const path = join(stateOf(folder), `lamp-look${n ? `-${n + 1}` : ""}.png`);
+    writeFileSync(path, bytes);
+    return path;
+  });
+}

package/cli/page.js

@@ -0,0 +1,165 @@
+// 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);
+  // 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);
+
+  // 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: said }, 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); };
+  }
+  // A page with the game runtime logs its own errors; any other page's are logged here.
+  addEventListener('error', e => { if (!window.__lampLive) say('error', [e.message + ' (' + (String(e.filename || '').split('/').pop() || 'the page') + ':' + e.lineno + ')']); });
+  addEventListener('unhandledrejection', e => { if (!window.__lampLive) say('error', [String(e.reason && e.reason.message || e.reason)]); });
+  addEventListener('load', () => said({ state: 'page-loaded' }));
+
+  // 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);
+    // A game takes the change and keeps the player's place; any other page opens again.
+    let taken = false;
+    try { taken = !!(window.__lampLive && window.__lampLive(change)); } catch (e) {}
+    if (!taken) { 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 (window.__lampLive) {
+      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: !!window.__lampLive, 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';
+  };
+})();