@botiverse/porthole 0.10.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.
- package/dist/annotate/types.d.ts +18 -6
- package/dist/annotate/validate.d.ts +11 -1
- package/dist/annotate/validate.js +18 -1
- package/dist/check/files.d.ts +2 -0
- package/dist/check/files.js +67 -50
- package/dist/check/lint.d.ts +8 -1
- package/dist/check/lint.js +18 -0
- package/dist/check/markup.d.ts +7 -0
- package/dist/check/markup.js +49 -0
- package/dist/check/page-source.js +1 -1
- package/dist/check/scroll.d.ts +100 -0
- package/dist/check/scroll.js +1429 -0
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/runtime.js +6 -0
- package/dist/guide/guide.js +1 -1
- package/dist/guide/runtime.js +2 -2
- package/dist/host/create-host.js +3 -3
- package/dist/index.d.ts +1 -1
- package/dist/react/frame.d.ts +2 -1
- package/dist/runtime/requests.d.ts +5 -0
- package/dist/runtime/requests.js +16 -1
- package/dist/runtime/types.generated.js +1 -1
- package/dist/shell/annotate.d.ts +2 -1
- package/dist/shell/annotate.js +29 -12
- package/dist/shell/use.js +9 -1
- package/docs/ADOPTING.md +25 -3
- package/docs/ARCHITECTURE.md +2 -1
- package/docs/DECISIONS.md +391 -2
- package/docs/DESIGN.md +31 -9
- package/docs/THREAT_MODEL.md +42 -7
- package/package.json +1 -1
- package/src/annotate/types.ts +19 -6
- package/src/annotate/validate.ts +20 -1
- package/src/check/files.ts +68 -54
- package/src/check/lint.ts +24 -0
- package/src/check/markup.ts +53 -0
- package/src/check/scroll.ts +1757 -0
- package/src/conformance/runtime.ts +9 -0
- package/src/guide/guide.ts +1 -0
- package/src/guide/runtime.ts +2 -2
- package/src/host/create-host.ts +9 -3
- package/src/index.ts +1 -0
- package/src/react/frame.tsx +2 -1
- package/src/runtime/requests.ts +23 -1
- package/src/runtime/types.generated.ts +1 -1
- package/src/shell/annotate.ts +29 -12
- package/src/shell/use.ts +9 -1
- package/types/runtime/v1/comments.d.ts +14 -4
|
@@ -588,6 +588,15 @@ export function defineRuntimeConformance(
|
|
|
588
588
|
"open",
|
|
589
589
|
);
|
|
590
590
|
expect(typeof opened === "boolean", "comments.open answers a boolean");
|
|
591
|
+
// A draft (P108): the handler takes the new field (a strict schema of its own must not refuse it).
|
|
592
|
+
const drafted = ok(
|
|
593
|
+
await as(handlers, viewers.view)("comments", {
|
|
594
|
+
anchor: { name: "slide-3" },
|
|
595
|
+
draft: "Approved",
|
|
596
|
+
}),
|
|
597
|
+
"open with a draft",
|
|
598
|
+
);
|
|
599
|
+
expect(typeof drafted === "boolean", "comments.open with a draft answers a boolean");
|
|
591
600
|
});
|
|
592
601
|
}
|
|
593
602
|
return cases;
|
package/src/guide/guide.ts
CHANGED
|
@@ -253,6 +253,7 @@ function widget(c: Context): string {
|
|
|
253
253
|
),
|
|
254
254
|
`- 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).`,
|
|
255
255
|
`- 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.`,
|
|
256
|
+
`- 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.`,
|
|
256
257
|
"- 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, …).",
|
|
257
258
|
"- Touch: anything clickable is at least 44 px tall. Phones don't hover: what a hover shows, a tap (click) shows too.",
|
|
258
259
|
fills
|
package/src/guide/runtime.ts
CHANGED
|
@@ -28,7 +28,7 @@ import { sizeWords } from "./limits.ts";
|
|
|
28
28
|
/** How each method is called, as the manual writes it. */
|
|
29
29
|
const CALLS: Readonly<Record<RuntimeCapabilityName, Readonly<Record<string, string>>>> = {
|
|
30
30
|
user: { get: "user.get()" },
|
|
31
|
-
comments: { open: "comments.open({ name, label, quote })" },
|
|
31
|
+
comments: { open: "comments.open({ name, label, quote }, { draft })" },
|
|
32
32
|
clipboard: { copy: "clipboard.copy(text)" },
|
|
33
33
|
links: { open: "links.open(url)" },
|
|
34
34
|
downloads: { save: "downloads.save({ name, text | data })" },
|
|
@@ -61,7 +61,7 @@ const CALLS: Readonly<Record<RuntimeCapabilityName, Readonly<Record<string, stri
|
|
|
61
61
|
const WHAT: Readonly<Partial<Record<CapabilityName, (config: PortholeConfig) => string>>> = {
|
|
62
62
|
user: () => "who is viewing: { id, name, level }, as the app says",
|
|
63
63
|
comments: () =>
|
|
64
|
-
"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
|
|
64
|
+
"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",
|
|
65
65
|
copyText: () =>
|
|
66
66
|
`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`,
|
|
67
67
|
openLink: () =>
|
package/src/host/create-host.ts
CHANGED
|
@@ -4,7 +4,13 @@ import {
|
|
|
4
4
|
type AnnotationMark,
|
|
5
5
|
type AnnotationReport,
|
|
6
6
|
} from "../annotate/types.ts";
|
|
7
|
-
import {
|
|
7
|
+
import {
|
|
8
|
+
annotateMode,
|
|
9
|
+
checkMarks,
|
|
10
|
+
clampRect,
|
|
11
|
+
hasMarker,
|
|
12
|
+
parseReport,
|
|
13
|
+
} from "../annotate/validate.ts";
|
|
8
14
|
import {
|
|
9
15
|
createBridge,
|
|
10
16
|
onceConsent,
|
|
@@ -253,7 +259,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
253
259
|
/**
|
|
254
260
|
* A report from the frame: checked, taken only while the host asked for it (a selection
|
|
255
261
|
* only in select mode, results only for its own marks, a marker's click only for a mark it
|
|
256
|
-
* shows with one, within a gesture), then through the bridge's gates.
|
|
262
|
+
* shows with one, a count's or a draft's, within a gesture), then through the bridge's gates.
|
|
257
263
|
*/
|
|
258
264
|
const onAnnotation = (raw: unknown, through: HostFunctionBridge) => {
|
|
259
265
|
if (
|
|
@@ -310,7 +316,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
310
316
|
}
|
|
311
317
|
case "activated": {
|
|
312
318
|
const { id } = report;
|
|
313
|
-
if (!marks.some((mark) => mark.id === id && mark
|
|
319
|
+
if (!marks.some((mark) => mark.id === id && hasMarker(mark))) {
|
|
314
320
|
return;
|
|
315
321
|
}
|
|
316
322
|
// A marker's real click gives the host's page transient activation (measured on all
|
package/src/index.ts
CHANGED
package/src/react/frame.tsx
CHANGED
|
@@ -587,7 +587,8 @@ export interface PortholeFrameProps {
|
|
|
587
587
|
readonly annotating?: AnnotateMode | null;
|
|
588
588
|
/**
|
|
589
589
|
* The anchors to mark in the frame (the host's comments). A mark with a `count` gets a
|
|
590
|
-
* clickable marker (P104)
|
|
590
|
+
* clickable marker (P104); a draft (`kind: "draft"`, the author's own frame only) a hollow one
|
|
591
|
+
* with no number (P107). Compared by value.
|
|
591
592
|
*/
|
|
592
593
|
readonly annotations?: readonly AnnotationMark[];
|
|
593
594
|
/**
|
package/src/runtime/requests.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { unseen } from "../bridge/unseen.ts";
|
|
1
2
|
import type { Limits } from "../config/schema.ts";
|
|
2
3
|
import { fileLimits, filePathProblem } from "../files/paths.ts";
|
|
3
4
|
import { fileTypeOf } from "../files/types.ts";
|
|
@@ -62,16 +63,36 @@ export interface CommentAnchor {
|
|
|
62
63
|
|
|
63
64
|
export interface CommentRequest {
|
|
64
65
|
readonly anchor: CommentAnchor;
|
|
66
|
+
/**
|
|
67
|
+
* Text to start the person's comment with (P108): the content's word, a draft in the composer
|
|
68
|
+
* that the person edits and posts themselves, or doesn't. Never posted by the host on its own.
|
|
69
|
+
*/
|
|
70
|
+
readonly draft?: string;
|
|
65
71
|
}
|
|
66
72
|
|
|
73
|
+
/**
|
|
74
|
+
* A draft (P108): text the person will post in their own name, so all of it must be text they can
|
|
75
|
+
* see: at most 2,000 characters, well-formed, not blank, and nothing `unseen` (P100: no zero-width
|
|
76
|
+
* or bidi characters, no tags, no controls but a new line and a tab), which a host would show as
|
|
77
|
+
* nothing and an agent would read as the person's words. Lines and tabs are fine: a checklist.
|
|
78
|
+
*/
|
|
79
|
+
const draftText = (value: unknown): value is string =>
|
|
80
|
+
typeof value === "string" &&
|
|
81
|
+
value.trim() !== "" &&
|
|
82
|
+
value.length <= 2_000 &&
|
|
83
|
+
value.isWellFormed() &&
|
|
84
|
+
!unseen(value);
|
|
85
|
+
|
|
67
86
|
export function parseCommentRequest(args: unknown): CommentRequest | null {
|
|
68
87
|
const anchor = isRecord(args) ? args.anchor : undefined;
|
|
69
88
|
if (!isRecord(anchor) || !shortText(anchor.name, 256)) {
|
|
70
89
|
return null;
|
|
71
90
|
}
|
|
91
|
+
const draft = isRecord(args) ? args.draft : undefined;
|
|
72
92
|
if (
|
|
73
93
|
(anchor.label !== undefined && !shortText(anchor.label, 200)) ||
|
|
74
|
-
(anchor.quote !== undefined && !shortText(anchor.quote, 2_000))
|
|
94
|
+
(anchor.quote !== undefined && !shortText(anchor.quote, 2_000)) ||
|
|
95
|
+
(draft !== undefined && !draftText(draft))
|
|
75
96
|
) {
|
|
76
97
|
return null;
|
|
77
98
|
}
|
|
@@ -81,6 +102,7 @@ export function parseCommentRequest(args: unknown): CommentRequest | null {
|
|
|
81
102
|
...(anchor.label === undefined ? {} : { label: anchor.label }),
|
|
82
103
|
...(anchor.quote === undefined ? {} : { quote: anchor.quote }),
|
|
83
104
|
},
|
|
105
|
+
...(draft === undefined ? {} : { draft }),
|
|
84
106
|
};
|
|
85
107
|
}
|
|
86
108
|
|
|
@@ -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\ninterface PortholeComments {\n /**\n * Opens the app's comment composer at the anchor (a name alone is { name }). The person writes
|
|
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",
|
package/src/shell/annotate.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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.
|
|
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.
|
|
737
|
+
if (mark.marker) {
|
|
727
738
|
const at = lastBox(rects);
|
|
728
739
|
if (at !== null) {
|
|
729
|
-
|
|
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.
|
|
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) =>
|
|
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/src/shell/use.ts
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
|
-
|
|
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) }) },
|
|
@@ -10,13 +10,23 @@ interface PortholeCommentAnchor {
|
|
|
10
10
|
readonly quote?: string;
|
|
11
11
|
}
|
|
12
12
|
|
|
13
|
+
/** How the composer opens. */
|
|
14
|
+
interface PortholeCommentOptions {
|
|
15
|
+
/**
|
|
16
|
+
* Text the composer starts with (at most 2,000 characters): a draft the person edits, posts
|
|
17
|
+
* or discards in the app. It is never posted without them. Visible text only: new lines and
|
|
18
|
+
* tabs are fine; a draft with zero-width, bidi or tag characters is refused.
|
|
19
|
+
*/
|
|
20
|
+
readonly draft?: string;
|
|
21
|
+
}
|
|
22
|
+
|
|
13
23
|
interface PortholeComments {
|
|
14
24
|
/**
|
|
15
|
-
* Opens the app's comment composer at the anchor (a name alone is { name })
|
|
16
|
-
* and posts it in the app. Resolves true if the
|
|
17
|
-
* comments. Call it from a click. Level: view.
|
|
25
|
+
* Opens the app's comment composer at the anchor (a name alone is { name }), starting with
|
|
26
|
+
* `options.draft` if given. The person writes and posts it in the app. Resolves true if the
|
|
27
|
+
* composer opened. Write-only: a page never reads comments. Call it from a click. Level: view.
|
|
18
28
|
*/
|
|
19
|
-
open(anchor: PortholeCommentAnchor | string): Promise<boolean>;
|
|
29
|
+
open(anchor: PortholeCommentAnchor | string, options?: PortholeCommentOptions): Promise<boolean>;
|
|
20
30
|
}
|
|
21
31
|
|
|
22
32
|
interface PortholeCapabilities {
|