@botiverse/porthole 0.6.0 → 0.8.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/README.md +25 -2
- package/THIRD_PARTY_NOTICES.md +421 -0
- package/dist/bridge/bounded-text.d.ts +34 -0
- package/dist/bridge/bounded-text.js +188 -0
- package/dist/bridge/bridge.d.ts +38 -5
- package/dist/bridge/bridge.js +469 -39
- package/dist/bridge/json-data.d.ts +28 -0
- package/dist/bridge/json-data.js +86 -0
- package/dist/bridge/navigation.d.ts +5 -0
- package/dist/bridge/navigation.js +7 -0
- package/dist/bridge/refusal.d.ts +5 -1
- package/dist/bridge/refusal.js +17 -0
- package/dist/bridge/types.d.ts +73 -5
- package/dist/check/check.d.ts +7 -0
- package/dist/check/check.js +1 -0
- package/dist/check/instrument.d.ts +3 -0
- package/dist/check/lint.js +4 -2
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +16 -0
- package/dist/check/tools.js +2 -3
- package/dist/compile/compile.d.ts +6 -0
- package/dist/compile/compile.js +3 -1
- package/dist/compile/policy.d.ts +55 -0
- package/dist/compile/policy.js +157 -0
- package/dist/config/capabilities.d.ts +85 -7
- package/dist/config/capabilities.js +32 -2
- package/dist/config/schema.d.ts +35 -0
- package/dist/config/validate.d.ts +9 -3
- package/dist/config/validate.js +92 -8
- package/dist/config/warnings.d.ts +20 -0
- package/dist/config/warnings.js +25 -0
- package/dist/conformance/behavior.js +46 -1
- package/dist/conformance/cookies.d.ts +15 -0
- package/dist/conformance/cookies.js +80 -0
- package/dist/conformance/harness/page.d.ts +1 -0
- package/dist/conformance/harness/page.js +9 -2
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/host-kit.js +5 -1
- package/dist/conformance/index.d.ts +11 -0
- package/dist/conformance/index.js +2 -0
- package/dist/conformance/limits.js +38 -1
- package/dist/conformance/runtime.d.ts +58 -0
- package/dist/conformance/runtime.js +324 -0
- package/dist/conformance/served.d.ts +2 -0
- package/dist/conformance/served.js +737 -4
- package/dist/files/paths.js +4 -0
- package/dist/guide/gates.d.ts +9 -0
- package/dist/guide/gates.js +31 -0
- package/dist/guide/guide.d.ts +2 -0
- package/dist/guide/guide.js +35 -33
- package/dist/guide/limits.js +4 -4
- package/dist/guide/runtime.d.ts +13 -0
- package/dist/guide/runtime.js +210 -0
- package/dist/host/create-host.js +73 -37
- package/dist/host/locate.js +8 -0
- package/dist/host/locator.js +7 -0
- package/dist/host/pages-of-set.d.ts +43 -0
- package/dist/host/pages-of-set.js +196 -0
- package/dist/host/types.d.ts +26 -1
- package/dist/index.d.ts +11 -4
- package/dist/index.js +11 -2
- package/dist/isolation/types.d.ts +8 -0
- package/dist/mcp/adapter.js +11 -15
- package/dist/node/index.d.ts +36 -4
- package/dist/node/index.js +402 -101
- package/dist/presets/presets.d.ts +22 -8
- package/dist/presets/presets.js +40 -8
- package/dist/protocol/live-data.d.ts +6 -2
- package/dist/protocol/live-data.js +20 -1
- package/dist/protocol/mcp-apps.d.ts +13 -2
- package/dist/protocol/mcp-apps.js +10 -2
- package/dist/protocol/message-text.d.ts +8 -0
- package/dist/protocol/message-text.js +29 -0
- package/dist/protocol/runtime-calls.d.ts +28 -0
- package/dist/protocol/runtime-calls.js +116 -0
- package/dist/protocol/shell-adapter.js +64 -25
- package/dist/react/context-notice.d.ts +32 -0
- package/dist/react/context-notice.js +28 -0
- package/dist/react/dialog.js +91 -16
- package/dist/react/frame.d.ts +25 -1
- package/dist/react/frame.js +85 -2
- package/dist/react/index.d.ts +2 -1
- package/dist/react/index.js +2 -1
- package/dist/runtime/contract.d.ts +201 -0
- package/dist/runtime/contract.js +245 -0
- package/dist/runtime/db.d.ts +188 -0
- package/dist/runtime/db.js +502 -0
- package/dist/runtime/declaration.d.ts +100 -0
- package/dist/runtime/declaration.js +363 -0
- package/dist/runtime/levels.d.ts +33 -0
- package/dist/runtime/levels.js +41 -0
- package/dist/runtime/requests.d.ts +125 -0
- package/dist/runtime/requests.js +215 -0
- package/dist/runtime/segments.d.ts +8 -0
- package/dist/runtime/segments.js +14 -0
- package/dist/runtime/types.generated.d.ts +1 -0
- package/dist/runtime/types.generated.js +19 -0
- package/dist/server/files.d.ts +19 -1
- package/dist/server/files.js +115 -6
- package/dist/server/host.d.ts +24 -2
- package/dist/server/host.js +137 -2
- package/dist/server/index.d.ts +3 -2
- package/dist/server/index.js +2 -1
- package/dist/server/peer.d.ts +4 -0
- package/dist/server/peer.js +19 -0
- package/dist/server/proxy.d.ts +6 -0
- package/dist/server/proxy.js +12 -3
- package/dist/server/pseudonym.d.ts +9 -0
- package/dist/server/pseudonym.js +20 -0
- package/dist/server/server.d.ts +0 -5
- package/dist/server/server.js +318 -52
- package/dist/server/types.d.ts +74 -2
- package/dist/shell/document.d.ts +16 -0
- package/dist/shell/document.js +19 -2
- package/dist/shell/legacy.d.ts +21 -0
- package/dist/shell/legacy.js +63 -0
- package/dist/shell/plan.d.ts +17 -1
- package/dist/shell/plan.js +13 -2
- package/dist/shell/runtime.js +390 -56
- package/dist/shell/use.d.ts +15 -0
- package/dist/shell/use.js +235 -0
- package/docs/ADOPTING.md +205 -15
- package/docs/ARCHITECTURE.md +34 -5
- package/docs/DECISIONS.md +1867 -11
- package/docs/DESIGN.md +137 -17
- package/docs/THREAT_MODEL.md +616 -0
- package/package.json +16 -3
- package/src/bridge/bounded-text.ts +240 -0
- package/src/bridge/bridge.ts +601 -51
- package/src/bridge/json-data.ts +95 -0
- package/src/bridge/navigation.ts +10 -0
- package/src/bridge/refusal.ts +17 -0
- package/src/bridge/types.ts +76 -5
- package/src/check/check.ts +8 -0
- package/src/check/instrument.ts +3 -0
- package/src/check/lint.ts +4 -2
- package/src/check/page.ts +16 -0
- package/src/check/tools.ts +2 -3
- package/src/compile/compile.ts +9 -1
- package/src/compile/policy.ts +177 -0
- package/src/config/capabilities.ts +71 -5
- package/src/config/schema.ts +35 -0
- package/src/config/validate.ts +141 -8
- package/src/config/warnings.ts +42 -0
- package/src/conformance/behavior.ts +54 -1
- package/src/conformance/cookies.ts +93 -0
- package/src/conformance/harness/page.ts +11 -2
- package/src/conformance/host-kit.ts +10 -1
- package/src/conformance/index.ts +17 -0
- package/src/conformance/limits.ts +39 -1
- package/src/conformance/runtime.ts +594 -0
- package/src/conformance/served.ts +888 -4
- package/src/files/paths.ts +4 -0
- package/src/guide/gates.ts +37 -0
- package/src/guide/guide.ts +61 -55
- package/src/guide/limits.ts +4 -4
- package/src/guide/runtime.ts +253 -0
- package/src/host/create-host.ts +88 -36
- package/src/host/locate.ts +10 -0
- package/src/host/locator.ts +11 -0
- package/src/host/pages-of-set.ts +226 -0
- package/src/host/types.ts +33 -1
- package/src/index.ts +94 -0
- package/src/isolation/types.ts +8 -0
- package/src/mcp/adapter.ts +16 -20
- package/src/node/index.ts +507 -116
- package/src/presets/presets.ts +67 -17
- package/src/protocol/live-data.ts +31 -3
- package/src/protocol/mcp-apps.ts +11 -2
- package/src/protocol/message-text.ts +36 -0
- package/src/protocol/runtime-calls.ts +141 -0
- package/src/protocol/shell-adapter.ts +79 -26
- package/src/react/context-notice.tsx +95 -0
- package/src/react/dialog.tsx +108 -15
- package/src/react/frame.tsx +120 -0
- package/src/react/index.ts +8 -1
- package/src/runtime/contract.ts +339 -0
- package/src/runtime/db.ts +650 -0
- package/src/runtime/declaration.ts +516 -0
- package/src/runtime/levels.ts +69 -0
- package/src/runtime/requests.ts +355 -0
- package/src/runtime/segments.ts +17 -0
- package/src/runtime/types.generated.ts +19 -0
- package/src/server/files.ts +138 -7
- package/src/server/host.ts +170 -3
- package/src/server/index.ts +4 -0
- package/src/server/peer.ts +21 -0
- package/src/server/proxy.ts +13 -3
- package/src/server/pseudonym.ts +21 -0
- package/src/server/server.ts +370 -57
- package/src/server/types.ts +73 -2
- package/src/shell/document.ts +29 -4
- package/src/shell/legacy.ts +64 -0
- package/src/shell/plan.ts +37 -3
- package/src/shell/runtime.ts +390 -56
- package/src/shell/use.ts +235 -0
- package/types/runtime/v1/artifact.d.ts +50 -0
- package/types/runtime/v1/assets.d.ts +43 -0
- package/types/runtime/v1/chat.d.ts +13 -0
- package/types/runtime/v1/clipboard.d.ts +14 -0
- package/types/runtime/v1/comments.d.ts +24 -0
- package/types/runtime/v1/context.d.ts +27 -0
- package/types/runtime/v1/data.d.ts +29 -0
- package/types/runtime/v1/db.d.ts +110 -0
- package/types/runtime/v1/downloads.d.ts +22 -0
- package/types/runtime/v1/links.d.ts +13 -0
- package/types/runtime/v1/porthole.d.ts +44 -0
- package/types/runtime/v1/user.d.ts +19 -0
package/dist/react/dialog.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
|
|
2
|
-
import { useEffect, useId, useRef, useState } from "react";
|
|
2
|
+
import { useEffect, useId, useMemo, useRef, useState } from "react";
|
|
3
|
+
import { formatBounded } from "../bridge/bounded-text.js";
|
|
3
4
|
/**
|
|
4
5
|
* The default confirmation dialog (P019): drawn by the host's page, outside every frame, as a
|
|
5
6
|
* modal (the top layer covers the frames, so content can't draw over it or click it). It shows
|
|
@@ -11,7 +12,42 @@ import { useEffect, useId, useRef, useState } from "react";
|
|
|
11
12
|
*/
|
|
12
13
|
/** How long the accept button ignores presses after the dialog opens. */
|
|
13
14
|
export const ARM_DELAY_MS = 500;
|
|
14
|
-
|
|
15
|
+
/**
|
|
16
|
+
* What a call carries, as JSON laid out, within bounds (P095): a frame's arguments come
|
|
17
|
+
* structured-cloned, so a cycle, a BigInt, or a graph billions of nodes long as a tree. Past the
|
|
18
|
+
* bounds the dialog says it shows only part.
|
|
19
|
+
*/
|
|
20
|
+
const DIALOG_TEXT_LIMITS = { chars: 20_000, nodes: 2_000, depth: 24 };
|
|
21
|
+
function carried(heading, accept, value, before = "") {
|
|
22
|
+
const { text, whole } = formatBounded(value, DIALOG_TEXT_LIMITS, 2);
|
|
23
|
+
return {
|
|
24
|
+
heading,
|
|
25
|
+
accept,
|
|
26
|
+
detail: `${before}${text}`,
|
|
27
|
+
...(whole ? {} : { note: "Only part of it is shown: it is more than this dialog shows." }),
|
|
28
|
+
};
|
|
29
|
+
}
|
|
30
|
+
/** How many of one kind of write the summary names before it counts the rest. */
|
|
31
|
+
const MOST_PATHS = 10;
|
|
32
|
+
/**
|
|
33
|
+
* A db change in a line (P094): the writes whose own gates asked for the yes, by kind ("Delete
|
|
34
|
+
* n/x, n/y; and 48 other writes."), or every write by kind where none of them asked (the host
|
|
35
|
+
* function's own confirmation); at most `MOST_PATHS` paths a kind, then a count.
|
|
36
|
+
*/
|
|
37
|
+
function writesSummary(writes, askedBy) {
|
|
38
|
+
const asked = writes.filter((each) => askedBy.includes(each.op));
|
|
39
|
+
const lead = asked.length === 0 ? writes : asked;
|
|
40
|
+
const kinds = new Map();
|
|
41
|
+
for (const each of lead) {
|
|
42
|
+
kinds.set(each.op, [...(kinds.get(each.op) ?? []), each.path]);
|
|
43
|
+
}
|
|
44
|
+
const said = [...kinds]
|
|
45
|
+
.map(([op, paths]) => `${op} ${paths.slice(0, MOST_PATHS).join(", ")}${paths.length > MOST_PATHS ? ` and ${paths.length - MOST_PATHS} more` : ""}`)
|
|
46
|
+
.join("; ");
|
|
47
|
+
const others = writes.length - lead.length;
|
|
48
|
+
const text = `${said}${others === 0 ? "" : `; and ${others} other write${others === 1 ? "" : "s"}`}.`;
|
|
49
|
+
return text.charAt(0).toUpperCase() + text.slice(1);
|
|
50
|
+
}
|
|
15
51
|
function words(request) {
|
|
16
52
|
switch (request.capability) {
|
|
17
53
|
case "sendPrompt":
|
|
@@ -32,33 +68,72 @@ function words(request) {
|
|
|
32
68
|
};
|
|
33
69
|
}
|
|
34
70
|
case "downloadFile":
|
|
35
|
-
return
|
|
36
|
-
heading: "Download this file?",
|
|
37
|
-
accept: "Download",
|
|
38
|
-
detail: json(request.args.contents),
|
|
39
|
-
};
|
|
71
|
+
return carried("Download this file?", "Download", request.args.contents);
|
|
40
72
|
case "callTool":
|
|
41
|
-
return {
|
|
42
|
-
heading: "Run this tool?",
|
|
43
|
-
accept: "Run",
|
|
44
|
-
detail: `${request.args.name}\n${json(request.args.arguments)}`,
|
|
45
|
-
};
|
|
73
|
+
return carried("Run this tool?", "Run", request.args.arguments, `${request.args.name}\n`);
|
|
46
74
|
case "setModelContext":
|
|
47
|
-
return
|
|
75
|
+
return carried("Share this with the agent?", "Share", request.args);
|
|
48
76
|
case "readData":
|
|
49
77
|
return { heading: "Let it read this?", accept: "Allow", detail: request.args.uri };
|
|
50
78
|
case "subscribeData":
|
|
51
79
|
return { heading: "Let it follow this?", accept: "Allow", detail: request.args.uri };
|
|
52
80
|
case "copyText":
|
|
53
81
|
return { heading: "Copy this text?", accept: "Copy", detail: request.args.text };
|
|
82
|
+
// The runtime's (P088, P089): the whole effect, as the page asked for it.
|
|
83
|
+
case "artifact":
|
|
84
|
+
return request.args.op === "publish"
|
|
85
|
+
? {
|
|
86
|
+
heading: "Publish a new version of this page?",
|
|
87
|
+
accept: "Publish",
|
|
88
|
+
detail: Object.entries(request.args.files)
|
|
89
|
+
.map(([path, file]) => file === null
|
|
90
|
+
? `${path}: removed`
|
|
91
|
+
: "text" in file
|
|
92
|
+
? `${path}: ${file.text.length.toLocaleString("en-US")} characters`
|
|
93
|
+
: `${path}: ${Math.floor((file.base64.length * 3) / 4).toLocaleString("en-US")} bytes`)
|
|
94
|
+
.join("\n"),
|
|
95
|
+
note: `From version ${request.args.base}${request.args.label === undefined ? "" : `: ${request.args.label}`}.`,
|
|
96
|
+
}
|
|
97
|
+
: carried("Allow this?", "Allow", request.args);
|
|
98
|
+
case "assets":
|
|
99
|
+
return request.args.op === "upload"
|
|
100
|
+
? {
|
|
101
|
+
heading: "Add this file to the page's library?",
|
|
102
|
+
accept: "Add",
|
|
103
|
+
detail: `${request.args.name} (${request.args.type}, ${request.args.size.toLocaleString("en-US")} bytes)`,
|
|
104
|
+
note: "Everyone who can see the page can load it.",
|
|
105
|
+
}
|
|
106
|
+
: request.args.op === "delete"
|
|
107
|
+
? {
|
|
108
|
+
heading: "Remove this file from the page's library?",
|
|
109
|
+
accept: "Remove",
|
|
110
|
+
detail: request.args.id,
|
|
111
|
+
}
|
|
112
|
+
: carried("Allow this?", "Allow", request.args);
|
|
113
|
+
// The page's shared data (P088): a change leads with what asked for the yes (P094).
|
|
114
|
+
case "db": {
|
|
115
|
+
const args = request.args;
|
|
116
|
+
const writes = args.op === "batch"
|
|
117
|
+
? args.writes
|
|
118
|
+
: args.op === "set" || args.op === "update" || args.op === "delete"
|
|
119
|
+
? [args]
|
|
120
|
+
: null;
|
|
121
|
+
return writes === null
|
|
122
|
+
? carried("Allow this?", "Allow", args)
|
|
123
|
+
: {
|
|
124
|
+
...carried("Change this page's shared data?", "Change", args),
|
|
125
|
+
summary: writesSummary(writes, request.askedBy ?? []),
|
|
126
|
+
};
|
|
127
|
+
}
|
|
54
128
|
default:
|
|
55
|
-
return
|
|
129
|
+
return carried("Allow this?", "Allow", request.args);
|
|
56
130
|
}
|
|
57
131
|
}
|
|
58
132
|
const STYLE = `.porthole-confirm{color-scheme:light dark;color:CanvasText;background:Canvas;border:1px solid color-mix(in srgb,CanvasText 18%,transparent);border-radius:12px;padding:20px;width:min(440px,calc(100vw - 32px));font:inherit;box-shadow:0 12px 40px rgb(0 0 0 / .28)}
|
|
59
133
|
.porthole-confirm::backdrop{background:rgb(0 0 0 / .4)}
|
|
60
134
|
.porthole-confirm h2{font-size:1.05em;margin:0 0 4px}
|
|
61
135
|
.porthole-confirm [data-porthole-source],.porthole-confirm [data-porthole-note]{opacity:.72;font-size:.9em;margin:0 0 12px}
|
|
136
|
+
.porthole-confirm [data-porthole-summary]{font-weight:600;overflow-wrap:anywhere;max-height:20vh;overflow:auto;margin:0 0 12px}
|
|
62
137
|
.porthole-confirm [data-porthole-detail]{white-space:pre-wrap;overflow-wrap:anywhere;max-height:40vh;overflow:auto;padding:10px 12px;border-radius:8px;background:color-mix(in srgb,CanvasText 7%,transparent);margin:0 0 12px;font:inherit}
|
|
63
138
|
.porthole-confirm menu{display:flex;justify-content:flex-end;gap:8px;margin:16px 0 0;padding:0}
|
|
64
139
|
.porthole-confirm button{font:inherit;min-height:36px;padding:0 14px;border-radius:8px;border:1px solid color-mix(in srgb,CanvasText 25%,transparent);background:transparent;color:inherit;cursor:pointer}
|
|
@@ -88,13 +163,13 @@ export function ConfirmDialog({ request, onAnswer, className }) {
|
|
|
88
163
|
const timer = setTimeout(() => setArmedFor(request), ARM_DELAY_MS);
|
|
89
164
|
return () => clearTimeout(timer);
|
|
90
165
|
}, [request]);
|
|
91
|
-
const said = request === null ? null : words(request);
|
|
166
|
+
const said = useMemo(() => (request === null ? null : words(request)), [request]);
|
|
92
167
|
return (_jsxs("dialog", { ref: dialog, className: className === undefined ? "porthole-confirm" : `porthole-confirm ${className}`, "aria-labelledby": heading, "data-porthole-confirm": request?.capability ?? "", onCancel: (event) => {
|
|
93
168
|
event.preventDefault();
|
|
94
169
|
if (request !== null) {
|
|
95
170
|
onAnswer(false);
|
|
96
171
|
}
|
|
97
|
-
}, children: [_jsx("style", { children: STYLE }), said === null || request === null ? null : (_jsxs(_Fragment, { children: [_jsx("h2", { id: heading, children: said.heading }), _jsx("p", { "data-porthole-source": "", children: `From “${request.display.title}”` }), _jsx("div", { "data-porthole-detail": "", children: said.detail }), said.note === undefined ? null : _jsx("p", { "data-porthole-note": "", children: said.note }), _jsxs("menu", { children: [_jsx("button", { type: "button", ref: cancel, autoFocus: true, "data-porthole-cancel": "", onClick: () => onAnswer(false), children: "Cancel" }), _jsx("button", { type: "button", "data-porthole-accept": "", "data-armed": String(armed), onClick: () => {
|
|
172
|
+
}, children: [_jsx("style", { children: STYLE }), said === null || request === null ? null : (_jsxs(_Fragment, { children: [_jsx("h2", { id: heading, children: said.heading }), _jsx("p", { "data-porthole-source": "", children: `From “${request.display.title}”` }), said.summary === undefined ? null : _jsx("p", { "data-porthole-summary": "", children: said.summary }), _jsx("div", { "data-porthole-detail": "", children: said.detail }), said.note === undefined ? null : _jsx("p", { "data-porthole-note": "", children: said.note }), _jsxs("menu", { children: [_jsx("button", { type: "button", ref: cancel, autoFocus: true, "data-porthole-cancel": "", onClick: () => onAnswer(false), children: "Cancel" }), _jsx("button", { type: "button", "data-porthole-accept": "", "data-armed": String(armed), onClick: () => {
|
|
98
173
|
if (armed) {
|
|
99
174
|
onAnswer(true);
|
|
100
175
|
}
|
package/dist/react/frame.d.ts
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
|
+
import type { PageDeclaration } from "../runtime/declaration.ts";
|
|
2
|
+
import type { ViewerInfo } from "../runtime/levels.ts";
|
|
1
3
|
import { type CSSProperties, type ReactElement, type ReactNode } from "react";
|
|
2
4
|
import type { AnnotateMode, AnnotationMark, AnnotationReport } from "../annotate/types.ts";
|
|
3
|
-
import type { CapabilityHandler, CapabilityHandlers, Confirm, ConfirmRequest, Consent, DataCache, Refusal } from "../bridge/types.ts";
|
|
5
|
+
import type { CapabilityHandler, CapabilityHandlers, Confirm, ConfirmRequest, Consent, DataCache, Refusal, Show } from "../bridge/types.ts";
|
|
4
6
|
import { Refused, type RefusalReason } from "../bridge/refusal.ts";
|
|
5
7
|
import type { CapabilityName } from "../config/capabilities.ts";
|
|
6
8
|
import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
|
|
@@ -38,6 +40,8 @@ interface PageState {
|
|
|
38
40
|
readonly locate?: InstanceLocator["locate"];
|
|
39
41
|
/** The default `copyText`: copies on the host's page and shows the toast (P052). */
|
|
40
42
|
readonly copyText?: CapabilityHandler<"copyText">;
|
|
43
|
+
/** Who shows the person `show`-gated calls: the provider's own, or its notice (P100). */
|
|
44
|
+
readonly show?: Show;
|
|
41
45
|
}
|
|
42
46
|
/** The provider's page state, for the binding's other components (`PortholeView`). */
|
|
43
47
|
export declare const PortholeContext: import("react").Context<PageState>;
|
|
@@ -89,6 +93,13 @@ export interface PortholeProviderProps {
|
|
|
89
93
|
* refuses them all with its reason, and their handlers may be left out (P080).
|
|
90
94
|
*/
|
|
91
95
|
readonly consent?: Consent | Refused;
|
|
96
|
+
/**
|
|
97
|
+
* Shows the person each `show`-gated call, outside every frame, before its handler has it
|
|
98
|
+
* (P100): by default, a frame's model context update (`setModelContext`), the content's text for
|
|
99
|
+
* the agent's next turn. Omitted: Porthole's `ContextNotice`. A host that shows it its own way (a
|
|
100
|
+
* chip by its composer) passes this; the update replaces the display's last.
|
|
101
|
+
*/
|
|
102
|
+
readonly show?: Show;
|
|
92
103
|
/** What the host last had for a resource, answered stale first (P079). */
|
|
93
104
|
readonly cached?: DataCache;
|
|
94
105
|
/** How the host names itself in the handshake. */
|
|
@@ -102,6 +113,8 @@ export interface PortholeProviderProps {
|
|
|
102
113
|
readonly dialogClassName?: string;
|
|
103
114
|
/** A class for the default copy toast, to restyle it. */
|
|
104
115
|
readonly toastClassName?: string;
|
|
116
|
+
/** A class for the default model context notice, to restyle it. */
|
|
117
|
+
readonly contextClassName?: string;
|
|
105
118
|
/**
|
|
106
119
|
* The page's CSP nonce, where its `script-src` is nonce-based: opaque frames inherit the page's
|
|
107
120
|
* policy, so their shell carries it (P054). `"auto"`: read from the page (a `<meta
|
|
@@ -145,6 +158,17 @@ export interface PortholeFrameProps {
|
|
|
145
158
|
* shows, for its confirmations only, never sent to the frame (P077).
|
|
146
159
|
*/
|
|
147
160
|
readonly instance?: InstanceRef;
|
|
161
|
+
/**
|
|
162
|
+
* What the page declared (P086), as the host stored it with the artifact: the capabilities it
|
|
163
|
+
* reaches through `porthole.use`, and its pinned runtime. By value: a change makes the display
|
|
164
|
+
* again.
|
|
165
|
+
*/
|
|
166
|
+
readonly declaration?: PageDeclaration;
|
|
167
|
+
/**
|
|
168
|
+
* Who is viewing (P087), for an opaque frame or one whose issue gave none. By value: a change
|
|
169
|
+
* makes the display again.
|
|
170
|
+
*/
|
|
171
|
+
readonly viewer?: ViewerInfo;
|
|
148
172
|
/** The color scheme it shows in. Default: the provider's `scheme`, else light. */
|
|
149
173
|
readonly scheme?: ColorScheme;
|
|
150
174
|
/** The host's live values for the config's theme variables (from its design tokens). */
|
package/dist/react/frame.js
CHANGED
|
@@ -4,6 +4,7 @@ import { isRefused, reasonOf, Refused } from "../bridge/refusal.js";
|
|
|
4
4
|
import { writeClipboard } from "../host/clipboard.js";
|
|
5
5
|
import { createHost } from "../host/create-host.js";
|
|
6
6
|
import { ConfirmDialog } from "./dialog.js";
|
|
7
|
+
import { ContextNotice } from "./context-notice.js";
|
|
7
8
|
import { createLiveFrames } from "./live.js";
|
|
8
9
|
import { CopyToast } from "./toast.js";
|
|
9
10
|
/**
|
|
@@ -12,6 +13,9 @@ import { CopyToast } from "./toast.js";
|
|
|
12
13
|
* display mounts it when it nears the screen, streams its content, flips its theme, and remembers
|
|
13
14
|
* its height. All the isolation is the core's (`createHost`); this is mounting and lifecycle.
|
|
14
15
|
*/
|
|
16
|
+
/** Why a model context update didn't go: it was never drawn (the review of P100). */
|
|
17
|
+
const REPLACED_UNSEEN = "a later update of this display replaced it before the person saw it";
|
|
18
|
+
const HIDDEN_UNSEEN = "the person hid this display's notice before the update was drawn";
|
|
15
19
|
/** How far off screen a frame starts (and keeps) running. */
|
|
16
20
|
const NEAR_SCREEN = "800px 0px";
|
|
17
21
|
/** The height a display holds before it has reported its own. */
|
|
@@ -84,6 +88,67 @@ export function PortholeProvider(props) {
|
|
|
84
88
|
return copied;
|
|
85
89
|
}, []);
|
|
86
90
|
const closeNotice = useCallback(() => setNotice(null), []);
|
|
91
|
+
// The default show (P100): each display's latest model context update, in the notice, outside
|
|
92
|
+
// every frame; the host's own `show` replaces it.
|
|
93
|
+
const [contexts, setContexts] = useState([]);
|
|
94
|
+
// Each show waiting for its own update to be on the page (after the review: React may draw two
|
|
95
|
+
// updates of a display in one render, the latest only). The number orders a display's shows.
|
|
96
|
+
const unseen = useRef([]);
|
|
97
|
+
const latest = useRef(new Map());
|
|
98
|
+
const sequence = useRef(0);
|
|
99
|
+
useLayoutEffect(() => {
|
|
100
|
+
unseen.current = unseen.current.filter((each) => {
|
|
101
|
+
const drawn = contexts.find((one) => one.displayId === each.entry.displayId);
|
|
102
|
+
if (drawn === each.entry) {
|
|
103
|
+
each.resolve();
|
|
104
|
+
return false;
|
|
105
|
+
}
|
|
106
|
+
// A later update of the display replaced it before it was drawn: never seen, never sent.
|
|
107
|
+
if ((latest.current.get(each.entry.displayId) ?? 0) > each.seq) {
|
|
108
|
+
each.reject(new Error(REPLACED_UNSEEN));
|
|
109
|
+
return false;
|
|
110
|
+
}
|
|
111
|
+
return true;
|
|
112
|
+
});
|
|
113
|
+
}, [contexts]);
|
|
114
|
+
const ownShow = useRef(props.show);
|
|
115
|
+
useLayoutEffect(() => {
|
|
116
|
+
ownShow.current = props.show;
|
|
117
|
+
});
|
|
118
|
+
const show = useCallback((request) => {
|
|
119
|
+
if (ownShow.current !== undefined) {
|
|
120
|
+
return ownShow.current(request);
|
|
121
|
+
}
|
|
122
|
+
if (request.capability !== "setModelContext") {
|
|
123
|
+
// The notice words model context only: anything else it would show unworded, so it isn't
|
|
124
|
+
// shown, and doesn't go (fail closed).
|
|
125
|
+
throw new Error(`Porthole's notice shows model context only, not ${request.capability}`);
|
|
126
|
+
}
|
|
127
|
+
const entry = {
|
|
128
|
+
displayId: request.display.id,
|
|
129
|
+
title: request.display.title,
|
|
130
|
+
update: request.args,
|
|
131
|
+
};
|
|
132
|
+
sequence.current += 1;
|
|
133
|
+
const seq = sequence.current;
|
|
134
|
+
latest.current.set(entry.displayId, seq);
|
|
135
|
+
// The call goes once this very update is on the page, so the handler never has it first.
|
|
136
|
+
return new Promise((resolve, reject) => {
|
|
137
|
+
unseen.current.push({ entry, seq, resolve, reject });
|
|
138
|
+
setContexts((each) => [...each.filter((one) => one.displayId !== entry.displayId), entry]);
|
|
139
|
+
});
|
|
140
|
+
}, []);
|
|
141
|
+
const hideContext = useCallback((displayId) => {
|
|
142
|
+
// Hidden by the person: an update of the display not drawn yet never will be.
|
|
143
|
+
unseen.current = unseen.current.filter((each) => {
|
|
144
|
+
if (each.entry.displayId !== displayId) {
|
|
145
|
+
return true;
|
|
146
|
+
}
|
|
147
|
+
each.reject(new Error(HIDDEN_UNSEEN));
|
|
148
|
+
return false;
|
|
149
|
+
});
|
|
150
|
+
setContexts((each) => each.filter((one) => one.displayId !== displayId));
|
|
151
|
+
}, []);
|
|
87
152
|
// Compared by value, and read when used: an inline hostInfo or locator doesn't start every
|
|
88
153
|
// frame again on each render.
|
|
89
154
|
const hostInfo = useByValue(props.hostInfo);
|
|
@@ -131,6 +196,7 @@ export function PortholeProvider(props) {
|
|
|
131
196
|
heights,
|
|
132
197
|
confirm,
|
|
133
198
|
copyText,
|
|
199
|
+
show,
|
|
134
200
|
...(consents ? { consent } : {}),
|
|
135
201
|
...(refusesAll === undefined ? {} : { refusesAll }),
|
|
136
202
|
...(caches ? { cached } : {}),
|
|
@@ -147,6 +213,7 @@ export function PortholeProvider(props) {
|
|
|
147
213
|
heights,
|
|
148
214
|
confirm,
|
|
149
215
|
copyText,
|
|
216
|
+
show,
|
|
150
217
|
consents,
|
|
151
218
|
consent,
|
|
152
219
|
refusesAll,
|
|
@@ -187,7 +254,7 @@ export function PortholeProvider(props) {
|
|
|
187
254
|
}
|
|
188
255
|
current?.resolve(accepted ? "accepted" : "declined");
|
|
189
256
|
setQueue((waiting) => waiting.slice(1));
|
|
190
|
-
} })) : null, props.notify !== undefined ? null : (_jsx(CopyToast, { notice: notice, ...(props.toastClassName === undefined ? {} : { className: props.toastClassName }), onClose: closeNotice, onCopy: (failed) => {
|
|
257
|
+
} })) : null, props.show !== undefined ? null : (_jsx(ContextNotice, { updates: contexts, onHide: hideContext, ...(props.contextClassName === undefined ? {} : { className: props.contextClassName }) })), props.notify !== undefined ? null : (_jsx(CopyToast, { notice: notice, ...(props.toastClassName === undefined ? {} : { className: props.toastClassName }), onClose: closeNotice, onCopy: (failed) => {
|
|
191
258
|
// A click on the host's own page: the write has the gesture it needs now.
|
|
192
259
|
void writeClipboard(failed.text, globalThis.document).then((copied) => setNotice({ ...failed, copied }));
|
|
193
260
|
} }))] }));
|
|
@@ -292,6 +359,8 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
|
|
|
292
359
|
// By value: a config or instance made inline (each render) is the same display.
|
|
293
360
|
const config = useByValue(frame.config);
|
|
294
361
|
const instance = useByValue(frame.instance);
|
|
362
|
+
const declaration = useByValue(frame.declaration);
|
|
363
|
+
const viewer = useByValue(frame.viewer);
|
|
295
364
|
const fills = config.mode === "url" || frame.fill === true || config.layout.kind === "fill";
|
|
296
365
|
// A consent that refuses everything (P080), this frame's or else the provider's, by value: a
|
|
297
366
|
// display made with it needs no data handlers, so a change makes the display again.
|
|
@@ -303,7 +372,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
|
|
|
303
372
|
// value) re-themes the running display, never makes it again (#9, P074). What a display is
|
|
304
373
|
// made with comes from the provider's stable parts below.
|
|
305
374
|
const latestPage = useEffectEvent(() => page);
|
|
306
|
-
const { handlers: pageHandlers, copyText: pageCopyText, confirm: pageConfirm, consent: pageConsent, cached: pageCached, hostInfo, locate, nonce, } = page;
|
|
375
|
+
const { handlers: pageHandlers, copyText: pageCopyText, confirm: pageConfirm, consent: pageConsent, show: pageShow, cached: pageCached, hostInfo, locate, nonce, } = page;
|
|
307
376
|
const notify = useEffectEvent((event, detail) => {
|
|
308
377
|
switch (event) {
|
|
309
378
|
case "initialized":
|
|
@@ -420,6 +489,15 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
|
|
|
420
489
|
},
|
|
421
490
|
}
|
|
422
491
|
: {}),
|
|
492
|
+
// Shown as the latest props name the display (P100).
|
|
493
|
+
...(pageShow === undefined
|
|
494
|
+
? {}
|
|
495
|
+
: {
|
|
496
|
+
show: (request) => pageShow({
|
|
497
|
+
...request,
|
|
498
|
+
display: { ...request.display, id: latest().displayId, title: latest().title },
|
|
499
|
+
}),
|
|
500
|
+
}),
|
|
423
501
|
...(caches
|
|
424
502
|
? {
|
|
425
503
|
cached: (args, context) => (latest().cached ?? pageCached)?.(args, named(context)),
|
|
@@ -436,6 +514,8 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
|
|
|
436
514
|
initialHeightPx: startHeight,
|
|
437
515
|
...(view === undefined ? {} : { document: view }),
|
|
438
516
|
...(instance === undefined ? {} : { instance }),
|
|
517
|
+
...(declaration === undefined ? {} : { declaration }),
|
|
518
|
+
...(viewer === undefined ? {} : { viewer }),
|
|
439
519
|
...(fills ? { fill: true } : {}),
|
|
440
520
|
});
|
|
441
521
|
}
|
|
@@ -477,12 +557,15 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
|
|
|
477
557
|
config,
|
|
478
558
|
view,
|
|
479
559
|
instance,
|
|
560
|
+
declaration,
|
|
561
|
+
viewer,
|
|
480
562
|
startHeight,
|
|
481
563
|
fills,
|
|
482
564
|
pageHandlers,
|
|
483
565
|
pageCopyText,
|
|
484
566
|
pageConfirm,
|
|
485
567
|
pageConsent,
|
|
568
|
+
pageShow,
|
|
486
569
|
pageCached,
|
|
487
570
|
refusesAll,
|
|
488
571
|
hostInfo,
|
package/dist/react/index.d.ts
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* `@botiverse/porthole/react`: the thin React binding (TSX: a host's bundler compiles it, or the
|
|
3
3
|
* package's `dist`). Peer: `react` (19.2+, for `useEffectEvent`).
|
|
4
4
|
*
|
|
5
|
-
* <PortholeProvider> // per page: live-frame cap, heights, the dialog, the copy toast
|
|
5
|
+
* <PortholeProvider> // per page: live-frame cap, heights, the dialog, the copy toast, the context notice
|
|
6
6
|
* <PortholeFrame config={widgetConfig} displayId={id} title={title} scheme={scheme}
|
|
7
7
|
* content={code} partial={streaming} handlers={{ sendPrompt, openLink }}
|
|
8
8
|
* theme={tokensFor} onError={report} />
|
|
@@ -10,6 +10,7 @@
|
|
|
10
10
|
*/
|
|
11
11
|
export { PLACEHOLDER_HEIGHT_PX, PortholeFrame, PortholeProvider, type PlaceholderProps, type PortholeFrameProps, type ConfirmActions, type PortholeProviderProps, } from "./frame.tsx";
|
|
12
12
|
export { ARM_DELAY_MS, ConfirmDialog, type ConfirmDialogProps } from "./dialog.tsx";
|
|
13
|
+
export { ContextNotice, contextSize, contextText, type ContextNoticeProps, type ContextUpdate, } from "./context-notice.tsx";
|
|
13
14
|
export { cssVariableTheme, PortholeView, usePortholeLink, useRunAgain, type PortholeFallbackProps, type PortholeViewProps, } from "./view.tsx";
|
|
14
15
|
export { CopyToast, TOAST_CHARS, TOAST_MS, clipped, type CopyNotice, type CopyToastProps, } from "./toast.tsx";
|
|
15
16
|
export { admitFrame, createLiveFrames, type FrameState, type LiveFrames } from "./live.ts";
|
package/dist/react/index.js
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* `@botiverse/porthole/react`: the thin React binding (TSX: a host's bundler compiles it, or the
|
|
3
3
|
* package's `dist`). Peer: `react` (19.2+, for `useEffectEvent`).
|
|
4
4
|
*
|
|
5
|
-
* <PortholeProvider> // per page: live-frame cap, heights, the dialog, the copy toast
|
|
5
|
+
* <PortholeProvider> // per page: live-frame cap, heights, the dialog, the copy toast, the context notice
|
|
6
6
|
* <PortholeFrame config={widgetConfig} displayId={id} title={title} scheme={scheme}
|
|
7
7
|
* content={code} partial={streaming} handlers={{ sendPrompt, openLink }}
|
|
8
8
|
* theme={tokensFor} onError={report} />
|
|
@@ -10,6 +10,7 @@
|
|
|
10
10
|
*/
|
|
11
11
|
export { PLACEHOLDER_HEIGHT_PX, PortholeFrame, PortholeProvider, } from "./frame.js";
|
|
12
12
|
export { ARM_DELAY_MS, ConfirmDialog } from "./dialog.js";
|
|
13
|
+
export { ContextNotice, contextSize, contextText, } from "./context-notice.js";
|
|
13
14
|
export { cssVariableTheme, PortholeView, usePortholeLink, useRunAgain, } from "./view.js";
|
|
14
15
|
export { CopyToast, TOAST_CHARS, TOAST_MS, clipped, } from "./toast.js";
|
|
15
16
|
export { admitFrame, createLiveFrames } from "./live.js";
|
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
import type { CapabilityName, Gate } from "../config/capabilities.ts";
|
|
2
|
+
import type { PortholeConfig } from "../config/schema.ts";
|
|
3
|
+
import { type ViewerLevel } from "./levels.ts";
|
|
4
|
+
/**
|
|
5
|
+
* The capability runtime's contract (P085): what a page reaches through its one global,
|
|
6
|
+
* `porthole.use(name)`, by contract version. A version is pinned per artifact when it is published
|
|
7
|
+
* (`declareCapabilities`) and served as pinned, so a page keeps the API it was written against.
|
|
8
|
+
*
|
|
9
|
+
* Each runtime capability is a namespace of methods; each method is served by one of the config's
|
|
10
|
+
* host functions (PRINCIPLE 4: the config still says what the host offers, with its gates), needs
|
|
11
|
+
* a viewer level (P087), and is either a call or a watch (a subscription). A built-in is reachable
|
|
12
|
+
* by any page whose host offers it; every other one only by a page that declared it (P086).
|
|
13
|
+
*/
|
|
14
|
+
/** The contract versions this Porthole serves. */
|
|
15
|
+
export declare const RUNTIME_VERSIONS: readonly ["1"];
|
|
16
|
+
export type RuntimeVersion = (typeof RUNTIME_VERSIONS)[number];
|
|
17
|
+
/** The version a declaration is pinned to unless its author asks for another. */
|
|
18
|
+
export declare const RUNTIME_VERSION: RuntimeVersion;
|
|
19
|
+
export declare function isRuntimeVersion(value: unknown): value is RuntimeVersion;
|
|
20
|
+
/** The one global the shell defines for the runtime, with `use` its only member. */
|
|
21
|
+
export declare const RUNTIME_GLOBAL = "porthole";
|
|
22
|
+
/** Where the host's roster goes in the handshake: MCP Apps' experimental host capabilities. */
|
|
23
|
+
export declare const RUNTIME_EXPERIMENTAL_KEY = "porthole/runtime";
|
|
24
|
+
/** A runtime call (own-prefixed, P002): `{ capability, method, args }`. */
|
|
25
|
+
export declare const RUNTIME_CALL_METHOD = "porthole/call";
|
|
26
|
+
/** A watch's end, frame to host (a notification, never gated): `{ watch }`. */
|
|
27
|
+
export declare const RUNTIME_UNWATCH_METHOD = "porthole/unwatch";
|
|
28
|
+
/** A watch's update, host to frame: `{ watch, data }`. */
|
|
29
|
+
export declare const RUNTIME_EVENT_METHOD = "porthole/event";
|
|
30
|
+
export interface RuntimeMethod {
|
|
31
|
+
/** The config's host function that serves it: declared there, gated as it says. */
|
|
32
|
+
readonly serves: CapabilityName;
|
|
33
|
+
/** The least level that may call it, unless the host's config or the page's says more. */
|
|
34
|
+
readonly level: ViewerLevel;
|
|
35
|
+
/** The least a host's config may set it to (`CapabilityConfig.levels`). */
|
|
36
|
+
readonly floor: ViewerLevel;
|
|
37
|
+
/** A subscription: the content passes callbacks and gets a function that stops it. */
|
|
38
|
+
readonly watch?: true;
|
|
39
|
+
/**
|
|
40
|
+
* Gates of its own, over its host function's (after the review, P088): what changes the
|
|
41
|
+
* artifact for everyone needs the person's click and their yes. A host's config may replace
|
|
42
|
+
* them (`CapabilityConfig.methodGates`).
|
|
43
|
+
*/
|
|
44
|
+
readonly gates?: readonly Gate[];
|
|
45
|
+
}
|
|
46
|
+
export interface RuntimeCapability {
|
|
47
|
+
/**
|
|
48
|
+
* Built in (P086): any page whose host offers it may use it without declaring it: the effect is
|
|
49
|
+
* the host's own UI, shown to the person (a copy, a link, a download, the comment composer).
|
|
50
|
+
*/
|
|
51
|
+
readonly builtIn: boolean;
|
|
52
|
+
readonly methods: Readonly<Record<string, RuntimeMethod>>;
|
|
53
|
+
}
|
|
54
|
+
/** Contract 1's capabilities, by the name a page passes to `use`. */
|
|
55
|
+
export declare const RUNTIME_CAPABILITIES: {
|
|
56
|
+
/** Who is viewing: `{ id, name, level }`, as the host says. Declared: the page learns who. */
|
|
57
|
+
readonly user: {
|
|
58
|
+
readonly builtIn: false;
|
|
59
|
+
readonly methods: {
|
|
60
|
+
readonly get: RuntimeMethod;
|
|
61
|
+
};
|
|
62
|
+
};
|
|
63
|
+
/** Opens the host's comment composer at an anchor the page names. Write-only (P090). */
|
|
64
|
+
readonly comments: {
|
|
65
|
+
readonly builtIn: true;
|
|
66
|
+
readonly methods: {
|
|
67
|
+
readonly open: RuntimeMethod;
|
|
68
|
+
};
|
|
69
|
+
};
|
|
70
|
+
/** Copies text, done and shown by the host (P051, P052). */
|
|
71
|
+
readonly clipboard: {
|
|
72
|
+
readonly builtIn: true;
|
|
73
|
+
readonly methods: {
|
|
74
|
+
readonly copy: RuntimeMethod;
|
|
75
|
+
};
|
|
76
|
+
};
|
|
77
|
+
/** Opens an http(s) link outside the frame. */
|
|
78
|
+
readonly links: {
|
|
79
|
+
readonly builtIn: true;
|
|
80
|
+
readonly methods: {
|
|
81
|
+
readonly open: RuntimeMethod;
|
|
82
|
+
};
|
|
83
|
+
};
|
|
84
|
+
/** Hands the person a file to save. */
|
|
85
|
+
readonly downloads: {
|
|
86
|
+
readonly builtIn: true;
|
|
87
|
+
readonly methods: {
|
|
88
|
+
readonly save: RuntimeMethod;
|
|
89
|
+
};
|
|
90
|
+
};
|
|
91
|
+
/** Sends text to the agent as the person's message. */
|
|
92
|
+
readonly chat: {
|
|
93
|
+
readonly builtIn: false;
|
|
94
|
+
readonly methods: {
|
|
95
|
+
readonly send: RuntimeMethod;
|
|
96
|
+
};
|
|
97
|
+
};
|
|
98
|
+
/** The host's data (MCP resources and tools, P079): read, follow, call. */
|
|
99
|
+
readonly data: {
|
|
100
|
+
readonly builtIn: false;
|
|
101
|
+
readonly methods: {
|
|
102
|
+
readonly read: RuntimeMethod;
|
|
103
|
+
readonly subscribe: RuntimeMethod;
|
|
104
|
+
readonly call: RuntimeMethod;
|
|
105
|
+
};
|
|
106
|
+
};
|
|
107
|
+
/** Context for the agent's next turns. */
|
|
108
|
+
readonly context: {
|
|
109
|
+
readonly builtIn: false;
|
|
110
|
+
readonly methods: {
|
|
111
|
+
readonly set: RuntimeMethod;
|
|
112
|
+
};
|
|
113
|
+
};
|
|
114
|
+
/** This artifact itself: its current version, and a new version of it (P088). */
|
|
115
|
+
readonly artifact: {
|
|
116
|
+
readonly builtIn: false;
|
|
117
|
+
readonly methods: {
|
|
118
|
+
readonly get: RuntimeMethod;
|
|
119
|
+
readonly publish: RuntimeMethod;
|
|
120
|
+
};
|
|
121
|
+
};
|
|
122
|
+
/** The artifact's asset library, served at `/_blob/<id>` (P089). */
|
|
123
|
+
readonly assets: {
|
|
124
|
+
readonly builtIn: false;
|
|
125
|
+
readonly methods: {
|
|
126
|
+
readonly list: RuntimeMethod;
|
|
127
|
+
readonly url: RuntimeMethod;
|
|
128
|
+
readonly upload: RuntimeMethod;
|
|
129
|
+
readonly delete: RuntimeMethod;
|
|
130
|
+
};
|
|
131
|
+
};
|
|
132
|
+
/** The artifact's shared document store (P088). */
|
|
133
|
+
readonly db: {
|
|
134
|
+
readonly builtIn: false;
|
|
135
|
+
readonly methods: {
|
|
136
|
+
readonly get: RuntimeMethod;
|
|
137
|
+
readonly query: RuntimeMethod;
|
|
138
|
+
readonly watch: RuntimeMethod;
|
|
139
|
+
readonly set: RuntimeMethod;
|
|
140
|
+
readonly update: RuntimeMethod;
|
|
141
|
+
readonly delete: RuntimeMethod;
|
|
142
|
+
readonly batch: RuntimeMethod;
|
|
143
|
+
};
|
|
144
|
+
};
|
|
145
|
+
};
|
|
146
|
+
export type RuntimeCapabilityName = keyof typeof RUNTIME_CAPABILITIES;
|
|
147
|
+
export declare const RUNTIME_CAPABILITY_NAMES: readonly RuntimeCapabilityName[];
|
|
148
|
+
export declare function isRuntimeCapabilityName(value: unknown): value is RuntimeCapabilityName;
|
|
149
|
+
/** A runtime capability's spec, as the general shape. */
|
|
150
|
+
export declare function runtimeCapability(name: RuntimeCapabilityName): RuntimeCapability;
|
|
151
|
+
/** The host functions the runtime added in contract 1 (P085): the config needs `runtime` for them. */
|
|
152
|
+
export declare const RUNTIME_HOST_FUNCTIONS: readonly CapabilityName[];
|
|
153
|
+
/**
|
|
154
|
+
* Where a host function sits in the runtime: its capability and the methods it serves. Null for
|
|
155
|
+
* the shell's own (`resize`, `reportError`, `annotate`), which content never calls by name.
|
|
156
|
+
*/
|
|
157
|
+
export declare function familyOf(serves: CapabilityName): {
|
|
158
|
+
readonly name: RuntimeCapabilityName;
|
|
159
|
+
readonly methods: readonly string[];
|
|
160
|
+
} | null;
|
|
161
|
+
/**
|
|
162
|
+
* The runtime method a host function's validated call is: the `op` of one that serves several
|
|
163
|
+
* (`artifact`, `assets`, `db`), else its one method.
|
|
164
|
+
*/
|
|
165
|
+
export declare function methodOf(serves: CapabilityName, args: unknown): string | null;
|
|
166
|
+
/**
|
|
167
|
+
* The runtime methods a validated call runs, each as often as it runs it: its own, and for a db
|
|
168
|
+
* batch each of its writes' (`set`, `update`, `delete`), for a db watch the read it repeats (`get`
|
|
169
|
+
* for a document, `query` for a collection). Each one's level and gates apply to the call (P091
|
|
170
|
+
* item 4 for levels, P094 for gates): a batch is its writes, a watch its read.
|
|
171
|
+
*/
|
|
172
|
+
export declare function methodsOfCall(serves: CapabilityName, args: unknown): readonly string[];
|
|
173
|
+
/**
|
|
174
|
+
* Whether a config's asset uploads are its admins' alone (`assets.upload` at admin or above,
|
|
175
|
+
* P089): only then may scripts and styles an admin uploaded run from the library. Never where
|
|
176
|
+
* the config serves no assets (P103: a config that dropped them runs nothing of its library).
|
|
177
|
+
*/
|
|
178
|
+
export declare function assetCodeRuns(config: PortholeConfig): boolean;
|
|
179
|
+
/**
|
|
180
|
+
* A runtime method's own gates (after the review): the config's (`CapabilityConfig.methodGates`),
|
|
181
|
+
* else the contract's; an upload where uploaded code may run is confirmed (P089).
|
|
182
|
+
*/
|
|
183
|
+
export declare function methodGates(config: PortholeConfig, family: RuntimeCapabilityName, name: string): readonly Gate[];
|
|
184
|
+
/** What a page declared for one capability, as far as levels go (P086). */
|
|
185
|
+
export interface DeclaredLevels {
|
|
186
|
+
readonly levels?: Readonly<Record<string, ViewerLevel>>;
|
|
187
|
+
}
|
|
188
|
+
/**
|
|
189
|
+
* The least level that may call `family.method` (P087): the contract's, or the host's config
|
|
190
|
+
* (`CapabilityConfig.levels`, no lower than the floor), raised by the page's declaration.
|
|
191
|
+
*/
|
|
192
|
+
export declare function methodLevel(config: PortholeConfig, family: RuntimeCapabilityName, name: string, declared?: DeclaredLevels): ViewerLevel | null;
|
|
193
|
+
/**
|
|
194
|
+
* What the host offers a display (P085): each runtime capability the config serves at least one
|
|
195
|
+
* method of (with those methods), reachable when it is built in or the page declared it. Without
|
|
196
|
+
* `config.runtime`, nothing: the display is 0.6's. `declared` is the page's declaration's names;
|
|
197
|
+
* absent, the page declared nothing (built-ins only).
|
|
198
|
+
*/
|
|
199
|
+
export declare function rosterOf(config: PortholeConfig, declared?: readonly string[]): Readonly<Partial<Record<RuntimeCapabilityName, readonly string[]>>>;
|
|
200
|
+
/** The capabilities a config offers to pages that declare them (for the manual and `declareCapabilities`). */
|
|
201
|
+
export declare function offeredCapabilities(config: PortholeConfig): RuntimeCapabilityName[];
|