@1agh/maude 0.28.0 → 0.29.0

package/apps/studio/whats-new.json

@@ -0,0 +1,139 @@
+{
+  "$schema": "./whats-new.schema.json",
+  "entries": [
+    {
+      "id": "studio-full-functionality",
+      "version": "0.29.0",
+      "date": "2026-06-08",
+      "kind": "feature",
+      "title": "The studio is fully wired now",
+      "summary": "Everything in the chrome is live: the top bar shows the real zoom + artboard count, the status bar always shows hub-sync, and your avatar (plus Claude when it's editing) appears in the menubar. The ⌘K palette grew real Canvas/Tools commands (New canvas, Export, Handoff, Draw), there's a proper Export & handoff dialog (PNG/PDF/SVG/HTML/shadcn/ZIP) right in the shell, and a new display-only Inspector panel (Inspect · Layers · CSS) reads any element you ⌘-click.",
+      "surface": "design-ui",
+      "tour": [
+        {
+          "target": ".st-mb-right",
+          "title": "Live status, finally",
+          "body": "Zoom, artboard count, presence and hub-sync now reflect the real state — no more static placeholders."
+        },
+        {
+          "target": ".st-rpanel",
+          "title": "Inspector",
+          "body": "⌘-click an element in the canvas, then press I — pos, size, ancestry and markup, read-only (live CSS knobs land in Phase 12)."
+        }
+      ]
+    },
+    {
+      "id": "draw-animation-lottie",
+      "version": "0.29.0",
+      "date": "2026-06-08",
+      "kind": "feature",
+      "title": "Animate draw marks → ship one Lottie",
+      "summary": "/design:draw now handles motion briefs (morph, pulse, blink) and proves the animation is actually live. /design:to-lottie productionizes it into one Lottie that plays 1:1 on web and React Native.",
+      "surface": "design-ui"
+    },
+    {
+      "id": "studio-maude-ds-redesign",
+      "version": "0.29.0",
+      "date": "2026-06-08",
+      "kind": "feature",
+      "title": "The studio, redesigned in maude",
+      "summary": "The canvas browser chrome is now built in the maude design system itself — a dark-first studio shell with a branded menubar + real dropdowns, a collapsible file-tree sidebar with a rail, a cohesive bottom context bar, a maude-styled comments panel, and a clean light handoff. New: a ⌘K command palette for jumping to the design-system view, comments, theme, reload, and help. The in-canvas chrome (tools, minimap, selection halos) was re-skinned to the same indigo accent so the whole surface reads as one product.",
+      "surface": "design-ui",
+      "tour": [
+        {
+          "target": ".st-menubar .st-brand",
+          "title": "Built in maude",
+          "body": "The studio chrome now dogfoods the maude DS — one cohesive material across the menubar, sidebar, canvas and status bar."
+        },
+        {
+          "target": ".st-menubar .st-whatsnew",
+          "title": "Press ⌘K",
+          "body": "A new command palette jumps you to the design-system view, comments, theme toggle, reload, and help — no mouse needed."
+        }
+      ]
+    },
+    {
+      "id": "annotation-tooling-polish",
+      "version": "0.29.0",
+      "date": "2026-06-08",
+      "kind": "improvement",
+      "title": "Richer annotations — highlighter, lists & text shortcuts",
+      "summary": "Annotations got a full polish pass: a new highlighter tool (translucent marker with multiply blend), dashed strokes on shapes, FigJam-style sticky corner, multi-line text with Enter, italic/underline/lists, and Cmd+B/I/U formatting shortcuts that work the same way in sticky notes, shapes, and the text tool.",
+      "surface": "design-ui",
+      "tour": [
+        {
+          "target": ".dc-tool-palette button[aria-label^='Highlighter']",
+          "title": "New: Highlighter",
+          "body": "A translucent marker pen (I) — overlapping strokes darken with multiply blend. Pick hue and nib width from the chrome below."
+        }
+      ]
+    },
+    {
+      "id": "canvas-media-images-links",
+      "version": "0.29.0",
+      "date": "2026-06-08",
+      "kind": "feature",
+      "title": "Drop images & paste links onto the canvas",
+      "summary": "Drag a screenshot from your desktop — or paste a clipboard image or a URL — straight onto the canvas. Images sit alongside your annotations; links render as a tidy preview chip you can open in one click.",
+      "surface": "design-ui"
+    },
+    {
+      "id": "in-app-whats-new-tour",
+      "version": "0.29.0",
+      "date": "2026-06-08",
+      "kind": "feature",
+      "title": "What's New, right in the canvas browser",
+      "summary": "The Maude UI now tells you what shipped — a dismissible notice plus a panel you can reopen from the menubar. Each closed-out feature adds an entry automatically.",
+      "surface": "design-ui",
+      "tour": [
+        {
+          "target": "[data-tour='whatsnew']",
+          "title": "Your What's New badge",
+          "body": "This ✦ badge lights up when a new maude version ships features. Click it any time to reopen this panel."
+        },
+        {
+          "target": "[data-tour='help']",
+          "title": "Tours live in Help too",
+          "body": "Open Help to replay the full \"how Maude works\" walkthrough whenever you want."
+        }
+      ]
+    },
+    {
+      "id": "canvas-create-delete-from-browser",
+      "version": "0.28.1",
+      "date": "2026-06-03",
+      "kind": "feature",
+      "title": "Create & delete canvases from the browser",
+      "summary": "Spin up a blank brief-board straight from the file tree (+ board) and remove canvases without leaving the UI — no /design:new round-trip needed.",
+      "learnMore": "https://github.com/1aGh/maude#readme",
+      "surface": "design-ui"
+    },
+    {
+      "id": "canvas-activity-overlay",
+      "version": "0.28.0",
+      "date": "2026-06-02",
+      "kind": "feature",
+      "title": "Live canvas activity overlay",
+      "summary": "See at a glance which artboard Claude (or a teammate) is editing — a soft rim + badge highlights the active canvas and fades when work settles.",
+      "surface": "design-ui"
+    },
+    {
+      "id": "draw-as-code-svg-agent",
+      "version": "0.28.0",
+      "date": "2026-05-30",
+      "kind": "feature",
+      "title": "Draw production SVGs as code",
+      "summary": "/design:draw generates logos, icons, and diagrams through a deterministic geometry engine — no hand-guessed path data — and proofs them across the 16/24/48/256 verify ladder.",
+      "surface": "design-ui"
+    },
+    {
+      "id": "self-hostable-hub-sync",
+      "version": "0.27.0",
+      "date": "2026-05-28",
+      "kind": "feature",
+      "title": "Self-hostable hub + live file sync",
+      "summary": "Run your own Maude hub and co-edit canvases with bidirectional file sync, offline-aware status, and conflict handling.",
+      "surface": "design-ui"
+    }
+  ]
+}

package/apps/studio/whats-new.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/1aGh/maude/main/apps/studio/whats-new.schema.json",
+  "title": "Maude What's New feed",
+  "description": "User-facing product-update entries surfaced in the Maude UI (and mirrored to the docs site). Single source of truth — ships with the dev-server, appended on /flow:done, stamped at release. See .ai/plans/feature-in-app-whats-new-tour.md (DDR-A).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["entries"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "entries": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/entry" }
+    }
+  },
+  "$defs": {
+    "entry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "kind", "title", "summary"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Stable slug (usually the plan slug). Used for de-dup and as the React key.",
+          "pattern": "^[a-z0-9][a-z0-9-]*$"
+        },
+        "version": {
+          "type": ["string", "null"],
+          "description": "Semver the feature shipped in, or null while pending (stamped at release).",
+          "pattern": "^\\d+\\.\\d+\\.\\d+"
+        },
+        "date": {
+          "type": ["string", "null"],
+          "description": "Release date YYYY-MM-DD, or null while pending."
+        },
+        "kind": { "enum": ["feature", "improvement", "usage", "fix"] },
+        "title": { "type": "string", "minLength": 1 },
+        "summary": { "type": "string", "minLength": 1 },
+        "learnMore": {
+          "type": "string",
+          "description": "Optional URL to docs / release notes. Constrained to http(s) — the feed renders this as an <a href>, so a javascript:/data: scheme is rejected at the data-contract layer (defense-in-depth alongside React's URL sanitizer).",
+          "pattern": "^https?://"
+        },
+        "surface": {
+          "type": "string",
+          "description": "Which UI surface this targets (e.g. design-ui). Future-proofing."
+        },
+        "tour": {
+          "type": "array",
+          "description": "Optional spotlight steps that highlight the new UI (consumed by the tour engine — Phase 3).",
+          "items": { "$ref": "#/$defs/tourStep" }
+        }
+      }
+    },
+    "tourStep": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["target", "title", "body"],
+      "properties": {
+        "target": {
+          "type": "string",
+          "description": "CSS selector or [data-tour=\"<key>\"] anchor to spotlight."
+        },
+        "title": { "type": "string", "minLength": 1 },
+        "body": { "type": "string", "minLength": 1 },
+        "placement": { "enum": ["top", "bottom", "left", "right", "auto"] }
+      }
+    }
+  }
+}

package/apps/studio/whats-new.ts

@@ -0,0 +1,87 @@
+// whats-new.ts — server-side loader for the Maude "What's New" feed.
+//
+// Single source of truth: `<DEV_SERVER_ROOT>/whats-new.json` (DDR-A). The feed
+// describes **Maude's own product** updates — it is resolved from the maude
+// package root (via paths.ts, NOT cwd), so the dev-server surfaces the same
+// product news whether it runs in this repo or a downstream user's project.
+//
+// Disk paths MUST come from paths.ts (DDR-045) — never
+// `dirname(fileURLToPath(import.meta.url))`, which is the virtual `/$bunfs/root`
+// inside a `bun --compile` standalone binary.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DEV_SERVER_ROOT } from './paths.ts';
+
+export type WhatsNewKind = 'feature' | 'improvement' | 'usage' | 'fix';
+
+export interface WhatsNewTourStep {
+  target: string;
+  title: string;
+  body: string;
+  placement?: 'top' | 'bottom' | 'left' | 'right' | 'auto';
+}
+
+export interface WhatsNewEntry {
+  id: string;
+  version: string | null;
+  date: string | null;
+  kind: WhatsNewKind;
+  title: string;
+  summary: string;
+  learnMore?: string;
+  surface?: string;
+  tour?: WhatsNewTourStep[];
+}
+
+export interface WhatsNewFeed {
+  /** The installed maude version (key the client compares "seen" against). */
+  version: string;
+  entries: WhatsNewEntry[];
+}
+
+let cache: WhatsNewFeed | null = null;
+
+/**
+ * Read the installed maude version from the design plugin manifest.
+ * `apps/studio/` → `plugins/design/.claude-plugin/plugin.json`.
+ * That manifest ships in BOTH npm installs and marketplace-cache clones
+ * (same rationale as build.ts `readPluginVersion`). Falls back to `dev`.
+ */
+export function resolveMaudeVersion(root: string = DEV_SERVER_ROOT): string {
+  const manifest = join(root, '..', '..', 'plugins', 'design', '.claude-plugin', 'plugin.json');
+  try {
+    const parsed = JSON.parse(readFileSync(manifest, 'utf8')) as { version?: unknown };
+    if (typeof parsed.version === 'string') return parsed.version;
+  } catch {
+    /* fall through */
+  }
+  return 'dev';
+}
+
+/**
+ * Load `<root>/whats-new.json`. Fails soft to an empty entry list — a missing
+ * or malformed feed must never 500 the dev-server (it's a non-critical chrome
+ * surface). Caches the default-root result; pass `{ root }` for an uncached
+ * read (tests) and `{ fresh: true }` to bypass the cache.
+ */
+export function loadWhatsNew(opts: { root?: string; fresh?: boolean } = {}): WhatsNewFeed {
+  const usingDefaultRoot = opts.root === undefined;
+  if (cache && usingDefaultRoot && !opts.fresh) return cache;
+
+  const root = opts.root ?? DEV_SERVER_ROOT;
+  const file = join(root, 'whats-new.json');
+  let entries: WhatsNewEntry[] = [];
+  try {
+    if (existsSync(file)) {
+      const parsed = JSON.parse(readFileSync(file, 'utf8')) as { entries?: unknown };
+      if (Array.isArray(parsed.entries)) entries = parsed.entries as WhatsNewEntry[];
+    }
+  } catch {
+    /* malformed feed → empty, never throw */
+  }
+
+  const feed: WhatsNewFeed = { version: resolveMaudeVersion(root), entries };
+  if (usingDefaultRoot) cache = feed;
+  return feed;
+}

package/cli/bin/maude.mjs

@@ -50,6 +50,16 @@ async function main(argv) {
     return run({ args: [], pkgRoot: PKG_ROOT });
   }
 
+  // `maude studio [...]` — top-level alias for `maude design serve` (DDR-095:
+  // the verb now matches the apps/studio home). Checked BEFORE the COMMANDS map
+  // so it never falls through to the unknown-command branch; it is deliberately
+  // NOT a COMMANDS entry (that would dispatch design.run with positional[0]
+  // wrong). `maude design serve` keeps working unchanged.
+  if (cmd === 'studio') {
+    const { run } = await COMMANDS.design();
+    return run({ args: ['serve', ...args.slice(1)], pkgRoot: PKG_ROOT });
+  }
+
   const loader = COMMANDS[cmd];
   if (!loader) {
     process.stderr.write(

package/cli/commands/design.mjs

@@ -1,6 +1,6 @@
 import { execSync, spawn, spawnSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
+import { chmodSync, existsSync, readFileSync } from 'node:fs';
+import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { basename, dirname, join, resolve } from 'node:path';
 import { parseArgs } from '../lib/argv.mjs';
@@ -40,8 +40,15 @@ const BIN_VERBS = new Set([
   'draw-build',
   'draw-proof',
   'svg-optimize',
+  'to-lottie',
+  'read-annotations',
 ]);
 
+// Bin verbs that boot the dev-server (directly, or by shelling into server-up.sh).
+// For these we resolve the compiled platform binary and hand its path to the
+// helper via MAUDE_DEV_SERVER_BIN — see runBinDispatch + DDR-084.
+const BOOT_VERBS = new Set(['server-up', 'visual-sanity', 'smoke']);
+
 export async function run({ args, pkgRoot }) {
   const { positional } = parseArgs(args);
   const sub = positional[0];
@@ -81,18 +88,35 @@ function runBinDispatch(verb, { args, pkgRoot }) {
     process.stderr.write(`maude design: "${verb}" is not a dev-tooling verb.\n${usage()}`);
     process.exit(2);
   }
+  // CLAUDE_PLUGIN_ROOT stays the design *plugin* dir (plugins/design) — that's
+  // its true meaning, and it remains 2 levels under pkgRoot so the helpers'
+  // `$PLUGIN_ROOT/../../cli` side-channel + `$PLUGIN_ROOT/../..` pkg-root math
+  // still resolve. The bin scripts themselves now live under apps/studio/bin
+  // (DDR-095) and resolve the dev-server tree via $SCRIPT_DIR/.. regardless.
   const pluginRoot = join(pkgRoot, 'plugins', 'design');
-  const script = join(pluginRoot, 'dev-server', 'bin', `${verb}.sh`);
+  const script = join(pkgRoot, 'apps', 'studio', 'bin', `${verb}.sh`);
   if (!existsSync(script)) {
     process.stderr.write(
-      `maude design ${verb}: helper not found at ${script}. Reinstall maude (the dev-server bin ships in the npm package).\n`
+      `maude design ${verb}: helper not found at ${script}. Reinstall maude (the studio bin ships in the npm package).\n`
     );
     process.exit(1);
   }
   const rest = args.slice(args.indexOf(verb) + 1); // everything after the verb token
+  const childEnv = { ...process.env, CLAUDE_PLUGIN_ROOT: pluginRoot };
+  // For verbs that boot the dev-server, resolve the compiled platform binary the
+  // SAME way `maude design serve` does and hand the path down. The binary embeds
+  // yjs + every runtime dep; `bun server.ts` from source does NOT (the deps live
+  // in a nested package.json the npm tarball excludes), so on a production install
+  // server.ts crashes at boot on `yjs`. server-up.sh prefers MAUDE_DEV_SERVER_BIN
+  // when set; absent ⇒ dev tree ⇒ it falls back to `bun server.ts`. Helpers that
+  // shell into server-up.sh (visual-sanity, smoke) inherit it. DDR-084.
+  if (BOOT_VERBS.has(verb) && !process.env.MAUDE_DEV_SERVER_BIN) {
+    const bin = resolveServerBinary({ pkgRoot });
+    if (bin) childEnv.MAUDE_DEV_SERVER_BIN = bin;
+  }
   const child = spawnSync('bash', [script, ...rest], {
     stdio: 'inherit',
-    env: { ...process.env, CLAUDE_PLUGIN_ROOT: pluginRoot },
+    env: childEnv,
   });
   if (child.error) {
     process.stderr.write(`maude design ${verb}: ${child.error.message}\n`);
@@ -110,7 +134,7 @@ Lifecycle:
 Dev-tooling (dispatch to the dev-server bash helpers — DDR-062):
   screenshot · server-up · prep · slug · bootstrap-check · runtime-health
   smoke · canvas-edit · handoff · asset-sweep · visual-sanity
-  draw-build · draw-proof · svg-optimize
+  draw-build · draw-proof · svg-optimize · to-lottie · read-annotations
         Invoke the bundled helper of the same name. maude resolves it from its
         own package root and sets CLAUDE_PLUGIN_ROOT for the child; stdout,
         stderr, and exit code pass straight through (so command-substitution
@@ -123,7 +147,8 @@ Dev-tooling (dispatch to the dev-server bash helpers — DDR-062):
 
   serve [--port N] [--root PATH]
         Start the design plugin's dev server in the current repo. Equivalent
-        to invoking 'claude-design-server'. Forwards all remaining args.
+        to 'maude studio' (top-level alias) or invoking 'claude-design-server'.
+        Forwards all remaining args.
 
   init  [--name <slug>] [--ds <name>] [--force] [--dry-run]
         [--no-discovery | --discovery-payload <path>]
@@ -242,8 +267,8 @@ async function runServe({ args, pkgRoot }) {
     process.exit(1);
   }
 
-  const tsEntry = resolve(pkgRoot, 'plugins', 'design', 'dev-server', 'server.ts');
-  const mjsEntry = resolve(pkgRoot, 'plugins', 'design', 'dev-server', 'server.mjs');
+  const tsEntry = resolve(pkgRoot, 'apps', 'studio', 'server.ts');
+  const mjsEntry = resolve(pkgRoot, 'apps', 'studio', 'server.mjs');
 
   const hasBun = await new Promise((res) => {
     const probe = spawn('bun', ['--version'], { stdio: 'ignore' });
@@ -295,6 +320,55 @@ function detectPlatformSlug() {
   return null;
 }
 
+// Read-only resolution of the compiled platform binary the dev-server should
+// boot as in a production install (it embeds yjs + every runtime dep). Mirrors
+// runServe's order — side-channel cache (postinstall) → lazy resolve of the
+// @1agh/maude-<slug> sibling/nested package — but performs NO caching and NEVER
+// hard-fails: returns the path, or null when none is found. A null result means
+// "fall back to `bun server.ts` from source" (correct in the local dev tree).
+// Honors MAUDE_FORCE_SOURCE=1 so maintainers hacking on the dev-server source
+// still boot their working copy. Used by runBinDispatch to hand the path to
+// server-up.sh; runServe keeps its own inline copy (it also caches + hard-fails).
+// Structural allowlist for a path we're about to spawn (DDR-084 hardening). The
+// compiled binary is ALWAYS named `maude` / `maude.exe` inside a `maude-<slug>/`
+// dir (the @1agh/maude-<slug> package, or the dev-tree `packages/maude-<slug>/`).
+// The side-channel file's content is the one attacker-influenceable input in a
+// shared-prefix / poisoned-clone layout — a path outside this shape is ignored
+// (caller falls back to source), so the file can only DENY the binary, never
+// redirect the spawn to an arbitrary executable. Paths `lazyResolveBinary`
+// constructs always conform, so this never rejects a legit resolve.
+export function isPlausiblePlatformBinary(p) {
+  if (!p) return false;
+  const b = basename(p);
+  if (b !== 'maude' && b !== 'maude.exe') return false;
+  return /^maude-[a-z0-9-]+$/.test(basename(dirname(p)));
+}
+
+export function resolveServerBinary({ pkgRoot }) {
+  if (process.env.MAUDE_FORCE_SOURCE === '1') return null;
+  // In the local source checkout, return null so server-up.sh boots
+  // `bun server.ts` from source — the maintainer is editing the dev-server and
+  // needs their working copy live, not a stale compiled binary that happens to
+  // be installed via pnpm. A production install has no `packages/` dir, so this
+  // never short-circuits there. (Preserves server-up's historic dev-tree
+  // behavior — it always ran source before DDR-084.)
+  if (isLocalDevTree(pkgRoot, { existsSync })) return null;
+  const sideChannel = resolve(pkgRoot, 'cli', '.platform-binary-path');
+  try {
+    if (existsSync(sideChannel)) {
+      const candidate = readFileSync(sideChannel, 'utf8').trim();
+      // Existence AND the structural allowlist — a poisoned side-channel pointing
+      // at an arbitrary executable is ignored (falls through to lazy resolve).
+      if (candidate && existsSync(candidate) && isPlausiblePlatformBinary(candidate)) {
+        return candidate;
+      }
+    }
+  } catch {
+    /* fall through to lazy resolve */
+  }
+  return lazyResolveBinary({ pkgRoot, fs: { existsSync, chmodSync } }).binPath;
+}
+
 function lazyResolveBinary({ pkgRoot, fs }) {
   const slug = detectPlatformSlug();
   if (!slug) return { binPath: null, slug: null };
@@ -348,7 +422,7 @@ function checkDevDeps({ pkgRoot }) {
   // with a less actionable error.
   const required = ['magic-string', 'oxc-parser'];
   const missing = [];
-  const paths = [resolve(pkgRoot, 'plugins', 'design', 'dev-server'), resolve(pkgRoot)];
+  const paths = [resolve(pkgRoot, 'apps', 'studio'), resolve(pkgRoot)];
   for (const dep of required) {
     try {
       require.resolve(dep, { paths });

package/cli/commands/design.test.mjs

@@ -8,11 +8,12 @@
 
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
-import { mkdtempSync, rmSync } from 'node:fs';
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { test } from 'node:test';
 import { fileURLToPath } from 'node:url';
+import { isPlausiblePlatformBinary, resolveServerBinary } from './design.mjs';
 
 const BIN = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'maude.mjs');
 
@@ -54,3 +55,134 @@ test('design help lists the dev-tooling verbs', () => {
     assert.match(res.stdout, new RegExp(verb), `usage should mention ${verb}`);
   }
 });
+
+// resolveServerBinary — the dev-server boot-runtime resolver (DDR-084). server-up
+// must boot the compiled platform binary on a production install (it embeds yjs +
+// every dep; `bun server.ts` from source can't resolve them — the historic
+// yjs-at-boot crash), but keep using SOURCE in the local dev tree so a maintainer's
+// edits are live.
+function fakePkgRoot({ devTree = false, sideChannelBin = null } = {}) {
+  const root = mkdtempSync(join(tmpdir(), 'maude-pkgroot-'));
+  if (devTree) {
+    mkdirSync(join(root, 'packages', 'maude-darwin-arm64'), { recursive: true });
+    writeFileSync(join(root, 'packages', 'maude-darwin-arm64', 'package.json'), '{}');
+  }
+  if (sideChannelBin) {
+    mkdirSync(join(root, 'cli'), { recursive: true });
+    writeFileSync(join(root, 'cli', '.platform-binary-path'), sideChannelBin);
+  }
+  return root;
+}
+
+test('resolveServerBinary → null in the local dev tree (packages/ present) — boots source', () => {
+  const root = fakePkgRoot({ devTree: true });
+  try {
+    delete process.env.MAUDE_FORCE_SOURCE;
+    assert.equal(resolveServerBinary({ pkgRoot: root }), null);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+// Build an executable in a layout the allowlist accepts (`maude-<slug>/maude`)
+// or rejects (anything else), under a throwaway dir.
+function fakeBinary({ conforming = true } = {}) {
+  const home = mkdtempSync(join(tmpdir(), 'maude-bin-'));
+  const dir = join(home, conforming ? 'maude-darwin-arm64' : 'evil');
+  mkdirSync(dir, { recursive: true });
+  const bin = join(dir, 'maude');
+  writeFileSync(bin, '#!/bin/sh\n');
+  chmodSync(bin, 0o755);
+  return { home, bin };
+}
+
+test('resolveServerBinary → null when MAUDE_FORCE_SOURCE=1 (maintainer override)', () => {
+  const { home, bin } = fakeBinary();
+  const root = fakePkgRoot({ sideChannelBin: bin }); // NOT a dev tree
+  const prev = process.env.MAUDE_FORCE_SOURCE;
+  try {
+    process.env.MAUDE_FORCE_SOURCE = '1';
+    assert.equal(resolveServerBinary({ pkgRoot: root }), null);
+  } finally {
+    if (prev === undefined) delete process.env.MAUDE_FORCE_SOURCE;
+    else process.env.MAUDE_FORCE_SOURCE = prev;
+    rmSync(root, { recursive: true, force: true });
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('resolveServerBinary → side-channel path on a production install (no packages/)', () => {
+  const { home, bin } = fakeBinary(); // conforming maude-<slug>/maude layout
+  const root = fakePkgRoot({ sideChannelBin: bin }); // production shape
+  const prev = process.env.MAUDE_FORCE_SOURCE;
+  try {
+    delete process.env.MAUDE_FORCE_SOURCE;
+    assert.equal(resolveServerBinary({ pkgRoot: root }), bin);
+  } finally {
+    if (prev !== undefined) process.env.MAUDE_FORCE_SOURCE = prev;
+    rmSync(root, { recursive: true, force: true });
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('resolveServerBinary → REJECTS a side-channel pointing outside the maude-<slug>/ layout (DDR-084 allowlist)', () => {
+  const { home, bin } = fakeBinary({ conforming: false }); // <tmp>/evil/maude
+  const root = fakePkgRoot({ sideChannelBin: bin }); // production shape, no real platform pkg
+  const prev = process.env.MAUDE_FORCE_SOURCE;
+  try {
+    delete process.env.MAUDE_FORCE_SOURCE;
+    // Poisoned side-channel is ignored → falls through to lazyResolve, which finds
+    // nothing in the fake root → null (server-up then boots source, not the planted bin).
+    assert.equal(resolveServerBinary({ pkgRoot: root }), null);
+  } finally {
+    if (prev !== undefined) process.env.MAUDE_FORCE_SOURCE = prev;
+    rmSync(root, { recursive: true, force: true });
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('isPlausiblePlatformBinary — accepts maude-<slug>/maude, rejects everything else', () => {
+  assert.equal(isPlausiblePlatformBinary('/x/node_modules/@1agh/maude-darwin-arm64/maude'), true);
+  assert.equal(isPlausiblePlatformBinary('/x/packages/maude-linux-x64-musl/maude'), true);
+  assert.equal(isPlausiblePlatformBinary('/x/maude-win32-x64/maude.exe'), true);
+  assert.equal(isPlausiblePlatformBinary('/tmp/evil/maude'), false); // parent not maude-<slug>
+  assert.equal(isPlausiblePlatformBinary('/x/maude-darwin-arm64/evil'), false); // basename not maude
+  assert.equal(isPlausiblePlatformBinary(''), false);
+  assert.equal(isPlausiblePlatformBinary(null), false);
+});
+
+// DDR-095 — `maude studio` is a top-level alias for `maude design serve`. Both
+// must resolve the same server-entry path. We prove parity by booting each
+// against a temp dir with no .design/: the dev-server fails loud (exit 1) with
+// an identical first-line signature, which only happens if `studio` routed
+// through design-serve resolution (`apps/studio/server.{ts,mjs}` / the binary).
+test('`maude studio` aliases `maude design serve` (identical boot resolution)', () => {
+  const BIN_PATH = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'maude.mjs');
+  function bootAgainstEmpty(argv) {
+    const cwd = mkdtempSync(join(tmpdir(), 'maude-studio-'));
+    try {
+      const r = spawnSync(process.execPath, [BIN_PATH, ...argv, '--root', cwd], {
+        encoding: 'utf8',
+        timeout: 30000,
+      });
+      return { status: r.status, firstErr: (r.stderr || '').split('\n').find(Boolean) ?? '' };
+    } finally {
+      rmSync(cwd, { recursive: true, force: true });
+    }
+  }
+  const viaDesign = bootAgainstEmpty(['design', 'serve']);
+  const viaStudio = bootAgainstEmpty(['studio']);
+  // Both fail loud (no .design/) — same exit code, same first-line diagnostic.
+  assert.notEqual(viaStudio.status, 0, `studio should not boot cleanly: ${viaStudio.firstErr}`);
+  assert.equal(viaStudio.status, viaDesign.status);
+  assert.equal(viaStudio.firstErr, viaDesign.firstErr);
+});
+
+test('`maude studio` is recognized (not an unknown command)', () => {
+  const BIN_PATH = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'maude.mjs');
+  const r = spawnSync(process.execPath, [BIN_PATH, 'studio', '--root', '/nonexistent-xyz'], {
+    encoding: 'utf8',
+    timeout: 30000,
+  });
+  assert.doesNotMatch(r.stderr || '', /unknown command/);
+});

package/cli/commands/help.mjs

@@ -29,9 +29,14 @@ COMMANDS
         contract — see DDR-061); 'list' shows layers + sizes; 'stats' shows
         hit-rate; 'inspect' pretty-prints entries; 'clear' wipes a layer or all.
 
+  studio [--port N] [--root PATH]
+        Alias for 'maude design serve' — boot the canvas studio (the design
+        dev server) in the current repo. Forwards all remaining args.
+
   design serve [--port N] [--root PATH]
         Start the design plugin's dev server in the current repo. Equivalent
-        to invoking 'claude-design-server'. Forwards all remaining args.
+        to 'maude studio' / invoking 'claude-design-server'. Forwards all
+        remaining args.
 
   design init [--name <slug>] [--ds <name>] [--force] [--dry-run]
               [--no-discovery | --discovery-payload <path>]
@@ -43,7 +48,7 @@ COMMANDS
 
   design <screenshot|server-up|prep|slug|bootstrap-check|runtime-health
           |smoke|canvas-edit|handoff|asset-sweep|visual-sanity> [args]
-        Dispatch to the dev-server's bundled bash helper of the same name.
+        Dispatch to the studio's bundled bash helper of the same name.
         maude resolves it from its own package root and sets CLAUDE_PLUGIN_ROOT
         for the child; stdout/stderr/exit-code pass straight through. This is
         the contract plugin markdown uses instead of a raw bin path (DDR-062).
@@ -88,6 +93,7 @@ EXAMPLES
   maude config get motion.complex
   maude cache list
   maude cache clear research/domain
+  maude studio --port 4399
   maude design serve --port 4399
   maude design init --no-discovery --name acme-app
   maude design slug "Some Canvas Name"