@ikenga/contract 0.6.0 → 0.9.0

package/src/canvas/use-drag-snap.ts

@@ -0,0 +1,107 @@
+// Scale-aware grid-snap drag for the <Canvas> primitive.
+//
+// Owns the in-flight drag gesture (which item, where it started) and the
+// pointer math that moves it: cursor delta is divided by the current viewport
+// scale (so a 10px screen move at scale 0.5 becomes a 20px canvas move, and at
+// scale 2.0 a 5px canvas move), then snapped to the `gridSnap` lattice.
+//
+//   nx = round((startPos.x + dx / scale) / gridSnap) * gridSnap
+//
+// Does NOT own `layout` — it reads the current placement to seed the gesture
+// and emits the moved layout through `onLayoutChange`. The parent stays the
+// source of truth.
+//
+// Extracted verbatim (behavior-preserving) from shell home.tsx's canvas block.
+
+import { useCallback, useEffect, useRef } from 'react';
+import type { ItemId, Placement } from './types.js';
+
+export interface DragState {
+  id: ItemId;
+  startMouse: { x: number; y: number };
+  startPos: { x: number; y: number };
+}
+
+export interface UseDragSnapArgs {
+  /** Controlled layout (id → placement). Read at gesture start; never mutated. */
+  layout: Record<ItemId, Placement>;
+  /** Snap lattice in canvas units. Home passes 12, studio passes 24. */
+  gridSnap: number;
+  /** Current viewport scale — drag delta is divided by this. */
+  scale: number;
+  /** Emits the moved layout so the parent can persist / re-render. */
+  onLayoutChange?: (layout: Record<ItemId, Placement>) => void;
+  /** Stage element whose `.is-dragging` class suppresses the pan transition. */
+  stageRef: React.RefObject<HTMLDivElement | null>;
+}
+
+export interface UseDragSnap {
+  dragState: React.MutableRefObject<DragState | null>;
+  /** Begin dragging `id` from a mousedown at screen (clientX, clientY). */
+  beginDrag: (id: ItemId, clientX: number, clientY: number) => void;
+  /** Is an item drag in flight? */
+  isDragging: () => boolean;
+}
+
+export function useDragSnap(args: UseDragSnapArgs): UseDragSnap {
+  const { layout, gridSnap, scale, onLayoutChange, stageRef } = args;
+  const dragState = useRef<DragState | null>(null);
+
+  // Keep the freshest layout/scale/snap reachable from the global listener
+  // without re-subscribing it on every render.
+  const layoutRef = useRef(layout);
+  layoutRef.current = layout;
+  const scaleRef = useRef(scale);
+  scaleRef.current = scale;
+  const gridSnapRef = useRef(gridSnap);
+  gridSnapRef.current = gridSnap;
+  const onLayoutChangeRef = useRef(onLayoutChange);
+  onLayoutChangeRef.current = onLayoutChange;
+
+  const beginDrag = useCallback(
+    (id: ItemId, clientX: number, clientY: number) => {
+      const w = layoutRef.current[id];
+      if (!w) return;
+      dragState.current = {
+        id,
+        startMouse: { x: clientX, y: clientY },
+        startPos: { x: w.x, y: w.y },
+      };
+      stageRef.current?.classList.add('is-dragging');
+    },
+    [stageRef]
+  );
+
+  const isDragging = useCallback(() => dragState.current != null, []);
+
+  useEffect(() => {
+    const onMove = (e: MouseEvent) => {
+      if (!dragState.current) return;
+      const s = scaleRef.current || 1;
+      const snap = gridSnapRef.current;
+      const dx = e.clientX - dragState.current.startMouse.x;
+      const dy = e.clientY - dragState.current.startMouse.y;
+      const nx = Math.round((dragState.current.startPos.x + dx / s) / snap) * snap;
+      const ny = Math.round((dragState.current.startPos.y + dy / s) / snap) * snap;
+      const id = dragState.current.id;
+      const cur = layoutRef.current;
+      const prev = cur[id];
+      if (!prev || (prev.x === nx && prev.y === ny)) return;
+      onLayoutChangeRef.current?.({ ...cur, [id]: { ...prev, x: nx, y: ny } });
+    };
+    const onUp = () => {
+      if (dragState.current) {
+        dragState.current = null;
+        stageRef.current?.classList.remove('is-dragging');
+      }
+    };
+    window.addEventListener('mousemove', onMove);
+    window.addEventListener('mouseup', onUp);
+    return () => {
+      window.removeEventListener('mousemove', onMove);
+      window.removeEventListener('mouseup', onUp);
+    };
+  }, [stageRef]);
+
+  return { dragState, beginDrag, isDragging };
+}

package/src/canvas/use-pan-zoom.ts

@@ -0,0 +1,211 @@
+// Pan / zoom / auto-fit for the <Canvas> primitive.
+//
+// Owns the viewport pan offset + scale, the imperative auto-fit math, the
+// pan gesture (Space-drag / middle-mouse / empty-canvas drag), and the
+// Space/Escape keyboard affordances + window-resize re-fit. It deliberately
+// does NOT own `layout`, `selectedId`, or `editMode` — those stay parent-held
+// and are threaded in as values so the auto-fit closure can read them.
+//
+// Extracted verbatim (behavior-preserving) from shell home.tsx's canvas block.
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { ItemId, Placement, Viewport } from './types.js';
+
+export interface UsePanZoomArgs {
+  /** Controlled layout (id → placement) the auto-fit bounding box reads. */
+  layout: Record<ItemId, Placement>;
+  /** Controlled edit-mode flag — auto-fit reserves palette width when true. */
+  editMode: boolean;
+  /** Re-fit on window resize. Default true. */
+  autoFitOnResize?: boolean;
+  /** Notified whenever the viewport pan/scale changes (controlled mirror). */
+  onViewportChange?: (viewport: Viewport) => void;
+  /** Escape exits edit mode → parent owns the state flip. */
+  onEditModeChange?: (editMode: boolean) => void;
+  /** Escape clears selection. */
+  onSelectionChange?: (selectedId: ItemId | null) => void;
+}
+
+export interface UsePanZoom {
+  /** Live viewport (x/y/scale). Mirrors `pan` in the original home code. */
+  pan: Viewport;
+  setPan: React.Dispatch<React.SetStateAction<Viewport>>;
+  /** Imperative re-fit. `animate=false` snaps without the transition. */
+  autoFit: (animate?: boolean) => void;
+  canvasRef: React.RefObject<HTMLDivElement | null>;
+  stageRef: React.RefObject<HTMLDivElement | null>;
+  /** True while Space is held — drag/pan branch reads this. */
+  spaceDown: React.MutableRefObject<boolean>;
+  /** Begin a pan gesture from a mousedown at screen (clientX, clientY). */
+  beginPan: (clientX: number, clientY: number) => void;
+  /** Is a pan gesture in flight? */
+  isPanning: () => boolean;
+}
+
+const RESERVED_PALETTE_WIDTH = 320;
+
+export function usePanZoom(args: UsePanZoomArgs): UsePanZoom {
+  const {
+    layout,
+    editMode,
+    autoFitOnResize = true,
+    onViewportChange,
+    onEditModeChange,
+    onSelectionChange,
+  } = args;
+
+  const [pan, setPan] = useState<Viewport>({ x: 0, y: 0, scale: 1 });
+
+  const canvasRef = useRef<HTMLDivElement>(null);
+  const stageRef = useRef<HTMLDivElement>(null);
+  const spaceDown = useRef(false);
+  const panStart = useRef<{ x: number; y: number } | null>(null);
+  // Latest pan reachable synchronously (for beginPan's offset seed) without
+  // adding `pan` to the gesture callbacks' deps.
+  const panRef = useRef(pan);
+  panRef.current = pan;
+
+  // Mirror viewport changes to the controlled parent in an effect (never
+  // inside a setState updater — that would setState-during-render the parent
+  // and trip React's "Cannot update a component while rendering a different
+  // component" warning). The ref skips the initial mount so the parent isn't
+  // notified of the default {0,0,1} before any real fit.
+  const viewportCbRef = useRef(onViewportChange);
+  viewportCbRef.current = onViewportChange;
+  const mountedViewport = useRef(false);
+  useEffect(() => {
+    if (!mountedViewport.current) {
+      mountedViewport.current = true;
+      return;
+    }
+    viewportCbRef.current?.(pan);
+  }, [pan]);
+
+  // Auto-fit: scale the bounding box of all items into the visible area,
+  // scaling down only (never up). Reserves the palette gutter in edit mode.
+  // Threads `layout` + `editMode` as deps so the closure never goes stale.
+  const autoFit = useCallback(
+    (animate = true) => {
+      const canvas = canvasRef.current;
+      const items = Object.values(layout);
+      if (!canvas || !items.length) return;
+      let minX = Infinity,
+        minY = Infinity,
+        maxX = -Infinity,
+        maxY = -Infinity;
+      for (const w of items) {
+        if (w.x < minX) minX = w.x;
+        if (w.y < minY) minY = w.y;
+        if (w.x + w.w > maxX) maxX = w.x + w.w;
+        if (w.y + w.h > maxY) maxY = w.y + w.h;
+      }
+      const cw = canvas.clientWidth - (editMode ? RESERVED_PALETTE_WIDTH : 0) - 40;
+      const ch = canvas.clientHeight - 44 - 32;
+      const bw = maxX - minX;
+      const bh = maxY - minY;
+      const sx = bw > 0 ? cw / bw : 1;
+      const sy = bh > 0 ? ch / bh : 1;
+      const scale = Math.min(1, sx, sy);
+      const offX = Math.round((cw + 40 - bw * scale) / 2 - minX * scale);
+      const offY = Math.round((ch + 32 - bh * scale) / 2 - minY * scale + 22);
+      setPan({ x: offX, y: offY, scale });
+      if (stageRef.current) stageRef.current.classList.toggle('is-dragging', !animate);
+    },
+    [layout, editMode, setPan]
+  );
+
+  // Initial fit + window-resize re-fit. Empty dep array on purpose — autoFit
+  // is read through the ref-stable callback, matching the original effect.
+  useEffect(() => {
+    requestAnimationFrame(() => autoFit(false));
+    if (!autoFitOnResize) return;
+    const onResize = () => autoFit(true);
+    window.addEventListener('resize', onResize);
+    return () => window.removeEventListener('resize', onResize);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // Re-fit whenever edit mode toggles (palette gutter changes the fit box).
+  useEffect(() => {
+    autoFit(true);
+  }, [editMode, autoFit]);
+
+  // Keyboard — Escape exits edit, Space arms the pan-grab cursor.
+  useEffect(() => {
+    const down = (e: KeyboardEvent) => {
+      if (e.key === 'Escape' && editMode) {
+        onEditModeChange?.(false);
+        onSelectionChange?.(null);
+      }
+      if (
+        e.code === 'Space' &&
+        !e.repeat &&
+        document.activeElement === document.body &&
+        canvasRef.current
+      ) {
+        spaceDown.current = true;
+        canvasRef.current.style.cursor = 'grab';
+        e.preventDefault();
+      }
+    };
+    const up = (e: KeyboardEvent) => {
+      if (e.code === 'Space') {
+        spaceDown.current = false;
+        if (canvasRef.current) canvasRef.current.style.cursor = '';
+      }
+    };
+    window.addEventListener('keydown', down);
+    window.addEventListener('keyup', up);
+    return () => {
+      window.removeEventListener('keydown', down);
+      window.removeEventListener('keyup', up);
+    };
+  }, [editMode, onEditModeChange, onSelectionChange]);
+
+  const beginPan = useCallback((clientX: number, clientY: number) => {
+    const p = panRef.current;
+    panStart.current = { x: clientX - p.x, y: clientY - p.y };
+    stageRef.current?.classList.add('is-dragging');
+    if (canvasRef.current) canvasRef.current.style.cursor = 'grabbing';
+  }, []);
+
+  const isPanning = useCallback(() => panStart.current != null, []);
+
+  // Global pan move/up. Drag (item) move/up lives in use-drag-snap so this
+  // effect only owns the pan branch + its own cleanup.
+  useEffect(() => {
+    const onMove = (e: MouseEvent) => {
+      if (panStart.current) {
+        setPan((p) => ({
+          ...p,
+          x: e.clientX - panStart.current!.x,
+          y: e.clientY - panStart.current!.y,
+        }));
+      }
+    };
+    const onUp = () => {
+      if (panStart.current) {
+        panStart.current = null;
+        stageRef.current?.classList.remove('is-dragging');
+        if (canvasRef.current) canvasRef.current.style.cursor = spaceDown.current ? 'grab' : '';
+      }
+    };
+    window.addEventListener('mousemove', onMove);
+    window.addEventListener('mouseup', onUp);
+    return () => {
+      window.removeEventListener('mousemove', onMove);
+      window.removeEventListener('mouseup', onUp);
+    };
+  }, [setPan]);
+
+  return {
+    pan,
+    setPan,
+    autoFit,
+    canvasRef,
+    stageRef,
+    spaceDown,
+    beginPan,
+    isPanning,
+  };
+}

package/src/engine/index.ts

@@ -10,3 +10,5 @@
 export * from './adapter.js';
 export * from './acp.js';
 export * from './errors.js';
+export * from './portability.js';
+export * from './subagent-transcoder.js';

package/src/engine/portability.ts

@@ -0,0 +1,123 @@
+/**
+ * Portability surface for engine pkgs — ADR-012.
+ *
+ * Engine pkgs implement this in parallel to the runtime adapter
+ * (`AcpEngine` in `./acp.ts`). The kernel's `engine_assets` registry calls
+ * these methods at pkg install / uninstall time, fanning the operation out
+ * to every installed `EngineAdapter` so a user's pkg investment (skills,
+ * commands, agents, MCP servers) survives an engine swap.
+ *
+ * No manifest schema changes — pkgs continue to declare `skills`,
+ * `commands`, `agents` as folder paths and `mcp[]` as inline entries.
+ * This file is a runtime interface; it has no Zod schema and no
+ * compile-time dependency on the manifest schema beyond reusing
+ * `McpServer` for the spec passed to `registerMcpServer`.
+ */
+
+import type { McpServer } from '../manifest.js';
+
+/**
+ * Result of an install / register operation. Per ADR §2 the kernel's pkg
+ * manager UI surfaces these so the user can see exactly what each engine
+ * adapter wrote.
+ */
+export interface InstallReport {
+  /** Absolute paths the adapter wrote or symlinked. */
+  wrote: string[];
+  /** Targets that were already correct — idempotent no-op. */
+  skipped: string[];
+  /** Non-fatal notes (e.g. "commands not supported on Codex; skipped"). */
+  warnings: string[];
+}
+
+/**
+ * Dry-run output for `EngineAdapter.plan()`. Shape mirrors `InstallReport`
+ * plus the `(engineId, pkgId)` tuple so the pkg manager UI can render a
+ * per-engine breakdown ("this pkg will install assets into 3 engines").
+ */
+export interface InstallPlan extends InstallReport {
+  /** Engine the plan was computed against — matches `EngineAdapter.id`. */
+  engineId: string;
+  /** Pkg the plan was computed for — matches the manifest `id` field. */
+  pkgId: string;
+}
+
+/**
+ * Minimal pkg manifest slice the adapter needs to compute a plan. Carved
+ * narrow on purpose: `plan()` runs before install, so it shouldn't load
+ * disk content the adapter wouldn't otherwise touch. Folder paths are
+ * relative to the pkg root (same convention as the on-disk manifest).
+ */
+export interface ManifestSnapshot {
+  /** Pkg id (e.g. `com.ikenga.studio`). */
+  id: string;
+  /** Pkg slug used to namespace materialized dirs (id with `.` → `-`). */
+  slug: string;
+  /** Relative folder for `skills/<name>/SKILL.md` files, if any. */
+  skills?: string;
+  /** Relative folder for `commands/<name>.md` files, if any. */
+  commands?: string;
+  /** Relative folder for `agents/<name>.md` files, if any. */
+  agents?: string;
+  /** Inline MCP server specs from the manifest's `mcp[]` block. */
+  mcp: McpServer[];
+}
+
+/**
+ * Portability adapter exported by every engine pkg alongside its runtime
+ * `AcpEngine`. The kernel resolves both at load time (ADR §2).
+ *
+ * Folder-level methods. Each `install*` call is the adapter's chance to
+ * symlink, copy, or walk-and-transcode the whole folder — the choice
+ * depends on what the engine accepts natively. Idempotent by contract:
+ * re-running with unchanged inputs is a no-op.
+ *
+ * `registerMcpServer` writes a single entry into the engine's external
+ * settings file (`~/.claude/settings.json`, `~/.gemini/settings.json`,
+ * `~/.codex/config.toml`). Entries are keyed `ikenga.<pkg-slug>.<name>`
+ * per ADR §7 so they never collide with user-authored entries.
+ *
+ * Inverses tear down only what this pkg owned — user content in the same
+ * dir / settings file is left untouched.
+ */
+export interface EngineAdapter {
+  /** Engine identifier — matches `engine.agentId` in the pkg manifest. */
+  readonly id: string;
+
+  /**
+   * Materialize the pkg's skills folder into the engine's recognized
+   * location. Idempotent.
+   */
+  installSkills(folder: string, pkgId: string, pkgSlug: string): Promise<InstallReport>;
+
+  /**
+   * Materialize the pkg's commands folder. Engines without a first-class
+   * commands primitive (Codex) may emit warnings and skip per-file
+   * instead of erroring — see ADR §5.
+   */
+  installCommands(folder: string, pkgId: string, pkgSlug: string): Promise<InstallReport>;
+
+  /** Materialize the pkg's agents folder. Codex transcodes MD→TOML. */
+  installAgents(folder: string, pkgId: string, pkgSlug: string): Promise<InstallReport>;
+
+  /**
+   * Register one MCP server in the engine's external settings file.
+   * Idempotent on the `(pkgSlug, server name)` key.
+   */
+  registerMcpServer(spec: McpServer, pkgId: string, pkgSlug: string): Promise<InstallReport>;
+
+  /** Inverse of `installSkills`. Removes only entries this pkg owned. */
+  uninstallSkills(pkgId: string, pkgSlug: string): Promise<void>;
+  /** Inverse of `installCommands`. */
+  uninstallCommands(pkgId: string, pkgSlug: string): Promise<void>;
+  /** Inverse of `installAgents`. */
+  uninstallAgents(pkgId: string, pkgSlug: string): Promise<void>;
+  /** Inverse of `registerMcpServer`. */
+  unregisterMcpServer(serverName: string, pkgId: string, pkgSlug: string): Promise<void>;
+
+  /**
+   * Dry-run used by the pkg manager UI. Returns the same shape as a real
+   * install would produce, without touching the filesystem.
+   */
+  plan(pkgId: string, pkgSlug: string, manifestSnapshot: ManifestSnapshot): Promise<InstallPlan>;
+}