@weatherboard/annotation 0.2.0 → 0.2.2

package/dist/transport.d.cts

@@ -87,6 +87,52 @@ export interface SendReceipt {
  * outcome the receipt is already designed to survive.
  */
 export declare function safeIssueUrl(value: unknown): string | undefined;
+/**
+ * A refusal sentence from the network that is safe to put in front of a
+ * reviewer (A-285).
+ *
+ * `safeIssueUrl`'s argument, applied to prose. The ingest composes refusals a
+ * human can act on — a link issued for a different deployment, an empty
+ * comment — and until this slice the transport threw `HTTP 403` and discarded
+ * every one of them, so **not one of those sentences had ever reached a
+ * human.**
+ *
+ * The value is still untrusted, and it ends up as `textContent` in the
+ * CUSTOMER'S OWN PAGE. `textContent` is not an injection seam the way `href`
+ * is, so the risk here is not script execution — it is a hostile or broken
+ * ingest writing a screenful of control characters, ANSI escapes or a whole
+ * JSON document into a toast the reviewer cannot dismiss. So: strings only,
+ * control characters dropped, whitespace collapsed, and a hard ceiling.
+ *
+ * Anything that fails is dropped rather than repaired, and the caller falls
+ * back to the HTTP status — which is what every refusal rendered as before
+ * this existed, so the floor cannot get worse.
+ */
+export declare function safeRefusalReason(value: unknown): string | undefined;
+/**
+ * The error a refused capture throws, carrying the reason as a FIELD.
+ *
+ * The reason is in the `message` too, prefixed for a log. A renderer that had
+ * to recover it by string-slicing that message would be parsing our own prose,
+ * which breaks the first time somebody edits the prefix — so the sentence a
+ * human should see is a property, and `refusalReason` is the one way to read
+ * it.
+ */
+export interface IngestRefusal extends Error {
+    /** The ingest's own words, already through `safeRefusalReason`. */
+    reason?: string;
+    /** The status, always — it is the fallback and it is never absent. */
+    status?: number;
+}
+/**
+ * The reviewer-facing sentence for a failed capture, or `undefined`.
+ *
+ * SANITISED AGAIN, deliberately, exactly as `safeIssueUrl` is called at both
+ * ends: this reads an `EgressOutcome.error` from WHATEVER transport produced
+ * it, including one a consumer wrote, which never passed through
+ * `httpTransport`. One function, so the two ends cannot disagree.
+ */
+export declare function refusalReason(error: unknown): string | undefined;
 export interface AnnotationTransport {
     /** For diagnostics and for tests; never sent anywhere. */
     readonly name: string;

package/dist/transport.d.mts

@@ -87,6 +87,52 @@ export interface SendReceipt {
  * outcome the receipt is already designed to survive.
  */
 export declare function safeIssueUrl(value: unknown): string | undefined;
+/**
+ * A refusal sentence from the network that is safe to put in front of a
+ * reviewer (A-285).
+ *
+ * `safeIssueUrl`'s argument, applied to prose. The ingest composes refusals a
+ * human can act on — a link issued for a different deployment, an empty
+ * comment — and until this slice the transport threw `HTTP 403` and discarded
+ * every one of them, so **not one of those sentences had ever reached a
+ * human.**
+ *
+ * The value is still untrusted, and it ends up as `textContent` in the
+ * CUSTOMER'S OWN PAGE. `textContent` is not an injection seam the way `href`
+ * is, so the risk here is not script execution — it is a hostile or broken
+ * ingest writing a screenful of control characters, ANSI escapes or a whole
+ * JSON document into a toast the reviewer cannot dismiss. So: strings only,
+ * control characters dropped, whitespace collapsed, and a hard ceiling.
+ *
+ * Anything that fails is dropped rather than repaired, and the caller falls
+ * back to the HTTP status — which is what every refusal rendered as before
+ * this existed, so the floor cannot get worse.
+ */
+export declare function safeRefusalReason(value: unknown): string | undefined;
+/**
+ * The error a refused capture throws, carrying the reason as a FIELD.
+ *
+ * The reason is in the `message` too, prefixed for a log. A renderer that had
+ * to recover it by string-slicing that message would be parsing our own prose,
+ * which breaks the first time somebody edits the prefix — so the sentence a
+ * human should see is a property, and `refusalReason` is the one way to read
+ * it.
+ */
+export interface IngestRefusal extends Error {
+    /** The ingest's own words, already through `safeRefusalReason`. */
+    reason?: string;
+    /** The status, always — it is the fallback and it is never absent. */
+    status?: number;
+}
+/**
+ * The reviewer-facing sentence for a failed capture, or `undefined`.
+ *
+ * SANITISED AGAIN, deliberately, exactly as `safeIssueUrl` is called at both
+ * ends: this reads an `EgressOutcome.error` from WHATEVER transport produced
+ * it, including one a consumer wrote, which never passed through
+ * `httpTransport`. One function, so the two ends cannot disagree.
+ */
+export declare function refusalReason(error: unknown): string | undefined;
 export interface AnnotationTransport {
     /** For diagnostics and for tests; never sent anywhere. */
     readonly name: string;

package/dist/transport.d.ts

@@ -87,6 +87,52 @@ export interface SendReceipt {
  * outcome the receipt is already designed to survive.
  */
 export declare function safeIssueUrl(value: unknown): string | undefined;
+/**
+ * A refusal sentence from the network that is safe to put in front of a
+ * reviewer (A-285).
+ *
+ * `safeIssueUrl`'s argument, applied to prose. The ingest composes refusals a
+ * human can act on — a link issued for a different deployment, an empty
+ * comment — and until this slice the transport threw `HTTP 403` and discarded
+ * every one of them, so **not one of those sentences had ever reached a
+ * human.**
+ *
+ * The value is still untrusted, and it ends up as `textContent` in the
+ * CUSTOMER'S OWN PAGE. `textContent` is not an injection seam the way `href`
+ * is, so the risk here is not script execution — it is a hostile or broken
+ * ingest writing a screenful of control characters, ANSI escapes or a whole
+ * JSON document into a toast the reviewer cannot dismiss. So: strings only,
+ * control characters dropped, whitespace collapsed, and a hard ceiling.
+ *
+ * Anything that fails is dropped rather than repaired, and the caller falls
+ * back to the HTTP status — which is what every refusal rendered as before
+ * this existed, so the floor cannot get worse.
+ */
+export declare function safeRefusalReason(value: unknown): string | undefined;
+/**
+ * The error a refused capture throws, carrying the reason as a FIELD.
+ *
+ * The reason is in the `message` too, prefixed for a log. A renderer that had
+ * to recover it by string-slicing that message would be parsing our own prose,
+ * which breaks the first time somebody edits the prefix — so the sentence a
+ * human should see is a property, and `refusalReason` is the one way to read
+ * it.
+ */
+export interface IngestRefusal extends Error {
+    /** The ingest's own words, already through `safeRefusalReason`. */
+    reason?: string;
+    /** The status, always — it is the fallback and it is never absent. */
+    status?: number;
+}
+/**
+ * The reviewer-facing sentence for a failed capture, or `undefined`.
+ *
+ * SANITISED AGAIN, deliberately, exactly as `safeIssueUrl` is called at both
+ * ends: this reads an `EgressOutcome.error` from WHATEVER transport produced
+ * it, including one a consumer wrote, which never passed through
+ * `httpTransport`. One function, so the two ends cannot disagree.
+ */
+export declare function refusalReason(error: unknown): string | undefined;
 export interface AnnotationTransport {
     /** For diagnostics and for tests; never sent anywhere. */
     readonly name: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weatherboard/annotation",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Click an element in a running app, get the source location that rendered it.",
   "keywords": [
     "annotation",
@@ -67,10 +67,10 @@
     "LICENSE"
   ],
   "//sizeBudget": "Gzipped bytes per published entry point, checked by `build.mjs` on every build and therefore in CI. A budget is here rather than in a separate config because the number is part of the package's contract: this code runs on every page of every managed product, and 'it grew a bit each time' is how a 4KB SDK becomes a 40KB one with nobody having decided. Raising a number is allowed; doing it in the same commit as the growth, where a reviewer sees both, is the point.",
-  "//sizeBudget-index": "A-241 adds arming: 8700 -> 9400 for index and 700 -> 850 for protocol. MEASURED by rebuilding, four numbers. Baseline at A-240's merge commit fceb183: index 8562, protocol 646 - the two figures the previous note recorded, re-measured rather than trusted. As shipped: index 9281, protocol 788. And with the ./arming re-export block deleted from src/index.ts but everything else present: 8913. SO readArming AND ITS TYPES ARE 368 OF THE 719, AND 351 ARE NOT: 142 of that is protocol's own growth (armedCookie, clearedCookie, ANNOTATION_ARMED_VALUE, REVIEW_RUN_PARAM), which index pays too because it re-exports protocol whole, and the rest is isAnnotatableBuild with its ANNOTATABLE_ENVS allowlist, the two-gate expression in mountAnnotation, and Done's teardown. That 351 is the number worth knowing: a consumer who never calls readArming still pays it, because the kill-switch is not optional and must not be tree-shakeable. TWO REVIEW CYCLES MOVED IT AND BOTH COSTS ARE MEASURED: the fail-closed allowlist +27 (9239 -> 9266) and Done's teardown +15 (9266 -> 9281). HEADROOM IS PER ENTRY POINT AND THE TWO ARE STATED SEPARATELY, because one figure for both was false here once already: index 9400/9281 = 1.28%, against A-240's 8700/8562 = 1.61%, so tighter and DELIBERATELY NOT TOPPED UP - the budget's job is to make the next growth a decision, and quietly restoring slack each time is how it stops doing that; protocol 850/788 = 7.87%, against its previous 700/646 = 8.36%. protocol runs looser in PROPORTION only because it is small - 62 bytes is 7.87% there and would be 0.67% of index. The argument for the toolbar's own 2553 bytes is in docs/decisions/a-240-annotation-toolbar-size.md, extended there for this slice rather than restated here.",
+  "//sizeBudget-index": "A-241 adds arming: 8700 -> 9400 for index and 700 -> 850 for protocol. MEASURED by rebuilding, four numbers. Baseline at A-240's merge commit fceb183: index 8562, protocol 646 - the two figures the previous note recorded, re-measured rather than trusted. As shipped: index 9281, protocol 788. And with the ./arming re-export block deleted from src/index.ts but everything else present: 8913. SO readArming AND ITS TYPES ARE 368 OF THE 719, AND 351 ARE NOT: 142 of that is protocol's own growth (armedCookie, clearedCookie, ANNOTATION_ARMED_VALUE, REVIEW_RUN_PARAM), which index pays too because it re-exports protocol whole, and the rest is isAnnotatableBuild with its ANNOTATABLE_ENVS allowlist, the two-gate expression in mountAnnotation, and Done's teardown. That 351 is the number worth knowing: a consumer who never calls readArming still pays it, because the kill-switch is not optional and must not be tree-shakeable. TWO REVIEW CYCLES MOVED IT AND BOTH COSTS ARE MEASURED: the fail-closed allowlist +27 (9239 -> 9266) and Done's teardown +15 (9266 -> 9281). HEADROOM IS PER ENTRY POINT AND THE TWO ARE STATED SEPARATELY, because one figure for both was false here once already: index 9400/9281 = 1.28%, against A-240's 8700/8562 = 1.61%, so tighter and DELIBERATELY NOT TOPPED UP - the budget's job is to make the next growth a decision, and quietly restoring slack each time is how it stops doing that; protocol 850/788 = 7.87%, against its previous 700/646 = 8.36%. protocol runs looser in PROPORTION only because it is small - 62 bytes is 7.87% there and would be 0.67% of index. The argument for the toolbar's own 2553 bytes is in docs/decisions/a-240-annotation-toolbar-size.md, extended there for this slice rather than restated here. A-254 MOVED IT AGAIN AND THE BUDGET IS DELIBERATELY NOT RAISED: index 9281 -> 9300, +19 gzipped bytes for the armed-before-persist early return in readArming, re-measured by running build.mjs before and after. Headroom is now 9400/9300 = 1.06%. That is tight on purpose - 19 bytes bought the end of an unarmed page storing an attacker-supplied capture token, and the next growth after it should be a decision somebody makes rather than slack somebody spends. A-285 MOVED IT AGAIN AND THE BUDGET IS RAISED, WITH THE COST SPLIT AND MEASURED: index 9300 -> 9471, +171 gzipped bytes, by rebuilding three times. 9300 is the baseline at this branch point, re-measured rather than trusted. 9426 with transport.ts alone - safeRefusalReason, the IngestRefusal fields and the body read on the refusal branch, 126 bytes. 9471 with the toolbar rendering it and index re-exporting the two functions, a further 45. THAT 171 IS WHAT IT COSTS FOR A REFUSAL TO REACH A HUMAN AT ALL: before it, every sentence the ingest composed - the link issued for another deployment, the empty comment - was thrown away by the only client that could show it, and every failure read 'That did not send'. 9550 rather than 9500: 9500 would leave 29 bytes, which is a budget that fails on the next comment somebody writes rather than on the next decision somebody makes. 9550/9471 = 0.83%, against A-254's 9400/9300 = 1.06% - so still tighter than it was, and deliberately not topped up.",
   "sizeBudget": {
     "protocol": 850,
-    "index": 9400,
+    "index": 9550,
     "host": 660
   },
   "engines": {