@devaccel-labs/app-comments-toolbar 1.1.0 → 1.3.0

package/src/runtime/markup-model.ts

@@ -0,0 +1,485 @@
+/**
+ * The markup model: shapes in the image's own pixel space, sizes, colours, label layout, hit-testing, moves and
+ * undo history. DOM-free, so native clients draw the same shapes with their own renderer; the web toolbar's
+ * canvas renderer and flattening are in `./markup.ts`.
+ */
+import { INK, type Point } from "./ink.js";
+
+export type { Point };
+export type Box = { x: number; y: number; w: number; h: number };
+
+export type MarkupTool = "select" | "pen" | "highlight" | "arrow" | "rect" | "ellipse" | "text";
+export type MarkupSize = "s" | "m" | "l";
+
+type ShapeBase = { id: string; color: string; size: MarkupSize };
+export type StrokeShape = ShapeBase & { kind: "pen" | "highlight"; points: Point[] };
+export type ArrowShape = ShapeBase & { kind: "arrow"; from: Point; to: Point };
+export type BoxShape = ShapeBase & { kind: "rect" | "ellipse"; box: Box };
+export type TextShape = ShapeBase & { kind: "text"; at: Point; text: string };
+export type MarkupShape = StrokeShape | ArrowShape | BoxShape | TextShape;
+
+/** Colours offered in the editor. The first is the toolbar's sketch ink. */
+export const MARKUP_COLORS: ReadonlyArray<{ name: string; value: string }> = [
+  { name: "Red", value: INK },
+  { name: "Orange", value: "#ff9500" },
+  { name: "Yellow", value: "#ffcc00" },
+  { name: "Green", value: "#34c759" },
+  { name: "Blue", value: "#007aff" },
+  { name: "Purple", value: "#af52de" },
+  { name: "Black", value: "#1d1d1f" },
+  { name: "White", value: "#ffffff" },
+];
+export const DEFAULT_INK = INK;
+export const DEFAULT_HIGHLIGHT = "#ffcc00";
+/** Highlighter strokes are drawn at this opacity so the page under them stays readable. */
+export const HIGHLIGHT_ALPHA = 0.38;
+/** Most undo steps kept. */
+export const HISTORY_LIMIT = 100;
+/** Stroke widths in `unit` for each size: s 2u, m 4u, l 8u. */
+const STROKE_SCALE: Record<MarkupSize, number> = { s: 2, m: 4, l: 8 };
+/** Font sizes in `unit`: s 14u, m 20u, l 30u. */
+const FONT_SCALE: Record<MarkupSize, number> = { s: 14, m: 20, l: 30 };
+/** A highlighter is this many pen strokes wide. */
+const HIGHLIGHT_RATIO = 5;
+/** Labels are set in the system UI stack so they match the app they are drawn over. */
+const FONT_STACK =
+  '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif';
+/** Label text on a light fill is this near-black; on a dark fill it is white. */
+const LABEL_ON_LIGHT = "#1d1d1f";
+const LABEL_ON_DARK = "#ffffff";
+/** Stripped off the original name before the flattened extension is added. */
+const KNOWN_EXTENSION = /\.(?:png|jpe?g|gif|webp)$/i;
+
+/**
+ * Sizes in image pixels for one image. `unit` is max(1, longest side / 1000), so markup looks the same on a 1x
+ * screenshot and a 3x one. Pen and arrow strokes: s 2u, m 4u, l 8u. Highlighter: 5x the pen width. Text font:
+ * s 14u, m 20u, l 30u.
+ */
+export type MarkupMetrics = {
+  unit: number;
+  stroke: (size: MarkupSize) => number;
+  highlight: (size: MarkupSize) => number;
+  font: (size: MarkupSize) => number;
+};
+
+/** Width in px of one line of text at `fontPx`, set in `markupFont(fontPx)`. */
+export type MeasureText = (text: string, fontPx: number) => number;
+
+/** Laid-out text label: the filled box in image px, its lines, and where each line's top-left sits. */
+export type TextLayout = {
+  box: Box;
+  lines: string[];
+  font: number;
+  pad: number;
+  lineHeight: number;
+};
+
+export function markupMetrics(width: number, height: number): MarkupMetrics {
+  const usable = Number.isFinite(width) && Number.isFinite(height) && width > 0 && height > 0;
+  const unit = usable ? Math.max(1, Math.max(width, height) / 1000) : 1;
+  return {
+    unit,
+    stroke: (size) => unit * STROKE_SCALE[size],
+    highlight: (size) => unit * STROKE_SCALE[size] * HIGHLIGHT_RATIO,
+    font: (size) => unit * FONT_SCALE[size],
+  };
+}
+
+/** CSS font for labels: `600 <px>px` in the system UI stack. */
+export function markupFont(px: number): string {
+  return `600 ${px}px ${FONT_STACK}`;
+}
+
+/**
+ * Label text for a fill: `#ffffff` while it keeps at least 3:1 contrast (WCAG AA for large bold text, which
+ * labels are), else whichever of white and `#1d1d1f` reads better. Red, blue, and purple keep white text;
+ * orange, green, yellow, and white get dark text.
+ */
+export function contrastText(color: string): string {
+  const rgb = parseHexColor(color);
+  if (!rgb) return LABEL_ON_DARK;
+  const fill = luminance(rgb);
+  const onWhite = contrastRatio(fill, 1);
+  if (onWhite >= 3) return LABEL_ON_DARK;
+  const dark = parseHexColor(LABEL_ON_LIGHT)!;
+  return contrastRatio(fill, luminance(dark)) > onWhite ? LABEL_ON_LIGHT : LABEL_ON_DARK;
+}
+
+/** Lays a label out: lines split on "\n", line height 1.25 em, padding 0.4 em, top-left at `shape.at`. */
+export function textLayout(
+  shape: TextShape,
+  metrics: MarkupMetrics,
+  measure: MeasureText,
+): TextLayout {
+  const font = metrics.font(shape.size);
+  const lineHeight = font * 1.25;
+  const pad = font * 0.4;
+  const lines = shape.text.split("\n");
+  let widest = 0;
+  for (const line of lines) widest = Math.max(widest, measure(line, font));
+  // An empty label still gets a box wide enough to click and type into.
+  if (shape.text === "") widest = Math.max(widest, font * 0.5);
+  return {
+    box: {
+      x: shape.at.x,
+      y: shape.at.y,
+      w: widest + 2 * pad,
+      h: lines.length * lineHeight + 2 * pad,
+    },
+    lines,
+    font,
+    pad,
+    lineHeight,
+  };
+}
+
+/** The area a shape paints, stroke width included, in image px. */
+export function shapeBounds(shape: MarkupShape, metrics: MarkupMetrics, measure: MeasureText): Box {
+  switch (shape.kind) {
+    case "pen":
+    case "highlight": {
+      const width = strokeWidth(shape, metrics);
+      return boxAroundPoints(shape.points, width / 2);
+    }
+    case "arrow": {
+      const width = metrics.stroke(shape.size);
+      // The shaft needs half its width and the head reaches a full head length past its base.
+      const expand = width / 2 + arrowHead(width, metrics.unit).length;
+      return boxAroundPoints([shape.from, shape.to], expand);
+    }
+    case "rect":
+    case "ellipse": {
+      const half = metrics.stroke(shape.size) / 2;
+      const rect = toRect(shape.box);
+      return { x: rect.x - half, y: rect.y - half, w: rect.w + 2 * half, h: rect.h + 2 * half };
+    }
+    case "text":
+      return textLayout(shape, metrics, measure).box;
+    default: {
+      const unknown: never = shape;
+      throw new Error(`Unknown markup shape: ${JSON.stringify(unknown)}`);
+    }
+  }
+}
+
+/**
+ * Id of the topmost shape under `point` (later shapes are on top), or null. Strokes and arrows hit within half
+ * their width plus `tolerance` of the line; rectangles and ellipses within that of their outline (not their
+ * inside, so a box drawn around something never hides it); text anywhere in its label box.
+ */
+export function hitTest(
+  shapes: MarkupShape[],
+  point: Point,
+  tolerance: number,
+  metrics: MarkupMetrics,
+  measure: MeasureText,
+): string | null {
+  for (let i = shapes.length - 1; i >= 0; i -= 1) {
+    const shape = shapes[i]!;
+    if (hitShape(shape, point, tolerance, metrics, measure)) return shape.id;
+  }
+  return null;
+}
+
+/** The same shape moved by (dx, dy); a new object, the input is left alone. */
+export function moveShape<T extends MarkupShape>(shape: T, dx: number, dy: number): T {
+  const moved = (point: Point): Point => ({ x: point.x + dx, y: point.y + dy });
+  switch (shape.kind) {
+    case "pen":
+    case "highlight":
+      return { ...shape, points: shape.points.map(moved) };
+    case "arrow":
+      return { ...shape, from: moved(shape.from), to: moved(shape.to) };
+    case "rect":
+    case "ellipse":
+      return { ...shape, box: { ...shape.box, x: shape.box.x + dx, y: shape.box.y + dy } };
+    case "text":
+      return { ...shape, at: moved(shape.at) };
+    default: {
+      const unknown: never = shape;
+      throw new Error(`Unknown markup shape: ${JSON.stringify(unknown)}`);
+    }
+  }
+}
+
+/** The box between two drag points, any direction. `square` makes it w = h = the larger side, kept on the drag side. */
+export function normalizeBox(a: Point, b: Point, square: boolean): Box {
+  let dx = b.x - a.x;
+  let dy = b.y - a.y;
+  if (square) {
+    const side = Math.max(Math.abs(dx), Math.abs(dy));
+    // A zero delta keeps the positive direction, so a straight drag still makes a box.
+    dx = dx < 0 ? -side : side;
+    dy = dy < 0 ? -side : side;
+  }
+  return {
+    x: Math.min(a.x, a.x + dx),
+    y: Math.min(a.y, a.y + dy),
+    w: Math.abs(dx),
+    h: Math.abs(dy),
+  };
+}
+
+/** `to` moved onto the nearest 45° ray from `from`, keeping its distance. */
+export function snapAngle(from: Point, to: Point): Point {
+  const dx = to.x - from.x;
+  const dy = to.y - from.y;
+  const distance = Math.hypot(dx, dy);
+  if (distance === 0) return { x: to.x, y: to.y };
+  const step = Math.PI / 4;
+  const angle = Math.round(Math.atan2(dy, dx) / step) * step;
+  // cos(π/2) is 6e-17, not 0; snap those dust values so a snapped arrow lands exactly on the axis.
+  const cos = tidy(Math.cos(angle));
+  const sin = tidy(Math.sin(angle));
+  return { x: from.x + cos * distance, y: from.y + sin * distance };
+}
+
+/**
+ * Whether a just-drawn shape is worth keeping: a stroke must span `minSize` px in at least one direction, an
+ * arrow must be at least `minSize` long, a box must be at least `minSize` both ways, and text must have
+ * non-blank text.
+ */
+export function isMeaningful(shape: MarkupShape, minSize: number): boolean {
+  switch (shape.kind) {
+    case "pen":
+    case "highlight": {
+      if (shape.points.length === 0) return false;
+      const bounds = boxAroundPoints(shape.points, 0);
+      // A tap spans nothing either way; a flick spans one way and is kept.
+      return bounds.w >= minSize || bounds.h >= minSize;
+    }
+    case "arrow":
+      return Math.hypot(shape.to.x - shape.from.x, shape.to.y - shape.from.y) >= minSize;
+    case "rect":
+    case "ellipse": {
+      const rect = toRect(shape.box);
+      return rect.w >= minSize && rect.h >= minSize;
+    }
+    case "text":
+      return shape.text.trim().length > 0;
+    default: {
+      const unknown: never = shape;
+      throw new Error(`Unknown markup shape: ${JSON.stringify(unknown)}`);
+    }
+  }
+}
+
+/** The original's base name with `.png` or `.jpg` for the flattened type ("shot.jpeg" → "shot.png"). */
+export function flattenedName(name: string, type: "image/png" | "image/jpeg"): string {
+  const base = name.replace(KNOWN_EXTENSION, "");
+  return `${base || "image"}${type === "image/jpeg" ? ".jpg" : ".png"}`;
+}
+
+/** Undo history. `present` is what is on screen. */
+export type MarkupHistory = {
+  past: MarkupShape[][];
+  present: MarkupShape[];
+  future: MarkupShape[][];
+};
+
+export function createHistory(shapes: MarkupShape[]): MarkupHistory {
+  return { past: [], present: shapes, future: [] };
+}
+
+/** Pushes `next` as a new step and clears redo; returns `history` itself when `next === history.present`. */
+export function commitHistory(history: MarkupHistory, next: MarkupShape[]): MarkupHistory {
+  if (next === history.present) return history;
+  const past = [...history.past, history.present];
+  return {
+    past: past.length > HISTORY_LIMIT ? past.slice(past.length - HISTORY_LIMIT) : past,
+    present: next,
+    future: [],
+  };
+}
+
+/** Returns `history` itself when there is nothing to undo. */
+export function undoHistory(history: MarkupHistory): MarkupHistory {
+  if (history.past.length === 0) return history;
+  return {
+    past: history.past.slice(0, -1),
+    present: history.past[history.past.length - 1]!,
+    future: [history.present, ...history.future],
+  };
+}
+
+/** Returns `history` itself when there is nothing to redo. */
+export function redoHistory(history: MarkupHistory): MarkupHistory {
+  if (history.future.length === 0) return history;
+  const [present, ...future] = history.future;
+  return { past: [...history.past, history.present], present: present!, future };
+}
+
+// ----------------------------------------------------------------------------
+// Geometry and colour helpers (the stroke, arrow-head and box ones are shared with renderers)
+// ----------------------------------------------------------------------------
+
+/** `#rgb` / `#rrggbb` to 0–1 channels; null for anything else, including `rgba()` and named colours. */
+function parseHexColor(color: string): [number, number, number] | null {
+  const match = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(color.trim());
+  if (!match) return null;
+  const hex = match[1]!;
+  const channel = (index: number) => {
+    // Three-digit hex repeats each digit; six-digit takes the pair.
+    const pair =
+      hex.length === 3 ? `${hex[index]!}${hex[index]!}` : hex.slice(index * 2, index * 2 + 2);
+    return Number.parseInt(pair, 16) / 255;
+  };
+  return [channel(0), channel(1), channel(2)];
+}
+
+/** WCAG relative luminance of 0–1 sRGB channels. */
+function luminance([r, g, b]: [number, number, number]): number {
+  return 0.2126 * linearChannel(r) + 0.7152 * linearChannel(g) + 0.0722 * linearChannel(b);
+}
+
+/** WCAG contrast ratio between two relative luminances. */
+function contrastRatio(a: number, b: number): number {
+  return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+}
+
+/** One sRGB channel (0–1) to its linear-light value, per WCAG relative luminance. */
+function linearChannel(channel: number): number {
+  return channel <= 0.03928 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4;
+}
+
+/** Drops floating-point dust so snapped rays land on exact axis values. */
+function tidy(value: number): number {
+  return Math.abs(value) < 1e-12 ? 0 : value;
+}
+
+/** Width a stroke paints, before any hit tolerance. Highlighter is wider by design. */
+export function strokeWidth(shape: StrokeShape, metrics: MarkupMetrics): number {
+  return shape.kind === "highlight" ? metrics.highlight(shape.size) : metrics.stroke(shape.size);
+}
+
+/** Arrow head length and half width, both from the shaft width and the image's unit. */
+export function arrowHead(lineWidth: number, unit: number): { length: number; halfWidth: number } {
+  const length = Math.max(4 * lineWidth, 10 * unit);
+  return { length, halfWidth: length * 0.55 };
+}
+
+/** A box as left/top with non-negative sides, so negative widths from odd input still draw. */
+export function toRect(box: Box): Box {
+  return {
+    x: Math.min(box.x, box.x + box.w),
+    y: Math.min(box.y, box.y + box.h),
+    w: Math.abs(box.w),
+    h: Math.abs(box.h),
+  };
+}
+
+/** The bounding box of `points`, grown by `expand` on every side. */
+function boxAroundPoints(points: Point[], expand: number): Box {
+  if (points.length === 0) return { x: 0, y: 0, w: 0, h: 0 };
+  let left = Infinity;
+  let top = Infinity;
+  let right = -Infinity;
+  let bottom = -Infinity;
+  for (const { x, y } of points) {
+    left = Math.min(left, x);
+    top = Math.min(top, y);
+    right = Math.max(right, x);
+    bottom = Math.max(bottom, y);
+  }
+  return {
+    x: left - expand,
+    y: top - expand,
+    w: right - left + 2 * expand,
+    h: bottom - top + 2 * expand,
+  };
+}
+
+/** Distance from `point` to the closest spot on segment `a`–`b`. */
+function distanceToSegment(point: Point, a: Point, b: Point): number {
+  const dx = b.x - a.x;
+  const dy = b.y - a.y;
+  const lengthSquared = dx * dx + dy * dy;
+  if (lengthSquared === 0) return Math.hypot(point.x - a.x, point.y - a.y);
+  const t = Math.max(0, Math.min(1, ((point.x - a.x) * dx + (point.y - a.y) * dy) / lengthSquared));
+  return Math.hypot(point.x - (a.x + t * dx), point.y - (a.y + t * dy));
+}
+
+/** Distance from `point` to a pen/highlighter stroke's polyline. */
+function distanceToStroke(points: Point[], point: Point): number {
+  if (points.length === 0) return Infinity;
+  if (points.length === 1) return Math.hypot(point.x - points[0]!.x, point.y - points[0]!.y);
+  let best = Infinity;
+  for (let i = 0; i + 1 < points.length; i += 1) {
+    best = Math.min(best, distanceToSegment(point, points[i]!, points[i + 1]!));
+  }
+  return best;
+}
+
+/** Distance from `point` to a rectangle's outline; a zero-width box is its own segment. */
+function distanceToRectOutline(point: Point, box: Box): number {
+  const rect = toRect(box);
+  const corners: Point[] = [
+    { x: rect.x, y: rect.y },
+    { x: rect.x + rect.w, y: rect.y },
+    { x: rect.x + rect.w, y: rect.y + rect.h },
+    { x: rect.x, y: rect.y + rect.h },
+  ];
+  let best = Infinity;
+  for (let i = 0; i < 4; i += 1) {
+    best = Math.min(best, distanceToSegment(point, corners[i]!, corners[(i + 1) % 4]!));
+  }
+  return best;
+}
+
+/** Distance from `point` to an ellipse's outline, approximated from the normalised radius. */
+function distanceToEllipseOutline(point: Point, box: Box): number {
+  const rect = toRect(box);
+  const rx = rect.w / 2;
+  const ry = rect.h / 2;
+  const cx = rect.x + rx;
+  const cy = rect.y + ry;
+  if (rx < 1e-6 || ry < 1e-6) {
+    // A collapsed ellipse is a line (or a point); its outline is that segment.
+    return distanceToSegment(point, { x: cx - rx, y: cy - ry }, { x: cx + rx, y: cy + ry });
+  }
+  const nx = (point.x - cx) / rx;
+  const ny = (point.y - cy) / ry;
+  return Math.abs(Math.hypot(nx, ny) - 1) * Math.min(rx, ry);
+}
+
+/** Whether `point` lands on `shape`, given the tolerance the editor adds for touch and imprecision. */
+function hitShape(
+  shape: MarkupShape,
+  point: Point,
+  tolerance: number,
+  metrics: MarkupMetrics,
+  measure: MeasureText,
+): boolean {
+  switch (shape.kind) {
+    case "pen":
+    case "highlight": {
+      const reach = strokeWidth(shape, metrics) / 2 + tolerance;
+      return distanceToStroke(shape.points, point) <= reach;
+    }
+    case "arrow": {
+      const reach = metrics.stroke(shape.size) / 2 + tolerance;
+      return distanceToSegment(point, shape.from, shape.to) <= reach;
+    }
+    case "rect": {
+      const reach = metrics.stroke(shape.size) / 2 + tolerance;
+      return distanceToRectOutline(point, shape.box) <= reach;
+    }
+    case "ellipse": {
+      const reach = metrics.stroke(shape.size) / 2 + tolerance;
+      return distanceToEllipseOutline(point, shape.box) <= reach;
+    }
+    case "text": {
+      const { box } = textLayout(shape, metrics, measure);
+      return (
+        point.x >= box.x - tolerance &&
+        point.x <= box.x + box.w + tolerance &&
+        point.y >= box.y - tolerance &&
+        point.y <= box.y + box.h + tolerance
+      );
+    }
+    default: {
+      const unknown: never = shape;
+      throw new Error(`Unknown markup shape: ${JSON.stringify(unknown)}`);
+    }
+  }
+}