@lampdotdev/lamp 0.35.0 → 0.36.2-nightly.16

package/README.md

@@ -16,10 +16,10 @@ Mac app, `projectOf`), or any folder with an `index.html`; without one, the fold
 | Command | What it does |
 | --- | --- |
 | `lamp new <folder> [--name "Its Name"] [--web \| --mac]` | Makes a new web game's folder from Lamp's starting files, or with `--web` a new web app's, or with `--mac` a new Mac app in Swift. |
-| `lamp init [--update]` | Puts Lamp's game runtime beside a page that's already there, changing none of the page's own files. |
+| `lamp init [--update]` | Puts Lamp's game runtime beside a page that's already there, changing none of the page's own files. `--update` writes again the Lamp files the folder has (`lamp.js` too), adding the game's only to a page that's a game already. |
 | `lamp unpack <file.lampapp> [folder]` | Unpacks a Lamp app file into a new folder beside it, named for it. A file carries none of Lamp's own files: a page gets them beside it as it's unpacked (the runtime for a game, lamp.js, the libraries its import map names), and a Mac app gets Package.swift, build.sh and LampSupport.swift from Lamp's starting files as it's first built (`writeMacStarter`), where it has none. One with a widget, a share extension or a 3D scene is left to Lamp's app, which writes the files they're built with. |
-| `lamp export [--to file] [--anyway]` | Makes the app's Lamp app file as Lamp's Share… does (`Sharing.export`, followed by `cli/lampapp.mjs`): its own files as its kind travels, Assets/, APP.md, what it declares, its credits with the app added to the chain, the licenses they name, its icon's design and lamp-app.json, never Lamp's own files. Refused when a license its credits name is gone or something in it is shaped like a key; `--anyway` sends work its credits give no license for. |
-| `lamp dev [--open] [--lan] [--port N]` | Runs the page and says how each change went. Each save goes into every open copy of it. `--open` opens a window for it; `--lan` lets other devices on the network open it. |
+| `lamp export [--to file] [--anyway]` | Makes the app's Lamp app file as Lamp's Share… does (`Sharing.export`, followed by `cli/lampapp.mjs`): its own files as its kind travels, Assets/, APP.md, what it declares, its credits with the app added to the chain, the licenses they name, its icon's design and lamp-app.json, never Lamp's own files. Refused when a license its credits name is gone or something in it is shaped like a key; `--anyway` sends work its credits give no license for. The shapes of keys, the names a license goes by and the sizes another Lamp opens are in `Resources/share-rules.json`, which Lamp's app reads too (`ShareRules`). |
+| `lamp dev [--open] [--lan] [--port N]` | Runs the page and says how each change went. Each save goes into every open copy of it, with the card Lamp's app puts on an app taking a change (`page.js`, left out of lamp's pictures; `lamp changing "<words>"` says on it what's changing). `--open` opens a window for it; `--lan` lets other devices on the network open it. |
 | `lamp open` | Shows the page in a window, running it in the background if it isn't running, and returns at once. |
 | `lamp open --in-lamp` | Gives a Mac app to Lamp's app (`cli/outside.mjs`), over the socket the person's own coding agent uses (`OutsideServer`, `OutsideWork`): `open_project` takes the folder on, with Lamp's review the first time, and from then on `look`, `reload` and `dev` call `apply_change`, so a change goes into the open app as Lamp's app puts it there (`LiveReload`) and its outcome is said: live, held, reopened, not_built, crashed. `use` calls `use_app`, in plain sight in the app Lamp's app has open, and `stop` calls `close_app`. A folder Lamp's app no longer has (its refusal says `taken_on: false`) is lamp's own again, said once. `lamp open --here` has lamp run its own copy again. `LAMP_APP` names another Lamp by its bundle id (a Lamp Dev instance). A Mac app `lamp new --mac` makes has the `lamp-app.json` Lamp's app takes a folder on by. |
 | `lamp look [--reopen] [--wait s] [--json]` | How the changes since the last look went, a picture of the page, its screen as text, new errors and the log. `--reopen` opens the page again from its beginning first. |
@@ -27,12 +27,17 @@ Mac app, `projectOf`), or any folder with an `index.html`; without one, the fold
 | `lamp reload [--fresh]` | Opens the page again from its files, a game from where the player is, or with `--fresh` from its beginning (`window.lampFreshStart`). |
 | `lamp stop` | Stops running it. |
 | `lamp share --words "…"` | Puts the page on lamp.dev: anyone with the link plays it there and can send an idea. Again, it sends the page as it is now to the same link. |
-| `lamp ideas [in <n> \| dismiss <n>]` | The ideas people playing the link have sent, and saying what became of one. |
+| `lamp share` (a page of Lamp's) | A web app or game in a Lamp's own folder is lamp's to share like any other page, Lamp open or not, to the link that Lamp keeps for it: lamp takes the link from the Lamp's `Wish Links.json` (by the app's instance id in `.lamp/meta.json`, `lampsKeptLink`) the first time, and tells it what went after each share or `unshare` (`keepInLamp`), so its Share Link card shows the link as it is. `ideas` and `unshare` take the link the same way. |
+| `lamp share` (any other app of Lamp's) | For a folder in Lamp's own (or a link to one) that lamp doesn't share as a page, shared by Lamp's app over its socket (`share_link`, `OutsideWork`): its Share Link card filled as it fills itself (`WishLinkCards.prepare`: the link's last words, the questions and what's new Lamp writes, the app's file, the GitHub release) and shared without its window, with `--line`, `--by`, `--asks`, `--notes`, `--no-file`, `--no-github`, `--put-on-github` in place of the card's own, and `--preview` to see it first. The link's secret stays in Lamp. Which Lamp is the one whose folder it is (`lampOwning`), or the one it was given to (`lamp open --in-lamp`, `givenTo`); any other folder is lamp's to share, whatever Lamp is running, and so is a given folder when its Lamp is too old to share for lamp. |
+| `lamp ideas [in <n> \| dismiss <n> \| reply <n> \| done <n> \| email <address\|off>] [note]` | The ideas people playing the link have sent and what's been said since, saying what became of one, and answering whoever sent it. |
 | `lamp unshare` | Takes the link down. |
+| `lamp account [username] [--email address]` | The maker's account on lamp.dev, which their links go under (`lamp.dev/<username>/<app>`): with a username and an email it asks the site for one (`askAccount`), whose key lamp keeps with its state (`account.json`, by site) and sends with every share (`X-Lamp-Account`); the link in the email the site sends confirms it. With only an email that has an account, it signs in to it, with a key of its own. On its own, it says which it's signed in as. A share before the email's link is opened goes out as links always have (`/w/<id>-<name>`), and moves under the username at its next share. |
+| `lamp play <link> [--to folder] [--newest]` | Plays an app shared on lamp.dev on this computer: the link's file (`latestOf`, its `.lampapp`), unpacked as `lamp unpack` does into a folder of its own in `~/Lamp Games` (or `--to`), with Lamp's own files beside its page, then opened as `lamp open` opens any folder. Its AI is answered by `lamp dev` (`ai.mjs`) in any browser, Safari included, where a shared page can't reach the computer. lamp remembers which folder each link went into (a file for each link under `played/` in its state), so playing it again goes on where it was; `--newest` takes the link's latest version into a new folder. |
+| `lamp ai [--forget]` | Answers the AI of pages shared on lamp.dev, played in a browser on this computer, with the person's own Claude Code, Codex or OpenRouter key (`cli/local-ai.mjs`, the same answers as `ai.mjs` gives `lamp dev`), until it's stopped. It listens on this computer alone at a port lamp.js knows (`LOCAL_AI_PORT`, `NEARBY` in lamp.js), and answers only a link's own page (`<id in hex>.play.lamp.dev`, `playOrigin`): the first time a page uses the AI, the person is asked in the terminal, and the page keeps the token it's given. Whether there's an AI is answered without asking. The browser asks the person too, once, before a page may reach this computer, so the link's frame on lamp.dev is given that permission. Safari never lets the page reach it (Safari 27, checked against a stand-in on the port), so lamp.js tells someone playing in Safari to use Chrome, Lamp or `lamp play` instead. `--forget` takes back every page allowed. Lamp's app runs the same server while it's open (`sharedPages` in `calls.mjs`, `SharedPagesAI`): it asks the person in a dialog and answers with the AI they set up in Lamp, and the pages allowed are the same list; whichever of the two starts first answers. |
 | `lamp devices [add \| forget <name>]` | The person's devices lamp puts a page on: an Xbox in Developer Mode (those set up and those found on the network), and Android (lamp's emulators, and the phones, tablets and TVs plugged in with USB debugging on). `add` sets one up, a step at a time; `add android` downloads Android's tools. |
 | `lamp open --on xbox` | Packages the page, installs it on the device and opens it there. `lamp look --on xbox` is the device's screen and the app's log there, `lamp stop --on xbox` ends it, and `lamp remove --on xbox` takes it off. |
 | `lamp open --on android [--hidden]` | Builds Lamp's Android app around the page and opens it in lamp's Android emulator (`--on android-tv`: its TV emulator; a device of the person's by its name), with `look`, `stop` and `remove` as on any device, and `lamp use --on android` to tap, type and press there. `--hidden` starts the emulator with no window. |
-| `lamp setup [--remove]` | Teaches Claude Code and Codex on this computer to work this way: a skill for each. |
+| `lamp setup [--remove]` | Teaches Claude Code and Codex on this computer to work this way: a skill for each. Says so when the computer has no browser lamp can drive, which web apps and games are looked at and played in; it's advice, never a failure. |
 | `lamp guide` | What that skill says, for any other agent. |
 | `lamp blocks [Name]` | Lamp's building blocks for a Mac app, each with what it's for, or one in full: read from the app's own `Sources/LampSupport.swift`, whose comments say how each is used. |
 | `lamp skills [word]`, `lamp skill <name>` | Lamp's skills (`Resources/skills`), the one place that says which building blocks to use and how: all of them or those about a word, and one in full, put together from its sections as Lamp's app does (`cli/skills.mjs` follows `Skills.assembled`). |
@@ -46,6 +51,11 @@ runtime, so no Node is needed:
 /Applications/Lamp.app/Contents/Resources/cli/lamp setup
 ```
 
+To type `lamp` anywhere, Lamp's menu has Install Command-Line Tool… (`CommandLineTool`): it links `/usr/local/bin/lamp`
+to that copy, asking for the Mac's administrator password when Lamp can't write there itself, so the command updates
+with Lamp. A build from source or an instance names its own (`Edition.commandName`: `lamp-dev`, `lamp-dev-<instance>`).
+The launcher finds the app it's in through the link (`${0:A:h}` in `cli/lamp.sh`).
+
 On a computer without Lamp, lamp comes from npm, `npm install -g @lampdotdev/lamp` (it needs Node 20), and
 `lamp setup` sets it up the same way. From a checkout of this repository, `node cli/lamp.mjs setup`.
 
@@ -54,8 +64,17 @@ The npm package is laid out as the repository is (`scripts/npm-package.sh <versi
 site's limits for a link, and the Lamp resources lamp reads, with their licenses. A copy npm installed asks npm's
 registry for a newer one at most once a day, in a process of its own that never holds up the command, and the next
 command says so in one line, once a day, with the command that updates it (`cli/update.mjs`). It never updates itself.
-The copy in Lamp's app updates with Lamp and a checkout with its repository, so neither asks; nor does one in CI, or
-with `LAMP_NO_UPDATE_CHECK` set.
+A checkout updates with its repository, so it doesn't ask; nor does a copy in CI, or with `LAMP_NO_UPDATE_CHECK` set.
+
+lamp is also published to npm from every push to main, as `nightly` (the release workflow's `cli-nightly` job, at the
+version `scripts/cli-version.sh` gives: `0.36.2-nightly.9` for the ninth commit after 0.36.1), in minutes rather than
+the most of an hour Lamp Nightly takes. The `lamp` that Lamp's app puts on the PATH (`cli/lamp.sh`) follows it: at most
+once an hour a process of its own fetches the newest of its channel (Lamp Nightly's `nightly`, Lamp's `latest`; none for
+Lamp Dev) into `~/.lamp/cli` when it's newer than the app's own copy, checked against npm's integrity hash, and the
+launcher runs that one from then on, until the app has caught up (`~/.lamp/cli/use` names it with the app version it was
+fetched for). Lamp's app stamps its copy with the same numbering (build.sh), so the same commit compares equal. Lamp's
+own calls of lamp (`LampCLI`) always run the app's copy, so the app and what it asks of lamp never differ.
+`lamp --version` says which is running.
 
 writes one skill, [`skill/SKILL.md`](skill/SKILL.md), where each agent found on the computer reads its skills
 (`~/.claude/skills/lamp`, `~/.codex/skills/lamp`), with the command as it's run on this computer filled in. From its
@@ -72,13 +91,17 @@ names its launcher, so the agent always runs the lamp of the Lamp that's install
 
 ## How a change goes in
 
-Files are watched; a save is handed to every open page a moment later.
+Files are watched; a save is handed to every open page a moment later. `APP.md` at the page's top is the app's
+notes, never part of the page, so saving it hands nothing over; any other Markdown may be content the page loads, and is a change.
 
 - **A game made with Lamp's runtime** (`lamp-game.js` beside the page) takes it the way it does inside Lamp. The
   runtime is handed the change exactly as Lamp's app around the page hands it over (`window.__lampLive`), so nothing
   in the game differs. A module that accepts changes is swapped in while the game runs (`live`); other code runs
   again with the player where they were (`reran`); what can't go in either way opens the page again from the
   player's place (`reopened`); and a game at a moment it can't be interrupted waits for the person's Reload (`held`).
+- **A game whose page doesn't run on the runtime** (a folder with `lamp-game.js` whose page doesn't load it) takes
+  it as it does inside Lamp too, through `lamp-live.js`, given after `page.js`: a stylesheet, or a change inside one
+  method of a class a module exports, goes in while the game runs (`live`); anything else waits for Reload (`held`).
 - **Any other page** opens again.
 
 ## Lamp's own files beside a game's page
@@ -92,7 +115,7 @@ What a game's folder lacks all the same, the server gives it:
 | `lamp-device.js`, `lamp-build.js` | Made by the server: the device is a browser on any device, as a page published to the web is given, and the build is named for the files as they are. |
 | `lamp-controllers.js` | `cli/lamps/lamp-controllers.js`, the list of controllers as Lamp writes it (`Controllers.pageJS`). `CLIFilesTests` fails when the two differ, and writes the copy again when run with `LAMP_WRITE_CLI_FILES=1`. The game runtime can't load without it. |
 | `three/`, `phaser/`, `rapier/` | Lamp's copies (`Resources/WebLibraries`), for a library the page asks for and the folder has none of. |
-| `lamp.js` | Lamp's building blocks for a page (saved data, the app's files, AI through Lamp's app), as Lamp's own code writes them: `scripts/cli-files.sh` writes the file out (`cli/lamps/lamp.js`, and `lamp-for-games.js` as a game is given it, without a TV's remote; not committed, since they change often), and without it a stand-in that holds nothing. What a block asks of Lamp's app as the page runs (its AI) isn't answered here. |
+| `lamp.js` | Lamp's building blocks for a page (saved data, the app's files, AI through Lamp's app), as Lamp's own code writes them: `scripts/cli-files.sh` writes the file out (`cli/lamps/lamp.js`, and `lamp-for-games.js` as a game is given it, without a TV's remote; not committed, since they change often), and without it a stand-in that holds nothing. Its AI (`LampAI`: status, ask, act, decide) is answered by `lamp dev` itself (`ai.mjs`, through `lampGatewayHost` in `page.js`, `/__lamp/ai`, only for the page on this Mac) with the person's own Claude Code or Codex, or OpenRouter with their key in `OPENROUTER_API_KEY` (`LAMP_AI` picks one: claude, codex or openrouter; `LAMP_AI_MODEL` its model), the engines sealed as Lamp's app seals it (the same run, `complete` in ai.mjs); making pictures and hearing need Lamp's app. On a page shared on lamp.dev, Lamp's app or `lamp ai` answers it instead. |
 
 A file the page asks for that neither the folder nor Lamp has is logged as an error, since a module that imports one
 never runs and the page can't say so itself.
@@ -125,7 +148,10 @@ What it looks at:
 1. **The window `lamp open` or `lamp dev --open` opened**, when there is one: what the person sees, where they are in it.
 2. **A copy of the page with no window**, which lamp starts for itself otherwise and closes ten minutes after it was
    last looked at. It starts where the page starts.
-3. With no browser lamp can drive on the computer, **a page open in any browser** says what's on it, without a picture.
+3. With no browser lamp can drive on the computer, **a page open in any browser** says what's on it, without a picture,
+   and `lamp use` can't act in it. A look with no page open yet waits for one, as long as it's given to wait. `open`,
+   `look`, `use` and `setup` each say that Chrome, Edge, Brave or Chromium is what's missing (`noBrowser` in
+   `cli/browser.mjs`).
 
 The window and the copy are a Chromium-family browser already on the computer (Chrome, Edge, Brave, Chromium;
 `LAMP_BROWSER` names another), started with files of its own, never the person's own browser profile, and spoken to
@@ -317,7 +343,13 @@ does. A problem says its kind where Lamp's app acts on which it was: a device th
   search for one target; `probe`, whether a device is there now, as a setup step's check asks; `run`, `open`, `putBack` and `check`, an
   integration's sequences and a setup's checks on one device, with the values Lamp's app fills in (what the person
   typed, from its own store, on the call's input) and, while a call waits on the device, an event that says so; `network`, the sweep
-  of this computer's subnet and every Bonjour service (cli/mdns.mjs); and `neighbours`, the gateway and subnet now.
+  of this computer's subnet and every Bonjour service (cli/mdns.mjs); and `neighbours`, the gateway and subnet now. An app's own AI is told and read here too (cli/app-ai.mjs, which `lamp dev`'s answers use as well): `actStep`,
+  `actAsk` and `actRead`, a step of `LampAI.act` checked, what its route is asked and its answer read (`AppAct`); and
+  `decideAsk` and `decideRead`, a decision answered by a text model (`AppAI.decideByText`). Which route answers and
+  asking it stay in Lamp's app, with its keys and its models, except Claude Code and Codex, which `engineAnswer` runs
+  (`AppAI.viaEngine`), sealed, with the program and its settings Lamp's app chose, and OpenRouter, which
+  `openRouterText`, `openRouterChat`, `openRouterDecide` and `openRouterImage` ask with the person's key (cli/openrouter.mjs; `AppAI.viaOpenRouter`,
+  `AppAct.openRouterStep`).
   Two things stay in Lamp's app, since only it can see them: whether macOS lets Lamp look at all, which is
   Network.framework's to say (`DeviceProbe.localNetworkDenied`), and the neighbor table, which macOS shows only to a
   process it lets on the local network, and the runtime Lamp carries isn't one (`Neighbours`). Moving a
@@ -356,3 +388,11 @@ into a Mac app without opening it again.
 ```bash
 node --test cli/tests/*.test.mjs
 ```
+
+The nightly Mac checks also pack and install the npm tarball in a temporary folder, then run its command, read its
+guidance and create each kind of starter. To check the package without publishing it, on a Mac:
+
+```bash
+scripts/npm-package.sh 0.0.0
+node scripts/check-npm-package.mjs build/npm/lampdotdev-lamp-0.0.0.tgz
+```

package/Resources/GameKit/apple/LampPage.swift

@@ -129,11 +129,13 @@ final class LampPageGateway: NSObject, WKScriptMessageHandlerWithReply {
             }
             return LampControllers.answer(stop: stop, reply)
         }
-        Self.ask(url, body: call["body"] as? String) { status, body in replyHandler(["status": status, "body": body], nil) }
+        // The page's own wait for an answer (a status check's few seconds, an action step's ten minutes at most).
+        let timeout = min(max((call["timeout"] as? NSNumber)?.doubleValue ?? 240_000, 1_000), 600_000) / 1000
+        Self.ask(url, body: call["body"] as? String, timeout: timeout) { status, body in replyHandler(["status": status, "body": body], nil) }
     }
 
-    private static func ask(_ url: URL, body: String?, done: @escaping @MainActor @Sendable (Int, String) -> Void) {
-        var request = URLRequest(url: url, timeoutInterval: 240)
+    private static func ask(_ url: URL, body: String?, timeout: TimeInterval, done: @escaping @MainActor @Sendable (Int, String) -> Void) {
+        var request = URLRequest(url: url, timeoutInterval: timeout)
         request.httpMethod = "POST"
         request.setValue("Bearer " + LampInstall.token, forHTTPHeaderField: "Authorization")
         request.setValue("application/json", forHTTPHeaderField: "Content-Type")
@@ -686,9 +688,18 @@ final class LampPageFiles: NSObject, WKURLSchemeHandler {
     private let lock = NSLock()
     private var changed: [String: URL] = [:]
     private var gone: Set<String> = []
+    private var askedFor: Set<String> = []
 
     init(scheme: String) { self.scheme = scheme }
 
+    /// Every file of the page the page asked for since the app opened, there or not: a change says them, so a game's page
+    /// that doesn't run on the runtime tells a file it uses from one it doesn't (`LampPageLive.gameScript`), which the
+    /// page can't see itself.
+    var asked: [String] {
+        lock.lock(); defer { lock.unlock() }
+        return askedFor.sorted()
+    }
+
     func take(changed: [String: URL], gone: Set<String>) {
         lock.lock(); defer { lock.unlock() }
         self.changed = changed
@@ -722,6 +733,7 @@ final class LampPageFiles: NSObject, WKURLSchemeHandler {
         let path = url.path.isEmpty || url.path.hasSuffix("/") ? url.path + "index.html" : url.path
         let relative = String(path.drop(while: { $0 == "/" }))
         lock.lock()
+        askedFor.insert(relative)
         let newer = changed[relative], removed = gone.contains(relative)
         lock.unlock()
         if let newer { return try? Data(contentsOf: newer) }
@@ -798,13 +810,17 @@ enum LampPageGuard {
         UserDefaults.standard.set(true, forKey: done)
     }
 
+    /// The pages held to a policy, which open again when its rules change (`retirePages`).
     private static let watchers = NSMapTable<WKWebView, LampPageWatcher>.weakToStrongObjects()
+    /// Every page's watcher, kept as long as its page.
+    private static let kept = NSMapTable<WKWebView, LampPageWatcher>.weakToStrongObjects()
 
-    /// Where the page may go, decided for every navigation of its window and frames.
+    /// Where the page may go, decided for every navigation of its window and frames, and the files it opens and saves:
+    /// every page has this, since a page with no policy still picks files and saves them (`LampPageWatcher`).
     @MainActor static func watch(_ view: WKWebView, scheme: String) {
-        guard policy != nil else { return }
         let watcher = LampPageWatcher(scheme: scheme)
-        watchers.setObject(watcher, forKey: view)
+        kept.setObject(watcher, forKey: view)
+        if policy != nil { watchers.setObject(watcher, forKey: view) }
         view.navigationDelegate = watcher
         view.uiDelegate = watcher
     }
@@ -850,33 +866,98 @@ enum LampPageGuard {
     }
 }
 
-/// The page's window and frames: only the page's own address, and a link the person clicks opened in the browser once
-/// they've seen where it goes.
+/// The page's window and frames: a shared page goes only to its own address, and a link the person clicks opens in the
+/// browser once they've seen where it goes. Any page opens the person's files with a file field and saves what it
+/// downloads (a link with `download`, a Blob it made, a file the web view can't show) where the person says, as a
+/// browser does, so a plain site needs no Swift for either. A download is a request, held to what the page may fetch,
+/// never a navigation: it doesn't take a shared page anywhere.
 @MainActor final class LampPageWatcher: NSObject, WKNavigationDelegate, WKUIDelegate {
     private let scheme: String
     private var asking = false
+    /// A shared page's request to one of its sites, let go to see whether it answers with a file, and whether the person
+    /// clicked it in the page's window, so a page that comes back instead is offered to the browser as before.
+    private var trying: (url: URL, clicked: Bool)?
     init(scheme: String) { self.scheme = scheme }
 
     func webView(_ webView: WKWebView, decidePolicyFor action: WKNavigationAction,
                  decisionHandler: @escaping @MainActor @Sendable (WKNavigationActionPolicy) -> Void) {
-        guard let url = action.request.url, let policy = LampPageGuard.current,
-              !policy.allowsFrame(url, own: LampPageGuard.own(scheme)) else { return decisionHandler(.allow) }
+        guard let url = action.request.url else { return decisionHandler(.allow) }
+        let policy = LampPageGuard.current, own = LampPageGuard.own(scheme)
+        #if os(macOS)
+        if action.shouldPerformDownload, policy?.allows(url, own: own) ?? true { return decisionHandler(.download) }
+        #endif
+        guard let policy, !policy.allowsFrame(url, own: own) else { return decisionHandler(.allow) }
+        let clicked = action.targetFrame?.isMainFrame != false && Self.clicked(action)
+        #if os(macOS)
+        // A link to a file on one of the page's sites (`download` is ignored across origins): the request is one the page
+        // may make anyway, and its answer decides, saved if it's a file, never shown (`decidePolicyFor response`). A
+        // redirect elsewhere comes back here and is refused.
+        if ["http", "https"].contains(url.scheme?.lowercased() ?? ""), policy.allows(url, own: own) {
+            trying = (url, clicked)
+            return decisionHandler(.allow)
+        }
+        #endif
         decisionHandler(.cancel)
+        refused(url, clicked: clicked, over: webView)
+    }
+
+    private func refused(_ url: URL, clicked: Bool, over view: WKWebView) {
         FileHandle.standardError.write(Data("Lamp kept this shared app from opening \(url.absoluteString.prefix(300))\n".utf8))
-        if action.targetFrame?.isMainFrame != false { offer(url, for: action, over: webView) }
+        if clicked { offer(url, over: view) }
+    }
+
+    #if os(macOS)
+    /// What the web view can't show (a zip, a file sent as an attachment) is saved rather than shown as nothing. A shared
+    /// page's site answering with a page is never shown: that's refused as it would have been before the request.
+    func webView(_ webView: WKWebView, decidePolicyFor response: WKNavigationResponse,
+                 decisionHandler: @escaping @MainActor @Sendable (WKNavigationResponsePolicy) -> Void) {
+        let attachment = ((response.response as? HTTPURLResponse)?.value(forHTTPHeaderField: "Content-Disposition") ?? "")
+            .lowercased().hasPrefix("attachment")
+        let file = attachment || !response.canShowMIMEType
+        if let url = response.response.url, let policy = LampPageGuard.current,
+           !policy.allowsFrame(url, own: LampPageGuard.own(scheme)) {
+            let clicked = trying?.url == url && trying?.clicked == true
+            trying = nil
+            if file { return decisionHandler(.download) }
+            decisionHandler(.cancel)
+            return refused(url, clicked: clicked, over: webView)
+        }
+        decisionHandler(file ? .download : .allow)
     }
 
-    /// A link that opens a window of its own (target="_blank"): never a window here.
+    func webView(_ webView: WKWebView, navigationAction: WKNavigationAction, didBecome download: WKDownload) {
+        download.delegate = LampPageDownloads.shared
+    }
+
+    func webView(_ webView: WKWebView, navigationResponse: WKNavigationResponse, didBecome download: WKDownload) {
+        download.delegate = LampPageDownloads.shared
+    }
+
+    /// A file field: the person's choice of files, or folders where the field takes one, as a browser offers them.
+    func webView(_ webView: WKWebView, runOpenPanelWith parameters: WKOpenPanelParameters, initiatedByFrame frame: WKFrameInfo,
+                 completionHandler: @escaping @MainActor @Sendable ([URL]?) -> Void) {
+        let panel = NSOpenPanel()
+        panel.canChooseFiles = true
+        panel.canChooseDirectories = parameters.allowsDirectories
+        panel.allowsMultipleSelection = parameters.allowsMultipleSelection
+        panel.resolvesAliases = true
+        let chosen: (NSApplication.ModalResponse) -> Void = { answer in completionHandler(answer == .OK ? panel.urls : nil) }
+        if let window = webView.window { panel.beginSheetModal(for: window, completionHandler: chosen) } else { chosen(panel.runModal()) }
+    }
+    #endif
+
+    /// A link that opens a window of its own (target="_blank"): never a window here. Only a shared page offers it to the
+    /// browser; the person's own page does with it what it always has, nothing.
     func webView(_ webView: WKWebView, createWebViewWith configuration: WKWebViewConfiguration,
                  for action: WKNavigationAction, windowFeatures: WKWindowFeatures) -> WKWebView? {
-        if let url = action.request.url { offer(url, for: action, over: webView) }
+        if LampPageGuard.policy != nil, let url = action.request.url, Self.clicked(action) { offer(url, over: webView) }
         return nil
     }
 
     /// A website the person clicked a link to, opened in the browser once they've said yes to where it goes. Anything
     /// the page does by itself (setting its address, opening a window, a redirect) goes nowhere.
-    private func offer(_ url: URL, for action: WKNavigationAction, over view: WKWebView) {
-        guard action.navigationType == .linkActivated, Self.byPerson(action), !asking,
+    private func offer(_ url: URL, over view: WKWebView) {
+        guard !asking,
               let scheme = url.scheme?.lowercased(), ["http", "https", "mailto"].contains(scheme) else { return }
         asking = true
         LampPageGuard.ask("Open \(url.host ?? "this website")?", url.absoluteString, button: "Open", over: view) { [weak self] open in
@@ -890,6 +971,9 @@ enum LampPageGuard {
         }
     }
 
+    /// A link the person clicked.
+    private static func clicked(_ action: WKNavigationAction) -> Bool { action.navigationType == .linkActivated && byPerson(action) }
+
     /// Whether the person's own click or tap started it. WebKit says so only by a name it doesn't publish: where it isn't
     /// there, a link's being clicked is all there is to go on.
     private static func byPerson(_ action: WKNavigationAction) -> Bool {
@@ -898,6 +982,63 @@ enum LampPageGuard {
     }
 }
 
+#if os(macOS)
+/// Where a page's download goes: where the person says, in the window it came from, starting in Downloads with the name
+/// the page gave it. Nothing is saved unless they say where.
+@MainActor final class LampPageDownloads: NSObject, WKDownloadDelegate {
+    static let shared = LampPageDownloads()
+    /// Each download is written beside where it goes, under a hidden name, and takes that place only once it's whole: a
+    /// file it replaces is kept if it fails.
+    private var places: [ObjectIdentifier: (writing: URL, final: URL)] = [:]
+    /// How each download set off by Lamp's builder goes, which `use_app` tells it (`LampSaves` in LampSupport.swift).
+    private var saves: [ObjectIdentifier: LampSaves.Save] = [:]
+
+    func download(_ download: WKDownload, decideDestinationUsing response: URLResponse, suggestedFilename: String,
+                  completionHandler: @escaping @MainActor @Sendable (URL?) -> Void) {
+        let panel = NSSavePanel()
+        panel.nameFieldStringValue = suggestedFilename
+        panel.directoryURL = FileManager.default.urls(for: .downloadsDirectory, in: .userDomainMask).first
+        panel.canCreateDirectories = true
+        let chosen: (NSApplication.ModalResponse) -> Void = { answer in
+            // Kept from when its panel is answered, whenever the download began (`LampSaves.began`).
+            let save = LampSaves.began(suggestedFilename)
+            guard answer == .OK, let url = panel.url else {
+                LampSaves.ended(save, .canceled)
+                return completionHandler(nil)
+            }
+            LampSaves.chose(save, url)
+            if let save { self.saves[ObjectIdentifier(download)] = save }
+            let writing = url.deletingLastPathComponent().appendingPathComponent(".\(url.lastPathComponent).\(UUID().uuidString).download")
+            self.places[ObjectIdentifier(download)] = (writing, url)
+            completionHandler(writing)
+        }
+        if let window = download.webView?.window { panel.beginSheetModal(for: window, completionHandler: chosen) } else { chosen(panel.runModal()) }
+    }
+
+    func downloadDidFinish(_ download: WKDownload) {
+        let save = saves.removeValue(forKey: ObjectIdentifier(download))
+        guard let place = places.removeValue(forKey: ObjectIdentifier(download)) else { return }
+        let files = FileManager.default
+        do {
+            // The save panel asked before replacing a file of that name.
+            if files.fileExists(atPath: place.final.path) { _ = try files.replaceItemAt(place.final, withItemAt: place.writing) }
+            else { try files.moveItem(at: place.writing, to: place.final) }
+            LampSaves.ended(save, .saved)
+        } catch {
+            try? files.removeItem(at: place.writing)
+            LampSaves.ended(save, .notMoved(error.localizedDescription))
+            FileHandle.standardError.write(Data("A download couldn't be saved: \(error.localizedDescription)\n".utf8))
+        }
+    }
+
+    func download(_ download: WKDownload, didFailWithError error: Error, resumeData: Data?) {
+        if let place = places.removeValue(forKey: ObjectIdentifier(download)) { try? FileManager.default.removeItem(at: place.writing) }
+        LampSaves.ended(saves.removeValue(forKey: ObjectIdentifier(download)), .failed(error.localizedDescription))
+        FileHandle.standardError.write(Data("A download failed: \(error.localizedDescription)\n".utf8))
+    }
+}
+#endif
+
 /// What the page was refused, from Lamp's own world in it: into the app's log, and, for a page whose review said it may
 /// connect elsewhere, shown above it with a way to allow the site.
 @MainActor final class LampPageRefused: NSObject, WKScriptMessageHandler {
@@ -1150,8 +1291,10 @@ typealias LampPageHolderBase = UIView
 /// The web view the page is shown in: its sound and pictures without a tap first, nothing to scroll or bounce.
 @MainActor enum LampPageView {
     /// A page that logs its own errors (a game's runtime does) leaves `catchErrors` off, or each would be logged twice.
-    /// `live` takes Lamp's changes while the app is open (`LampPageLive`).
-    static func make(_ files: LampPageFiles, catchErrors: Bool = true, live: Bool = false) -> WKWebView {
+    /// `live` takes Lamp's changes while the app is open (`LampPageLive`). `gameChanges`, a game's page: one that doesn't
+    /// run on Lamp's game runtime still takes a change while it's played where it can (`LampPageLive.gameScript`), where
+    /// any other page opens again for it.
+    static func make(_ files: LampPageFiles, catchErrors: Bool = true, live: Bool = false, gameChanges: Bool = false) -> WKWebView {
         let configuration = WKWebViewConfiguration()
         configuration.setURLSchemeHandler(files, forURLScheme: files.scheme)
         // LampAI and the page's calls of this device, and its console into the app's log.
@@ -1160,6 +1303,10 @@ typealias LampPageHolderBase = UIView
         LampPageGuard.attach(to: configuration, scheme: files.scheme)
         let changes = live ? LampPageLive(files: files) : nil
         if let changes { configuration.userContentController.add(changes, contentWorld: .page, name: "lampLive") }
+        if changes != nil, gameChanges {
+            configuration.userContentController.addUserScript(WKUserScript(source: LampPageLive.gameScript, injectionTime: .atDocumentStart,
+                                                                           forMainFrameOnly: true, in: .page))
+        }
         configuration.mediaTypesRequiringUserActionForPlayback = []
         #if os(iOS)
         configuration.allowsInlineMediaPlayback = true
@@ -1217,6 +1364,8 @@ typealias LampPageHolderBase = UIView
     /// What each window's pages held when last read, by the window's number.
     private static var read: [Int: [LampScreen.Item]] = [:]
     private static let script = "{{PAGE_SCREEN_SCRIPT}}"
+    /// A click that says what it landed on, and won't click a thing named that's dimmed or under another (`PageScreen.click`).
+    private static let click = "{{PAGE_CLICK_SCRIPT}}"
 
     /// The page shown in a window, or, with none there, the first shown anywhere: what the app menu's Reload reopens.
     static func page(in window: NSWindow?) -> WKWebView? {
@@ -1228,7 +1377,7 @@ typealias LampPageHolderBase = UIView
         pages.add(view)
         LampPageItems.refresh = refresh
         LampPageItems.items = { read[$0.windowNumber] ?? [] }
-        LampPageItems.act = act
+        LampPageItems.act = { act($0, at: $1, meant: $2, in: $3, said: $4) }
         LampPageItems.own = { own($0, batch: $1) }
         LampPageItems.hold = { hold($0, in: $1, for: $2, said: $3) }
     }
@@ -1302,17 +1451,23 @@ typealias LampPageHolderBase = UIView
     ]
 
     /// A click, a key or typing on a page, carried out in the page: the point (in the window's frame view) turned into
-    /// the page's own, or, with none, whatever the page has focused while it holds the window's keyboard.
-    private static func act(_ action: LampDriver.Action, at point: NSPoint?, in window: NSWindow) -> String? {
+    /// the page's own, or, with none, whatever the page has focused while it holds the window's keyboard. A click's
+    /// outcome is the page's answer, given to `said` once it comes (with whether it clicked): what it landed on, and for
+    /// the thing `meant` (one of the page's own, as listed), whether it was that thing at all.
+    private static func act(_ action: LampDriver.Action, at point: NSPoint?, meant: LampScreen.Item?, in window: NSWindow,
+                            said: @escaping @MainActor (String, Bool) -> Void) -> String? {
         guard let frame = window.contentView?.superview ?? window.contentView else { return nil }
         let shown = pages.allObjects.filter { $0.window === window }
         let page: WKWebView, spot: String
+        var css = CGPoint.zero, zoom: CGFloat = 1
         if let point {
             guard let hit = shown.first(where: { $0.frame.contains($0.superview?.convert(point, from: frame) ?? .zero) }) else { return nil }
-            let local = hit.convert(point, from: frame), zoom = max(hit.pageZoom, 0.01)
+            let local = hit.convert(point, from: frame)
+            zoom = max(hit.pageZoom, 0.01)
             let y = hit.isFlipped ? local.y : hit.bounds.height - local.y
             page = hit
-            spot = "document.elementFromPoint(\(local.x / zoom), \(y / zoom))"
+            css = CGPoint(x: local.x / zoom, y: y / zoom)
+            spot = "document.elementFromPoint(\(css.x), \(css.y))"
         } else {
             guard let focused = shown.first(where: { page in
                 (window.firstResponder as? NSView).map { $0 === page || $0.isDescendant(of: page) } ?? false
@@ -1325,15 +1480,22 @@ typealias LampPageHolderBase = UIView
         case "click", "double_click":
             guard point != nil else { return nil }
             let clicks = action.action == "click" ? 1 : 2
-            run("""
-                var focusable = el.closest('[data-focus], button, a[href], input, select, textarea, [tabindex]') || el;
-                if (focusable.focus) focusable.focus();
-                for (var i = 0; i < \(clicks); i++) if (focusable.click) focusable.click();
-                if (\(clicks) === 2) focusable.dispatchEvent(new MouseEvent('dblclick', { bubbles: true, cancelable: true }));
-                """)
-            // Sent, not proof: a game takes a click in its own time, and may not take it at all.
-            if action.page == true { return (clicks == 1 ? "clicked" : "double-clicked") + " in the game's page; the picture shows whether the game took it" }
-            return clicks == 1 ? "clicked in the page" : "double-clicked in the page"
+            // The thing as the page's read listed it, with its box in the page's own pixels: the page clicks that very
+            // thing, once it's checked it's still there, at its middle (the point).
+            let scale = LampRuntime.scale(of: window)
+            let want = meant.map { "{ ref: \($0.ref ?? -1), w: \($0.frame.width / scale / zoom), h: \($0.frame.height / scale / zoom) }" } ?? "null"
+            page.evaluateJavaScript(click + "(\(css.x), \(css.y), \(want), \(clicks))") { answer, error in
+                MainActor.assumeIsolated {
+                    guard error == nil, let json = answer as? String,
+                          let told = try? JSONSerialization.jsonObject(with: Data(json.utf8)) as? [String: Any], let words = told["said"] as? String else {
+                        return said("the page couldn't take the click (\(error?.localizedDescription ?? "it gave no answer")), so it may not have happened", false)
+                    }
+                    let did = told["did"] as? Bool ?? false
+                    // Sent, not proof: a game takes a click in its own time, and may not take it at all.
+                    said(words + (did && action.page == true ? "; the picture shows whether the game took it" : ""), did)
+                }
+            }
+            return LampPageItems.sent
         case "type":
             let text = action.text ?? ""
             let quoted = String(decoding: (try? JSONSerialization.data(withJSONObject: [text])) ?? Data("[\"\"]".utf8), as: UTF8.self)
@@ -1423,7 +1585,7 @@ typealias LampPageHolderBase = UIView
             let role = ["button": "button", "field": "text field", "choice": "choice", "image": "picture"][kind] ?? "text"
             return LampScreen.Item(role: role, label: entry["name"] as? String ?? "", value: entry["value"] as? String ?? "",
                                    frame: CGRect(x: (box.minX + n("x")) * scale, y: (top + n("y")) * scale, width: n("w") * scale, height: n("h") * scale),
-                                   selected: entry["focused"] as? Bool ?? false)
+                                   selected: entry["focused"] as? Bool ?? false, ref: (entry["ref"] as? NSNumber)?.intValue)
         }
     }
 }
@@ -1435,7 +1597,8 @@ typealias LampPageHolderBase = UIView
 /// there's a change, or after a while with nothing), fetches the files that differ from its bundle into its caches, has
 /// `LampPageFiles` serve them in place of the bundle's, and tells the page (`window.__lampLive` in lamp-game.js), which
 /// puts new pictures, models, sounds and the code its modules take in as it runs, and opens itself again for code they
-/// don't, keeping the player's place.
+/// don't, keeping the player's place. A game's page that doesn't run on the runtime is told by `gameScript`, which puts
+/// in what it safely can and holds the rest for Reload; any other page opens again.
 /// What the page did is told back to Lamp, which says so in the chat. The files are kept for the next launch of this
 /// same bundle, so the app opens as Lamp last changed it; a new bundle (Lamp installed the app again) starts from its own.
 @MainActor final class LampPageLive: NSObject, WKScriptMessageHandler {
@@ -1444,6 +1607,9 @@ typealias LampPageHolderBase = UIView
     private(set) weak static var current: LampPageLive?
     #endif
     private let files: LampPageFiles
+    /// A game's page that doesn't run on Lamp's game runtime takes changes with this (lamp-live.js, written in by Lamp),
+    /// given to it before any script of its own; the runtime, as it loads, takes over from it.
+    static let gameScript = "{{PAGE_LIVE_SCRIPT}}"
     private weak var page: WKWebView?
     private var epoch = "", gen = 0
     private var have: [String: String] = [:]
@@ -1557,10 +1723,11 @@ typealias LampPageHolderBase = UIView
         let pageChanged = answer["changed"] as? [String] ?? []
         // Only the phone page: the game's own page has nothing to do.
         if pageChanged.isEmpty, !now { tell(next, "phone"); return }
-        let change: [String: Any] = ["gen": next, "changed": pageChanged, "removed": answer["removed"] as? [String] ?? [], "now": now, "pill": Self.place != "mac"]
+        let change: [String: Any] = ["gen": next, "changed": pageChanged, "removed": answer["removed"] as? [String] ?? [], "now": now, "pill": Self.place != "mac",
+                                     "read": files.asked]
         guard let page, let json = try? JSONSerialization.data(withJSONObject: change) else { return }
         let taken = try? await page.evaluateJavaScript("window.__lampLive ? window.__lampLive(\(String(decoding: json, as: UTF8.self))) : false", in: nil, contentWorld: .page)
-        // A page without Lamp's game runtime is opened again as it is.
+        // A page that takes no changes (a web app's, a screen's) is opened again as it is.
         if taken as? Bool != true {
             page.reload()
             tell(next, "reloading")

package/Resources/GameKit/apple/LampWebGame.swift

@@ -50,7 +50,7 @@ struct LampGameScreen: View {
 @MainActor enum LampGamePage {
     static let files = LampPageFiles(scheme: "lamp-game")
 
-    static func make() -> WKWebView { LampPageView.make(files, catchErrors: false, live: true) }
+    static func make() -> WKWebView { LampPageView.make(files, catchErrors: false, live: true, gameChanges: true) }
 }
 
 #if os(macOS)