pi-pocket 0.25.0 → 0.26.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +2 -0
- package/README.md +5 -3
- package/docs/architecture.md +21 -0
- package/docs/design/design-mode.md +108 -0
- package/docs/design/notes-a.md +106 -0
- package/docs/design/notes-b.md +123 -0
- package/docs/design/notes-c.md +92 -0
- package/docs/design/notes-d.md +78 -0
- package/docs/design/release-notes-design.md +46 -0
- package/docs/extensions/browser-modules.md +2 -0
- package/docs/extensions/policies/api-stability.md +2 -0
- package/docs/extensions/reference/api-versions.md +1 -0
- package/docs/extensions/reference/host.md +1 -1
- package/docs/extensions/reference/limits.md +4 -0
- package/docs/extensions/reference/names.md +2 -2
- package/docs/extensions/reference/pocket.md +38 -0
- package/docs/features.md +19 -5
- package/docs/map.md +75 -54
- package/docs/release-notes.md +1 -1
- package/docs/self-editing.md +1 -1
- package/docs/systemd.md +1 -1
- package/npm-shrinkwrap.json +2 -2
- package/package.json +1 -1
- package/src/launcher/main.ts +20 -9
- package/src/server/app.ts +113 -4
- package/src/server/background.ts +3 -3
- package/src/server/cache-keeper.ts +605 -0
- package/src/server/compaction.ts +68 -15
- package/src/server/design/bundle.ts +65 -0
- package/src/server/design/export.ts +118 -0
- package/src/server/design/files.ts +49 -0
- package/src/server/design/guide.ts +56 -0
- package/src/server/design/index.ts +232 -0
- package/src/server/design/pptx.ts +304 -0
- package/src/server/design/render.ts +593 -0
- package/src/server/design/system.ts +248 -0
- package/src/server/docs.ts +55 -0
- package/src/server/extensions/artifacts.ts +202 -18
- package/src/server/extensions/design/canvas.js +304 -0
- package/src/server/extensions/design/comments.js +15 -0
- package/src/server/extensions/design/data.js +263 -0
- package/src/server/extensions/design/devices.js +70 -0
- package/src/server/extensions/design/docks.js +647 -0
- package/src/server/extensions/design/edits.js +37 -0
- package/src/server/extensions/design/index.js +326 -0
- package/src/server/extensions/design/messages.js +92 -0
- package/src/server/extensions/design/parts.js +160 -0
- package/src/server/extensions/design/state.js +146 -0
- package/src/server/extensions/design/style.css +1332 -0
- package/src/server/extensions/design/tweaks.js +161 -0
- package/src/server/extensions/design/views.js +375 -0
- package/src/server/extensions/design/workspace.js +723 -0
- package/src/server/extensions/design.ts +620 -0
- package/src/server/extensions/plan.ts +11 -9
- package/src/server/extensions/prompt.ts +11 -3
- package/src/server/extensions/subagents.ts +7 -1
- package/src/server/extensions/updates/index.js +16 -6
- package/src/server/extensions/updates.ts +2 -2
- package/src/server/http/artifact-assets.ts +216 -0
- package/src/server/http/artifact-inspect.ts +1281 -0
- package/src/server/http/artifacts.ts +89 -14
- package/src/server/http/conversation-routes.ts +46 -1
- package/src/server/http.ts +12 -4
- package/src/server/main.ts +4 -0
- package/src/server/npm-install.ts +82 -0
- package/src/server/npm-update.ts +100 -0
- package/src/server/reload.ts +5 -0
- package/src/server/room.ts +2 -0
- package/src/server/spend.ts +73 -9
- package/src/server/update-state.ts +257 -8
- package/src/server/updates.ts +268 -33
- package/src/server/zip.ts +163 -0
- package/types/pocket.d.ts +32 -0
- package/web/activity-fold.js +28 -0
- package/web/artifact-bridge.js +506 -82
- package/web/extension-ui.js +21 -1
- package/web/pip.js +46 -9
- package/web/sessions.js +1 -1
- package/web/sheets/appearance.js +10 -0
- package/web/sheets/viewers.js +26 -1
- package/web/style.css +11 -0
- package/web/taps.js +26 -0
- package/web/theme.js +6 -0
- package/web/transcript.js +19 -10
- package/src/server/http/public.ts +0 -30
package/AGENTS.md
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# Working on Pi Pocket
|
|
2
2
|
|
|
3
|
+
In an npm install (inside `node_modules`), read only: to change Pi Pocket, clone the repository.
|
|
4
|
+
|
|
3
5
|
Pi Pocket is often edited from inside itself, while it runs. [docs/map.md](docs/map.md) says where things are, and [docs/architecture.md](docs/architecture.md) what they rely on. [docs/self-editing.md](docs/self-editing.md) has the whole of what follows, including how to check a change on a throwaway copy (`node test/serve.ts`); [docs/index.md](docs/index.md) lists every guide. Keep editing safe:
|
|
4
6
|
|
|
5
7
|
- `web/**` changes reload every open browser right away. Keep the app loadable after each save: a syntax error blanks the screen for everyone, including you. Check with `node --check web/<file>.js` after editing.
|
package/README.md
CHANGED
|
@@ -37,7 +37,9 @@ npm install -g pi-pocket
|
|
|
37
37
|
pi-pocket
|
|
38
38
|
```
|
|
39
39
|
|
|
40
|
-
|
|
40
|
+
Newer npm may print "install-scripts ... not yet covered by allowScripts" for `@google/genai` and `protobufjs`, which come from Pi's model library. The warning is expected: Pi Pocket needs neither script. `npm config set allow-scripts=@google/genai,protobufjs --location=user` quiets it by letting both run, which does no harm.
|
|
41
|
+
|
|
42
|
+
Or try it with `npx pi-pocket`. To change Pi Pocket's code, run a git checkout instead:
|
|
41
43
|
|
|
42
44
|
```bash
|
|
43
45
|
git clone https://github.com/TannerMidd/pi-pocket.git
|
|
@@ -50,7 +52,7 @@ The launcher asks how your devices should connect, then prints a sign-in link an
|
|
|
50
52
|
|
|
51
53
|
While it runs: **q** quit · **r** restart server · **a** change access · **o** open in browser · **s** show QR code.
|
|
52
54
|
|
|
53
|
-
**Updating:** Menu → **Update Pi Pocket** updates a git checkout run with `npm start`
|
|
55
|
+
**Updating:** Menu → **Update Pi Pocket** updates a git checkout run with `npm start`, or a global npm install (`npm install -g pi-pocket`) that your user can write, and restarts. It goes back by itself if the new version does not start ([features](docs/features.md)). A local install (`npm install pi-pocket` in a project) and `npx pi-pocket` do not update from the app: the sheet says what to run, `npm install pi-pocket@latest` or `npx pi-pocket@latest`. By hand: stop the server, back up `~/.pi-pocket`, pull, run `npm install`, and start again; for a global install, run `npm install -g pi-pocket@latest`. If the machine stops at the very moment of the switch, `pi-pocket` may not start; `npm install -g pi-pocket` restores it. Read the [release notes](https://github.com/TannerMidd/pi-pocket/releases) first: 0.21.0 upgrades the database one way, so going back needs the backup.
|
|
54
56
|
|
|
55
57
|
### Other ways to run it
|
|
56
58
|
|
|
@@ -79,7 +81,7 @@ Choose a mode in the launcher, or pass `--access`:
|
|
|
79
81
|
| `cloudflare` | Anyone with the link | Free https quick tunnel, no account; needs `cloudflared` |
|
|
80
82
|
| `tailscale` | Your tailnet | Tailscale address only |
|
|
81
83
|
|
|
82
|
-
Other options: `--port` (8787), `--cwd`, `--data` (`~/.pi-pocket`), `--host`, and `-y` to reuse the last access choice. `npm start -- --help` lists them all. `PI_POCKET_BROWSER` and `PI_POCKET_BROWSER_ARGS` pick the built-in browser and its flags when Chromium or Chrome is not found by itself.
|
|
84
|
+
Other options: `--port` (8787), `--cwd`, `--data` (`~/.pi-pocket`), `--host`, and `-y` to reuse the last access choice. `npm start -- --help` lists them all. `PI_POCKET_BROWSER` and `PI_POCKET_BROWSER_ARGS` pick the built-in browser and its flags when Chromium or Chrome is not found by itself. `PI_POCKET_PROMPT_DATE=1` puts today's date in Pi's system prompt; it is left out by default, so the prompt cache does not start over when the date changes. `PI_POCKET_CACHE_KEEPER=off` turns off the prompt cache keeper, which keeps a model's prompt cache warm while a run waits on a tool call ([features](docs/features.md)).
|
|
83
85
|
|
|
84
86
|
> [!WARNING]
|
|
85
87
|
> Anyone who can steer a session can make Pi run commands on this machine, as you. That reaches your files, Pi Pocket's own settings and tokens, and its code. Invite only people you would trust at your keyboard. View-only users cannot make Pi act. [SECURITY.md](SECURITY.md) says what is protected and what is not.
|
package/docs/architecture.md
CHANGED
|
@@ -105,6 +105,16 @@ Only people choose models; Pi, PiP, and Pi Pocket itself never pick one on the s
|
|
|
105
105
|
- **No spend, no model choice.** A wait sends nothing but rejected requests. A gate never picks another model: only people do. Titles and PiP's summaries pass `noWait` and fail as they did.
|
|
106
106
|
- **What people see.** The room view's `live.limit`, the session list's `limited` (a session's subagents too), the peek summary, and a subagent's `limited` on its bar and the board: the live line, the square (`limited`), peek tiles, and one push (kind `limit`) when a wait of ten minutes or more begins.
|
|
107
107
|
|
|
108
|
+
## Prompt cache keeper
|
|
109
|
+
|
|
110
|
+
`CacheKeeper` (`cache-keeper.ts`, `app.cacheKeeper`) wraps `models.streamSimple` as the outermost wrapper, so it sees each real request finish and replays it through the wrappers below. The order, innermost first, is the final payload observer, request shaping, `timing.ts`, `LimitGate`, then the keeper. A warm request passes `noWait`, so a limit makes it fail and never queue. It is on by default; `PI_POCKET_CACHE_KEEPER=off` turns it off.
|
|
111
|
+
|
|
112
|
+
- **When.** A request that ended in a tool call is replayed with `maxTokens` 1 at 90% of the cache lifetime, or 10 seconds before its end, only when the expected savings are more than the cost. It never warms an idle session, a 1h cache, a request with `cacheRetention` none, or Anthropic thinking set by a token budget.
|
|
113
|
+
- **Payload.** The observer hashes the real request's final JSON after all shapers. Before transmission, it compares each warm's final JSON with that hash. Only provider output-cap fields may differ. A changed or unobserved payload sends no warm and adds no spend.
|
|
114
|
+
- **Stop.** A real cached request, the end of the run (PiP's too), a changed payload, an error, shutdown, or 30 minutes stops it.
|
|
115
|
+
- **Spend.** A warm request's usage counts in `pi.usage` and in the spend of the person and session captured when it started. `Spend` checks their limits before each warm.
|
|
116
|
+
- **Restart.** A restart discards the warm timers. It replays no warm request.
|
|
117
|
+
|
|
108
118
|
## Memory
|
|
109
119
|
|
|
110
120
|
Lessons Pi keeps across sessions are one document for the whole app, `MemoryDoc` (`pocket.memory`), by id. Each is for a project or for everywhere. A project is keyed by the real path of its git common folder (`git rev-parse --git-common-dir`), so a repository and all its worktrees share lessons; outside a repository, by the folder itself. `Memory` (`memory.ts`) works out a folder's project (kept a minute per folder) and keeps the rules:
|
|
@@ -275,6 +285,17 @@ What a browser shows is its person's choice of theme (`look`) and colors (`theme
|
|
|
275
285
|
- Extensions' API: `web` on the server and `pocket` in the browser, at `POCKET_API`. Modules outside this repository depend on them: add to them freely, and change what they do only with a new version.
|
|
276
286
|
- `ATTACHMENTS_HEADING` and `splitAttachments` (which also reads the form sent before 0.14.0), which `ui.js` repeats from `entry-format.ts`.
|
|
277
287
|
|
|
288
|
+
## Updates of Pi Pocket itself
|
|
289
|
+
|
|
290
|
+
`Updates` (`updates.ts`, `app.updates`) works out `installKind` from where the server's files are: a git checkout (`git`), the global package folder of the Node.js that runs it, as `npm root -g` gives it (`npm-global`), another `node_modules` folder (`npm-local`), the npx cache (`npx`), or none of these (`unknown`; `npm-install.ts` does the npm kinds). Every kind shares one status (`UpdateStatus`), one set of checks (the launcher runs the server, no sessions busy, the warning tick), the two settings of the `updates` extension, and the outcome format in `update-state.ts`. What differs is where the newest version comes from and how it goes in:
|
|
291
|
+
|
|
292
|
+
- **The newest version.** An npm kind reads the registry's `latest` tag, and takes the notes, link, and date from the GitHub release of that version; if GitHub does not answer, the version stands without notes and is treated as one with a warning. A git checkout reads GitHub's newest release, or the version tags.
|
|
293
|
+
- **Git.** The release's commit is fetched under `refs/pocket-update/target`, packages install in `.pocket-update/staging/`, and the branch moves forward.
|
|
294
|
+
- **Global npm.** Only when the server's user can write the package and its parent folder, and the launcher advertises `PI_POCKET_NPM_ROLLBACK=1`. The new version installs through `npm-update.ts` in a separate global prefix under the sibling `.pi-pocket-update/staging/`. `update-state.ts` swaps the whole package, keeping the old one in `previous/`. The sibling folder also holds `pending.json` and `last.json`, so replacing the package does not replace recovery state. Before each server spawn, the launcher repairs a missing live folder from the pending update's copies; the server also checks before loading app modules. The launcher swaps the kept copy back when the server does not start; this needs no network. A successful start removes `previous/`. An older launcher requires a full quit and start before npm updates become available.
|
|
295
|
+
- **Local npm and npx.** Nothing in the app can change these. Their status has a blocker with the command to run (`npm install pi-pocket@latest`, or `npx pi-pocket@latest`).
|
|
296
|
+
|
|
297
|
+
A release with a warning (or notes that could not be read) is never installed by itself and is not rolled back by itself, whatever the kind. The browser module (`extensions/updates/index.js`) only shows `installKind` in words and the blockers the server gives: it holds no rule of its own.
|
|
298
|
+
|
|
278
299
|
## Checking a change
|
|
279
300
|
|
|
280
301
|
- **Every change:** `npm run check` (types, and no unused imports or locals in the TypeScript), `npm run lint`, and `npm test`.
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
# Design mode (0.26.0)
|
|
2
|
+
|
|
3
|
+
Status: built. The four streams (A to D) are merged into `feat/design`, off `release/0.26.0`. This page is the plan, corrected where the build differs from it. Each place that changed says "Built:". What each stream built is in `notes-a.md` to `notes-d.md`; the words for the release are in `release-notes-design.md`.
|
|
4
|
+
|
|
5
|
+
Design mode gives Pi Pocket what Claude Design has: a big canvas beside the chat, where Pi makes interactive designs (prototypes, screens, one-pagers, slide decks), and people point at them, comment, tweak, edit text, compare versions and variations, export, and hand off to code.
|
|
6
|
+
|
|
7
|
+
It builds on artifacts. A design is an HTML artifact. Everything that works for artifacts today (versions, the sandbox, the bridge, saved state, share links, inline cards) keeps working.
|
|
8
|
+
|
|
9
|
+
## The parts, and who builds them
|
|
10
|
+
|
|
11
|
+
| Stream | Branch | Owns (only these files, plus new tests) |
|
|
12
|
+
| ------ | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
13
|
+
| A | `design/bundles` | `src/server/extensions/artifacts.ts`, `src/server/http/artifacts.ts` (serving only, not the bridge script), new `src/server/http/artifact-assets.ts`, `src/server/app.ts` (`artifactBody` and new bundle readers), the artifact kinds in `src/server/docs.ts`, new `src/server/zip.ts` |
|
|
14
|
+
| B | `design/bridge` | `web/artifact-bridge.js`, the bridge script in `src/server/http/artifacts.ts` (`ARTIFACT_BRIDGE` and what it calls), new `src/server/http/artifact-inspect.ts` |
|
|
15
|
+
| C | `design/workspace` | new `src/server/extensions/design.ts`, new `src/server/extensions/design/` (browser module folder), `src/server/reload.ts`, a new kind at the end of `src/server/docs.ts`, `web/sheets/viewers.js` (an "Open in Design" button only) |
|
|
16
|
+
| D | `design/agent` | new `src/server/design/` (tools, prompt guide, preview, export, PPTX), nothing else |
|
|
17
|
+
|
|
18
|
+
Rules for every stream:
|
|
19
|
+
|
|
20
|
+
- Work only in your own worktree (`/mnt/games/Development/pi-pocket-design-<a|b|c|d>`). Never edit `/mnt/games/Development/pi-pocket` (the live server: a file saved there loads for everyone at once).
|
|
21
|
+
- Touch only the files your stream owns. When you need a change in another stream's file, write it in your notes file and keep going with a small local stub.
|
|
22
|
+
- Do not edit `docs/features.md`, `docs/map.md`, `docs/release-notes.md`, `README.md`, or `CHANGELOG`. Write what they must say in `docs/design/notes-<a|b|c|d>.md`. The integrator merges them.
|
|
23
|
+
- Document kinds are stored data. Add new kinds and new optional fields. Never rename a kind, or change its scope, history, or fork settings.
|
|
24
|
+
- Keep to the house style (AGENTS.md): erasable TypeScript, `.ts` imports, Prettier and ESLint, `npm run format`, `npm run check`, `npm run lint`, `npm test`.
|
|
25
|
+
- No new npm dependencies. Node and the browser have what this needs (zlib for zip, CDP for Chromium).
|
|
26
|
+
- Check by hand on a throwaway copy: `node test/serve.ts <port> 127.0.0.2` with your port (A 8901, B 8902, C 8903, D 8904). The `browser` tool is one Chromium that all streams and the people watching share: navigate, check, and leave. If a page changes under you, another stream uses it: navigate again.
|
|
27
|
+
|
|
28
|
+
## A. Artifact bundles (assets, groups)
|
|
29
|
+
|
|
30
|
+
A design needs images, fonts, data files, and more than one page. Today an artifact is one UTF-8 file.
|
|
31
|
+
|
|
32
|
+
- The `artifact` and `artifact_inline` tools get `assets`: up to 200 entries of `{ name, path }` (copy a file from the session's machine, binary allowed) or `{ name, content }` (UTF-8 text). `name` is a relative path: segments of `[A-Za-z0-9._-]`, joined by `/`, no `.` or `..` segment, no leading `/`, up to 200 characters.
|
|
33
|
+
- A new version keeps the assets of the version before. `removeAssets: string[]` drops some. An entry with an existing name replaces it.
|
|
34
|
+
- Limits: 5 MB for one asset, 20 MB for all the assets of one version, as constants beside `MAX_BYTES`.
|
|
35
|
+
- Storage: assets are stored once for each content hash (sha256) in a new document kind, `pocket.artifact-asset`, keyed by the hash, with the bytes in base64. `ArtifactVersion` gets an optional `assets?: Record<string, { hash: string; size: number; type: string }>`. A replayed call must find what it wrote, as the body does.
|
|
36
|
+
- Serving: an asset is at `/a/:conversation/:artifact/:version/<name>`, and for a published link at `/pub/:token/<name>` (built: `src/server/http.ts` calls `publicArtifactBundle` in `src/server/http/artifact-assets.ts`, and `src/server/http/public.ts` is deleted), with the same sandbox CSP as the page, `X-Content-Type-Options: nosniff`, and a content type from its extension (an unknown extension is `application/octet-stream`, never HTML). A relative URL in the page (`assets/logo.png`, `about.html`) must resolve, in the viewer, the inline card, its own tab, and a published link. Inject a `<base href>` when the page has assets, or serve the page at a URL that ends in `/`: choose and say which. Built: an absolute `<base href>` is injected. A sandboxed page sends no cookie, so a private page gets a signed, version-scoped asset address that lasts 12 hours and permits only the version's manifest assets.
|
|
37
|
+
- A second HTML file in the bundle is a page of the design (`about.html`). It gets the bridge as the main page does.
|
|
38
|
+
- `group?: string` (a slug) on the tools puts the artifact in a group: variations of one design. Store it in `ArtifactMeta`. The workspace shows a group as a grid.
|
|
39
|
+
- `kind?: "page" | "deck"` on the tools, stored in `ArtifactMeta`. A deck is a slide deck (see D).
|
|
40
|
+
- Bundle reader on `PocketApp`: `artifactBundle(id, artifact, version?) => Promise<{ meta, version, content, assets: { name, type, bytes: Buffer }[] }>`. Built: the Design tools and routes do not use it. `designTools(host)` and `designRoutes(web, host)` take no bundle reader; `src/server/design/bundle.ts` reads the artifact documents with `snapshot`, the assets by hash.
|
|
41
|
+
- `src/server/zip.ts`: `zip(entries: { name: string; bytes: Buffer }[]) => Buffer`, deflate with `node:zlib`, no dependency. D uses it for PPTX and the HTML export (built: `design/export.ts` and `design/pptx.ts` import it).
|
|
42
|
+
|
|
43
|
+
## B. The bridge: inspect, edit, tweaks
|
|
44
|
+
|
|
45
|
+
New messages over the existing port. App → page messages come only from the app. Page → app messages are untrusted data: the app checks their shape and length, and uses them only as data in a person's own comment or edit.
|
|
46
|
+
|
|
47
|
+
App → page:
|
|
48
|
+
|
|
49
|
+
- `{ type: "pocket-inspect", on: boolean }`: inspect mode. The page outlines the element under the pointer (or finger), and a click or tap picks it (the page's own handler does not run). It sends `pocket-picked`.
|
|
50
|
+
- `{ type: "pocket-edit-text", on: boolean }`: text edit mode. Text elements become `contenteditable`. When one loses focus with a change, the page sends `pocket-text-edited`.
|
|
51
|
+
- `{ type: "pocket-tweak-set", values: Record<string, string | number | boolean> }`: for a name that starts with `--`, set that CSS custom property on `:root`; for any name, dispatch `pocket:tweak` on `window` with `{ detail: { name, value } }`.
|
|
52
|
+
- `{ type: "pocket-highlight", targets: Target[] }`: show numbered pins on these elements (the comments). An empty list clears them.
|
|
53
|
+
- `{ type: "pocket-goto", slide: number }`: in a deck, show this slide.
|
|
54
|
+
|
|
55
|
+
Page → app:
|
|
56
|
+
|
|
57
|
+
- `{ type: "pocket-picked", target: Target }`.
|
|
58
|
+
- `{ type: "pocket-text-edited", target: Target, before: string, after: string }` (each up to 2,000 characters).
|
|
59
|
+
- `{ type: "pocket-tweaks", knobs: Knob[] }`: once at start, from the page's manifest (below), and again if it changes.
|
|
60
|
+
- `{ type: "pocket-deck", slides: number, current: number }`: at start in a deck, and when the slide changes.
|
|
61
|
+
|
|
62
|
+
`Target` is `{ pid?: string, selector: string, tag: string, text: string (up to 200), html: string (up to 1,000), rect: { x, y, width, height }, styles: Record<string, string> (color, background-color, font-family, font-size, font-weight, line-height, padding, margin, border-radius, gap) }`. `pid` is the element's nearest `data-pid`. `selector` is a short unique CSS selector the bridge computes.
|
|
63
|
+
|
|
64
|
+
The tweaks manifest is in the page: `<script type="application/json" id="pocket-tweaks">[ … ]</script>`. A `Knob` is `{ name, label?, type: "range" | "color" | "select" | "toggle" | "text", value, min?, max?, step?, unit?, options? }`, at most 40.
|
|
65
|
+
|
|
66
|
+
A deck is a page with `<meta name="pocket-kind" content="deck">` and its slides as `<section class="slide">`, 16:9. The bridge shows one slide at a time, scaled to fit, with arrow keys and swipes, and handles `pocket-goto`. Built: slides are 1920×1080 by default, or the size in `<meta name="pocket-slide-size" content="WxH">`, in the canvas and in the PNG, PDF, and PPTX exports. Slide numbers in `pocket-goto` and `pocket-deck` start at 0; the `slide` of `design_preview` starts at 1.
|
|
67
|
+
|
|
68
|
+
The inspector lives in `src/server/http/artifact-inspect.ts` as a script string that the bridge script includes. It must not change the page until a mode turns on, and must clean up fully when it turns off.
|
|
69
|
+
|
|
70
|
+
The existing follow-up and saved-state messages stay as they are.
|
|
71
|
+
|
|
72
|
+
## C. The workspace
|
|
73
|
+
|
|
74
|
+
A built-in module, `design` (title "Design", on by default), with a browser module folder `src/server/extensions/design/`.
|
|
75
|
+
|
|
76
|
+
- A wide panel beside the conversation (`pocket.panel({ wide: true })`): chat on the left, canvas on the right. On a phone, the panel covers the chat, with a button back to the chat that keeps the canvas state.
|
|
77
|
+
- Opened from a rail button, the places, an "Open in Design" button in the artifact viewer, and `/design-open [artifact]`. Built: the command is `/design-open`, because a command's name must have a dash.
|
|
78
|
+
- The canvas: a picker of the session's HTML artifacts (newest first, groups together), the page in the artifact sandbox frame (the same frame and bridge as the viewer), device sizes (phone 390×844, tablet 820×1180, desktop 1280×800, custom), zoom and fit, and a light or dark backdrop.
|
|
79
|
+
- Versions: a timeline of the artifact's versions, side-by-side compare of two, and "Go back to this one" (asks Pi for a new version with that content, or writes one directly if C can do that safely through a durable call; say which). Built: the route writes a copy of the old version as a new one, assets included, in one commit. It never asks Pi.
|
|
80
|
+
- Comment mode: tap an element, write a note, and it becomes a pin. Comments are shared with everyone in the session, stored in a new kind at the end of `docs.ts` (`pocket.design-comments`, per conversation, keyed by artifact), with the version, the `Target`, the author, the text, and resolved or not. "Send to Pi" puts one message with all open comments (each with its target as JSON) in the message box, for the person to send.
|
|
81
|
+
- Edit mode: text edits gather into a list; "Apply" sends them to Pi as one message (Pi makes the new version with `edits`).
|
|
82
|
+
- Tweaks: a panel of the page's knobs (from `pocket-tweaks`), live on the canvas, kept for each person and artifact (in the module's own storage or the new kind). "Keep these" sends the values to Pi to write into the design.
|
|
83
|
+
- Variations: a group shows as a grid of live thumbnails; "Use this one" sends a message to Pi.
|
|
84
|
+
- Decks: a slide strip, and a full-screen present mode.
|
|
85
|
+
- Export: buttons for PNG, PDF, PPTX (decks), and HTML zip, through D's route, wired in `design.ts`. Built: the buttons `POST /api/x/design/export`, which writes the file in the session's `exports/` folder and answers `{ path, relative, name, size }`. The browser then downloads it through the core route `GET /api/c/<conversation>/download?path=<relative>`, which streams a file of the session folder as an attachment for the people that the file viewer lets read it, and does not follow a link at the file. The Design module has no download route of its own.
|
|
86
|
+
- Share: the existing Share, as in the viewer.
|
|
87
|
+
- `design.ts` registers D's tools and prompt section: `import { designTools, designGuide, designRoutes } from "../design/index.ts"` (see D). Until D lands, stub them.
|
|
88
|
+
- Register the module in `reload.ts`: `ORDER`, `TITLES`, and the names of D's tools in `BUILT_IN_TOOLS`.
|
|
89
|
+
- Viewers (people who cannot steer) see the canvas, versions, and comments, but cannot comment, edit, tweak, or send.
|
|
90
|
+
|
|
91
|
+
## D. The agent side
|
|
92
|
+
|
|
93
|
+
`src/server/design/index.ts` exports:
|
|
94
|
+
|
|
95
|
+
- `designTools(host): ToolRegistration[]`, the tools:
|
|
96
|
+
- `design_preview({ id, version?, viewports?: ("mobile" | "tablet" | "desktop")[], fullPage?: boolean, slide?: number })`: render the artifact in a headless Chromium page of its own (not the shared browser people watch) and return the screenshots as images, plus console errors and failed requests. Pi uses it to check its own work before it replies.
|
|
97
|
+
- `design_export({ id, version?, format: "png" | "pdf" | "pptx" | "html", viewport?, path? })`: write the file in the session's folder (default `exports/<id>-v<version>.<ext>`) and return the path. PNG and PDF through Chromium (CDP `Page.captureScreenshot`, `Page.printToPDF`). Built: the tool and the export route share `saveDesignExport` in `src/server/design/export.ts`. PPTX for a deck: one slide for each `section.slide`, as an image, 16:9, with the slide's text in the notes, written with `zip.ts`. HTML: the bundle as a zip.
|
|
98
|
+
- `design_system({ action: "read" | "write", content? })`: the project's design system, a Markdown file at `<session folder>/.pi/design-system.md` (tokens as a fenced JSON block, then components and rules). Pi writes it after it reads a codebase or brand files the person points at.
|
|
99
|
+
- `designGuide(host)`: the prompt section for sessions with the module on. It tells Pi how to make designs: one HTML artifact for each design, `data-pid` on meaningful elements, a tweaks manifest of 3 to 8 useful knobs as CSS custom properties, the deck format, assets for images and fonts, the design system when one exists, variations as a `group` of 2 to 4 artifacts made in parallel (subagents or codemode), `design_preview` at two sizes before it replies, and handoff to code (export `html` into the project, then a linked session with the `team` tool).
|
|
100
|
+
- `designRoutes(web, host)`: the export route for the workspace (same formats, steer access). Built: `POST export` answers `{ path, relative, name, size }`. It does not stream the file: the core download route does (see C).
|
|
101
|
+
|
|
102
|
+
Headless rendering: use the same Chromium discovery as `src/server/browser/` (`discovery.ts`, `cdp.ts`), in a separate, headless browser or a separate target and context, closed after use, with a time limit. It loads the artifact from the server's own address (`/a/...`) and so needs the person's session cookie or a short-lived internal token: say which you chose and why it is safe. Built: neither. Each render serves the bundle from a temporary server on `127.0.0.1`, under a random 256-bit path, and Chromium gets no cookie, token, or app address, so a page's scripts hold no app credential. Other requests go through `host.fetchPublic`.
|
|
103
|
+
|
|
104
|
+
Canva export is out of scope and is not in 0.26.0: it needs an app approved by Canva and OAuth for each person.
|
|
105
|
+
|
|
106
|
+
## Integration
|
|
107
|
+
|
|
108
|
+
The integrator merged A and B into `feat/design` first, then C and D. The notes are now in `docs/features.md`, `docs/map.md`, and `docs/design/release-notes-design.md`. The release swarm runs again on `release/0.26.0` with `feat/design` merged.
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
# Stream A: artifact bundles
|
|
2
|
+
|
|
3
|
+
Status: bundle implementation and core published-route wiring are complete on `design/bundles`.
|
|
4
|
+
|
|
5
|
+
## Built interfaces
|
|
6
|
+
|
|
7
|
+
- Both artifact tools accept `assets`, `removeAssets`, `group`, and `kind`.
|
|
8
|
+
- `assets` accepts up to 200 entries, each with `name` and exactly one of `path` or `content`.
|
|
9
|
+
- Paths copy regular local files. The final path cannot be a symbolic link. Binary files are allowed.
|
|
10
|
+
- Asset names have up to 200 ASCII characters, with safe relative path segments.
|
|
11
|
+
- Each version inherits previous assets. New entries replace matching names. Removals apply before additions.
|
|
12
|
+
- Limits are 5,000,000 bytes per asset and 20,000,000 bytes per version. A version keeps at most 200 assets.
|
|
13
|
+
- `ArtifactVersion.assets` maps names to `{ hash, size, type }`.
|
|
14
|
+
- `pocket.artifact-asset` is a session-scoped document family. SHA-256 keys hold immutable base64 bytes.
|
|
15
|
+
- The asset documents, version manifest, index, and main body commit together. Replays find their original version before reading local files.
|
|
16
|
+
- `ArtifactMeta` has optional `group` and `kind: "page" | "deck"` fields.
|
|
17
|
+
- `PocketApp.artifactBundle(conversation, artifact, version?)` returns `{ meta, version, content, assets: { name, type, bytes }[] }`.
|
|
18
|
+
- `PocketApp.artifactAsset(conversation, artifact, version, name)` reads only one manifest asset.
|
|
19
|
+
- Both readers require the caller to check conversation access.
|
|
20
|
+
- `http/artifact-assets.ts` exports `ASSET_TYPES`, the frozen extension-to-MIME table, and `assetName(name)`, the safe path check.
|
|
21
|
+
- That module also exports `assetType(name)` with the binary fallback and `ARTIFACT_CSP` for isolated renderers.
|
|
22
|
+
- `zip(entries: { name: string; bytes: Buffer }[]): Buffer` writes ZIP32, with CRC32, UTF-8 names, and deflate when smaller.
|
|
23
|
+
|
|
24
|
+
## Serving choice and security
|
|
25
|
+
|
|
26
|
+
The server injects a `<base href>` before the page content when a version has assets.
|
|
27
|
+
The base is absolute, so inline source documents and run frames resolve URLs correctly.
|
|
28
|
+
An HTML asset gets its own directory as its base. Nested pages can use `../` links within the bundle.
|
|
29
|
+
The server injects the existing bridge into HTML assets under the existing frame rules.
|
|
30
|
+
Each asset response has the artifact sandbox CSP, `nosniff`, and `no-referrer`.
|
|
31
|
+
The file extension selects the MIME type. An unknown extension is `application/octet-stream`.
|
|
32
|
+
CORS allows opaque-origin module scripts and fonts. It does not grant access to any API.
|
|
33
|
+
|
|
34
|
+
Sandbox subrequests have no SameSite sign-in cookie.
|
|
35
|
+
Authenticated pages therefore receive a signed, version-scoped asset base: `/a/:conversation/:artifact/:version~person~expiry~signature/`.
|
|
36
|
+
The capability lasts 12 hours. It permits only manifest assets, not the main page, APIs, or arbitrary hashes.
|
|
37
|
+
HMAC-SHA256 signs the conversation, artifact, version, expiry, person, and person's token hash.
|
|
38
|
+
The existing persistent `ConfigStore.ownerToken` supplies the server key. No new data file is needed.
|
|
39
|
+
The signature input has a purpose label. `timingSafeEqual` compares the fixed-length signature bytes.
|
|
40
|
+
Every request rechecks the person's current session access. Removing the person or rotating a token revokes access.
|
|
41
|
+
A capability-authenticated HTML asset preserves the original expiry. It cannot renew its capability.
|
|
42
|
+
The usual authenticated `/a/:conversation/:artifact/:version/<name>` also works.
|
|
43
|
+
A page open for more than 12 hours loads new assets only after a reload.
|
|
44
|
+
The server creates capabilities only in HTTP responses. It does not store them in documents, tool results, or transcripts.
|
|
45
|
+
`artifactBody` and `artifactBundle` return raw content without injected capabilities, so normal agent readers do not receive them.
|
|
46
|
+
The capability code does not log URLs. Its errors use fixed messages and never include the capability.
|
|
47
|
+
Pages and assets send `Referrer-Policy: no-referrer`, so CDN requests do not receive the capability through `Referer`.
|
|
48
|
+
|
|
49
|
+
## Published routes
|
|
50
|
+
|
|
51
|
+
The integrator approved stream A's ownership of the serving changes in `src/server/http.ts` and `src/server/http/public.ts`.
|
|
52
|
+
`http.ts` now routes `/pub/:token/<name>` through `publicArtifact()` to the shared bundle responder.
|
|
53
|
+
`http/artifact-assets.ts` exports `publicArtifactBundle(app, request, response, token, name = "", query = new URLSearchParams())`.
|
|
54
|
+
The route passes `parts[1]` as the token and `parts.slice(2).join("/")` as the name.
|
|
55
|
+
The responder checks the share on every request and uses the share's pinned or latest version.
|
|
56
|
+
It gives public HTML no bridge. The same name check, MIME table, sandbox CSP, and `nosniff` protect public and private assets.
|
|
57
|
+
A latest-version link follows asset replacements, additions, and removals. A pinned link keeps its own manifest.
|
|
58
|
+
Ending or expiring a link closes its main page and every asset.
|
|
59
|
+
Tests use the real core HTTP handler, not an isolated route adapter.
|
|
60
|
+
Chromium also loads the bundle's fonts, images, CSS, and imported modules through a published link.
|
|
61
|
+
|
|
62
|
+
## Integration still needed
|
|
63
|
+
|
|
64
|
+
`room.ts:601` also needs to project `meta.group` and `meta.kind` for the workspace picker.
|
|
65
|
+
Stream A stores these fields but does not own `room.ts`.
|
|
66
|
+
|
|
67
|
+
Inline Run loads bundle assets correctly. Static Preview keeps its existing restrictive security boundary.
|
|
68
|
+
`web/rich.js:previewDocument()` removes base tags and stylesheet links, and its CSP permits only data images and fonts.
|
|
69
|
+
If static Preview must show bundle assets before Run, the integrator must add a safe preview path in `web/rich.js`.
|
|
70
|
+
Stream A does not own that file. The browser tests check inline Run, not static Preview.
|
|
71
|
+
|
|
72
|
+
The capability code does not send capabilities to Pi or logs, but generic output paths need an integration review.
|
|
73
|
+
`browser/page.ts` can log a signed URL after navigation to a bundled HTML asset.
|
|
74
|
+
An artifact can also explicitly include its base URI in a follow-up or saved value.
|
|
75
|
+
Absolute exclusion from all agent context, transcripts, and logs needs redaction in those browser and bridge paths.
|
|
76
|
+
Stream A does not own those files. The integrator received this limitation.
|
|
77
|
+
|
|
78
|
+
`npm run format` also fixes an existing unbraced `if` in `src/server/extensions/prompt.ts`.
|
|
79
|
+
This unrelated formatting change stays uncommitted in this worktree. The integrator must keep the brace fix for lint.
|
|
80
|
+
The reported full format and lint checks include that local brace fix.
|
|
81
|
+
|
|
82
|
+
## Documentation updates for the integrator
|
|
83
|
+
|
|
84
|
+
- `features.md`: artifacts can bundle files, inherit or replace assets, and group design variations.
|
|
85
|
+
- `features.md`: mention binary local assets, relative page links, and the per-version limits.
|
|
86
|
+
- `map.md`: add `http/artifact-assets.ts`, the bundle readers on `PocketApp`, and `zip.ts`.
|
|
87
|
+
- Release notes: designs can carry images, fonts, modules, styles, data, and extra HTML pages.
|
|
88
|
+
- Release notes: old single-file artifacts remain compatible. No stored kind changes semantics.
|
|
89
|
+
|
|
90
|
+
## Checks
|
|
91
|
+
|
|
92
|
+
- `npm run format`, `npm run check`, and `npm run lint` passed.
|
|
93
|
+
- The final complete `npm test` run passed after the 12-hour capability change: 762 tests, 0 failures, 0 skips, about 90 seconds.
|
|
94
|
+
- The bundle and ZIP tests passed together, including a real Chromium test.
|
|
95
|
+
- Tests cover inheritance, replacement, removal, hash storage, replay, unsafe sources, limits, capability scope, expiry, and revocation.
|
|
96
|
+
- Capability tests reject reuse across conversations, artifacts, and versions. They reject changed signatures and verify the 12-hour boundary.
|
|
97
|
+
- Restart tests verify that the existing signing key stays valid. Raw readers and tool results contain no injected capabilities.
|
|
98
|
+
- Tests cover sandbox headers, MIME types, public route revocation and expiry, pinned and latest manifests, nested pages, fonts, images, CSS, module imports, inline RunFrame, own-tab rendering, and published rendering.
|
|
99
|
+
- The focused bundle and share suites passed after the routing change: 19 tests, 0 failures.
|
|
100
|
+
- A fresh security review of the core routing changes found no concrete bugs.
|
|
101
|
+
- Fork and restart tests confirm that manifests and global asset bytes survive.
|
|
102
|
+
- `unzip -t` accepted an archive with a deflated HTML entry and a binary entry.
|
|
103
|
+
- A fresh, strong-model security review found no remaining concrete bugs after 3 fixes.
|
|
104
|
+
- The throwaway server ran with `node test/serve.ts 8901 127.0.0.2`.
|
|
105
|
+
- The mobile session loaded correctly, with no browser console errors. The server was stopped afterward.
|
|
106
|
+
- Manual checks did not seed an artifact in the echo-only throwaway model. Automated Chromium tests checked the actual bundle rendering.
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# Stream B notes: the bridge
|
|
2
|
+
|
|
3
|
+
Branch `design/bridge`. Owner of: `web/artifact-bridge.js`, the bridge script in `src/server/http/artifacts.ts` (`ARTIFACT_BRIDGE`), new `src/server/http/artifact-inspect.ts`, new `test/design-bridge-ui.test.ts`.
|
|
4
|
+
|
|
5
|
+
Two edits outside those files, both small:
|
|
6
|
+
|
|
7
|
+
- `src/server/http/artifacts.ts`, `artifactResponse`: one line. A page that is a tab of its own, or a published link, gets `withDeck(content)` where it got `content`. Stream A edits this function too: keep that one line when merging.
|
|
8
|
+
- `test/artifact-inline.test.ts`: the test that runs the bridge script in a fake window now also passes a fake `document`.
|
|
9
|
+
|
|
10
|
+
## What it does
|
|
11
|
+
|
|
12
|
+
The page side lives in `ARTIFACT_INSPECT` (a function expression, as a string) in `artifact-inspect.ts`. `ARTIFACT_BRIDGE` calls it with the line to the app, and it also runs in the run frame (`RUN_FRAME`). It is inert until the app turns a mode on, and each mode removes all it added when it turns off. Two things work from the page's own markup, with no mode: it reads the tweaks manifest, and it shows a deck one slide at a time.
|
|
13
|
+
|
|
14
|
+
| Message (app → page) | What the page does |
|
|
15
|
+
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
16
|
+
| `{ type: "pocket-inspect", on }` | Outlines the element under the pointer. A click or tap picks it (the page's click, mouse, pointer-down/up, and submit handlers do not run; scrolling still works) and sends `pocket-picked`. |
|
|
17
|
+
| `{ type: "pocket-edit-text", on }` | Text blocks become `contenteditable="plaintext-only"`, with a dashed hint. A block that loses focus with a change sends `pocket-text-edited`. Enter commits, Escape undoes. Clicks do not run the page's handlers. |
|
|
18
|
+
| `{ type: "pocket-tweak-set", values }` | A `--name` sets that custom property on `:root`; every name fires `pocket:tweak` on `window`. |
|
|
19
|
+
| `{ type: "pocket-highlight", targets }` | Numbered pins (and a faint outline) on the targets. An empty list clears them. |
|
|
20
|
+
| `{ type: "pocket-goto", slide }` | In a deck, shows this slide. |
|
|
21
|
+
|
|
22
|
+
| Message (page → app) | When |
|
|
23
|
+
| ------------------------------------------------------- | ------------------------------------------------------------------------- |
|
|
24
|
+
| `{ type: "pocket-picked", target }` | A pick in inspect mode. |
|
|
25
|
+
| `{ type: "pocket-text-edited", target, before, after }` | An edited block loses focus, or edit mode turns off. |
|
|
26
|
+
| `{ type: "pocket-tweaks", knobs }` | At start (only if the manifest has knobs), and when the manifest changes. |
|
|
27
|
+
| `{ type: "pocket-deck", slides, current }` | At start in a deck, and when the slide or the slide count changes. |
|
|
28
|
+
|
|
29
|
+
Only the inspector can send those four: the stand-in `parent` in the page sends the page's own messages to the real parent window, where the app ignores them. A test proves a page cannot forge them.
|
|
30
|
+
|
|
31
|
+
### Choices where the plan let me choose
|
|
32
|
+
|
|
33
|
+
- **Slide numbers are 0-based**, in `pocket-goto` and `pocket-deck`. D: if `design_preview({ slide })` is 1-based for Pi, convert.
|
|
34
|
+
- **Modes are exclusive**: turning inspect on turns text edit off, and the other way round. Pins and tweaks are separate.
|
|
35
|
+
- **`rect` is in page coordinates** (viewport rect plus scroll), in CSS pixels after any transform (a deck's scale is in it).
|
|
36
|
+
- **`before` in `pocket-text-edited` is the first text** the block had (whitespace squashed), not the text before the last edit. The same block can be sent again; keep the last one for each `target.selector`. Putting the old text back is sent too (`after === before`), so a reverted edit can be dropped.
|
|
37
|
+
- **Text edit makes editable**: an element with its own text and no block element inside (inline tags only), not inside another editable, with a layout box, and up to 2,000 characters. `<li>Text <ul>…` is not editable. Inline markup inside a block stays; typing plain text.
|
|
38
|
+
- **Knob `options`** are strings (`["calm", "loud"]`). An option written `{ value, label }` becomes its `value`.
|
|
39
|
+
- **A number for a `--name` gets the knob's `unit`**: `--radius: 12` with `unit: "px"` sets `12px`. A string is set as it is. A boolean sets `1` or `0`.
|
|
40
|
+
- **Extras, optional**: `pocket-tweak-set` with a `null` value removes that custom property (a reset). A `pocket-highlight` target may have `label` (string up to 8 characters or a number) to show instead of its list position, so pins can match comment numbers. The page also fires `pocket:slide` (`{ index, count }`) on `window` when the slide changes.
|
|
41
|
+
- **Pins** find an element by `selector`, and if that finds nothing (a newer version), by the `pid`'s `[data-pid]` element. A pin with no element is hidden.
|
|
42
|
+
- **Decks** are laid out at 1920×1080 and scaled to fit (letterboxed in black unless the page paints its own ground). `<meta name="pocket-slide-size" content="1280x720">` changes the size. The page side adds a viewport meta when a deck has none (a phone would lay it out at 980 pixels). Keys: arrows, PageUp/Down, Home, End, Space (Shift+Space back). Swipes: horizontal, over 50 pixels. Keys and swipes are off while text edit is on.
|
|
43
|
+
- **A deck as a page of its own** (a tab, a published link: no bridge there) also shows one slide at a time with keys and swipes: `withDeck` puts in the same script with no line to an app. Printing it shows every slide, one for each page (`@page` is the slide size), so a PDF export of a deck needs nothing more.
|
|
44
|
+
- **The overlay** (outlines, pins) is a `<pocket-overlay>` element at the end of `<html>`, in a closed shadow root, `pointer-events: none`. It is in the page only while it shows something. Styles go in with CSSOM and constructable stylesheets, never markup, so a page's CSP or Trusted Types does not stop it.
|
|
45
|
+
- **The page-side listeners** of the modes (window, capture phase) are added when the page starts, with the native `addEventListener` kept before the page's scripts run, so they run before any the page adds, and a page that replaces `addEventListener` cannot get a handler and call it with invented events. Each does nothing until its mode is on. Inspect also stops the page's touch handlers (not scrolling).
|
|
46
|
+
- **Early messages**: the app may speak as soon as the page starts. Design messages that arrive before the page is parsed wait, and run when it is (so a unit finds its manifest, and text edit finds its body). In the run frame, whose document is replaced, the last modes, pins, and tweak values are given to the new document.
|
|
47
|
+
- **Limit on messages** from one page: 60 a second; the rest are dropped.
|
|
48
|
+
|
|
49
|
+
## The app side: for stream C
|
|
50
|
+
|
|
51
|
+
All in `web/artifact-bridge.js`.
|
|
52
|
+
|
|
53
|
+
```js
|
|
54
|
+
import {
|
|
55
|
+
useArtifactBridge,
|
|
56
|
+
sendToFrame,
|
|
57
|
+
attachBridge,
|
|
58
|
+
checkPageMessage,
|
|
59
|
+
checkAppMessage,
|
|
60
|
+
} from "../artifact-bridge.js";
|
|
61
|
+
|
|
62
|
+
// In a component (the canvas):
|
|
63
|
+
const frame = useRef(null);
|
|
64
|
+
const bridge = useArtifactBridge(frame, {
|
|
65
|
+
artifact: id, // as for the viewer: saved state, follow-ups
|
|
66
|
+
source: `the design “${title}”`,
|
|
67
|
+
enabled: artifact.type === "html",
|
|
68
|
+
onMessage(message, frame) {
|
|
69
|
+
// already checked and cleaned
|
|
70
|
+
if (message.type === "pocket-picked") addPin(message.target);
|
|
71
|
+
else if (message.type === "pocket-text-edited") addEdit(message);
|
|
72
|
+
else if (message.type === "pocket-tweaks") setKnobs(message.knobs);
|
|
73
|
+
else if (message.type === "pocket-deck") setSlide(message.slides, message.current);
|
|
74
|
+
},
|
|
75
|
+
onReady(frame) {
|
|
76
|
+
// the page opened its line (it just started)
|
|
77
|
+
bridge.send({ type: "pocket-highlight", targets: openComments.map(toPin) });
|
|
78
|
+
},
|
|
79
|
+
});
|
|
80
|
+
|
|
81
|
+
bridge.send({ type: "pocket-inspect", on: true }); // true: sent or queued
|
|
82
|
+
bridge.send({ type: "pocket-tweak-set", values: { "--accent": "#f00", "--radius": 12 } });
|
|
83
|
+
bridge.send({ type: "pocket-goto", slide: 2 });
|
|
84
|
+
bridge.ready(); // has the page opened its line
|
|
85
|
+
|
|
86
|
+
html`<iframe ref=${frame} key=${`${id}/${version}`} src=${src} sandbox="allow-scripts …" />`;
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
- `useArtifactBridge(ref, settings)` returns the same `{ send, ready }` on each render. `onMessage` and `onReady` may change between renders; the bridge is made again only when `artifact`, `source`, or `enabled` change. `enabled: false` (SVG, Markdown) gives `send` that returns false.
|
|
90
|
+
- `send(message)` checks the message (`checkAppMessage`), then sends it down the line, or **queues** it (the newest of each type; tweak values merge) when the frame has not loaded a page yet, and sends the queue when the page opens its line. It returns false when the message is wrong, or the page has no line (it never had a bridge, or it went to another page). Turning inspect or text edit **on** also needs `canSteer()`: a viewer gets false. Viewers may still send pins, goto, and tweaks: C hides what they must not use.
|
|
91
|
+
- **One line for one page.** The frame's first page opens the line, and a page it goes on to gets none. To show another version or artifact, **make a new iframe** (`key` on the artifact and version), and use `onReady` to say again what the canvas needs (modes, pins, tweak values, slide).
|
|
92
|
+
- Without a component: `attachBridge(ref, settings)` returns `{ send, ready, detach }`. `sendToFrame(frame, message, { wait })` sends to a frame that a bridge covers.
|
|
93
|
+
- `checkPageMessage(data)` and `checkAppMessage(raw)` are exported (tests use them). `LIMITS` has the numbers.
|
|
94
|
+
- Message shapes, after the app checked them. `Target`: `{ pid?, selector, tag, text (≤200), html (≤1000), rect: { x, y, width, height }, styles }` with `styles` having only these keys that the page had: `color`, `background-color`, `font-family`, `font-size`, `font-weight`, `line-height`, `padding`, `margin`, `border-radius`, `gap`. `Knob`: `{ name, label?, type, value, min?, max?, step?, unit?, options? }`, at most 40, names once each. A selector over 500 characters, or a `before` or `after` over 2,000, makes the message be dropped.
|
|
95
|
+
- Keys go to the frame only when it has focus. When focus is in the app, C moves slides with `pocket-goto`.
|
|
96
|
+
- Moving between pins and the page: a pin shows `label` (or its place in the list); the page has no way to say a pin was tapped.
|
|
97
|
+
|
|
98
|
+
## For stream D (the guide, preview, export)
|
|
99
|
+
|
|
100
|
+
Pi needs to be told, in `designGuide`:
|
|
101
|
+
|
|
102
|
+
- **Pids**: `data-pid="hero"` on meaningful elements; a pick or a pin falls back to the nearest one.
|
|
103
|
+
- **Tweaks manifest**: `<script type="application/json" id="pocket-tweaks">[ { "name": "--accent", "label": "Accent", "type": "color", "value": "#3366ff" }, { "name": "--radius", "type": "range", "value": 12, "min": 0, "max": 32, "step": 1, "unit": "px" } ]</script>`. 3 to 8 knobs. Types: `range`, `color`, `select` (with `options`), `toggle`, `text`. The CSS must use the variables (`var(--accent)`). A knob that is not a `--name` is only an event: `addEventListener("pocket:tweak", (e) => e.detail.name / e.detail.value)`.
|
|
104
|
+
- **Decks**: `<meta name="pocket-kind" content="deck">`, slides as `<section class="slide">`, each authored at **1920×1080** (the page side sets that size and scales it), no own navigation script needed. Slide-by-slide work (`design_preview({ slide })`, PPTX images): load the page from `/a/…` as a page of its own (no bridge, deck script only), set the viewport to the slide size, press `ArrowRight` through CDP; the current slide has `data-pocket-current`. The print media rule shows all slides one on each page, with `@page` at the slide size.
|
|
105
|
+
- A page that is not a deck loaded from `/a/…` as a page of its own is as written (no script added).
|
|
106
|
+
|
|
107
|
+
## What the docs must say
|
|
108
|
+
|
|
109
|
+
- `docs/map.md`: `web/artifact-bridge.js` row: also the design messages (`sendToFrame`, `attachBridge`, `checkPageMessage`, `checkAppMessage`). New row, `src/server/http/artifact-inspect.ts`: the page side of Design mode (inspect, text edit, tweaks, pins, decks), `ARTIFACT_INSPECT`, `withDeck`. The "rules that are easy to break": the inspector script has no backtick, and it sits in a template string.
|
|
110
|
+
- `docs/features.md`: in Artifacts or Design mode: a deck is a page with the meta and `section.slide`; the tweaks manifest; the message list above (one line each) for people who write pages by hand.
|
|
111
|
+
- `docs/architecture.md` (if it lists the bridge): the line now also goes down from the app, and the page→app design messages come only from the inspector.
|
|
112
|
+
- Release notes: "Artifact pages can be inspected, edited in place, tweaked, pinned, and presented as decks (the bridge for Design mode). A deck opened as a page of its own, or published, shows one slide at a time."
|
|
113
|
+
|
|
114
|
+
## Open problems
|
|
115
|
+
|
|
116
|
+
- A deck's slides are forced to 1920×1080 (width, height, and the min and max of each). A page that already scales its own slides (100vw) gets the same result, but its own scaling script and this fight if it moves slides itself.
|
|
117
|
+
- Inspect and pins cannot reach inside an iframe or a closed shadow root in the page. A `<canvas>` is one element.
|
|
118
|
+
- A page that navigates itself (a link, `location`) loses the line: its next page is not heard. C must show a new version in a new iframe, as written above.
|
|
119
|
+
- Text edit does not reach text in an element that also has a block element inside it (`li` with a nested list), or text that is longer than 2,000 characters.
|
|
120
|
+
- The selector is `#id`, `[data-pid]`, or a short chain with `:nth-of-type`. It names the element in this version, not in a later one that moved it. Pins fall back to the pid.
|
|
121
|
+
- The pins take no pointer: a tap on a pin in inspect mode picks the element below. A pin cannot say it was tapped. If C needs that, add a message (`pocket-pin-tapped`) and a pointer-taking pin.
|
|
122
|
+
- `ARTIFACT_INSPECT` makes each HTML artifact's page about 36 KB longer. If this matters, serve it as a script from the server and load it from the bridge (the sandbox allows that to the app's own address).
|
|
123
|
+
- The shared Chromium test files run in parallel in `npm test`: under heavy load one of the older artifact bridge tests took over 30 seconds once. It passed on the next run.
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
# Stream C: the workspace
|
|
2
|
+
|
|
3
|
+
Branch `design/workspace`. The Design module: a wide panel beside the chat with the canvas, versions, comments, text edits, tweaks, variations, decks, export, and share.
|
|
4
|
+
|
|
5
|
+
## What is built
|
|
6
|
+
|
|
7
|
+
Server (`src/server/extensions/design.ts`, built in, on by default, title "Design"):
|
|
8
|
+
|
|
9
|
+
- Routes under `/api/x/design/` (all through `web.conversationRoute`, so Pi Pocket checks that the person sees the session, and for a write that they steer):
|
|
10
|
+
- `GET c/:conversation/artifacts`: the session's HTML designs with `group`, `kind`, and each version's `restoredFrom`.
|
|
11
|
+
- `GET c/:conversation/designs/:artifact`: all comments and this person's tweaks.
|
|
12
|
+
- `POST …/comments`, `POST …/comments/:id` (words, resolved), `DELETE …/comments/:id`, `POST …/resolve` (many ids): comments. Everyone who sees the session reads them; people who steer write them. Only the author or the owner changes the words or deletes.
|
|
13
|
+
- `POST …/tweaks`: this person's tweak values for the design, replaced as a whole (`values: null` clears).
|
|
14
|
+
- `POST …/restore` (`{ version, key }`): "Go back to this one", see below.
|
|
15
|
+
- `POST export` (stream D's route, registered by `designRoutes`): see "Export".
|
|
16
|
+
- The `/design-open [artifact]` command. It is `design-open`, not `design`: a command's name must have a dash (`COMMAND_NAME` in `extension-web.ts`). It sends `open` to the tab of the person who ran it, which opens the panel.
|
|
17
|
+
- Events to browsers: `comments` (`{ conversation, artifact }`, after any comment change) and `open`.
|
|
18
|
+
- Registered in `reload.ts`: `ORDER`, `TITLES`, and `design_preview`, `design_export`, `design_system` in `BUILT_IN_TOOLS`.
|
|
19
|
+
- Tools, the prompt guide, and the export route come from `../design/index.ts` (stream D), by a static import.
|
|
20
|
+
|
|
21
|
+
Document (`src/server/docs.ts`, appended at the end): `pocket.design-comments`, scope `conversation`, history `latest`, fork `current`. By artifact id: `comments[]`, `tweaks` (by person id), `restores` (new version → copied version). It is one kind for comments, tweaks, and restores; the name is the plan's.
|
|
22
|
+
|
|
23
|
+
Browser module (`src/server/extensions/design/`, folder served with `web.client("design", { access: "view" })`):
|
|
24
|
+
|
|
25
|
+
- `index.js` sets up a panel (`wide`), a rail button, a launcher action, and listeners. It keeps the workspace state in one store made at load (`state.js`), outside the panel's component, so going back to the chat on a phone and coming again leaves the canvas as it was.
|
|
26
|
+
- `workspace.js` (picker, toolbar, tabs, menu, layout), `canvas.js` (the frame, the page side of every mode through the bridge), `docks.js` (versions, comments, text edits, tweaks), `views.js` (compare, variations grid, slide strip, present mode), `data.js` (what it asks of the server), `parts.js`, `style.css`.
|
|
27
|
+
- Pure helpers with tests: `devices.js`, `tweaks.js`, `edits.js`, `messages.js`, `comments.js`.
|
|
28
|
+
|
|
29
|
+
In `web/sheets/viewers.js`: an "Open in Design" button in the artifact viewer (only when the Design module is ready in this tab), and, in the share sheet, "close goes back to where it was opened from" (a prop `back: "design"` in the sheet state: closing goes to the canvas, not to the viewer). The second is a small step past "a button only"; it is 3 lines.
|
|
30
|
+
|
|
31
|
+
## How it looks and behaves
|
|
32
|
+
|
|
33
|
+
- Panel: on a screen ≥ 1100 px it is beside the chat. Its width is `max(480px, min(58%, 100% - 760px))` (`style.css`), so the chat keeps 440 px. Under 1100 px it covers the chat, with the app's back button.
|
|
34
|
+
- Bars: the picker (designs newest first, a group kept together), a size choice (phone 390×844, tablet 820×1180, desktop 1280×800, custom; a deck has 1280×720 in place of desktop), "…" menu (backdrop, reload, compare, variations, present, export, share, open in tab). Tabs: Preview, Comment, Edit text, Tweaks, Versions; icon buttons for compare, variations (a group of 2 or more), present (a deck).
|
|
35
|
+
- The side panel (the dock) sits beside the canvas on a wide panel (≥ 900 px), or on a narrower one that shows a tall page (phone, tablet); under the canvas otherwise (and always below 560 px).
|
|
36
|
+
- Canvas: fit (never past 100%) or zoom steps, size readout, light/dark/theme backdrop. What a person chose (size, zoom, backdrop) is kept in this browser (`localStorage`); the design last open is kept in the tab for each session.
|
|
37
|
+
- A new design that appears while the panel is open opens, unless the person is in a mode, has a draft or edits, or it is a variation of the open design (it shows in the grid).
|
|
38
|
+
|
|
39
|
+
## What the workspace says to the bridge (stream B)
|
|
40
|
+
|
|
41
|
+
Uses `useArtifactBridge(ref, { artifact, source, enabled, onMessage, onReady })` returning `{ send }`, as stream B built it (`attachBridge`). If the hook returns nothing (a copy without stream B), the canvas still works and says "needs the frame's inspector" in the mode hints.
|
|
42
|
+
|
|
43
|
+
- `pocket-inspect` / `pocket-edit-text` on or off with the mode. `pocket-highlight` with `{ pid, selector, label }`, where `label` is the pin's number (the order of open comments made on the version shown). `pocket-tweak-set`: only what differs from what the page was last told (a fresh page has been told nothing), and the page's default again for a knob that returns to it. For a name starting with `--` that has a `unit`, the value goes as text with the unit (`"20px"`); a toggle for such a name goes as `"1"` or `"0"`. Any other name gets the raw value. `pocket-goto` with a 0-based slide (the strip shows it plus 1).
|
|
44
|
+
- Takes `pocket-picked`, `pocket-text-edited`, `pocket-tweaks`, `pocket-deck`. It cleans them again (shape and length) before use, and the server cuts a comment's target to a fixed shape.
|
|
45
|
+
|
|
46
|
+
## Choices where the plan let me choose
|
|
47
|
+
|
|
48
|
+
- "Go back to this one" writes the version directly, in one commit of the route (`request.commit`): a copy of the old version's record (assets included, as the record carries them) and of its body, with the same `taskId` and a new `callId` (`design-restore:<key>`), which no real tool call matches. A repeated tap with the same `key` finds its version. It also notes `restores[new] = old` so the timeline says "from v1". It never asks Pi.
|
|
49
|
+
- Everything that goes to Pi goes into the message box with `pocket.insertText`: the module has no way to send. Comments ("Send N to Pi"), text edits ("Apply N with Pi"), tweaks ("Keep these N"), a chosen variation ("Use this one"). Each text starts with a letter (never a command), and puts element data as JSON in a fence longer than any run of backticks inside it. On a phone the panel closes after it, so the box shows.
|
|
50
|
+
- Comments are shared. Tweaks are per person (the plan allowed this module's own storage or the new kind: it is the new kind).
|
|
51
|
+
- The design list is the app's own live one (`view.artifacts`), merged with the server's list for `group`, `kind`, `restoredFrom`. This is why the module imports `/store.js`. It also imports `/artifact-bridge.js`: the same frame and bridge as the viewer.
|
|
52
|
+
- Viewers see the canvas, versions, and comments, and have no Edit text or Tweaks tab, no comment actions, no send buttons, and no "Go back". The server enforces it: the write routes are for those who steer, so a viewer gets the 404 that any person gets for a route that is not theirs.
|
|
53
|
+
- Download of an export: see below.
|
|
54
|
+
|
|
55
|
+
## Export
|
|
56
|
+
|
|
57
|
+
Stream D's route is `POST /api/x/design/export` with `{ conversation, id, version?, format, viewport }`; it writes the file in the session's `exports/` folder and answers `{ path, relative, name, size }`. The buttons POST it, then save the file through core's `GET /api/c/<conversation>/download?path=<relative>` (a link with `download`; no header needed), and say where it is saved.
|
|
58
|
+
|
|
59
|
+
## What the docs must say
|
|
60
|
+
|
|
61
|
+
`features.md`:
|
|
62
|
+
|
|
63
|
+
- Design mode: a canvas panel; versions with compare and "go back to this one"; comments shared with the session, pinned to elements, sent to Pi as one message; edit text and apply; tweaks kept per person and kept into the design by Pi; variations as a grid ("use this one"); decks with a slide strip and present mode; export (PNG, PDF, PPTX, HTML zip); share; "Open in Design" in the artifact viewer; `/design-open`.
|
|
64
|
+
- Who: everyone who sees every session loads it; people who steer write; viewers read; people invited to one session never load it (a module is for the whole app). While "take turns" is on, only the driver comments (core checks it for routes bound to a session).
|
|
65
|
+
|
|
66
|
+
`map.md`: `extensions/design.ts` (routes, document, command; installs `../design/index.ts`'s tools, guide, and export route), `extensions/design/` (the folder, what each file does), `docs.ts`' `DesignCommentsDoc`, `reload.ts`' entries, `viewers.js` (the button and `back`). Mention that the module imports `/store.js` and `/artifact-bridge.js`.
|
|
67
|
+
|
|
68
|
+
Release notes: Design mode; "go back to this one" makes a copy as a new version; comments are shared and durable; tweaks stay with the person.
|
|
69
|
+
|
|
70
|
+
`docs/extensions/built-in.md` or `architecture.md`: the module's document and its use of `../design/index.ts`.
|
|
71
|
+
|
|
72
|
+
## Tests
|
|
73
|
+
|
|
74
|
+
`test/design-routes.test.ts` (HTTP: access, shape cutting, limits, restore, tweaks, export), `test/design-parts.test.ts` (the pure helpers), `test/design-ui.test.ts` (a real Chromium: panel, sizes, picker and groups, grid, versions, restore, compare, comments and the message, viewer button, `/design-open`, share, viewer role, phone layout; pointing, tweaks, and decks run when this copy has stream B's bridge). `test/design-fixtures.ts` makes the designs (a landing page in three versions, a deck, three variations) and is also what I used to look at it by hand.
|
|
75
|
+
|
|
76
|
+
## Changes to files outside my stream
|
|
77
|
+
|
|
78
|
+
- `test/extension-commands.test.ts`: one assertion expected no commands at all after a drop-in went; the built-in `design-open` command is now always there, so it filters that name out.
|
|
79
|
+
- `web/sheets/viewers.js`: see above.
|
|
80
|
+
|
|
81
|
+
## Open problems
|
|
82
|
+
|
|
83
|
+
- A page inside the frame that goes on to another page (`about.html`) has no bridge, so comment, edit, pins, and tweaks go quiet on it with no message.
|
|
84
|
+
- While Pi makes a new version, the person in a mode, with a draft, or with text edits stays on the version they work on and sees "Version N of M" with a way to the newest. Otherwise the canvas follows the newest.
|
|
85
|
+
|
|
86
|
+
- `/design` itself cannot be a command (names need a dash); core could add a one-word client command in `web/commands.js` that calls `openExtPanel("design", "design")`.
|
|
87
|
+
- Comments are tied to the version they were made on. A comment's pin shows only on that version. Nothing moves a comment to a newer version when Pi makes one: "mark them done" is manual (a button after "Send to Pi").
|
|
88
|
+
- Writes to a design's notes need the turn when "take turns" is on, because core checks it for any route bound to a session.
|
|
89
|
+
- On a phone, a 1280 px page at "fit" is about 28% (a deck slide too). Zoom and custom sizes are there; there is no pinch zoom.
|
|
90
|
+
- The present mode uses the browser's full screen when it can; inside it Esc is the browser's and ends it.
|
|
91
|
+
- The module imports two app files (`/store.js`, `/artifact-bridge.js`). Both are served by the same server; if either moves, the module fails to load (and the Extensions sheet says so).
|
|
92
|
+
- `npm run format` also rewrites `src/server/extensions/prompt.ts` on `release/0.26.0` (a missing brace). I left it alone.
|