@1agh/maude 0.25.0 → 0.26.0

package/plugins/design/dev-server/draw/composition.ts

@@ -0,0 +1,229 @@
+/**
+ * @file       draw/composition.ts — Phase 25.1 compositional scaffolding layer
+ * @scope      plugins/design/dev-server/draw/composition.ts
+ * @purpose    The missing answer to "blob soup": deterministic COMPOSITION.
+ *             Random placement is empirically catastrophic — only ~3–12% of
+ *             randomly-placed multi-element layouts even avoid overlap (Shiripour
+ *             et al., ACM EICS 2021). The fix is to place elements ON a
+ *             constructed armature, not scatter-then-hope.
+ *
+ *             Grounded in the Phase-25.1 deep research (recorded in DDR-070 +
+ *             the rubric's "Phase-25.1 corrections" section):
+ *               • rule-of-thirds power points + rabatment lines + golden points
+ *                 + dynamic-symmetry "eyes" — REAL, exact, encodable focal
+ *                 scaffolds (place focal elements on the construction points).
+ *               • VME visual balance as moment-equilibrium (nine-grid weight +
+ *                 Manhattan distance; net moment → 0 = balanced).
+ *               • φ / root-N are OPTIONAL aspect/scaffold choices, NEVER a
+ *                 mandatory constraint — the golden-ratio "secret formula" is a
+ *                 debunked myth (Naini 2024; Markowsky 1992).
+ *
+ *             CRITICAL: armatures are a GENERATION tool only. "Does it align to
+ *             a grid?" is mathematically non-discriminating (a dense enough
+ *             armature fits ANY image — Blake 1921), so it is USELESS as a critic
+ *             gate. The critic uses discriminating metrics (balance moment,
+ *             value range, hue-harmony distance) — see palette.ts + the rubric.
+ *
+ *             React-free (DDR-067); pure + deterministic (no Math.random).
+ */
+
+import type { Rect } from './geometry.ts';
+import type { Point } from './primitives.ts';
+
+const PHI = 1.618033988749895;
+
+export type ArmatureKind = 'thirds' | 'golden' | 'rabatment' | 'dynamic-symmetry' | 'quad';
+
+export interface Armature {
+  kind: ArmatureKind;
+  box: Rect;
+  /** Construction lines (for an optional debug overlay). */
+  lines: Array<{ x1: number; y1: number; x2: number; y2: number }>;
+  /** The focal "power points" / "eyes" — snap dominant elements here. */
+  focals: Point[];
+  /** The composition's visual center (canvas center; slightly-high reads better but center is the neutral default). */
+  center: Point;
+}
+
+function corners(b: Rect) {
+  return {
+    tl: { x: b.x, y: b.y },
+    tr: { x: b.x + b.width, y: b.y },
+    bl: { x: b.x, y: b.y + b.height },
+    br: { x: b.x + b.width, y: b.y + b.height },
+  };
+}
+
+/** Foot of the perpendicular from point `p` onto the line through `a`→`b`. */
+function perpFoot(p: Point, a: Point, b: Point): Point {
+  const dx = b.x - a.x;
+  const dy = b.y - a.y;
+  const len2 = dx * dx + dy * dy || 1;
+  const t = ((p.x - a.x) * dx + (p.y - a.y) * dy) / len2;
+  return { x: a.x + t * dx, y: a.y + t * dy };
+}
+
+/**
+ * Build a compositional armature for a canvas. The returned `focals` are the
+ * snap targets for the dominant element(s); `lines` are the construction lines.
+ * `golden` is offered for completeness but the research shows it has no special
+ * status — prefer `thirds` / `rabatment` / `dynamic-symmetry`.
+ */
+export function armature(box: Rect, kind: ArmatureKind = 'thirds'): Armature {
+  const { x, y, width: W, height: H } = box;
+  const center = { x: x + W / 2, y: y + H / 2 };
+  const lines: Armature['lines'] = [];
+  let focals: Point[] = [];
+
+  if (kind === 'thirds' || kind === 'golden') {
+    const fx = kind === 'golden' ? [W / PHI, W - W / PHI] : [W / 3, (2 * W) / 3];
+    const fy = kind === 'golden' ? [H / PHI, H - H / PHI] : [H / 3, (2 * H) / 3];
+    for (const vx of fx) lines.push({ x1: x + vx, y1: y, x2: x + vx, y2: y + H });
+    for (const hy of fy) lines.push({ x1: x, y1: y + hy, x2: x + W, y2: y + hy });
+    for (const hy of fy) for (const vx of fx) focals.push({ x: x + vx, y: y + hy });
+  } else if (kind === 'rabatment') {
+    // Implied squares folded from each short side. Landscape → vertical lines at
+    // x = H and x = W−H; portrait → horizontal lines at y = W and y = H−W. Focal
+    // y (landscape) taken at the thirds heights (the verified rabatment geometry
+    // governs the dominant axis; thirds fills the minor axis).
+    if (W >= H) {
+      const vx = [H, W - H];
+      const hy = [H / 3, (2 * H) / 3];
+      for (const v of vx) lines.push({ x1: x + v, y1: y, x2: x + v, y2: y + H });
+      for (const h of hy) for (const v of vx) focals.push({ x: x + v, y: y + h });
+    } else {
+      const hy = [W, H - W];
+      const vx = [W / 3, (2 * W) / 3];
+      for (const h of hy) lines.push({ x1: x, y1: y + h, x2: x + W, y2: y + h });
+      for (const h of hy) for (const v of vx) focals.push({ x: x + v, y: y + h });
+    }
+  } else if (kind === 'dynamic-symmetry') {
+    const c = corners(box);
+    // Main diagonals.
+    lines.push({ x1: c.tl.x, y1: c.tl.y, x2: c.br.x, y2: c.br.y });
+    lines.push({ x1: c.tr.x, y1: c.tr.y, x2: c.bl.x, y2: c.bl.y });
+    // "Eyes" = feet of perpendiculars from the off-diagonal corners onto each main.
+    const e1 = perpFoot(c.tr, c.tl, c.br);
+    const e2 = perpFoot(c.bl, c.tl, c.br);
+    const e3 = perpFoot(c.tl, c.tr, c.bl);
+    const e4 = perpFoot(c.br, c.tr, c.bl);
+    focals = [e1, e2, e3, e4];
+    // Reciprocal segments (corner → its eye) for the overlay.
+    lines.push({ x1: c.tr.x, y1: c.tr.y, x2: e1.x, y2: e1.y });
+    lines.push({ x1: c.bl.x, y1: c.bl.y, x2: e2.x, y2: e2.y });
+    lines.push({ x1: c.tl.x, y1: c.tl.y, x2: e3.x, y2: e3.y });
+    lines.push({ x1: c.br.x, y1: c.br.y, x2: e4.x, y2: e4.y });
+  } else {
+    // quad — the four quarter-centers (a simple, balanced fallback grid).
+    for (const qy of [0.25, 0.75])
+      for (const qx of [0.25, 0.75]) focals.push({ x: x + W * qx, y: y + H * qy });
+  }
+
+  return { kind, box, lines, focals, center };
+}
+
+/** Nearest focal point on an armature to `p` (snap target). */
+export function snapToFocal(p: Point, arm: Armature): Point {
+  let best = arm.focals[0];
+  let bestD = Number.POSITIVE_INFINITY;
+  for (const f of arm.focals) {
+    const d = Math.hypot(f.x - p.x, f.y - p.y);
+    if (d < bestD) {
+      bestD = d;
+      best = f;
+    }
+  }
+  return best;
+}
+
+/**
+ * Assign `n` elements to distinct composition slots. The first (dominant) gets a
+ * strong focal point; the rest fill the remaining focals, then a jittered grid —
+ * but NEVER pure random scatter. Deterministic given the armature.
+ */
+export function assignSlots(n: number, arm: Armature): Point[] {
+  const out: Point[] = [];
+  const focals = [...arm.focals];
+  for (let i = 0; i < n; i++) {
+    if (i < focals.length) {
+      out.push(focals[i]);
+    } else {
+      // Beyond the focals, lay a calm grid inside the box (rows of ~√extra).
+      const extra = i - focals.length;
+      const cols = Math.max(2, Math.ceil(Math.sqrt(n - focals.length)));
+      const r = Math.floor(extra / cols);
+      const c = extra % cols;
+      const rows = Math.ceil((n - focals.length) / cols);
+      out.push({
+        x: arm.box.x + arm.box.width * ((c + 1) / (cols + 1)),
+        y: arm.box.y + arm.box.height * ((r + 1) / (rows + 1)),
+      });
+    }
+  }
+  return out;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// VME visual balance — moment equilibrium (nine-grid weight + Manhattan)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface WeightedBox {
+  bbox: Rect;
+  /** Optional explicit visual weight; defaults to bbox area. */
+  weight?: number;
+}
+
+export interface BalanceResult {
+  /** Net moment vector about the visual center, normalized to [-1,1] per axis. */
+  moment: Point;
+  /** 0 (wildly off-balance) … 1 (perfectly balanced). */
+  score: number;
+}
+
+function boxCentroid(b: Rect): Point {
+  return { x: b.x + b.width / 2, y: b.y + b.height / 2 };
+}
+
+/**
+ * Visual balance as moment equilibrium (VME). Each element exerts a moment about
+ * the canvas visual center proportional to its weight × Manhattan offset; a
+ * balanced composition has a net moment near zero. Returns the normalized net
+ * moment + a [0,1] balance score (the discriminating critic metric for balance).
+ */
+export function balanceMoment(elements: WeightedBox[], box: Rect): BalanceResult {
+  const center = { x: box.x + box.width / 2, y: box.y + box.height / 2 };
+  const halfW = box.width / 2 || 1;
+  const halfH = box.height / 2 || 1;
+  let mx = 0;
+  let my = 0;
+  let totalW = 0;
+  for (const el of elements) {
+    const w = el.weight ?? Math.max(0, el.bbox.width * el.bbox.height);
+    const c = boxCentroid(el.bbox);
+    mx += w * (c.x - center.x);
+    my += w * (c.y - center.y);
+    totalW += w;
+  }
+  if (totalW === 0) return { moment: { x: 0, y: 0 }, score: 1 };
+  const nx = mx / (totalW * halfW);
+  const ny = my / (totalW * halfH);
+  // Manhattan-style aggregate imbalance (matches VME's non-Euclidean weighting).
+  const imbalance = Math.min(1, (Math.abs(nx) + Math.abs(ny)) / 2);
+  return { moment: { x: nx, y: ny }, score: Math.max(0, 1 - imbalance) };
+}
+
+/**
+ * Dominance check: does the composition have ONE clear focal element? Returns the
+ * size ratio of the largest element's visual weight to the next-largest. A ratio
+ * well above 1 means a single element commands attention; ~1 means competing
+ * foci (the "everything is equally loud" failure). Threshold tuning is the
+ * critic's job — this just reports the measurable ratio.
+ */
+export function dominanceRatio(elements: WeightedBox[]): number {
+  const weights = elements
+    .map((e) => e.weight ?? Math.max(0, e.bbox.width * e.bbox.height))
+    .sort((a, b) => b - a);
+  if (weights.length === 0) return 0;
+  if (weights.length === 1) return Number.POSITIVE_INFINITY;
+  return weights[1] > 0 ? weights[0] / weights[1] : Number.POSITIVE_INFINITY;
+}