@1agh/maude 1.4.5 → 1.5.0

package/apps/studio/annotations/elements/shape.model.ts

@@ -0,0 +1,141 @@
+/**
+ * Closed shape (DDR-242) — rect / ellipse / diamond / triangle / triangle-down
+ * in ONE type with a `kind` field, so converting a shape is a field change that
+ * keeps its id, binds and label. The label is an embedded record (Excalidraw
+ * "bound text"): exactly one per shape, by construction.
+ */
+
+import {
+  DEFAULT_FONT_SIZE,
+  DEFAULT_INK,
+  SHAPE_KINDS,
+  SHAPE_MIN_SIZE,
+  type ShapeKind,
+} from '../constants.ts';
+import { bool, color, fill, num, oneOf, record, text } from '../fields.ts';
+import type { AnnotationElement, Box, ElementDef } from '../types.ts';
+import {
+  BOX_FIELDS,
+  boxOf,
+  get,
+  inBox,
+  pointSegmentDist,
+  ROT_FIELD,
+  resizeBox,
+  textStyleFields,
+  toLocal,
+  translateBox,
+} from './_shared.ts';
+
+export const LABEL_FIELDS = {
+  text: text(),
+  fontSize: num({ min: 4, max: 400, dp: 1, def: DEFAULT_FONT_SIZE }),
+  color: color(DEFAULT_INK),
+  ...textStyleFields('center'),
+};
+
+const FIELDS = {
+  kind: oneOf(SHAPE_KINDS, 'rect'),
+  ...BOX_FIELDS,
+  ...ROT_FIELD,
+  color: color(DEFAULT_INK),
+  width: num({ min: 0.5, max: 64, dp: 1, def: 2 }),
+  fill: fill(),
+  radius: num({ min: 0, max: 1000, dp: 1, def: 0 }),
+  dashed: bool(),
+  label: record(LABEL_FIELDS, { def: {} }),
+};
+
+/** Outline vertices of the polygon kinds, spanning the full box. */
+export function polygonVertices(kind: ShapeKind, b: Box): Array<[number, number]> {
+  const { x, y, w, h } = b;
+  if (kind === 'diamond') {
+    return [
+      [x + w / 2, y],
+      [x + w, y + h / 2],
+      [x + w / 2, y + h],
+      [x, y + h / 2],
+    ];
+  }
+  if (kind === 'triangle') {
+    return [
+      [x + w / 2, y],
+      [x + w, y + h],
+      [x, y + h],
+    ];
+  }
+  return [
+    [x, y],
+    [x + w, y],
+    [x + w / 2, y + h],
+  ];
+}
+
+function pointInPolygon(px: number, py: number, pts: ReadonlyArray<[number, number]>): boolean {
+  let inside = false;
+  for (let i = 0, j = pts.length - 1; i < pts.length; j = i++) {
+    const a = pts[i] as [number, number];
+    const b = pts[j] as [number, number];
+    if (a[1] > py !== b[1] > py && px < ((b[0] - a[0]) * (py - a[1])) / (b[1] - a[1]) + a[0]) {
+      inside = !inside;
+    }
+  }
+  return inside;
+}
+
+function shapeHit(el: AnnotationElement, px: number, py: number, tol: number): boolean {
+  const b = boxOf(el);
+  const [lx, ly] = toLocal(el, b, px, py);
+  const kind = get<ShapeKind>(FIELDS, el, 'kind');
+  const filled = get<string | null>(FIELDS, el, 'fill') != null;
+  const t = Math.max(tol, get<number>(FIELDS, el, 'width'));
+  if (kind === 'ellipse') {
+    const rx = b.w / 2;
+    const ry = b.h / 2;
+    if (rx <= 0 || ry <= 0) return false;
+    const nx = (lx - (b.x + rx)) / rx;
+    const ny = (ly - (b.y + ry)) / ry;
+    const d = nx * nx + ny * ny;
+    if (filled) return d <= 1 + t / Math.max(rx, ry);
+    return Math.abs(Math.sqrt(d) - 1) <= t / Math.max(rx, ry);
+  }
+  if (kind === 'rect') {
+    if (filled) return inBox(b, lx, ly, t);
+    if (!inBox(b, lx, ly, t)) return false;
+    return (
+      Math.abs(lx - b.x) <= t ||
+      Math.abs(lx - (b.x + b.w)) <= t ||
+      Math.abs(ly - b.y) <= t ||
+      Math.abs(ly - (b.y + b.h)) <= t
+    );
+  }
+  const pts = polygonVertices(kind, b);
+  if (filled && pointInPolygon(lx, ly, pts)) return true;
+  for (let i = 0; i < pts.length; i++) {
+    const a = pts[i] as [number, number];
+    const c = pts[(i + 1) % pts.length] as [number, number];
+    if (pointSegmentDist(lx, ly, a[0], a[1], c[0], c[1]) <= t) return true;
+  }
+  return false;
+}
+
+export const shape: ElementDef = {
+  type: 'shape',
+  fields: FIELDS,
+  caps: {
+    box: true,
+    rotatable: true,
+    resizable: true,
+    bindable: true,
+    container: false,
+    textSlot: 'label',
+  },
+  bounds: (el) => boxOf(el),
+  hitTest: (el, px, py, tol) => shapeHit(el, px, py, tol),
+  translate: translateBox,
+  resize: resizeBox,
+  meaningful: (el) => {
+    const b = boxOf(el);
+    return b.w >= SHAPE_MIN_SIZE && b.h >= SHAPE_MIN_SIZE;
+  },
+};

package/apps/studio/annotations/elements/sticky.model.ts

@@ -0,0 +1,48 @@
+/** Sticky note — a paper card with a wrapped text body (DDR-242). */
+
+import {
+  DEFAULT_FONT_SIZE,
+  DEFAULT_STICKY_FILL,
+  STICKY_MIN_SIZE,
+  STICKY_RADIUS,
+} from '../constants.ts';
+import { color, num, text } from '../fields.ts';
+import type { ElementDef } from '../types.ts';
+import {
+  BOX_FIELDS,
+  boxOf,
+  ROT_FIELD,
+  resizeBox,
+  solidBoxHit,
+  textStyleFields,
+  translateBox,
+} from './_shared.ts';
+
+export const sticky: ElementDef = {
+  type: 'sticky',
+  fields: {
+    ...BOX_FIELDS,
+    ...ROT_FIELD,
+    fill: color(DEFAULT_STICKY_FILL),
+    text: text(),
+    fontSize: num({ min: 4, max: 400, dp: 1, def: DEFAULT_FONT_SIZE }),
+    radius: num({ min: 0, max: 200, dp: 1, def: STICKY_RADIUS }),
+    ...textStyleFields('left'),
+  },
+  caps: {
+    box: true,
+    rotatable: true,
+    resizable: true,
+    bindable: true,
+    container: false,
+    textSlot: 'text',
+  },
+  bounds: (el) => boxOf(el),
+  hitTest: (el, px, py, tol) => solidBoxHit(el, px, py, tol),
+  translate: translateBox,
+  resize: resizeBox,
+  meaningful: (el) => {
+    const b = boxOf(el);
+    return b.w >= STICKY_MIN_SIZE && b.h >= STICKY_MIN_SIZE;
+  },
+};

package/apps/studio/annotations/elements/text.model.ts

@@ -0,0 +1,52 @@
+/**
+ * Standalone text (DDR-242). Unlike v1, its box is STORED (measured by the
+ * editor at commit) instead of estimated from a character count, so hit-test,
+ * marquee, snapping and headless readers agree with what is drawn. A shape's
+ * label is NOT a text element — it lives on the shape (`shape.label`).
+ */
+
+import { DEFAULT_FONT_SIZE, DEFAULT_INK } from '../constants.ts';
+import { color, num, text } from '../fields.ts';
+import type { ElementDef } from '../types.ts';
+import {
+  BOX_FIELDS,
+  boxOf,
+  ROT_FIELD,
+  resizeBox,
+  solidBoxHit,
+  textStyleFields,
+  translateBox,
+} from './_shared.ts';
+
+/** Text blocks larger than this don't take arrow binds (a paragraph is not a node). */
+export const MAX_TEXT_BIND_W = 1200;
+export const MAX_TEXT_BIND_H = 480;
+
+export const textEl: ElementDef = {
+  type: 'text',
+  fields: {
+    ...BOX_FIELDS,
+    ...ROT_FIELD,
+    text: text(),
+    fontSize: num({ min: 4, max: 400, dp: 1, def: DEFAULT_FONT_SIZE }),
+    color: color(DEFAULT_INK),
+    ...textStyleFields('left'),
+  },
+  caps: {
+    box: true,
+    rotatable: true,
+    resizable: true,
+    bindable: true,
+    container: false,
+    textSlot: 'text',
+  },
+  bounds: (el) => boxOf(el),
+  hitTest: (el, px, py, tol) => solidBoxHit(el, px, py, tol, 0),
+  translate: translateBox,
+  resize: resizeBox,
+  meaningful: (el) => typeof el.text === 'string' && el.text.trim().length > 0,
+};
+
+export function textBindable(w: number, h: number): boolean {
+  return w > 0 && h > 0 && w <= MAX_TEXT_BIND_W && h <= MAX_TEXT_BIND_H;
+}

package/apps/studio/annotations/fields.ts

@@ -0,0 +1,347 @@
+/**
+ * @file       annotations/fields.ts — field-spec vocabulary + the validator engine
+ * @scope      apps/studio/annotations/fields.ts
+ * @purpose    The annotations-v2 element model (DDR-242) validates every record
+ *             against a per-type field spec. This module is that vocabulary —
+ *             number / string / enum / point / bind / text-style … — plus the
+ *             one engine that walks a spec, clamps, rounds, and drops defaults
+ *             (the canonical form). It is shared by the studio, the hub kernel
+ *             (Node 24 type-stripping — keep this file free of `enum`,
+ *             `namespace` and parameter properties) and the headless bins, so
+ *             every writer produces byte-identical canonical records.
+ *
+ *             Peer data is UNTRUSTED (DDR-054). The engine never throws on
+ *             bad input: a field that fails its spec falls back to its default
+ *             (or makes the element invalid when it is `required`), unknown
+ *             keys are dropped, and prototype keys never survive.
+ */
+
+/** Keys that must never survive a parse of untrusted JSON (DDR-054 §2g). */
+export const DANGEROUS_KEYS: ReadonlySet<string> = new Set([
+  '__proto__',
+  'constructor',
+  'prototype',
+]);
+
+/** Coordinates and sizes round to 2 decimals; rotation to 0.1°. */
+export const COORD_DP = 2;
+/** Every coordinate is clamped into ±COORD_MAX (a peer can't park a node at 1e300). */
+export const COORD_MAX = 1_000_000;
+
+export type Json = null | boolean | number | string | Json[] | { [k: string]: Json };
+
+/**
+ * A field spec. `parse` returns the clean value, or `undefined` when the raw
+ * value is unusable (the engine then applies the default, or rejects the
+ * element when the field is required). `def` is the implicit value: a field
+ * equal to its default is OMITTED from the canonical record.
+ */
+export interface FieldSpec<T = unknown> {
+  parse(raw: unknown): T | undefined;
+  def?: T;
+  required?: boolean;
+  /** Structural equality for default-omission and change detection. */
+  eq?(a: T, b: T): boolean;
+}
+
+export function round(v: number, dp: number): number {
+  const f = 10 ** dp;
+  const r = Math.round(v * f) / f;
+  return Object.is(r, -0) ? 0 : r;
+}
+
+export interface NumOpts {
+  min?: number;
+  max?: number;
+  dp?: number;
+  def?: number;
+  required?: boolean;
+}
+
+export function num(opts: NumOpts = {}): FieldSpec<number> {
+  const min = opts.min ?? -COORD_MAX;
+  const max = opts.max ?? COORD_MAX;
+  const dp = opts.dp ?? COORD_DP;
+  return {
+    def: opts.def,
+    required: opts.required,
+    parse(raw) {
+      if (typeof raw !== 'number' || !Number.isFinite(raw)) return undefined;
+      return round(Math.min(max, Math.max(min, raw)), dp);
+    },
+  };
+}
+
+export interface StrOpts {
+  max: number;
+  re?: RegExp;
+  def?: string;
+  required?: boolean;
+  /** Strip control / bidi / zero-width characters (display names). */
+  plain?: boolean;
+  /** Allow an empty string (else '' counts as absent). */
+  allowEmpty?: boolean;
+}
+
+/** Control chars, C1, zero-width, bidi overrides/isolates, BOM. Newline/tab kept for text bodies. */
+export function stripUnsafe(s: string, keepNewlines: boolean): string {
+  let out = '';
+  for (const ch of s) {
+    const cp = ch.codePointAt(0) ?? 0;
+    if (keepNewlines && (cp === 0x0a || cp === 0x09)) {
+      out += ch;
+      continue;
+    }
+    const unsafe =
+      cp <= 0x1f ||
+      (cp >= 0x7f && cp <= 0x9f) ||
+      (cp >= 0x200b && cp <= 0x200f) ||
+      (cp >= 0x202a && cp <= 0x202e) ||
+      (cp >= 0x2066 && cp <= 0x2069) ||
+      cp === 0xfeff;
+    if (!unsafe) out += ch;
+  }
+  return out;
+}
+
+export function str(opts: StrOpts): FieldSpec<string> {
+  return {
+    def: opts.def,
+    required: opts.required,
+    parse(raw) {
+      if (typeof raw !== 'string') return undefined;
+      let v = opts.plain ? stripUnsafe(raw, false).trim() : raw.replace(/\r\n?/g, '\n');
+      if (!opts.plain) v = stripUnsafe(v, true);
+      if (v.length > opts.max) {
+        // A patterned value (id, path, url, colour) is an identity — reject, never truncate.
+        if (opts.re) return undefined;
+        v = v.slice(0, opts.max);
+      }
+      if (!opts.allowEmpty && v === '') return undefined;
+      if (opts.re && !opts.re.test(v)) return undefined;
+      return v;
+    },
+  };
+}
+
+/** Multi-line body text. Empty is a valid value (a fresh sticky). */
+export function text(max = 20_000): FieldSpec<string> {
+  return { ...str({ max, allowEmpty: true }), def: '' };
+}
+
+export function bool(def = false): FieldSpec<boolean> {
+  return {
+    def,
+    parse(raw) {
+      return typeof raw === 'boolean' ? raw : undefined;
+    },
+  };
+}
+
+export function oneOf<T extends string>(
+  values: readonly T[],
+  def?: T,
+  required?: boolean
+): FieldSpec<T> {
+  const set = new Set<string>(values);
+  return {
+    def,
+    required,
+    parse(raw) {
+      return typeof raw === 'string' && set.has(raw) ? (raw as T) : undefined;
+    },
+  };
+}
+
+/** `#rgb`, `#rrggbb`, `#rrggbbaa` — the only colour forms the palettes produce. */
+export const COLOR_RE = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+
+export function color(def?: string, required?: boolean): FieldSpec<string> {
+  return { ...str({ max: 9, re: COLOR_RE }), def, required };
+}
+
+/** A fill: a colour, or `null` for "no fill" (null is the default). */
+export function fill(): FieldSpec<string | null> {
+  return {
+    def: null,
+    parse(raw) {
+      if (raw === null) return null;
+      return typeof raw === 'string' && COLOR_RE.test(raw) ? raw : undefined;
+    },
+  };
+}
+
+/** Element id — the stable identity external references (comments) hold. */
+export const ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+
+export function id(required = false): FieldSpec<string> {
+  return { ...str({ max: 64, re: ID_RE }), required };
+}
+
+/** Fractional z-order key (base-62 digits, see fractional-index.ts). */
+export const INDEX_RE = /^[0-9A-Za-z]{1,64}$/;
+
+export function stringList(maxItems: number, item: FieldSpec<string>): FieldSpec<string[]> {
+  return {
+    def: [],
+    eq: (a, b) => a.length === b.length && a.every((v, i) => v === b[i]),
+    parse(raw) {
+      if (!Array.isArray(raw)) return undefined;
+      const out: string[] = [];
+      for (const r of raw.slice(0, maxItems)) {
+        const v = item.parse(r);
+        if (v !== undefined && !out.includes(v)) out.push(v);
+      }
+      return out;
+    },
+  };
+}
+
+/** Flat `[x0, y0, x1, y1, …]` point list (pen ink). Odd trailing values are dropped. */
+export function points(maxPoints: number): FieldSpec<number[]> {
+  return {
+    required: true,
+    eq: (a, b) => a.length === b.length && a.every((v, i) => v === b[i]),
+    parse(raw) {
+      if (!Array.isArray(raw)) return undefined;
+      const n = Math.min(raw.length - (raw.length % 2), maxPoints * 2);
+      const out: number[] = [];
+      for (let i = 0; i < n; i++) {
+        const v = raw[i];
+        if (typeof v !== 'number' || !Number.isFinite(v)) return undefined;
+        out.push(round(Math.min(COORD_MAX, Math.max(-COORD_MAX, v)), COORD_DP));
+      }
+      return out.length >= 2 ? out : undefined;
+    },
+  };
+}
+
+/** Deep structural equality over JSON values (records, arrays, primitives). */
+export function jsonEq(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object') return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a)) {
+    const bb = b as unknown[];
+    return a.length === bb.length && a.every((v, i) => jsonEq(v, bb[i]));
+  }
+  const ak = Object.keys(a as object);
+  const bk = Object.keys(b as object);
+  if (ak.length !== bk.length) return false;
+  for (const k of ak) {
+    if (!Object.hasOwn(b as object, k)) return false;
+    if (!jsonEq((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k])) return false;
+  }
+  return true;
+}
+
+/** A nested record with its own field spec (e.g. an arrow end, a shape label). */
+export function record(
+  spec: FieldSpecMap,
+  opts: { required?: boolean; def?: Record<string, unknown> } = {}
+): FieldSpec<Record<string, unknown>> {
+  return {
+    required: opts.required,
+    def: opts.def,
+    eq: jsonEq,
+    parse(raw) {
+      if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return undefined;
+      const r = parseFields(spec, raw as Record<string, unknown>);
+      return r.ok ? r.value : undefined;
+    },
+  };
+}
+
+/** Try each alternative in order; the first that parses wins. */
+export function either<T>(...alts: FieldSpec<T>[]): FieldSpec<T> {
+  return {
+    eq: jsonEq as (a: T, b: T) => boolean,
+    parse(raw) {
+      for (const a of alts) {
+        const v = a.parse(raw);
+        if (v !== undefined) return v;
+      }
+      return undefined;
+    },
+  };
+}
+
+export type FieldSpecMap = Readonly<Record<string, FieldSpec<unknown>>>;
+
+export type ParseResult =
+  | { ok: true; value: Record<string, unknown> }
+  | { ok: false; reason: string };
+
+function isDefault(spec: FieldSpec<unknown>, v: unknown): boolean {
+  if (spec.def === undefined) return false;
+  return spec.eq ? spec.eq(v, spec.def) : jsonEq(v, spec.def);
+}
+
+/**
+ * Walk `spec` over `raw` in SPEC ORDER (that order is the canonical key order),
+ * dropping unknown keys and default-valued fields. Required fields that fail
+ * make the record invalid; optional ones fall back to (omitted) defaults.
+ */
+export function parseFields(spec: FieldSpecMap, raw: Record<string, unknown>): ParseResult {
+  const out: Record<string, unknown> = {};
+  for (const key of Object.keys(spec)) {
+    if (DANGEROUS_KEYS.has(key)) continue;
+    const f = spec[key] as FieldSpec<unknown>;
+    const has = Object.hasOwn(raw, key);
+    const v = has ? f.parse(raw[key]) : undefined;
+    if (v === undefined) {
+      if (f.required) return { ok: false, reason: `field "${key}" missing or invalid` };
+      continue;
+    }
+    if (isDefault(f, v)) continue;
+    out[key] = v;
+  }
+  return { ok: true, value: out };
+}
+
+/** The value of `key` on a canonical record, falling back to the spec default. */
+export function fieldValue(spec: FieldSpecMap, rec: Record<string, unknown>, key: string): unknown {
+  if (Object.hasOwn(rec, key)) return rec[key];
+  return spec[key]?.def;
+}
+
+/**
+ * Safe JSON parse for untrusted text: a reviver drops prototype keys at every
+ * depth (DDR-054 §2g). Returns `undefined` on malformed input — never throws.
+ */
+export function parseJsonSafe(text: string): unknown {
+  try {
+    return JSON.parse(text, (k, v) => (DANGEROUS_KEYS.has(k) ? undefined : v));
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Bounded generic JSON sanitizer for UNKNOWN element types (forward-compat
+ * passthrough): primitives, arrays and plain objects only, depth ≤ 4, ≤ 256
+ * keys/items per level, strings capped, prototype keys dropped. Returns
+ * `undefined` when the value is not representable.
+ */
+export function sanitizeJson(raw: unknown, depth = 0): Json | undefined {
+  if (raw === null) return null;
+  if (typeof raw === 'boolean') return raw;
+  if (typeof raw === 'number') return Number.isFinite(raw) ? raw : undefined;
+  if (typeof raw === 'string') return stripUnsafe(raw, true).slice(0, 20_000);
+  if (depth >= 4 || typeof raw !== 'object') return undefined;
+  if (Array.isArray(raw)) {
+    const out: Json[] = [];
+    for (const v of raw.slice(0, 256)) {
+      const s = sanitizeJson(v, depth + 1);
+      if (s !== undefined) out.push(s);
+    }
+    return out;
+  }
+  const out: { [k: string]: Json } = {};
+  for (const k of Object.keys(raw as object).slice(0, 256)) {
+    if (DANGEROUS_KEYS.has(k) || k.length > 64) continue;
+    const s = sanitizeJson((raw as Record<string, unknown>)[k], depth + 1);
+    if (s !== undefined) out[k] = s;
+  }
+  return out;
+}