@botiverse/porthole 0.12.0 → 0.13.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/dist/bridge/bridge.d.ts +8 -1
- package/dist/bridge/bridge.js +7 -0
- package/dist/bridge/unseen.d.ts +8 -0
- package/dist/bridge/unseen.js +17 -0
- package/dist/check/files.js +14 -10
- package/dist/check/lint.js +1 -1
- package/dist/check/page-source.js +1 -1
- package/dist/check/scroll.d.ts +29 -13
- package/dist/check/scroll.js +74 -18
- package/dist/config/capabilities.d.ts +16 -3
- package/dist/config/capabilities.js +1 -0
- package/dist/conformance/harness-source.js +1 -1
- package/dist/guide/runtime.js +1 -1
- package/dist/host/create-host.js +27 -0
- package/dist/host/types.d.ts +15 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/platform/focus-guard.d.ts +143 -0
- package/dist/platform/focus-guard.js +445 -0
- package/dist/platform/types.d.ts +18 -0
- package/dist/platform/web.js +22 -0
- package/dist/react/frame.d.ts +8 -0
- package/dist/react/frame.js +4 -0
- package/dist/runtime/requests.js +34 -12
- package/dist/runtime/types.generated.js +1 -1
- package/docs/ADOPTING.md +85 -6
- package/docs/DECISIONS.md +355 -5
- package/docs/DESIGN.md +9 -2
- package/docs/THREAT_MODEL.md +121 -29
- package/package.json +1 -1
- package/src/bridge/bridge.ts +17 -1
- package/src/bridge/unseen.ts +24 -0
- package/src/check/files.ts +14 -10
- package/src/check/lint.ts +1 -1
- package/src/check/scroll.ts +106 -38
- package/src/config/capabilities.ts +16 -3
- package/src/guide/runtime.ts +1 -1
- package/src/host/create-host.ts +29 -0
- package/src/host/types.ts +13 -0
- package/src/index.ts +1 -0
- package/src/platform/focus-guard.ts +572 -0
- package/src/platform/types.ts +17 -0
- package/src/platform/web.ts +22 -0
- package/src/react/frame.tsx +10 -0
- package/src/runtime/requests.ts +36 -14
- package/src/runtime/types.generated.ts +1 -1
- package/types/runtime/v1/comments.d.ts +8 -4
package/src/runtime/requests.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { unseenStrict, withoutUnseen } from "../bridge/unseen.ts";
|
|
2
2
|
import type { Limits } from "../config/schema.ts";
|
|
3
3
|
import { fileLimits, filePathProblem } from "../files/paths.ts";
|
|
4
4
|
import { fileTypeOf } from "../files/types.ts";
|
|
@@ -70,18 +70,42 @@ export interface CommentRequest {
|
|
|
70
70
|
readonly draft?: string;
|
|
71
71
|
}
|
|
72
72
|
|
|
73
|
+
/** Characters that draw as a blank: spaces of every kind, tabs, new lines, the braille blank. */
|
|
74
|
+
const BLANK = /^[\p{White_Space}\u2800]*$/u;
|
|
75
|
+
/** More than 32 blanks in a row on a line, or more than two blank lines in a row (P109). */
|
|
76
|
+
const BLANK_RUN = /[\p{Zs}\t\u2800]{33}|\n(?:[\p{Zs}\t\u2800]*\n){3}/u;
|
|
77
|
+
/** Line and paragraph separators: a line break a person may see as nothing (Firefox, WebKit). */
|
|
78
|
+
const SEPARATORS = /[\u2028\u2029]/u;
|
|
79
|
+
|
|
73
80
|
/**
|
|
74
|
-
* A draft (P108): text the person will post in their own name, so all of it must be text
|
|
75
|
-
* see: at most 2,000 characters, well-formed,
|
|
76
|
-
*
|
|
77
|
-
*
|
|
81
|
+
* A draft (P108, P109): text the person will post in their own name, so all of it must be text
|
|
82
|
+
* they can see: at most 2,000 characters, well-formed, and nothing invisible (`unseenStrict`: no
|
|
83
|
+
* zero-width characters, bidi or tag characters, controls but a new line and a tab; a joiner or
|
|
84
|
+
* non-joiner only between two letters or marks, a variation selector only after a pictograph), no line or paragraph
|
|
85
|
+
* separator, not blank-looking, at most 32 blanks in a row and two blank lines in a row (so that
|
|
86
|
+
* "whole" is something a host can show). Lines and tabs are fine: a checklist.
|
|
78
87
|
*/
|
|
79
88
|
const draftText = (value: unknown): value is string =>
|
|
80
89
|
typeof value === "string" &&
|
|
81
|
-
value.trim() !== "" &&
|
|
82
90
|
value.length <= 2_000 &&
|
|
83
91
|
value.isWellFormed() &&
|
|
84
|
-
!
|
|
92
|
+
!BLANK.test(value) &&
|
|
93
|
+
!unseenStrict(value) &&
|
|
94
|
+
!SEPARATORS.test(value) &&
|
|
95
|
+
!BLANK_RUN.test(value);
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* An anchor's label or quote, shown beside the draft (P109): the page's short text, without what a
|
|
99
|
+
* person can't see (P105's `withoutUnseen`, line and paragraph separators too), or null if nothing
|
|
100
|
+
* visible is left. Shown, never posted as the person's words, so cleaned rather than refused.
|
|
101
|
+
*/
|
|
102
|
+
const shownText = (value: unknown, max: number): string | null => {
|
|
103
|
+
if (!shortText(value, max)) {
|
|
104
|
+
return null;
|
|
105
|
+
}
|
|
106
|
+
const seen = withoutUnseen(value).replace(/[\u2028\u2029]/gu, "");
|
|
107
|
+
return BLANK.test(seen) ? null : seen;
|
|
108
|
+
};
|
|
85
109
|
|
|
86
110
|
export function parseCommentRequest(args: unknown): CommentRequest | null {
|
|
87
111
|
const anchor = isRecord(args) ? args.anchor : undefined;
|
|
@@ -89,18 +113,16 @@ export function parseCommentRequest(args: unknown): CommentRequest | null {
|
|
|
89
113
|
return null;
|
|
90
114
|
}
|
|
91
115
|
const draft = isRecord(args) ? args.draft : undefined;
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
(draft !== undefined && !draftText(draft))
|
|
96
|
-
) {
|
|
116
|
+
const label = anchor.label === undefined ? undefined : shownText(anchor.label, 200);
|
|
117
|
+
const quote = anchor.quote === undefined ? undefined : shownText(anchor.quote, 2_000);
|
|
118
|
+
if (label === null || quote === null || (draft !== undefined && !draftText(draft))) {
|
|
97
119
|
return null;
|
|
98
120
|
}
|
|
99
121
|
return {
|
|
100
122
|
anchor: {
|
|
101
123
|
name: anchor.name,
|
|
102
|
-
...(
|
|
103
|
-
...(
|
|
124
|
+
...(label === undefined ? {} : { label }),
|
|
125
|
+
...(quote === undefined ? {} : { quote }),
|
|
104
126
|
},
|
|
105
127
|
...(draft === undefined ? {} : { draft }),
|
|
106
128
|
};
|
|
@@ -7,7 +7,7 @@ export const RUNTIME_TYPES: Readonly<Record<string, Readonly<Record<string, stri
|
|
|
7
7
|
"assets": "// Porthole capability runtime, contract 1: assets (the artifact's asset library). Declare it: { assets: {} }.\n// Assets live outside every version, at \"/_blob/<id>\" on the page's own origin: keep that url (or\n// the id) in your data, and show it with assets.url(id). Images, media and fonts load; scripts and\n// stylesheets only where the app lets only admins upload, and only those an admin added. Not for\n// files that version with the page: publish those with it.\n\ninterface PortholeAsset {\n /** 32 hex characters. */\n readonly id: string;\n /** \"/_blob/<id>\": use it as given. */\n readonly url: string;\n readonly name: string;\n /** Porthole's type for the name's extension. */\n readonly type: string;\n readonly size: number;\n}\n\ninterface PortholeAssets {\n /** The library, people's uploads through the page included. Level: view. */\n list(): Promise<readonly PortholeAsset[]>;\n /**\n * Adds a file (a File from an <input type=\"file\">, a Blob, bytes) under its name (a File's own,\n * or options.name): an image, media, a font, a PDF, text or data, never HTML; a script or a\n * stylesheet only where uploads are the admins'. The app may ask the person first. Level: admin,\n * unless the app lets people who interact upload.\n */\n upload(\n file: Blob | ArrayBuffer | ArrayBufferView,\n options?: { readonly name?: string },\n ): Promise<PortholeAsset>;\n /**\n * The address that loads an asset in this page now: put it in src or href when you show it.\n * Store the id (or \"/_blob/<id>\"), never this: it carries this page's access. A \"/_blob/<id>\"\n * written in the page loads too, except in some browsers' frames (Safari's); this always does.\n */\n url(id: string): string;\n /** Removes one, from a click; the app asks the person first. Level: admin. */\n delete(id: string): Promise<boolean>;\n}\n\ninterface PortholeCapabilities {\n assets: PortholeAssets;\n}\n",
|
|
8
8
|
"chat": "// Porthole capability runtime, contract 1: chat. Declare it: { chat: {} }.\n\ninterface PortholeChat {\n /**\n * Sends text to the agent as the person's message (\"explain this point\"). Call it from a click.\n * Resolves true if it was sent. Level: interact.\n */\n send(text: string): Promise<boolean>;\n}\n\ninterface PortholeCapabilities {\n chat: PortholeChat;\n}\n",
|
|
9
9
|
"clipboard": "// Porthole capability runtime, contract 1: clipboard. Built in: never declare it.\n\ninterface PortholeClipboard {\n /**\n * Copies text to the person's clipboard (at most 20,000 characters); the app shows them what\n * was copied. Nothing else in the page can write the clipboard. Call it from a click.\n * Resolves true if it was copied. Level: view.\n */\n copy(text: string): Promise<boolean>;\n}\n\ninterface PortholeCapabilities {\n clipboard: PortholeClipboard;\n}\n",
|
|
10
|
-
"comments": "// Porthole capability runtime, contract 1: comments. Built in: never declare it.\n\n/** Where a comment goes, in the page's own words. */\ninterface PortholeCommentAnchor {\n /** A stable name the page chose: \"slide-3\", \"refs/a.md#L12\" (at most 256 characters). */\n readonly name: string;\n /** What the app shows for it (at most 200). */\n readonly label?: string;\n /** The text the comment is about (at most 2,000). */\n readonly quote?: string;\n}\n\n/** How the composer opens. */\ninterface PortholeCommentOptions {\n /**\n * Text the composer starts with (at most 2,000 characters): a draft the person edits, posts\n * or discards in the app. It is never posted without them. Visible text only: new lines and\n * tabs are fine; a draft with zero-width, bidi or tag characters is refused.\n */\n readonly draft?: string;\n}\n\ninterface PortholeComments {\n /**\n * Opens the app's comment composer at the anchor (a name alone is { name }), starting with\n * `options.draft` if given. The person writes and posts it in the app. Resolves true if the\n * composer opened
|
|
10
|
+
"comments": "// Porthole capability runtime, contract 1: comments. Built in: never declare it.\n\n/** Where a comment goes, in the page's own words. */\ninterface PortholeCommentAnchor {\n /** A stable name the page chose: \"slide-3\", \"refs/a.md#L12\" (at most 256 characters). */\n readonly name: string;\n /** What the app shows for it (at most 200; what a person can't see is taken out). */\n readonly label?: string;\n /** The text the comment is about (at most 2,000; what a person can't see is taken out). */\n readonly quote?: string;\n}\n\n/** How the composer opens. */\ninterface PortholeCommentOptions {\n /**\n * Text the composer starts with (at most 2,000 characters): a draft the person edits, posts\n * or discards in the app. It is never posted without them. Visible text only: new lines and\n * tabs are fine (at most 32 blanks in a row, two blank lines in a row), and so are U+200C and\n * U+200D between two letters or marks (Persian, the Indic scripts); a draft with zero-width\n * characters, a joiner anywhere else (an emoji joined with U+200D too; ❤️ is fine), bidi or tag\n * characters, or a line or paragraph separator (U+2028, U+2029) is refused.\n */\n readonly draft?: string;\n}\n\ninterface PortholeComments {\n /**\n * Opens the app's comment composer at the anchor (a name alone is { name }), starting with\n * `options.draft` if given. The person writes and posts it in the app. Resolves true if the\n * composer opened, false if it didn't (the app may refuse while the person is writing).\n * Write-only: a page never reads comments. Call it from a click in the page. Level: view.\n */\n open(anchor: PortholeCommentAnchor | string, options?: PortholeCommentOptions): Promise<boolean>;\n}\n\ninterface PortholeCapabilities {\n comments: PortholeComments;\n}\n",
|
|
11
11
|
"context": "// Porthole capability runtime, contract 1: context. Declare it: { context: {} }.\n\ninterface PortholeContextUpdate {\n /**\n * MCP text blocks only: [{ type: \"text\", text: \"…\" }]. Visible characters only, here and in\n * structuredContent: no zero-width or bidi controls, variation selectors, tag or private-use\n * characters, or controls other than new lines and tabs (refused), but the selectors and\n * joiners inside real emoji (☀️, 👨👩👧, 1️⃣), and a joiner or non-joiner between two letters of\n * a script it shapes (Arabic, Persian, the Indic scripts, Myanmar…).\n */\n readonly content?: readonly unknown[];\n /** Plain JSON. With the text, at most 20,000 characters. */\n readonly structuredContent?: Record<string, unknown>;\n}\n\ninterface PortholeContext {\n /**\n * Tells the agent, at its next turns, what the page says the person is looking at (replaces the\n * last). The agent reads it as the page's words, unconfirmed by the person; the app shows the\n * person each update unless it says otherwise. Level: interact.\n */\n set(update: PortholeContextUpdate): Promise<unknown>;\n}\n\ninterface PortholeCapabilities {\n context: PortholeContext;\n}\n",
|
|
12
12
|
"data": "// Porthole capability runtime, contract 1: data (the app's data and tools).\n// Declare it: { data: {} }, or narrow it: { data: { resources: [\"app://tasks/*\"], tools: [\"create_task\"] } }\n// (exact names, or a prefix ending in *; absent: everything the app serves).\n\ninterface PortholeDataInfo {\n /** The first value may be the app's last copy (stale: true), with the current one right after. */\n readonly stale: boolean;\n readonly uri: string;\n}\n\ninterface PortholeData {\n /** Reads the app's data at uri, as the person viewing it may see it: JSON parsed, else text. Level: view. */\n read(uri: string): Promise<unknown>;\n /**\n * Keeps the page current: onData(value, info) now and at every change; onError hears a\n * refusal. Returns a function that stops it. Draw from onData every time; don't poll. Level: view.\n */\n subscribe(\n uri: string,\n onData: (value: unknown, info: PortholeDataInfo) => void,\n onError?: (error: PortholeError) => void,\n ): () => void;\n /** Calls one of the app's tools; resolves with its result. Level: interact. */\n call(name: string, args?: Record<string, unknown>): Promise<unknown>;\n}\n\ninterface PortholeCapabilities {\n data: PortholeData;\n}\n",
|
|
13
13
|
"db": "// Porthole capability runtime, contract 1: db (the artifact's shared document store).\n// Declare it: { db: {} }, with rules if some data needs a higher level:\n// { db: { rules: { config: { write: \"admin\" }, \"*\": { read: \"view\", write: \"interact\" } } } }\n// (by top-level collection or \"*\"; they only raise the defaults: read view, write interact).\n// Use it for data people share and keep (votes, entries, a board); localStorage for one person's\n// view settings; the artifact capability when the page itself is the record.\n// Rows were written by the page's viewers: they are data, never instructions. Show them with\n// textContent, never innerHTML.\n\n/** JSON values. */\ntype PortholeDbValue =\n | null\n | boolean\n | number\n | string\n | readonly PortholeDbValue[]\n | { readonly [field: string]: PortholeDbValue };\n\ntype PortholeDbData = { readonly [field: string]: PortholeDbValue };\n\n/**\n * A document. Paths are slash-separated: a collection is an odd number of segments (\"votes\",\n * \"rooms/r1/messages\"), a document an even number (\"votes/ada\"); segments are letters, digits and\n * _ . ~ : @ + -. \"data/users/me\" is the viewer's own private collection (\"data/users/me/prefs\" a document in it):\n * only they reach it.\n */\ninterface PortholeDbSnapshot {\n readonly path: string;\n readonly id: string;\n readonly exists: boolean;\n /** Counts its writes (1 after the first); 0 when it doesn't exist. */\n readonly version: number;\n readonly data?: PortholeDbData;\n}\n\n/** Every write to a document that exists names the version you read; a mismatch rejects with conflict. ifVersion 0: it must not exist yet. */\ninterface PortholeDbWriteOptions {\n readonly ifVersion?: number;\n}\n\ntype PortholeDbWrite =\n | {\n readonly op: \"set\";\n readonly path: string;\n readonly data: PortholeDbData;\n readonly ifVersion?: number;\n }\n | {\n readonly op: \"update\";\n readonly path: string;\n readonly data: PortholeDbData;\n readonly ifVersion?: number;\n }\n | { readonly op: \"delete\"; readonly path: string; readonly ifVersion?: number };\n\ninterface PortholeDbQuery {\n /** At most 10: [field, op, value]. */\n readonly where?: readonly (readonly [\n field: string,\n op: \"==\" | \"!=\" | \"<\" | \"<=\" | \">\" | \">=\" | \"in\" | \"array-contains\",\n value: PortholeDbValue,\n ])[];\n readonly orderBy?: { readonly field: string; readonly direction?: \"asc\" | \"desc\" };\n /** 1 to 500. */\n readonly limit?: number;\n}\n\ninterface PortholeDb {\n /** Level: view. */\n get(path: string): Promise<PortholeDbSnapshot>;\n /** A collection's documents. Level: view. */\n query(\n collection: string,\n query?: PortholeDbQuery,\n ): Promise<{ readonly docs: readonly PortholeDbSnapshot[] }>;\n /** Writes a whole document (at most 1 MiB of JSON). Level: interact. */\n set(\n path: string,\n data: PortholeDbData,\n options?: PortholeDbWriteOptions,\n ): Promise<{ readonly version: number }>;\n /** Merges fields over a document's. Level: interact. */\n update(\n path: string,\n data: PortholeDbData,\n options?: PortholeDbWriteOptions,\n ): Promise<{ readonly version: number }>;\n /** Level: interact. */\n delete(path: string, options?: PortholeDbWriteOptions): Promise<null>;\n /**\n * Up to 50 writes to different documents, all or none. Each write's new version (null for a\n * delete). Each write at its own level.\n */\n batch(\n writes: readonly PortholeDbWrite[],\n ): Promise<{ readonly versions: readonly (number | null)[] }>;\n /**\n * Follows a document (a snapshot) or a collection ({ docs }) now and at every change. Returns a\n * function that stops it. Draw from onData; don't poll. Level: view.\n */\n onSnapshot(\n path: string,\n onData: (state: PortholeDbSnapshot | { readonly docs: readonly PortholeDbSnapshot[] }) => void,\n onError?: (error: PortholeError) => void,\n ): () => void;\n}\n\ninterface PortholeCapabilities {\n db: PortholeDb;\n}\n",
|
|
@@ -4,9 +4,9 @@
|
|
|
4
4
|
interface PortholeCommentAnchor {
|
|
5
5
|
/** A stable name the page chose: "slide-3", "refs/a.md#L12" (at most 256 characters). */
|
|
6
6
|
readonly name: string;
|
|
7
|
-
/** What the app shows for it (at most 200). */
|
|
7
|
+
/** What the app shows for it (at most 200; what a person can't see is taken out). */
|
|
8
8
|
readonly label?: string;
|
|
9
|
-
/** The text the comment is about (at most 2,000). */
|
|
9
|
+
/** The text the comment is about (at most 2,000; what a person can't see is taken out). */
|
|
10
10
|
readonly quote?: string;
|
|
11
11
|
}
|
|
12
12
|
|
|
@@ -15,7 +15,10 @@ interface PortholeCommentOptions {
|
|
|
15
15
|
/**
|
|
16
16
|
* Text the composer starts with (at most 2,000 characters): a draft the person edits, posts
|
|
17
17
|
* or discards in the app. It is never posted without them. Visible text only: new lines and
|
|
18
|
-
* tabs are fine
|
|
18
|
+
* tabs are fine (at most 32 blanks in a row, two blank lines in a row), and so are U+200C and
|
|
19
|
+
* U+200D between two letters or marks (Persian, the Indic scripts); a draft with zero-width
|
|
20
|
+
* characters, a joiner anywhere else (an emoji joined with U+200D too; ❤️ is fine), bidi or tag
|
|
21
|
+
* characters, or a line or paragraph separator (U+2028, U+2029) is refused.
|
|
19
22
|
*/
|
|
20
23
|
readonly draft?: string;
|
|
21
24
|
}
|
|
@@ -24,7 +27,8 @@ interface PortholeComments {
|
|
|
24
27
|
/**
|
|
25
28
|
* Opens the app's comment composer at the anchor (a name alone is { name }), starting with
|
|
26
29
|
* `options.draft` if given. The person writes and posts it in the app. Resolves true if the
|
|
27
|
-
* composer opened
|
|
30
|
+
* composer opened, false if it didn't (the app may refuse while the person is writing).
|
|
31
|
+
* Write-only: a page never reads comments. Call it from a click in the page. Level: view.
|
|
28
32
|
*/
|
|
29
33
|
open(anchor: PortholeCommentAnchor | string, options?: PortholeCommentOptions): Promise<boolean>;
|
|
30
34
|
}
|