@adecore/drawing 0.0.1 → 0.17.0-beta.1

package/src/geometry.ts

@@ -0,0 +1,273 @@
+import type { DrawingElement } from './protocol.ts';
+
+export interface Point {
+    x: number;
+    y: number;
+}
+
+export interface Rect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+
+export const RESIZE_HANDLES = ['nw', 'n', 'ne', 'e', 'se', 's', 'sw', 'w'] as const;
+export type ResizeHandle = (typeof RESIZE_HANDLES)[number];
+
+export function boundsOf(element: Pick<DrawingElement, 'x' | 'y' | 'w' | 'h'>): Rect {
+    return { x: element.x, y: element.y, w: element.w, h: element.h };
+}
+
+export function centerOf(rect: Rect): Point {
+    return { x: rect.x + rect.w / 2, y: rect.y + rect.h / 2 };
+}
+
+/* A point on the whole pixel, for a layout that lines its boxes and its lines up on a pixel grid. */
+export function roundPoint(point: Point): Point {
+    return { x: Math.round(point.x), y: Math.round(point.y) };
+}
+
+export function rotatePoint(point: Point, around: Point, angle: number): Point {
+    if (angle === 0) {
+        return point;
+    }
+    const cos = Math.cos(angle);
+    const sin = Math.sin(angle);
+    const dx = point.x - around.x;
+    const dy = point.y - around.y;
+    return { x: around.x + dx * cos - dy * sin, y: around.y + dx * sin + dy * cos };
+}
+
+/* A point in the element's own frame, so every hit test can pretend nothing is turned. */
+export function toLocal(element: DrawingElement, point: Point): Point {
+    return rotatePoint(point, centerOf(boundsOf(element)), -(element.angle ?? 0));
+}
+
+export function unionOf(rects: readonly Rect[]): Rect | null {
+    if (rects.length === 0) {
+        return null;
+    }
+    let left = Infinity;
+    let top = Infinity;
+    let right = -Infinity;
+    let bottom = -Infinity;
+    for (const rect of rects) {
+        left = Math.min(left, rect.x, rect.x + rect.w);
+        top = Math.min(top, rect.y, rect.y + rect.h);
+        right = Math.max(right, rect.x, rect.x + rect.w);
+        bottom = Math.max(bottom, rect.y, rect.y + rect.h);
+    }
+    return { x: left, y: top, w: right - left, h: bottom - top };
+}
+
+export function boundsOfElements(elements: readonly DrawingElement[]): Rect | null {
+    return unionOf(elements.map(boundsOf));
+}
+
+export function intersects(a: Rect, b: Rect): boolean {
+    return a.x < b.x + b.w && a.x + a.w > b.x && a.y < b.y + b.h && a.y + a.h > b.y;
+}
+
+export function rectFromPoints(from: Point, to: Point): Rect {
+    return {
+        x: Math.min(from.x, to.x),
+        y: Math.min(from.y, to.y),
+        w: Math.abs(to.x - from.x),
+        h: Math.abs(to.y - from.y)
+    };
+}
+
+export function distanceToSegment(point: Point, a: Point, b: Point): number {
+    const dx = b.x - a.x;
+    const dy = b.y - a.y;
+    const length = dx * dx + dy * dy;
+    if (length === 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) / length));
+    return Math.hypot(point.x - (a.x + t * dx), point.y - (a.y + t * dy));
+}
+
+export function absolutePoints(element: DrawingElement): Point[] {
+    if (element.kind !== 'line' && element.kind !== 'freehand') {
+        return [];
+    }
+    return element.points.map(([x, y]) => ({ x: element.x + x, y: element.y + y }));
+}
+
+function isFilled(element: DrawingElement): boolean {
+    return element.fill !== undefined && element.fill !== 'none';
+}
+
+function cornersOfDiamond(rect: Rect): Point[] {
+    return [
+        { x: rect.x + rect.w / 2, y: rect.y },
+        { x: rect.x + rect.w, y: rect.y + rect.h / 2 },
+        { x: rect.x + rect.w / 2, y: rect.y + rect.h },
+        { x: rect.x, y: rect.y + rect.h / 2 }
+    ];
+}
+
+function insidePolygon(point: Point, polygon: readonly Point[]): boolean {
+    let inside = false;
+    for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i++) {
+        const a = polygon[i]!;
+        const b = polygon[j]!;
+        if (a.y > point.y !== b.y > point.y && point.x < ((b.x - a.x) * (point.y - a.y)) / (b.y - a.y) + a.x) {
+            inside = !inside;
+        }
+    }
+    return inside;
+}
+
+function nearPolygon(point: Point, polygon: readonly Point[], tolerance: number): boolean {
+    return polygon.some((corner, index) => distanceToSegment(point, corner, polygon[(index + 1) % polygon.length]!) <= tolerance);
+}
+
+function nearPolyline(point: Point, points: readonly Point[], tolerance: number): boolean {
+    if (points.length === 1) {
+        return Math.hypot(point.x - points[0]!.x, point.y - points[0]!.y) <= tolerance;
+    }
+    return points.slice(0, -1).some((from, index) => distanceToSegment(point, from, points[index + 1]!) <= tolerance);
+}
+
+function insideRect(point: Point, rect: Rect): boolean {
+    return point.x >= rect.x && point.x <= rect.x + rect.w && point.y >= rect.y && point.y <= rect.y + rect.h;
+}
+
+/*
+ * Whether a point lands on an element. A shape with a fill is hit anywhere inside it, one without
+ * only near its outline, which is what makes an empty rectangle easy to draw inside of.
+ */
+export function hitsElement(element: DrawingElement, point: Point, tolerance: number): boolean {
+    const local = toLocal(element, point);
+    const rect = boundsOf(element);
+    const reach = Math.max(tolerance, element.strokeWidth);
+    switch (element.kind) {
+        // Both are their own sheet: anywhere on it is on them.
+        case 'text':
+        case 'note':
+            return insideRect(local, rect);
+        case 'rect': {
+            const corners = [
+                { 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 }
+            ];
+            return isFilled(element) ? insideRect(local, rect) : nearPolygon(local, corners, reach);
+        }
+        case 'diamond': {
+            const corners = cornersOfDiamond(rect);
+            return isFilled(element) ? insidePolygon(local, corners) : nearPolygon(local, corners, reach);
+        }
+        case 'ellipse': {
+            const center = centerOf(rect);
+            const rx = Math.max(rect.w / 2, 0.01);
+            const ry = Math.max(rect.h / 2, 0.01);
+            const distance = Math.hypot((local.x - center.x) / rx, (local.y - center.y) / ry);
+            if (isFilled(element)) {
+                return distance <= 1;
+            }
+            return Math.abs(distance - 1) <= reach / Math.min(rx, ry);
+        }
+        case 'line':
+        case 'freehand':
+            return nearPolyline(local, absolutePoints(element), reach);
+    }
+}
+
+export function elementAt(elements: readonly DrawingElement[], point: Point, tolerance: number): DrawingElement | undefined {
+    for (let i = elements.length - 1; i >= 0; i--) {
+        const element = elements[i]!;
+        if (!element.locked && hitsElement(element, point, tolerance)) {
+            return element;
+        }
+    }
+    return undefined;
+}
+
+export function elementsIn(elements: readonly DrawingElement[], rect: Rect): DrawingElement[] {
+    return elements.filter((element) => !element.locked && intersects(boundsOf(element), rect));
+}
+
+export function handlePoint(rect: Rect, handle: ResizeHandle): Point {
+    const x = handle.includes('w') ? rect.x : handle.includes('e') ? rect.x + rect.w : rect.x + rect.w / 2;
+    const y = handle.startsWith('n') ? rect.y : handle.startsWith('s') ? rect.y + rect.h : rect.y + rect.h / 2;
+    return { x, y };
+}
+
+/*
+ * The box a resize drag makes: the handle follows the pointer and the side across from it stays
+ * put. `aspect` keeps the proportions, which is what Shift asks for.
+ */
+export function resizeRect(rect: Rect, handle: ResizeHandle, point: Point, aspect = false): Rect {
+    let { x, y, w, h } = rect;
+    if (handle.includes('w')) {
+        w = rect.x + rect.w - point.x;
+        x = point.x;
+    }
+    if (handle.includes('e')) {
+        w = point.x - rect.x;
+    }
+    if (handle.startsWith('n')) {
+        h = rect.y + rect.h - point.y;
+        y = point.y;
+    }
+    if (handle.startsWith('s')) {
+        h = point.y - rect.y;
+    }
+    if (aspect && rect.w > 0 && rect.h > 0) {
+        const ratio = rect.h / rect.w;
+        // A side handle moves one dimension, which sets the other; a corner follows the smaller pull.
+        const width = handle === 'e' || handle === 'w' ? w : handle === 'n' || handle === 's' ? h / ratio : Math.abs(w) < Math.abs(h / ratio) ? w : h / ratio;
+        const height = width * ratio;
+        if (handle.includes('w')) {
+            x = rect.x + rect.w - width;
+        }
+        if (handle.startsWith('n')) {
+            y = rect.y + rect.h - height;
+        }
+        w = width;
+        h = height;
+    }
+    return { x, y, w, h };
+}
+
+export function scaleElement(element: DrawingElement, from: Rect, to: Rect): DrawingElement {
+    const scaleX = from.w === 0 ? 1 : to.w / from.w;
+    const scaleY = from.h === 0 ? 1 : to.h / from.h;
+    const placed = {
+        ...element,
+        x: to.x + (element.x - from.x) * scaleX,
+        y: to.y + (element.y - from.y) * scaleY,
+        w: element.w * scaleX,
+        h: element.h * scaleY
+    };
+    if (placed.kind === 'line') {
+        return { ...placed, points: placed.points.map(([x, y]) => [x * scaleX, y * scaleY] as [number, number]) };
+    }
+    if (placed.kind === 'freehand') {
+        return { ...placed, points: placed.points.map(([x, y, pressure]) => [x * scaleX, y * scaleY, pressure] as [number, number, number?]) };
+    }
+    if (placed.kind === 'text') {
+        // From here on the box is the person's, so typing no longer refits it.
+        return { ...placed, sized: true };
+    }
+    return placed;
+}
+
+export function arrowHead(tip: Point, from: Point, size: number): [Point, Point][] {
+    const angle = Math.atan2(tip.y - from.y, tip.x - from.x);
+    const spread = Math.PI / 7;
+    return [
+        [tip, { x: tip.x - size * Math.cos(angle - spread), y: tip.y - size * Math.sin(angle - spread) }],
+        [tip, { x: tip.x - size * Math.cos(angle + spread), y: tip.y - size * Math.sin(angle + spread) }]
+    ];
+}
+
+/* How long an arrow head is for a given stroke: heavier lines carry a bigger head. */
+export function arrowHeadSize(strokeWidth: number): number {
+    return 12 + strokeWidth * 4;
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+export {
+    type Point,
+    type Rect,
+    RESIZE_HANDLES,
+    type ResizeHandle,
+    boundsOf,
+    centerOf,
+    roundPoint,
+    rotatePoint,
+    toLocal,
+    unionOf,
+    boundsOfElements,
+    intersects,
+    rectFromPoints,
+    distanceToSegment,
+    absolutePoints,
+    hitsElement,
+    elementAt,
+    elementsIn,
+    handlePoint,
+    resizeRect,
+    scaleElement,
+    arrowHead,
+    arrowHeadSize
+} from './geometry.ts';
+export { type ElementPath, outlineToPath, freehandOutline, pathsOfElement } from './paths.ts';
+export { readingOrder } from './reading-order.ts';
+export { type SvgOptions, DEFAULT_SVG_MARGIN, DEFAULT_PALETTE, DEFAULT_PAPER, DEFAULT_EDGE, toSvg } from './svg.ts';
+export {
+    LINE_HEIGHT,
+    DEFAULT_FONT_STACKS,
+    type WrittenElement,
+    NOTE_PADDING,
+    NOTE_RADIUS,
+    writingFrameOf,
+    textLines,
+    type MeasureLine,
+    approximateMeasure,
+    wrapLines,
+    linesOf,
+    fontOf
+} from './text.ts';

package/src/paths.ts

@@ -0,0 +1,162 @@
+import type { DrawingElement } from './protocol.ts';
+import { getStroke } from 'perfect-freehand';
+// Rough's unbundled modules use extensionless imports; its package entry also runs in Node.
+import rough from 'roughjs';
+import type { RoughGenerator } from 'roughjs/bin/generator.js';
+import type { Options } from 'roughjs/bin/core.js';
+import { arrowHead, arrowHeadSize, type Point } from './geometry.ts';
+import { NOTE_RADIUS } from './text.ts';
+
+/*
+ * What a painter has to do with one path. The colors are not in here: a drawing names palette
+ * colors and the painter resolves them against the theme it is drawing in.
+ */
+export interface ElementPath {
+    d: string;
+    /* `stroke` outlines in the stroke color, `fill` fills in the fill color, `ink` fills in the stroke color. */
+    role: 'stroke' | 'fill' | 'ink';
+    strokeWidth: number;
+    /* Whole units on and off, or null for a solid line. */
+    dash: number[] | null;
+}
+
+// Sentinels, not colors: rough hands them back on every path, which is how a path says what it is.
+const STROKE = '#000001';
+const FILL = '#000002';
+
+let generator: RoughGenerator | undefined;
+
+function drawingGenerator(): RoughGenerator {
+    return (generator ??= rough.generator());
+}
+
+function dashOf(element: DrawingElement): number[] | null {
+    if (element.strokeStyle === 'dashed') {
+        return [element.strokeWidth * 4, element.strokeWidth * 4];
+    }
+    if (element.strokeStyle === 'dotted') {
+        return [element.strokeWidth, element.strokeWidth * 3];
+    }
+    return null;
+}
+
+/* Architect, Artist, Cartoonist. Absent reads as Artist, which is what a hand-written file gets. */
+function roughnessOf(element: DrawingElement): Pick<Options, 'roughness' | 'bowing' | 'disableMultiStroke'> {
+    switch (element.roughness ?? 1) {
+        case 0:
+            return { roughness: 0, bowing: 0, disableMultiStroke: true };
+        case 2:
+            return { roughness: 2.5, bowing: 2 };
+        default:
+            return { roughness: 1, bowing: 1 };
+    }
+}
+
+function optionsOf(element: DrawingElement): Options {
+    return {
+        seed: element.seed + 1,
+        stroke: STROKE,
+        strokeWidth: element.strokeWidth,
+        ...roughnessOf(element),
+        ...(element.fill && element.fill !== 'none'
+            ? { fill: FILL, fillStyle: element.fill === 'solid' ? 'solid' : 'hachure', fillWeight: element.strokeWidth / 2, hachureGap: 8 }
+            : {})
+    };
+}
+
+// Rough has no rounded-rectangle primitive.
+function roundedRectPath(w: number, h: number, radius: number): string {
+    const r = Math.min(radius, w / 2, h / 2);
+    return `M ${r} 0 L ${w - r} 0 Q ${w} 0 ${w} ${r} L ${w} ${h - r} Q ${w} ${h} ${w - r} ${h} L ${r} ${h} Q 0 ${h} 0 ${h - r} L 0 ${r} Q 0 0 ${r} 0 Z`;
+}
+
+export function outlineToPath(outline: readonly (readonly number[])[]): string {
+    if (outline.length === 0) {
+        return '';
+    }
+    const [first, ...rest] = outline;
+    return `M ${first![0]} ${first![1]} ${rest.map((point) => `L ${point[0]} ${point[1]}`).join(' ')} Z`;
+}
+
+export function freehandOutline(element: DrawingElement & { kind: 'freehand' }): string {
+    const points = element.points.map(([x, y, pressure]) => [x, y, pressure ?? 0.5] as [number, number, number]);
+    const outline = getStroke(points, {
+        size: element.strokeWidth * 4 + 2,
+        thinning: 0.6,
+        smoothing: 0.5,
+        streamline: 0.5,
+        // A pressure of exactly 0.5 on every point is a mouse; the stroke gets its taper from speed.
+        simulatePressure: element.points.every((point) => point[2] === undefined)
+    });
+    return outlineToPath(outline);
+}
+
+function linesToPath(segments: readonly [Point, Point][]): string {
+    return segments.map(([from, to]) => `M ${from.x} ${from.y} L ${to.x} ${to.y}`).join(' ');
+}
+
+/*
+ * One element as paths in its own frame: the origin is the element's own (x, y), so the painter
+ * translates and turns, and a path can be cached until the element's shape itself changes.
+ */
+export function pathsOfElement(element: DrawingElement): ElementPath[] {
+    if (element.kind === 'text') {
+        return [];
+    }
+    // A note is a sheet of paper, not a drawn shape: no wobble, and an edge of its own paper color.
+    if (element.kind === 'note') {
+        const d = roundedRectPath(element.w, element.h, NOTE_RADIUS);
+        return [
+            { d, role: 'fill', strokeWidth: 0, dash: null },
+            { d, role: 'stroke', strokeWidth: element.strokeWidth, dash: null }
+        ];
+    }
+    const options = optionsOf(element);
+    const dash = dashOf(element);
+    if (element.kind === 'freehand') {
+        return [{ d: freehandOutline(element), role: 'ink', strokeWidth: 0, dash: null }];
+    }
+    const generator = drawingGenerator();
+    const drawable = (() => {
+        switch (element.kind) {
+            case 'rect':
+                return element.radius
+                    ? generator.path(roundedRectPath(element.w, element.h, element.radius), options)
+                    : generator.rectangle(0, 0, element.w, element.h, options);
+            case 'diamond':
+                return generator.polygon(
+                    [
+                        [element.w / 2, 0],
+                        [element.w, element.h / 2],
+                        [element.w / 2, element.h],
+                        [0, element.h / 2]
+                    ],
+                    options
+                );
+            case 'ellipse':
+                return generator.ellipse(element.w / 2, element.h / 2, element.w, element.h, options);
+            case 'line':
+                return generator.linearPath(
+                    element.points.map(([x, y]) => [x, y] as [number, number]),
+                    options
+                );
+        }
+    })();
+    const paths: ElementPath[] = generator.toPaths(drawable).map((path) => ({
+        d: path.d,
+        role: path.fill === FILL ? 'fill' : path.stroke === FILL ? 'fill' : 'stroke',
+        strokeWidth: path.strokeWidth,
+        dash: path.stroke === STROKE ? dash : null
+    }));
+    if (element.kind !== 'line') {
+        return paths;
+    }
+    const points = element.points.map(([x, y]) => ({ x, y }));
+    const size = arrowHeadSize(element.strokeWidth);
+    const heads: [Point, Point][] = [
+        ...(element.arrowEnd ? arrowHead(points.at(-1)!, points.at(-2)!, size) : []),
+        ...(element.arrowStart ? arrowHead(points[0]!, points[1]!, size) : [])
+    ];
+    // The head is always solid: a dashed arrow still points at something.
+    return heads.length === 0 ? paths : [...paths, { d: linesToPath(heads), role: 'stroke', strokeWidth: element.strokeWidth, dash: null }];
+}

package/src/protocol.ts

@@ -0,0 +1,130 @@
+import { z } from 'zod';
+
+export const DrawingFontSchema = z.enum(['hand', 'sans', 'mono']);
+export type DrawingFont = z.infer<typeof DrawingFontSchema>;
+
+/*
+ * Palette names keep a document independent of the theme that renders it.
+ */
+export const DrawingColorSchema = z.enum(['ink', 'muted', 'accent', 'red', 'orange', 'yellow', 'green', 'blue', 'purple', 'pink']);
+export type DrawingColor = z.infer<typeof DrawingColorSchema>;
+
+/* In the order the color menu shows them. */
+export const DRAWING_COLORS = DrawingColorSchema.options;
+
+export const DrawingFillSchema = z.enum(['none', 'solid', 'hachure']);
+export type DrawingFill = z.infer<typeof DrawingFillSchema>;
+
+export const DrawingStrokeStyleSchema = z.enum(['solid', 'dashed', 'dotted']);
+export type DrawingStrokeStyle = z.infer<typeof DrawingStrokeStyleSchema>;
+
+export const DrawingStrokeWidthSchema = z.union([z.literal(1), z.literal(2), z.literal(4)]);
+export type DrawingStrokeWidth = z.infer<typeof DrawingStrokeWidthSchema>;
+
+/* Architect, Artist, Cartoonist. Absent reads as 1, so a file written by hand looks hand drawn. */
+export const DrawingRoughnessSchema = z.union([z.literal(0), z.literal(1), z.literal(2)]);
+export type DrawingRoughness = z.infer<typeof DrawingRoughnessSchema>;
+
+export const DrawingAlignSchema = z.enum(['left', 'center', 'right']);
+export type DrawingAlign = z.infer<typeof DrawingAlignSchema>;
+
+export const DRAWING_TEXT_SIZE_MIN = 12;
+export const DRAWING_TEXT_SIZE_MAX = 96;
+
+const ElementBaseSchema = z.object({
+    id: z.string().min(1),
+    x: z.number(),
+    y: z.number(),
+    w: z.number(),
+    h: z.number(),
+    // Radians around the center; absent means 0.
+    angle: z.number().optional(),
+    stroke: DrawingColorSchema,
+    strokeWidth: DrawingStrokeWidthSchema,
+    strokeStyle: DrawingStrokeStyleSchema.optional(),
+    fill: DrawingFillSchema.optional(),
+    fillColor: DrawingColorSchema.optional(),
+    roughness: DrawingRoughnessSchema.optional(),
+    // Keeps the wobble the same on every render, on every machine.
+    seed: z.number().int().nonnegative(),
+    locked: z.boolean().optional()
+});
+
+export const DrawingElementSchema = z.discriminatedUnion('kind', [
+    ElementBaseSchema.extend({ kind: z.literal('rect'), radius: z.number().nonnegative().optional() }),
+    ElementBaseSchema.extend({ kind: z.literal('diamond') }),
+    ElementBaseSchema.extend({ kind: z.literal('ellipse') }),
+    // Points are relative to (x, y) and their bounds are the box. An arrow is a line with a head.
+    ElementBaseSchema.extend({
+        kind: z.literal('line'),
+        points: z.array(z.tuple([z.number(), z.number()])).min(2),
+        arrowStart: z.boolean().optional(),
+        arrowEnd: z.boolean().optional()
+    }),
+    // A stroke: relative points with an optional pressure, drawn through perfect-freehand.
+    ElementBaseSchema.extend({
+        kind: z.literal('freehand'),
+        points: z.array(z.tuple([z.number(), z.number(), z.number().optional()])).min(1)
+    }),
+    ElementBaseSchema.extend({
+        kind: z.literal('text'),
+        text: z.string(),
+        size: z.number().int().min(DRAWING_TEXT_SIZE_MIN).max(DRAWING_TEXT_SIZE_MAX),
+        // Absent means 'hand', the default a drawing is written in.
+        font: DrawingFontSchema.optional(),
+        align: DrawingAlignSchema.optional(),
+        // Set once the box was dragged by hand; absent means the box follows the glyphs.
+        sized: z.boolean().optional()
+    }),
+    /*
+     * A sticky note: a sheet of paper in `fillColor` with the text written on it. It is one element
+     * rather than a shape with a text on top, so moving the note takes what it says along.
+     */
+    ElementBaseSchema.extend({
+        kind: z.literal('note'),
+        text: z.string(),
+        size: z.number().int().min(DRAWING_TEXT_SIZE_MIN).max(DRAWING_TEXT_SIZE_MAX),
+        font: DrawingFontSchema.optional(),
+        align: DrawingAlignSchema.optional()
+    })
+]);
+export type DrawingElement = z.infer<typeof DrawingElementSchema>;
+export type DrawingElementKind = DrawingElement['kind'];
+
+export const DRAWING_VERSION = 1;
+
+export const DrawingContentSchema = z.object({
+    // In stacking order, back to front.
+    elements: z.array(DrawingElementSchema)
+});
+export type DrawingContent = z.infer<typeof DrawingContentSchema>;
+
+export const DrawingDocumentSchema = DrawingContentSchema.extend({
+    version: z.literal(DRAWING_VERSION),
+    // Goes up by one on every write; a save that names an older rev is a conflict.
+    rev: z.number().int().nonnegative()
+});
+export type DrawingDocument = z.infer<typeof DrawingDocumentSchema>;
+
+export const EMPTY_DRAWING: DrawingDocument = { version: 1, rev: 0, elements: [] };
+
+/* One version so far, so reading is a parse. A file that is not a drawing at all reads as null. */
+export function migrateDrawing(value: unknown): DrawingDocument | null {
+    const parsed = DrawingDocumentSchema.safeParse(value);
+    return parsed.success ? parsed.data : null;
+}
+
+/*
+ * Element ids never leave their own file, so they only have to be unique inside it. A repeat would
+ * make selection and hit tests pick two elements at once, so such a file is refused by name.
+ */
+export function duplicateElementIdIn(elements: DrawingElement[]): string | null {
+    const seen = new Set<string>();
+    for (const element of elements) {
+        if (seen.has(element.id)) {
+            return element.id;
+        }
+        seen.add(element.id);
+    }
+    return null;
+}

package/src/reading-order.ts

@@ -0,0 +1,82 @@
+import type { DrawingElement } from './protocol.ts';
+import { absolutePoints, boundsOf, centerOf, hitsElement, type Point } from './geometry.ts';
+
+/* Two texts within this many units of each other are on the same line and read left to right. */
+const ROW_TOLERANCE = 24;
+
+/* How far from an arrow's end a label may sit and still be what the arrow points at. */
+const LABEL_REACH = 48;
+
+function labelOf(element: DrawingElement): string | null {
+    return element.kind === 'text' || element.kind === 'note' ? element.text.trim() || null : null;
+}
+
+/* A shape says what it is by the text inside it, which is how a box on a diagram is named. */
+function labelInside(element: DrawingElement, elements: readonly DrawingElement[]): string | null {
+    for (const candidate of elements) {
+        if (candidate.kind !== 'text' || candidate.id === element.id) {
+            continue;
+        }
+        const center = centerOf(boundsOf(candidate));
+        if (hitsElement({ ...element, fill: 'solid' }, center, 0)) {
+            return labelOf(candidate);
+        }
+    }
+    return null;
+}
+
+/* What an arrow points at: the text at that end, or the shape there and the text it holds. */
+function labelAt(point: Point, elements: readonly DrawingElement[], arrowId: string): string | null {
+    let best: { label: string; distance: number } | null = null;
+    for (const element of elements) {
+        if (element.id === arrowId || element.kind === 'line' || element.kind === 'freehand') {
+            continue;
+        }
+        const center = centerOf(boundsOf(element));
+        const distance = Math.hypot(center.x - point.x, center.y - point.y);
+        const inside = hitsElement({ ...element, fill: 'solid' }, point, LABEL_REACH);
+        if (!inside && distance > LABEL_REACH) {
+            continue;
+        }
+        const label = labelOf(element) ?? labelInside(element, elements);
+        if (label && (!best || distance < best.distance)) {
+            best = { label, distance };
+        }
+    }
+    return best?.label ?? null;
+}
+
+/*
+ * A drawing as lines an agent can read: the texts top to bottom and left to right, then every
+ * arrow as the two things it connects. A diagram becomes a list without anyone looking at it.
+ */
+export function readingOrder(elements: readonly DrawingElement[]): string[] {
+    // A row is measured from its top text, so a staircase of texts cannot chain into one long line.
+    const rows: DrawingElement[][] = [];
+    const labeled = elements.filter((element) => labelOf(element) !== null).sort((left, right) => left.y - right.y || left.x - right.x);
+    for (const element of labeled) {
+        const row = rows.at(-1);
+        if (row && element.y - row[0]!.y <= ROW_TOLERANCE) {
+            row.push(element);
+        } else {
+            rows.push([element]);
+        }
+    }
+    const texts = rows.flatMap((row) => row.sort((left, right) => left.x - right.x || left.y - right.y)).map((element) => labelOf(element)!);
+
+    const arrows: string[] = [];
+    for (const element of elements) {
+        if (element.kind !== 'line' || (!element.arrowEnd && !element.arrowStart)) {
+            continue;
+        }
+        const points = absolutePoints(element);
+        const from = labelAt(points[0]!, elements, element.id);
+        const to = labelAt(points.at(-1)!, elements, element.id);
+        if (!from || !to || from === to) {
+            continue;
+        }
+        // An arrow that only has a head at its start reads the other way around.
+        arrows.push(element.arrowEnd ? `${from} -> ${to}` : `${to} -> ${from}`);
+    }
+    return [...texts, ...arrows];
+}