@call-me-sensei/angelo 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hyperbond Studio Pte. Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PROTOCOL.md

@@ -0,0 +1,243 @@
+<!-- SPDX-FileCopyrightText: 2026 Hyperbond Studio Pte. Ltd. -->
+<!-- SPDX-License-Identifier: MIT -->
+
+# Angelo web live link: wire contract
+
+This is the contract between Angelo, the dev-server bridge (`@call-me-sensei/angelo/vite`) and the browser SDK
+(`@call-me-sensei/angelo`; the unscoped alias `angelo-studio` re-exports both). Angelo's side is `doc/angelo/web_link.rst`; the engine-neutral link is
+`doc/angelo/engine_link.rst`. Both halves of this package follow this file. A change here changes both.
+
+## 1. Angelo ⇄ bridge: `angelo-link/1`
+
+The bridge is an engine editor plugin like Godot's. It runs in Node, inside the developer's dev server.
+
+### Finding Angelo
+
+- **The endpoint record.** The record is `angelo-link.json` in Angelo's per-user data folder:
+  - macOS: `~/Library/Application Support/Angelo`
+  - Windows: `%LOCALAPPDATA%\Angelo`
+  - Linux and others: `$XDG_STATE_HOME/Angelo`, or `~/.local/state/Angelo`
+- **The override.** `ANGELO_LINK_RECORD` names the record instead (tests use it).
+- **Reading it.** Read the record only when it is a regular file of at most 4096 bytes. Where modes exist, it must be
+  owned by this user and carry no group or other bits. Never follow a link.
+  - JSON: `{protocol: "angelo-link/1", port, pid, token: <64 hex>, app, binary}`.
+  - Any other content counts as no record.
+- **The token.** The token is secret: never log it, print it, send it to the page or put it in an error.
+- **Polling.** Watch the record about every 2 s while disconnected. A changed record means a new Angelo: reconnect.
+
+### Frames
+
+- Each frame is a 4-byte big-endian length `n` (1 ≤ n ≤ 65536), then `n` bytes of UTF-8 JSON (the header), then
+  `header.bytes` bytes of payload when the header has `bytes`.
+- Payloads from Angelo are at most 512 MiB.
+- Non-finite numbers are invalid JSON here.
+- A malformed frame ends the connection.
+
+### Authentication (mutual HMAC-SHA256; the token never crosses the socket)
+
+1. Connect to `127.0.0.1:<port>`. Angelo sends `{type: "hello", protocol: "angelo-link/1", nonce: <64 hex>, app}`.
+2. The client sends `{type: "auth", nonce: <its own 64 hex>, proof, client}`.
+   - `proof = hex(HMAC-SHA256(key = bytes.fromhex(token), msg = "angelo-link/1/client\n" + server nonce + "\n" + client nonce))`.
+   - The message is ASCII, joined with `\n`.
+3. Angelo answers `{type: "welcome", proof}`, where `proof` is the same HMAC over `"angelo-link/1/server\n…"`.
+   - The client checks it, in constant time, before trusting anything.
+   - `{type: "error", code: "auth"}` or a wrong proof means: not Angelo, or a stale token. Stop and wait for a new
+     record.
+4. Auth must finish within 10 s.
+
+`client` in `auth` is what the editor says about itself. Angelo keeps at most 8 capabilities and 400 characters a
+field:
+
+```json
+{"engine": "web", "web": "vite 7.1.3; three 0.185.1", "plugin": "@call-me-sensei/angelo 0.1.0",
+ "capabilities": ["durable", "live", "acks", "capture"],
+ "project": "/abs/path/to/the/project", "project_name": "<package.json name, else the folder name>"}
+```
+
+`project` is the folder holding `package.json` at or above Vite's `root` (Vite's root may be a subfolder); asset paths
+are relative to it.
+
+Add `"look"` to `capabilities` only when a tracked page asked for `look: "apply"`. It is reserved: Angelo 1.0.10
+sends no look frames yet.
+
+### Liveness
+
+- Send `{type: "ping"}` every 10 s. Angelo answers `pong`.
+- Angelo drops an editor that sends nothing for 45 s.
+- The client counts Angelo lost after 60 s without any frame.
+
+### Requests (client → Angelo; headers only, never a payload except §1.1)
+
+- `{type: "open", id, project, asset, project_name, node}`
+  - `asset` is the project-relative POSIX path of a `.glb` (`"public/models/chair.glb"`).
+  - `node` is the clicked object's name, shown on the card.
+  - `id` is unique per request, at most 64 characters.
+- `{type: "close", id, asset}`
+- `{type: "status", asset, code, ...}` acknowledgements:
+  - `{code: "previewed", version, instances}`: `instances` is the number of tracked copies now showing that
+    version, summed over every tab.
+  - `{code: "preview_failed", version, message}`
+  - `{code: "reimported", save}` after the page shows the saved file of a `saved` frame, echoing its `save`.
+  - `{code: "reimport_failed", save, message}`
+  - Messages are English, at most 200 characters, and never hold a path.
+
+### Replies and pushes (Angelo → client)
+
+- `pending {id, asset}`: the person decides on a card in Angelo.
+- `opened {id?, asset}`: linked. Without an `id`, it is a broadcast to every editor of the project.
+- `refused {id, code, message}`: show `message` (English).
+  - Codes: `not_project`, `outside`, `kind`, `missing`, `engine`, `superseded`, `declined`, `failed`,
+    `unreadable`.
+- `closed {id, asset}`
+- `scene {asset, version, export_ms, kind, base?, removed?}` plus a `.glb` payload: a live frame (§1.2). It is
+  uncompressed, with images embedded and no animations.
+- `saved {asset, files, scene_version, save}`: the asset file on disk was rewritten. The page re-fetches it.
+- `status {asset, code, message}`: `edit_mode`, `export_failed`, `write_failed`, `baked_*`. Shown as notices.
+- `ended {asset, reason}`: `engine`, `angelo`, `stopped`, `replaced`, `other_file`, `saved_elsewhere`. Every reason
+  but `engine` gets a notice.
+- `capture {id, asset, max}` (§1.1).
+- `pong`
+
+### 1.2 Live frames: full and delta
+
+The page keeps every object it already has, and a live frame never rebuilds the developer's scene.
+
+**Every node** in a frame's `.glb` carries, in `extras`:
+
+- `angelo_uid`: the node's **key**. It is unique in the file and the same in every frame of one Angelo process.
+  - an object's key is its Blender `session_uid`;
+  - a bone's key is `"<armature uid>/<bone name>"`, and the exporter's extra leaf node of a bone adds `"#leaf"`;
+  - an object inside a collection instance is keyed `"<instancer key>><uid>"`.
+- `angelo_role`:
+  - `"content"`: the page applies this node;
+  - `"parent"`: present only so that a content node hangs where it belongs. The page never changes a parent node; it
+    finds it by key.
+- `angelo_digest`, on content nodes: the digest of everything the page shows for the node:
+  - its name, transform and children's keys;
+  - its mesh data and materials, with its images by digest;
+  - its skin, camera and extensions.
+
+  A content node whose digest equals the one the page already has is left untouched: no geometry, material, texture
+  or GPU work, and no event.
+
+**Images** carry `extras.angelo_digest`, the SHA-256 of their bytes. An image that every receiving page already has
+is sent as a **stub**: a 1 × 1 PNG with `extras.angelo_stub: true`. The page uses its cached texture of that digest.
+The page keeps its textures by digest for the whole link, even after the objects that used them go. A stub whose
+digest the page doesn't have means the page resyncs (below).
+
+**`kind: "full"`** holds every node, all `content`. It carries no stubs, except the full frame of a still-scene
+check (Angelo's whole export after edits pause, sent only when a digest moved), which may stub images every
+receiving page has. A page missing a stub's picture asks for a full frame, which comes with no stubs. The page
+applies a full frame by diff:
+
+- nodes it has with the same digest stay untouched;
+- changed nodes update in place;
+- new nodes are created;
+- nodes it had under the tracked asset that the frame lacks are removed.
+
+Angelo sends a full frame for a page's first frame, a resync, a page that fell behind (`LinkServer.lagging`), after
+an undo, redo or file read, and when most of the scene changed.
+
+**`kind: "delta"`** holds only the objects that changed (as `content`) plus their ancestors and the armatures their
+skins need (as `parent`).
+
+- `base` is the version it applies on.
+- `removed` lists the keys that are gone.
+- Angelo never drops a delta, and a client more than 8 deltas behind gets a full frame instead.
+- The page applies a delta only when `base` equals the version it shows. Otherwise it applies nothing and asks for
+  a full frame.
+
+**The page asks for a full frame** (page → bridge `angelo:resync {asset}`, bridge → Angelo
+`{type: "status", asset, code: "resync"}`) when a delta doesn't fit what it shows:
+
+- the `base` differs;
+- a parent key it doesn't have and the frame doesn't hold;
+- a stub digest it doesn't have.
+
+**Keys can change** across an undo or a reload: Blender may give objects new session uids. In a full frame, the
+page matches a node whose key it doesn't know by its name path from the asset root before it creates anything.
+When one matches, the existing Object3D adopts the new key, so identity survives.
+
+**Skinned meshes**: the page keeps its bone Object3Ds, always. A bone's content updates only its rest data:
+
+- its transform;
+- the skin's inverse bind matrices.
+
+A new or changed SkinnedMesh binds to the existing bones by key, so a playing AnimationMixer keeps driving them.
+
+### 1.1 Captures: the only client payload
+
+When Angelo's agent asks to see the page (`angelo_view` `image: "WEB"`), Angelo sends `capture {id, asset, max}` to
+one live editor of the linked asset. The client answers once, within 8 s, with one of:
+
+- `{type: "status", asset, code: "captured", id, bytes: <n>}` plus a PNG payload of at most 8 MiB, at most `max`
+  pixels on its longer side, from the WebGL canvas only;
+- `{type: "status", asset, code: "capture_failed", id, message}`: capture off in the config, a hidden tab, or no
+  tracked copy on screen.
+
+A payload is accepted only:
+
+- in reply to that client's outstanding `id`;
+- with `code: "captured"`;
+- when it starts with the PNG signature and fits the bound.
+
+Angelo ends the connection on any other client payload.
+
+## 2. Bridge ⇄ page
+
+The page never talks to Angelo. Events travel over Vite's HMR channel. Bytes travel over same-origin HTTP under
+`/@angelo-live/<token>/`, where `<token>` is 16 random bytes (base64url) made once per dev-server start and given to
+the page in the virtual module `virtual:angelo-live/config`.
+
+### Server → page (`server.hot.send` / `server.ws.send`; event names)
+
+- `angelo:state {link: "waiting" | "live" | "lost" | "off", message?, session}`: `session` grows when the bridge
+  links to another Angelo process (its keys mean other objects then).
+- `angelo:pending {asset}`, `angelo:opened {asset}`, `angelo:refused {asset, code, message}`
+- `angelo:scene {asset, version, session, kind, base?, removed?, url}`: `url` is that frame's `.glb`
+  (`scene/<asset-id>/<version>.glb`). The bridge keeps every delta since the last full frame, at most 8 (a delta is
+  never skipped), and passes `kind`, `base` and `removed` through unchanged.
+- `angelo:saved {asset, save, scene_version, url}`: `url` is the asset's own dev-server URL with `?angelo=<save>`.
+  A page that already shows `scene_version` changes nothing (no fetch, no upload); otherwise it applies the file by
+  the same diff.
+- `angelo:status {asset, code, message}`, `angelo:ended {asset, reason}`
+- `angelo:capture {id, asset, max}`: sent to every tab. The first good answer wins; the bridge relays it.
+
+`asset` on the page side is the URL the page loaded (`"/models/chair.glb"`). The bridge maps between that URL and the
+project path (Vite `publicDir` and `root`).
+
+### Page → server (`import.meta.hot.send`)
+
+- `angelo:hello {tab, three, tracked: [url], capture: bool, look}`
+- `angelo:track {tab, url}`, `angelo:untrack {tab, url}`
+- `angelo:edit {tab, url, node}`
+- `angelo:ack {tab, asset, code, version|save, instances, message?}`
+- `angelo:capture_failed {tab, id, message}`
+- `angelo:resync {tab, asset}`: the bridge sends Angelo `status {asset, code: "resync"}` (§1.2). A page asks once
+  per version it shows; the bridge passes at most 8 a second per asset.
+- `angelo:bye {tab}`: the page stopped its live link (a component unmounted); the bridge stops waiting for that
+  tab's answers. A closed socket says the same for every tab on it.
+
+### HTTP, under `/@angelo-live/<token>/`
+
+- `GET scene/<asset-id>/<version>.glb`: any frame the bridge still holds (the last full one and the deltas after
+  it); 404 otherwise.
+- `POST capture/<id>`: a PNG body of at most 8 MiB.
+
+Every request must pass every check, or it gets 403 or 404 with no body detail:
+
+- the socket peer is loopback (`127.0.0.1`, `::1`, `::ffff:127.0.0.1`), whatever the `Host` says;
+- `Host` is `localhost`, `127.0.0.1` or `[::1]` with the dev server's port, or one of Vite's `allowedHosts`;
+- `Sec-Fetch-Site` is `same-origin`, or `Origin` equals the dev server's own origin;
+- the path token matches (constant-time).
+
+Every response carries `Cache-Control: no-store`, `X-Content-Type-Options: nosniff`, `Referrer-Policy: no-referrer`
+and `Cross-Origin-Resource-Policy: same-origin`, and never a CORS header.
+
+## 3. Production
+
+- `@call-me-sensei/angelo` under the `production` export condition (and its default) is a no-op stub with the same
+  API. In a build the plugin also resolves the package to the stub whatever the conditions, so a build run with
+  another `NODE_ENV` can't pick up the development SDK.
+- The Vite plugin is `apply: "serve"`.
+- A production build holds no `angelo-live` route, socket or string.

package/README.md

@@ -1,3 +1,136 @@
-# Temporary Holding Version
+<!-- SPDX-FileCopyrightText: 2026 Hyperbond Studio Pte. Ltd. -->
+<!-- SPDX-License-Identifier: MIT -->
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @call-me-sensei/angelo
+
+Angelo's live link for the web: edits you make in [Angelo](https://angelo.studio) show up live in **your own**
+Three.js page, inside your lights, shaders, physics and game state. Saving in Angelo rewrites the `.glb` your page
+loads, and the page picks the new file up without reloading.
+
+It has two halves:
+
+- a **Vite plugin** that runs in your dev server and talks to Angelo on this computer;
+- a **browser SDK** that updates the objects of a tracked glTF in place, by glTF node identity.
+
+Your page never talks to Angelo. It talks only to its own dev server, over its own origin.
+
+## Install
+
+```bash
+npm i -D @call-me-sensei/angelo
+```
+
+(`angelo-studio` is an unscoped alias of the same package.) Requirements: Vite 6.0.9 or newer, three.js r172 or
+newer, Node 18.18 or newer.
+
+## Use
+
+```js
+// vite.config.js
+import { angeloLive } from "@call-me-sensei/angelo/vite";
+export default { plugins: [angeloLive()] };
+```
+
+```js
+// your page
+import { createAngeloLive } from "@call-me-sensei/angelo";
+
+const loader = new GLTFLoader(); // yours, with your Draco / meshopt / KTX2 decoders
+const live = createAngeloLive({ renderer, scene, loader });
+const gltf = await loader.loadAsync("/models/chair.glb");
+scene.add(gltf.scene);
+live.track(gltf, "/models/chair.glb");
+```
+
+In Angelo, add the link from the chat bar's + menu (Game engine live link ▸ Add Angelo Link to a web project…).
+Then **Alt-click** an object in your canvas and click **Edit chair.glb in Angelo**, or call
+`live.edit("/models/chair.glb")`. Angelo asks you on a card, and from then on its edits show in your page.
+
+### `createAngeloLive(options)`
+
+| option | default | |
+|---|---|---|
+| `renderer` | | Your `WebGLRenderer`. Alt-click picking and captures use its canvas. |
+| `loader` | required | Your `GLTFLoader` (three's or three-stdlib's). Live frames and saved files are decoded with it. |
+| `scene` | | Your scene (optional). |
+| `camera` | last camera rendered | The camera Alt-click picks with. |
+| `capture` | `true` | Let Angelo's agent ask for a picture of the canvas. `false` answers "capture is off on this page". |
+| `overlay` | `true` | The small status dot in the corner. `false` hides it. |
+| `look` | `"ignore"` | Reserved: `"apply"` will take Angelo's lighting and environment. Angelo 1.0.10 sends no look yet, so nothing is applied either way. |
+
+### `live.track(target, url)`
+
+`target` is a GLTFLoader result (the best choice: its parser tells the SDK which object is which glTF node), its
+scene, or a clone of that scene (`scene.clone()` or `SkeletonUtils.clone`). Track every copy you show: one parse of
+each live frame serves them all. `track` returns `{ untrack() }`.
+
+Other methods: `live.untrack(objectOrUrl)`, `live.edit(url, nodeName?)`, `live.on(event, listener)` (returns a function
+that removes the listener), `live.stop()` (puts everything back as saved, then stops), and `live.state`.
+
+### How updates keep your objects
+
+- **Nothing is rebuilt and the page never reloads.** Every frame is applied as a diff. An object whose content didn't
+  change keeps its geometry, material and textures, with no GPU upload and no event.
+- **Your Object3Ds stay the same objects.** So do your references to them, their `userData`, the children you added,
+  and the physics bodies and mixers that hold them. Bones are never replaced, so a playing `AnimationMixer` keeps
+  running.
+- **Angelo changes** an object's geometry, its local transform (only when Angelo moved it, so your own animation of an
+  object Angelo didn't move continues) and its name.
+- **Materials**: Angelo changes a material only when it changed it. A material you replaced stays yours. So does a
+  change you made in place to a loaded material (a colour variant), until Angelo edits that material itself.
+- **A deleted object** is removed. Children you had added to it move to the nearest remaining part of the asset,
+  keeping their world position (event `removed`, plus one console warning).
+- **New objects** arrive as the loader makes them (event `added`): apply your per-mesh setup there, for example
+  `castShadow`.
+- **Textures** are kept by content, so a picture the page already has is never decoded or uploaded again.
+- **When Angelo stops** (or `live.stop()`), the SDK puts back exactly what it changed, in place, without reloading.
+  If the dev server loses Angelo it waits 15 s before that, so a reconnect doesn't flicker.
+
+### Events
+
+`live.on(name, listener)`; the `angelo:` prefix is optional.
+
+| event | detail |
+|---|---|
+| `state` | `{link: "off" \| "waiting" \| "live" \| "lost", message, session}` |
+| `pending`, `opened` | `{asset}`: Angelo is asking on a card / the asset is open |
+| `refused` | `{asset, code, message}` |
+| `updated` | `{asset, version, frame: "full" \| "delta", instances, changed, timing: {fetch, parse, apply}}` |
+| `renamed` | `{asset, object, from, to}` |
+| `removed` | `{asset, name, moved: [your objects], to}` |
+| `added` | `{asset, objects}` |
+| `replaced` | `{asset, from, to}`: an object changed kind (a mesh became skinned), so a new Object3D took its place |
+| `saved` | `{asset, save, instances, load()}`: `load()` gives the saved file through your loader (with animations) |
+| `restored`, `ended` | `{asset, ...}`: the asset shows as saved again / Angelo stopped editing it |
+| `status`, `resync` | Angelo's notices; a frame the page asked Angelo to send again in full |
+
+## Security
+
+- The dev-server routes answer only this computer (loopback peers), whatever the `Host` says. A phone on your LAN
+  (`vite --host`) gets nothing, and the SDK switches itself off on a non-local page.
+- Each route also checks the `Host` (a loopback name or one of your `server.allowedHosts`, with the dev server's
+  port), that the request comes from the page's own origin (`Sec-Fetch-Site`/`Origin`), and a random path token made
+  for each dev-server start. The routes never send CORS headers.
+- Events travel over Vite's own HMR socket, which Vite protects with a token from 6.0.9 on. Don't turn on
+  `legacy.skipWebSocketTokenCheck`; the plugin warns if you do.
+- Angelo's endpoint record is read only when it is a small file owned by you, with no group or other permissions,
+  and never through a link. Its token never leaves the dev server's process, and the token itself never crosses the
+  socket.
+- A capture is the WebGL canvas only, never the page's DOM. It is sent only while Angelo asks, at most one at a time,
+  within 8 s, and only as a PNG of at most 8 MiB. Turn it off with `capture: false` here or `angeloLive({ capture:
+  false })`.
+- The package has no runtime dependencies and fetches nothing from the network.
+
+## Production
+
+The plugin runs on the dev server only. In a build, `@call-me-sensei/angelo` resolves to a no-op stub with the same
+API (the `production` export condition, and the plugin enforces it in builds whatever `NODE_ENV` says). A production
+build holds no Angelo route, socket or string. You can leave `createAngeloLive` and `track` in your code.
+
+## Protocol
+
+The wire contract between Angelo, the plugin and the page is [PROTOCOL.md](PROTOCOL.md).
+
+## License
+
+MIT © 2026 Hyperbond Studio Pte. Ltd.

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@call-me-sensei/angelo",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Angelo's web live link: see Angelo's edits live in your own Three.js page, through your Vite dev server.",
+  "license": "MIT",
+  "author": "Hyperbond Studio Pte. Ltd.",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "development": "./src/browser/index.js",
+      "production": "./src/stub.js",
+      "default": "./src/stub.js"
+    },
+    "./vite": {
+      "types": "./src/vite/index.d.ts",
+      "default": "./src/vite/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./src/index.d.ts",
+  "files": [
+    "src/",
+    "LICENSE",
+    "README.md",
+    "PROTOCOL.md"
+  ],
+  "engines": {
+    "node": ">=18.18"
+  },
+  "peerDependencies": {
+    "three": ">=0.172.0",
+    "vite": ">=6.0.9"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "three": "0.187.0",
+    "vite": "7.3.7",
+    "vitest": "5.1.0"
+  },
+  "scripts": {
+    "test": "vitest run"
+  },
+  "keywords": ["three", "threejs", "vite", "vite-plugin", "gltf", "live-link", "angelo"]
+}

package/src/browser/capture.js

@@ -0,0 +1,130 @@
+// SPDX-FileCopyrightText: 2026 Hyperbond Studio Pte. Ltd.
+// SPDX-License-Identifier: MIT
+//
+// Pictures of the WebGL canvas for Angelo's agent, only when Angelo asks (PROTOCOL.md §1.1), and only the canvas.
+//
+// A WebGL drawing buffer is cleared once the browser presents the frame, unless the page asked for
+// preserveDrawingBuffer. So the SDK wraps renderer.render once: after a render to the canvas, while a capture is
+// pending, a microtask copies the canvas into a scaled 2D canvas. A microtask runs after the developer's frame code
+// (every pass of a post-processing chain, an overlay scene) but before the frame is presented.
+
+export const MAX_BYTES = 8 * 1024 * 1024;
+const FORCE_RENDER_MS = 600; // An app that renders only on change gets one render of its last scene and camera.
+const GIVE_UP_MS = 6000;
+
+const WRAPPED = Symbol("angelo live render hook");
+
+/**
+ * Wrap `renderer.render` once per renderer so `onCanvasRender(scene, camera)` runs after each render to the canvas.
+ * Several live links may share a renderer (a component that mounts twice); each unhook removes only its own
+ * listener, and the original render comes back when the last one goes.
+ */
+export function hookRenderer(renderer, onCanvasRender) {
+  let hook = renderer[WRAPPED];
+  if (!hook) {
+    const original = renderer.render;
+    hook = { listeners: new Set(), original, wrapped: null };
+    hook.wrapped = function render(scene, camera) {
+      const result = original.apply(this, arguments);
+      const target = typeof this.getRenderTarget === "function" ? this.getRenderTarget() : null;
+      if (target === null) for (const listener of hook.listeners) listener(scene, camera);
+      return result;
+    };
+    renderer.render = hook.wrapped;
+    renderer[WRAPPED] = hook;
+  }
+  hook.listeners.add(onCanvasRender);
+  return () => {
+    hook.listeners.delete(onCanvasRender);
+    if (hook.listeners.size || renderer[WRAPPED] !== hook) return;
+    delete renderer[WRAPPED];
+    if (renderer.render === hook.wrapped) renderer.render = hook.original; // Another wrapper on top stays as it is.
+  };
+}
+
+function scaledCanvas(source, max) {
+  const scale = Math.min(1, max / Math.max(source.width, source.height));
+  const canvas = document.createElement("canvas");
+  canvas.width = Math.max(1, Math.round(source.width * scale));
+  canvas.height = Math.max(1, Math.round(source.height * scale));
+  canvas.getContext("2d").drawImage(source, 0, 0, canvas.width, canvas.height);
+  return canvas;
+}
+
+function pngOf(canvas) {
+  return new Promise((resolve) => canvas.toBlob(resolve, "image/png"));
+}
+
+export class Capturer {
+  /**
+   * @param {object} o
+   * @param {object} o.renderer  The developer's WebGLRenderer.
+   * @param {(id: string, blob: Blob) => Promise<void>} o.send  POSTs the PNG.
+   * @param {(id: string, message: string) => void} o.fail
+   */
+  constructor({ renderer, send, fail }) {
+    Object.assign(this, { renderer, send, fail });
+    this.pending = null;
+    this.lastScene = null;
+    this.lastCamera = null;
+  }
+
+  /** Called by the render hook after each render to the canvas. */
+  rendered(scene, camera) {
+    this.lastScene = scene;
+    this.lastCamera = camera;
+    const pending = this.pending;
+    if (!pending || pending.scheduled) return;
+    pending.scheduled = true;
+    queueMicrotask(() => this.grab(pending));
+  }
+
+  request(id, max) {
+    if (this.pending) this.finish(this.pending, "Another capture replaced this one");
+    const pending = { id, max, scheduled: false, done: false };
+    pending.force = setTimeout(() => {
+      // Nothing rendered: draw the last scene and camera once (an app that renders on demand).
+      if (!pending.scheduled && this.lastScene && this.lastCamera) {
+        this.renderer.render(this.lastScene, this.lastCamera);
+      }
+    }, FORCE_RENDER_MS);
+    pending.giveUp = setTimeout(() => this.finish(pending, "The page didn't draw a frame in time"), GIVE_UP_MS);
+    this.pending = pending;
+  }
+
+  async grab(pending) {
+    if (pending.done) return;
+    let canvas;
+    try {
+      canvas = scaledCanvas(this.renderer.domElement, pending.max); // Synchronous: the frame is still there.
+    } catch {
+      return this.finish(pending, "The canvas couldn't be read");
+    }
+    let blob = await pngOf(canvas);
+    for (let tries = 0; blob && blob.size > MAX_BYTES && tries < 4; tries++) {
+      canvas = scaledCanvas(canvas, Math.floor(Math.max(canvas.width, canvas.height) * 0.7));
+      blob = await pngOf(canvas);
+    }
+    if (pending.done) return;
+    if (!blob || blob.size > MAX_BYTES) return this.finish(pending, "The picture is larger than 8 MiB");
+    this.finish(pending, null);
+    try {
+      await this.send(pending.id, blob);
+    } catch {
+      // The bridge answers Angelo itself when no picture arrives in time.
+    }
+  }
+
+  finish(pending, failure) {
+    if (pending.done) return;
+    pending.done = true;
+    clearTimeout(pending.force);
+    clearTimeout(pending.giveUp);
+    if (this.pending === pending) this.pending = null;
+    if (failure) this.fail(pending.id, failure);
+  }
+
+  cancel() {
+    if (this.pending) this.finish(this.pending, "The page stopped the live link");
+  }
+}

package/src/browser/delta.js

@@ -0,0 +1,64 @@
+// SPDX-FileCopyrightText: 2026 Hyperbond Studio Pte. Ltd.
+// SPDX-License-Identifier: MIT
+//
+// Delta frames (PROTOCOL.md §1.2): only the objects Angelo changed, as `content` nodes, hung under their real
+// ancestors, which come as `parent` nodes (locators the page finds by key and never changes), plus the keys that
+// are gone. Only content nodes are touched, and one whose digest the page already has is skipped. A delta that
+// doesn't fit what the page shows (a parent key it doesn't have) is not applied at all: the caller asks for a full
+// frame instead.
+
+import { skins } from "./matcher.js";
+import { describe } from "./source.js";
+import { Update, sdkDigest } from "./update.js";
+
+/** The delta's nodes, parents first, each with `parentUid`: its glb parent's key, or "" under the asset root. */
+export function describeDelta(gltf) {
+  const whole = describe(gltf);
+  const nodes = whole.nodes.map((node) => ({ ...node, parentUid: node.parent ? node.parent.uid : "" }));
+  const byObject = new Map(nodes.map((node) => [node.object, node]));
+  for (const node of nodes) node.parent = node.parent ? byObject.get(node.parent.object) : null;
+  return { nodes, byObject };
+}
+
+/**
+ * Apply a delta to one copy: {report} when applied, or {problem} (and nothing changed) when the page must ask
+ * for a full frame. `removedKeys` is the header's `removed`.
+ */
+export function applyDelta(copy, delta, removedKeys, cache) {
+  const byUid = new Map();
+  for (const [object, info] of copy.nodes) if (info.uid !== null && !byUid.has(info.uid)) byUid.set(info.uid, object);
+
+  // Resolve first, so a delta is applied whole or not at all.
+  for (const node of delta.nodes) {
+    if (node.uid === null) return { problem: "a node without its key" };
+    if (node.role === "parent" && !byUid.has(node.uid)) return { problem: "a parent the page doesn't have" };
+  }
+  const removed = removedKeys.map((key) => byUid.get(key)).filter(Boolean);
+  const removing = new Set(removed);
+  for (const node of delta.nodes) {
+    if (removing.has(byUid.get(node.uid))) return { problem: "a node both sent and removed" };
+  }
+
+  const update = new Update(copy, copy.journal, cache);
+  const finish = update.removeNodes(removed);
+  const objectOf = new Map();
+  const changed = new Set();
+  for (const node of delta.nodes) { // Parents before children.
+    const existing = byUid.get(node.uid);
+    if (node.role === "parent") {
+      objectOf.set(node, existing);
+      continue;
+    }
+    const parent = node.parent ? objectOf.get(node.parent) : copy.root;
+    if (existing && node.digest && sdkDigest.get(existing) === node.digest) {
+      objectOf.set(node, existing);
+      continue; // What the page has already: untouched.
+    }
+    changed.add(node);
+    objectOf.set(node, existing ? update.updateNode(existing, node, parent) : update.addNode(node, parent));
+  }
+  finish();
+  // Joints by key: bones (sent as parents when only a skin needs them) are the page's own objects, never replaced.
+  skins(update, delta, (bone) => objectOf.get(delta.byObject.get(bone)) ?? null, objectOf, changed);
+  return { report: update.report };
+}