@hybridlabor-api/aos 4.17.0 → 4.18.0

package/skills/global_config/plan-canvas/scripts/lib/plan-canvas/annotate-client/model.js

@@ -0,0 +1,192 @@
+'use strict';
+
+const { roundPoint, clampPoint, fromAnchorUnits, simplify } = require('./geometry');
+
+// Inlined into the browser bundle (see index.js): CAPS and the two regexes
+// are emitted as constants, the functions with fn.toString().
+const CAPS = {
+  maxItemsPerPost: 20,
+  maxBodyBytes: 200000,
+  maxShapes: 16,
+  maxPointsTotal: 2048,
+  maxFreehand: 512,
+  text: 4000,
+  snippet: 200,
+  selector: 500,
+  textRange: 1000,
+  classes: 12,
+  url: 300,
+  bbox: 100000
+};
+const SHAPE_COLORS = ['red', 'yellow', 'blue', 'green'];
+const POINT_RULES = { rect: [2, 2], arrow: [2, 2], blur: [2, 2], comment: [1, 1], freehand: [2, 512] };
+const STRIP_RE = /[\u0000-\u001f\u007f-\u009f​-‏‪-‮⁦-⁩]/g;
+const CLASS_RE = /^[A-Za-z0-9_-]{1,64}$/;
+const SRC_RE = /^[\w@.-]+(?:\/[\w@.-]+)*\.[A-Za-z0-9]{1,8}:\d{1,6}(?::\d{1,5})?$/;
+const TAG_RE = /^[a-z][a-z0-9-]{0,59}$/;
+
+function cleanText(value, max) {
+  if (typeof value !== 'string') return '';
+  return value.replace(STRIP_RE, '').slice(0, max);
+}
+
+function cleanClasses(list) {
+  const out = [];
+  if (!Array.isArray(list)) return out;
+  for (let i = 0; i < Math.min(list.length, 200) && out.length < CAPS.classes; i++) {
+    const c = list[i];
+    if (typeof c === 'string' && CLASS_RE.test(c) && !out.includes(c)) out.push(c);
+  }
+  return out;
+}
+
+function cleanSrcLoc(value) {
+  if (typeof value !== 'string' || value.length > 240 || !SRC_RE.test(value)) return null;
+  const file = value.slice(0, value.search(/:\d/));
+  return file.split('/').some(s => s.startsWith('.') || s === 'node_modules') ? null : value;
+}
+
+function makeShape(type, points, color) {
+  const rule = POINT_RULES[Object.prototype.hasOwnProperty.call(POINT_RULES, type) ? type : ''];
+  if (!rule || !Array.isArray(points)) return null;
+  if (!points.every(p => Array.isArray(p) && Number.isFinite(p[0]) && Number.isFinite(p[1]))) return null;
+  const pts = (type === 'freehand' ? simplify(points, 0.002, CAPS.maxFreehand) : points)
+    .map(p => roundPoint(clampPoint(p)));
+  if (pts.length < rule[0] || pts.length > rule[1]) return null;
+  const shape = { type, points: pts };
+  if (SHAPE_COLORS.includes(color)) shape.color = color;
+  return shape;
+}
+
+function createDraft() {
+  return { shapes: [], redo: [] };
+}
+
+function draftPointCount(draft) {
+  return draft.shapes.reduce((n, s) => n + s.points.length, 0);
+}
+
+// Returns '' when added, otherwise the reason it was refused.
+function draftAdd(draft, shape) {
+  if (!shape) return 'invalid';
+  if (draft.shapes.length >= CAPS.maxShapes) return 'max-shapes';
+  if (draftPointCount(draft) + shape.points.length > CAPS.maxPointsTotal) return 'max-points';
+  draft.shapes.push(shape);
+  draft.redo.length = 0;
+  return '';
+}
+
+function draftUndo(draft) {
+  const s = draft.shapes.pop();
+  if (s) draft.redo.push(s);
+  return Boolean(s);
+}
+
+function draftRedo(draft) {
+  const s = draft.redo.pop();
+  if (s) draft.shapes.push(s);
+  return Boolean(s);
+}
+
+function draftClear(draft) {
+  draft.shapes.length = 0;
+  draft.redo.length = 0;
+}
+
+function shapeSummary(shapes) {
+  return Array.isArray(shapes) ? shapes.map(s => s.type).join(', ') : '';
+}
+
+function pageBBox(shapes, box) {
+  const xs = [];
+  const ys = [];
+  for (const s of shapes) for (const p of s.points) {
+    const pt = fromAnchorUnits(p, box);
+    xs.push(pt[0]);
+    ys.push(pt[1]);
+  }
+  if (!xs.length) return null;
+  const c = v => Math.round(Math.min(CAPS.bbox, Math.max(0, v)));
+  const x = c(Math.min(...xs));
+  const y = c(Math.min(...ys));
+  return { x, y, w: c(Math.max(...xs)) - x, h: c(Math.max(...ys)) - y };
+}
+
+function buildItem(input) {
+  const text = cleanText(input.text, CAPS.text).trim();
+  if (!text || !input.anchor) return null;
+  const shapes = (input.shapes || []).slice(0, CAPS.maxShapes);
+  const blurred = shapes.some(s => s.type === 'blur');
+  const a = input.anchor;
+  const tag = a.tag === 'text' || TAG_RE.test(a.tag || '') ? a.tag : 'div';
+  const anchor = {
+    selector: cleanText(a.selector, CAPS.selector) || 'body',
+    tag,
+    snippet: blurred ? '' : cleanText(a.snippet, CAPS.snippet)
+  };
+  const classes = cleanClasses(a.classes);
+  if (classes.length) anchor.classes = classes;
+  if (a.textRange && !blurred) {
+    const t = cleanText(a.textRange.text, CAPS.textRange);
+    if (t) anchor.textRange = { text: t };
+  }
+  const item = { kind: 'annotation', text, anchor };
+  let points = 0;
+  const kept = [];
+  for (const s of shapes) {
+    if (points + s.points.length > CAPS.maxPointsTotal) break;
+    points += s.points.length;
+    const out = { type: s.type, points: s.points.map(p => [p[0], p[1]]) };
+    if (SHAPE_COLORS.includes(s.color)) out.color = s.color;
+    kept.push(out);
+  }
+  if (kept.length) item.shapes = kept;
+  const v = input.viewport;
+  if (v && Number.isFinite(v.w) && Number.isFinite(v.h)) {
+    const int = n => Math.min(100000, Math.max(1, Math.round(n)));
+    const dpr = Number.isFinite(v.dpr) ? Math.min(8, Math.max(0.5, v.dpr)) : 1;
+    item.viewport = { w: int(v.w), h: int(v.h), dpr: Math.round(dpr * 100) / 100 };
+  }
+  if (input.box) {
+    const b = input.box;
+    const c = n => (Number.isFinite(n) ? Math.round(Math.min(CAPS.bbox, Math.max(0, n))) : 0);
+    const page = kept.length ? pageBBox(kept, b) : { x: c(b.left), y: c(b.top), w: c(b.width), h: c(b.height) };
+    if (page) item.page = page;
+  }
+  if (input.target) {
+    const target = { url: cleanText(input.target.url, CAPS.url) };
+    const src = cleanSrcLoc(input.target.srcLoc);
+    if (src) target.srcLoc = src;
+    item.target = target;
+  }
+  return item;
+}
+
+function chunkItems(items) {
+  const chunks = [];
+  let cur = [];
+  let bytes = 0;
+  for (const item of items) {
+    const size = JSON.stringify(item).length;
+    if (cur.length && (cur.length >= CAPS.maxItemsPerPost || bytes + size > CAPS.maxBodyBytes)) {
+      chunks.push(cur);
+      cur = [];
+      bytes = 0;
+    }
+    cur.push(item);
+    bytes += size;
+  }
+  if (cur.length) chunks.push(cur);
+  return chunks;
+}
+
+const PURE_FUNCTIONS = [
+  cleanText, cleanClasses, cleanSrcLoc, makeShape, createDraft, draftPointCount, draftAdd, draftUndo,
+  draftRedo, draftClear, shapeSummary, pageBBox, buildItem, chunkItems
+];
+
+module.exports = {
+  CAPS, SHAPE_COLORS, POINT_RULES, STRIP_RE, CLASS_RE, SRC_RE, TAG_RE, PURE_FUNCTIONS,
+  cleanText, cleanClasses, cleanSrcLoc, makeShape, createDraft, draftPointCount, draftAdd, draftUndo,
+  draftRedo, draftClear, shapeSummary, pageBBox, buildItem, chunkItems
+};

package/skills/global_config/plan-canvas/scripts/lib/plan-canvas/annotate-client/toolbar.js

@@ -0,0 +1,99 @@
+'use strict';
+
+// Static markup only: nothing here is ever interpolated with page or user data.
+
+const TOOLS = [
+  ['element', 'V', 'Element'],
+  ['text', 'T', 'Text'],
+  ['rect', 'R', 'Area'],
+  ['arrow', 'A', 'Arrow'],
+  ['freehand', 'F', 'Freehand'],
+  ['blur', 'B', 'Blur'],
+  ['comment', 'C', 'Comment']
+];
+const COLORS = ['red', 'yellow', 'blue', 'green'];
+const STROKES = [['2', 'Thin'], ['4', 'Medium'], ['7', 'Thick']];
+
+function toolbarCss() {
+  return `
+:host{all:initial;--bg:#0a0a0a;--fg:#fff;--mut:#a1a1aa;--line:#2a2a30;--acc:#9b30c4;--acc-fg:#fff;--sh:0 8px 32px rgba(0,0,0,.55)}
+@media (prefers-color-scheme:light){:host{--bg:#fff;--fg:#0a0a0a;--mut:#52525b;--line:#d4d4d8;--sh:0 8px 32px rgba(0,0,0,.18)}}
+*{box-sizing:border-box;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif}
+.hl{position:fixed;pointer-events:none;border:1.5px solid var(--acc);background:rgba(155,48,196,.12);border-radius:4px;display:none;z-index:2147483646;transition:all .06s ease-out}
+svg.ov{position:absolute;left:0;top:0;overflow:visible;pointer-events:none;z-index:2147483645}
+svg.ov.draw{pointer-events:auto;cursor:crosshair;touch-action:none}
+button{font-size:12px;font-weight:600;line-height:1;cursor:pointer;color:var(--fg);background:transparent;border:1px solid var(--line);border-radius:6px;min-width:32px;min-height:32px;padding:6px 8px}
+button:hover{border-color:var(--acc)}
+button:focus-visible,textarea:focus-visible{outline:2px solid var(--acc);outline-offset:2px}
+button[aria-pressed=true],button.primary{background:var(--acc);border-color:var(--acc);color:var(--acc-fg)}
+button:disabled{opacity:.4;cursor:default}
+.bar{position:fixed;left:50%;bottom:12px;transform:translateX(-50%);z-index:2147483647;display:flex;flex-wrap:wrap;gap:6px;align-items:center;justify-content:center;max-width:calc(100vw - 16px);background:var(--bg);color:var(--fg);border:1px solid var(--line);border-radius:10px;padding:6px;box-shadow:var(--sh)}
+.bar[hidden],.launch[hidden],.card[hidden],.mini[hidden]{display:none}
+.grp{display:flex;gap:4px;align-items:center}
+.sep{width:1px;align-self:stretch;background:var(--line)}
+.sw{min-width:24px;min-height:24px;width:24px;height:24px;padding:0;border-radius:50%}
+.sw[data-color=red]{background:#e5484d}.sw[data-color=yellow]{background:#f5c518}.sw[data-color=blue]{background:#3b82f6}.sw[data-color=green]{background:#30a46c}
+.sw[aria-pressed=true]{outline:2px solid var(--fg);outline-offset:2px;border-color:transparent}
+.launch{position:fixed;right:12px;bottom:12px;z-index:2147483647;background:var(--bg);box-shadow:var(--sh)}
+.status{flex-basis:100%;text-align:center;font-size:11px;color:var(--mut);min-height:14px}
+.selhint{position:absolute;display:none;z-index:2147483647;background:var(--bg);box-shadow:var(--sh)}
+.card{position:absolute;z-index:2147483647;width:min(300px,calc(100vw - 16px));background:var(--bg);color:var(--fg);border:1px solid var(--line);border-radius:8px;box-shadow:var(--sh)}
+.card h4{margin:0;padding:10px 12px 0;font-size:11px;font-weight:600;text-transform:uppercase;letter-spacing:.05em;color:var(--mut)}
+.card .snippet{padding:4px 12px 0;font:10.5px 'SF Mono','Fira Code',monospace;color:var(--acc);white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+.card textarea{display:block;width:calc(100% - 24px);margin:8px 12px;min-height:56px;resize:vertical;background:transparent;border:1px solid var(--line);border-radius:6px;color:var(--fg);font-size:16px;line-height:1.4;padding:7px 9px}
+.card .row{display:flex;justify-content:flex-end;gap:8px;padding:0 12px 8px}
+.card .keys{padding:0 12px 10px;font-size:10px;color:var(--mut)}
+.mini{position:fixed;right:12px;bottom:64px;z-index:2147483647;width:min(280px,calc(100vw - 24px));background:var(--bg);color:var(--fg);border:1px solid var(--line);border-radius:8px;box-shadow:var(--sh);padding:8px;font-size:12px}
+.mini ul{list-style:none;margin:0 0 8px;padding:0;max-height:140px;overflow:auto}
+.mini li{display:flex;gap:6px;align-items:center;padding:3px 0}
+.mini li span{flex:1;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.mini .msg{margin-top:6px;font-size:11px;color:var(--mut)}
+@media (prefers-reduced-motion:reduce){*{transition:none!important;animation:none!important}}
+`;
+}
+
+function toolbarHtml() {
+  const tool = ([id, key, label]) =>
+    `<button type="button" data-tool="${id}" aria-pressed="false" aria-keyshortcuts="${key}" aria-label="${label} tool (${key})" title="${label} (${key})">${key}</button>`;
+  const color = c =>
+    `<button type="button" class="sw" data-color="${c}" aria-pressed="false" aria-label="Colour ${c}" title="${c}"></button>`;
+  const stroke = ([w, label]) =>
+    `<button type="button" data-stroke="${w}" aria-pressed="false" aria-label="${label} stroke" title="${label}">${w}</button>`;
+  return `
+<svg class="ov" aria-hidden="true"></svg>
+<div class="hl"></div>
+<button class="selhint" type="button">Annotate selection</button>
+<button class="launch" type="button" aria-label="Annotate this page (Alt+Shift+A)" title="Annotate (Alt+Shift+A)" hidden>Annotate</button>
+<div class="bar" role="toolbar" aria-label="Annotation tools" aria-orientation="horizontal" hidden>
+  <div class="grp" role="group" aria-label="Tools">${TOOLS.map(tool).join('')}</div>
+  <span class="sep"></span>
+  <div class="grp" role="group" aria-label="Colour">${COLORS.map(color).join('')}</div>
+  <div class="grp" role="group" aria-label="Stroke">${STROKES.map(stroke).join('')}</div>
+  <span class="sep"></span>
+  <div class="grp" role="group" aria-label="Edit">
+    <button type="button" data-act="undo" aria-label="Undo (Ctrl or Cmd+Z)" title="Undo">&#8630;</button>
+    <button type="button" data-act="redo" aria-label="Redo (Ctrl or Cmd+Shift+Z)" title="Redo">&#8631;</button>
+    <button type="button" data-act="delete" aria-label="Delete drawing (Delete)" title="Delete">&#10005;</button>
+    <button type="button" data-act="close" aria-label="Close annotation tools (Esc)" title="Close">Esc</button>
+  </div>
+  <div class="status" role="status" aria-live="polite"></div>
+</div>
+<div class="card" role="dialog" aria-label="Annotation note" hidden>
+  <h4></h4>
+  <div class="snippet"></div>
+  <textarea aria-label="What should change here?" placeholder="What should change here?"></textarea>
+  <div class="row">
+    <button type="button" data-act="cancel">Cancel</button>
+    <button type="button" data-act="queue" class="primary">Queue</button>
+  </div>
+  <div class="keys">Enter to queue &middot; Cmd/Ctrl+Enter to queue &amp; send &middot; Esc to cancel</div>
+</div>
+<div class="mini" role="region" aria-label="Queued annotations" hidden>
+  <ul></ul>
+  <button type="button" data-act="send" class="primary">Send</button>
+  <div class="msg" role="status" aria-live="polite"></div>
+</div>
+`;
+}
+
+module.exports = { toolbarCss, toolbarHtml, TOOLS, COLORS, STROKES };

package/skills/global_config/plan-canvas/scripts/lib/plan-canvas/annotate-server.js

@@ -0,0 +1,282 @@
+'use strict';
+
+/**
+ * Annotation endpoint for a running dev app (the "annotate" half of Plan
+ * Canvas). server.js hands requests for `/annotate.js` and `/api/annotate/*`
+ * here after the Host check and before the Origin/fetch-site gate, because the
+ * caller is a page on a different loopback origin by design.
+ *
+ * Trust model: a per-session token (only its SHA-256 is stored) bound to one
+ * exact loopback app origin. The endpoint can queue `kind:"annotation"` items
+ * and nothing else, so an app page can never approve, chat or end a session.
+ */
+
+const crypto = require('crypto');
+
+const { normalizeOrigin } = require('./annotation-schema');
+
+const KEY_RE = /^[a-f0-9]{12}$/;
+const ROUTE_RE = /^\/api\/annotate\/([a-f0-9]{12})(\/token)?$/;
+const MAX_BODY_BYTES = 256 * 1024;
+const MAX_TOKEN_BODY_BYTES = 4 * 1024;
+const MAX_ITEMS_PER_POST = 20;
+const MAX_PENDING = 200;
+const RATE_PER_MINUTE = 60;
+const DEFAULT_TTL_MS = 8 * 60 * 60 * 1000;
+const MAX_TTL_MS = 24 * 60 * 60 * 1000;
+const MIN_TTL_MS = 1000;
+const MAX_TOKEN_HEADER = 200;
+const SERVER_HOST = '127.0.0.1';
+
+const STUB_CLIENT_JS =
+  "'use strict';\n(() => { try { console.warn('[aos-annotate] client layer not installed in this build'); } catch (_) {} })();\n";
+
+function sha256(value) {
+  return crypto.createHash('sha256').update(value).digest();
+}
+
+function loadClientJs(version) {
+  let mod;
+  try {
+    mod = require('./annotate-client');
+  } catch (error) {
+    if (error && error.code === 'MODULE_NOT_FOUND') return STUB_CLIENT_JS;
+    throw error;
+  }
+  return mod.annotateClientJs({ transport: 'fetch', version });
+}
+
+function sendJson(res, status, payload, extraHeaders = {}) {
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+    'x-content-type-options': 'nosniff',
+    ...extraHeaders
+  });
+  res.end(JSON.stringify(payload));
+}
+
+class HttpError extends Error {
+  constructor(status, code, message, headers) {
+    super(message || code);
+    this.status = status;
+    this.code = code;
+    this.headers = headers;
+  }
+}
+
+// Stops reading at the cap; the caller answers 413 and drops the socket.
+function readBody(req, maxBytes) {
+  return new Promise((resolve, reject) => {
+    const declared = Number(req.headers['content-length']);
+    if (Number.isFinite(declared) && declared > maxBytes) {
+      return reject(new HttpError(413, 'too_large', 'body too large', { connection: 'close' }));
+    }
+    let size = 0;
+    const chunks = [];
+    req.on('data', chunk => {
+      size += chunk.length;
+      if (size > maxBytes) {
+        chunks.length = 0;
+        reject(new HttpError(413, 'too_large', 'body too large', { connection: 'close' }));
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+    req.on('error', reject);
+    return undefined;
+  });
+}
+
+function parseJsonObject(text) {
+  if (!text) return {};
+  try {
+    const value = JSON.parse(text);
+    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function isJsonContentType(value) {
+  return typeof value === 'string' && /^application\/json\s*(;|$)/i.test(value.trim());
+}
+
+function createAnnotateHandler({ store, version = '0.0.0', onQueued = () => {}, now = Date.now, log = () => {} } = {}) {
+  if (!store) throw new Error('createAnnotateHandler requires a session store');
+  const buckets = new Map(); // key -> { tokens, at }
+
+  function takeRate(key) {
+    const t = now();
+    const bucket = buckets.get(key) || { tokens: RATE_PER_MINUTE, at: t };
+    bucket.tokens = Math.min(RATE_PER_MINUTE, bucket.tokens + Math.max(0, t - bucket.at) * (RATE_PER_MINUTE / 60000));
+    bucket.at = t;
+    buckets.set(key, bucket);
+    if (bucket.tokens < 1) return Math.max(1, Math.ceil((1 - bucket.tokens) / (RATE_PER_MINUTE / 60)));
+    bucket.tokens -= 1;
+    return 0;
+  }
+
+  function corsHeaders(origin, { preflight = false, privateNetwork = false } = {}) {
+    const headers = { 'access-control-allow-origin': origin, vary: 'Origin' };
+    if (preflight) {
+      headers['access-control-allow-methods'] = 'POST';
+      headers['access-control-allow-headers'] = 'content-type, x-aos-annotate-token';
+      headers['access-control-max-age'] = '600';
+      if (privateNetwork) headers['access-control-allow-private-network'] = 'true';
+    }
+    return headers;
+  }
+
+  function issueToken(key, origin, ttlMs = DEFAULT_TTL_MS) {
+    const bound = normalizeOrigin(origin);
+    if (!bound) throw new HttpError(400, 'bad_origin', 'origin must be http://127.0.0.1|localhost|[::1]:<1024-65535>');
+    const session = store.get(key);
+    if (!session) throw new HttpError(404, 'unknown_session', 'unknown session');
+    if (session.status === 'ended') throw new HttpError(409, 'ended', 'session already ended');
+    const token = crypto.randomBytes(32).toString('base64url');
+    const createdAt = now();
+    const expiresAt = createdAt + Math.min(MAX_TTL_MS, Math.max(MIN_TTL_MS, ttlMs));
+    store.setAnnotateToken(key, { tokenSha256: sha256(token).toString('hex'), origin: bound, createdAt, expiresAt });
+    buckets.delete(key);
+    return { token, origin: bound, expiresAt };
+  }
+
+  function serveScript(req, res) {
+    if (req.method !== 'GET') return sendJson(res, 405, { error: 'method not allowed', code: 'method' }, { allow: 'GET' });
+    res.writeHead(200, {
+      'content-type': 'text/javascript; charset=utf-8',
+      'cache-control': 'no-cache',
+      'x-content-type-options': 'nosniff',
+      'cross-origin-resource-policy': 'cross-origin',
+      'x-aos-annotate-version': version
+    });
+    return res.end(loadClientJs(version));
+  }
+
+  async function handleToken(req, res, key) {
+    if (req.method !== 'POST') throw new HttpError(405, 'method', 'method not allowed', { allow: 'POST' });
+    // Browsers always send Origin or Sec-Fetch-Site; only the CLI sends neither.
+    if (req.headers.origin !== undefined || req.headers['sec-fetch-site'] !== undefined) {
+      throw new HttpError(403, 'browser_forbidden', 'token issuing is CLI-only');
+    }
+    const body = parseJsonObject(await readBody(req, MAX_TOKEN_BODY_BYTES));
+    if (!body) throw new HttpError(400, 'json', 'invalid JSON body');
+    let ttlMs = DEFAULT_TTL_MS;
+    if (body.ttlMs !== undefined) {
+      if (typeof body.ttlMs !== 'number' || !Number.isFinite(body.ttlMs) || body.ttlMs < MIN_TTL_MS) {
+        throw new HttpError(400, 'bad_ttl', 'ttlMs must be a number of at least 1000');
+      }
+      ttlMs = body.ttlMs;
+    }
+    const issued = issueToken(key, body.origin, ttlMs);
+    const base = `http://${SERVER_HOST}:${req.socket.localPort}`;
+    const src = `${base}/annotate.js?v=${encodeURIComponent(version)}`;
+    const scriptTag = `<script src="${src}" data-session="${key}" data-token="${issued.token}"></script>`;
+    const bookmarklet =
+      `javascript:(function(){var s=document.createElement('script');s.src='${src}';` +
+      `s.setAttribute('data-session','${key}');s.setAttribute('data-token','${issued.token}');` +
+      `document.documentElement.appendChild(s)})()`;
+    return sendJson(res, 200, {
+      token: issued.token,
+      origin: issued.origin,
+      expiresAt: new Date(issued.expiresAt).toISOString(),
+      scriptTag,
+      bookmarklet
+    });
+  }
+
+  function handlePreflight(req, res, key) {
+    const record = store.getAnnotateToken(key);
+    const origin = req.headers.origin;
+    // An expired token still gets the preflight so the POST can answer 401 token_expired readably.
+    if (!record || typeof origin !== 'string' || origin !== record.origin) {
+      res.writeHead(403, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+      return res.end(JSON.stringify({ error: 'forbidden', code: 'origin' }));
+    }
+    const privateNetwork = req.headers['access-control-request-private-network'] === 'true';
+    res.writeHead(204, corsHeaders(origin, { preflight: true, privateNetwork }));
+    return res.end();
+  }
+
+  async function handlePost(req, res, key) {
+    const session = store.get(key);
+    if (!session) throw new HttpError(404, 'unknown_session', 'unknown session');
+    const record = store.getAnnotateToken(key);
+    // The bound origin may read every answer (including 401 token errors) so the
+    // page can show "link expired"; any other origin gets no CORS headers at all.
+    const cors = record && req.headers.origin === record.origin ? corsHeaders(record.origin) : {};
+    try {
+      const header = req.headers['x-aos-annotate-token'];
+      if (typeof header !== 'string' || header.length === 0) throw new HttpError(401, 'no_token', 'token required');
+      // No record means no bound origin to compare, so this stays 401 rather than 403.
+      if (!record) throw new HttpError(401, 'token', 'invalid token');
+      if (now() >= record.expiresAt) throw new HttpError(401, 'token_expired', 'token expired');
+      if (req.headers.origin !== record.origin) throw new HttpError(403, 'origin', 'origin not allowed');
+      if (header.length > MAX_TOKEN_HEADER) throw new HttpError(401, 'token', 'invalid token');
+      const expected = Buffer.from(String(record.tokenSha256), 'hex');
+      const presented = sha256(header);
+      if (expected.length !== presented.length || !crypto.timingSafeEqual(expected, presented)) {
+        throw new HttpError(401, 'token', 'invalid token');
+      }
+      const retryAfter = takeRate(key);
+      if (retryAfter) throw new HttpError(429, 'rate', 'too many requests', { 'retry-after': String(retryAfter) });
+      if (!isJsonContentType(req.headers['content-type'])) {
+        throw new HttpError(415, 'content_type', 'content-type must be application/json');
+      }
+      const body = parseJsonObject(await readBody(req, MAX_BODY_BYTES));
+      if (!body) throw new HttpError(400, 'json', 'invalid JSON body');
+      const items = Object.hasOwn(body, 'items') ? body.items : undefined;
+      if (!Array.isArray(items) || items.length < 1 || items.length > MAX_ITEMS_PER_POST) {
+        throw new HttpError(400, 'items', `items must be an array of 1-${MAX_ITEMS_PER_POST}`);
+      }
+      if (session.status === 'ended') throw new HttpError(409, 'ended', 'session already ended');
+      if (session.pendingFeedback.length + items.length > MAX_PENDING) {
+        throw new HttpError(429, 'queue_full', 'too many pending annotations; the agent has not picked them up');
+      }
+      const result = store.queueFeedback(key, items, { origin: 'app', boundOrigin: record.origin });
+      if (!result) throw new HttpError(409, 'ended', 'session already ended');
+      onQueued(key);
+      return sendJson(
+        res,
+        200,
+        { status: 'queued', accepted: result.accepted.length, rejected: result.rejected, pending: result.pending },
+        cors
+      );
+    } catch (error) {
+      if (error instanceof HttpError) error.headers = { ...cors, ...error.headers };
+      throw error;
+    }
+  }
+
+  function handles(pathname) {
+    return pathname === '/annotate.js' || (typeof pathname === 'string' && pathname.startsWith('/api/annotate/'));
+  }
+
+  async function handle(req, res, url) {
+    try {
+      if (url.pathname === '/annotate.js') return serveScript(req, res);
+      const match = ROUTE_RE.exec(url.pathname);
+      if (!match || !KEY_RE.test(match[1])) throw new HttpError(404, 'not_found', 'not found');
+      const [, key, tokenSuffix] = match;
+      if (tokenSuffix) return await handleToken(req, res, key);
+      if (req.method === 'OPTIONS') return handlePreflight(req, res, key);
+      if (req.method === 'POST') return await handlePost(req, res, key);
+      throw new HttpError(405, 'method', 'method not allowed', { allow: 'POST, OPTIONS' });
+    } catch (error) {
+      if (res.headersSent) return res.end();
+      if (error instanceof HttpError) {
+        sendJson(res, error.status, { error: error.message, code: error.code }, error.headers);
+        if (error.status === 413) res.once('finish', () => req.destroy());
+        return undefined;
+      }
+      log(`[plan-canvas] annotate error: ${error && error.message}`);
+      return sendJson(res, 500, { error: 'internal error', code: 'internal' });
+    }
+  }
+
+  return { handles, handle, issueToken };
+}
+
+module.exports = { MAX_BODY_BYTES, MAX_ITEMS_PER_POST, MAX_PENDING, RATE_PER_MINUTE, createAnnotateHandler };