@medeo-plugin/plugin-screenshot 1.0.0 → 1.0.1

package/src/resources/helper.js

@@ -0,0 +1,99 @@
+// The plugin's window onto AppKit, run with `osascript -l JavaScript` (always present, no Xcode).
+//   screen              → the display under the pointer and the windows on it, front to back
+//   copy <png>          → put a PNG (plus TIFF for older apps) on the general pasteboard
+//   copy-text <file>    → put the UTF-8 text in <file> on the pasteboard
+//   ocr <png>           → text lines (Vision, all languages) and QR/barcode payloads as JSON
+//   choose-folder <prompt> <start>  → a folder chosen by the user, or "" when cancelled
+// Coordinates are top-left global points, the ones `screencapture -R` and Electron use.
+ObjC.import('AppKit');
+ObjC.import('CoreGraphics');
+ObjC.import('Vision');
+
+function screen() {
+  const m = $.NSEvent.mouseLocation, screens = $.NSScreen.screens;
+  const mainH = screens.objectAtIndex(0).frame.size.height;
+  let display = null;
+  for (let i = 0; i < screens.count; i++) {
+    const s = screens.objectAtIndex(i), f = s.frame;
+    const d = { x: f.origin.x, y: mainH - (f.origin.y + f.size.height), width: f.size.width, height: f.size.height, scale: s.backingScaleFactor };
+    if (!display) display = d;
+    if (m.x >= f.origin.x && m.x <= f.origin.x + f.size.width && m.y >= f.origin.y && m.y <= f.origin.y + f.size.height) { display = d; break; }
+  }
+  const raw = $.CGWindowListCopyWindowInfo($.kCGWindowListOptionOnScreenOnly | $.kCGWindowListExcludeDesktopElements, 0);
+  const list = ObjC.deepUnwrap(ObjC.castRefToObject(raw)) || [];
+  const windows = [];
+  for (const w of list) {
+    const b = w.kCGWindowBounds;
+    if (!b || w.kCGWindowLayer !== 0 || w.kCGWindowAlpha === 0 || b.Width < 24 || b.Height < 24) continue;
+    const x = Math.max(b.X, display.x), y = Math.max(b.Y, display.y);
+    const r = Math.min(b.X + b.Width, display.x + display.width), btm = Math.min(b.Y + b.Height, display.y + display.height);
+    if (r - x < 24 || btm - y < 24) continue;
+    windows.push({ x: x - display.x, y: y - display.y, w: r - x, h: btm - y });
+  }
+  return JSON.stringify({ display, windows: windows.slice(0, 200) });
+}
+
+function copy(file) {
+  const data = $.NSData.dataWithContentsOfFile(file);
+  if (data.isNil()) return 'missing';
+  const pb = $.NSPasteboard.generalPasteboard;
+  pb.clearContents;
+  pb.declareTypesOwner($(['public.png', 'public.tiff']), $());
+  pb.setDataForType(data, 'public.png');
+  const rep = $.NSBitmapImageRep.imageRepWithData(data);
+  if (!rep.isNil()) pb.setDataForType(rep.TIFFRepresentation, 'public.tiff');
+  return 'ok';
+}
+
+function copyText(file) {
+  const text = $.NSString.stringWithContentsOfFileEncodingError(file, $.NSUTF8StringEncoding, $());
+  if (text.isNil()) return 'missing';
+  const pb = $.NSPasteboard.generalPasteboard;
+  pb.clearContents;
+  pb.setStringForType(text, 'public.utf8-plain-text');
+  return 'ok';
+}
+
+function ocr(file) {
+  const handler = $.VNImageRequestHandler.alloc.initWithURLOptions($.NSURL.fileURLWithPath(file), $());
+  const text = $.VNRecognizeTextRequest.alloc.init;
+  text.recognitionLevel = 0; // accurate
+  text.usesLanguageCorrection = true;
+  if (text.respondsToSelector('setAutomaticallyDetectsLanguage:')) text.automaticallyDetectsLanguage = true;
+  const codes = $.VNDetectBarcodesRequest.alloc.init;
+  handler.performRequestsError($([text, codes]), $());
+  const lines = [], payloads = [];
+  const found = text.results;
+  if (!found.isNil()) for (let i = 0; i < found.count; i++) {
+    const o = found.objectAtIndex(i), top = o.topCandidates(1);
+    if (top.count === 0) continue;
+    const b = o.boundingBox;
+    lines.push({ t: top.objectAtIndex(0).string.js, x: b.origin.x, y: b.origin.y, h: b.size.height });
+  }
+  const bars = codes.results;
+  if (!bars.isNil()) for (let i = 0; i < bars.count; i++) {
+    const v = bars.objectAtIndex(i).payloadStringValue;
+    if (!v.isNil() && !payloads.includes(v.js)) payloads.push(v.js);
+  }
+  return JSON.stringify({ lines, codes: payloads });
+}
+
+function chooseFolder(prompt, start) {
+  const app = Application.currentApplication();
+  app.includeStandardAdditions = true;
+  app.activate();
+  try {
+    const options = { withPrompt: prompt };
+    if (start && $.NSFileManager.defaultManager.fileExistsAtPath(start)) options.defaultLocation = Path(start);
+    return app.chooseFolder(options).toString();
+  } catch (e) { return ''; }
+}
+
+function run(argv) {
+  if (argv[0] === 'screen') return screen();
+  if (argv[0] === 'copy') return copy(argv[1]);
+  if (argv[0] === 'copy-text') return copyText(argv[1]);
+  if (argv[0] === 'ocr') return ocr(argv[1]);
+  if (argv[0] === 'choose-folder') return chooseFolder(argv[1] || '', argv[2] || '');
+  return 'unknown';
+}

package/src/resources/trayTemplate.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="36" height="36" viewBox="0 0 36 36" fill="none" stroke="#000" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"><path d="M10 4v22h22"/><path d="M4 10h22v22"/><circle cx="18" cy="18" r="3.2" fill="#000" stroke="none"/></svg>

package/src/src/annotations.ts

@@ -0,0 +1,398 @@
+// Annotations as plain data in display points, and how to draw, hit-test and edit them on any 2D
+// context. The live editor draws with a devicePixelRatio transform and the export with the
+// capture's scale, so both come out identical.
+import type { Point, Rect } from './geometry.ts';
+
+export type Tool = 'select' | 'arrow' | 'line' | 'pencil' | 'marker' | 'rect' | 'ellipse' | 'text' | 'number' | 'censor' | 'highlight' | 'stamp' | 'measure' | 'sampler';
+export const TOOLS: Tool[] = ['select', 'arrow', 'line', 'pencil', 'marker', 'rect', 'ellipse', 'text', 'number', 'censor', 'highlight', 'stamp', 'measure', 'sampler'];
+/** Single-key tool shortcuts once a region is selected. */
+export const TOOL_KEYS: Record<string, Tool> = { s: 'select', a: 'arrow', l: 'line', p: 'pencil', m: 'marker', r: 'rect', o: 'ellipse', t: 'text', n: 'number', b: 'censor', h: 'highlight', g: 'stamp', u: 'measure', i: 'sampler' };
+export const KEY_OF: Partial<Record<Tool, string>> = Object.fromEntries(Object.entries(TOOL_KEYS).map(([k, v]) => [v, k.toUpperCase()]));
+
+export const COLORS = ['#FF3B30', '#FF9500', '#FFCC00', '#34C759', '#00C7BE', '#007AFF', '#5856D6', '#AF52DE', '#FF2D55', '#FFFFFF', '#8E8E93', '#000000'];
+export const EMOJIS = ['👍', '👎', '✅', '❌', '⚠️', '❓', '❗', '💡', '🔥', '⭐', '❤️', '😀', '😂', '😍', '🤔', '😢', '😡', '🎉', '👀', '👉', '🐛'];
+
+export type LineStyle = 'solid' | 'dashed' | 'dotted';
+export type ArrowStyle = 'single' | 'double' | 'open' | 'thick' | 'tail';
+export type Fill = 'stroke' | 'strokeFill' | 'fill';
+export type NumberFormat = 'decimal' | 'roman' | 'alpha' | 'alphaLower';
+export type CensorMode = 'pixelate' | 'blur' | 'solid';
+export type Align = 'left' | 'center' | 'right';
+
+/** Everything a tool can be set to; each annotation keeps the values it was drawn with. */
+export interface Options {
+  color: string; width: number; opacity: number; lineStyle: LineStyle;
+  arrow: ArrowStyle; fill: Fill; radius: number;
+  fontSize: number; bold: boolean; italic: boolean; underline: boolean; align: Align; textBg: boolean;
+  numberFormat: NumberFormat; censor: CensorMode; emoji: string; stampSize: number;
+}
+export const DEFAULT_OPTIONS: Options = {
+  color: COLORS[0], width: 4, opacity: 1, lineStyle: 'solid', arrow: 'single', fill: 'stroke', radius: 0,
+  fontSize: 22, bold: false, italic: false, underline: false, align: 'left', textBg: false,
+  numberFormat: 'decimal', censor: 'pixelate', emoji: '👍', stampSize: 48,
+};
+
+interface Base { id: number; o: Options }
+export type Stroke = Base & { kind: 'pencil' | 'marker'; points: Point[] };
+export type Segment = Base & { kind: 'line' | 'arrow' | 'measure'; a: Point; b: Point; c: Point | null };
+export type Box = Base & { kind: 'rect' | 'ellipse' | 'censor' | 'highlight'; a: Point; b: Point };
+export type Text = Base & { kind: 'text'; at: Point; text: string };
+export type Num = Base & { kind: 'number'; at: Point; tip: Point | null; n: number };
+export type Stamp = Base & { kind: 'stamp'; at: Point; size: number };
+export type Ann = Stroke | Segment | Box | Text | Num | Stamp;
+
+/** What drawing needs besides the annotation: pixelated/blurred copies of the display, the capture scale. */
+export interface Env { mosaic: CanvasImageSource | null; blur: CanvasImageSource | null; width: number; height: number; scale: number }
+
+export const FONT = '-apple-system, BlinkMacSystemFont, "PingFang SC", "Hiragino Sans GB", "Helvetica Neue", sans-serif';
+const LINE = 1.25;
+
+// ---------------------------------------------------------------- small helpers
+export const boxOf = (a: Point, b: Point): Rect => ({ x: Math.min(a.x, b.x), y: Math.min(a.y, b.y), w: Math.abs(b.x - a.x), h: Math.abs(b.y - a.y) });
+const contrast = (hex: string) => {
+  const v = parseInt(hex.slice(1), 16), r = v >> 16 & 255, g = v >> 8 & 255, b = v & 255;
+  return (r * 299 + g * 587 + b * 114) / 1000 > 160 ? '#000000' : '#FFFFFF';
+};
+
+export function formatNumber(n: number, f: NumberFormat): string {
+  if (f === 'decimal') return String(n);
+  if (f === 'roman') {
+    const table: [number, string][] = [[1000, 'M'], [900, 'CM'], [500, 'D'], [400, 'CD'], [100, 'C'], [90, 'XC'], [50, 'L'], [40, 'XL'], [10, 'X'], [9, 'IX'], [5, 'V'], [4, 'IV'], [1, 'I']];
+    let out = '', v = Math.max(1, Math.min(3999, n));
+    for (const [k, s] of table) while (v >= k) { out += s; v -= k; }
+    return out;
+  }
+  // A…Z, AA…AZ, BA… (spreadsheet columns)
+  let out = '', v = Math.max(1, n);
+  while (v > 0) { v--; out = String.fromCharCode(65 + (v % 26)) + out; v = Math.floor(v / 26); }
+  return f === 'alpha' ? out : out.toLowerCase();
+}
+
+/** Shift: lines snap to 45°, boxes become squares. */
+export function constrain(a: Point, p: Point, kind: Ann['kind']): Point {
+  const dx = p.x - a.x, dy = p.y - a.y;
+  if (kind === 'line' || kind === 'arrow' || kind === 'measure') {
+    const ang = Math.round(Math.atan2(dy, dx) / (Math.PI / 4)) * (Math.PI / 4), len = Math.hypot(dx, dy);
+    return { x: a.x + Math.cos(ang) * len, y: a.y + Math.sin(ang) * len };
+  }
+  const d = Math.max(Math.abs(dx), Math.abs(dy));
+  return { x: a.x + Math.sign(dx || 1) * d, y: a.y + Math.sign(dy || 1) * d };
+}
+
+export const badgeRadius = (o: Options) => 10 + o.width * 1.6;
+export const arrowHead = (o: Options) => 9 + o.width * 2.6;
+
+let scratch: CanvasRenderingContext2D | null = null;
+const measureCtx = () => scratch ??= document.createElement('canvas').getContext('2d')!;
+const textFont = (o: Options) => `${o.italic ? 'italic ' : ''}${o.bold ? '700 ' : '400 '}${o.fontSize}px ${FONT}`;
+export function textBox(s: Text): Rect {
+  const ctx = measureCtx(); ctx.font = textFont(s.o);
+  const lines = s.text.split('\n'), pad = s.o.textBg ? s.o.fontSize * 0.35 : 0;
+  const w = Math.max(...lines.map(l => ctx.measureText(l).width), s.o.fontSize * 0.5);
+  return { x: s.at.x - pad, y: s.at.y - pad, w: w + pad * 2, h: lines.length * s.o.fontSize * LINE + pad * 2 };
+}
+
+/** The bounding box, for selection outlines and hit tests. */
+export function bounds(s: Ann): Rect {
+  switch (s.kind) {
+    case 'pencil': case 'marker': {
+      const xs = s.points.map(p => p.x), ys = s.points.map(p => p.y);
+      return { x: Math.min(...xs), y: Math.min(...ys), w: Math.max(...xs) - Math.min(...xs), h: Math.max(...ys) - Math.min(...ys) };
+    }
+    case 'line': case 'arrow': case 'measure': {
+      const pts = [s.a, s.b, ...(s.c ? [curveMid(s)] : [])];
+      const xs = pts.map(p => p.x), ys = pts.map(p => p.y);
+      return { x: Math.min(...xs), y: Math.min(...ys), w: Math.max(...xs) - Math.min(...xs), h: Math.max(...ys) - Math.min(...ys) };
+    }
+    case 'rect': case 'ellipse': case 'censor': case 'highlight': return boxOf(s.a, s.b);
+    case 'text': return textBox(s);
+    case 'number': { const r = badgeRadius(s.o); return { x: s.at.x - r, y: s.at.y - r, w: r * 2, h: r * 2 }; }
+    case 'stamp': return { x: s.at.x - s.size / 2, y: s.at.y - s.size / 2, w: s.size, h: s.size };
+  }
+}
+
+// ---------------------------------------------------------------- drawing
+function dash(ctx: CanvasRenderingContext2D, o: Options) {
+  ctx.setLineDash(o.lineStyle === 'dashed' ? [o.width * 3, o.width * 2] : o.lineStyle === 'dotted' ? [0.1, o.width * 2] : []);
+}
+
+function smooth(ctx: CanvasRenderingContext2D, points: Point[]) {
+  ctx.beginPath();
+  if (points.length === 1) { ctx.moveTo(points[0].x, points[0].y); ctx.lineTo(points[0].x + 0.01, points[0].y); return; }
+  ctx.moveTo(points[0].x, points[0].y);
+  for (let i = 1; i < points.length - 1; i++) {
+    const m = { x: (points[i].x + points[i + 1].x) / 2, y: (points[i].y + points[i + 1].y) / 2 };
+    ctx.quadraticCurveTo(points[i].x, points[i].y, m.x, m.y);
+  }
+  const last = points[points.length - 1]; ctx.lineTo(last.x, last.y);
+}
+
+function head(ctx: CanvasRenderingContext2D, tip: Point, from: Point, size: number, open = false) {
+  const ang = Math.atan2(tip.y - from.y, tip.x - from.x), spread = Math.PI / 7;
+  const l = { x: tip.x - size * Math.cos(ang - spread), y: tip.y - size * Math.sin(ang - spread) };
+  const r = { x: tip.x - size * Math.cos(ang + spread), y: tip.y - size * Math.sin(ang + spread) };
+  ctx.beginPath();
+  if (open) { ctx.setLineDash([]); ctx.moveTo(l.x, l.y); ctx.lineTo(tip.x, tip.y); ctx.lineTo(r.x, r.y); ctx.stroke(); return; }
+  ctx.moveTo(tip.x, tip.y); ctx.lineTo(l.x, l.y);
+  ctx.lineTo(tip.x - size * 0.72 * Math.cos(ang), tip.y - size * 0.72 * Math.sin(ang));
+  ctx.lineTo(r.x, r.y); ctx.closePath(); ctx.fill();
+}
+
+/** The point halfway along a segment; dragging it bends the shaft through the pointer. */
+export function curveMid(s: Segment): Point {
+  const c = s.c ?? { x: (s.a.x + s.b.x) / 2, y: (s.a.y + s.b.y) / 2 };
+  return { x: 0.25 * s.a.x + 0.5 * c.x + 0.25 * s.b.x, y: 0.25 * s.a.y + 0.5 * c.y + 0.25 * s.b.y };
+}
+
+/** Pull `p` back towards `from` by `by` points (so a round cap never pokes out of an arrowhead). */
+const back = (p: Point, from: Point, by: number): Point => { const d = Math.hypot(p.x - from.x, p.y - from.y) || 1; return { x: p.x - (p.x - from.x) / d * by, y: p.y - (p.y - from.y) / d * by }; };
+
+function segment(ctx: CanvasRenderingContext2D, s: Segment, env: Env) {
+  const o = s.o;
+  if (s.kind === 'arrow' && o.arrow === 'thick') { thickArrow(ctx, s.a, s.b, o); return; }
+  const size = arrowHead(o);
+  const endFrom = s.c ?? s.a, startFrom = s.c ?? s.b;
+  const headEnd = s.kind === 'arrow', headStart = s.kind === 'arrow' && o.arrow === 'double';
+  const filled = s.kind === 'arrow' && o.arrow !== 'open';
+  const a = headStart && filled ? back(s.a, startFrom, size * 0.6) : s.a;
+  const b = headEnd && filled ? back(s.b, endFrom, size * 0.6) : s.b;
+  dash(ctx, o);
+  ctx.beginPath(); ctx.moveTo(a.x, a.y);
+  if (s.c) ctx.quadraticCurveTo(s.c.x, s.c.y, b.x, b.y); else ctx.lineTo(b.x, b.y);
+  ctx.stroke(); ctx.setLineDash([]);
+  if (headEnd) head(ctx, s.b, endFrom, size, o.arrow === 'open');
+  if (headStart) head(ctx, s.a, startFrom, size, false);
+  if (s.kind === 'arrow' && o.arrow === 'tail') { ctx.beginPath(); ctx.arc(s.a.x, s.a.y, Math.max(3, o.width * 1.2), 0, Math.PI * 2); ctx.fill(); }
+  if (s.kind === 'measure') {
+    // Ticks at both ends and the length in pixels of the captured image.
+    const ang = Math.atan2(s.b.y - s.a.y, s.b.x - s.a.x), t = 6 + o.width;
+    for (const p of [s.a, s.b]) { ctx.beginPath(); ctx.moveTo(p.x - Math.sin(ang) * t, p.y + Math.cos(ang) * t); ctx.lineTo(p.x + Math.sin(ang) * t, p.y - Math.cos(ang) * t); ctx.stroke(); }
+    const len = Math.round(Math.hypot(s.b.x - s.a.x, s.b.y - s.a.y) * env.scale), label = `${len} px`;
+    const m = { x: (s.a.x + s.b.x) / 2, y: (s.a.y + s.b.y) / 2 };
+    ctx.font = `600 12px ${FONT}`; const w = ctx.measureText(label).width + 10;
+    ctx.globalAlpha = 1; ctx.fillStyle = 'rgba(17,24,39,0.85)'; ctx.beginPath(); ctx.roundRect(m.x - w / 2, m.y - 20 - t, w, 18, 4); ctx.fill();
+    ctx.fillStyle = '#fff'; ctx.textAlign = 'center'; ctx.textBaseline = 'middle'; ctx.fillText(label, m.x, m.y - 11 - t);
+  }
+}
+
+/** A solid banner arrow: a tapered body with a wide head. */
+function thickArrow(ctx: CanvasRenderingContext2D, a: Point, b: Point, o: Options) {
+  const len = Math.hypot(b.x - a.x, b.y - a.y); if (len < 1) return;
+  const ux = (b.x - a.x) / len, uy = (b.y - a.y) / len, nx = -uy, ny = ux;
+  const w = 3 + o.width * 1.6, hw = w * 2.4, hl = Math.min(len * 0.6, w * 3.2);
+  const base = { x: b.x - ux * hl, y: b.y - uy * hl };
+  ctx.beginPath();
+  ctx.moveTo(a.x + nx * w * 0.25, a.y + ny * w * 0.25);
+  ctx.lineTo(base.x + nx * w, base.y + ny * w); ctx.lineTo(base.x + nx * hw, base.y + ny * hw);
+  ctx.lineTo(b.x, b.y);
+  ctx.lineTo(base.x - nx * hw, base.y - ny * hw); ctx.lineTo(base.x - nx * w, base.y - ny * w);
+  ctx.lineTo(a.x - nx * w * 0.25, a.y - ny * w * 0.25); ctx.closePath(); ctx.fill();
+}
+
+function box(ctx: CanvasRenderingContext2D, s: Box, env: Env) {
+  const r = boxOf(s.a, s.b), o = s.o;
+  if (s.kind === 'censor') {
+    ctx.save(); ctx.beginPath(); ctx.rect(r.x, r.y, r.w, r.h); ctx.clip(); ctx.globalAlpha = 1;
+    if (o.censor === 'solid') { ctx.fillStyle = o.color; ctx.fillRect(r.x, r.y, r.w, r.h); }
+    else { const src = o.censor === 'pixelate' ? env.mosaic : env.blur; if (src) ctx.drawImage(src, 0, 0, env.width, env.height); }
+    ctx.restore(); return;
+  }
+  if (s.kind === 'highlight') return; // painted together with the others by `spotlight`
+  ctx.beginPath();
+  if (s.kind === 'rect') ctx.roundRect(r.x, r.y, r.w, r.h, Math.min(o.radius, r.w / 2, r.h / 2));
+  else ctx.ellipse(r.x + r.w / 2, r.y + r.h / 2, r.w / 2, r.h / 2, 0, 0, Math.PI * 2);
+  if (o.fill !== 'stroke') { ctx.save(); ctx.globalAlpha = o.opacity * (o.fill === 'strokeFill' ? 0.3 : 1); ctx.fill(); ctx.restore(); }
+  if (o.fill !== 'fill') { dash(ctx, o); ctx.stroke(); ctx.setLineDash([]); }
+}
+
+function text(ctx: CanvasRenderingContext2D, s: Text) {
+  const o = s.o, r = textBox(s), lines = s.text.split('\n');
+  ctx.font = textFont(o); ctx.textBaseline = 'top';
+  const inner = { x: s.at.x, w: r.w - (o.textBg ? o.fontSize * 0.7 : 0) };
+  if (o.textBg) { ctx.beginPath(); ctx.roundRect(r.x, r.y, r.w, r.h, o.fontSize * 0.3); ctx.fill(); ctx.fillStyle = contrast(o.color); }
+  lines.forEach((line, i) => {
+    const w = ctx.measureText(line).width;
+    const x = o.align === 'center' ? inner.x + (inner.w - w) / 2 : o.align === 'right' ? inner.x + inner.w - w : inner.x;
+    const y = s.at.y + i * o.fontSize * LINE + o.fontSize * 0.1;
+    ctx.fillText(line, x, y);
+    if (o.underline && w) ctx.fillRect(x, y + o.fontSize * 1.02, w, Math.max(1, o.fontSize / 14));
+  });
+}
+
+function number(ctx: CanvasRenderingContext2D, s: Num) {
+  const o = s.o, r = badgeRadius(o);
+  if (s.tip) {
+    // A cone from the badge towards what it points at.
+    const d = Math.hypot(s.tip.x - s.at.x, s.tip.y - s.at.y);
+    if (d > r) {
+      const ang = Math.atan2(s.tip.y - s.at.y, s.tip.x - s.at.x), spread = Math.asin(Math.min(0.95, r * 0.55 / r));
+      ctx.beginPath(); ctx.moveTo(s.at.x + Math.cos(ang - spread) * r, s.at.y + Math.sin(ang - spread) * r);
+      ctx.lineTo(s.tip.x, s.tip.y); ctx.lineTo(s.at.x + Math.cos(ang + spread) * r, s.at.y + Math.sin(ang + spread) * r); ctx.closePath(); ctx.fill();
+    }
+  }
+  ctx.beginPath(); ctx.arc(s.at.x, s.at.y, r, 0, Math.PI * 2); ctx.fill();
+  const label = formatNumber(s.n, o.numberFormat);
+  ctx.fillStyle = contrast(o.color); ctx.textAlign = 'center'; ctx.textBaseline = 'middle';
+  ctx.font = `700 ${Math.round(r * (label.length > 2 ? 0.75 : label.length > 1 ? 0.9 : 1.1))}px ${FONT}`;
+  ctx.fillText(label, s.at.x, s.at.y + r * 0.05);
+}
+
+export function draw(ctx: CanvasRenderingContext2D, s: Ann, env: Env) {
+  const o = s.o;
+  ctx.save();
+  ctx.globalAlpha = o.opacity; ctx.strokeStyle = o.color; ctx.fillStyle = o.color;
+  ctx.lineWidth = o.width; ctx.lineCap = 'round'; ctx.lineJoin = 'round';
+  switch (s.kind) {
+    case 'pencil': dash(ctx, o); smooth(ctx, s.points); ctx.stroke(); break;
+    case 'marker':
+      ctx.globalAlpha = 0.4 * o.opacity; ctx.globalCompositeOperation = 'multiply'; ctx.lineWidth = o.width * 3 + 8; ctx.lineCap = 'butt';
+      smooth(ctx, s.points); ctx.stroke(); break;
+    case 'line': case 'arrow': case 'measure': segment(ctx, s, env); break;
+    case 'rect': case 'ellipse': case 'censor': case 'highlight': box(ctx, s, env); break;
+    case 'text': text(ctx, s); break;
+    case 'number': number(ctx, s); break;
+    case 'stamp': ctx.globalAlpha = o.opacity; ctx.font = `${s.size}px "Apple Color Emoji", ${FONT}`; ctx.textAlign = 'center'; ctx.textBaseline = 'middle'; ctx.fillText(o.emoji, s.at.x, s.at.y + s.size * 0.06); break;
+  }
+  ctx.restore();
+}
+
+let spot: HTMLCanvasElement | null = null;
+/** Spotlight: everything in `area` outside the highlight boxes is dimmed (the Highlight tool). */
+export function spotlight(ctx: CanvasRenderingContext2D, list: Ann[], area: Rect) {
+  const boxes = list.filter((s): s is Box => s.kind === 'highlight');
+  if (!boxes.length) return;
+  const c = spot ??= document.createElement('canvas');
+  if (c.width !== ctx.canvas.width || c.height !== ctx.canvas.height) { c.width = ctx.canvas.width; c.height = ctx.canvas.height; }
+  const m = c.getContext('2d')!;
+  m.setTransform(1, 0, 0, 1, 0, 0); m.globalCompositeOperation = 'source-over'; m.clearRect(0, 0, c.width, c.height);
+  m.setTransform(ctx.getTransform());
+  m.fillStyle = 'rgba(0,0,0,0.55)'; m.fillRect(area.x, area.y, area.w, area.h);
+  m.globalCompositeOperation = 'destination-out';
+  for (const b of boxes) { const r = boxOf(b.a, b.b); m.beginPath(); m.roundRect(r.x, r.y, r.w, r.h, 6); m.fill(); }
+  ctx.save(); ctx.setTransform(1, 0, 0, 1, 0, 0); ctx.globalAlpha = 1; ctx.drawImage(c, 0, 0); ctx.restore();
+  for (const b of boxes) {
+    const r = boxOf(b.a, b.b);
+    ctx.save(); ctx.strokeStyle = b.o.color; ctx.lineWidth = 2; ctx.globalAlpha = b.o.opacity; dash(ctx, b.o);
+    ctx.beginPath(); ctx.roundRect(r.x, r.y, r.w, r.h, 6); ctx.stroke(); ctx.restore();
+  }
+}
+
+// ---------------------------------------------------------------- editing
+export type HandleId = 'a' | 'b' | 'c' | 'tip' | 'nw' | 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w';
+
+export function handles(s: Ann): { id: HandleId; p: Point }[] {
+  switch (s.kind) {
+    case 'rect': case 'ellipse': case 'censor': case 'highlight': case 'stamp': {
+      const r = bounds(s), cx = r.x + r.w / 2, cy = r.y + r.h / 2, R = r.x + r.w, B = r.y + r.h;
+      const corners: { id: HandleId; p: Point }[] = [{ id: 'nw', p: { x: r.x, y: r.y } }, { id: 'ne', p: { x: R, y: r.y } }, { id: 'se', p: { x: R, y: B } }, { id: 'sw', p: { x: r.x, y: B } }];
+      if (s.kind === 'stamp') return corners;
+      return [...corners, { id: 'n', p: { x: cx, y: r.y } }, { id: 'e', p: { x: R, y: cy } }, { id: 's', p: { x: cx, y: B } }, { id: 'w', p: { x: r.x, y: cy } }];
+    }
+    case 'line': case 'measure': return [{ id: 'a', p: s.a }, { id: 'b', p: s.b }];
+    case 'arrow': return s.o.arrow === 'thick' ? [{ id: 'a', p: s.a }, { id: 'b', p: s.b }] : [{ id: 'a', p: s.a }, { id: 'c', p: curveMid(s) }, { id: 'b', p: s.b }];
+    case 'number': return s.tip ? [{ id: 'tip', p: s.tip }] : [];
+    default: return [];
+  }
+}
+
+export function dragHandle(s: Ann, h: HandleId, p: Point, shift = false): Ann {
+  switch (s.kind) {
+    case 'line': case 'arrow': case 'measure':
+      if (h === 'a') return { ...s, a: shift ? constrain(s.b, p, s.kind) : p };
+      if (h === 'b') return { ...s, b: shift ? constrain(s.a, p, s.kind) : p };
+      if (h === 'c') return { ...s, c: { x: 2 * p.x - (s.a.x + s.b.x) / 2, y: 2 * p.y - (s.a.y + s.b.y) / 2 } };
+      return s;
+    case 'number': return h === 'tip' ? { ...s, tip: p } : s;
+    case 'stamp': {
+      const size = Math.max(16, Math.min(400, Math.max(Math.abs(p.x - s.at.x), Math.abs(p.y - s.at.y)) * 2));
+      return { ...s, size };
+    }
+    case 'rect': case 'ellipse': case 'censor': case 'highlight': {
+      const r = boxOf(s.a, s.b); let x1 = r.x, y1 = r.y, x2 = r.x + r.w, y2 = r.y + r.h;
+      if (h.includes('w')) x1 = p.x; if (h.includes('e')) x2 = p.x; if (h.includes('n')) y1 = p.y; if (h.includes('s')) y2 = p.y;
+      return { ...s, a: { x: x1, y: y1 }, b: { x: x2, y: y2 } };
+    }
+    default: return s;
+  }
+}
+
+export function translate(s: Ann, dx: number, dy: number): Ann {
+  const t = (p: Point) => ({ x: p.x + dx, y: p.y + dy });
+  switch (s.kind) {
+    case 'pencil': case 'marker': return { ...s, points: s.points.map(t) };
+    case 'line': case 'arrow': case 'measure': return { ...s, a: t(s.a), b: t(s.b), c: s.c && t(s.c) };
+    case 'rect': case 'ellipse': case 'censor': case 'highlight': return { ...s, a: t(s.a), b: t(s.b) };
+    case 'text': case 'stamp': return { ...s, at: t(s.at) };
+    case 'number': return { ...s, at: t(s.at), tip: s.tip && t(s.tip) };
+  }
+}
+
+function distToSegment(p: Point, a: Point, b: Point) {
+  const dx = b.x - a.x, dy = b.y - a.y, l = dx * dx + dy * dy;
+  const k = l ? Math.max(0, Math.min(1, ((p.x - a.x) * dx + (p.y - a.y) * dy) / l)) : 0;
+  return Math.hypot(p.x - (a.x + k * dx), p.y - (a.y + k * dy));
+}
+const nearPolyline = (p: Point, pts: Point[], tol: number) => pts.length === 1 ? Math.hypot(p.x - pts[0].x, p.y - pts[0].y) <= tol : pts.some((q, i) => i > 0 && distToSegment(p, pts[i - 1], q) <= tol);
+const inside = (r: Rect, p: Point, pad: number) => p.x >= r.x - pad && p.x <= r.x + r.w + pad && p.y >= r.y - pad && p.y <= r.y + r.h + pad;
+
+/** Whether `p` grabs `s`. Outlined shapes are grabbed by their edge so things inside stay clickable. */
+export function hit(s: Ann, p: Point): boolean {
+  const tol = Math.max(6, s.o.width / 2 + 5);
+  switch (s.kind) {
+    case 'pencil': return nearPolyline(p, s.points, tol);
+    case 'marker': return nearPolyline(p, s.points, (s.o.width * 3 + 8) / 2 + 3);
+    case 'line': case 'arrow': case 'measure': {
+      if (!s.c) return distToSegment(p, s.a, s.b) <= tol + (s.kind === 'arrow' && s.o.arrow === 'thick' ? s.o.width * 2 : 2);
+      const pts: Point[] = [];
+      for (let i = 0; i <= 24; i++) { const k = i / 24, u = 1 - k; pts.push({ x: u * u * s.a.x + 2 * u * k * s.c.x + k * k * s.b.x, y: u * u * s.a.y + 2 * u * k * s.c.y + k * k * s.b.y }); }
+      return nearPolyline(p, pts, tol + 2);
+    }
+    case 'rect': case 'ellipse': {
+      const r = boxOf(s.a, s.b);
+      if (s.o.fill !== 'stroke') return inside(r, p, tol / 2);
+      if (!inside(r, p, tol)) return false;
+      if (s.kind === 'rect') return !inside({ x: r.x + tol, y: r.y + tol, w: r.w - tol * 2, h: r.h - tol * 2 }, p, 0);
+      const cx = r.x + r.w / 2, cy = r.y + r.h / 2, rx = Math.max(1, r.w / 2), ry = Math.max(1, r.h / 2);
+      const d = Math.hypot((p.x - cx) / rx, (p.y - cy) / ry);
+      return Math.abs(d - 1) * Math.min(rx, ry) <= tol;
+    }
+    case 'censor': case 'stamp': case 'text': return inside(bounds(s), p, 3);
+    case 'highlight': { const r = boxOf(s.a, s.b); return inside(r, p, tol) && !inside({ x: r.x + tol, y: r.y + tol, w: r.w - tol * 2, h: r.h - tol * 2 }, p, 0); }
+    case 'number': return Math.hypot(p.x - s.at.x, p.y - s.at.y) <= badgeRadius(s.o) + 3 || (!!s.tip && distToSegment(p, s.at, s.tip) <= tol);
+  }
+}
+
+/** Mouse wheel over a selected annotation: stroke width, font size or stamp size. */
+export function adjust(s: Ann, delta: number): Ann {
+  if (s.kind === 'text') return { ...s, o: { ...s.o, fontSize: Math.max(10, Math.min(160, s.o.fontSize + delta * 2)) } };
+  if (s.kind === 'stamp') return { ...s, size: Math.max(16, Math.min(400, s.size + delta * 4)) };
+  return { ...s, o: { ...s.o, width: Math.max(1, Math.min(40, s.o.width + delta)) } };
+}
+
+/** A drag that never really moved draws nothing (a number badge is placed by a click). */
+export function meaningful(s: Ann): boolean {
+  switch (s.kind) {
+    case 'rect': case 'ellipse': case 'censor': case 'highlight': return Math.abs(s.a.x - s.b.x) > 3 && Math.abs(s.a.y - s.b.y) > 3;
+    case 'line': case 'arrow': case 'measure': return Math.hypot(s.a.x - s.b.x, s.a.y - s.b.y) > 4;
+    case 'text': return s.text.trim().length > 0;
+    default: return true;
+  }
+}
+
+/** Which option controls a tool shows (besides colour, width and opacity). */
+export function optionsFor(kind: Tool | Ann['kind']): (keyof Options)[] {
+  switch (kind) {
+    case 'arrow': return ['arrow', 'lineStyle'];
+    case 'line': case 'pencil': return ['lineStyle'];
+    case 'rect': return ['fill', 'radius', 'lineStyle'];
+    case 'ellipse': return ['fill', 'lineStyle'];
+    case 'text': return ['fontSize', 'bold', 'italic', 'underline', 'align', 'textBg'];
+    case 'number': return ['numberFormat'];
+    case 'censor': return ['censor'];
+    case 'stamp': return ['emoji'];
+    default: return [];
+  }
+}
+/** Tools without a meaningful colour or stroke width. */
+export const NO_COLOR = new Set<Tool | Ann['kind']>(['select', 'sampler', 'stamp']);
+export const NO_WIDTH = new Set<Tool | Ann['kind']>(['select', 'sampler', 'stamp', 'text', 'censor', 'highlight']);

package/src/src/beautify.ts

@@ -0,0 +1,41 @@
+// Beautify: the capture on a gradient with padding, rounded corners, a soft shadow and an optional
+// macOS window frame. Used for the export and for the live preview around the selection.
+export interface Beauty { on: boolean; style: number; padding: number; frame: boolean }
+export const DEFAULT_BEAUTY: Beauty = { on: false, style: 0, padding: 48, frame: false };
+export const GRADIENTS: string[][] = [
+  ['#6366F1', '#A855F7', '#EC4899'], ['#0EA5E9', '#6366F1'], ['#F97316', '#F43F5E'], ['#10B981', '#06B6D4'],
+  ['#FDE68A', '#F9A8D4', '#C4B5FD'], ['#1E293B', '#334155'], ['#F1F5F9', '#CBD5E1'], ['#FB7185', '#FDBA74', '#FDE047'],
+];
+export const FRAME_BAR = 28;
+export const RADIUS = 10;
+
+export function fillGradient(ctx: CanvasRenderingContext2D, x: number, y: number, w: number, h: number, style: number) {
+  const stops = GRADIENTS[style] ?? GRADIENTS[0];
+  const g = ctx.createLinearGradient(x, y, x + w, y + h);
+  stops.forEach((c, i) => g.addColorStop(stops.length === 1 ? 0 : i / (stops.length - 1), c));
+  ctx.fillStyle = g; ctx.fillRect(x, y, w, h);
+}
+
+/** Draws the window chrome (title bar with the three lights) at `x,y`, `w` wide, in points. */
+export function drawFrame(ctx: CanvasRenderingContext2D, x: number, y: number, w: number) {
+  ctx.fillStyle = '#ECECEC'; ctx.fillRect(x, y, w, FRAME_BAR);
+  ctx.fillStyle = 'rgba(0,0,0,0.08)'; ctx.fillRect(x, y + FRAME_BAR - 1, w, 1);
+  ['#FF5F57', '#FEBC2E', '#28C840'].forEach((c, i) => { ctx.fillStyle = c; ctx.beginPath(); ctx.arc(x + 16 + i * 20, y + FRAME_BAR / 2, 6, 0, Math.PI * 2); ctx.fill(); });
+}
+
+/** The beautified image; `src` is the flattened capture at `scale` pixels per point. */
+export function beautify(src: HTMLCanvasElement, b: Beauty, scale: number): HTMLCanvasElement {
+  const w = src.width / scale, h = src.height / scale, bar = b.frame ? FRAME_BAR : 0, pad = b.padding;
+  const out = document.createElement('canvas');
+  out.width = Math.round((w + pad * 2) * scale); out.height = Math.round((h + bar + pad * 2) * scale);
+  const ctx = out.getContext('2d')!; ctx.scale(scale, scale);
+  fillGradient(ctx, 0, 0, w + pad * 2, h + bar + pad * 2, b.style);
+  const x = pad, y = pad;
+  ctx.save(); ctx.shadowColor = 'rgba(0,0,0,0.35)'; ctx.shadowBlur = 30; ctx.shadowOffsetY = 12;
+  ctx.fillStyle = '#fff'; ctx.beginPath(); ctx.roundRect(x, y, w, h + bar, RADIUS); ctx.fill(); ctx.restore();
+  ctx.save(); ctx.beginPath(); ctx.roundRect(x, y, w, h + bar, RADIUS); ctx.clip();
+  if (bar) drawFrame(ctx, x, y, w);
+  ctx.drawImage(src, x, y + bar, w, h);
+  ctx.restore();
+  return out;
+}

package/src/src/geometry.ts

@@ -0,0 +1,79 @@
+// Selection geometry as plain data (display points, top-left origin): dragging out a rectangle,
+// the eight resize handles, moving inside the display and placing the toolbar. No DOM, no SDK.
+
+export interface Point { x: number; y: number }
+export interface Rect { x: number; y: number; w: number; h: number }
+export type Handle = 'nw' | 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w';
+export const HANDLES: Handle[] = ['nw', 'n', 'ne', 'e', 'se', 's', 'sw', 'w'];
+
+export const clamp = (v: number, lo: number, hi: number) => Math.min(Math.max(v, lo), hi);
+
+/** The rectangle between two points, kept inside `bounds`; `square` makes the shorter side follow the longer. */
+export function fromPoints(a: Point, b: Point, bounds: Rect, square = false): Rect {
+  let bx = clamp(b.x, bounds.x, bounds.x + bounds.w), by = clamp(b.y, bounds.y, bounds.y + bounds.h);
+  if (square) {
+    const dx = bx - a.x, dy = by - a.y;
+    // The side is limited by how far the display reaches in both drag directions.
+    const room = Math.min(dx < 0 ? a.x - bounds.x : bounds.x + bounds.w - a.x, dy < 0 ? a.y - bounds.y : bounds.y + bounds.h - a.y);
+    const side = Math.min(Math.max(Math.abs(dx), Math.abs(dy)), room);
+    bx = a.x + Math.sign(dx || 1) * side; by = a.y + Math.sign(dy || 1) * side;
+  }
+  return { x: Math.min(a.x, bx), y: Math.min(a.y, by), w: Math.abs(bx - a.x), h: Math.abs(by - a.y) };
+}
+
+/** Rounds to whole points so the exported crop lands on pixel boundaries. */
+export const round = (r: Rect): Rect => {
+  const x = Math.round(r.x), y = Math.round(r.y);
+  return { x, y, w: Math.round(r.x + r.w) - x, h: Math.round(r.y + r.h) - y };
+};
+
+export function intersect(a: Rect, b: Rect): Rect | null {
+  const x = Math.max(a.x, b.x), y = Math.max(a.y, b.y);
+  const r = Math.min(a.x + a.w, b.x + b.w), btm = Math.min(a.y + a.h, b.y + b.h);
+  return r > x && btm > y ? { x, y, w: r - x, h: btm - y } : null;
+}
+
+export const contains = (r: Rect, p: Point, pad = 0) => p.x >= r.x - pad && p.x <= r.x + r.w + pad && p.y >= r.y - pad && p.y <= r.y + r.h + pad;
+
+export function handlePoint(r: Rect, h: Handle): Point {
+  const cx = r.x + r.w / 2, cy = r.y + r.h / 2, R = r.x + r.w, B = r.y + r.h;
+  return { nw: { x: r.x, y: r.y }, n: { x: cx, y: r.y }, ne: { x: R, y: r.y }, e: { x: R, y: cy }, se: { x: R, y: B }, s: { x: cx, y: B }, sw: { x: r.x, y: B }, w: { x: r.x, y: cy } }[h];
+}
+
+/** The handle under `p` (within `radius`), corners before edges. */
+export function hitHandle(r: Rect, p: Point, radius = 6): Handle | null {
+  for (const h of ['nw', 'ne', 'se', 'sw', 'n', 'e', 's', 'w'] as Handle[]) {
+    const q = handlePoint(r, h);
+    if (Math.abs(q.x - p.x) <= radius && Math.abs(q.y - p.y) <= radius) return h;
+  }
+  return null;
+}
+
+/** Drags `h` of the rectangle as it was at the start of the drag to `p`; flips past the opposite side. */
+export function resize(start: Rect, h: Handle, p: Point, bounds: Rect): Rect {
+  let x1 = start.x, y1 = start.y, x2 = start.x + start.w, y2 = start.y + start.h;
+  const px = clamp(p.x, bounds.x, bounds.x + bounds.w), py = clamp(p.y, bounds.y, bounds.y + bounds.h);
+  if (h.includes('w')) x1 = px; if (h.includes('e')) x2 = px;
+  if (h.includes('n')) y1 = py; if (h.includes('s')) y2 = py;
+  return { x: Math.min(x1, x2), y: Math.min(y1, y2), w: Math.abs(x2 - x1), h: Math.abs(y2 - y1) };
+}
+
+/** Moves without changing the size, stopping at the display edges. */
+export function move(start: Rect, dx: number, dy: number, bounds: Rect): Rect {
+  return { ...start, x: clamp(start.x + dx, bounds.x, bounds.x + bounds.w - start.w), y: clamp(start.y + dy, bounds.y, bounds.y + bounds.h - start.h) };
+}
+
+export const CURSORS: Record<Handle, string> = { nw: 'nwse-resize', se: 'nwse-resize', ne: 'nesw-resize', sw: 'nesw-resize', n: 'ns-resize', s: 'ns-resize', e: 'ew-resize', w: 'ew-resize' };
+
+/** The frontmost window under the pointer (windows arrive front to back), else the whole display. */
+export function windowAt(windows: Rect[], p: Point, display: Rect): Rect {
+  return windows.find(w => contains(w, p)) ?? display;
+}
+
+/** Below the selection, else above it, else inside its bottom edge; always inside the display. */
+export function placeToolbar(sel: Rect, size: { w: number; h: number }, view: Rect, gap = 8): Point & { above: boolean } {
+  const x = clamp(sel.x + sel.w - size.w, view.x + 4, view.x + view.w - size.w - 4);
+  if (sel.y + sel.h + gap + size.h <= view.y + view.h - 4) return { x, y: sel.y + sel.h + gap, above: false };
+  if (sel.y - gap - size.h >= view.y + 4) return { x, y: sel.y - gap - size.h, above: true };
+  return { x, y: Math.max(view.y + 4, sel.y + sel.h - gap - size.h), above: false };
+}

package/src/src/naming.ts

@@ -0,0 +1,19 @@
+// `Medeo_20261109_140501.png`; a second file in the same second gets `_1`, `_2`… never overwriting.
+const pad = (n: number) => String(n).padStart(2, '0');
+export function stamp(d: Date): string {
+  return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}_${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+}
+export function fileName(prefix: string, d: Date, exists: (name: string) => boolean, ext = 'png'): string {
+  const base = `${prefix}_${stamp(d)}`;
+  for (let i = 0; ; i++) {
+    const name = i ? `${base}_${i}.${ext}` : `${base}.${ext}`;
+    if (!exists(name)) return name;
+  }
+}
+/** `~/x` → `<home>/x`; anything that is not absolute falls back to `fallback`. */
+export function expandHome(dir: string, home: string, fallback: string): string {
+  const v = dir.trim();
+  if (v === '~') return home;
+  if (v.startsWith('~/')) return home + v.slice(1);
+  return v.startsWith('/') ? v : fallback;
+}