@1agh/maude 0.15.0

package/plugins/design/dev-server/inspect.ts

@@ -0,0 +1,365 @@
+// Active-canvas state, selected-element tracking, and HTML injection
+// (inspector overlay + canvas runtime). See plan Task 7 + DDR-007.
+
+import path from 'node:path';
+import type { Context } from './context.ts';
+
+export interface SelectedElement {
+  file: string;
+  /** CSS-selector path (v1 anchor). Always present for backwards-compat + legacy HTML canvases. */
+  selector: string;
+  tag: string;
+  classes: string;
+  text: string;
+  dom_path: string[];
+  bounds: { x: number; y: number; w: number; h: number } | null;
+  html: string;
+  ts: string;
+  /**
+   * Schema version. v2 = TSX canvas with a `data-cd-id` anchor at click target
+   * (or any ancestor — script walks via `closest()`); v1 = no `data-cd-id`
+   * anywhere (legacy `.html` canvases, or click on shell chrome of a TSX
+   * canvas). Readers must accept both during the grace window.
+   */
+  v: 1 | 2;
+  /** Stable per-element id from canvas-pipeline two-pass transform. Present only when v === 2. */
+  id?: string;
+  /**
+   * Canvas slug — POSIX, extension-less, relative to designRoot. Matches
+   * `_locator.json` top-level keys. Present only when v === 2. The inspector
+   * derives it server-side from `file` (stripping `<designRoot>/` prefix + `.tsx`).
+   */
+  canvas?: string;
+}
+
+/**
+ * Phase 4.1: `selected` widens from `SelectedElement | null` to
+ * `SelectedElement | SelectedElement[] | null` for multi-select via canvas-shell
+ * input router. Readers must accept all three shapes. Writer below emits a
+ * single object when cardinality is 1 (back-compat with `/design:edit` +
+ * downstream tools that read the legacy shape) and an array for N > 1.
+ */
+export type SelectedValue = SelectedElement | SelectedElement[] | null;
+
+export interface ActiveState {
+  active: string | null;
+  open_tabs: string[];
+  selected: SelectedValue;
+  last_change: string | null;
+  session_started: string;
+  active_comments?: unknown[];
+}
+
+type SetSelectedInput =
+  | Omit<SelectedElement, 'ts' | 'v' | 'canvas'>
+  | Array<Omit<SelectedElement, 'ts' | 'v' | 'canvas'>>
+  | null;
+
+export interface Inspect {
+  state: ActiveState;
+  load(): Promise<void>;
+  setActive(file: string): void;
+  setOpenTabs(tabs: string[]): void;
+  setSelected(sel: SetSelectedInput): void;
+  save(): Promise<void>;
+  injectInspector(html: string): string;
+}
+
+const NEW = (): ActiveState => ({
+  active: null,
+  open_tabs: [],
+  selected: null,
+  last_change: null,
+  session_started: new Date().toISOString(),
+});
+
+export function createInspect(
+  ctx: Context,
+  loadActiveComments: (file: string) => Promise<unknown[]>
+): Inspect {
+  const state: ActiveState = NEW();
+  let saveQueued = false;
+
+  async function save() {
+    saveQueued = false;
+    try {
+      // Bun.write creates parent dirs automatically — no .keep poke needed.
+      let active_comments: unknown[] = [];
+      if (state.active) {
+        try {
+          active_comments = await loadActiveComments(state.active);
+        } catch {
+          /* ignore */
+        }
+      }
+      const enriched = { ...state, active_comments };
+      await Bun.write(ctx.paths.activeFile, JSON.stringify(enriched, null, 2));
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      console.error('  warn: failed to save _active.json:', msg);
+    }
+  }
+
+  function scheduleSave() {
+    if (saveQueued) return;
+    saveQueued = true;
+    queueMicrotask(save);
+  }
+
+  async function load() {
+    try {
+      const raw = await Bun.file(ctx.paths.activeFile).text();
+      const prev = JSON.parse(raw);
+      Object.assign(state, prev, { session_started: new Date().toISOString() });
+    } catch {
+      // first boot
+    }
+  }
+
+  function setActive(file: string) {
+    if (typeof file !== 'string') return;
+    if (state.active === file) return;
+    state.active = file || null;
+    state.selected = null;
+    state.last_change = new Date().toISOString();
+    scheduleSave();
+    ctx.bus.emit('active', state.active);
+  }
+
+  function setOpenTabs(tabs: string[]) {
+    if (!Array.isArray(tabs)) return;
+    state.open_tabs = tabs.filter((t): t is string => typeof t === 'string');
+    state.last_change = new Date().toISOString();
+    scheduleSave();
+  }
+
+  function enrich(sel: Omit<SelectedElement, 'ts' | 'v' | 'canvas'>): SelectedElement {
+    const file = typeof sel.file === 'string' ? sel.file : (state.active ?? '');
+    const id = typeof sel.id === 'string' && sel.id ? sel.id : undefined;
+    const v: 1 | 2 = id ? 2 : 1;
+    return {
+      file,
+      selector: String(sel.selector || ''),
+      tag: String(sel.tag || ''),
+      classes: String(sel.classes || ''),
+      text: String(sel.text || '').slice(0, 240),
+      dom_path: Array.isArray(sel.dom_path) ? sel.dom_path.slice(0, 16) : [],
+      bounds: sel.bounds ?? null,
+      html: String(sel.html || '').slice(0, 4000),
+      ts: new Date().toISOString(),
+      v,
+      ...(id ? { id, canvas: deriveCanvasSlug(file) } : {}),
+    };
+  }
+
+  function setSelected(sel: SetSelectedInput) {
+    if (sel == null) {
+      state.selected = null;
+    } else if (Array.isArray(sel)) {
+      const enriched = sel
+        .filter(
+          (s): s is Omit<SelectedElement, 'ts' | 'v' | 'canvas'> => !!s && typeof s === 'object'
+        )
+        .map(enrich);
+      // Writer back-compat: collapse single-entry array to a bare object so
+      // legacy readers (`/design:edit`, handoff tooling) keep working without
+      // schema awareness. N>1 stays as an array.
+      if (enriched.length === 0) state.selected = null;
+      else if (enriched.length === 1) state.selected = enriched[0] ?? null;
+      else state.selected = enriched;
+    } else if (typeof sel === 'object') {
+      state.selected = enrich(sel);
+    } else {
+      state.selected = null;
+    }
+    state.last_change = new Date().toISOString();
+    scheduleSave();
+    ctx.bus.emit('selected', state.selected);
+  }
+
+  /**
+   * Canvas slug for v2 selections. Mirrors `canvasSlug()` from locator.ts but
+   * accepts a designRoot-relative `file` path (which is what the iframe reports)
+   * rather than an absolute one. Strips a leading `<designRoot-relative>/` if
+   * present and strips the final extension.
+   */
+  function deriveCanvasSlug(file: string): string {
+    let s = (file || '').replace(/^\/+/, '');
+    // Strip a leading designRoot prefix if it's part of the file path. The
+    // iframe's pathname includes the design root (e.g. `.design/ui/Foo.tsx`);
+    // locator.ts strips it via path.relative — mirror that here.
+    const dr = ctx.paths.designRel.replace(/^\.\//, '').replace(/^\/+|\/+$/g, '');
+    if (dr && s.startsWith(`${dr}/`)) s = s.slice(dr.length + 1);
+    const dot = s.lastIndexOf('.');
+    return dot > 0 ? s.slice(0, dot) : s;
+  }
+
+  return {
+    state,
+    load,
+    setActive,
+    setOpenTabs,
+    setSelected,
+    save,
+    injectInspector,
+  };
+}
+
+// ---------- Inspector script injection ----------
+
+function injectInspector(html: string): string {
+  const idx = html.lastIndexOf('</body>');
+  if (idx === -1) return html + INSPECTOR_SCRIPT;
+  return html.slice(0, idx) + INSPECTOR_SCRIPT + html.slice(idx);
+}
+
+// Comment-pin rendering overlay injected into every served HTML page under
+// designRoot. Pin layer is the ONLY responsibility — hover/click selection is
+// owned by canvas-shell.tsx (TSX canvases) and isn't applicable to legacy
+// `.html` mocks since the broader migration to TSX. Pin layer keeps working
+// in both, because pins are positioned by selector and updated via the
+// `comments-set` postMessage channel from the shell.
+const INSPECTOR_SCRIPT = `
+<script>
+(function() {
+  if (window.__designInspectorAttached) return;
+  window.__designInspectorAttached = true;
+
+  var styleEl = document.createElement('style');
+  styleEl.textContent = [
+    '.dgn-pin { position: absolute; top: 0; left: 0; z-index: 2147483646; width: 22px; height: 22px; padding: 0; border: 0; border-radius: 999px 999px 999px 4px; background: #facc15; color: #1c1917; font: 600 11px/22px ui-sans-serif, system-ui, sans-serif; text-align: center; cursor: pointer; box-shadow: 0 2px 6px rgba(0,0,0,0.5), 0 0 0 1px rgba(0,0,0,0.4); transition: filter 120ms; transform-origin: bottom left; will-change: transform; }',
+    '.dgn-pin:hover { filter: brightness(1.1); outline: 2px solid rgba(0,0,0,0.3); }',
+    '.dgn-pin.resolved { background: #22c55e; color: #052e16; }',
+    '.dgn-pin.focused { box-shadow: 0 4px 12px rgba(0,0,0,0.6), 0 0 0 2px #fff; outline: 2px solid #fff; }'
+  ].join('\\n');
+  document.documentElement.appendChild(styleEl);
+
+  var pinLayer = document.createElement('div');
+  pinLayer.id = 'dgn-pin-layer';
+  pinLayer.style.cssText = 'position:absolute;top:0;left:0;width:0;height:0;pointer-events:none;z-index:2147483646;';
+  document.documentElement.appendChild(pinLayer);
+
+  var commentsCache = [];
+  var focusedPinId = null;
+
+  var pinNodes = [];
+  var rafToken = null;
+
+  function buildPinNodes() {
+    pinLayer.innerHTML = '';
+    pinNodes = [];
+    var withSelector = commentsCache.filter(function(c) { return c && c.selector; });
+    withSelector.forEach(function(c, i) {
+      var target = null;
+      try { target = document.querySelector(c.selector); } catch (e) {}
+      var pin = document.createElement('button');
+      pin.className = 'dgn-pin' + (c.status === 'resolved' ? ' resolved' : '') + (c.id === focusedPinId ? ' focused' : '');
+      pin.textContent = String(i + 1);
+      pin.title = (c.text || '').slice(0, 200);
+      pin.style.pointerEvents = 'auto';
+      pin.style.left = '0px';
+      pin.style.top = '0px';
+      pin.dataset.id = c.id;
+      pin.addEventListener('click', function(ev) {
+        ev.preventDefault();
+        ev.stopPropagation();
+        focusedPinId = c.id;
+        try { window.parent.postMessage({ dgn: 'comment-click', id: c.id }, '*'); } catch (e) {}
+        buildPinNodes();
+      });
+      pinLayer.appendChild(pin);
+      pinNodes.push({ el: pin, comment: c, target: target });
+    });
+    placePins();
+  }
+
+  function placePins() {
+    if (!pinNodes.length) return;
+    for (var i = 0; i < pinNodes.length; i++) {
+      var node = pinNodes[i];
+      var x, y, hidden = false;
+      if (!node.target || !node.target.isConnected) {
+        try { node.target = document.querySelector(node.comment.selector); } catch (e) {}
+      }
+      if (node.target) {
+        var r = node.target.getBoundingClientRect();
+        x = r.left + window.scrollX - 8;
+        y = r.top + window.scrollY - 8;
+        if (r.width === 0 && r.height === 0) hidden = true;
+      } else if (node.comment.bounds) {
+        x = node.comment.bounds.x - 8;
+        y = node.comment.bounds.y - 8;
+      } else {
+        hidden = true;
+      }
+      if (hidden) {
+        node.el.style.display = 'none';
+      } else {
+        node.el.style.display = '';
+        var scale = (node.comment.id === focusedPinId) ? 1.2 : 1;
+        node.el.style.transform = 'translate(' + Math.round(x) + 'px, ' + Math.round(y) + 'px) scale(' + scale + ')';
+      }
+    }
+  }
+
+  function tick() {
+    rafToken = null;
+    placePins();
+    if (pinNodes.length) rafToken = requestAnimationFrame(tick);
+  }
+  function startTick() {
+    if (rafToken == null && pinNodes.length) rafToken = requestAnimationFrame(tick);
+  }
+
+  function schedulePins() { buildPinNodes(); startTick(); }
+
+  window.addEventListener('resize', placePins);
+  document.addEventListener('scroll', placePins, { passive: true, capture: true });
+  document.addEventListener('wheel',  function() { startTick(); }, { passive: true, capture: true });
+  document.addEventListener('pointermove', function(e) { if (e.buttons) startTick(); }, { passive: true, capture: true });
+  document.addEventListener('keyup', function() { startTick(); }, true);
+  if (typeof MutationObserver !== 'undefined') {
+    new MutationObserver(function(){ startTick(); }).observe(document.documentElement, { subtree: true, attributes: true, attributeFilter: ['style', 'class'], childList: true });
+  }
+
+  window.addEventListener('message', function(e) {
+    var m = e.data;
+    if (!m || typeof m !== 'object' || !m.dgn) return;
+    if (m.dgn === 'comments-set' && Array.isArray(m.comments)) {
+      commentsCache = m.comments;
+      schedulePins();
+    } else if (m.dgn === 'comment-focus') {
+      focusedPinId = m.id || null;
+      pinNodes.forEach(function(node) {
+        node.el.classList.toggle('focused', node.comment.id === focusedPinId);
+      });
+      placePins();
+      startTick();
+      var c = commentsCache.find(function(x){ return x && x.id === m.id; });
+      if (c && c.selector) {
+        try {
+          var t = document.querySelector(c.selector);
+          if (t) t.scrollIntoView({ behavior: 'smooth', block: 'center' });
+        } catch (e) {}
+      }
+    }
+    /* force-clear is now consumed by canvas-shell.tsx — the inspector
+       overlay has no per-element selection state to clear anymore. */
+  });
+
+  try {
+    var p = location.pathname;
+    var file;
+    if (p === '/_canvas-shell.html' || p === '/_canvas-shell') {
+      var qs = new URLSearchParams(location.search);
+      var canvas = qs.get('canvas') || '';
+      var designRel = (qs.get('designRel') || '.design').replace(/^\\/+|\\/+$/g, '');
+      file = designRel + '/' + canvas;
+    } else {
+      file = decodeURIComponent(p).replace(/^\\//, '');
+    }
+    window.parent.postMessage({ dgn: 'loaded', file: file }, '*');
+  } catch (e) {}
+})();
+</script>
+`;

package/plugins/design/dev-server/locator.ts

@@ -0,0 +1,159 @@
+// LocatorMap reader/writer for <designRoot>/_locator.json (DDR-019, Phase 3.6 Task 2).
+//
+// _locator.json is a multi-canvas map keyed by canvas slug. Each canvas's value
+// is its LocatorMap (data-cd-id -> source location). The same file holds the
+// state for every canvas under the design root, so concurrent transpiles
+// against different canvases share the file but must not corrupt each other.
+//
+// Concurrency strategy: per-path Promise-chained mutex. Each write to a given
+// _locator.json serialises behind the previous write on the same path. Cheap
+// (no OS-level locking) and sufficient because the dev-server is the only
+// writer.
+//
+// On-disk shape:
+//   {
+//     "ui/Docs Site": {
+//       "a1b2c3d4": { canvas, line, col, jsxPath, componentName },
+//       ...
+//     },
+//     "ui/Canvas Viewport": { ... }
+//   }
+// Top-level keys are POSIX-style canvas slugs relative to designRoot, ext-less.
+
+import path from 'node:path';
+
+export interface LocatorEntry {
+  /** Absolute path of the canvas .tsx file the ID belongs to. */
+  canvas: string;
+  /** 1-based line number of the JSXElement's opening tag. */
+  line: number;
+  /** 0-based column number of the JSXElement's opening tag. */
+  col: number;
+  /** Breadcrumb of JSX element-type names from component root down. */
+  jsxPath: string[];
+  /** Enclosing component name (PascalCase fn/arrow), "" if outside any component. */
+  componentName: string;
+}
+
+export type LocatorMap = Record<string, LocatorEntry>;
+export type LocatorFile = Record<string, LocatorMap>;
+
+/**
+ * Canvas slug used as the top-level key in _locator.json. Posix-style,
+ * extension-less, relative to designRoot. Matches the slug shape that
+ * bin/slug.sh produces for `_history/<slug>/`.
+ */
+export function canvasSlug(canvasAbsPath: string, designRoot: string): string {
+  const rel = path.posix.normalize(
+    path.relative(designRoot, canvasAbsPath).split(path.sep).join('/')
+  );
+  // strip extension
+  const dot = rel.lastIndexOf('.');
+  return dot > 0 ? rel.slice(0, dot) : rel;
+}
+
+// ---------------------------------------------------------------------------
+// Per-path mutex. Promise chain — each acquire waits on the previous release.
+
+const locks = new Map<string, Promise<void>>();
+function withLock<T>(filePath: string, fn: () => Promise<T>): Promise<T> {
+  const prev = locks.get(filePath) ?? Promise.resolve();
+  let release!: () => void;
+  const gate = new Promise<void>((res) => {
+    release = res;
+  });
+  const next = prev.then(() => gate);
+  locks.set(filePath, next);
+  return prev.then(fn).finally(() => {
+    release();
+    // Only the last queued acquire clears the map entry; intermediate ones
+    // leave it pointing at the still-pending tail.
+    if (locks.get(filePath) === next) locks.delete(filePath);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Reader
+
+export async function readLocatorFile(locatorAbsPath: string): Promise<LocatorFile> {
+  const f = Bun.file(locatorAbsPath);
+  if (!(await f.exists())) return {};
+  try {
+    const raw = await f.text();
+    if (!raw.trim()) return {};
+    const parsed = JSON.parse(raw) as unknown;
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return parsed as LocatorFile;
+    }
+    return {};
+  } catch {
+    // Corrupt / mid-write — treat as empty rather than throw. The next write
+    // overwrites cleanly.
+    return {};
+  }
+}
+
+export async function readLocator(
+  locatorAbsPath: string,
+  slug: string
+): Promise<LocatorMap | null> {
+  const file = await readLocatorFile(locatorAbsPath);
+  return file[slug] ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// Writer — atomic per-canvas update. Writes to "<file>.tmp.<rand>", then
+// renames over the original. Per-path mutex prevents concurrent writers from
+// trampling each other's slug entries.
+
+export function writeLocator(locatorAbsPath: string, slug: string, map: LocatorMap): Promise<void> {
+  return withLock(locatorAbsPath, async () => {
+    const current = await readLocatorFile(locatorAbsPath);
+    const next: LocatorFile = { ...current, [slug]: map };
+    const json = stableStringify(next);
+    const tmp = `${locatorAbsPath}.tmp.${Math.random().toString(36).slice(2, 10)}`;
+    await Bun.write(tmp, json);
+    // Bun has no direct rename — use node:fs/promises. fsync of the dir is
+    // overkill for a dev-tool sidecar; the rename is atomic on POSIX which is
+    // all we ship to.
+    const { rename } = await import('node:fs/promises');
+    await rename(tmp, locatorAbsPath);
+  });
+}
+
+/**
+ * Drop a canvas's slug from the locator file (e.g. on canvas deletion).
+ * No-op if the slug isn't present.
+ */
+export function clearLocatorSlug(locatorAbsPath: string, slug: string): Promise<void> {
+  return withLock(locatorAbsPath, async () => {
+    const current = await readLocatorFile(locatorAbsPath);
+    if (!(slug in current)) return;
+    delete current[slug];
+    const json = stableStringify(current);
+    const tmp = `${locatorAbsPath}.tmp.${Math.random().toString(36).slice(2, 10)}`;
+    await Bun.write(tmp, json);
+    const { rename } = await import('node:fs/promises');
+    await rename(tmp, locatorAbsPath);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Deterministic JSON — sorted keys at every level, 2-space indent, trailing
+// newline. Makes git diffs of _locator.json reviewable (and stable across
+// re-transpiles when source hasn't changed). The replacer sorts; callers do
+// not need to pre-sort.
+
+function stableStringify(obj: LocatorFile): string {
+  return `${JSON.stringify(obj, sortedSlugKeysReplacer, 2)}\n`;
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: JSON.stringify replacer signature
+function sortedSlugKeysReplacer(_key: string, value: any): any {
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    const sorted: Record<string, unknown> = {};
+    for (const k of Object.keys(value).sort()) sorted[k] = value[k];
+    return sorted;
+  }
+  return value;
+}

package/plugins/design/dev-server/mem.ts

@@ -0,0 +1,97 @@
+// Memory hygiene: FinalizationRegistry-backed iframe-state cleanup +
+// periodic heap-watch. See plan Task 8 + DDR-009.
+//
+// FinalizationRegistry callbacks are not guaranteed — they are the safety net,
+// not the primary path. The primary path is the explicit `iframe:closed` event
+// emitted on the bus, which calls cleanupFn synchronously.
+
+const HEAP_WARN_BYTES = 256 * 1024 * 1024; // 256 MB — log only
+const HEAP_PANIC_BYTES = 384 * 1024 * 1024; // 384 MB — force GC
+
+let registry: FinalizationRegistry<{ id: string; cleanupFn: () => void }> | null = null;
+
+function ensureRegistry(): FinalizationRegistry<{ id: string; cleanupFn: () => void }> {
+  if (registry) return registry;
+  registry = new FinalizationRegistry((held) => {
+    try {
+      held.cleanupFn();
+    } catch (err) {
+      console.error(`[mem] finalize callback for ${held.id} threw:`, err);
+    }
+  });
+  return registry;
+}
+
+/**
+ * Register a per-iframe cleanup function. The callback fires when the host
+ * object is GC'd, OR when the caller explicitly invokes `cleanupFn`.
+ */
+export function registerIframe(id: string, host: object, cleanupFn: () => void) {
+  ensureRegistry().register(host, { id, cleanupFn });
+}
+
+/**
+ * Weak-ref'd map. Lookups deref to undefined when the entry has been GC'd.
+ * Caller must null-check on every get().
+ */
+export class WeakMapById<T extends object> {
+  private map = new Map<string, WeakRef<T>>();
+
+  set(id: string, value: T) {
+    this.map.set(id, new WeakRef(value));
+  }
+
+  get(id: string): T | undefined {
+    const ref = this.map.get(id);
+    if (!ref) return undefined;
+    const value = ref.deref();
+    if (!value) {
+      this.map.delete(id);
+      return undefined;
+    }
+    return value;
+  }
+
+  delete(id: string) {
+    this.map.delete(id);
+  }
+
+  /** Sweep dead refs; returns the number of slots reclaimed. */
+  sweep(): number {
+    let n = 0;
+    for (const [id, ref] of this.map) {
+      if (!ref.deref()) {
+        this.map.delete(id);
+        n++;
+      }
+    }
+    return n;
+  }
+}
+
+let heapTimer: ReturnType<typeof setInterval> | null = null;
+
+export function startHeapWatch(intervalMs = 60_000) {
+  if (heapTimer) return;
+  heapTimer = setInterval(() => {
+    const u = process.memoryUsage();
+    if (u.heapTotal > HEAP_PANIC_BYTES) {
+      console.warn(
+        `[mem] heap ${(u.heapTotal / 1024 / 1024).toFixed(0)}MB > panic threshold — forcing GC`
+      );
+      // Bun.gc(true) is sync; Node has no equivalent without --expose-gc.
+      const gc = (globalThis as { Bun?: { gc?: (sync: boolean) => void } }).Bun?.gc;
+      if (gc) gc(true);
+    } else if (u.heapTotal > HEAP_WARN_BYTES) {
+      console.warn(`[mem] heap ${(u.heapTotal / 1024 / 1024).toFixed(0)}MB > warn threshold`);
+    }
+  }, intervalMs);
+  // Don't keep the event loop alive just for the heap watch.
+  const t = heapTimer as unknown as { unref?: () => void };
+  t.unref?.();
+}
+
+export function stopHeapWatch() {
+  if (heapTimer) clearInterval(heapTimer);
+  heapTimer = null;
+}