@botiverse/porthole 0.16.0 → 0.16.1

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@botiverse/porthole",
3
- "version": "0.16.0",
3
+ "version": "0.16.1",
4
4
  "description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
5
5
  "homepage": "https://github.com/botiverse/porthole#readme",
6
6
  "bugs": {
@@ -53,7 +53,8 @@ export interface AnnotationAnchor {
53
53
  * outside is a box of no size on the nearest edge. A positioning hint only. It is in the frame's
54
54
  * own layout px: a host that scales or transforms the frame maps it through that transform too
55
55
  * (P105). A result's `documentRect` (P132) and a report's `lastLineDocumentRect` (P133) are the
56
- * same shape in the document's coordinates, and aren't clamped.
56
+ * same shape in the document's coordinates, and aren't clamped; nor is a pick's `pointDocument`
57
+ * (P150), a point there.
57
58
  */
58
59
  export interface AnnotationRect {
59
60
  readonly x: number;
@@ -180,6 +181,16 @@ export type AnnotationReport =
180
181
  readonly rect: AnnotationRect;
181
182
  readonly lastLineDocumentRect?: AnnotationRect;
182
183
  readonly scroll?: AnnotationScroll;
184
+ /**
185
+ * Where the person picked the element (P150): the point a click, a tap or a held finger
186
+ * picked it at, in the coordinates of `documentRect` (the point in the frame's viewport plus
187
+ * `scroll`), unclamped. For a host's UI by what was pointed at, where the element is larger
188
+ * than most of the frame: its place in the frame's viewport is this less `scroll`, which a
189
+ * host clips to the frame's box. Element picks only (a text selection that carries one is
190
+ * dropped), never without `scroll` (P137), and absent from a pick from the keyboard and from
191
+ * an older shell. The page's word: where to put the host's own UI, nothing more.
192
+ */
193
+ readonly pointDocument?: { readonly x: number; readonly y: number };
183
194
  }
184
195
  /** The text selection went away. */
185
196
  | { readonly type: "unselected" }
@@ -119,6 +119,14 @@ export function parseRect(value: unknown): AnnotationRect | null {
119
119
  * may be negative: an engine's overscroll); null for anything else.
120
120
  */
121
121
  export function parseScroll(value: unknown): AnnotationScroll | null {
122
+ return parsePoint(value);
123
+ }
124
+
125
+ /**
126
+ * A point (a pick's `pointDocument`, P150): two finite numbers within the coordinate limit, as a
127
+ * scroll is; null for anything else.
128
+ */
129
+ function parsePoint(value: unknown): { x: number; y: number } | null {
122
130
  if (!isRecord(value) || !coordinate(value.x) || !coordinate(value.y)) {
123
131
  return null;
124
132
  }
@@ -236,19 +244,33 @@ export function parseReport(value: unknown): AnnotationReport | null {
236
244
  ? undefined
237
245
  : parseRect(value.lastLineDocumentRect);
238
246
  const scroll = value.scroll === undefined ? undefined : parseScroll(value.scroll);
239
- if (anchor === null || rect === null || lastLineDocumentRect === null || scroll === null) {
247
+ // Where an element was picked (P150), in the document as the last line is.
248
+ const pointDocument =
249
+ value.pointDocument === undefined ? undefined : parsePoint(value.pointDocument);
250
+ if (
251
+ anchor === null ||
252
+ rect === null ||
253
+ lastLineDocumentRect === null ||
254
+ scroll === null ||
255
+ pointDocument === null
256
+ ) {
240
257
  return null;
241
258
  }
242
259
  // A pair, here (P137): a selection has never had one without the other.
243
260
  if ((lastLineDocumentRect === undefined) !== (scroll === undefined)) {
244
261
  return null;
245
262
  }
263
+ // A point only for an element, and with its scroll (P150, as P137): text has no point.
264
+ if (pointDocument !== undefined && (anchor.kind !== "element" || scroll === undefined)) {
265
+ return null;
266
+ }
246
267
  return {
247
268
  type: "selected",
248
269
  anchor,
249
270
  rect,
250
271
  ...(lastLineDocumentRect === undefined ? {} : { lastLineDocumentRect }),
251
272
  ...(scroll === undefined ? {} : { scroll }),
273
+ ...(pointDocument === undefined ? {} : { pointDocument }),
252
274
  };
253
275
  }
254
276
  case "unselected":
@@ -11,7 +11,7 @@ import type { ViewerInfo } from "../runtime/levels.ts";
11
11
  import type { RefusalReason } from "./refusal.ts";
12
12
 
13
13
  /**
14
- * The host-function bridge (ARCHITECTURE § Framework layer): carries a capability call from the
14
+ * The host-function bridge (DESIGN.md § Framework layer): carries a capability call from the
15
15
  * frame to the host's handler and its result back, checking at the boundary that the capability
16
16
  * is declared, that its arguments are well formed, and that every gate passes, in that order.
17
17
  * Adapters decode protocol messages into calls; the bridge alone decides whether they run.
@@ -383,7 +383,8 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
383
383
  * Every box a report carries, clamped to the frame's viewport as it is now (P104): the page
384
384
  * places the host's own UI nowhere outside its frame. A mark's `documentRect` and the
385
385
  * document's `scroll` (P132) pass as they were checked: where a mark is in the document,
386
- * offscreen too, which a clamp would erase; the host clips what it draws from them.
386
+ * offscreen too, which a clamp would erase; the host clips what it draws from them. So does a
387
+ * pick's `pointDocument` (P150).
387
388
  */
388
389
  const withinFrame = (report: AnnotationReport): AnnotationReport => {
389
390
  const viewport = frameViewport();
@@ -3,7 +3,7 @@ import type { FrameSource } from "../isolation/types.ts";
3
3
  import type { Transport } from "../transport/types.ts";
4
4
 
5
5
  /**
6
- * The platform-host seam (ARCHITECTURE § Platform hosts): what owns the isolation primitive and
6
+ * The platform-host seam (DESIGN.md § Platform hosts): what owns the isolation primitive and
7
7
  * the transport. The web's is an `<iframe>` with `postMessage`; a native web view is another
8
8
  * implementation of the same interface, not a fork.
9
9
  */
@@ -108,6 +108,9 @@ export const WORD_LATE = String.raw`(at, now) => {
108
108
  * them placed as the document scrolls, from one report and the followed mark's scroll;
109
109
  * - the last line (P133): where a selection or a mark's words end, in the document's coordinates
110
110
  * too (`lastLineDocumentRect`), so a host places its UI after them;
111
+ * - the point picked (P150): where a pointer picked an element (the click's or tap's point, a held
112
+ * finger's), in the document's coordinates too (`pointDocument`), so a host places its UI by what
113
+ * the person pointed at in an element larger than the frame;
111
114
  * - the selection followed (P138): what the last `selected` reported (the element picked, or the
112
115
  * words selected) is kept while the host follows the selection (`track` with `selection`) or said
113
116
  * at `start` that it will (`keepSelection`, P140), and nothing is kept otherwise; while followed
@@ -389,11 +392,15 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
389
392
  return rect === null ? null : inDocument(box(rect), scroll);
390
393
  };
391
394
  // What a selection's report adds to its box (P133): its last line, with the scroll it was
392
- // read at; neither where nothing of it is drawn.
393
- const placeOf = (found) => {
395
+ // read at; neither where nothing of it is drawn. An element's pick by a pointer adds where it
396
+ // was picked (P150): that point in the viewport, in the document by the same scroll.
397
+ const placeOf = (found, point) => {
394
398
  const scroll = scrollOf();
395
399
  const lastLineDocumentRect = lastLineOf(found, scroll);
396
- return lastLineDocumentRect === null ? {} : { lastLineDocumentRect, scroll };
400
+ if (lastLineDocumentRect === null) {
401
+ return {};
402
+ }
403
+ return point ? { lastLineDocumentRect, scroll, pointDocument: { x: point.x + scroll.x, y: point.y + scroll.y } } : { lastLineDocumentRect, scroll };
397
404
  };
398
405
 
399
406
  // The shell's own layer, over the content: marks, the outline of what would be picked.
@@ -1713,7 +1720,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1713
1720
  holdSelected(anchor, { element });
1714
1721
  picked = keeping && !followingSelection ? element : null;
1715
1722
  redraw();
1716
- tell(M.selected, Object.assign({ anchor, rect: box(elementRect.call(element)) }, placeOf({ element })));
1723
+ tell(M.selected, Object.assign({ anchor, rect: box(elementRect.call(element)) }, placeOf({ element }, { x, y })));
1717
1724
  }, HOLD_MS),
1718
1725
  };
1719
1726
  }, true);
@@ -1765,7 +1772,10 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
1765
1772
  // only for a host that will follow it (P140): for any other it goes with the pick.
1766
1773
  picked = keeping && !followingSelection ? element : null;
1767
1774
  draw();
1768
- tell(M.selected, Object.assign({ anchor, rect: box(elementRect.call(element)) }, placeOf({ element })));
1775
+ // Where it was clicked or tapped (P150), the point the element was found under; a click
1776
+ // from the keyboard (no detail) has no point.
1777
+ const point = event.detail === 0 ? null : { x: event.clientX, y: event.clientY };
1778
+ tell(M.selected, Object.assign({ anchor, rect: box(elementRect.call(element)) }, placeOf({ element }, point)));
1769
1779
  }, true);
1770
1780
  window.addEventListener("keydown", (event) => {
1771
1781
  if (event.key !== "Escape") {
@@ -1,326 +0,0 @@
1
- # Architecture
2
-
3
- This describes the layers, their contracts, the flows and trust boundaries, and
4
- the extension points. It is meant to stay stable while concrete APIs change; the
5
- phase-1 API lives in [DESIGN.md](DESIGN.md). What the boundaries protect, from whom,
6
- and what each use guarantees and leaves to the host is in
7
- [THREAT_MODEL.md](THREAT_MODEL.md).
8
-
9
- ## The core abstraction
10
-
11
- Porthole renders **agent-drawn HTML plus a declared set of host functions.**
12
-
13
- - The HTML is untrusted. It may draw anything, but on its own it can only draw.
14
- - A **host function (capability)** is any power beyond drawing: send a prompt to
15
- the agent, open a link, read or write state, call a tool, read data, report an
16
- error. Each is named in the config and carries three facts: its **gate** (needs
17
- a user gesture, needs a person's confirmation, is shown to the person first, is
18
- rate-limited), its **egress
19
- needs** (origins it must reach), and its **guide entry** (how the manual
20
- describes it).
21
-
22
- A page published as an artifact may be an app: under the **capability runtime**, an optional
23
- layer over the display (THREAT_MODEL.md says what each guarantees), it reaches its
24
- host through one global, `porthole.use(name)`, for the capabilities it declared and its viewer's
25
- level allows. The runtime is how content reaches host functions, not new ones: each of its
26
- methods is served by a host function the config declares, and the bridge alone decides each call
27
- (the page's declaration, the viewer's level, the gates). The services behind them (a document
28
- store, an asset library, versions, comments) are the host's.
29
-
30
- One capability list therefore drives three artifacts: the **bridge** (which
31
- functions the shell wires and the host handles), the **CSP** (what the sandbox
32
- may reach), and the **manual** (what the agent is told). This is why the config
33
- is the single source (PRINCIPLE 3) and why "talk to the agent" is not special —
34
- it is one host function (PRINCIPLE 4).
35
-
36
- ## Layers
37
-
38
- ```
39
- ┌──────────────────────────────────────────────────────────┐
40
- │ Host app (owns product policy, theme, callbacks) │
41
- └───────────────┬──────────────────────────────────────────┘
42
- │ picks a preset, passes theme + callbacks
43
- ┌─────────────────────────▼─────────────────────────────────────────┐
44
- │ PRESET POLICY LAYER │
45
- │ inline-widget · artifact · mcp-app · url │
46
- │ each = a config: CSP+origins, capabilities+gates, theme, guide │
47
- └─────────────────────────┬─────────────────────────────────────────┘
48
- │ one config
49
- ┌─────────────────────────▼─────────────────────────────────────────┐
50
- │ FRAMEWORK LAYER (mechanisms only, no policy) │
51
- │ │
52
- │ config compiler ── CSP + sandbox/allow attrs │
53
- │ └── shell runtime (what to wire) │
54
- │ └── guide + tool description │
55
- │ │
56
- │ isolation core · egress hardening · streaming render · auto-size │
57
- │ theming · host-function bridge · guide gen · serving (/server) │
58
- └───────┬───────────────────────────────────────┬────────────────────┘
59
- │ host side │ in-frame side (shell)
60
- ┌───────▼─────────┐ ┌───────▼──────────────────┐
61
- │ PROTOCOL ADAPTER│ ◄── transport ──► │ SHELL (runs first in │
62
- │ (MCP Apps; …) │ (postMessage/ │ the isolated frame; │
63
- │ │ native bridge) │ renders HTML, wires caps)│
64
- └───────┬─────────┘ └───────────────────────────┘
65
- │
66
- ┌───────▼───────────────────────────────────────────────────────────┐
67
- │ PLATFORM HOST web (iframe) now · WKWebView / Android later │
68
- └─────────────────────────────────────────────────────────────────── ┘
69
-
70
- CONFORMANCE / LEAK SUITE drives a platform host through the adapter and
71
- probes every egress and escape channel (runnable by any host).
72
- ```
73
-
74
- ### Framework layer (mechanisms)
75
-
76
- Pure mechanism, no product policy, no host or vendor types.
77
-
78
- - **Config compiler.** Turns one config into the CSP string, the iframe sandbox
79
- and `allow` attributes, the shell's wiring, and the guide + tool description.
80
- Deterministic and pure, so a test can assert the three outputs agree.
81
- - **Isolation core.** Places the content on an origin that is never the host's,
82
- with nothing of the host's reachable: an opaque-origin frame, or a served
83
- origin of its own (domain mode: a subdomain per storage scope on a separate
84
- registrable domain; url mode: the app's own origin). The mode is chosen by
85
- config; the rest of the framework does not depend on which.
86
- - **Egress hardening.** The closed-by-default network and navigation walls, plus
87
- the in-shell defenses for channels a CSP does not cover (see Trust boundaries).
88
- - **Shell runtime.** The code that runs first inside the frame: applies theme,
89
- inserts the HTML (streaming-aware), reports size and errors, and exposes the
90
- declared host functions to the content.
91
- - **Host-function bridge.** Carries capability calls from the shell to the host
92
- and results back, over a transport, with validation and gating at the boundary.
93
- - **Streaming render, auto-size, theming, guide generator.** The remaining
94
- mechanisms, each usable on its own. Content is plain HTML and SVG; its look
95
- comes from the theme variables, never from a component vocabulary (P015).
96
- - **Serving.** For served modes, a request handler a host's backend mounts: it
97
- serves documents on their own origins with their CSP in headers, and turns a
98
- one-time ticket the host minted into a cookie of that origin only. A stored
99
- version may be one page or a set of files: each file is looked up in the
100
- version's manifest only, typed by Porthole's own table, and served under that
101
- version's own address, so a page's relative addresses are its version's.
102
-
103
- ### Preset policy layer
104
-
105
- A preset is a named config with safe defaults. It fixes the CSP and allowed
106
- origins, the capabilities and their gates, the theme vocabulary, and the manual.
107
- A host adopts a preset and overrides only theme and callbacks.
108
-
109
- - **inline-widget** — host injects agent code into a strict, opaque-origin frame
110
- with a shell; smallest capability set; for cards inside a conversation.
111
- - **artifact** — a standalone page: written into an opaque frame where the host
112
- has it, or served at a URL on a separate registrable domain, CSP in headers,
113
- versioned.
114
- - **mcp-app** — renders a standard MCP Apps view (a `ui://` template plus tool
115
- input/result), using the MCP Apps adapter.
116
- - **url** — frames a running app by URL (a dev server's preview): isolation and
117
- access auth only; no shell, no capabilities, no egress control.
118
-
119
- ### Protocol adapters
120
-
121
- A thin adapter maps the framework's capability and lifecycle events onto a wire
122
- protocol. **MCP Apps** is the first and default. The adapter is the only layer
123
- that knows protocol method names and shapes; the core speaks capabilities.
124
-
125
- ### Platform hosts
126
-
127
- The platform host owns the actual isolation primitive and the transport: an
128
- `iframe` + `postMessage` on the web now; a `WKWebView` + message handler on iOS
129
- later. The framework layer is written against a small platform interface so a new
130
- platform is an implementation of that interface, not a fork.
131
-
132
- ### Conformance / leak suite
133
-
134
- A standalone test runner that drives a platform host through an adapter and
135
- attempts every known egress and escape channel, asserting none succeeds. Any host
136
- can run it against its own integration. It is both our regression gate and the
137
- artifact we offer upstream (PRINCIPLE 5, 6).
138
-
139
- ## Contracts between layers
140
-
141
- - **Host → preset:** a preset name, theme tokens (resolved per color scheme), and
142
- callbacks for each enabled host function. Nothing else is required.
143
- - **Preset → framework:** one config (capabilities with gates and egress needs,
144
- allowed origins, theme variable map, limits, layout, mode and isolation).
145
- - **Config → {CSP, shell, guide}:** derived, never hand-written; a test asserts
146
- agreement.
147
- - **Framework ↔ shell:** lifecycle and capability messages over a transport.
148
- Validated both directions; unknown or malformed messages are dropped.
149
- - **Framework ↔ adapter:** the adapter translates between capability/lifecycle
150
- events and protocol messages; it may add protocol-only messages (handshake,
151
- teardown) that the framework does not model.
152
- - **Framework ↔ platform host:** create an isolated surface, set its policy
153
- (CSP/sandbox/allow or the native equivalent), send and receive messages,
154
- report size, tear down.
155
-
156
- ## Flows per mode
157
-
158
- ### Inline widget
159
-
160
- ```
161
- Host app Framework/Adapter Shell (opaque frame)
162
- │ mount(config, cbs) │ │
163
- │──────────────────────────►│ compile config → CSP, │
164
- │ │ sandbox attrs, shell doc │
165
- │ │ create opaque frame ───────►│ (shell runs first)
166
- │ │◄──── initialize ─────────────│
167
- │ │──── host context (theme, │
168
- │ │ capabilities, size) ────►│
169
- │ content (may stream) ───►│──── content (partial*) ─────►│ draw inert
170
- │ │──── content (complete) ─────►│ run
171
- │ │◄──── size / error ───────────│
172
- │◄── onError / onResize ────│ │
173
- │ │◄──── capability call ────────│ (e.g. sendPrompt)
174
- │◄── gate (confirm?) ───────│ validate + gate │
175
- │── result ────────────────►│──── result ─────────────────►│
176
- ```
177
-
178
- `*` partial content is drawn inert (no scripts, handlers or navigation) until
179
- complete; see Streaming in DESIGN.md.
180
-
181
- ### MCP Apps view
182
-
183
- Same shape, with the adapter speaking MCP Apps: the view is an MCP Apps `App`;
184
- `initialize`/`initialized` is the handshake; content arrives as tool input
185
- (streamed as tool-input-partial, then tool-input) and tool result; capability
186
- calls are `ui/message`, `ui/open-link`, etc., which map to host functions. On the
187
- web a second-origin sandbox proxy relays messages so arbitrary MCP App HTML
188
- (which expects `allow-same-origin`) is isolated from the host; the proxy is
189
- transparent to the view and the host.
190
-
191
- ### Artifact page
192
-
193
- The content is served as a real document at a URL on a separate registrable
194
- domain with its CSP in HTTP headers; the host embeds that URL in a frame whose
195
- `frame-ancestors` names the host. No code injection, and the shell is optional.
196
- A page may come with files of its own (stylesheets, scripts, data, images, other
197
- pages): they are served beside it, under its version's own address, and its CSP
198
- opens that path and nothing else of its origin; every page of the set gets the
199
- shell.
200
- Access is gated by a one-time ticket exchanged for a scoped cookie. Where the host
201
- holds the page and needs no stable origin, the shell writes it into an opaque
202
- frame instead.
203
-
204
- ### URL frame
205
-
206
- ```
207
- Host app Host backend (+ /server) App origin (served)
208
- │ mount(url preset) │ │
209
- │── locate ─────────►│ decide the viewer may see it, │
210
- │◄── ticketed URL ───│ mint a one-time ticket │
211
- │ frame src = URL ──────────────────────────────────────►│ ticket → cookie
212
- │ │ (that origin only)
213
- ```
214
-
215
- No shell and no protocol: the app is someone else's. The embedding page frames
216
- only the declared content origins.
217
-
218
- ## Trust boundaries
219
-
220
- The attackers each boundary faces, what is out of scope, and the composition rule for
221
- several displays on one page are in [THREAT_MODEL.md](THREAT_MODEL.md).
222
-
223
- 1. **Host ↔ content.** The hard boundary. The content runs on an origin that is
224
- never the host's, so same-origin policy denies it the host's DOM, storage,
225
- cookies and credentials. Everything it wants beyond drawing crosses the bridge
226
- as a validated, gated capability call. *What each side may know:* the content
227
- never holds a host secret; whatever it says, the host treats as the content's
228
- own word and confirms with a person before acting where the capability's gate
229
- says so.
230
-
231
- 2. **Content ↔ the outside network.** Closed by default and opened only to the
232
- origins the config's capabilities declare (and, for a served page with files,
233
- its own version's path on its own origin, and its artifact's asset library at `/_blob/`: the
234
- host's own server, P082, P089). Two
235
- kinds of attacker matter:
236
- - *Attacking the host* (steal credentials, read other data, escape the
237
- sandbox): stopped by origin isolation — the content is a stranger to the
238
- host origin.
239
- - *Leaking or deceiving* (exfiltrate what the content was already given, or
240
- draw a convincing fake to fool the viewer): origin isolation does not help
241
- here; egress hardening and gating do. Some channels (a peer connection's
242
- ICE gathering, a self-navigation of the frame, a nested frame in a fresh
243
- realm) reach the network outside a frame's own `connect-src`. These are
244
- closed by in-shell defenses and by the embedding page's own policy, each
245
- proven by a leak-suite probe (DESIGN.md lists them).
246
- - *A served page outside its frame* (a public link, a new tab) has no frame's sandbox and no
247
- embedding page: its own CSP header carries the frame's sandbox tokens, and the shell closes
248
- `window.open` and stops it navigating away (P099).
249
- - *An opaque frame is as closed as its page.* A `srcdoc` frame inherits the
250
- embedding page's whole policy as well as its own, so on a page with
251
- `default-src 'none'` and a tight `connect-src`/`img-src` its content is more
252
- closed than its config says: an origin the config opens stays shut. On such
253
- a page prefer domain mode, whose frames inherit nothing (P058).
254
-
255
- 3. **Host's decision ↔ what a page may do.** Under the capability runtime a page reaches only the
256
- built-ins and what it declared at publish (stored by the host, given to the mount), and each
257
- method only for viewers at its level (`view < interact < admin < owner`), which the host's
258
- access says. The bridge refuses before any handler; the host's own API checks again, since it
259
- is its data's wall. A person's per-user data is reached by the host's id for them, never the
260
- content's word.
261
-
262
- 4. **Message boundary.** Every message crossing the frame is validated against a
263
- schema and checked for sender identity before use; the shell accepts messages
264
- only from its host, and the host only from its frame. What the frame says about
265
- itself (its size, its errors, an annotation's anchor and where it is, how many
266
- matches find found) is the content's word even when the shell says it, since they
267
- share a realm: the host bounds it and uses it as a UI hint, never as a permission
268
- (P053, P131). What the host sends in (a mark, a find query) the content can read.
269
-
270
- 5. **Host's decision ↔ content domain.** Authentication and authorization
271
- *policy* are the host's; carrying the host's decision safely onto the content
272
- domain is Porthole's *mechanism*. The host decides who may open an instance
273
- before it calls `issue` (a viewer it knows, or a public link), and may decide
274
- again on every request (`ServerOptions.authorize`). Porthole carries the decision
275
- as a one-time ticket, then a signed cookie of that origin and instance only,
276
- with the host's opaque `subject` inside, and never interprets identity. A deny
277
- ends access from the next request on and tells the display why.
278
-
279
- ## Extension points
280
-
281
- - **Capabilities.** New host functions are added to the capability vocabulary
282
- with a gate, egress need, and guide entry. Adding one extends the bridge, the
283
- CSP, and the manual together.
284
- - **Protocol extension points.** MCP Apps gaps go through the spec's own
285
- mechanisms (experimental capabilities, own-prefixed methods), so the external
286
- contract stays standard (PRINCIPLE 2).
287
- - **Theme variables.** The theme map is config; the standard MCP Apps variable
288
- names are the default vocabulary.
289
- - **The person's clipboard** is the host's alone: content asks for a copy
290
- (`copyText`), the host performs it and shows what it copied (P051, P052).
291
- - **The capability runtime** (`config.runtime`): a contract version's capabilities, each a
292
- namespace of methods over host functions, with a versioned `.d.ts`; a host offers them through
293
- its config and serves them through its handlers; an artifact's asset library is served by
294
- `/server` from the host's store at `/_blob/<id>` on the artifact's origin.
295
- - **Annotations** (`annotate`): the host drives a select mode and marks anchors in
296
- the shell; anchors are W3C Web Annotation selectors a host stores with its own
297
- comments (P053). A mark may carry a count, drawn as a marker, a button at its
298
- paragraph's end (P133), whose click the host hears and answers with its own UI outside
299
- the frame (P104), and may be a draft, its author's unposted comment, drawn apart with a
300
- hollow marker (P107).
301
- - **Find in page** (`find`): the host draws its own find bar and asks the shell for
302
- a query (`porthole/find.query`, a request: how many matches, which is current);
303
- the shell finds it in the same text index annotations read, highlights it in a layer
304
- of its own, and says when the person pressed Cmd+F or Ctrl+F in the frame, where the
305
- host takes the shortcut (P131). An older shell answers "isn't offered here", and the
306
- host calls find unsupported there.
307
- - **Served content.** A host plugs its own policy and infrastructure into `/server`:
308
- who may see what (`authorize`), where tickets live (`TicketStore`: memory, D1),
309
- how origins are named (`content.name`, other servers' `reserved` namespaces),
310
- and where apps and artifact versions come from (`upstream`, `artifacts`: a page, or a
311
- manifest of files and their bytes), and which address means which version (`entry.at`). It runs
312
- on any runtime with web-standard `Request`/`Response` (Node, Workers).
313
-
314
- ## How a new protocol or platform plugs in
315
-
316
- - **A new protocol** is a new adapter implementing the capability/lifecycle
317
- translation. It does not touch the core, the shell mechanisms, or the presets
318
- beyond adding a preset that selects it. The capability abstraction is the seam.
319
- - **A new platform** is a new implementation of the platform-host interface
320
- (create isolated surface, set policy, transport, size, teardown). The framework
321
- layer, adapters and presets are unchanged; the shell runtime is plain,
322
- dependency-free script so it runs as-is in a new engine.
323
-
324
- This is what keeps the three answers independent: *which protocol* (adapter),
325
- *which platform* (platform host), and *what policy* (preset/config) each vary
326
- without the others changing.
@@ -1,116 +0,0 @@
1
- # Objectives
2
-
3
- ## What Porthole is for
4
-
5
- Any app that wants the "show content made by an agent" ability — like the inline
6
- visuals and standalone pages in ChatGPT and the Claude app — should be able to
7
- embed Porthole and get a working, safe display out of the box, plus the manual
8
- that teaches the agent to write for it.
9
-
10
- The library has two layers:
11
-
12
- - a **framework layer** of mechanisms (isolation, egress hardening, the in-frame
13
- shell, streaming, sizing, theming, the host-function bridge, the guide
14
- generator); and
15
- - a **preset policy layer** of ready-made bundles a host adopts with near-zero
16
- config: **inline widget**, **artifact** (a standalone page), **MCP Apps** (the
17
- standard protocol), and **URL** (a running app framed by URL, such as a dev
18
- server's preview).
19
-
20
- The subject, stated generally, is **HTML drawn by an agent that may optionally
21
- interact with the agent** — and that interaction is just one host function among
22
- several. "Out of the box" means: a host picks a preset, passes theme tokens and
23
- callbacks, and receives a safe display plus a generated agent manual.
24
-
25
- ## Objectives and success criteria
26
-
27
- 1. **Show untrusted agent HTML without putting the host at risk.**
28
- - *Success:* the conformance/leak suite passes on Chromium, WebKit and
29
- Firefox — every egress and escape probe attempts its channel and observes
30
- nothing; the content cannot reach the host origin, its storage, its DOM, or
31
- its credentials.
32
-
33
- 2. **One config generates the sandbox, the shell, and the manual, in agreement.**
34
- - *Success:* for every preset, a test derives the CSP, the shell's wired host
35
- functions, and the generated guide from the same config and asserts they
36
- match — the guide names only variables the shell injects and only
37
- capabilities the CSP and bridge allow; changing the config changes all
38
- three together.
39
-
40
- 3. **Speak the MCP Apps standard, proven against the reference implementation.**
41
- - *Success:* the MCP Apps preset renders and interacts with the official
42
- ext-apps example servers **unmodified** (initialize handshake, tool input
43
- and result, size and theme changes, open-link and message), driven in the
44
- leak suite.
45
-
46
- 4. **Embed with near-zero config across the modes.**
47
- - *Success:* a host mounts an inline widget, an artifact page, an MCP Apps
48
- view and a URL frame each in a few lines using only a preset, theme tokens
49
- and callbacks; the framework-agnostic core and the React binding both do
50
- this; no host-specific code lives in the core.
51
-
52
- 5. **Ship the agent manual as a first-class output.**
53
- - *Success:* each preset produces an agent-facing guide and tool description
54
- from its config; a real agent that reads the guide produces content that
55
- renders within the sandbox and reads correctly at the target widths in light
56
- and dark, checked by rendering the guide's own examples in the leak suite.
57
-
58
- ## Non-goals
59
-
60
- - **Host-drawn DSL rendering.** Rendering a JSON/JSX/remote-DOM UI description
61
- with the host's own native components (A2UI, json-render, remote-dom, JSX
62
- preview) is a separate concern and a different project. Porthole is the HTML
63
- sandbox only.
64
- - **A component vocabulary inside the sandbox.** Content is plain HTML and SVG,
65
- taught by the generated manual; a consistent look comes from the injected theme
66
- variables and, at most, plain base CSS for native elements, never from tags and
67
- props an agent must learn (P015). Nor is Porthole a design-system library.
68
- - **A new widget-side protocol.** The contract is MCP Apps; we do not define an
69
- alternative (PRINCIPLE 2).
70
- - **A shell or egress control for URL mode.** A URL frame is someone else's
71
- running app: Porthole gives it isolation and access auth, nothing more (P020).
72
- - **Operating infrastructure.** The serving part (`/server`) is a request handler a
73
- host mounts in its own backend; Porthole runs no service, domain or certificate
74
- of its own.
75
- - **Being an agent framework or an MCP server.** Porthole is host-side rendering
76
- and isolation. It does not run models, implement an MCP server, or decide
77
- product policy (PRINCIPLE 8).
78
-
79
- ## Who the users are
80
-
81
- - **Host app developers** who want to show agent-made HTML in a chat or canvas UI
82
- and do not want to build or audit an isolation layer themselves. They are the
83
- primary users: they embed the library and pick a preset.
84
- - **Agents (and the people prompting them)** who write the HTML. They are served
85
- indirectly: the generated manual is written for them, and the sandbox is the
86
- environment their code runs in.
87
- - **MCP App authors** who build standard MCP Apps and want them to render in any
88
- Porthole-based host unmodified.
89
-
90
- The first adopter is a normal user of the public API, with no privileged path
91
- (PRINCIPLE 9).
92
-
93
- ## What "done" means for phase 1
94
-
95
- Phase 1 is done when:
96
-
97
- - the framework-agnostic web core and the React binding (with its default,
98
- replaceable confirmation dialog) exist, with opaque-origin isolation, egress
99
- hardening, the shell runtime, streaming render, auto-sizing, theming, and the
100
- host-function bridge;
101
- - the served modes exist: domain mode (a stable origin per storage scope, CSP in
102
- headers, ticket → cookie for private content) with its `/server` request
103
- handler, the artifact page on it, and URL mode (frame, isolation and access
104
- auth only);
105
- - the presets exist (inline widget, artifact page, MCP Apps view, URL), each
106
- generating its CSP and frame policy, and all but URL its shell and manual, from
107
- one config;
108
- - the MCP Apps adapter runs the official ext-apps examples unmodified;
109
- - the leak/conformance suite passes on Chromium and WebKit, then Firefox, and is
110
- runnable by any host; and
111
- - the first host has migrated onto it (dogfooding), every one of its features
112
- that shows agent-made or foreign HTML (widgets, shown HTML files, the dev-server
113
- preview) going through Porthole, with its own code reduced to configuration
114
- plus callbacks.
115
-
116
- Native hosts (WKWebView, maybe Android) are phase 2.