@mandujs/core 0.48.0 → 0.50.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.48.0",
+  "version": "0.50.0",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/deploy/index.ts

@@ -57,6 +57,15 @@ export {
   type BrainInferenceOptions,
 } from "./inference/brain";
 
+export {
+  extractExplicitIntents,
+  mergeExplicitIntents,
+  type ExplicitIntentEntry,
+  type ExplicitIntentError,
+  type ExtractExplicitIntentsOptions,
+  type ExtractExplicitIntentsResult,
+} from "./inference/filling-extract";
+
 export {
   planDeploy,
   planHasChanges,

package/src/deploy/inference/filling-extract.ts

@@ -0,0 +1,245 @@
+/**
+ * Build-time extractor for `.deploy()` intents on `Mandu.filling()`
+ * route modules.
+ *
+ * Issue #250 M5. Bridges the runtime DSL (filling.deploy) and the
+ * build-time cache (`.mandu/deploy.intent.json`):
+ *
+ *   1. For every route in the manifest, dynamically `import()` the
+ *      module file.
+ *   2. If the default export looks like a `ManduFilling` instance and
+ *      its `getDeployIntent()` returns a non-null value, capture it
+ *      as a Zod-validated `DeployIntent`.
+ *   3. The CLI / MCP merges captured entries into the previous cache
+ *      with `source: "explicit"` BEFORE calling `planDeploy()` —
+ *      explicit entries are protected from inference (M1) so the
+ *      user's `.deploy()` always wins.
+ *
+ * Failure modes (non-fatal — extractor returns the offending route in
+ * `errors[]`, planner falls back to inference for it):
+ *
+ *   - Module file cannot be imported (syntax error, missing dep).
+ *   - Default export is not a filling instance.
+ *   - `.deploy({...})` payload fails Zod validation (this throws at
+ *     module load, so the import error path catches it).
+ *
+ * The extractor uses dynamic import rather than AST parsing because
+ * the manifest is built by importing routes anyway (for static
+ * params, slot metadata, etc.) — adding another loader would
+ * duplicate work. Side effects in route modules ARE a concern, but
+ * Mandu's convention is to put side effects in `loader()` / `get()`
+ * callbacks (which the extractor never invokes).
+ */
+
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { promises as fs } from "node:fs";
+import { DeployIntent, type DeployIntent as DeployIntentType } from "../intent";
+import type { RoutesManifest, RouteSpec } from "../../spec/schema";
+
+export interface ExplicitIntentEntry {
+  routeId: string;
+  pattern: string;
+  /** Fully-validated, defaults-applied intent. */
+  intent: DeployIntentType;
+}
+
+export interface ExplicitIntentError {
+  routeId: string;
+  pattern: string;
+  module: string;
+  reason: string;
+}
+
+export interface ExtractExplicitIntentsResult {
+  entries: ExplicitIntentEntry[];
+  errors: ExplicitIntentError[];
+}
+
+export interface ExtractExplicitIntentsOptions {
+  /**
+   * Override the dynamic import for tests. Receives the absolute file
+   * URL the extractor would have imported and returns whatever module
+   * shape the test wants to inject.
+   */
+  importer?: (fileUrl: string) => Promise<unknown>;
+  /**
+   * Skip routes whose modules don't exist on disk. Default `true` —
+   * a missing route is a manifest staleness issue, not an extractor
+   * concern.
+   */
+  skipMissing?: boolean;
+}
+
+/**
+ * Walk the manifest, import each route, and capture explicit deploy
+ * intents from `Mandu.filling().deploy({...})` declarations.
+ */
+export async function extractExplicitIntents(
+  rootDir: string,
+  manifest: RoutesManifest,
+  options: ExtractExplicitIntentsOptions = {},
+): Promise<ExtractExplicitIntentsResult> {
+  const importer = options.importer ?? defaultImporter;
+  const skipMissing = options.skipMissing ?? true;
+  const entries: ExplicitIntentEntry[] = [];
+  const errors: ExplicitIntentError[] = [];
+
+  for (const route of manifest.routes) {
+    const modulePath = path.resolve(rootDir, route.module);
+    if (skipMissing) {
+      const exists = await pathExists(modulePath);
+      if (!exists) continue;
+    }
+
+    let mod: unknown;
+    try {
+      const url = pathToFileURL(modulePath).href;
+      mod = await importer(url);
+    } catch (err) {
+      errors.push({
+        routeId: route.id,
+        pattern: route.pattern,
+        module: route.module,
+        reason: `import failed: ${err instanceof Error ? err.message : String(err)}`,
+      });
+      continue;
+    }
+
+    const filling = pickDefaultFilling(mod);
+    if (!filling) continue;
+
+    let raw: unknown;
+    try {
+      raw = filling.getDeployIntent();
+    } catch (err) {
+      errors.push({
+        routeId: route.id,
+        pattern: route.pattern,
+        module: route.module,
+        reason: `getDeployIntent threw: ${err instanceof Error ? err.message : String(err)}`,
+      });
+      continue;
+    }
+
+    if (raw === undefined || raw === null) continue;
+
+    // Validate + apply schema defaults so downstream code (cache,
+    // adapters) never sees half-typed shapes.
+    const parsed = DeployIntent.safeParse(raw);
+    if (!parsed.success) {
+      errors.push({
+        routeId: route.id,
+        pattern: route.pattern,
+        module: route.module,
+        reason: `.deploy() validation failed: ${parsed.error.errors.map((e) => e.message).join("; ")}`,
+      });
+      continue;
+    }
+
+    entries.push({
+      routeId: route.id,
+      pattern: route.pattern,
+      intent: parsed.data,
+    });
+  }
+
+  return { entries, errors };
+}
+
+// ─── Internals ────────────────────────────────────────────────────────
+
+/**
+ * Loose duck-type check for ManduFilling. We can't `instanceof`
+ * because the imported module's `ManduFilling` constructor may not be
+ * the one this package was bundled with (workspace symlinks, package
+ * upgrades, etc.). Instead, we look for the public `getDeployIntent`
+ * method that ships in the same release as `.deploy()` — versions
+ * without the M5 method silently no-op (no entry captured).
+ */
+type FillingLike = { getDeployIntent: () => unknown };
+
+function isFillingLike(value: unknown): value is FillingLike {
+  return (
+    value != null &&
+    typeof value === "object" &&
+    "getDeployIntent" in value &&
+    typeof (value as { getDeployIntent: unknown }).getDeployIntent === "function"
+  );
+}
+
+function pickDefaultFilling(mod: unknown): FillingLike | null {
+  if (!mod || typeof mod !== "object") return null;
+  const candidate = (mod as { default?: unknown }).default;
+  return isFillingLike(candidate) ? candidate : null;
+}
+
+async function defaultImporter(fileUrl: string): Promise<unknown> {
+  return await import(fileUrl);
+}
+
+async function pathExists(p: string): Promise<boolean> {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ─── Cache merge helper ───────────────────────────────────────────────
+
+import type { DeployIntentCache, DeployIntentCacheEntry } from "../cache";
+import { hashSource } from "./context";
+
+/**
+ * Merge extractor entries into a cache, marking each one as
+ * `source: "explicit"`. Existing entries with the same route id are
+ * overwritten — the user's `.deploy()` always wins.
+ *
+ * `sourceHash` is set from the file's current bytes so the planner
+ * can detect drift between the cached intent and the live source.
+ * The cache's `generatedAt` and `brainModel` are left untouched so
+ * the merge step doesn't pretend to be a re-plan.
+ */
+export async function mergeExplicitIntents(
+  cache: DeployIntentCache,
+  entries: ReadonlyArray<ExplicitIntentEntry>,
+  rootDir: string,
+  manifest: RoutesManifest,
+): Promise<DeployIntentCache> {
+  if (entries.length === 0) return cache;
+  const next: DeployIntentCache = {
+    ...cache,
+    intents: { ...cache.intents },
+  };
+  const routeById = new Map<string, RouteSpec>(
+    manifest.routes.map((r) => [r.id, r]),
+  );
+
+  for (const entry of entries) {
+    const route = routeById.get(entry.routeId);
+    if (!route) continue;
+    const modulePath = path.resolve(rootDir, route.module);
+    let source = "";
+    try {
+      source = await fs.readFile(modulePath, "utf8");
+    } catch {
+      // Route file vanished between extraction and merge — keep
+      // going with an empty hash; the planner will catch the
+      // missing-source case on its own.
+    }
+    const cacheEntry: DeployIntentCacheEntry = {
+      intent: entry.intent,
+      source: "explicit",
+      rationale:
+        cache.intents[entry.routeId]?.source === "explicit"
+          ? cache.intents[entry.routeId]?.rationale ?? "explicit .deploy() override"
+          : "explicit .deploy() override",
+      sourceHash: hashSource(source),
+    };
+    next.intents[entry.routeId] = cacheEntry;
+  }
+
+  return next;
+}

package/src/design/__tests__/tailwind-theme.test.ts

@@ -0,0 +1,229 @@
+/**
+ * Issue #245 M3 — Tailwind v4 `@theme` compiler tests.
+ *
+ * Pin the contract every other tool (CLI sync, MCP discovery,
+ * dev-mode watcher) depends on:
+ *
+ *   - DESIGN.md tokens → CSS variable naming (Tailwind v4 convention).
+ *   - Slug normalisation handles the human-friendly names DESIGN.md
+ *     authors actually write.
+ *   - Markered region merge preserves user-edited regions.
+ *   - Conflicts surface explicitly so the user can reconcile.
+ */
+
+import { describe, it, expect } from "bun:test";
+import { parseDesignMd } from "../parser";
+import {
+  compileTailwindTheme,
+  mergeThemeIntoCss,
+  slugifyTokenName,
+  stripMarkeredBlock,
+  THEME_MARKER_END,
+  THEME_MARKER_START,
+} from "../tailwind-theme";
+
+describe("slugifyTokenName", () => {
+  it("kebab-cases multi-word names", () => {
+    expect(slugifyTokenName("Hot Peach")).toBe("hot-peach");
+    expect(slugifyTokenName("Body Small")).toBe("body-small");
+    expect(slugifyTokenName("h1 hero")).toBe("h1-hero");
+  });
+
+  it("collapses runs of whitespace and underscores", () => {
+    expect(slugifyTokenName("primary  color")).toBe("primary-color");
+    expect(slugifyTokenName("warm_cream")).toBe("warm-cream");
+  });
+
+  it("strips characters that aren't word/space/dash", () => {
+    expect(slugifyTokenName("primary!")).toBe("primary");
+    expect(slugifyTokenName("orange (500)")).toBe("orange-500");
+  });
+
+  it("lowercases ASCII", () => {
+    expect(slugifyTokenName("Primary")).toBe("primary");
+  });
+});
+
+describe("compileTailwindTheme — color palette", () => {
+  it("emits --color-<slug> per token", () => {
+    const spec = parseDesignMd(`# Test
+## Color Palette
+- Primary — #FF8C42 — brand accent
+- Surface — #FFF8F0 — neutral background
+`);
+    const compiled = compileTailwindTheme(spec);
+    const vars = compiled.entries.map((e) => [e.variable, e.value]);
+    expect(vars).toContainEqual(["--color-primary", "#FF8C42"]);
+    expect(vars).toContainEqual(["--color-surface", "#FFF8F0"]);
+  });
+
+  it("warns and skips tokens with no parseable value", () => {
+    const spec = parseDesignMd(`# Test
+## Color Palette
+- Primary — see Stripe brand docs
+- Surface — #FFF8F0
+`);
+    const compiled = compileTailwindTheme(spec);
+    expect(compiled.entries.find((e) => e.variable === "--color-primary")).toBeUndefined();
+    expect(compiled.warnings.some((w) => w.kind === "missing-value" && w.tokenName === "Primary")).toBe(true);
+  });
+
+  it("flags slug collisions", () => {
+    const spec = parseDesignMd(`# Test
+## Color Palette
+- Primary — #ff0000
+- primary — #00ff00
+`);
+    const compiled = compileTailwindTheme(spec);
+    expect(compiled.warnings.some((w) => w.kind === "slug-collision")).toBe(true);
+    // First wins.
+    expect(compiled.entries.find((e) => e.variable === "--color-primary")?.value).toBe("#ff0000");
+  });
+});
+
+describe("compileTailwindTheme — emit order + section comments", () => {
+  it("groups entries by section with comment dividers", () => {
+    const spec = parseDesignMd(`# Test
+## Color Palette
+- Primary — #FF8C42
+
+## Layout
+- sm: 0.5rem
+- md: 1rem
+`);
+    const compiled = compileTailwindTheme(spec);
+    expect(compiled.cssBody).toContain("/* Colors */");
+    expect(compiled.cssBody).toContain("--color-primary: #FF8C42;");
+    expect(compiled.cssBody).toContain("/* Spacing */");
+    expect(compiled.cssBody).toContain("--spacing-sm: 0.5rem;");
+  });
+});
+
+describe("mergeThemeIntoCss", () => {
+  it("inserts a fresh markered block when none exists", () => {
+    const spec = parseDesignMd(`# Test
+## Color Palette
+- Primary — #FF8C42
+`);
+    const compiled = compileTailwindTheme(spec);
+    const result = mergeThemeIntoCss("@import 'tailwindcss';\n", compiled);
+    expect(result.inserted).toBe(true);
+    expect(result.css).toContain(THEME_MARKER_START);
+    expect(result.css).toContain(THEME_MARKER_END);
+    expect(result.css).toContain("--color-primary: #FF8C42;");
+    expect(result.css).toContain("@import 'tailwindcss';");
+  });
+
+  it("replaces the markered region only — leaves surrounding content untouched", () => {
+    const initial = `@import 'tailwindcss';
+
+/* user comment */
+${THEME_MARKER_START}
+@theme {
+  --color-primary: oldvalue;
+}
+${THEME_MARKER_END}
+
+.user-class { color: red; }
+`;
+    const spec = parseDesignMd(`# Test
+## Color Palette
+- Primary — #FF8C42
+`);
+    const compiled = compileTailwindTheme(spec);
+    const result = mergeThemeIntoCss(initial, compiled);
+    expect(result.inserted).toBe(false);
+    expect(result.css).toContain("/* user comment */");
+    expect(result.css).toContain(".user-class { color: red; }");
+    expect(result.css).toContain("--color-primary: #FF8C42;");
+    expect(result.css).not.toContain("oldvalue");
+  });
+
+  it("flags conflicts when a hand-written @theme variable contradicts DESIGN.md", () => {
+    const initial = `@import 'tailwindcss';
+@theme {
+  --color-primary: #000000;
+}
+`;
+    const spec = parseDesignMd(`# Test
+## Color Palette
+- Primary — #FF8C42
+`);
+    const compiled = compileTailwindTheme(spec);
+    const result = mergeThemeIntoCss(initial, compiled);
+    expect(result.conflicts).toHaveLength(1);
+    expect(result.conflicts[0]!.variable).toBe("--color-primary");
+    expect(result.conflicts[0]!.fromDesign).toBe("#FF8C42");
+    expect(result.conflicts[0]!.fromCss).toBe("#000000");
+  });
+
+  it("emits an empty markered region (no orphans) when DESIGN.md has no tokens", () => {
+    const spec = parseDesignMd("# Empty\n");
+    const compiled = compileTailwindTheme(spec);
+    const result = mergeThemeIntoCss("body { margin: 0; }\n", compiled);
+    expect(result.css).toContain(THEME_MARKER_START);
+    expect(result.css).toContain(THEME_MARKER_END);
+    expect(result.css).toContain("body { margin: 0; }");
+  });
+});
+
+describe("stripMarkeredBlock", () => {
+  it("removes only the markered region", () => {
+    const css = `@import 'tailwindcss';
+${THEME_MARKER_START}
+@theme {
+  --color-primary: #FF8C42;
+}
+${THEME_MARKER_END}
+.user { color: red; }
+`;
+    const result = stripMarkeredBlock(css);
+    expect(result).not.toContain("--color-primary");
+    expect(result).toContain("@import 'tailwindcss';");
+    expect(result).toContain(".user { color: red; }");
+  });
+
+  it("is a no-op when no markers are present", () => {
+    const css = `@import 'tailwindcss';\n`;
+    expect(stripMarkeredBlock(css)).toBe(css);
+  });
+});
+
+describe("end-to-end — stripe-like DESIGN.md → Tailwind theme", () => {
+  it("compiles a full multi-section DESIGN.md into one cohesive @theme", () => {
+    const designMd = `# Stripe-like
+
+## Color Palette
+- Primary — #635BFF — brand
+- Surface — #FFFFFF — page background
+- Text — #1A1F36 — body text
+
+## Typography
+- body: font-family: "Inter", sans-serif; size: 16px; line-height: 1.5
+- h1 hero: font-family: "Inter", sans-serif; size: 48px; line-height: 1.1
+
+## Layout
+- xs: 0.25rem
+- sm: 0.5rem
+- md: 1rem
+
+## Depth & Elevation
+- card — 0 1px 3px rgba(0,0,0,0.1)
+- modal — 0 25px 50px rgba(0,0,0,0.25)
+`;
+    const spec = parseDesignMd(designMd);
+    const compiled = compileTailwindTheme(spec);
+
+    // Colors
+    expect(compiled.cssBody).toContain("--color-primary: #635BFF;");
+    expect(compiled.cssBody).toContain("--color-surface: #FFFFFF;");
+    // Typography (font + text)
+    expect(compiled.cssBody).toContain("--font-body:");
+    expect(compiled.cssBody).toContain("--text-h1-hero: 48px / 1.1;");
+    // Spacing
+    expect(compiled.cssBody).toContain("--spacing-md: 1rem;");
+    // Shadows
+    expect(compiled.cssBody).toContain("--shadow-card:");
+    expect(compiled.cssBody).toContain("--shadow-modal:");
+  });
+});

package/src/design/index.ts

@@ -20,6 +20,20 @@ export {
   AWESOME_DESIGN_MD_RAW_BASE,
 } from "./scaffold";
 
+export {
+  compileTailwindTheme,
+  mergeThemeIntoCss,
+  stripMarkeredBlock,
+  slugifyTokenName,
+  THEME_MARKER_START,
+  THEME_MARKER_END,
+  type CompiledTheme,
+  type CompiledThemeEntry,
+  type CompiledThemeWarning,
+  type ThemeMergeConflict,
+  type ThemeMergeResult,
+} from "./tailwind-theme";
+
 export type {
   AgentPrompt,
   AgentPromptsSection,

package/src/design/tailwind-theme.ts

@@ -0,0 +1,441 @@
+/**
+ * DESIGN.md → Tailwind v4 `@theme` compiler (Token Bridge).
+ *
+ * Issue #245 M3 — Team E. Reads structured tokens from a parsed
+ * `DesignSpec` and emits the CSS `@theme` block Tailwind v4 inlines
+ * to generate utility classes. The compiler is the **only** authoritative
+ * source for the CSS variable names — Tailwind's naming convention is
+ * baked in here so other tools (Guard, MCP) consult one place when
+ * they need to map a token name to its `--var`.
+ *
+ * # Variable naming (Tailwind v4 convention)
+ *
+ *   - `--color-<name>`     — color palette
+ *   - `--font-<name>`      — typography (font family)
+ *   - `--text-<name>`      — typography (font size + line-height)
+ *   - `--spacing-<scale>`  — layout / spacing
+ *   - `--shadow-<name>`    — depth / elevation
+ *
+ * # Token name normalisation
+ *
+ * DESIGN.md author writes tokens in human form ("Hot Peach", "Body
+ * Small"). Tailwind variables need kebab-case ASCII-safe identifiers.
+ * `slugifyTokenName()` is the canonical normaliser:
+ *
+ *   "Hot Peach"   → "hot-peach"
+ *   "Body Small"  → "body-small"
+ *   "h1 hero"     → "h1-hero"
+ *
+ * Collisions (two tokens that slugify the same) are flagged as
+ * `conflicts[]` so the caller can surface them — the compiler keeps
+ * the first occurrence and skips duplicates.
+ *
+ * # Conflict detection
+ *
+ * `compileTailwindTheme` also emits warnings when a DESIGN.md token
+ * contradicts an existing `@theme` block: same variable name, different
+ * value. The merge step (`mergeThemeIntoCss`) preserves user-edited
+ * regions outside the markers, so this is the only place the conflict
+ * can be detected.
+ */
+
+import type { DesignSpec } from "./types";
+
+// ─── Marker constants ────────────────────────────────────────────────
+
+/**
+ * Marker comments wrapping the auto-generated `@theme` body.
+ *
+ * Mandu only ever rewrites the region between these markers. Anything
+ * outside is treated as user-owned and preserved verbatim. The marker
+ * format is intentionally noisy so a casual reader can tell at a
+ * glance "this is generated, don't hand-edit".
+ */
+export const THEME_MARKER_START = "/* @mandu-design-sync:start — generated from DESIGN.md, do not edit */";
+export const THEME_MARKER_END = "/* @mandu-design-sync:end */";
+
+// ─── Public surface ───────────────────────────────────────────────────
+
+export interface CompiledThemeEntry {
+  /** Tailwind v4 CSS variable name (`--color-primary`). */
+  variable: string;
+  value: string;
+  /** Origin token from the DesignSpec (e.g. "Hot Peach"). */
+  sourceTokenName: string;
+  /** Section the token came from. */
+  section: "color-palette" | "typography" | "layout" | "shadows";
+}
+
+export interface CompiledThemeWarning {
+  kind: "missing-value" | "slug-collision";
+  message: string;
+  /** Token name as it appears in DESIGN.md. */
+  tokenName: string;
+  section: CompiledThemeEntry["section"];
+}
+
+export interface CompiledTheme {
+  /** Flat list of variables in emit order. */
+  entries: CompiledThemeEntry[];
+  /** Non-fatal issues — missing values, slug collisions. */
+  warnings: CompiledThemeWarning[];
+  /** The `@theme { ... }` body as it would be written to disk. */
+  cssBody: string;
+}
+
+export interface ThemeMergeConflict {
+  variable: string;
+  fromDesign: string;
+  fromCss: string;
+}
+
+export interface ThemeMergeResult {
+  /** Updated CSS — markered region replaced, rest preserved. */
+  css: string;
+  /**
+   * Variables that collide with manual `@theme` declarations OUTSIDE
+   * the marker region. The caller surfaces these in CLI output so the
+   * user knows to reconcile.
+   */
+  conflicts: ThemeMergeConflict[];
+  /** Whether the markered region already existed (vs. was inserted). */
+  inserted: boolean;
+}
+
+/**
+ * Compile a `DesignSpec` into a Tailwind v4 `@theme` block.
+ *
+ * Tokens with no parseable value are skipped with a `missing-value`
+ * warning — they're declarative-only entries (e.g. "primary — see
+ * docs"). Slug collisions also warn but never throw.
+ */
+export function compileTailwindTheme(spec: DesignSpec): CompiledTheme {
+  const entries: CompiledThemeEntry[] = [];
+  const warnings: CompiledThemeWarning[] = [];
+  const seen = new Set<string>();
+
+  // Color palette → --color-<slug>
+  for (const token of spec.sections["color-palette"].tokens) {
+    const variable = `--color-${slugifyTokenName(token.name)}`;
+    if (!token.value) {
+      warnings.push({
+        kind: "missing-value",
+        message: `color "${token.name}" has no parseable value — skipped`,
+        tokenName: token.name,
+        section: "color-palette",
+      });
+      continue;
+    }
+    if (seen.has(variable)) {
+      warnings.push({
+        kind: "slug-collision",
+        message: `color "${token.name}" collides with an earlier token on ${variable} — skipped`,
+        tokenName: token.name,
+        section: "color-palette",
+      });
+      continue;
+    }
+    seen.add(variable);
+    entries.push({
+      variable,
+      value: token.value,
+      sourceTokenName: token.name,
+      section: "color-palette",
+    });
+  }
+
+  // Typography → --font-<slug> + --text-<slug>
+  for (const token of spec.sections.typography.tokens) {
+    const slug = slugifyTokenName(token.name);
+    if (token.fontFamily) {
+      const variable = `--font-${slug}`;
+      if (!seen.has(variable)) {
+        seen.add(variable);
+        entries.push({
+          variable,
+          value: token.fontFamily,
+          sourceTokenName: token.name,
+          section: "typography",
+        });
+      } else {
+        warnings.push({
+          kind: "slug-collision",
+          message: `typography "${token.name}" collides on ${variable}`,
+          tokenName: token.name,
+          section: "typography",
+        });
+      }
+    }
+    if (token.size) {
+      const variable = `--text-${slug}`;
+      const value = token.lineHeight ? `${token.size} / ${token.lineHeight}` : token.size;
+      if (!seen.has(variable)) {
+        seen.add(variable);
+        entries.push({
+          variable,
+          value,
+          sourceTokenName: token.name,
+          section: "typography",
+        });
+      } else {
+        warnings.push({
+          kind: "slug-collision",
+          message: `typography "${token.name}" collides on ${variable}`,
+          tokenName: token.name,
+          section: "typography",
+        });
+      }
+    }
+    if (!token.fontFamily && !token.size) {
+      warnings.push({
+        kind: "missing-value",
+        message: `typography "${token.name}" has neither fontFamily nor size — skipped`,
+        tokenName: token.name,
+        section: "typography",
+      });
+    }
+  }
+
+  // Layout / spacing → --spacing-<slug>
+  for (const token of spec.sections.layout.tokens) {
+    if (!token.value) {
+      warnings.push({
+        kind: "missing-value",
+        message: `spacing "${token.name}" has no value — skipped`,
+        tokenName: token.name,
+        section: "layout",
+      });
+      continue;
+    }
+    const variable = `--spacing-${slugifyTokenName(token.name)}`;
+    if (seen.has(variable)) {
+      warnings.push({
+        kind: "slug-collision",
+        message: `spacing "${token.name}" collides on ${variable}`,
+        tokenName: token.name,
+        section: "layout",
+      });
+      continue;
+    }
+    seen.add(variable);
+    entries.push({
+      variable,
+      value: token.value,
+      sourceTokenName: token.name,
+      section: "layout",
+    });
+  }
+
+  // Shadows → --shadow-<slug>
+  for (const token of spec.sections.shadows.tokens) {
+    if (!token.value) {
+      warnings.push({
+        kind: "missing-value",
+        message: `shadow "${token.name}" has no value — skipped`,
+        tokenName: token.name,
+        section: "shadows",
+      });
+      continue;
+    }
+    const variable = `--shadow-${slugifyTokenName(token.name)}`;
+    if (seen.has(variable)) {
+      warnings.push({
+        kind: "slug-collision",
+        message: `shadow "${token.name}" collides on ${variable}`,
+        tokenName: token.name,
+        section: "shadows",
+      });
+      continue;
+    }
+    seen.add(variable);
+    entries.push({
+      variable,
+      value: token.value,
+      sourceTokenName: token.name,
+      section: "shadows",
+    });
+  }
+
+  return {
+    entries,
+    warnings,
+    cssBody: formatThemeBody(entries),
+  };
+}
+
+/**
+ * Merge a compiled `@theme` body into an existing CSS file. The
+ * markered region (between `THEME_MARKER_START` and `_END`) is
+ * **replaced**; everything outside is preserved verbatim.
+ *
+ * If the markers are absent, the merger inserts a fresh markered block:
+ *   - Inside the first existing `@theme { ... }` block when one exists
+ *     (so users get to keep their hand-written palette and the
+ *     generated block sits alongside it).
+ *   - Otherwise as a top-level `@theme { ... }` block prepended to the
+ *     file. The user can move it later — we err on the side of
+ *     "visible at the top" rather than "buried somewhere".
+ *
+ * Conflicts: variables declared both inside the generated region AND
+ * inside a hand-written `@theme` block elsewhere in the file are
+ * surfaced in `conflicts[]`. The auto-generated value wins inside the
+ * markered region; the user's value stays in their own block. The
+ * caller decides what to do with the warning.
+ */
+export function mergeThemeIntoCss(
+  existingCss: string,
+  compiled: CompiledTheme,
+): ThemeMergeResult {
+  const generatedBlock = renderMarkeredBlock(compiled.cssBody);
+
+  const startIdx = existingCss.indexOf(THEME_MARKER_START);
+  const endIdx = existingCss.indexOf(THEME_MARKER_END);
+
+  let merged: string;
+  let inserted: boolean;
+  if (startIdx >= 0 && endIdx > startIdx) {
+    const before = existingCss.slice(0, startIdx);
+    const after = existingCss.slice(endIdx + THEME_MARKER_END.length);
+    merged = `${before}${generatedBlock}${after}`;
+    inserted = false;
+  } else {
+    merged = insertMarkeredBlock(existingCss, generatedBlock);
+    inserted = true;
+  }
+
+  const conflicts = detectMergeConflicts(existingCss, compiled);
+  return { css: merged, conflicts, inserted };
+}
+
+/**
+ * Strip the markered block from a CSS file — used by `mandu design
+ * sync --remove` and tests.
+ */
+export function stripMarkeredBlock(css: string): string {
+  const startIdx = css.indexOf(THEME_MARKER_START);
+  const endIdx = css.indexOf(THEME_MARKER_END);
+  if (startIdx < 0 || endIdx < startIdx) return css;
+  const before = css.slice(0, startIdx).replace(/\n*$/, "\n");
+  const after = css.slice(endIdx + THEME_MARKER_END.length).replace(/^\n+/, "");
+  return `${before}${after}`;
+}
+
+/**
+ * Slugify a human-friendly token name into a kebab-case ASCII slug
+ * Tailwind v4 accepts as a CSS variable suffix.
+ */
+export function slugifyTokenName(name: string): string {
+  return name
+    .normalize("NFKD")
+    .replace(/[^\w\s-]/g, "")
+    .trim()
+    .replace(/\s+/g, "-")
+    .replace(/_/g, "-")
+    .replace(/-+/g, "-")
+    .toLowerCase();
+}
+
+// ─── Internals ────────────────────────────────────────────────────────
+
+function formatThemeBody(entries: CompiledThemeEntry[]): string {
+  if (entries.length === 0) return "";
+  const lines: string[] = [];
+  let lastSection: CompiledThemeEntry["section"] | null = null;
+  for (const entry of entries) {
+    if (entry.section !== lastSection) {
+      if (lastSection !== null) lines.push("");
+      lines.push(`  /* ${humanizeSection(entry.section)} */`);
+      lastSection = entry.section;
+    }
+    lines.push(`  ${entry.variable}: ${entry.value};`);
+  }
+  return lines.join("\n");
+}
+
+function humanizeSection(section: CompiledThemeEntry["section"]): string {
+  switch (section) {
+    case "color-palette":
+      return "Colors";
+    case "typography":
+      return "Typography";
+    case "layout":
+      return "Spacing";
+    case "shadows":
+      return "Shadows";
+  }
+}
+
+function renderMarkeredBlock(themeBody: string): string {
+  if (themeBody.trim().length === 0) {
+    // Even an empty body keeps the markers — re-running sync after
+    // emptying DESIGN.md should remove old vars, not orphan them.
+    return `${THEME_MARKER_START}\n@theme {\n}\n${THEME_MARKER_END}`;
+  }
+  return `${THEME_MARKER_START}\n@theme {\n${themeBody}\n}\n${THEME_MARKER_END}`;
+}
+
+/**
+ * Insert a fresh markered block. Prefer to nest it inside an existing
+ * `@theme` block when one exists; otherwise prepend.
+ */
+function insertMarkeredBlock(css: string, block: string): string {
+  // Try to find the END of the first `@theme { ... }` block.
+  const themeStart = /@theme\s*\{/.exec(css);
+  if (themeStart) {
+    let depth = 0;
+    let i = themeStart.index;
+    for (; i < css.length; i++) {
+      const ch = css[i];
+      if (ch === "{") depth++;
+      else if (ch === "}") {
+        depth--;
+        if (depth === 0) break;
+      }
+    }
+    if (i < css.length) {
+      // Insert just before the closing `}` of the existing @theme block,
+      // unwrapping our generated block (which contains its own @theme).
+      // The cleanest move: replace the whole existing @theme block with
+      // a concatenation of "user's content" + generated body. But that
+      // risks re-ordering. So instead, append the generated block AFTER
+      // the existing one — Tailwind merges multiple @theme blocks at
+      // build time.
+      const before = css.slice(0, i + 1);
+      const after = css.slice(i + 1);
+      return `${before}\n\n${block}\n${after}`;
+    }
+  }
+  // No existing @theme → prepend.
+  return `${block}\n\n${css}`.replace(/\n{3,}/g, "\n\n");
+}
+
+function detectMergeConflicts(
+  existingCss: string,
+  compiled: CompiledTheme,
+): ThemeMergeConflict[] {
+  // Strip the markered region — anything inside is owned by Mandu and
+  // can't conflict with itself.
+  const outside = stripMarkeredBlock(existingCss);
+  const conflicts: ThemeMergeConflict[] = [];
+  for (const entry of compiled.entries) {
+    const re = new RegExp(
+      `${escapeRegex(entry.variable)}\\s*:\\s*([^;\\n]+);`,
+      "m",
+    );
+    const m = re.exec(outside);
+    if (!m) continue;
+    const fromCss = m[1]!.trim();
+    if (fromCss !== entry.value.trim()) {
+      conflicts.push({
+        variable: entry.variable,
+        fromDesign: entry.value,
+        fromCss,
+      });
+    }
+  }
+  return conflicts;
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/filling/filling.ts

@@ -31,6 +31,10 @@ import {
   type ExecuteOptions,
 } from "../runtime/lifecycle";
 import type { SlotMetadata, SlotConstraints } from "../guard/semantic-slots";
+import {
+  DeployIntentInput,
+  type DeployIntentInput as DeployIntentInputType,
+} from "../deploy/intent";
 
 /** Handler function type */
 export type Handler = (ctx: ManduContext) => Response | Promise<Response>;
@@ -112,6 +116,19 @@ interface FillingConfig<TLoaderData = unknown> {
   middleware: MiddlewareEntry[];
   /** Semantic slot metadata */
   semantic: SlotMetadata;
+  /**
+   * Issue #250 M5 — explicit deploy intent override. When present,
+   * `mandu deploy:plan` records this entry as `source: "explicit"`,
+   * which the planner never overwrites via inference. The shape is
+   * the partial-input form so users can declare just the fields they
+   * care about (typically `runtime` + maybe `regions`).
+   *
+   * Use this to escape-hatch the heuristic / brain when you know
+   * better than they do — e.g. an API route that imports a DB driver
+   * but is actually called from a build-only script and you want it
+   * to ship as `static`.
+   */
+  deploy?: DeployIntentInputType;
 }
 
 export class ManduFilling<TLoaderData = unknown> {
@@ -201,6 +218,49 @@ export class ManduFilling<TLoaderData = unknown> {
     return { ...this.config.semantic };
   }
 
+  /**
+   * Deploy intent override — pin the runtime / cache / regions for this
+   * route so `mandu deploy:plan` never overrides it via inference.
+   *
+   * Issue #250 M5. The shape mirrors the cache schema's partial-input
+   * form: declare only the fields you care about; the rest fall to
+   * the heuristic / brain. The `deploy:plan` command records the
+   * entry as `source: "explicit"` and protects it from re-inference.
+   *
+   * @example Pin an API route to bun + Seoul region:
+   * ```typescript
+   * Mandu.filling()
+   *   .deploy({ runtime: "bun", regions: ["icn1"] })
+   *   .post(async (ctx) => { ... });
+   * ```
+   *
+   * @example Force a dynamic page to render statically (only valid when
+   * `generateStaticParams` covers every parameter set):
+   * ```typescript
+   * Mandu.filling()
+   *   .deploy({ runtime: "static" })
+   *   .loader(async () => ({ ... }));
+   * ```
+   *
+   * The intent is validated immediately so a typo (`runtime: "lambdda"`)
+   * fails at module load instead of silently shipping the wrong shape.
+   */
+  deploy(intent: DeployIntentInputType): this {
+    this.config.deploy = DeployIntentInput.parse(intent);
+    return this;
+  }
+
+  /**
+   * Read the explicit deploy intent for this route, if any.
+   *
+   * Returns `undefined` when the user did not call `.deploy()`. The
+   * build-time extractor consults this to decide whether to mark the
+   * cache entry as `source: "explicit"` or pass through to inference.
+   */
+  getDeployIntent(): DeployIntentInputType | undefined {
+    return this.config.deploy;
+  }
+
   /**
    * SSR 데이터 로더 등록
    *