@botiverse/porthole 0.3.3 → 0.3.4

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.
@@ -19,8 +19,9 @@ export type CapabilityHandlers = {
19
19
  readonly [N in HandledCapability]?: CapabilityHandler<N>;
20
20
  };
21
21
  /**
22
- * The display a confirmation is for, as the host named it: its id and title, and the instance it
23
- * shows where it is served (P076), so a host can word its dialog from its own records.
22
+ * The display a confirmation is for, as the host named it: its id and title, and the instance the
23
+ * host gave it, served or opaque (P076, P077), so a host can word its dialog from its own records.
24
+ * Host-side only: none of it is the content's word, and an opaque frame never gets the instance.
24
25
  */
25
26
  export interface ConfirmDisplay {
26
27
  readonly id: string;
@@ -51,7 +51,11 @@ export interface MountOptions {
51
51
  readonly scheme: ColorScheme;
52
52
  /** Handlers for this display only, over the host's. */
53
53
  readonly handlers?: CapabilityHandlers;
54
- /** Domain and external isolation: the instance to locate. */
54
+ /**
55
+ * Domain and external isolation: the instance to locate. Opaque: the host's own name for what
56
+ * the display shows, given back to the host in its confirmations (`ConfirmRequest.display`) and
57
+ * never sent to the frame (P077).
58
+ */
55
59
  readonly instance?: InstanceRef;
56
60
  /** A whole document the frame starts with (an MCP Apps view), hardened by the shell. */
57
61
  readonly document?: string;
@@ -126,7 +126,10 @@ export interface PortholeFrameProps {
126
126
  readonly partial?: boolean;
127
127
  /** A whole document to start with (an MCP Apps view). */
128
128
  readonly document?: string;
129
- /** Domain and external isolation: the instance to show. */
129
+ /**
130
+ * Domain and external isolation: the instance to show. Opaque: the host's own name for what it
131
+ * shows, for its confirmations only, never sent to the frame (P077).
132
+ */
130
133
  readonly instance?: InstanceRef;
131
134
  /** The color scheme it shows in. Default: the provider's `scheme`, else light. */
132
135
  readonly scheme?: ColorScheme;
@@ -22,7 +22,10 @@ export interface PortholeFallbackProps extends FrameFallback {
22
22
  export interface PortholeViewProps extends Omit<PortholeFrameProps, "config" | "instance" | "content" | "fill"> {
23
23
  /** The display kind (`defineDisplays`). */
24
24
  readonly display: string;
25
- /** The instance to show while frames are served. */
25
+ /**
26
+ * The instance: what a served frame shows; for an opaque one, the host's own name for it, given
27
+ * back in its confirmations only, never sent to the frame (P077).
28
+ */
26
29
  readonly instance?: InstanceRef;
27
30
  /**
28
31
  * The content: a served shell's to draw, and what an opaque frame shows while frames aren't
@@ -73,7 +73,7 @@ export function PortholeView(props) {
73
73
  if (failed !== null) {
74
74
  return _jsx(_Fragment, { children: (fallback ?? DefaultFallback)({ ...failed, link, retry }) });
75
75
  }
76
- return (_jsx(PortholeFrame, { ...frame, config: config, generation: (frame.generation ?? 0) + generation, ...(served && instance !== undefined ? { instance } : {}), ...(content === undefined ? {} : { content }), onOutcome: (outcome) => {
76
+ return (_jsx(PortholeFrame, { ...frame, config: config, generation: (frame.generation ?? 0) + generation, ...(instance === undefined ? {} : { instance }), ...(content === undefined ? {} : { content }), onOutcome: (outcome) => {
77
77
  onOutcome?.(outcome);
78
78
  const said = frameFallback(outcome, { url });
79
79
  if (said !== null) {
package/docs/ADOPTING.md CHANGED
@@ -66,8 +66,8 @@ a copy button copied), and `renderConfirm` (your own dialog, given `accept`, `de
66
66
  `redirect`: Porthole keeps the queue, runs `accept` inside its click, and counts declines toward
67
67
  muting the display; `redirect`, for "edit it first", answers the call `"redirected"` and neither
68
68
  counts nor resets the count). The request names the display (`request.display`: its `id`,
69
- `title`, and the `instance` a served frame shows), so the dialog can say what it is from your own
70
- records. `useRunAgain()` gives a "run again" button.
69
+ `title`, and the `instance` you gave the frame, served or opaque), so the dialog can say what it
70
+ is from your own records. It stays on your side: an opaque frame never gets the instance. `useRunAgain()` gives a "run again" button.
71
71
 
72
72
  ## 4. Served pages: the host kit
73
73
 
package/docs/DECISIONS.md CHANGED
@@ -2142,3 +2142,21 @@ and the failure shows only where the path runs.
2142
2142
  for an opaque one); `test/kit03.test.ts` (a host made in the `listen` callback is checked without a
2143
2143
  request, once, however often it is started).
2144
2144
 
2145
+ ## P077 · 2026-10-12 · A confirmation names the host's instance in opaque frames too · Accepted
2146
+
2147
+ **Decision.** P076 gave `ConfirmRequest.display` the instance only where the frame is served,
2148
+ because `PortholeView` handed the instance to its frame only then. The instance is the host's own
2149
+ value in both modes: Ferry passes `instance={widgetInstance(sessionId)}` to `PortholeView`
2150
+ whether its frame ends up served or opaque (the content domain down, absent on a self-hosted
2151
+ server, the first seconds before the probe). 0.3.4: `PortholeView` gives its frame the instance
2152
+ in both modes, and an opaque mount's `instance` (`MountOptions`, `PortholeFrame`) is documented
2153
+ as the host's own name for what it shows, given back in its confirmations only.
2154
+
2155
+ **Never sent to the frame.** An opaque frame's document is the shell built from the config, with
2156
+ no instance in it; the instance is used to locate only a served frame, and the bridge's display
2157
+ (where confirmations get it) stays on the host's side. A served frame already knows its scope:
2158
+ its origin is named from it.
2159
+ **Measured.** `leak/react.spec.ts`: `renderConfirm` names the instance the host gave, served and
2160
+ opaque (failing on 0.3.3 for opaque); for an opaque frame, the instance is in none of the frame's
2161
+ attributes, its document, its address or name, nor any message its page heard.
2162
+
package/docs/DESIGN.md CHANGED
@@ -541,7 +541,8 @@ What both adopters still wrote after 0.2 moves into Porthole (ADOPTING.md is the
541
541
  opaque, with its fallback), `usePortholeLink`, and the provider's shared `scheme`, `theme`
542
542
  (`cssVariableTheme`), `nonce: "auto"`, `handlers`, `openLink`, `notify` and `renderConfirm`
543
543
  (`accept`, `decline`, and `redirect`: `"redirected"`, which doesn't count toward muting, P074;
544
- the request's `display` carries the served frame's `instance`, P076).
544
+ the request's `display` carries the instance the host gave the frame, served or opaque, and an
545
+ opaque frame never gets it, P076, P077).
545
546
  A flip of the provider's scheme or a new themeKey re-themes running frames in place: no effect
546
547
  that makes a display depends on the context value those renew (#9, P074).
547
548
  - **The viewer handoff** for a page that holds a token: `POST /porthole/handoff` with the app's
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@botiverse/porthole",
3
- "version": "0.3.3",
3
+ "version": "0.3.4",
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
  "license": "Apache-2.0",
6
6
  "bin": {
@@ -30,8 +30,9 @@ export type CapabilityHandler<N extends CapabilityName> = (
30
30
  export type CapabilityHandlers = { readonly [N in HandledCapability]?: CapabilityHandler<N> };
31
31
 
32
32
  /**
33
- * The display a confirmation is for, as the host named it: its id and title, and the instance it
34
- * shows where it is served (P076), so a host can word its dialog from its own records.
33
+ * The display a confirmation is for, as the host named it: its id and title, and the instance the
34
+ * host gave it, served or opaque (P076, P077), so a host can word its dialog from its own records.
35
+ * Host-side only: none of it is the content's word, and an opaque frame never gets the instance.
35
36
  */
36
37
  export interface ConfirmDisplay {
37
38
  readonly id: string;
package/src/host/types.ts CHANGED
@@ -51,7 +51,11 @@ export interface MountOptions {
51
51
  readonly scheme: ColorScheme;
52
52
  /** Handlers for this display only, over the host's. */
53
53
  readonly handlers?: CapabilityHandlers;
54
- /** Domain and external isolation: the instance to locate. */
54
+ /**
55
+ * Domain and external isolation: the instance to locate. Opaque: the host's own name for what
56
+ * the display shows, given back to the host in its confirmations (`ConfirmRequest.display`) and
57
+ * never sent to the frame (P077).
58
+ */
55
59
  readonly instance?: InstanceRef;
56
60
  /** A whole document the frame starts with (an MCP Apps view), hardened by the shell. */
57
61
  readonly document?: string;
@@ -359,7 +359,10 @@ export interface PortholeFrameProps {
359
359
  readonly partial?: boolean;
360
360
  /** A whole document to start with (an MCP Apps view). */
361
361
  readonly document?: string;
362
- /** Domain and external isolation: the instance to show. */
362
+ /**
363
+ * Domain and external isolation: the instance to show. Opaque: the host's own name for what it
364
+ * shows, for its confirmations only, never sent to the frame (P077).
365
+ */
363
366
  readonly instance?: InstanceRef;
364
367
  /** The color scheme it shows in. Default: the provider's `scheme`, else light. */
365
368
  readonly scheme?: ColorScheme;
@@ -37,7 +37,10 @@ export interface PortholeViewProps extends Omit<
37
37
  > {
38
38
  /** The display kind (`defineDisplays`). */
39
39
  readonly display: string;
40
- /** The instance to show while frames are served. */
40
+ /**
41
+ * The instance: what a served frame shows; for an opaque one, the host's own name for it, given
42
+ * back in its confirmations only, never sent to the frame (P077).
43
+ */
41
44
  readonly instance?: InstanceRef;
42
45
  /**
43
46
  * The content: a served shell's to draw, and what an opaque frame shows while frames aren't
@@ -144,7 +147,7 @@ export function PortholeView(props: PortholeViewProps): ReactElement | null {
144
147
  {...frame}
145
148
  config={config}
146
149
  generation={(frame.generation ?? 0) + generation}
147
- {...(served && instance !== undefined ? { instance } : {})}
150
+ {...(instance === undefined ? {} : { instance })}
148
151
  {...(content === undefined ? {} : { content })}
149
152
  onOutcome={(outcome: FrameOutcome) => {
150
153
  onOutcome?.(outcome);