@botiverse/porthole 0.10.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.
Files changed (68) hide show
  1. package/dist/annotate/types.d.ts +18 -6
  2. package/dist/annotate/validate.d.ts +11 -1
  3. package/dist/annotate/validate.js +18 -1
  4. package/dist/bridge/bridge.d.ts +8 -1
  5. package/dist/bridge/bridge.js +7 -0
  6. package/dist/bridge/unseen.d.ts +8 -0
  7. package/dist/bridge/unseen.js +17 -0
  8. package/dist/check/files.d.ts +2 -0
  9. package/dist/check/files.js +71 -50
  10. package/dist/check/lint.d.ts +8 -1
  11. package/dist/check/lint.js +18 -0
  12. package/dist/check/markup.d.ts +7 -0
  13. package/dist/check/markup.js +49 -0
  14. package/dist/check/page-source.js +1 -1
  15. package/dist/check/scroll.d.ts +116 -0
  16. package/dist/check/scroll.js +1485 -0
  17. package/dist/config/capabilities.d.ts +16 -3
  18. package/dist/config/capabilities.js +1 -0
  19. package/dist/conformance/harness-source.js +1 -1
  20. package/dist/conformance/runtime.js +6 -0
  21. package/dist/guide/guide.js +1 -1
  22. package/dist/guide/runtime.js +2 -2
  23. package/dist/host/create-host.js +30 -3
  24. package/dist/host/types.d.ts +15 -0
  25. package/dist/index.d.ts +2 -1
  26. package/dist/index.js +1 -0
  27. package/dist/platform/focus-guard.d.ts +143 -0
  28. package/dist/platform/focus-guard.js +445 -0
  29. package/dist/platform/types.d.ts +18 -0
  30. package/dist/platform/web.js +22 -0
  31. package/dist/react/frame.d.ts +10 -1
  32. package/dist/react/frame.js +4 -0
  33. package/dist/runtime/requests.d.ts +5 -0
  34. package/dist/runtime/requests.js +41 -4
  35. package/dist/runtime/types.generated.js +1 -1
  36. package/dist/shell/annotate.d.ts +2 -1
  37. package/dist/shell/annotate.js +29 -12
  38. package/dist/shell/use.js +9 -1
  39. package/docs/ADOPTING.md +106 -5
  40. package/docs/ARCHITECTURE.md +2 -1
  41. package/docs/DECISIONS.md +741 -2
  42. package/docs/DESIGN.md +38 -9
  43. package/docs/THREAT_MODEL.md +146 -19
  44. package/package.json +1 -1
  45. package/src/annotate/types.ts +19 -6
  46. package/src/annotate/validate.ts +20 -1
  47. package/src/bridge/bridge.ts +17 -1
  48. package/src/bridge/unseen.ts +24 -0
  49. package/src/check/files.ts +72 -54
  50. package/src/check/lint.ts +24 -0
  51. package/src/check/markup.ts +53 -0
  52. package/src/check/scroll.ts +1825 -0
  53. package/src/config/capabilities.ts +16 -3
  54. package/src/conformance/runtime.ts +9 -0
  55. package/src/guide/guide.ts +1 -0
  56. package/src/guide/runtime.ts +2 -2
  57. package/src/host/create-host.ts +38 -3
  58. package/src/host/types.ts +13 -0
  59. package/src/index.ts +2 -0
  60. package/src/platform/focus-guard.ts +572 -0
  61. package/src/platform/types.ts +17 -0
  62. package/src/platform/web.ts +22 -0
  63. package/src/react/frame.tsx +12 -1
  64. package/src/runtime/requests.ts +50 -6
  65. package/src/runtime/types.generated.ts +1 -1
  66. package/src/shell/annotate.ts +29 -12
  67. package/src/shell/use.ts +9 -1
  68. package/types/runtime/v1/comments.d.ts +20 -6
@@ -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; 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",
@@ -16,7 +16,8 @@
16
16
  * is reported `orphaned`;
17
17
  * - markers (P104): a mark with a count gets a small bubble with the number beside its anchor's
18
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;
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;
20
21
  * - following: while a mark has a marker, once a scroll, a resize or a change of the content
21
22
  * settles, the marks that moved since the host was last told are reported, at most once a
22
23
  * second, so the host's own UI beside a mark can follow.
@@ -16,7 +16,8 @@
16
16
  * is reported `orphaned`;
17
17
  * - markers (P104): a mark with a count gets a small bubble with the number beside its anchor's
18
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;
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;
20
21
  * - following: while a mark has a marker, once a scroll, a resize or a change of the content
21
22
  * settles, the marks that moved since the host was last told are reported, at most once a
22
23
  * second, so the host's own UI beside a mark can follow.
@@ -364,8 +365,10 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
364
365
  // they are; the active one and a flash add a ring around it, not more fill over its words.
365
366
  // An element's mark with a marker is quieter (a thin line): the marker says what it is.
366
367
  // A marker is a small bubble with a number, drawn in its own colors and font (only what the
367
- // layer inherits from the page could reach it, so each of those is set here).
368
- const STYLE = ".mark{position:absolute;border-radius:2px;background:rgba(250,204,21,.18);box-shadow:inset 0 -2px 0 rgba(234,179,8,.95)}.mark.element{background:rgba(250,204,21,.07);box-shadow:none;outline:2px solid rgba(234,179,8,.9);outline-offset:1px}.mark.active{background:rgba(250,204,21,.26);box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 2px rgba(234,179,8,.45)}.mark.element.active{background:rgba(250,204,21,.12);box-shadow:none;outline-width:3px}.mark.element.quiet{background:rgba(250,204,21,.05);outline:1px solid rgba(234,179,8,.6);outline-offset:2px}.mark.element.quiet.active{background:rgba(250,204,21,.1);outline:2px solid rgba(234,179,8,.9)}.marker{position:absolute;box-sizing:border-box;height:18px;min-width:18px;display:flex;align-items:center;justify-content:center;gap:3px;margin:0;padding:0 5px;border:1px solid rgba(161,98,7,.6);border-radius:9px 9px 9px 2px;background:#fde68a;color:#422006;box-shadow:0 1px 2px rgba(0,0,0,.3);font:600 11px/16px system-ui,-apple-system,Segoe UI,Roboto,sans-serif;font-style:normal;letter-spacing:0;word-spacing:0;text-transform:none;text-indent:0;text-shadow:none;direction:ltr;writing-mode:horizontal-tb;white-space:nowrap;user-select:none;-webkit-user-select:none;cursor:pointer;pointer-events:auto}.marker:hover{background:#fcd34d}.marker.active{background:#facc15;box-shadow:0 0 0 2px rgba(234,179,8,.55),0 1px 2px rgba(0,0,0,.3)}.marker.compact{padding:0 4px}.marker.inert{pointer-events:none}.marker svg{display:block;width:11px;height:11px;flex:none}.mark.flash{animation:flash 1.8s ease-out}@keyframes flash{from{box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 6px rgba(250,204,21,.6)}}.hover{position:absolute;outline:2px solid #2563eb;outline-offset:1px;background:rgba(37,99,235,.12)}.tag{position:absolute;max-width:70vw;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font:12px/18px ui-monospace,SFMono-Regular,Menlo,monospace;padding:0 6px;border-radius:4px;background:#1e293b;color:#fff}";
368
+ // layer inherits from the page could reach it, so each of those is set here). A draft
369
+ // (P107) is a comment not yet posted: its line is dashed (an element's outline too) and its
370
+ // marker hollow, a light bubble with a dashed edge and the glyph's outline, no number.
371
+ const STYLE = ".mark{position:absolute;border-radius:2px;background:rgba(250,204,21,.18);box-shadow:inset 0 -2px 0 rgba(234,179,8,.95)}.mark.element{background:rgba(250,204,21,.07);box-shadow:none;outline:2px solid rgba(234,179,8,.9);outline-offset:1px}.mark.active{background:rgba(250,204,21,.26);box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 2px rgba(234,179,8,.45)}.mark.element.active{background:rgba(250,204,21,.12);box-shadow:none;outline-width:3px}.mark.element.quiet{background:rgba(250,204,21,.05);outline:1px solid rgba(234,179,8,.6);outline-offset:2px}.mark.element.quiet.active{background:rgba(250,204,21,.1);outline:2px solid rgba(234,179,8,.9)}.mark.draft{box-sizing:border-box;background:rgba(250,204,21,.08);box-shadow:none;border-bottom:2px dashed rgba(202,138,4,.95)}.mark.draft.active{background:rgba(250,204,21,.16);box-shadow:0 0 0 2px rgba(234,179,8,.45);border-bottom-width:3px}.mark.element.draft{background:rgba(250,204,21,.04);border-bottom:0;outline-style:dashed}.mark.element.draft.active{background:rgba(250,204,21,.08);box-shadow:none;outline-style:dashed}.marker{position:absolute;box-sizing:border-box;height:18px;min-width:18px;display:flex;align-items:center;justify-content:center;gap:3px;margin:0;padding:0 5px;border:1px solid rgba(161,98,7,.6);border-radius:9px 9px 9px 2px;background:#fde68a;color:#422006;box-shadow:0 1px 2px rgba(0,0,0,.3);font:600 11px/16px system-ui,-apple-system,Segoe UI,Roboto,sans-serif;font-style:normal;letter-spacing:0;word-spacing:0;text-transform:none;text-indent:0;text-shadow:none;direction:ltr;writing-mode:horizontal-tb;white-space:nowrap;user-select:none;-webkit-user-select:none;cursor:pointer;pointer-events:auto}.marker:hover{background:#fcd34d}.marker.active{background:#facc15;box-shadow:0 0 0 2px rgba(234,179,8,.55),0 1px 2px rgba(0,0,0,.3)}.marker.compact{padding:0 4px}.marker.draft{border:1px dashed rgb(202,138,4);background:#fffdf5;color:#a16207;box-shadow:0 1px 2px rgba(0,0,0,.2)}.marker.draft:hover{background:#fef9e7}.marker.draft.active{background:#fef3c7;box-shadow:0 0 0 2px rgba(234,179,8,.55),0 1px 2px rgba(0,0,0,.2)}.marker.inert{pointer-events:none}.marker svg{display:block;width:11px;height:11px;flex:none}.mark.flash{animation:flash 1.8s ease-out}@keyframes flash{from{box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 6px rgba(250,204,21,.6)}}.hover{position:absolute;outline:2px solid #2563eb;outline-offset:1px;background:rgba(37,99,235,.12)}.tag{position:absolute;max-width:70vw;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font:12px/18px ui-monospace,SFMono-Regular,Menlo,monospace;padding:0 6px;border-radius:4px;background:#1e293b;color:#fff}";
369
372
  // Inline and important: the content's own style sheets can't hide, shrink or move it by
370
373
  // accident. Set again at each draw, since its scripts can rewrite it (narrowing only: the
371
374
  // content can still cover the layer, or move it with its ancestors, P104).
@@ -645,10 +648,10 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
645
648
  // window's first listener stops every click on the layer); the click is told there.
646
649
  callOf(listenOn, marker, ["click", tapTarget]);
647
650
  }
648
- marker.className = "marker" + (each.compact ? " compact" : "") + (mark.id === active ? " active" : "") + (mode.elements ? " inert" : "");
651
+ marker.className = "marker" + (mark.draft ? " draft" : "") + (each.compact ? " compact" : "") + (mark.id === active ? " active" : "") + (mode.elements ? " inert" : "");
649
652
  marker.style.cssText = "left:" + each.left + "px;top:" + each.top + "px";
650
653
  markers.push({ id: mark.id, element: marker });
651
- const form = (each.compact ? "compact:" : "full:") + label;
654
+ const form = (mark.draft ? "draft:" : "") + (each.compact ? "compact:" : "full:") + label;
652
655
  if (kept && kept.form === form) {
653
656
  return marker;
654
657
  }
@@ -659,7 +662,15 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
659
662
  glyph.setAttribute("viewBox", "0 0 16 16");
660
663
  glyph.setAttribute("aria-hidden", "true");
661
664
  const path = createElementNS.call(document, SVG, "path");
662
- path.setAttribute("fill", "currentColor");
665
+ // A draft's glyph is its outline (P107), a posted one's filled.
666
+ if (mark.draft) {
667
+ path.setAttribute("fill", "none");
668
+ path.setAttribute("stroke", "currentColor");
669
+ path.setAttribute("stroke-width", "1.5");
670
+ path.setAttribute("stroke-linejoin", "round");
671
+ } else {
672
+ path.setAttribute("fill", "currentColor");
673
+ }
663
674
  path.setAttribute("d", "M3 2h10a2 2 0 0 1 2 2v6a2 2 0 0 1-2 2H8l-4 3v-3H3a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2z");
664
675
  glyph.appendChild(path);
665
676
  marker.appendChild(glyph);
@@ -719,14 +730,15 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
719
730
  continue;
720
731
  }
721
732
  const each = createElement.call(document, "div");
722
- each.className = "mark " + (mark.found.range ? "text" : "element") + (mark.count === null ? "" : " quiet") + (mark.id === active || mark.id === hot ? " active" : "") + (flashOn && mark.id === flashing ? " flash" : "");
733
+ each.className = "mark " + (mark.found.range ? "text" : "element") + (mark.marker ? " quiet" : "") + (mark.draft ? " draft" : "") + (mark.id === active || mark.id === hot ? " active" : "") + (flashOn && mark.id === flashing ? " flash" : "");
723
734
  each.style.cssText = "left:" + rect.left + "px;top:" + rect.top + "px;width:" + rect.width + "px;height:" + rect.height + "px";
724
735
  parts.push(each);
725
736
  }
726
- if (mark.count !== null) {
737
+ if (mark.marker) {
727
738
  const at = lastBox(rects);
728
739
  if (at !== null) {
729
- const label = labelOf(mark.count);
740
+ // A draft's marker has no number (P107).
741
+ const label = mark.draft ? "" : labelOf(mark.count);
730
742
  const each = { mark, order: corners.length + wanted.length, label, width: markerWidth(label), small: compactWidth(label), compact: false, at, left: 0, top: 0 };
731
743
  if (mark.found.range) {
732
744
  // Kept while it still holds the words (P105): a change elsewhere doesn't move them.
@@ -926,7 +938,7 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
926
938
  let followed = 0;
927
939
  // A scroll moved the page since the selection was last told: it is followed only then.
928
940
  let selectionScrolled = false;
929
- const counted = () => marks.some((mark) => mark.count !== null);
941
+ const counted = () => marks.some((mark) => mark.marker);
930
942
  const sendFollow = () => {
931
943
  let sent = 0;
932
944
  if (marks.length > 0 && !settling() && counted()) {
@@ -1244,10 +1256,15 @@ export const ANNOTATE_RUNTIME = String.raw `if (declared("annotate")) {
1244
1256
  stop();
1245
1257
  break;
1246
1258
  case M.show:
1259
+ // A draft (P107) has a marker and never a number; a kind the shell doesn't know is no mark.
1247
1260
  marks = (Array.isArray(params.marks) ? params.marks : [])
1248
1261
  .slice(0, LIMIT.marks)
1249
- .filter((mark) => mark && typeof mark.id === "string" && mark.anchor && Array.isArray(mark.anchor.selectors))
1250
- .map((mark) => ({ id: mark.id, anchor: mark.anchor, count: typeof mark.count === "number" && mark.count >= 0 && mark.count <= LIMIT.count && Math.floor(mark.count) === mark.count ? mark.count : null, found: null, state: null, told: null }));
1262
+ .filter((mark) => mark && typeof mark.id === "string" && mark.anchor && Array.isArray(mark.anchor.selectors) && (mark.kind === undefined || mark.kind === "posted" || mark.kind === "draft"))
1263
+ .map((mark) => {
1264
+ const draft = mark.kind === "draft";
1265
+ const count = !draft && typeof mark.count === "number" && mark.count >= 0 && mark.count <= LIMIT.count && Math.floor(mark.count) === mark.count ? mark.count : null;
1266
+ return { id: mark.id, anchor: mark.anchor, count, draft, marker: draft || count !== null, found: null, state: null, told: null };
1267
+ });
1251
1268
  if (typeof params.active === "string") {
1252
1269
  active = params.active;
1253
1270
  }
package/dist/shell/use.js CHANGED
@@ -131,7 +131,15 @@ export const USE_RUNTIME = String.raw `
131
131
  const METHODS = {
132
132
  user: { get: () => call("user", "get", {}) },
133
133
  comments: {
134
- open: (anchor) => clicked("comments", "comments.open") || call("comments", "open", { anchor: typeof anchor === "string" ? { name: anchor } : record(anchor) }),
134
+ // The draft goes as the page gave it, for the host to refuse what isn't text (P108): read
135
+ // after the click's check, so a getter that throws is a rejection; options that aren't an
136
+ // object send a null draft, refused.
137
+ open: (anchor, options) =>
138
+ clicked("comments", "comments.open") ||
139
+ Promise.resolve().then(() => {
140
+ const draft = options === undefined || options === null ? undefined : typeof options === "object" ? options.draft : null;
141
+ return call("comments", "open", { anchor: typeof anchor === "string" ? { name: anchor } : record(anchor), ...(draft === undefined ? {} : { draft }) });
142
+ }),
135
143
  },
136
144
  clipboard: { copy: (text) => clicked("copyText", "clipboard.copy") || call("clipboard", "copy", { text: String(text) }) },
137
145
  links: { open: (url) => clicked("openLink", "links.open") || call("links", "open", { url: String(url) }) },
package/docs/ADOPTING.md CHANGED
@@ -251,10 +251,16 @@ createHost(config, {
251
251
  With `annotate` declared (`capabilities: { annotate: {} }`), a host lets people point at a
252
252
  display and keeps its comments beside it ([P053](DECISIONS.md), P104). Everything the frame
253
253
  reports is the page's word: a hint where to draw, never a permission. A mark's `count` puts a
254
- numbered marker beside its words; a click on one is `activated`.
254
+ numbered marker beside its words; a click on one is `activated`. A draft, a comment its author
255
+ hasn't posted yet (`kind: "draft"`, P107), is drawn apart: a dashed line and a hollow marker with no
256
+ number, which is clicked and followed as a posted one is.
255
257
 
256
258
  ```js
257
- display.annotations.show(comments.map((c) => ({ id: c.markId, anchor: c.anchor, count: c.replies })));
259
+ display.annotations.show([
260
+ ...comments.map((c) => ({ id: c.markId, anchor: c.anchor, count: c.replies })),
261
+ // Only in the author's own frame: the page can read that these are drafts.
262
+ ...myDrafts.map((d) => ({ id: d.markId, anchor: d.anchor, kind: "draft" })),
263
+ ]);
258
264
  display.annotations.start({ elements: false, text: true }); // comment mode: the person selects words
259
265
  display.on("annotation", (report) => {
260
266
  if (report.type === "selected") composer.openBeside(frame, report.rect, report.anchor);
@@ -265,13 +271,30 @@ display.on("annotation", (report) => {
265
271
 
266
272
  - **Ids say nothing, and a count only where the page may know it**: the content reads every
267
273
  `show`. Who wrote what stays in your view, outside the frame.
274
+ - **Drafts only to their author's frame**: the page reads which marks are drafts (that its viewer
275
+ is writing a comment there), so send a person's drafts only to the frame that person is viewing,
276
+ never one shared with others. A draft's `count` is dropped before the frame (no number is
277
+ drawn), so give a draft's id at random like any other; a `kind` other than `"posted"` or
278
+ `"draft"` throws, as a bad anchor does (React: `onHostError`, kind `"annotations"`). The shell
279
+ is your content server's: upgrade its Porthole first, or an older shell draws a draft as a
280
+ posted mark without a marker. The view a draft's `activated` opens is guarded like any (below)
281
+ and puts no "Post", "Submit review" or "Discard" one click away: a page can fake that click on
282
+ the person's own press in the content (P107, P109).
283
+ - **No drafts to a page that can pass them on**, or accept that it does: a page with the runtime's
284
+ `db` writes and `user` can store who is drafting where (`user.get()` and the marks it is shown)
285
+ for its author and other viewers to read before the draft is posted, and tie the posted comment
286
+ to its author after; origins its config declares for egress (an MCP App's `connectDomains`, an
287
+ `egress` you opened) can carry the same out. Send
288
+ drafts only to pages without such a channel (annotations, `copyText`, `openLink` and the like),
289
+ or accept that the page's author and other viewers can learn of them (THREAT_MODEL §7).
268
290
  - **The content chooses when your view opens and where** (it can post `activated` for a mark you
269
291
  show on the person's own press in the content, under their pointer, P105), so a view that a
270
292
  report opens or moves takes no press of any kind for 500 ms after it appears or moves (no
271
293
  `pointerdown`, `pointerup`, `click` or key: menu triggers act on a press, and menu items click
272
294
  themselves on a release), ignores a press that began before that, opens beside the frame rather
273
- than over `rect` where the layout allows, takes no focus, and has no destructive action (resolve,
274
- delete) one click away. Making it `inert` while it arms does all of the first:
295
+ than over `rect` where the layout allows, takes no focus, and has nothing one click away that
296
+ posts, submits, resolves, deletes or discards. Making it `inert` while it arms does all of the
297
+ first:
275
298
 
276
299
  ```js
277
300
  // Call placed() each time the view appears or moves. For 500 ms it takes nothing (inert: no
@@ -322,6 +345,37 @@ display.on("annotation", (report) => {
322
345
  the person can't see; a quote (`exact`) keeps it, to be found again. Hand either to a model only
323
346
  as the page's words.
324
347
 
348
+ ### The keyboard: what a display can take, and what you get
349
+
350
+ Any display can move the keyboard into its frame (`element.focus()` in the page, with no gesture
351
+ on Chromium and WebKit), and what the person goes on typing in your composer or chat box then goes
352
+ to the page. `createHost` (and so `PortholeView`) guards every display (P109): when focus leaves
353
+ one of your page's text fields (a `<textarea>`, an `<input>` that takes text, a `contenteditable`
354
+ region) for a display's frame without the person's press on the frame or a Tab into it, focus goes
355
+ back to the field, and the display tells you; a display that keeps doing it is stopped.
356
+
357
+ ```js
358
+ display.on("focusTaken", ({ typing }) => toast(typing ? "This page tried to take what you were typing." : "This page tried to take the keyboard."));
359
+ display.on("contentError", ({ message }) => log(message)); // "The content kept taking the keyboard from the page; it was stopped."
360
+ // Moving focus into a display yourself (a "focus the page" shortcut): use the display's own move.
361
+ display.focus(); // not frame.focus(): from a text field, that one is taken for the page's and undone
362
+ // Opening your composer focused (on `selected`, say): Porthole's move, not textarea.focus().
363
+ import { focusField } from "@botiverse/porthole";
364
+ focusField(composer.textarea); // Firefox ignores a plain focus() while a fighting frame holds focus
365
+ ```
366
+
367
+ - **Free:** the guard, on by default, with no option. A page gets at most the keys typed before
368
+ focus is back (none or one in a sentence, measured on all three engines); three tries while the
369
+ person types (within 10 s), or five within 2 s, stop the display (`reload()` runs it again).
370
+ - **Yours:** don't move focus from a text field into a display with the frame's own `focus()`
371
+ (use `display.focus()`), nor into your composer with the field's own `focus()` where a display
372
+ may hold focus (use `focusField`: on Firefox a page with the person's gesture that takes focus
373
+ back on its blur keeps a plain `focus()` from landing, and gets the keys); with a platform of your own (a native web view), implement `focused`,
374
+ `onFocusTaken` and `focus` on its surface, or a display can read what is typed beside it; know
375
+ the limits (THREAT_MODEL §7 "The keyboard": on Firefox, which shows your page no press
376
+ in a frame, a page keeps the keyboard if the pointer came over its frame after the person last
377
+ typed and after the field got focus; moves between two frames aren't judged).
378
+
325
379
  ## 4. Served pages: the host kit
326
380
 
327
381
  ### Local development
@@ -505,7 +559,11 @@ handlers: {
505
559
  db: (args, { viewer, declared, instance, changed, signal }) => myApi.db(instance, viewer, args, declared?.rules, { changed, signal }),
506
560
  artifact: (args, { viewer, instance }) => myApi.artifact(instance, viewer, args), // Refused("conflict") when base moved
507
561
  assets: (args, { viewer, instance }) => myApi.assets(instance, viewer, args),
508
- comments: ({ anchor }) => composer.open(anchor), // true if it opened
562
+ // true if it opened. Never over the person's own words or place; a page's draft (P108) shown whole,
563
+ // editable, as the page's suggestion, taking no focus, posted only on the person's Send (below)
564
+ // (inUse: the composer holds the person's own words, or a place they chose)
565
+ comments: ({ anchor, draft }) =>
566
+ composer.inUse() ? false : draft === undefined ? composer.open(anchor) : openPageDraft(composer, anchor, draft),
509
567
  },
510
568
  // 5. The mount: what this version declared, within what the artifact declares now; null for a
511
569
  // page published before 0.7 (required under a runtime). Before rendering: a stored
@@ -516,6 +574,49 @@ if (shown && !shown.ok) return <VersionError problems={shown.problems} />; //
516
574
  <PortholeView display="page" instance={instance} declaration={shown ? shown.declaration : null} />
517
575
  ```
518
576
 
577
+ - **A page's draft in your composer** (P108, P109): `comments.open` reaches your handler only from
578
+ a gesture with the person in that frame (a press in it, a Tab into it; not their typing in your
579
+ UI), but the page still picks the moment (the second click of a double click, a field it asked
580
+ them to type into). So the composer it fills is the person's to act on:
581
+
582
+ ```js
583
+ // A composer the page filled: its words are the page's until the person acts in it.
584
+ function openPageDraft(composer, anchor, draft) {
585
+ // Opens beside the frame, and takes no focus: keys stay where the person was typing, so what
586
+ // they type for the page never lands in a postable comment.
587
+ composer.open(anchor, { text: draft, focus: false }); // where your composer focuses, focusField
588
+ // Armed as THREAT_MODEL §6 says: no press of any kind for 500 ms (guardPresses, § Annotations).
589
+ guardPresses(composer.element).placed();
590
+ // Said by you, outside the frame where the page can't draw, until they edit it: never shown as
591
+ // one of their own drafts.
592
+ composer.setNote("Suggested by this page");
593
+ composer.input.addEventListener("input", () => composer.setNote(null), { once: true });
594
+ // Enter sends only once the person has focused or edited the composer themselves (a press in
595
+ // it, a Tab into it, their typing); until then Send is a click. It opened without focus, and a
596
+ // page can't move focus into your page's fields, so its focus is theirs.
597
+ let theirs = false;
598
+ for (const type of ["pointerdown", "focus", "input"]) {
599
+ composer.input.addEventListener(type, () => (theirs = true), { once: true });
600
+ }
601
+ composer.input.addEventListener("keydown", (event) => {
602
+ if (event.key === "Enter" && !theirs) event.preventDefault();
603
+ });
604
+ return true;
605
+ }
606
+ ```
607
+
608
+ - Never over the person's words: while the composer holds their text, or a place they chose,
609
+ answer `false`, or show the page's words as a separate suggestion that takes no focus; never
610
+ replace, append to or retarget what they wrote.
611
+ - Show the draft whole, as plain text (a comment that renders as markdown hides an HTML comment
612
+ or a link definition from readers but not from an agent: render a page-drafted comment as
613
+ plain text, or show before Send what readers will see); show the anchor's `label` and `quote`
614
+ as isolated text (`<bdi>`, `dir="auto"`). Porthole has already refused a draft with anything
615
+ invisible, a line separator or a run of blanks, and taken what can't be seen out of the label
616
+ and quote.
617
+ - Nothing one click away in it, or in a draft's view, posts, submits or discards; your own list
618
+ of a person's drafts (not the frame's markers, which a page can draw too) is how they find
619
+ theirs.
519
620
  - **Built-ins** (`clipboard`, `links`, `downloads`, `comments`) reach every page whose kind offers
520
621
  them; everything else only a page that declared it. A page with no declaration (one published
521
622
  before 0.7) gets the built-ins through `use` and 0.6's globals as before: give it a declaration
@@ -294,7 +294,8 @@ several displays on one page are in [THREAT_MODEL.md](THREAT_MODEL.md).
294
294
  - **Annotations** (`annotate`): the host drives a select mode and marks anchors in
295
295
  the shell; anchors are W3C Web Annotation selectors a host stores with its own
296
296
  comments (P053). A mark may carry a count, drawn as a clickable marker whose click
297
- the host hears and answers with its own UI outside the frame (P104).
297
+ the host hears and answers with its own UI outside the frame (P104), and may be a
298
+ draft, its author's unposted comment, drawn apart with a hollow marker (P107).
298
299
  - **Served content.** A host plugs its own policy and infrastructure into `/server`:
299
300
  who may see what (`authorize`), where tickets live (`TicketStore`: memory, D1),
300
301
  how origins are named (`content.name`, other servers' `reserved` namespaces),