npm - @1agh/maude - Versions diffs - 0.15.0 - Mend

@1agh/maude 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (211) hide show

package/plugins/design/dev-server/config.schema.json ADDED Viewed

@@ -0,0 +1,147 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Design Plugin — per-repo config",
+  "description": "Per-repo configuration consumed by the design plugin's dev-server, slash commands, and skills. Place at <repo>/.design/config.json.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["name", "designRoot"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Short repo / product name. Shown in server header and as a token in skill prompts."
+    },
+    "projectLabel": {
+      "type": "string",
+      "description": "Long label for the design browser (window title and big H1). Defaults to <name> + ' Design'."
+    },
+    "designRoot": {
+      "type": "string",
+      "description": "Repo-relative root where canvas + design system files live. Default convention: '.design' (top-level, alongside .git, .claude, etc.). Older repos may use '.ai/design'.",
+      "default": ".design"
+    },
+    "canvasGroups": {
+      "type": "array",
+      "description": "Top-level groupings shown in the file tree. Each entry maps a folder under designRoot to a sidebar section.",
+      "items": {
+        "type": "object",
+        "required": ["label", "path"],
+        "properties": {
+          "label": { "type": "string" },
+          "path": {
+            "type": "string",
+            "description": "Folder under designRoot to scan for .html canvases."
+          }
+        },
+        "additionalProperties": false
+      },
+      "default": [
+        { "label": "Design system", "path": "system" },
+        { "label": "Canvases", "path": "ui" }
+      ]
+    },
+    "rootClass": {
+      "type": "string",
+      "description": "Body / canvas root CSS class that the project's tokens are scoped under. Generated canvases use <body class=\"<rootClass>\">.",
+      "default": "app"
+    },
+    "themeDefault": {
+      "type": "string",
+      "enum": ["dark", "light"],
+      "description": "Default theme attribute (data-theme) for new canvases.",
+      "default": "dark"
+    },
+    "tokensCssRel": {
+      "type": "string",
+      "description": "Path to the design system CSS, relative to designRoot. New canvases <link> to this file.",
+      "default": "system/colors_and_type.css"
+    },
+    "teamAccentDefault": {
+      "type": ["string", "null"],
+      "description": "Optional default value for data-team attribute on new canvases. Set to null if the project doesn't use multi-team accent overrides."
+    },
+    "handoffTargets": {
+      "type": "array",
+      "description": "Where /design:handoff emits target artifacts. Empty array disables handoff. Special `path` values: `registry:item` emits a shadcn registry-item.json sidecar next to the canvas (Phase 3.6 default — consume via `bunx shadcn add file://./<Slug>.registry.json`). Any other path is treated as a repo-relative target dir for legacy direct-migration handoff. Recommended single-entry default: `[{ label: 'shadcn registry', path: 'registry:item', platform: 'web' }]`.",
+      "items": {
+        "type": "object",
+        "required": ["label", "path"],
+        "properties": {
+          "label": { "type": "string" },
+          "path": {
+            "type": "string",
+            "description": "`registry:item` for shadcn sidecar emit, or repo-relative target dir for direct migration."
+          },
+          "platform": { "type": "string", "enum": ["web", "mobile", "desktop", "other"] }
+        },
+        "additionalProperties": false
+      },
+      "default": []
+    },
+    "newCanvasDir": {
+      "type": "string",
+      "description": "Default folder (under designRoot) where /design:new scaffolds new canvas .tsx files (Phase 3.6+; older repos may still hold .html canvases pending one-shot migration).",
+      "default": "ui"
+    },
+    "newComponentDir": {
+      "type": "string",
+      "description": "Default folder (under designRoot) where /design:new puts shared component .jsx files.",
+      "default": "ui/components"
+    },
+    "extensions": {
+      "type": "array",
+      "description": "User-added directories the docs renderer / completeness-critic should track but not validate against the standard schema. Each entry maps a folder (under the DS) to a label.",
+      "items": {
+        "type": "object",
+        "required": ["label", "path"],
+        "properties": {
+          "label": { "type": "string" },
+          "path": { "type": "string" }
+        },
+        "additionalProperties": false
+      },
+      "default": []
+    },
+    "completenessProfile": {
+      "type": "string",
+      "enum": ["minimal", "standard", "strict"],
+      "description": "Severity profile for the design-system-completeness-critic. 'minimal' = Core blockers only; 'standard' = Core + most Conventional checks; 'strict' = all checks incl. voice/tone/hard-stops in README.",
+      "default": "standard"
+    },
+    "activeFamilies": {
+      "type": "array",
+      "description": "Token families this project has in scope. Computed during /design:setup-ds. The completeness-critic uses this to gate Conventional checks (e.g. type-mono specimen only required when 'mono' is here).",
+      "items": {
+        "type": "string",
+        "enum": ["accent", "status", "presence", "mono"]
+      },
+      "default": ["accent"]
+    },
+    "designSystems": {
+      "type": "array",
+      "description": "Design systems available in this project. Single-DS projects have one entry; multi-DS projects (marketing vs. admin vs. mobile) list each here. Each canvas's .meta.json declares which DS it uses via the 'designSystem' field.",
+      "items": {
+        "type": "object",
+        "required": ["name", "path"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$",
+            "description": "Kebab-case slug. Used to match canvas .meta.json.designSystem references."
+          },
+          "path": {
+            "type": "string",
+            "description": "Folder under designRoot (e.g. 'system/marketing')."
+          },
+          "description": { "type": "string" }
+        },
+        "additionalProperties": false
+      },
+      "default": []
+    },
+    "defaultDesignSystem": {
+      "type": ["string", "null"],
+      "description": "Name of the DS used when a canvas's .meta.json has no 'designSystem' field. For single-DS projects, this is the only DS. For multi-DS, pick the most common.",
+      "default": null
+    }
+  }
+}

package/plugins/design/dev-server/context-menu.tsx ADDED Viewed

@@ -0,0 +1,343 @@
+/**
+ * @file       context-menu.tsx — Phase 4.1 right-click context menu
+ * @scope      plugins/design/dev-server/context-menu.tsx
+ * @purpose    Floating, context-aware right-click menu. The router calls
+ *             `openContextMenu({ clientX, clientY, target })`; the menu
+ *             resolves the section list via the ContextRegistry and renders
+ *             items with right-aligned shortcut hints. Pattern prior:
+ *             `audience-pro/components-toast-menu.html` (hairline border,
+ *             mono shortcut hints, sep lines).
+ *
+ * Targeting taxonomy:
+ *   - element        — cursor is over a `[data-cd-id]` descendant
+ *   - artboard-chrome — cursor over an artboard's label/border (`[data-dc-screen]`)
+ *   - world           — cursor on empty canvas background
+ *   - overlay         — cursor over MiniMap / ZoomToolbar / ToolPalette
+ *                       (no menu — bubble through)
+ *
+ * Items registered for each target type live in the default registry; consumers
+ * can extend via `<ContextMenuProvider extra={...}>` (Phase 5+).
+ */
+import {
+  type ReactNode,
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+export type ContextTargetKind = 'element' | 'artboard-chrome' | 'world' | 'overlay';
+export interface ContextTarget {
+  kind: ContextTargetKind;
+  /** Resolved DOM element under cursor (raw hit). */
+  el: Element | null;
+  /** Stable `data-cd-id` if the hit is inside a TSX-pipeline-stamped subtree. */
+  cdId: string | null;
+  /** Owning artboard id (`data-dc-screen`). */
+  artboardId: string | null;
+  /** Viewport coords for the menu position. */
+  clientX: number;
+  clientY: number;
+}
+export interface MenuItem {
+  id: string;
+  label: string;
+  /** Right-aligned shortcut hint (e.g. `⌘C`, `⌫`). */
+  shortcut?: string;
+  destructive?: boolean;
+  disabled?: boolean;
+  onSelect: (target: ContextTarget) => void;
+}
+export type MenuSection = MenuItem[];
+export type ContextRegistry = Record<ContextTargetKind, MenuSection[]>;
+// ─────────────────────────────────────────────────────────────────────────────
+// Default registry. Item callbacks intentionally use `console.warn` for the
+// un-implemented affordances; T6 + later phases wire real handlers in.
+function noop(name: string) {
+  return () => {
+    if (typeof console !== 'undefined') {
+      console.warn(`[context-menu] TODO: ${name}`);
+    }
+  };
+}
+const DEFAULT_REGISTRY: ContextRegistry = {
+  element: [
+    [
+      { id: 'add-comment', label: 'Add comment', shortcut: 'C', onSelect: noop('add-comment') },
+      { id: 'copy-css', label: 'Copy CSS', shortcut: '⌘⇧C', onSelect: noop('copy-css') },
+      { id: 'copy-id', label: 'Copy data-cd-id', onSelect: noop('copy-id') },
+      { id: 'inspect', label: 'Inspect', shortcut: '⌥I', onSelect: noop('inspect') },
+    ],
+    [
+      { id: 'hide', label: 'Hide', shortcut: '⌘⇧H', onSelect: noop('hide') },
+      { id: 'lock', label: 'Lock', shortcut: '⌘⇧L', onSelect: noop('lock') },
+    ],
+  ],
+  'artboard-chrome': [
+    [
+      { id: 'rename', label: 'Rename', shortcut: '↵', onSelect: noop('rename-artboard') },
+      { id: 'duplicate', label: 'Duplicate', shortcut: '⌘D', onSelect: noop('duplicate-artboard') },
+    ],
+    [
+      { id: 'fit-one', label: 'Fit just this artboard', onSelect: noop('fit-one') },
+      { id: 'reset-pos', label: 'Reset position', onSelect: noop('reset-artboard-pos') },
+    ],
+  ],
+  world: [
+    [
+      {
+        id: 'paste-artboard',
+        label: 'Paste artboard',
+        shortcut: '⌘V',
+        onSelect: noop('paste-artboard'),
+      },
+      { id: 'fit-view', label: 'Fit to view', shortcut: '1', onSelect: noop('fit-view') },
+      { id: 'reset-view', label: 'Reset view', shortcut: '⌘0', onSelect: noop('reset-view') },
+    ],
+  ],
+  overlay: [],
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Provider / context
+interface ContextMenuValue {
+  open: (target: ContextTarget) => void;
+  close: () => void;
+  registry: ContextRegistry;
+}
+const ContextMenuContext = createContext<ContextMenuValue | null>(null);
+interface InternalState {
+  target: ContextTarget | null;
+}
+const MENU_CSS = `
+.dc-context-menu {
+  position: fixed;
+  z-index: 7;
+  background: var(--bg-1, #fff);
+  border: 1px solid var(--border-default, rgba(0,0,0,0.12));
+  border-radius: var(--radius-md, 6px);
+  box-shadow: var(--shadow-md, 0 8px 24px rgba(0,0,0,0.12));
+  padding: 4px;
+  min-width: 220px;
+  font: inherit;
+  font-size: 12px;
+  color: var(--fg-0, rgba(20,15,10,0.92));
+  user-select: none;
+}
+.dc-context-menu .dc-menu-sep {
+  height: 1px;
+  background: var(--border-subtle, rgba(0,0,0,0.08));
+  margin: 4px -4px;
+}
+.dc-context-menu .dc-menu-item {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 16px;
+  padding: 6px 10px;
+  border-radius: var(--radius-sm, 4px);
+  cursor: pointer;
+  background: transparent;
+  border: 0;
+  width: 100%;
+  text-align: left;
+  font: inherit;
+  color: inherit;
+}
+.dc-context-menu .dc-menu-item:hover,
+.dc-context-menu .dc-menu-item:focus-visible {
+  background: var(--bg-3, rgba(0,0,0,0.05));
+  outline: none;
+}
+.dc-context-menu .dc-menu-item[disabled] {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+.dc-context-menu .dc-menu-item.is-destructive:hover,
+.dc-context-menu .dc-menu-item.is-destructive:focus-visible {
+  background: var(--status-error, #c0392b);
+  color: var(--accent-fg, #fff);
+}
+.dc-context-menu .dc-menu-shortcut {
+  color: var(--fg-2, rgba(40,30,20,0.55));
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 10px;
+  font-variant-numeric: tabular-nums;
+}
+`.trim();
+function ensureMenuStyles(): void {
+  if (typeof document === 'undefined') return;
+  if (document.getElementById('dc-context-menu-css')) return;
+  const s = document.createElement('style');
+  s.id = 'dc-context-menu-css';
+  s.textContent = MENU_CSS;
+  document.head.appendChild(s);
+}
+export function ContextMenuProvider({
+  children,
+  registry = DEFAULT_REGISTRY,
+}: {
+  children: ReactNode;
+  registry?: ContextRegistry;
+}) {
+  const [state, setState] = useState<InternalState>({ target: null });
+  const open = useCallback((target: ContextTarget) => {
+    if (target.kind === 'overlay') return;
+    setState({ target });
+  }, []);
+  const close = useCallback(() => setState({ target: null }), []);
+  const value = useMemo<ContextMenuValue>(
+    () => ({ open, close, registry }),
+    [open, close, registry]
+  );
+  return (
+    <ContextMenuContext.Provider value={value}>
+      {children}
+      {state.target ? (
+        <ContextMenuView
+          target={state.target}
+          sections={registry[state.target.kind] ?? []}
+          onClose={close}
+        />
+      ) : null}
+    </ContextMenuContext.Provider>
+  );
+}
+export function useContextMenu(): ContextMenuValue {
+  const ctx = useContext(ContextMenuContext);
+  if (!ctx) {
+    throw new Error('useContextMenu must be used inside <ContextMenuProvider>');
+  }
+  return ctx;
+}
+export function useContextMenuOptional(): ContextMenuValue | null {
+  return useContext(ContextMenuContext);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// View
+function ContextMenuView({
+  target,
+  sections,
+  onClose,
+}: {
+  target: ContextTarget;
+  sections: MenuSection[];
+  onClose: () => void;
+}) {
+  ensureMenuStyles();
+  const ref = useRef<HTMLDivElement | null>(null);
+  const [pos, setPos] = useState<{ x: number; y: number }>({
+    x: target.clientX,
+    y: target.clientY,
+  });
+  // Reposition if menu would overflow the viewport.
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    const r = el.getBoundingClientRect();
+    const vw = window.innerWidth;
+    const vh = window.innerHeight;
+    let nx = target.clientX;
+    let ny = target.clientY;
+    if (nx + r.width > vw - 8) nx = Math.max(8, vw - r.width - 8);
+    if (ny + r.height > vh - 8) ny = Math.max(8, vh - r.height - 8);
+    if (nx !== pos.x || ny !== pos.y) setPos({ x: nx, y: ny });
+    // Focus first menu item for keyboard nav.
+    const firstBtn = el.querySelector<HTMLButtonElement>('button.dc-menu-item:not([disabled])');
+    firstBtn?.focus();
+    // Dismiss on outside-click / Esc / scroll.
+    const onDocPointer = (e: PointerEvent) => {
+      if (!el.contains(e.target as Node)) onClose();
+    };
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        onClose();
+        return;
+      }
+      if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
+        e.preventDefault();
+        const items = Array.from(
+          el.querySelectorAll<HTMLButtonElement>('button.dc-menu-item:not([disabled])')
+        );
+        if (items.length === 0) return;
+        const idx = items.findIndex((b) => b === document.activeElement);
+        const nextIdx =
+          e.key === 'ArrowDown'
+            ? (idx + 1) % items.length
+            : (idx - 1 + items.length) % items.length;
+        items[nextIdx]?.focus();
+      }
+    };
+    const onScroll = () => onClose();
+    document.addEventListener('pointerdown', onDocPointer, true);
+    document.addEventListener('keydown', onKey, true);
+    document.addEventListener('scroll', onScroll, true);
+    window.addEventListener('blur', onClose);
+    return () => {
+      document.removeEventListener('pointerdown', onDocPointer, true);
+      document.removeEventListener('keydown', onKey, true);
+      document.removeEventListener('scroll', onScroll, true);
+      window.removeEventListener('blur', onClose);
+    };
+  }, [target.clientX, target.clientY, onClose, pos.x, pos.y]);
+  return (
+    <div ref={ref} className="dc-context-menu" role="menu" style={{ left: pos.x, top: pos.y }}>
+      {sections.map((section, si) => {
+        const sectionKey = section.map((i) => i.id).join('|') || `s${si}`;
+        return (
+          // biome-ignore lint/a11y/useSemanticElements: ARIA group within role="menu"; no native equivalent.
+          <div key={sectionKey} role="group">
+            {si > 0 ? <div className="dc-menu-sep" aria-hidden="true" /> : null}
+            {section.map((item) => (
+              <button
+                key={item.id}
+                type="button"
+                role="menuitem"
+                disabled={item.disabled}
+                className={`dc-menu-item${item.destructive ? ' is-destructive' : ''}`}
+                onClick={() => {
+                  if (item.disabled) return;
+                  item.onSelect(target);
+                  onClose();
+                }}
+              >
+                <span>{item.label}</span>
+                {item.shortcut ? <span className="dc-menu-shortcut">{item.shortcut}</span> : null}
+              </button>
+            ))}
+          </div>
+        );
+      })}
+    </div>
+  );
+}

package/plugins/design/dev-server/context.ts ADDED Viewed

@@ -0,0 +1,173 @@
+// Shared Context object passed to each module's factory.
+// Owns config + paths + a tiny pub-sub bus the modules use to talk without
+// importing each other. Stateless beyond that — per-conn data lives on Bun's
+// ws.data, per-request state on the Bun.serve context.
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+export type ConfigSource = '.design/config.json' | 'defaults' | 'defaults (config invalid)';
+export interface CanvasGroup {
+  label: string;
+  path: string;
+}
+export interface DesignSystemEntry {
+  name: string;
+  path: string;
+  description?: string;
+  tokensCssRel?: string;
+  rootClass?: string;
+  themeDefault?: 'dark' | 'light';
+  themes?: string[];
+  newCanvasDir?: string;
+  newComponentDir?: string;
+}
+export interface DevServerConfig {
+  name: string;
+  projectLabel: string | null;
+  designRoot: string;
+  canvasGroups: CanvasGroup[];
+  designSystems?: DesignSystemEntry[];
+  rootClass: string;
+  themeDefault: 'dark' | 'light';
+  tokensCssRel: string;
+  teamAccentDefault: string | null;
+  handoffTargets: unknown[];
+  newCanvasDir: string;
+  newComponentDir: string;
+  _source: ConfigSource;
+}
+const DEFAULT_CONFIG: Omit<DevServerConfig, '_source'> = {
+  name: 'Design',
+  projectLabel: null,
+  designRoot: '.design',
+  canvasGroups: [
+    { label: 'Design system', path: 'system' },
+    { label: 'Canvases', path: 'ui' },
+  ],
+  rootClass: 'app',
+  themeDefault: 'dark',
+  tokensCssRel: 'system/colors_and_type.css',
+  teamAccentDefault: null,
+  handoffTargets: [],
+  newCanvasDir: 'ui',
+  newComponentDir: 'ui/components',
+};
+export interface Paths {
+  repoRoot: string;
+  designRel: string;
+  designRoot: string;
+  serverInfoFile: string;
+  activeFile: string;
+  commentsDir: string;
+  canvasStateDir: string;
+  historyDir: string;
+  tokensUrlRel: string;
+  systemDirRel: string;
+}
+// Tiny pub-sub bus. Lazy — modules subscribe with on('selected', fn) and emit
+// the matching event. Avoids cycling imports between inspect.ts <-> ws.ts.
+export interface Bus {
+  // biome-ignore lint/suspicious/noExplicitAny: heterogeneous pubsub — subscribers annotate their own payload shape.
+  on(evt: string, fn: (payload: any) => void): () => void;
+  // biome-ignore lint/suspicious/noExplicitAny: heterogeneous pubsub — emitters supply their own payload shape.
+  emit(evt: string, payload?: any): void;
+}
+export function createBus(): Bus {
+  // biome-ignore lint/suspicious/noExplicitAny: subscribers are typed at the call site; the bus stores the erased type.
+  const subs = new Map<string, Set<(p: any) => void>>();
+  return {
+    on(evt, fn) {
+      const set = subs.get(evt) ?? new Set();
+      set.add(fn);
+      subs.set(evt, set);
+      return () => set.delete(fn);
+    },
+    emit(evt, payload) {
+      const set = subs.get(evt);
+      if (!set) return;
+      for (const fn of set) {
+        try {
+          fn(payload);
+        } catch (err) {
+          console.error(`[bus] subscriber for ${evt} threw:`, err);
+        }
+      }
+    },
+  };
+}
+export interface Context {
+  cfg: DevServerConfig;
+  projectLabel: string;
+  paths: Paths;
+  bus: Bus;
+}
+function resolveRepoRoot(): string {
+  const i = process.argv.indexOf('--root');
+  if (i !== -1 && process.argv[i + 1]) return path.resolve(process.argv[i + 1]);
+  if (process.env.CLAUDE_PROJECT_DIR) return path.resolve(process.env.CLAUDE_PROJECT_DIR);
+  return process.cwd();
+}
+function loadConfig(repoRoot: string): DevServerConfig {
+  const configPath = path.join(repoRoot, '.design', 'config.json');
+  let raw: string;
+  try {
+    raw = readFileSync(configPath, 'utf8');
+  } catch {
+    return { ...DEFAULT_CONFIG, _source: 'defaults' };
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return { ...DEFAULT_CONFIG, ...parsed, _source: '.design/config.json' };
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    console.error(`  warn: ${configPath} is not valid JSON: ${msg}. Using defaults.`);
+    return { ...DEFAULT_CONFIG, _source: 'defaults (config invalid)' };
+  }
+}
+export function createContext(): Context {
+  const repoRoot = resolveRepoRoot();
+  // Fail loud if launched from a directory that has no .design/ — preserves the
+  // load-bearing diagnostic from server.mjs: silent fallback to defaults masks
+  // "wrong project root" bugs.
+  if (!existsSync(path.join(repoRoot, '.design'))) {
+    console.error(`  error: no .design/ directory at ${repoRoot}`);
+    console.error('  Run from your project root, set $CLAUDE_PROJECT_DIR, or pass --root <path>.');
+    process.exit(1);
+  }
+  const cfg = loadConfig(repoRoot);
+  const designRel = cfg.designRoot.replace(/^\/+|\/+$/g, '');
+  const designRoot = path.join(repoRoot, designRel);
+  const systemDirRel = cfg.canvasGroups.find((g) => /system/i.test(g.path))?.path ?? 'system';
+  return {
+    cfg,
+    projectLabel: cfg.projectLabel || `${cfg.name} Design`,
+    paths: {
+      repoRoot,
+      designRel,
+      designRoot,
+      serverInfoFile: path.join(designRoot, '_server.json'),
+      activeFile: path.join(designRoot, '_active.json'),
+      commentsDir: path.join(designRoot, '_comments'),
+      canvasStateDir: path.join(designRoot, '_canvas-state'),
+      historyDir: path.join(designRoot, '_history'),
+      tokensUrlRel: path.posix.join(designRel, cfg.tokensCssRel.replace(/^\/+/, '')),
+      systemDirRel,
+    },
+    bus: createBus(),
+  };
+}