@miadi/stateloom-web 0.1.0

package/server/src/components/UiScale.tsx

@@ -0,0 +1,199 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useSyncExternalStore } from "react";
+import { isOnCanvasPane } from "@/lib/gestureOwner";
+import {
+  applyUiScale,
+  clampUiScale,
+  getServerUiScale,
+  getUiScale,
+  setUiScale,
+  subscribeUiScale,
+} from "@/lib/uiScale";
+
+/**
+ * How far the fingers must travel before a two-finger contact counts as a
+ * request to resize the chrome. The canvas needs no such threshold — two fingers
+ * on the board can only ever mean zoom — but the chrome is full of things a hand
+ * rests on, and a two-finger tap on a panel must not leave the menus a few
+ * percent bigger than they were.
+ */
+const CHROME_PINCH_SLOP_PX = 12;
+
+interface ChromePinch {
+  a: number;
+  b: number;
+  /** The chrome size the gesture opened against. Never re-read mid-gesture. */
+  startScale: number;
+  /**
+   * Finger separation at the moment the gesture *engaged* — which is when it
+   * passed the slop, not when the fingers landed. Re-baselining there is what
+   * stops the chrome jumping a slop's worth of scale the instant it engages.
+   */
+  startDist: number;
+  engaged: boolean;
+}
+
+function distanceBetween(a: Touch, b: Touch): number {
+  // Two fingers on one pixel would divide by zero; a floor of one pixel makes the
+  // opening frame a no-op instead of an infinity. Same guard the canvas uses.
+  return Math.max(1, Math.hypot(b.clientX - a.clientX, b.clientY - a.clientY));
+}
+
+function findTouch(list: TouchList, identifier: number): Touch | null {
+  for (let i = 0; i < list.length; i++) {
+    if (list[i].identifier === identifier) return list[i];
+  }
+  return null;
+}
+
+/**
+ * The second set of controls.
+ *
+ * Pinch the board and the machine gets bigger. Pinch anywhere else — toolbar,
+ * panels, the bottom sheet, the tab dock — and the *interface* gets bigger:
+ * labels, buttons, the 44px touch floors, all of it, because every one of them is
+ * a multiple of the root font size. See `lib/uiScale.ts` for why that one
+ * property is the whole mechanism, and `lib/gestureOwner.ts` for the rule that
+ * keeps the two pinches from ever answering the same gesture.
+ */
+export default function UiScale() {
+  // The scale lives outside React (lib/uiScale.ts) — it is a property of the
+  // document that a gesture sets and the browser remembers. This component only
+  // observes it, which is why there is no restore-from-storage effect here and no
+  // render at 100% before the remembered size arrives.
+  const scale = useSyncExternalStore(subscribeUiScale, getUiScale, getServerUiScale);
+  const pinchRef = useRef<ChromePinch | null>(null);
+  // The size the fingers have asked for but the screen has not yet been given.
+  // Only the gesture writes it — never the render — so a frame that lands between
+  // two moves cannot roll the pinch back to where it was one move ago.
+  const pendingRef = useRef<number | null>(null);
+  const frameRef = useRef<number | null>(null);
+
+  // Keep the glass in step with the store. Normally a no-op: the inline script in
+  // layout.tsx has already sized the root before first paint, and every gesture
+  // writes the DOM before it notifies. This is the belt for the case where that
+  // script was blocked.
+  useEffect(() => {
+    applyUiScale(scale);
+  }, [scale]);
+
+  /** Move at most once per frame; fingers report far faster than the screen. */
+  const paint = useCallback((next: number) => {
+    pendingRef.current = next;
+    if (frameRef.current !== null) return;
+    frameRef.current = requestAnimationFrame(() => {
+      frameRef.current = null;
+      if (pendingRef.current !== null) setUiScale(pendingRef.current, false);
+    });
+  }, []);
+
+  const reset = useCallback(() => {
+    pendingRef.current = null;
+    setUiScale(1, true);
+  }, []);
+
+  // Chrome pinch. Native touch listeners rather than React's pointer events for
+  // two reasons: `TouchEvent.touches` hands over every finger at once, so no map
+  // has to be kept to know a gesture is a pinch; and `preventDefault` on a
+  // *non-passive* touchmove is the only thing that reliably stops a panel from
+  // scrolling out from under a hand that meant to resize it.
+  useEffect(() => {
+    const endPinch = () => {
+      const pinch = pinchRef.current;
+      pinchRef.current = null;
+      if (!pinch?.engaged) return;
+      // The fingers are off the glass. Whatever the last move asked for goes on
+      // now — a lift must never be answered by the frame before it — and now, and
+      // only now, is the size worth remembering across reloads.
+      if (frameRef.current !== null) {
+        cancelAnimationFrame(frameRef.current);
+        frameRef.current = null;
+      }
+      const settled = pendingRef.current ?? getUiScale();
+      pendingRef.current = null;
+      setUiScale(clampUiScale(settled), true);
+    };
+
+    const onTouchStart = (e: TouchEvent) => {
+      if (e.touches.length !== 2) {
+        // A third finger — or a drop back to one — is no longer a chrome pinch.
+        // It settles at the size it reached rather than snapping back.
+        if (pinchRef.current) endPinch();
+        return;
+      }
+      const [a, b] = [e.touches[0], e.touches[1]];
+      // The arbitration rule, applied once and never revisited: if either finger
+      // is on the canvas pane, this gesture is not ours. The canvas takes it when
+      // the other finger is there too; when it is not, nobody takes it.
+      if (isOnCanvasPane(a.target) || isOnCanvasPane(b.target)) return;
+
+      pinchRef.current = {
+        a: a.identifier,
+        b: b.identifier,
+        startScale: getUiScale(),
+        startDist: distanceBetween(a, b),
+        engaged: false,
+      };
+    };
+
+    const onTouchMove = (e: TouchEvent) => {
+      const pinch = pinchRef.current;
+      if (!pinch) return;
+      const a = findTouch(e.touches, pinch.a);
+      const b = findTouch(e.touches, pinch.b);
+      if (!a || !b) return;
+
+      // Two fingers on the chrome never mean "scroll" — one finger does that — so
+      // the browser's reading of this gesture is always wrong, and is refused from
+      // the very first move, before it can commit to a scroll it cannot undo.
+      e.preventDefault();
+
+      const dist = distanceBetween(a, b);
+      if (!pinch.engaged) {
+        if (Math.abs(dist - pinch.startDist) < CHROME_PINCH_SLOP_PX) return;
+        pinch.engaged = true;
+        pinch.startDist = dist;
+        return;
+      }
+      // Measured from the opening frame, never from the previous move — the same
+      // arithmetic the canvas zoom uses, so the two gestures feel like one gesture
+      // pointed at two different things, and neither accumulates drift.
+      paint(clampUiScale(pinch.startScale * (dist / pinch.startDist)));
+    };
+
+    const onTouchEnd = (e: TouchEvent) => {
+      const pinch = pinchRef.current;
+      if (!pinch) return;
+      // Either finger leaving ends the gesture. A hand that puts one back down
+      // opens a fresh pinch against the size this one settled on.
+      if (!findTouch(e.touches, pinch.a) || !findTouch(e.touches, pinch.b)) endPinch();
+    };
+
+    // Capture phase, so a panel that stops propagation cannot hide the gesture.
+    document.addEventListener("touchstart", onTouchStart, { passive: true, capture: true });
+    document.addEventListener("touchmove", onTouchMove, { passive: false, capture: true });
+    document.addEventListener("touchend", onTouchEnd, { passive: true, capture: true });
+    document.addEventListener("touchcancel", onTouchEnd, { passive: true, capture: true });
+    return () => {
+      document.removeEventListener("touchstart", onTouchStart, { capture: true });
+      document.removeEventListener("touchmove", onTouchMove, { capture: true });
+      document.removeEventListener("touchend", onTouchEnd, { capture: true });
+      document.removeEventListener("touchcancel", onTouchEnd, { capture: true });
+      if (frameRef.current !== null) cancelAnimationFrame(frameRef.current);
+    };
+  }, [paint]);
+
+  if (scale === 1) return null;
+
+  // Sized in px on purpose. This is the way back from a chrome that has become
+  // too big to use — it must be the one thing on screen the scale cannot reach.
+  return (
+    <div className="ui-scale-pill" role="status" aria-live="polite">
+      <span>UI {Math.round(scale * 100)}%</span>
+      <button type="button" onClick={reset} aria-label="Reset interface size to 100 percent">
+        Reset
+      </button>
+    </div>
+  );
+}

package/server/src/components/ValidationPanel.tsx

@@ -0,0 +1,62 @@
+"use client";
+
+import { useDesignerStore } from "@/store/useDesignerStore";
+
+export default function ValidationPanel() {
+  const errors = useDesignerStore((s) => s.errors);
+  const validate = useDesignerStore((s) => s.validate);
+  const select = useDesignerStore((s) => s.select);
+
+  return (
+    <div className="p-3">
+      <div className="flex items-center justify-between mb-2">
+        <h3 className="text-xs font-semibold text-gray-400">
+          Validation {errors.length > 0 && <span className="text-red-500">({errors.length})</span>}
+        </h3>
+        <button
+          onClick={() => validate()}
+          className="text-xs bg-gray-700 hover:bg-gray-600 text-gray-300 px-2 py-0.5 rounded"
+        >
+          Re-check
+        </button>
+      </div>
+
+      {errors.length === 0 ? (
+        <div className="flex items-center gap-2 text-green-500 text-xs">
+          <span>✓</span>
+          <span>Definition is valid</span>
+        </div>
+      ) : (
+        <div className="space-y-0.5">
+          {errors.map((err, i) => (
+            <div
+              key={i}
+              // Error rows are tap targets — clicking one selects the offending
+              // element — so they get a thumb-sized row on touch and keep the
+              // dense desktop row from `md` up.
+              className={`flex items-start gap-1.5 text-[13px] py-2.5 border-b border-gray-800/50 md:text-xs md:py-1 ${
+                err.element ? "cursor-pointer hover:bg-gray-800/30" : ""
+              }`}
+              onClick={() => {
+                if (!err.element) return;
+                // Determine if element is a state or event
+                select("state", err.element);
+              }}
+              title={err.element ? `Click to select "${err.element}"` : undefined}
+            >
+              <span className={`font-mono text-[10px] mt-0.5 ${err.severity === "error" ? "text-red-600" : "text-yellow-600"}`}>
+                {err.ruleId}
+              </span>
+              <span className={`flex-1 ${err.severity === "error" ? "text-red-400" : "text-yellow-400"}`}>
+                {err.message}
+              </span>
+              {err.element && (
+                <span className="text-gray-600 text-[10px]">→ {err.element}</span>
+              )}
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

package/server/src/lib/exportImage.ts

@@ -0,0 +1,271 @@
+"use client";
+
+/**
+ * Exporting the board as a picture — the browser half of `smcx render`.
+ *
+ * The CLI redraws a definition from scratch; here the board is already on the
+ * screen as SVG, so the export *is* the canvas, cloned and cleaned. That is the
+ * point: what a designer sees, including every box they dragged by hand, is
+ * what lands in the file. Nothing is re-derived, so nothing can disagree.
+ *
+ * Cleaning means three things, each answering a way the live canvas is not a
+ * picture: the viewport transform comes off (an export frames the whole board,
+ * not the current pan), the invisible fingertip cuffs go (they exist to catch
+ * touches, and a `fill="transparent"` rect in a still is only a bigger file),
+ * and the font moves onto the root element (an SVG loaded as an image is
+ * sandboxed away from the page's stylesheet, and unstated text would come back
+ * in the default serif).
+ */
+
+import { diagramFileName, renderMermaid } from "@miadi/stateloom-protocol";
+import type { StateMachineDefinition } from "@miadi/stateloom-protocol";
+
+/** The id the canvas `<svg>` carries so an export can find it. */
+export const CANVAS_SVG_ID = "stateloom-canvas";
+
+/** Fonts named on the export root, since page CSS cannot reach inside it. */
+const FONT_STACK =
+  "ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif";
+
+const BACKGROUND = "#030712";
+
+/**
+ * What the board can be exported as.
+ *
+ * `mermaid` and `markdown` are the same diagram in text: the bare
+ * `stateDiagram-v2` source for a `.mmd` file a renderer picks up directly, and
+ * the fenced snippet for pasting into a README, an issue, or a chronicle page.
+ * Both come from the definition rather than the canvas — mermaid describes a
+ * graph, not a placement, so there is no board geometry for it to carry.
+ */
+export type ExportFormat = "png" | "jpeg" | "svg" | "mermaid" | "markdown";
+
+export const EXPORT_FORMATS: ExportFormat[] = ["png", "jpeg", "svg", "mermaid", "markdown"];
+
+/** What the picker shows for each format. */
+export const FORMAT_LABEL: Record<ExportFormat, string> = {
+  png: "PNG",
+  jpeg: "JPEG",
+  svg: "SVG",
+  mermaid: "Mermaid",
+  markdown: "Markdown",
+};
+
+const MIME: Record<ExportFormat, string> = {
+  png: "image/png",
+  jpeg: "image/jpeg",
+  svg: "image/svg+xml",
+  mermaid: "text/vnd.mermaid",
+  markdown: "text/markdown",
+};
+
+const EXTENSION: Record<ExportFormat, string> = {
+  png: "png",
+  jpeg: "jpg",
+  svg: "svg",
+  mermaid: "mmd",
+  markdown: "md",
+};
+
+export interface ExportOptions {
+  /** Blank margin around the board, in world units. */
+  padding?: number;
+  /** Pixel multiplier for the raster formats. Defaults to 2. */
+  scale?: number;
+  background?: string;
+}
+
+/** The live canvas element, or null when the board is not mounted. */
+export function canvasElement(): SVGSVGElement | null {
+  if (typeof document === "undefined") return null;
+  return document.getElementById(CANVAS_SVG_ID) as unknown as SVGSVGElement | null;
+}
+
+/**
+ * The world-space box that holds every drawn thing.
+ *
+ * Measured on the *live* group, because `getBBox` needs a laid-out element and
+ * a detached clone has no layout. The group's own transform is excluded by
+ * definition — `getBBox` reports the untransformed union of its children — so
+ * this is the board's extent, whatever the viewport happens to be showing.
+ */
+function worldBox(svg: SVGSVGElement): DOMRect | null {
+  const world = svg.querySelector<SVGGElement>(":scope > g");
+  if (!world) return null;
+  try {
+    const box = world.getBBox();
+    return box.width > 0 && box.height > 0 ? box : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Strip the live-only bits from a cloned subtree. */
+function clean(node: Element): void {
+  for (const child of Array.from(node.children)) {
+    // Fingertip cuffs and the invisible ribbons that catch a tap on an edge:
+    // present only to be touched, and never to be seen.
+    if (child.getAttribute("fill") === "transparent" || child.getAttribute("stroke") === "transparent") {
+      child.remove();
+      continue;
+    }
+    child.removeAttribute("class");
+    child.removeAttribute("style");
+    clean(child);
+  }
+}
+
+/**
+ * Serialize the board as a standalone SVG document framing all of it.
+ *
+ * Returns null when there is no canvas or nothing has been drawn on it.
+ */
+export function serializeCanvas(opts: ExportOptions = {}): string | null {
+  const svg = canvasElement();
+  if (!svg) return null;
+  const box = worldBox(svg);
+  if (!box) return null;
+
+  const padding = opts.padding ?? 48;
+  const background = opts.background ?? BACKGROUND;
+  const minX = Math.round(box.x - padding);
+  const minY = Math.round(box.y - padding);
+  const width = Math.round(box.width + padding * 2);
+  const height = Math.round(box.height + padding * 2);
+
+  const clone = svg.cloneNode(true) as SVGSVGElement;
+  clone.removeAttribute("id");
+  clone.removeAttribute("class");
+  clone.removeAttribute("style");
+  clone.setAttribute("xmlns", "http://www.w3.org/2000/svg");
+  clone.setAttribute("width", String(width));
+  clone.setAttribute("height", String(height));
+  clone.setAttribute("viewBox", `${minX} ${minY} ${width} ${height}`);
+  clone.setAttribute("font-family", FONT_STACK);
+
+  clean(clone);
+
+  // The pan and zoom the designer is currently using are not part of the board.
+  const world = clone.querySelector<SVGGElement>(":scope > g");
+  world?.removeAttribute("transform");
+
+  const backdrop = document.createElementNS("http://www.w3.org/2000/svg", "rect");
+  backdrop.setAttribute("x", String(minX));
+  backdrop.setAttribute("y", String(minY));
+  backdrop.setAttribute("width", String(width));
+  backdrop.setAttribute("height", String(height));
+  backdrop.setAttribute("fill", background);
+  clone.insertBefore(backdrop, clone.firstChild);
+
+  return new XMLSerializer().serializeToString(clone);
+}
+
+/** Paint an SVG document onto a canvas and hand back the encoded bitmap. */
+function rasterize(svg: string, format: "png" | "jpeg", scale: number): Promise<Blob> {
+  return new Promise((resolve, reject) => {
+    const size = svg.match(/width="(\d+)"\s+height="(\d+)"/);
+    const width = size ? Number(size[1]) : 1200;
+    const height = size ? Number(size[2]) : 800;
+
+    const url = URL.createObjectURL(new Blob([svg], { type: "image/svg+xml;charset=utf-8" }));
+    const img = new Image();
+    img.onload = () => {
+      URL.revokeObjectURL(url);
+      const canvas = document.createElement("canvas");
+      canvas.width = Math.max(1, Math.round(width * scale));
+      canvas.height = Math.max(1, Math.round(height * scale));
+      const ctx = canvas.getContext("2d");
+      if (!ctx) {
+        reject(new Error("this browser gave no 2d context to draw into"));
+        return;
+      }
+      // JPEG has no transparency to fall back on, so the backdrop is painted
+      // before the board rather than trusted to the SVG alone.
+      ctx.fillStyle = BACKGROUND;
+      ctx.fillRect(0, 0, canvas.width, canvas.height);
+      ctx.drawImage(img, 0, 0, canvas.width, canvas.height);
+      canvas.toBlob(
+        (blob) => (blob ? resolve(blob) : reject(new Error("the canvas produced no image"))),
+        MIME[format],
+        format === "jpeg" ? 0.92 : undefined
+      );
+    };
+    img.onerror = () => {
+      URL.revokeObjectURL(url);
+      reject(new Error("the browser could not read the serialized board"));
+    };
+    img.src = url;
+  });
+}
+
+export interface ExportSubject {
+  /** The machine being drawn — its `settings.name` names the file. */
+  definition: StateMachineDefinition;
+  /** Absolute path of the project document, when the client knows it. */
+  docPath?: string | null;
+  /** The document's bare name, used when the full path is unknown. */
+  fileName?: string | null;
+}
+
+/**
+ * The download name: `[ep252--]<Machine>--<yyMMddHHmmss>.<ext>`.
+ *
+ * Built by the protocol so a browser download and a `smcx render --stamp` land
+ * on the same shape of name. The episode prefix appears when the document sits
+ * under a chronicle episode; the stamp means the second export of an afternoon
+ * never overwrites the first.
+ */
+export function exportFileName(subject: ExportSubject, format: ExportFormat, at?: Date): string {
+  return diagramFileName({
+    doc: subject.docPath ?? subject.fileName ?? null,
+    machine: subject.definition?.settings?.name ?? null,
+    // A format outside the table is already impossible by type; falling back to
+    // its own name keeps a caller that reached here from JS with a file called
+    // something, rather than one called `.undefined`.
+    format: EXTENSION[format] ?? String(format),
+    at: at ?? new Date(),
+  });
+}
+
+/** The mermaid source, alone or fenced for a markdown document. */
+function mermaidBody(definition: StateMachineDefinition, fenced: boolean): string {
+  const source = renderMermaid(definition);
+  return fenced ? `\`\`\`mermaid\n${source}\n\`\`\`\n` : `${source}\n`;
+}
+
+/**
+ * Export the board and hand it to the browser as a download.
+ *
+ * Throws with a sentence worth showing when there is nothing to draw or the
+ * browser refuses to rasterize — the caller surfaces it on the toolbar.
+ * Returns the name it wrote.
+ */
+export async function downloadCanvas(
+  format: ExportFormat,
+  subject: ExportSubject,
+  opts: ExportOptions = {}
+): Promise<string> {
+  let blob: Blob;
+
+  if (format === "mermaid" || format === "markdown") {
+    blob = new Blob([mermaidBody(subject.definition, format === "markdown")], {
+      type: `${MIME[format]};charset=utf-8`,
+    });
+  } else {
+    const svg = serializeCanvas(opts);
+    if (!svg) throw new Error("nothing on the board to export yet");
+    blob =
+      format === "svg"
+        ? new Blob([svg], { type: `${MIME.svg};charset=utf-8` })
+        : await rasterize(svg, format, opts.scale ?? 2);
+  }
+
+  const name = exportFileName(subject, format);
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = name;
+  a.click();
+  URL.revokeObjectURL(url);
+  return name;
+}

package/server/src/lib/gestureOwner.ts

@@ -0,0 +1,36 @@
+/**
+ * Who owns a two-finger gesture.
+ *
+ * There are exactly two pinch handlers in this app and they must never both fire
+ * on one gesture. The rule that keeps them apart is a property of *where the
+ * fingers landed*, decided once, at touch-down, and never revisited:
+ *
+ *   · The canvas pinch (Canvas.tsx) counts fingers in `pointersRef`, and a
+ *     pointer only ever enters that map from a `pointerdown` that hit the canvas
+ *     pane. So the canvas needs **both** fingers on itself before it will pinch.
+ *   · The chrome pinch (UiScale.tsx) begins only when **neither** finger is on
+ *     the canvas pane, which it tests with the selector below.
+ *
+ * The two conditions are mutually exclusive by construction, and they leave one
+ * deliberate hole: a finger on the canvas and a finger on the toolbar starts
+ * nothing at all. That is the honest answer — the gesture is genuinely ambiguous
+ * — and it is far better than a hand that straddles the boundary silently
+ * resizing both the board and the menus.
+ */
+
+/**
+ * Marks the canvas pane. Read by the chrome pinch to disqualify itself. The
+ * attribute name is written literally as `data-pinch-owner` on the pane in
+ * Canvas.tsx — JSX cannot take it from a constant without a spread — so these
+ * two strings are the pair to keep in step if it is ever renamed.
+ */
+export const PINCH_OWNER_ATTR = "data-pinch-owner";
+export const CANVAS_PINCH_OWNER = "canvas";
+export const CANVAS_PANE_SELECTOR = `[${PINCH_OWNER_ATTR}="${CANVAS_PINCH_OWNER}"]`;
+
+/** Is this touch resting on the canvas pane (the SVG, its HUD, its breadcrumb)? */
+export function isOnCanvasPane(target: EventTarget | null): boolean {
+  const el = target as Element | null;
+  if (!el || typeof el.closest !== "function") return false;
+  return el.closest(CANVAS_PANE_SELECTOR) !== null;
+}