@adecore/drawing 0.0.1 → 0.17.0-beta.1

package/dist/protocol.js

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+export const DrawingFontSchema = z.enum(['hand', 'sans', 'mono']);
+/*
+ * 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']);
+/* In the order the color menu shows them. */
+export const DRAWING_COLORS = DrawingColorSchema.options;
+export const DrawingFillSchema = z.enum(['none', 'solid', 'hachure']);
+export const DrawingStrokeStyleSchema = z.enum(['solid', 'dashed', 'dotted']);
+export const DrawingStrokeWidthSchema = z.union([z.literal(1), z.literal(2), z.literal(4)]);
+/* 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 const DrawingAlignSchema = z.enum(['left', 'center', 'right']);
+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 const DRAWING_VERSION = 1;
+export const DrawingContentSchema = z.object({
+    // In stacking order, back to front.
+    elements: z.array(DrawingElementSchema)
+});
+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 const EMPTY_DRAWING = { 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) {
+    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) {
+    const seen = new Set();
+    for (const element of elements) {
+        if (seen.has(element.id)) {
+            return element.id;
+        }
+        seen.add(element.id);
+    }
+    return null;
+}

package/dist/reading-order.d.ts

@@ -0,0 +1,2 @@
+import type { DrawingElement } from './protocol.ts';
+export declare function readingOrder(elements: readonly DrawingElement[]): string[];

package/dist/reading-order.js

@@ -0,0 +1,75 @@
+import { absolutePoints, boundsOf, centerOf, hitsElement } from './geometry.js';
+/* 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) {
+    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, elements) {
+    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, elements, arrowId) {
+    let best = 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) {
+    // A row is measured from its top text, so a staircase of texts cannot chain into one long line.
+    const rows = [];
+    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 = [];
+    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];
+}

package/dist/svg.d.ts

@@ -0,0 +1,16 @@
+import type { DrawingColor, DrawingElement, DrawingFont } from './protocol.ts';
+import { type MeasureLine, type WrittenElement } from './text.ts';
+export interface SvgOptions {
+    palette: Record<DrawingColor, string>;
+    background?: string | null;
+    margin?: number;
+    fonts?: Partial<Record<DrawingFont, string>>;
+    paper?: Record<DrawingColor, string>;
+    edge?: Record<DrawingColor, string>;
+    measure?: (element: WrittenElement) => MeasureLine;
+}
+export declare const DEFAULT_SVG_MARGIN = 32;
+export declare const DEFAULT_PALETTE: Record<DrawingColor, string>;
+export declare const DEFAULT_PAPER: Record<DrawingColor, string>;
+export declare const DEFAULT_EDGE: Record<DrawingColor, string>;
+export declare function toSvg(elements: readonly DrawingElement[], options: SvgOptions): string;

package/dist/svg.js

@@ -0,0 +1,109 @@
+import { boundsOfElements, centerOf, boundsOf } from './geometry.js';
+import { pathsOfElement } from './paths.js';
+import { DEFAULT_FONT_STACKS, LINE_HEIGHT, approximateMeasure, fontOf, linesOf, writingFrameOf } from './text.js';
+export const DEFAULT_SVG_MARGIN = 32;
+// Fallback colors for rendering without a host theme.
+export const DEFAULT_PALETTE = {
+    ink: '#18181b',
+    muted: '#6f6f78',
+    accent: '#4f46e5',
+    red: '#d64545',
+    orange: '#d97706',
+    yellow: '#b7860b',
+    green: '#2f8a4f',
+    blue: '#2563eb',
+    purple: '#7c3aed',
+    pink: '#db2777'
+};
+// Pale note fills for rendering without a host theme.
+export const DEFAULT_PAPER = {
+    ink: '#f4f4f6',
+    muted: '#ececef',
+    accent: '#e2e5fd',
+    red: '#fddfdf',
+    orange: '#fde9d0',
+    yellow: '#fff3bf',
+    green: '#dcf5e3',
+    blue: '#dbe9ff',
+    purple: '#eadffb',
+    pink: '#fde2ea'
+};
+/* The edge of that paper outside the app: every sheet above, a step deeper into its own color. */
+export const DEFAULT_EDGE = {
+    ink: '#dedee2',
+    muted: '#d6d6da',
+    accent: '#c3cbf7',
+    red: '#f4bebe',
+    orange: '#f3d3a8',
+    yellow: '#f0dc94',
+    green: '#b9e3c6',
+    blue: '#b6cff2',
+    purple: '#d5bef0',
+    pink: '#f3c0d1'
+};
+// XML has no way to write a control character other than tab and the line breaks, not even escaped.
+// oxlint-disable-next-line no-control-regex
+const NOT_XML = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\uFFFE\uFFFF]/g;
+function escapeXml(value) {
+    return value.replace(NOT_XML, '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&apos;');
+}
+function round(value) {
+    return Math.round(value * 100) / 100;
+}
+function transformOf(element) {
+    const center = centerOf(boundsOf(element));
+    const turn = element.angle ? ` rotate(${round((element.angle * 180) / Math.PI)} ${round(center.x)} ${round(center.y)})` : '';
+    return `translate(${round(element.x)} ${round(element.y)})${turn}`;
+}
+function textSvg(element, options) {
+    const family = options.fonts?.[fontOf(element.font)] ?? DEFAULT_FONT_STACKS[fontOf(element.font)];
+    const anchor = element.align === 'center' ? 'middle' : element.align === 'right' ? 'end' : 'start';
+    const frame = writingFrameOf(element);
+    const dx = frame.x + (element.align === 'center' ? frame.w / 2 : element.align === 'right' ? frame.w : 0);
+    const measure = options.measure?.(element) ?? approximateMeasure(element.size, element.font);
+    const lines = linesOf(element, measure)
+        .map((line, index) => `<tspan x="${round(dx)}" y="${round(frame.y + (index + 0.8) * element.size * LINE_HEIGHT)}">${escapeXml(line)}</tspan>`)
+        .join('');
+    return `<text font-family="${escapeXml(family)}" font-size="${element.size}" fill="${options.palette[element.stroke]}" text-anchor="${anchor}">${lines}</text>`;
+}
+function elementSvg(element, options) {
+    const note = element.kind === 'note';
+    const paper = options.paper ?? DEFAULT_PAPER;
+    const edge = options.edge ?? DEFAULT_EDGE;
+    const body = element.kind === 'text'
+        ? textSvg(element, options)
+        : pathsOfElement(element)
+            .map((path) => {
+            const dash = path.dash ? ` stroke-dasharray="${path.dash.join(' ')}"` : '';
+            if (path.role === 'stroke') {
+                const line = note ? edge[element.fillColor ?? element.stroke] : options.palette[element.stroke];
+                return `<path d="${path.d}" fill="none" stroke="${line}" stroke-width="${path.strokeWidth}" stroke-linecap="round"${dash}/>`;
+            }
+            // A note is filled with its paper, which is a palette of pale sheets of its own.
+            const fill = note ? paper : options.palette;
+            const color = path.role === 'ink' ? options.palette[element.stroke] : fill[element.fillColor ?? element.stroke];
+            // A hachure fill is a bundle of lines, so it arrives as a stroke with its own width.
+            return path.strokeWidth > 0 && path.role === 'fill' && element.fill === 'hachure'
+                ? `<path d="${path.d}" fill="none" stroke="${color}" stroke-width="${path.strokeWidth}"/>`
+                : `<path d="${path.d}" fill="${color}" stroke="none"/>`;
+        })
+            .join('');
+    // The paper is drawn first and the note's own words go on top of it.
+    const written = note ? textSvg(element, options) : '';
+    return `<g transform="${transformOf(element)}">${body}${written}</g>`;
+}
+/*
+ * The whole drawing as one SVG, in the colors of the theme it is exported from. Fonts are named,
+ * never embedded: a file that opens outside the app falls back to a system face.
+ */
+export function toSvg(elements, options) {
+    const margin = options.margin ?? DEFAULT_SVG_MARGIN;
+    const bounds = boundsOfElements(elements) ?? { x: 0, y: 0, w: 1, h: 1 };
+    const x = round(bounds.x - margin);
+    const y = round(bounds.y - margin);
+    const w = round(bounds.w + margin * 2);
+    const h = round(bounds.h + margin * 2);
+    const paper = options.background ? `<rect x="${x}" y="${y}" width="${w}" height="${h}" fill="${options.background}"/>` : '';
+    const body = elements.map((element) => elementSvg(element, options)).join('');
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="${x} ${y} ${w} ${h}">${paper}${body}</svg>`;
+}

package/dist/text.d.ts

@@ -0,0 +1,19 @@
+import type { DrawingElement, DrawingFont } from './protocol.ts';
+export declare const LINE_HEIGHT = 1.25;
+export declare const DEFAULT_FONT_STACKS: Record<DrawingFont, string>;
+export type WrittenElement = DrawingElement & {
+    kind: 'text' | 'note';
+};
+export declare const NOTE_PADDING = 16;
+export declare const NOTE_RADIUS = 8;
+export declare function writingFrameOf(element: WrittenElement): {
+    x: number;
+    y: number;
+    w: number;
+};
+export declare function textLines(text: string): string[];
+export type MeasureLine = (line: string) => number;
+export declare function approximateMeasure(size: number, font: DrawingFont | undefined): MeasureLine;
+export declare function wrapLines(text: string, maxWidth: number, measure: MeasureLine): string[];
+export declare function linesOf(element: WrittenElement, measure: MeasureLine): string[];
+export declare function fontOf(font: DrawingFont | undefined): DrawingFont;

package/dist/text.js

@@ -0,0 +1,74 @@
+/* A drawing sets its lines the way the app does: a little air, no leading of its own. */
+export const LINE_HEIGHT = 1.25;
+/* What each font name means outside the app, where the interface tokens do not exist. */
+export const DEFAULT_FONT_STACKS = {
+    hand: 'Kalam, "Comic Sans MS", cursive',
+    sans: 'system-ui, -apple-system, "Segoe UI", sans-serif',
+    mono: 'ui-monospace, SFMono-Regular, Menlo, monospace'
+};
+/* How much paper a note keeps free around its text, on every side. */
+export const NOTE_PADDING = 16;
+/* The corners of a sheet of paper, which are never quite square. */
+export const NOTE_RADIUS = 8;
+/*
+ * Where the glyphs of an element sit inside it: a note writes within its padding, a text is its
+ * own box. Everything that lays out or measures a text goes through this, so both stay in step.
+ */
+export function writingFrameOf(element) {
+    return element.kind === 'note' ? { x: NOTE_PADDING, y: NOTE_PADDING, w: Math.max(1, element.w - NOTE_PADDING * 2) } : { x: 0, y: 0, w: element.w };
+}
+export function textLines(text) {
+    return text.split('\n');
+}
+/*
+ * A measure for where no font exists, such as the daemon writing an SVG for an agent: a glyph is
+ * a little over half its size wide, which is what most faces come to on average.
+ */
+export function approximateMeasure(size, font) {
+    const glyph = fontOf(font) === 'mono' ? 0.6 : 0.55;
+    return (line) => line.length * size * glyph;
+}
+function wrapParagraph(paragraph, maxWidth, measure) {
+    const lines = [];
+    let line = '';
+    const push = () => {
+        lines.push(line);
+        line = '';
+    };
+    for (const word of paragraph.split(' ')) {
+        const candidate = line === '' ? word : `${line} ${word}`;
+        if (measure(candidate) <= maxWidth) {
+            line = candidate;
+            continue;
+        }
+        if (line !== '') {
+            push();
+        }
+        if (measure(word) <= maxWidth) {
+            line = word;
+            continue;
+        }
+        for (const glyph of word) {
+            if (line !== '' && measure(line + glyph) > maxWidth) {
+                push();
+            }
+            line += glyph;
+        }
+    }
+    lines.push(line);
+    return lines;
+}
+export function wrapLines(text, maxWidth, measure) {
+    return textLines(text).flatMap((paragraph) => wrapParagraph(paragraph, maxWidth, measure));
+}
+// An unsized text element follows its content; once sized, its box controls wrapping.
+export function linesOf(element, measure) {
+    if (element.kind === 'note') {
+        return wrapLines(element.text, writingFrameOf(element).w, measure);
+    }
+    return element.sized ? wrapLines(element.text, element.w, measure) : textLines(element.text);
+}
+/* Absent means hand: a drawing is written by hand unless it says otherwise. */
+export function fontOf(font) {
+    return font ?? 'hand';
+}

package/package.json

@@ -1,11 +1,51 @@
 {
   "name": "@adecore/drawing",
-  "version": "0.0.1",
-  "description": "Placeholder for the first release.",
+  "version": "0.17.0-beta.1",
+  "description": "Drawing schemas, geometry, deterministic paths, SVG export and reading order.",
   "license": "FSL-1.1-MIT",
+  "author": "Bas Milius",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/basmilius/adecore.git",
     "directory": "packages/drawing"
+  },
+  "bugs": {
+    "url": "https://github.com/basmilius/adecore/issues"
+  },
+  "homepage": "https://adecore.dev/drawing/",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/fixtures"
+  ],
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./protocol": {
+      "source": "./src/protocol.ts",
+      "types": "./dist/protocol.d.ts",
+      "default": "./dist/protocol.js"
+    }
+  },
+  "scripts": {
+    "build": "bun scripts/build.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test --conditions=source"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.2",
+    "@types/node": "^24.13.6",
+    "typescript": "^7.0.2"
+  },
+  "dependencies": {
+    "zod": "^4.6.5",
+    "perfect-freehand": "^1.2.3",
+    "roughjs": "^4.6.6"
   }
 }