@weatherboard/annotation 0.3.0 → 0.6.0

package/ADOPTING.md

@@ -98,23 +98,40 @@ pointed at production anyway.
 
 ```ts
 // middleware.ts
-import { ANNOTATION_ARMED_COOKIE, readAnnotationToken } from "@weatherboard/annotation/protocol";
+import {
+  ANNOTATION_ARMED_COOKIE,
+  ANNOTATION_ARMED_COOKIES,
+  ANNOTATION_TOKEN_PARAMS,
+  readAnnotationToken,
+} from "@weatherboard/annotation/protocol";
 
 const presented = readAnnotationToken(request.nextUrl.searchParams);
 const expected = process.env.ANNOTATION_TOKEN;
+const attempted = ANNOTATION_TOKEN_PARAMS.some((name) => request.nextUrl.searchParams.has(name));
+const overHttps = request.nextUrl.protocol === "https:";
 
 if (expected && presented && presented.length === expected.length && presented === expected) {
-  const overHttps = request.nextUrl.protocol === "https:";
   response.cookies.set(ANNOTATION_ARMED_COOKIE, "1", {
     httpOnly: false,           // the client bundle is what reads it
     sameSite: overHttps ? "none" : "lax",
     secure: overHttps,
     path: "/",
   });
+} else if (attempted) {
+  for (const name of ANNOTATION_ARMED_COOKIES) {
+    response.cookies.set(name, "", {
+      httpOnly: false,
+      sameSite: overHttps ? "none" : "lax",
+      secure: overHttps,
+      path: "/",
+      maxAge: 0,
+      expires: new Date(0),
+    });
+  }
 }
 ```
 
-Four details, each of which has cost somebody a day:
+Five details, each of which has cost somebody a day:
 
 - **The cookie holds `1`, never the token.** It records that the token was
   presented once, so navigation inside the frame stays armed without the secret
@@ -127,6 +144,10 @@ Four details, each of which has cost somebody a day:
 - **…but `None` is only honoured with `Secure`**, and `Secure` is dropped over
   plain http — so a local `next dev` would set a cookie the browser silently
   discards. Fall back to `Lax`, which is same-origin anyway.
+- **A fresh rejected token expires both cookie spellings.** A browser may still
+  carry a valid cookie from an earlier link. Leaving it in place turns the new
+  rejection into an accepted launch and lets the old capture/read/run context
+  survive under a different review link.
 
 ### First-party, the cookie is an ordinary one — use `armedCookie()` (A-241)
 
@@ -140,12 +161,63 @@ Do not re-derive the attributes. `@weatherboard/annotation/protocol` exports the
 cookie itself, so the two halves cannot disagree:
 
 ```ts
-import { armedCookie, clearedCookie, ANNOTATION_ARMED_COOKIE } from "@weatherboard/annotation/protocol";
+import {
+  armedCookie,
+  clearedCookie,
+  ANNOTATION_ARMED_COOKIES,
+  ANNOTATION_TOKEN_PARAMS,
+  readAnnotationToken,
+} from "@weatherboard/annotation/protocol";
 
-// after YOUR comparison against YOUR secret has succeeded, and only then:
-response.headers.append("set-cookie", armedCookie());
+const presented = readAnnotationToken(request.nextUrl.searchParams);
+const attempted = ANNOTATION_TOKEN_PARAMS.some((name) => request.nextUrl.searchParams.has(name));
+if (presented && presented === process.env.ANNOTATION_TOKEN) {
+  response.headers.append("set-cookie", armedCookie());
+} else if (attempted) {
+  for (const name of ANNOTATION_ARMED_COOKIES) {
+    response.headers.append("set-cookie", clearedCookie(name));
+  }
+}
+```
+
+Put the package bootstrap in the first raw script in `<head>`, before styles,
+analytics and hydration:
+
+```tsx
+import { annotationBootstrapScript } from "@weatherboard/annotation/bootstrap";
+
+<script dangerouslySetInnerHTML={{ __html: annotationBootstrapScript() }} />
 ```
 
+The script synchronously strips `ai_annotate`, its legacy spelling,
+`ai_capture`, `ai_read` and `ai_run`. When middleware accepted the arming link,
+it keeps capture/read/run in this tab's `sessionStorage`, so same-tab routing
+and a hard reload remain armed after the URL is clean. When middleware rejected
+the link, it persists only `{ status: "rejected", capture: "present" | "missing" }`.
+No credential from an unarmed link is stored.
+
+The client mount can consume that signal once and report a generic failure:
+
+```ts
+import {
+  consumeAnnotationAttempt,
+  reportAnnotationStartupFailure,
+} from "@weatherboard/annotation/bootstrap";
+
+const attempt = consumeAnnotationAttempt();
+if (attempt?.status === "rejected") {
+  return reportAnnotationStartupFailure("rejected-arming");
+}
+if (attempt?.capture === "missing") {
+  return reportAnnotationStartupFailure("missing-capture");
+}
+```
+
+The reporter owns one host, `#ai-annotation-startup-status`, and returns a
+cleanup function. Import and mount failures use `"import-failed"` and
+`"mount-failed"`. All copy is package-owned and contains no token or product
+name.
+
 It takes no value argument on purpose — the cookie holds a marker, never the
 token, and the first bullet above is the reason. The page half calls
 `readArming()`, which reads that cookie, strips the tokens out of the URL with
@@ -341,20 +413,36 @@ panel with the comment, who raised it, when, and what has happened to it.
 
 ```tsx
 const { readToken } = readArming();          // from `ai_read`, stripped and stored
-if (!readToken) return;                      // a link minted before markers shipped
 
 const { createAnnotationReader } = await import("@weatherboard/annotation/read");
 const { mountAnnotationMarkers } = await import("@weatherboard/annotation/markers");
 
 const layer = mountAnnotationMarkers({
-  reader: createAnnotationReader({
-    endpoint: "https://<console>/ingest/annotations",
-    readToken,
-  }),
+  // `reader` is a REQUIRED NULLABLE, not an optional. Mount whenever armed and
+  // pass null when there is no token — the count line then says so on the page.
+  // Returning early instead leaves an armed page blank, which is the one state
+  // this layer exists to make impossible. See "The count line is the feature".
+  reader: readToken
+    ? createAnnotationReader({
+        endpoint: "https://<console>/ingest/annotations",
+        readToken,
+      })
+    : null,
 });
 await layer.refresh();                       // and again after a route change
 ```
 
+**Call `refresh()` even with a null reader.** It is what replaces the *"Looking
+for annotations…"* line with *"No read credential, so annotations were not
+requested."* Treating a null reader as "nothing to do" leaves an armed page
+loading forever — a mistake that is not obvious from the signature, and one the
+first adopter made.
+
+**Treat an empty token as absent, not as a credential.** `createAnnotationReader`
+throws on `""`, and `?ai_read=` with nothing after it is a query string anyone
+can type. Guard on presence, or a stray character in a URL takes the whole mount
+down and the toolbar with it.
+
 **It is a second credential, not the capture token.** The console refuses a write
 claim at the read endpoint and a read claim at the ingest, so handing
 `captureToken` to the reader does not degrade to a read — it fails. The read
@@ -376,6 +464,34 @@ the read, whatever the answer: *"3 annotations here, 1 shown"*. Zero markers is
 exactly what "working, nothing here" looks like and a dozen distinct causes
 produce it, so a layer that drew only icons would be silent in every one.
 
+**A finished capture is hidden, and the line says how many.** The console
+suppresses `done` and `cancelled` by default, so the sentence gains a third
+clause when it is holding something back — *"3 annotations here, 1 shown · 2
+resolved"* — and the pill grows a button that re-reads with them included. You
+do not have to wire either one up; both are in the layer.
+
+The clause matters most on the page where `total` is **zero and history is
+not**: without it, a component with three finished conversations behind it reads
+*"No annotations on this page"*, and a reviewer who fixed something and came back
+to check what they had said would find no evidence there had ever been anything.
+`total` counts what the response is about, so a suppressed capture is outside it
+and is never added in — that is what keeps *"5 annotations here, 2 shown"* from
+appearing on a page where nothing is wrong.
+
+Pass `showResolved: true` to start wide. The default is `false`, matching the
+console's own default deliberately: a layer that always asked for everything
+would move that decision to a place nobody reading the console's code would see.
+
+**If you drive the reader yourself**, `read(path, { includeResolved })` is the
+only way to see them, and the console honours **only** the literal
+`?resolved=include` — `true`, `1`, `yes`, `Include` and a trailing space all get
+the default silently. Use the option rather than building the query string.
+
+**Overriding `labels.count`?** It now takes a third argument,
+`(total, shown, resolvedHidden)`. A two-parameter override still compiles and
+still works — and will not say what is being held back, which is the one thing
+that argument is for.
+
 **`refresh()` never rejects.** A refused CORS preflight arrives as `TypeError:
 Failed to fetch` with no status and no body; it becomes a sentence in the count
 line rather than an exception in your page.
@@ -446,3 +562,22 @@ misattributed.
 Every step above is a thing that, when absent, produces no error, no warning and
 no log line — only an absence. When you are debugging, prefer the check that
 distinguishes causes over the check that confirms your guess.
+
+## Host-owned contextual feedback
+
+`@weatherboard/annotation/selection` exposes `relativePoint`,
+`captureTextSelection`, `resolveTextSelection` and `prepareTextSelections` without
+arming the developer SDK, mounting UI or sending network requests. Production
+hosts such as Pitch own authentication, capture intent, target persistence and
+permission-scoped reads. Import this subpath directly; importing the root SDK
+still observes its existing production restrictions.
+
+Mark authored text containers with `data-annotation-text="host-field-path"`.
+Capture returns UTF-16 offsets, exact quote and bounded prefix/suffix using CRLF
+normalisation only. A field path is evidence qualified by a host content revision,
+not a permanent identity. Pass whether content is unchanged when resolving;
+edited content requires a unique quote/context match. Missing or ambiguous
+locations must remain reviewable as unplaced feedback. `prepareTextSelections`
+shares one bounded text-map snapshot across annotations in a layout frame; discard
+it after content or layout changes. Neither helper reads application controls as
+authored text or persists DOM nodes.

package/COMPATIBILITY.md

@@ -95,3 +95,18 @@ whoever drops it, in the same change, and not by whoever finds out.
 
 `0.x` while the wire protocol is still moving. **1.0 is the statement that a
 hundred consumers can rely on it**, not a way to look finished.
+
+### Additive selection subpath (A-391)
+
+The workspace adds `./selection` with ESM, CommonJS and TypeScript exports.
+Existing SDK wire versions and production arming rules are unchanged. Pitch uses
+the workspace source; external consumers need a subsequently published package
+version containing this entry point. The tarball smoke test verifies its exports;
+this feature does not itself publish an npm release.
+
+### Additive bootstrap subpath and hosted-mode metadata (A-1375)
+
+Version 0.6.0 adds `./bootstrap` for synchronous credential stripping,
+per-tab continuation and token-free startup status. It also adds the exact
+`x-weatherboard-annotation-mode: first-party` constants to `./protocol`. The
+wire payload version and all existing names remain unchanged.

package/README.md

@@ -20,23 +20,37 @@ adding to your supply chain.
 npm i @weatherboard/annotation
 ```
 
-## Six entry points
+## Eight entry points
 
 They are split by **who imports them**, not by topic.
 
 | Import | Runs where | For |
 |---|---|---|
 | `@weatherboard/annotation` | The browser | The page SDK — overlay, target resolution, state collection, screenshots |
+| `@weatherboard/annotation/bootstrap` | The browser, before hydration | Immediate URL stripping, arming reads and token-free startup status |
 | `@weatherboard/annotation/protocol` | Anywhere, no DOM | The wire names and the two readers. This is what a middleware imports |
 | `@weatherboard/annotation/host` | The reviewing console | The parent half of the channel |
 | `@weatherboard/annotation/anchor` | The browser | `resolveAnchor` — where a capture's marker goes, or why it goes nowhere |
 | `@weatherboard/annotation/read` | The browser | `createAnnotationReader` — the captures already made on this page |
 | `@weatherboard/annotation/markers` | The browser | The marker layer and its panel |
+| `@weatherboard/annotation/selection` | The browser | Authored-content text/point selection and placement helpers |
 
-The last three are separate for one reason: they run only in a product that
-RENDERS markers, and a product that merely captures should not pay for them. They
-are subpaths rather than a tree-shaking promise for the same reason `/protocol`
-is.
+The final four remain separate because products can choose capture, marker
+rendering and authored-content selection independently. A product that merely
+captures should not pay for readers, marker UI or selection helpers. They are
+subpaths rather than a tree-shaking promise for the same reason `/protocol` is.
+
+`/bootstrap` is also a subpath rather than a tree-shaking promise. Put
+`annotationBootstrapScript()` in the first raw script in `<head>`, then keep the
+root entry behind a dynamic import. A normal visitor pays for URL and cookie
+reads without downloading the toolbar or state collector.
+
+Package-authored browser UI keeps its styles zero-dependency too. Declare
+colour, spacing and radius literals once as local `--ai-*` custom properties,
+then consume them with `var()` in the same style string. Do not import a
+product's design tokens: a toolbar or startup notice runs inside somebody
+else's page, where those names and values are not ours. New runtime surfaces
+must pass `pnpm gyde:check`; do not add their findings to the allowance ledger.
 
 `/protocol` is a subpath rather than a tree-shaking promise on purpose: an edge
 middleware is often bundled as CJS, and CJS does not shake. Importing the root
@@ -63,11 +77,21 @@ right is yours, because only you hold the secret.
 
 ```ts
 // middleware.ts
-import { ANNOTATION_ARMED_COOKIE, readAnnotationToken } from "@weatherboard/annotation/protocol";
+import {
+  ANNOTATION_ARMED_COOKIE,
+  ANNOTATION_ARMED_COOKIES,
+  ANNOTATION_TOKEN_PARAMS,
+  readAnnotationToken,
+} from "@weatherboard/annotation/protocol";
 
 const token = readAnnotationToken(request.nextUrl.searchParams);
-if (token !== undefined && token === process.env.ANNOTATION_TOKEN) {
+const attempted = ANNOTATION_TOKEN_PARAMS.some((name) => request.nextUrl.searchParams.has(name));
+if (token !== null && token === process.env.ANNOTATION_TOKEN) {
   response.cookies.set(ANNOTATION_ARMED_COOKIE, "1", { httpOnly: false, sameSite: "lax" });
+} else if (attempted) {
+  for (const name of ANNOTATION_ARMED_COOKIES) {
+    response.cookies.set(name, "", { path: "/", maxAge: 0, expires: new Date(0) });
+  }
 }
 ```
 
@@ -75,7 +99,8 @@ if (token !== undefined && token === process.env.ANNOTATION_TOKEN) {
 for an absent *or empty* parameter. An empty token compared with `===` against
 your secret is a rejection; an empty token treated as present is an app armed
 with the empty string, which fails later and reads like a bad secret rather than
-a missing one.
+a missing one. A fresh rejected attempt must expire **both** supported cookie
+spellings so an already-armed browser cannot reuse its previous session.
 
 ## Source refs
 

package/dist/anchor.cjs

@@ -1,2 +1,2 @@
-"use strict";var f=Object.defineProperty;var x=Object.getOwnPropertyDescriptor;var E=Object.getOwnPropertyNames;var T=Object.prototype.hasOwnProperty;var R=(e,n)=>{for(var t in n)f(e,t,{get:n[t],enumerable:!0})},b=(e,n,t,o)=>{if(n&&typeof n=="object"||typeof n=="function")for(let r of E(n))!T.call(e,r)&&r!==t&&f(e,r,{get:()=>n[r],enumerable:!(o=x(n,r))||o.enumerable});return e};var y=e=>b(f({},"__esModule",{value:!0}),e);var L={};R(L,{anchorFromTarget:()=>S,resolveAnchor:()=>A,tallyAnchors:()=>_});module.exports=y(L);var u="data-src";function g(e){return e.selection==="region"?"region":"element"}var m=8;function s(e){if(!e)return null;let n=e.lastIndexOf(":");if(n<=0)return null;let t=e.lastIndexOf(":",n-1);if(t<=0)return null;let o=e.slice(0,t),r=Number(e.slice(t+1,n)),i=Number(e.slice(n+1));return!o||!Number.isFinite(r)||!Number.isFinite(i)?null:{file:o,line:r,column:i}}function d(e,n=m){let t=[],o=e;for(;o&&t.length<n;){let r=s(o.getAttribute(u));if(r){let i=t[t.length-1];i&&i.file===r.file&&i.line===r.line||t.push(r)}o=o.parentElement}return t}function h(e){let n=e;for(;n;){if(s(n.getAttribute(u)))return n;n=n.parentElement}return null}function l(e,n){return e.file!==n.file||e.line!==n.line?!1:e.column===void 0||n.column===void 0?!0:e.column===n.column}function k(e,n){if(e.length===0)return!1;if(e.length<m){if(n.length!==e.length)return!1}else if(n.length<e.length)return!1;return e.every((t,o)=>{let r=n[o];return r!==void 0&&l(t,r)})}function N(e,n){let t={file:e.file,line:e.line};e.column!==void 0&&(t.column=e.column);let o=n.querySelectorAll(`[${u}]`),r=[];for(let i=0;i<o.length;i++){let a=o[i],c=s(a.getAttribute(u));if(!c||!l(t,c))continue;let p=s(h(a.parentElement)?.getAttribute(u)??null);p&&l(p,c)||r.push(a)}return r}function A(e,n){switch(e.kind){case"route":{if(!e.path)return"none";let t=n.location?.pathname;return!t||t!==e.path?"none":n.body??"none"}case"dom-path":{if(!e.path)return"none";let t;try{t=n.querySelectorAll(e.path)}catch{return"none"}return t.length===0?"none":t.length>1?"ambiguous":t[0]}case"source-ref":{if(e.chain.length===0)return"none";let t=N(e,n).filter(o=>k(e.chain,d(o)));return t.length===0?"none":t.length>1?"ambiguous":t[0]}default:return"none"}}function S(e,n={}){let t=()=>n.path===void 0?{kind:"route"}:{kind:"route",path:n.path};if(g(e)==="region")return t();let o=e.sourceChain??[],r=o[0],i=e.source??r;if(i&&r&&l(i,r)){let a={kind:"source-ref",file:i.file,line:i.line,chain:o};return i.column!==void 0&&(a.column=i.column),n.ordinal!==void 0&&(a.ordinal=n.ordinal),a}return e.domPath?{kind:"dom-path",path:e.domPath}:t()}function _(e,n){let t={total:e.length,placed:0,ambiguous:0,unresolved:0};for(let o of e){let r=A(o,n);r==="ambiguous"?t.ambiguous+=1:r==="none"?t.unresolved+=1:t.placed+=1}return t}
+"use strict";var f=Object.defineProperty;var x=Object.getOwnPropertyDescriptor;var E=Object.getOwnPropertyNames;var T=Object.prototype.hasOwnProperty;var R=(e,n)=>{for(var t in n)f(e,t,{get:n[t],enumerable:!0})},b=(e,n,t,o)=>{if(n&&typeof n=="object"||typeof n=="function")for(let r of E(n))!T.call(e,r)&&r!==t&&f(e,r,{get:()=>n[r],enumerable:!(o=x(n,r))||o.enumerable});return e};var y=e=>b(f({},"__esModule",{value:!0}),e);var O={};R(O,{anchorFromTarget:()=>S,resolveAnchor:()=>A,tallyAnchors:()=>_});module.exports=y(O);var s="data-src";function g(e){return e.selection==="region"?"region":"element"}var m=8;function u(e){if(!e)return null;let n=e.lastIndexOf(":");if(n<=0)return null;let t=e.lastIndexOf(":",n-1);if(t<=0)return null;let o=e.slice(0,t),r=Number(e.slice(t+1,n)),i=Number(e.slice(n+1));return!o||!Number.isFinite(r)||!Number.isFinite(i)?null:{file:o,line:r,column:i}}function d(e,n=m){let t=[],o=e;for(;o&&t.length<n;){let r=u(o.getAttribute(s));if(r){let i=t[t.length-1];i&&i.file===r.file&&i.line===r.line||t.push(r)}o=o.parentElement}return t}function h(e){let n=e;for(;n;){if(u(n.getAttribute(s)))return n;n=n.parentElement}return null}function l(e,n){return e.file!==n.file||e.line!==n.line?!1:e.column===void 0||n.column===void 0?!0:e.column===n.column}function k(e,n){if(e.length===0)return!1;if(e.length<m){if(n.length!==e.length)return!1}else if(n.length<e.length)return!1;return e.every((t,o)=>{let r=n[o];return r!==void 0&&l(t,r)})}function N(e,n){let t={file:e.file,line:e.line};e.column!==void 0&&(t.column=e.column);let o=n.querySelectorAll(`[${s}]`),r=[];for(let i=0;i<o.length;i++){let a=o[i],c=u(a.getAttribute(s));if(!c||!l(t,c))continue;let p=u(h(a.parentElement)?.getAttribute(s)??null);p&&l(p,c)||r.push(a)}return r}function A(e,n){switch(e.kind){case"route":{if(!e.path)return"none";let t=n.location?.pathname;return!t||t!==e.path?"none":n.body??"none"}case"dom-path":{if(!e.path)return"none";let t;try{t=n.querySelectorAll(e.path)}catch{return"none"}return t.length===0?"none":t.length>1?"ambiguous":t[0]}case"source-ref":{if(e.chain.length===0)return"none";let t=N(e,n).filter(o=>k(e.chain,d(o)));return t.length===0?"none":t.length>1?"ambiguous":t[0]}default:return"none"}}function S(e,n={}){let t=()=>n.path===void 0?{kind:"route"}:{kind:"route",path:n.path};if(g(e)==="region")return t();let o=e.sourceChain??[],r=o[0],i=e.source??r;if(i&&r&&l(i,r)){let a={kind:"source-ref",file:i.file,line:i.line,chain:o};return i.column!==void 0&&(a.column=i.column),n.ordinal!==void 0&&(a.ordinal=n.ordinal),a}return e.domPath?{kind:"dom-path",path:e.domPath}:t()}function _(e,n){let t={total:e.length,placed:0,ambiguous:0,unresolved:0};for(let o of e){let r=A(o,n);r==="ambiguous"?t.ambiguous+=1:r==="none"?t.unresolved+=1:t.placed+=1}return t}
 //# sourceMappingURL=anchor.cjs.map