@weatherboard/annotation 0.6.0 → 0.7.0

package/dist/shortcut.d.mts

@@ -0,0 +1,52 @@
+import type { BuildInfo } from "./protocol.mjs";
+/**
+ * The in-app shortcut's pre-arm half (A-2384).
+ *
+ * WHY THIS LIVES IN `./bootstrap` AND NOT IN `mountAnnotation`
+ * A host loads the toolbar behind a dynamic `import()` that only an armed page
+ * reaches (ADOPTING.md, step 6). On an ordinary staging page there is no
+ * marker, so nothing from the index entry point is loaded, and a listener
+ * there cannot hear the chord. This one is installed by the small, statically
+ * imported entry point on every annotatable page, armed or not.
+ *
+ * ONE DECISION, MADE BY WHOEVER IS MOUNTED
+ * The mounted toolbar's own listener toggles the toolbar when the page is armed
+ * with a fresh token, and calls `preventDefault()`. This listener waits for the
+ * dispatch to finish and re-arms only if nothing claimed the chord: no toolbar
+ * loaded, a toolbar whose token is missing or within five minutes of expiry,
+ * or a toolbar the reviewer ended with Done. So the two listeners cannot both
+ * act, and freshness is judged in exactly one place.
+ *
+ * WHAT RE-ARMING IS
+ * A top-level navigation to Studio's `/annotate/arm`, which checks the signed-in
+ * reviewer, mints the tokens and redirects back to the return path with them in
+ * the query; the host's middleware arms on that request and the bootstrap
+ * script strips the query. The only thing this side carries is a return path
+ * with every annotation parameter removed, plus a credential-free open intent
+ * in session storage so the armed mount on return opens the toolbar.
+ *
+ * PRODUCTION
+ * `isAnnotatableBuild` refuses production at install: no listener is added.
+ */
+/** The default chord: Command or Control, Shift and the full stop. */
+export declare const DEFAULT_HOTKEY = "Mod+Shift+Period";
+/** Exact modifiers and a KeyboardEvent code or key, such as Mod+Shift+Period. */
+export declare function matchesHotkey(event: Pick<KeyboardEvent, "key" | "code" | "metaKey" | "ctrlKey" | "shiftKey" | "altKey" | "repeat">, chord: string): boolean;
+export interface AnnotationShortcutOptions {
+    /** The same build the mount is given. Production installs nothing. */
+    build: Pick<BuildInfo, "env">;
+    /**
+     * Studio's arm endpoint for this product's staging target, for example
+     * `https://studio.example/annotate/arm?product=<product-id>&target=staging`. Absolute
+     * http(s), and carrying no `return`: the shortcut adds it.
+     */
+    armUrl: string;
+    /** The chord. The mount must be given the same one. */
+    hotkey: string;
+    /** Defaults to the ambient `document`. */
+    doc?: Document;
+}
+/** The URL the chord navigates to: `armUrl` plus a token-free return path. */
+export declare function annotationArmUrl(armUrl: string, current: string): string;
+/** Install the pre-arm listener. Returns its removal. */
+export declare function installAnnotationShortcut(options: AnnotationShortcutOptions): () => void;

package/dist/shortcut.d.ts

@@ -0,0 +1,52 @@
+import type { BuildInfo } from "./protocol.js";
+/**
+ * The in-app shortcut's pre-arm half (A-2384).
+ *
+ * WHY THIS LIVES IN `./bootstrap` AND NOT IN `mountAnnotation`
+ * A host loads the toolbar behind a dynamic `import()` that only an armed page
+ * reaches (ADOPTING.md, step 6). On an ordinary staging page there is no
+ * marker, so nothing from the index entry point is loaded, and a listener
+ * there cannot hear the chord. This one is installed by the small, statically
+ * imported entry point on every annotatable page, armed or not.
+ *
+ * ONE DECISION, MADE BY WHOEVER IS MOUNTED
+ * The mounted toolbar's own listener toggles the toolbar when the page is armed
+ * with a fresh token, and calls `preventDefault()`. This listener waits for the
+ * dispatch to finish and re-arms only if nothing claimed the chord: no toolbar
+ * loaded, a toolbar whose token is missing or within five minutes of expiry,
+ * or a toolbar the reviewer ended with Done. So the two listeners cannot both
+ * act, and freshness is judged in exactly one place.
+ *
+ * WHAT RE-ARMING IS
+ * A top-level navigation to Studio's `/annotate/arm`, which checks the signed-in
+ * reviewer, mints the tokens and redirects back to the return path with them in
+ * the query; the host's middleware arms on that request and the bootstrap
+ * script strips the query. The only thing this side carries is a return path
+ * with every annotation parameter removed, plus a credential-free open intent
+ * in session storage so the armed mount on return opens the toolbar.
+ *
+ * PRODUCTION
+ * `isAnnotatableBuild` refuses production at install: no listener is added.
+ */
+/** The default chord: Command or Control, Shift and the full stop. */
+export declare const DEFAULT_HOTKEY = "Mod+Shift+Period";
+/** Exact modifiers and a KeyboardEvent code or key, such as Mod+Shift+Period. */
+export declare function matchesHotkey(event: Pick<KeyboardEvent, "key" | "code" | "metaKey" | "ctrlKey" | "shiftKey" | "altKey" | "repeat">, chord: string): boolean;
+export interface AnnotationShortcutOptions {
+    /** The same build the mount is given. Production installs nothing. */
+    build: Pick<BuildInfo, "env">;
+    /**
+     * Studio's arm endpoint for this product's staging target, for example
+     * `https://studio.example/annotate/arm?product=<product-id>&target=staging`. Absolute
+     * http(s), and carrying no `return`: the shortcut adds it.
+     */
+    armUrl: string;
+    /** The chord. The mount must be given the same one. */
+    hotkey: string;
+    /** Defaults to the ambient `document`. */
+    doc?: Document;
+}
+/** The URL the chord navigates to: `armUrl` plus a token-free return path. */
+export declare function annotationArmUrl(armUrl: string, current: string): string;
+/** Install the pre-arm listener. Returns its removal. */
+export declare function installAnnotationShortcut(options: AnnotationShortcutOptions): () => void;

package/dist/toolbar.d.cts

@@ -1,6 +1,7 @@
 import type { AnnotationSdk, AnnotationSdkOptions, CommentCollector } from "./sdk.cjs";
 import { type Arming } from "./arming.cjs";
 import type { EgressOutcome } from "./transport.cjs";
+export { DEFAULT_HOTKEY, matchesHotkey } from "./shortcut.cjs";
 /**
  * The toolbar and the post-it (A-240).
  *
@@ -131,6 +132,8 @@ export interface AnnotationToolbarOptions {
      * Unarmed, NOTHING IS APPENDED TO THE DOCUMENT. Not hidden: absent.
      */
     armed?: boolean;
+    /** Keep the toolbar detached until the host's chord is pressed. */
+    dormant?: boolean;
     doc?: Document;
     /** Only for the viewport clamp, so a fake one is two numbers. */
     win?: Pick<Window, "innerWidth" | "innerHeight">;
@@ -149,11 +152,21 @@ export interface AnnotationToolbar {
     showResult: (outcome: EgressOutcome, retry: () => void) => void;
     /** Whether the panel is open. For tests and for the mounting app. */
     isExpanded: () => boolean;
+    setVisible: (visible: boolean) => void;
+    isVisible: () => boolean;
     destroy: () => void;
 }
 export declare function createAnnotationToolbar(options?: AnnotationToolbarOptions): AnnotationToolbar;
 export interface MountAnnotationOptions extends AnnotationSdkOptions {
     toolbar?: AnnotationToolbarOptions;
+    /**
+     * Opt-in (A-2384). A chord such as `DEFAULT_HOTKEY` starts an armed toolbar
+     * hidden until it is pressed; absent or null keeps the immediate toolbar every
+     * mount before 0.7.0 had. Mod means Meta on macOS and Control elsewhere.
+     * Re-arming is not this listener's: with no fresh token it leaves the chord
+     * unclaimed, and `installAnnotationShortcut` (from `./bootstrap`) re-arms.
+     */
+    hotkey?: string | null;
     /**
      * The arming decision, from `readArming()` (A-241).
      *

package/dist/toolbar.d.mts

@@ -1,6 +1,7 @@
 import type { AnnotationSdk, AnnotationSdkOptions, CommentCollector } from "./sdk.mjs";
 import { type Arming } from "./arming.mjs";
 import type { EgressOutcome } from "./transport.mjs";
+export { DEFAULT_HOTKEY, matchesHotkey } from "./shortcut.mjs";
 /**
  * The toolbar and the post-it (A-240).
  *
@@ -131,6 +132,8 @@ export interface AnnotationToolbarOptions {
      * Unarmed, NOTHING IS APPENDED TO THE DOCUMENT. Not hidden: absent.
      */
     armed?: boolean;
+    /** Keep the toolbar detached until the host's chord is pressed. */
+    dormant?: boolean;
     doc?: Document;
     /** Only for the viewport clamp, so a fake one is two numbers. */
     win?: Pick<Window, "innerWidth" | "innerHeight">;
@@ -149,11 +152,21 @@ export interface AnnotationToolbar {
     showResult: (outcome: EgressOutcome, retry: () => void) => void;
     /** Whether the panel is open. For tests and for the mounting app. */
     isExpanded: () => boolean;
+    setVisible: (visible: boolean) => void;
+    isVisible: () => boolean;
     destroy: () => void;
 }
 export declare function createAnnotationToolbar(options?: AnnotationToolbarOptions): AnnotationToolbar;
 export interface MountAnnotationOptions extends AnnotationSdkOptions {
     toolbar?: AnnotationToolbarOptions;
+    /**
+     * Opt-in (A-2384). A chord such as `DEFAULT_HOTKEY` starts an armed toolbar
+     * hidden until it is pressed; absent or null keeps the immediate toolbar every
+     * mount before 0.7.0 had. Mod means Meta on macOS and Control elsewhere.
+     * Re-arming is not this listener's: with no fresh token it leaves the chord
+     * unclaimed, and `installAnnotationShortcut` (from `./bootstrap`) re-arms.
+     */
+    hotkey?: string | null;
     /**
      * The arming decision, from `readArming()` (A-241).
      *

package/dist/toolbar.d.ts

@@ -1,6 +1,7 @@
 import type { AnnotationSdk, AnnotationSdkOptions, CommentCollector } from "./sdk.js";
 import { type Arming } from "./arming.js";
 import type { EgressOutcome } from "./transport.js";
+export { DEFAULT_HOTKEY, matchesHotkey } from "./shortcut.js";
 /**
  * The toolbar and the post-it (A-240).
  *
@@ -131,6 +132,8 @@ export interface AnnotationToolbarOptions {
      * Unarmed, NOTHING IS APPENDED TO THE DOCUMENT. Not hidden: absent.
      */
     armed?: boolean;
+    /** Keep the toolbar detached until the host's chord is pressed. */
+    dormant?: boolean;
     doc?: Document;
     /** Only for the viewport clamp, so a fake one is two numbers. */
     win?: Pick<Window, "innerWidth" | "innerHeight">;
@@ -149,11 +152,21 @@ export interface AnnotationToolbar {
     showResult: (outcome: EgressOutcome, retry: () => void) => void;
     /** Whether the panel is open. For tests and for the mounting app. */
     isExpanded: () => boolean;
+    setVisible: (visible: boolean) => void;
+    isVisible: () => boolean;
     destroy: () => void;
 }
 export declare function createAnnotationToolbar(options?: AnnotationToolbarOptions): AnnotationToolbar;
 export interface MountAnnotationOptions extends AnnotationSdkOptions {
     toolbar?: AnnotationToolbarOptions;
+    /**
+     * Opt-in (A-2384). A chord such as `DEFAULT_HOTKEY` starts an armed toolbar
+     * hidden until it is pressed; absent or null keeps the immediate toolbar every
+     * mount before 0.7.0 had. Mod means Meta on macOS and Control elsewhere.
+     * Re-arming is not this listener's: with no fresh token it leaves the chord
+     * unclaimed, and `installAnnotationShortcut` (from `./bootstrap`) re-arms.
+     */
+    hotkey?: string | null;
     /**
      * The arming decision, from `readArming()` (A-241).
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weatherboard/annotation",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Click an element in a running app, get the source location that rendered it.",
   "keywords": [
     "annotation",
@@ -122,16 +122,26 @@
   "//sizeBudget-host": "A-359, and the first note this entry point has had. MEASURED BY RUNNING `node build.mjs` AND READING ITS OUTPUT, three entry points, before and after, on this branch rather than trusted from the last note: host 566 -> 649 (+83), protocol 800 -> 869 (+69), index 9531 -> 9599 (+68). WHAT THE BYTES ARE: `unhandledMessage` in protocol.ts, which is the whole of protocol's 69 and is re-exported into index for index's 68; host pays that 69 plus 14 for its own `default` branch. The `const unhandled: never` assertions cost NOTHING - they are erased at build, which is the good half of this trade. WHAT THEY BUY: host.ts and sdk.ts each dispatched on a discriminated union with no `default`, so a message type added to `ParentToFrame` or `FrameToParent` was DROPPED by whichever half had not been taught about it, with no error anywhere. Measured before the fix: adding a member to each union and running `tsc --noEmit` gave exit 0 and zero errors. These two files are the only things in the world that can disagree about what a message on this wire means, and they deploy from different repositories. THE FIRST DRAFT OF THE SENTENCE COST 230 CHARACTERS AND PUT ALL THREE ENTRY POINTS OVER AT ONCE - index 9717/9650, protocol 991/870, host 771/660 - which is the gate working, and is why the shipped string is one line: which half, what arrived, and that nothing was done with it. Nothing beyond that survived the budget, and nothing beyond that is load-bearing. BUDGETS RAISED: protocol 870 -> 890, index 9650 -> 9700, host 660 -> 680. Every one of the three was ALREADY UNDER its old budget after the string was trimmed - 869/870, 9599/9650 and 649/660 - so this is not a raise to make a failure go away, and the numbers above are the gate's own output at both ends. It is a raise because 1, 51 and 11 bytes of headroom is the state the A-277 note names as the thing to avoid: 'a budget that fails on the next sentence somebody writes rather than on the next decision somebody makes'. Protocol at one byte would have failed the next contributor over a comma. New headroom: protocol 890/869 = 2.4%, host 680/649 = 4.8%, index 9700/9599 = 1.05% - index tightest in proportion for the reason every note here gives, that a percentage of index is a lot of bytes, and the two small entry points looser for the reason protocol has always run looser, that 20 bytes is 2% there and would be 0.2% of index.",
   "//sizeBudget-host-a359-cycle2": "The guard on `unhandledMessage`'s stringify, and this raise IS forced by the gate rather than headroom-tidying like the one above it. MEASURED BY RUNNING `node build.mjs`, every figure its own output: protocol 869 -> 908 (+39), host 649 -> 686 (+37), index 9599 -> 9615 (+16). protocol and host both went OVER their A-359 budgets (908/890, 686/680) and are raised to 940 and 720; index needs nothing and is NOT raised, so it stays at 9700 with 9615 against it. WHAT THE BYTES BUY: `unhandledMessage` interpolated `JSON.stringify(message)` unguarded, and postMessage serialises with STRUCTURED CLONE, which PRESERVES CYCLES where JSON cannot represent them - so a circular `event.data` made the function throw `Converting circular structure to JSON` from inside a `message` listener on a page this SDK is a guest on, once per message, at the sender's discretion. That is the exact outcome the forty-line comment on that function argues against; the implementation defeated its own argument. Both the circular case and a throwing-getter Proxy were confirmed RED against the previous implementation before the fix and are pinned in exhaustive.test.ts. THE EXPENSIVE ALTERNATIVE WAS TRIED AND MEASURED RATHER THAN REASONED ABOUT: reusing `describeArg` from state.ts - which solves the same problem and whose own comment names the same hazard - costs protocol 869 -> 1008 (+139) and host 649 -> 793 (+144), a hundred bytes per entry point more than the local version, because describeArg is built for console ARGUMENTS (strings, Errors, a prototype walk) and almost none of it is reachable for a wire message. It was reverted for a second reason that would stand even at equal cost: `protocol.ts` currently has ZERO imports, `state.ts` imports FROM it, and importing back would make the pure wire contract depend on the console-patching state collector and close a module cycle that is invisible only because state.ts's side is `import type`. The cost of that choice is two safe-stringify helpers in this package instead of one; they cannot drift in a way that matters, each being a total function with one behaviour and its own test, and the note on `safeJson` says what to do if a third ever appears. New headroom: protocol 940/908 = 3.5%, host 720/686 = 5.0%, index 9700/9615 = 0.88%.",
   "//sizeBudget-a1375": "A-1375 adds an eighth, deliberately small ./bootstrap entry point for the synchronous pre-hydration script, arming reads and token-free startup status. It is separate so an ordinary visitor does not download the toolbar, state collector or transport before the page knows it is armed. REPRODUCED WITH NODE 22.19.0 by running `pnpm --filter @weatherboard/annotation build` on the unmodified origin/main baseline 4d1df98e and on this source, then reading build.mjs's ESM gzip rows: index 9919 -> 10082 (+163), protocol 908 -> 967 (+59), and bootstrap absent (0 emitted bytes) -> 2321 (+2321). The index increase pays for the hosted-mode constants re-export and Done clearing shared bootstrap state; protocol pays for the two token-free capability constants; bootstrap contains the new early runtime itself. The index budget moves 9950 -> 10150 (+200, 2.01%) and leaves 68 bytes, 0.67% of its current artifact. The protocol budget moves 940 -> 1000 (+60, 6.38%) and leaves 33 bytes, 3.41% of its current artifact, effectively preserving its previous 32-byte allowance. The new bootstrap budget is 2350 and leaves 29 bytes, 1.25% of its current artifact. Bootstrap is deliberately tighter than protocol because it runs synchronously in every adopting document; all three limits remain close enough that the next material feature requires an explicit increase rather than spending unrecorded slack.",
+  "//sizeBudget-a2385": "A-2385, the viewport screenshot. MEASURED BY RUNNING `node build.mjs` under Node 22.23.3, before (an archive of origin/main) and after: index 10082 -> 10441 (+359): the viewport caps, the option resolution, the timeout wrapper and the lazy loader in screenshot.ts. Budget 10150 -> 10500. NINTH ENTRY POINT `page-capture`, 1308 as built, budget 1400: it is an entry ONLY so it can be lazy - screenshot.ts loads it with import() on the first capture, so its 1.3KB and the modern-screenshot library behind it (~14KB, external, not counted here) are downloaded by a page that is clicked and by no other. Folding it into index was measured too: 11385, which is the cost this split avoids.",
+  "//sizeBudget-a2384": "A-2384 adds cookie fallback and expiry decisions to readArming, exported by both index and bootstrap, plus shortcut wiring in index. The Node 22.23.3 package build measured index 11035 and bootstrap 2822 gzip bytes on this branch; both exceeded the previous 10150 and 2350 limits. Raise only those entry points to 11100 and 2850, leaving 65 and 28 bytes of headroom. Other entry points remain at their previous limits. No runtime dependency was added.",
+  "//sizeBudget-a2384-cycle2": "Cycle 2 of A-2384 makes the shortcut opt-in, reveals the toolbar when a result is shown, and carries an open intent through re-arming in session storage; bootstrap re-exports the intent's storage key so a host pre-arm listener can write it. MEASURED with Node 22.23.3 by `pnpm build`: index 11035 -> 11183 (+148) and bootstrap 2822 -> 2859 (+37), over the 11100 and 2850 limits. Raise only those two to 11250 and 2900, leaving 67 and 41 bytes of headroom. Other entry points are unchanged.",
+  "//sizeBudget-a2384-cycle3": "Cycle 3 of A-2384 moves the shortcut's re-arming out of mountAnnotation into ./bootstrap (installAnnotationShortcut, matchesHotkey, DEFAULT_HOTKEY, annotationArmUrl), because a host loads the index entry only on an armed page and an unarmed page must still hear the chord. MEASURED with Node 22.23.3 by `pnpm build`: bootstrap 2859 -> 3383 (+524), index 11183 -> 11098 (-85, onNeedArming and the intent write left it). Raise bootstrap only, 2900 -> 3450, leaving 67 bytes. Index stays at 11250. Other entry points are unchanged.",
+  "//sizeBudget-a2385-merge": "After merging the shortcut source from main with A-2385's lazy screenshot loader, Node 22.23.3 `pnpm --filter @weatherboard/annotation build` measured index 11452 gzip bytes, 202 above the shortcut branch's 11250 limit and 354 above its measured 11098. Raise index to 11500, leaving 48 bytes; page-capture remains 1301/1400 and the other entry points remain below their limits.",
   "sizeBudget": {
-    "bootstrap": 2350,
+    "bootstrap": 3450,
     "protocol": 1000,
-    "index": 10150,
+    "index": 11500,
+    "page-capture": 1400,
     "host": 720,
     "anchor": 1100,
     "read": 1700,
     "markers": 4250,
     "selection": 3500
   },
+  "//dependencies": "ONE, by approved exception (A-2385, owner decision 2026-10-17). `modern-screenshot` renders the viewport for the capture's screenshot: MIT, maintained, zero dependencies of its own, ~14KB gzip. It is imported dynamically in src/page-capture.ts only and kept external by build.mjs, so it is not in any entry point's bundle or size budget and an armed page that is never clicked never loads it. The argument is in the header of build.mjs; any further dependency needs its own there.",
+  "dependencies": {
+    "modern-screenshot": "^4.7.0"
+  },
   "engines": {
     "node": ">=18"
   },