@botiverse/porthole 0.9.0 → 0.12.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.
Files changed (65) hide show
  1. package/dist/annotate/types.d.ts +21 -7
  2. package/dist/annotate/validate.d.ts +18 -3
  3. package/dist/annotate/validate.js +29 -5
  4. package/dist/bridge/bridge.js +1 -51
  5. package/dist/bridge/unseen.d.ts +18 -0
  6. package/dist/bridge/unseen.js +71 -0
  7. package/dist/check/files.d.ts +2 -0
  8. package/dist/check/files.js +67 -50
  9. package/dist/check/lint.d.ts +8 -1
  10. package/dist/check/lint.js +18 -0
  11. package/dist/check/markup.d.ts +7 -0
  12. package/dist/check/markup.js +49 -0
  13. package/dist/check/page-source.js +1 -1
  14. package/dist/check/scroll.d.ts +100 -0
  15. package/dist/check/scroll.js +1429 -0
  16. package/dist/conformance/behavior.js +107 -68
  17. package/dist/conformance/clipboard.js +16 -14
  18. package/dist/conformance/harness-source.js +1 -1
  19. package/dist/conformance/limits.js +117 -64
  20. package/dist/conformance/probes.js +66 -49
  21. package/dist/conformance/runtime.js +6 -0
  22. package/dist/conformance/served.js +66 -63
  23. package/dist/guide/guide.js +1 -1
  24. package/dist/guide/runtime.js +2 -2
  25. package/dist/host/create-host.js +46 -4
  26. package/dist/index.d.ts +1 -1
  27. package/dist/platform/types.d.ts +4 -2
  28. package/dist/react/frame.d.ts +2 -1
  29. package/dist/runtime/requests.d.ts +5 -0
  30. package/dist/runtime/requests.js +16 -1
  31. package/dist/runtime/types.generated.js +1 -1
  32. package/dist/shell/annotate.d.ts +6 -3
  33. package/dist/shell/annotate.js +474 -104
  34. package/dist/shell/use.js +9 -1
  35. package/docs/ADOPTING.md +99 -1
  36. package/docs/ARCHITECTURE.md +2 -1
  37. package/docs/DECISIONS.md +764 -14
  38. package/docs/DESIGN.md +192 -42
  39. package/docs/THREAT_MODEL.md +109 -27
  40. package/package.json +1 -1
  41. package/src/annotate/types.ts +22 -7
  42. package/src/annotate/validate.ts +32 -6
  43. package/src/bridge/bridge.ts +1 -60
  44. package/src/bridge/unseen.ts +82 -0
  45. package/src/check/files.ts +68 -54
  46. package/src/check/lint.ts +24 -0
  47. package/src/check/markup.ts +53 -0
  48. package/src/check/scroll.ts +1757 -0
  49. package/src/conformance/behavior.ts +221 -69
  50. package/src/conformance/clipboard.ts +44 -14
  51. package/src/conformance/limits.ts +169 -76
  52. package/src/conformance/probes.ts +97 -49
  53. package/src/conformance/runtime.ts +9 -0
  54. package/src/conformance/served.ts +112 -63
  55. package/src/guide/guide.ts +1 -0
  56. package/src/guide/runtime.ts +2 -2
  57. package/src/host/create-host.ts +50 -4
  58. package/src/index.ts +1 -0
  59. package/src/platform/types.ts +4 -2
  60. package/src/react/frame.tsx +2 -1
  61. package/src/runtime/requests.ts +23 -1
  62. package/src/runtime/types.generated.ts +1 -1
  63. package/src/shell/annotate.ts +474 -104
  64. package/src/shell/use.ts +9 -1
  65. package/types/runtime/v1/comments.d.ts +14 -4
@@ -158,7 +158,7 @@ function widget(c) {
158
158
  const smallest = Math.round(((13 * layout.minWidthPx) / viewBox) * 10) / 10;
159
159
  const largest = Math.round(((13 * 400) / viewBox) * 10) / 10;
160
160
  const textSize = themeDefault(config.theme.variables["--font-text-md-size"] ?? "14px", "light").replace(/^(\d+(?:\.\d+)?)px$/u, "$1 px");
161
- return lines(`# ${title}${tool}`, "", what, "", `Where it runs: ${fills ? `in a sandboxed frame that fills the app's viewer (often smaller than the window: toolbars and side panels take room), about ${layout.narrowWidthPx} px wide on a phone (${layout.minWidthPx} on a small one) and wider on a desktop` : `in a sandboxed frame as wide as the column it sits in, about ${layout.narrowWidthPx} px on a phone (${layout.minWidthPx} on a small one) and ${layout.wideWidthPx} on a desktop`}; the same ${noun} is read on both, so never write for one of them. Design for ${layout.narrowWidthPx} first; where the layout depends on the width, read it as it runs (the ${fills ? "frame's own innerWidth, again on resize" : "box's clientWidth, again from a ResizeObserver"}). ${said("layout")} ${said("theme")} It runs again each time it is shown${loadsScripts(config) ? ": pin library versions" : ""}.`, "", "Sizes that read on a phone:", c.when(`- Words go in HTML (titles, notes, legends, readouts): it keeps its size and wraps. The frame's text is already ${textSize} --font-sans in --color-text-primary; notes --font-text-sm-size, never under 12 px.`), `- An SVG scales with the frame: its text shows at font-size × frame width ÷ viewBox width, so a 680-wide viewBox turns 12 into 5 px on a phone. Draw it for the phone: viewBox="0 0 ${viewBox} H", no text under 13, width="100%" style="max-width: 400px"; its text then shows at ${smallest} to ${largest} px on every screen. Or draw it 1 unit = 1 px with a script (topic chart).`, `- The frame never scrolls sideways: nothing fixed wider than ${layout.minWidthPx} px; images max-width: 100%; a grid or flex child with long text min-width: 0; a wide table or code block in its own box with overflow-x: auto.`, "- Cards in a row wrap (flex-wrap: wrap; flex: 1 1 100px), or a grid of repeat(auto-fit, minmax(160px, 1fr)): at most 2 columns under 500 px, never a fixed repeat(3, …).", "- Touch: anything clickable is at least 44 px tall. Phones don't hover: what a hover shows, a tap (click) shows too.", fills
161
+ return lines(`# ${title}${tool}`, "", what, "", `Where it runs: ${fills ? `in a sandboxed frame that fills the app's viewer (often smaller than the window: toolbars and side panels take room), about ${layout.narrowWidthPx} px wide on a phone (${layout.minWidthPx} on a small one) and wider on a desktop` : `in a sandboxed frame as wide as the column it sits in, about ${layout.narrowWidthPx} px on a phone (${layout.minWidthPx} on a small one) and ${layout.wideWidthPx} on a desktop`}; the same ${noun} is read on both, so never write for one of them. Design for ${layout.narrowWidthPx} first; where the layout depends on the width, read it as it runs (the ${fills ? "frame's own innerWidth, again on resize" : "box's clientWidth, again from a ResizeObserver"}). ${said("layout")} ${said("theme")} It runs again each time it is shown${loadsScripts(config) ? ": pin library versions" : ""}.`, "", "Sizes that read on a phone:", c.when(`- Words go in HTML (titles, notes, legends, readouts): it keeps its size and wraps. The frame's text is already ${textSize} --font-sans in --color-text-primary; notes --font-text-sm-size, never under 12 px.`), `- An SVG scales with the frame: its text shows at font-size × frame width ÷ viewBox width, so a 680-wide viewBox turns 12 into 5 px on a phone. Draw it for the phone: viewBox="0 0 ${viewBox} H", no text under 13, width="100%" style="max-width: 400px"; its text then shows at ${smallest} to ${largest} px on every screen. Or draw it 1 unit = 1 px with a script (topic chart).`, `- The frame never scrolls sideways: nothing fixed wider than ${layout.minWidthPx} px; images max-width: 100%; a grid or flex child with long text min-width: 0; a wide table or code block in its own box with overflow-x: auto.`, `- It scrolls as a document: unless it's meant to fit one screen (a game, a canvas), don't hold html, body or the element that holds it all to one screen (height: 100% or 100vh with overflow: hidden, or position: fixed), or what's below the first screen can't be reached. A box that scrolls by itself takes the wheel while the pointer is over it: keep those to parts of the ${noun} (a wide table, a long list), never the whole of it.`, "- Cards in a row wrap (flex-wrap: wrap; flex: 1 1 100px), or a grid of repeat(auto-fit, minmax(160px, 1fr)): at most 2 columns under 500 px, never a fixed repeat(3, …).", "- Touch: anything clickable is at least 44 px tall. Phones don't hover: what a hover shows, a tap (click) shows too.", fills
162
162
  ? null
163
163
  : "- No position: fixed: the frame grows with its content, so a fixed element covers it.", "", "The sandbox:", ...stated.filter((limit) => limit.topic === "sandbox").map((limit) => `- ${limit.text}`), `Keep it under ${sizeWords(limits.maxBytes)}.`, servesFiles(config) ? "" : null, files(config), loadsScripts(config)
164
164
  ? "\nLibraries: pin an exact version at least two weeks old (chart.js@4.4.1 in its URL), never @latest or a range, so the code can't be swapped under you and draws the same every time."
@@ -17,7 +17,7 @@ import { sizeWords } from "./limits.js";
17
17
  /** How each method is called, as the manual writes it. */
18
18
  const CALLS = {
19
19
  user: { get: "user.get()" },
20
- comments: { open: "comments.open({ name, label, quote })" },
20
+ comments: { open: "comments.open({ name, label, quote }, { draft })" },
21
21
  clipboard: { copy: "clipboard.copy(text)" },
22
22
  links: { open: "links.open(url)" },
23
23
  downloads: { save: "downloads.save({ name, text | data })" },
@@ -48,7 +48,7 @@ const CALLS = {
48
48
  /** What each host function does, in a phrase, for its line. */
49
49
  const WHAT = {
50
50
  user: () => "who is viewing: { id, name, level }, as the app says",
51
- comments: () => "opens the app's comment composer at a place the page names (a stable name like slide-3 or refs/a.md#L12, a label, the quoted text); the person writes it in the app. True if it opened. Write-only: a page never reads comments",
51
+ comments: () => "opens the app's comment composer at a place the page names (a stable name like slide-3 or refs/a.md#L12, a label, the quoted text), optionally starting with a draft (at most 2,000 characters of visible text, lines and tabs fine, no zero-width, bidi or tag characters; e.g. a button's \"Approved\" or a checklist to fill in); the person edits and posts it in the app, or doesn't. True if it opened. Write-only: a page never reads comments, and never posts one",
52
52
  copyText: () => `copies text to the person's clipboard (at most ${MAX_COPY_CHARS.toLocaleString("en-US")} characters), and the app shows them what was copied; nothing else in the page can write the clipboard. True if copied`,
53
53
  openLink: () => "opens an http(s) link outside the page; a click on an <a href> does the same. True if it opened",
54
54
  downloadFile: () => "hands the person a file to save (<a download> doesn't work here). True if it started",
@@ -1,5 +1,5 @@
1
1
  import { ANNOTATE_METHODS, } from "../annotate/types.js";
2
- import { annotateMode, checkMarks, clampRect, parseReport } from "../annotate/validate.js";
2
+ import { annotateMode, checkMarks, clampRect, hasMarker, parseReport, } from "../annotate/validate.js";
3
3
  import { createBridge, onceConsent, } from "../bridge/bridge.js";
4
4
  import { compile } from "../compile/compile.js";
5
5
  import { servesFiles } from "../files/paths.js";
@@ -138,12 +138,47 @@ export function createHost(config, options = {}) {
138
138
  toFrame(ANNOTATE_METHODS.start, { ...annotating });
139
139
  }
140
140
  };
141
+ /**
142
+ * The frame's viewport as the platform tells it now; undefined where it can't (no
143
+ * `viewport`, or one that answers no size or throws, P105): every box is then nothing at the
144
+ * frame's corner, and nothing throws out of the frame's listener.
145
+ */
146
+ const frameViewport = () => {
147
+ try {
148
+ const viewport = surface?.viewport?.();
149
+ if (viewport === null || typeof viewport !== "object") {
150
+ return undefined;
151
+ }
152
+ const size = viewport;
153
+ const across = size.width;
154
+ const down = size.height;
155
+ return typeof across === "number" && typeof down === "number"
156
+ ? { width: across, height: down }
157
+ : undefined;
158
+ }
159
+ catch {
160
+ return undefined;
161
+ }
162
+ };
163
+ /**
164
+ * Whether the person is known to have made no gesture just now (P105): the platform says the
165
+ * page has no transient activation, or fails to say. Where it can't tell (undefined), as for
166
+ * the gesture gate, a report passes.
167
+ */
168
+ const noGesture = () => {
169
+ try {
170
+ return surface?.userActivation() === false;
171
+ }
172
+ catch {
173
+ return true;
174
+ }
175
+ };
141
176
  /**
142
177
  * Every box a report carries, clamped to the frame's viewport as it is now (P104): the page
143
178
  * places the host's own UI nowhere outside its frame.
144
179
  */
145
180
  const withinFrame = (report) => {
146
- const viewport = surface?.viewport?.();
181
+ const viewport = frameViewport();
147
182
  switch (report.type) {
148
183
  case "selected":
149
184
  case "activated":
@@ -162,7 +197,7 @@ export function createHost(config, options = {}) {
162
197
  /**
163
198
  * A report from the frame: checked, taken only while the host asked for it (a selection
164
199
  * only in select mode, results only for its own marks, a marker's click only for a mark it
165
- * shows with one), then through the bridge's gates.
200
+ * shows with one, a count's or a draft's, within a gesture), then through the bridge's gates.
166
201
  */
167
202
  const onAnnotation = (raw, through) => {
168
203
  if (!isRecord(raw) ||
@@ -215,7 +250,14 @@ export function createHost(config, options = {}) {
215
250
  }
216
251
  case "activated": {
217
252
  const { id } = report;
218
- if (!marks.some((mark) => mark.id === id && mark.count !== undefined)) {
253
+ if (!marks.some((mark) => mark.id === id && hasMarker(mark))) {
254
+ return;
255
+ }
256
+ // A marker's real click gives the host's page transient activation (measured on all
257
+ // three engines, P105); a click a page posts at load, on a timer or on a scroll has
258
+ // none and is dropped. One posted on the person's own press in the content passes: the
259
+ // host's view guards itself against that (THREAT_MODEL §6).
260
+ if (noGesture()) {
219
261
  return;
220
262
  }
221
263
  break;
package/dist/index.d.ts CHANGED
@@ -43,5 +43,5 @@ export { admitContent, admitFiles, type AdmitFilesResult, answerGuide, checkTool
43
43
  export { writeClipboard } from "./host/clipboard.ts";
44
44
  export { httpLocator, LocateError, servedOrOpaque, type HttpLocatorOptions, type ServedMeta, } from "./host/locator.ts";
45
45
  export type { AnnotationControls, DisplayControls, DisplayEvents, FrameBlock, FrameOutcome, DisplayHandle, HostOptions, MountOptions, PortholeHost, } from "./host/types.ts";
46
- export { ANNOTATE_METHODS, ANNOTATION_LIMITS, type AnchorResult, type AnchorState, type AnnotateMode, type AnnotationAnchor, type AnnotationMark, type AnnotationRect, type AnnotationReport, type AnnotationSelector, type CssSelector, type TextPositionSelector, type TextQuoteSelector, } from "./annotate/types.ts";
46
+ export { ANNOTATE_METHODS, ANNOTATION_LIMITS, type AnchorResult, type AnchorState, type AnnotateMode, type AnnotationAnchor, type AnnotationMark, type AnnotationMarkKind, type AnnotationRect, type AnnotationReport, type AnnotationSelector, type CssSelector, type TextPositionSelector, type TextQuoteSelector, } from "./annotate/types.ts";
47
47
  export { parseAnchor, parseRect, parseReport } from "./annotate/validate.ts";
@@ -32,13 +32,15 @@ export interface Surface {
32
32
  setColorScheme(scheme: ColorScheme): void;
33
33
  /**
34
34
  * Whether the embedding page has transient user activation now (a gesture in the frame
35
- * activates its ancestors), or undefined where the platform can't tell.
35
+ * activates its ancestors), or undefined where the platform can't tell. The gesture gate reads
36
+ * it, and so does a marker's click (P105): false, or a throw, drops it.
36
37
  */
37
38
  userActivation(): boolean | undefined;
38
39
  /**
39
40
  * The frame's viewport now, CSS px (its content box): what a box the frame reports is clamped
40
41
  * to (P104). Undefined, or absent, where the platform can't tell: every reported box is then
41
- * clamped to nothing, at the frame's corner.
42
+ * clamped to nothing, at the frame's corner, as it is for an answer that isn't a size, or a
43
+ * throw (P105).
42
44
  */
43
45
  viewport?(): {
44
46
  readonly width: number;
@@ -252,7 +252,8 @@ export interface PortholeFrameProps {
252
252
  readonly annotating?: AnnotateMode | null;
253
253
  /**
254
254
  * The anchors to mark in the frame (the host's comments). A mark with a `count` gets a
255
- * clickable marker (P104). Compared by value.
255
+ * clickable marker (P104); a draft (`kind: "draft"`, the author's own frame only) a hollow one
256
+ * with no number (P107). Compared by value.
256
257
  */
257
258
  readonly annotations?: readonly AnnotationMark[];
258
259
  /**
@@ -26,6 +26,11 @@ export interface CommentAnchor {
26
26
  }
27
27
  export interface CommentRequest {
28
28
  readonly anchor: CommentAnchor;
29
+ /**
30
+ * Text to start the person's comment with (P108): the content's word, a draft in the composer
31
+ * that the person edits and posts themselves, or doesn't. Never posted by the host on its own.
32
+ */
33
+ readonly draft?: string;
29
34
  }
30
35
  export declare function parseCommentRequest(args: unknown): CommentRequest | null;
31
36
  /** One file of a new version: text, bytes as base64, or `null` (removed from the base's set). */
@@ -1,3 +1,4 @@
1
+ import { unseen } from "../bridge/unseen.js";
1
2
  import { fileLimits, filePathProblem } from "../files/paths.js";
2
3
  import { fileTypeOf } from "../files/types.js";
3
4
  const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
@@ -20,13 +21,26 @@ export function base64Bytes(value) {
20
21
  return (value.length / 4) * 3 - padding;
21
22
  }
22
23
  const encoder = new TextEncoder();
24
+ /**
25
+ * A draft (P108): text the person will post in their own name, so all of it must be text they can
26
+ * see: at most 2,000 characters, well-formed, not blank, and nothing `unseen` (P100: no zero-width
27
+ * or bidi characters, no tags, no controls but a new line and a tab), which a host would show as
28
+ * nothing and an agent would read as the person's words. Lines and tabs are fine: a checklist.
29
+ */
30
+ const draftText = (value) => typeof value === "string" &&
31
+ value.trim() !== "" &&
32
+ value.length <= 2_000 &&
33
+ value.isWellFormed() &&
34
+ !unseen(value);
23
35
  export function parseCommentRequest(args) {
24
36
  const anchor = isRecord(args) ? args.anchor : undefined;
25
37
  if (!isRecord(anchor) || !shortText(anchor.name, 256)) {
26
38
  return null;
27
39
  }
40
+ const draft = isRecord(args) ? args.draft : undefined;
28
41
  if ((anchor.label !== undefined && !shortText(anchor.label, 200)) ||
29
- (anchor.quote !== undefined && !shortText(anchor.quote, 2_000))) {
42
+ (anchor.quote !== undefined && !shortText(anchor.quote, 2_000)) ||
43
+ (draft !== undefined && !draftText(draft))) {
30
44
  return null;
31
45
  }
32
46
  return {
@@ -35,6 +49,7 @@ export function parseCommentRequest(args) {
35
49
  ...(anchor.label === undefined ? {} : { label: anchor.label }),
36
50
  ...(anchor.quote === undefined ? {} : { quote: anchor.quote }),
37
51
  },
52
+ ...(draft === undefined ? {} : { draft }),
38
53
  };
39
54
  }
40
55
  /** The most files one publish names (as the publish protocol, task #124 §4). */
@@ -7,7 +7,7 @@ export const RUNTIME_TYPES = {
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\ninterface PortholeComments {\n /**\n * Opens the app's comment composer at the anchor (a name alone is { name }). The person writes\n * and posts it in the app. Resolves true if the composer opened. Write-only: a page never reads\n * comments. Call it from a click. Level: view.\n */\n open(anchor: PortholeCommentAnchor | string): Promise<boolean>;\n}\n\ninterface PortholeCapabilities {\n comments: PortholeComments;\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. Write-only: a page never reads comments. Call it from a click. 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",
@@ -7,14 +7,17 @@
7
7
  * The host drives it (`porthole/annotate.start|stop|show|focus|clear`) and it reports
8
8
  * (`porthole/annotate.selected|unselected|cancelled|anchored|activated`):
9
9
  * - picking an element: the element under the pointer (or finger) is outlined with its name; a
10
- * click or tap picks it, and the content's own handlers never see that click; Escape cancels;
10
+ * click or tap picks it, and the content's own handlers never see that click (unless the content
11
+ * patched the DOM's built-ins, P105); Escape cancels;
11
12
  * - selecting text: each selection that settles is reported, with where it is, and its clearing;
12
13
  * - marks: each anchor is found in the content as it is now (its CSS selector, its text where it
13
14
  * was, its text anywhere, its words with any spacing) and drawn over it, in a layer of the
14
15
  * shell's own (a closed shadow root), again whenever the content changes; what can't be found
15
16
  * is reported `orphaned`;
16
- * - markers (P104): a mark with a count gets a small bubble with the number at its anchor's end;
17
- * a click on it is reported (`activated`), and the content's own handlers never see it;
17
+ * - markers (P104): a mark with a count gets a small bubble with the number beside its anchor's
18
+ * last line (P105: in the line's gutter); a click on it is reported (`activated`), and the
19
+ * content's own handlers never see it; a draft (P107) is drawn apart, a dashed line and a hollow
20
+ * bubble with no number, and has a marker with or without a count;
18
21
  * - following: while a mark has a marker, once a scroll, a resize or a change of the content
19
22
  * settles, the marks that moved since the host was last told are reported, at most once a
20
23
  * second, so the host's own UI beside a mark can follow.