@mandujs/core 0.54.32 → 0.55.0-beta.1

package/src/design/types.ts

@@ -1,210 +1,210 @@
-/**
- * DESIGN.md type surface.
- *
- * The 9-section schema is borrowed verbatim from Google Stitch's
- * DESIGN.md convention (also used by VoltAgent's awesome-design-md
- * catalog of 69 brand spec files). Mandu adopts it as a first-class
- * format rather than inventing its own — see Issue #245 v2 plan.
- *
- * Parsing is **permissive**: a DESIGN.md may include any subset of
- * sections, in any order, with arbitrary free-form content between
- * structured tokens. The parser populates the sections it understands
- * and stores the rest as `rawBody` so round-trips don't lose user
- * prose. Tools (Guard, MCP, token bridge) consume only the structured
- * fields they care about.
- *
- * @module core/design/types
- */
-
-export const DESIGN_SECTION_IDS = [
-  "theme",
-  "color-palette",
-  "typography",
-  "components",
-  "layout",
-  "shadows",
-  "dos-donts",
-  "responsive",
-  "agent-prompts",
-] as const;
-
-export type DesignSectionId = (typeof DESIGN_SECTION_IDS)[number];
-
-/**
- * Color palette entry. `hex` may be missing when a row only carries a
- * semantic role (e.g. "primary — brand color, see Stripe docs"); the
- * Guard rule and the token bridge skip rows without a parseable value.
- */
-export interface ColorToken {
-  name: string;
-  /** `#rrggbb`, `#rrggbbaa`, `rgb(...)`, `rgba(...)`, `oklch(...)`, etc. */
-  value?: string;
-  /** Functional role — "primary", "surface", "text-muted", … (free-form). */
-  role?: string;
-}
-
-export interface TypographyToken {
-  name: string;
-  fontFamily?: string;
-  weight?: string;
-  size?: string;
-  lineHeight?: string;
-  /** Free-form usage hint ("h1 hero", "body small", …). */
-  usage?: string;
-}
-
-export interface ComponentToken {
-  name: string;
-  /** Variants surfaced as a `name → list` map. Empty when not declared. */
-  variants: Record<string, string[]>;
-  /** Free-form description / props notes from markdown body. */
-  notes?: string;
-}
-
-export interface SpacingToken {
-  /** "xs", "sm", "md", "lg", "xl" — caller-defined. */
-  name: string;
-  value?: string;
-}
-
-export interface ShadowToken {
-  /** "card", "popover", "modal" — caller-defined elevation name. */
-  name: string;
-  value?: string;
-  /** Free-form usage hint. */
-  usage?: string;
-}
-
-export interface DoDontRule {
-  /** "do" or "dont" — Guard rule consumes "dont" as `forbidInlineClasses` candidates. */
-  kind: "do" | "dont";
-  /** Plain-text rule body. */
-  text: string;
-}
-
-export interface ResponsiveBreakpoint {
-  name: string;
-  value?: string;
-  /** Free-form notes (touch target, scaling strategy, …). */
-  notes?: string;
-}
-
-export interface AgentPrompt {
-  /** Heading or first sentence used as a label. */
-  title: string;
-  /** Body of the prompt — passed through verbatim. */
-  body: string;
-}
-
-/**
- * Per-section payload. Every section carries:
- *   - `present`: whether the heading was found at all
- *   - `rawBody`: original markdown body for round-trip / fallback
- *   - structured fields where applicable (`tokens`, `rules`, …)
- *
- * Tools that only care about presence (e.g. `mandu design validate`)
- * read `present`; structured consumers (Guard, token bridge) read the
- * typed fields and treat empties as "not declared".
- */
-export interface DesignSection {
-  id: DesignSectionId;
-  present: boolean;
-  /** Heading line as written by the user (e.g. "## Color Palette"). */
-  headingText?: string;
-  /** Raw markdown body between this heading and the next H2. */
-  rawBody: string;
-}
-
-export interface ThemeSection extends DesignSection {
-  id: "theme";
-  /** First non-empty paragraph — quick "vibe" answer. */
-  summary?: string;
-}
-
-export interface ColorPaletteSection extends DesignSection {
-  id: "color-palette";
-  tokens: ColorToken[];
-}
-
-export interface TypographySection extends DesignSection {
-  id: "typography";
-  tokens: TypographyToken[];
-}
-
-export interface ComponentsSection extends DesignSection {
-  id: "components";
-  tokens: ComponentToken[];
-}
-
-export interface LayoutSection extends DesignSection {
-  id: "layout";
-  tokens: SpacingToken[];
-}
-
-export interface ShadowsSection extends DesignSection {
-  id: "shadows";
-  tokens: ShadowToken[];
-}
-
-export interface DosDontsSection extends DesignSection {
-  id: "dos-donts";
-  rules: DoDontRule[];
-}
-
-export interface ResponsiveSection extends DesignSection {
-  id: "responsive";
-  breakpoints: ResponsiveBreakpoint[];
-}
-
-export interface AgentPromptsSection extends DesignSection {
-  id: "agent-prompts";
-  prompts: AgentPrompt[];
-}
-
-export type AnyDesignSection =
-  | ThemeSection
-  | ColorPaletteSection
-  | TypographySection
-  | ComponentsSection
-  | LayoutSection
-  | ShadowsSection
-  | DosDontsSection
-  | ResponsiveSection
-  | AgentPromptsSection;
-
-export interface DesignSpec {
-  /** Original source string (for round-trip). */
-  source: string;
-  /**
-   * Sections in canonical order. `present: false` when the user omitted
-   * the section — Mandu still reserves the slot so consumers can index
-   * by id without `find()`.
-   */
-  sections: {
-    theme: ThemeSection;
-    "color-palette": ColorPaletteSection;
-    typography: TypographySection;
-    components: ComponentsSection;
-    layout: LayoutSection;
-    shadows: ShadowsSection;
-    "dos-donts": DosDontsSection;
-    responsive: ResponsiveSection;
-    "agent-prompts": AgentPromptsSection;
-  };
-  /** Extra H2 sections the user wrote that don't map to the 9-section spec. */
-  extraSections: Array<{ heading: string; body: string }>;
-  /** Optional H1 title at the top of the file. */
-  title?: string;
-}
-
-export interface ValidationIssue {
-  /** "missing" — section absent. "empty" — section present but no structured tokens. "malformed" — parse error inside a section. */
-  kind: "missing" | "empty" | "malformed";
-  section: DesignSectionId;
-  message: string;
-}
-
-export interface ValidationResult {
-  ok: boolean;
-  issues: ValidationIssue[];
-}
+/**
+ * DESIGN.md type surface.
+ *
+ * The 9-section schema is borrowed verbatim from Google Stitch's
+ * DESIGN.md convention (also used by VoltAgent's awesome-design-md
+ * catalog of 69 brand spec files). Mandu adopts it as a first-class
+ * format rather than inventing its own — see Issue #245 v2 plan.
+ *
+ * Parsing is **permissive**: a DESIGN.md may include any subset of
+ * sections, in any order, with arbitrary free-form content between
+ * structured tokens. The parser populates the sections it understands
+ * and stores the rest as `rawBody` so round-trips don't lose user
+ * prose. Tools (Guard, MCP, token bridge) consume only the structured
+ * fields they care about.
+ *
+ * @module core/design/types
+ */
+
+export const DESIGN_SECTION_IDS = [
+  "theme",
+  "color-palette",
+  "typography",
+  "components",
+  "layout",
+  "shadows",
+  "dos-donts",
+  "responsive",
+  "agent-prompts",
+] as const;
+
+export type DesignSectionId = (typeof DESIGN_SECTION_IDS)[number];
+
+/**
+ * Color palette entry. `hex` may be missing when a row only carries a
+ * semantic role (e.g. "primary — brand color, see Stripe docs"); the
+ * Guard rule and the token bridge skip rows without a parseable value.
+ */
+export interface ColorToken {
+  name: string;
+  /** `#rrggbb`, `#rrggbbaa`, `rgb(...)`, `rgba(...)`, `oklch(...)`, etc. */
+  value?: string;
+  /** Functional role — "primary", "surface", "text-muted", … (free-form). */
+  role?: string;
+}
+
+export interface TypographyToken {
+  name: string;
+  fontFamily?: string;
+  weight?: string;
+  size?: string;
+  lineHeight?: string;
+  /** Free-form usage hint ("h1 hero", "body small", …). */
+  usage?: string;
+}
+
+export interface ComponentToken {
+  name: string;
+  /** Variants surfaced as a `name → list` map. Empty when not declared. */
+  variants: Record<string, string[]>;
+  /** Free-form description / props notes from markdown body. */
+  notes?: string;
+}
+
+export interface SpacingToken {
+  /** "xs", "sm", "md", "lg", "xl" — caller-defined. */
+  name: string;
+  value?: string;
+}
+
+export interface ShadowToken {
+  /** "card", "popover", "modal" — caller-defined elevation name. */
+  name: string;
+  value?: string;
+  /** Free-form usage hint. */
+  usage?: string;
+}
+
+export interface DoDontRule {
+  /** "do" or "dont" — Guard rule consumes "dont" as `forbidInlineClasses` candidates. */
+  kind: "do" | "dont";
+  /** Plain-text rule body. */
+  text: string;
+}
+
+export interface ResponsiveBreakpoint {
+  name: string;
+  value?: string;
+  /** Free-form notes (touch target, scaling strategy, …). */
+  notes?: string;
+}
+
+export interface AgentPrompt {
+  /** Heading or first sentence used as a label. */
+  title: string;
+  /** Body of the prompt — passed through verbatim. */
+  body: string;
+}
+
+/**
+ * Per-section payload. Every section carries:
+ *   - `present`: whether the heading was found at all
+ *   - `rawBody`: original markdown body for round-trip / fallback
+ *   - structured fields where applicable (`tokens`, `rules`, …)
+ *
+ * Tools that only care about presence (e.g. `mandu design validate`)
+ * read `present`; structured consumers (Guard, token bridge) read the
+ * typed fields and treat empties as "not declared".
+ */
+export interface DesignSection {
+  id: DesignSectionId;
+  present: boolean;
+  /** Heading line as written by the user (e.g. "## Color Palette"). */
+  headingText?: string;
+  /** Raw markdown body between this heading and the next H2. */
+  rawBody: string;
+}
+
+export interface ThemeSection extends DesignSection {
+  id: "theme";
+  /** First non-empty paragraph — quick "vibe" answer. */
+  summary?: string;
+}
+
+export interface ColorPaletteSection extends DesignSection {
+  id: "color-palette";
+  tokens: ColorToken[];
+}
+
+export interface TypographySection extends DesignSection {
+  id: "typography";
+  tokens: TypographyToken[];
+}
+
+export interface ComponentsSection extends DesignSection {
+  id: "components";
+  tokens: ComponentToken[];
+}
+
+export interface LayoutSection extends DesignSection {
+  id: "layout";
+  tokens: SpacingToken[];
+}
+
+export interface ShadowsSection extends DesignSection {
+  id: "shadows";
+  tokens: ShadowToken[];
+}
+
+export interface DosDontsSection extends DesignSection {
+  id: "dos-donts";
+  rules: DoDontRule[];
+}
+
+export interface ResponsiveSection extends DesignSection {
+  id: "responsive";
+  breakpoints: ResponsiveBreakpoint[];
+}
+
+export interface AgentPromptsSection extends DesignSection {
+  id: "agent-prompts";
+  prompts: AgentPrompt[];
+}
+
+export type AnyDesignSection =
+  | ThemeSection
+  | ColorPaletteSection
+  | TypographySection
+  | ComponentsSection
+  | LayoutSection
+  | ShadowsSection
+  | DosDontsSection
+  | ResponsiveSection
+  | AgentPromptsSection;
+
+export interface DesignSpec {
+  /** Original source string (for round-trip). */
+  source: string;
+  /**
+   * Sections in canonical order. `present: false` when the user omitted
+   * the section — Mandu still reserves the slot so consumers can index
+   * by id without `find()`.
+   */
+  sections: {
+    theme: ThemeSection;
+    "color-palette": ColorPaletteSection;
+    typography: TypographySection;
+    components: ComponentsSection;
+    layout: LayoutSection;
+    shadows: ShadowsSection;
+    "dos-donts": DosDontsSection;
+    responsive: ResponsiveSection;
+    "agent-prompts": AgentPromptsSection;
+  };
+  /** Extra H2 sections the user wrote that don't map to the 9-section spec. */
+  extraSections: Array<{ heading: string; body: string }>;
+  /** Optional H1 title at the top of the file. */
+  title?: string;
+}
+
+export interface ValidationIssue {
+  /** "missing" — section absent. "empty" — section present but no structured tokens. "malformed" — parse error inside a section. */
+  kind: "missing" | "empty" | "malformed";
+  section: DesignSectionId;
+  message: string;
+}
+
+export interface ValidationResult {
+  ok: boolean;
+  issues: ValidationIssue[];
+}

package/src/desktop/__tests__/smoke.test.ts

@@ -17,7 +17,7 @@ import fs from "fs";
 const repoRoot = path.resolve(__dirname, "..", "..", "..", "..", "..");
 const demoPath = path.join(repoRoot, "demo", "desktop-starter");
 
-describe("@mandujs/core/desktop — smoke", () => {
+describe("@mandujs/core/compat/desktop — smoke", () => {
   it("barrel exports createWindow and the type surface", async () => {
     const mod = await import("../index");
     expect(typeof mod.createWindow).toBe("function");
@@ -82,7 +82,7 @@ const canOpenWindow =
     process.platform === "linux");
 
 describe.skipIf(!canOpenWindow)(
-  "@mandujs/core/desktop — browser smoke (opt-in)",
+  "@mandujs/core/compat/desktop — browser smoke (opt-in)",
   () => {
     it("opens and closes a data: URL window", async () => {
       const { createWindow } = await import("../window");

package/src/desktop/__tests__/webview-fallback.test.ts

@@ -36,7 +36,7 @@ import {
   afterEach,
 } from "bun:test";
 
-describe("@mandujs/core/desktop/webview-fallback — module import", () => {
+describe("@mandujs/core/compat/desktop/webview-fallback — module import", () => {
   it("imports without loading libwebview", async () => {
     // The import itself must succeed even when `bun:ffi.dlopen` would
     // fail (no libwebview). Module-level code must not `dlopen` — that
@@ -60,7 +60,7 @@ describe("@mandujs/core/desktop/webview-fallback — module import", () => {
   });
 });
 
-describe("@mandujs/core/desktop/webview-fallback — FFI symbol contract", () => {
+describe("@mandujs/core/compat/desktop/webview-fallback — FFI symbol contract", () => {
   it("_ffiSymbols declares the minimal webview C ABI we depend on", async () => {
     const { _ffiSymbols } = await import("../webview-fallback");
     // The set of symbols MUST match the upstream webview.h surface we
@@ -105,7 +105,7 @@ describe("@mandujs/core/desktop/webview-fallback — FFI symbol contract", () =>
   });
 });
 
-describe("@mandujs/core/desktop/webview-fallback — _mapHintToInt", () => {
+describe("@mandujs/core/compat/desktop/webview-fallback — _mapHintToInt", () => {
   it("matches WEBVIEW_HINT_* enum values from upstream webview.h", async () => {
     const { _mapHintToInt } = await import("../webview-fallback");
     expect(_mapHintToInt("none")).toBe(0);
@@ -116,7 +116,7 @@ describe("@mandujs/core/desktop/webview-fallback — _mapHintToInt", () => {
   });
 });
 
-describe("@mandujs/core/desktop/webview-fallback — library candidate probe", () => {
+describe("@mandujs/core/compat/desktop/webview-fallback — library candidate probe", () => {
   const ORIGINAL_ENV = process.env.MANDU_LIBWEBVIEW_PATH;
 
   beforeEach(() => {
@@ -158,7 +158,7 @@ describe("@mandujs/core/desktop/webview-fallback — library candidate probe", (
   });
 });
 
-describe("@mandujs/core/desktop/webview-fallback — createFallbackWebview", () => {
+describe("@mandujs/core/compat/desktop/webview-fallback — createFallbackWebview", () => {
   it("rejects missing options before any dlopen attempt", async () => {
     const { createFallbackWebview } = await import("../webview-fallback");
     // An empty-object options bag must be caught by defensive guards
@@ -184,33 +184,13 @@ describe("@mandujs/core/desktop/webview-fallback — createFallbackWebview", ()
   });
 });
 
-describe("@mandujs/core/desktop/webview-fallback — loadFFILibwebview failure surface", () => {
-  const ORIGINAL_ENV = process.env.MANDU_LIBWEBVIEW_PATH;
-
-  beforeEach(async () => {
-    // Force an unreachable path so the loader's failure hint is
-    // exercised without depending on the actual libwebview install
-    // state of the CI runner.
-    process.env.MANDU_LIBWEBVIEW_PATH =
-      "/path/that/definitely/does/not/exist/libwebview.so";
-    const mod = await import("../webview-fallback");
-    mod._resetFFICache();
-  });
-
-  afterEach(async () => {
-    if (ORIGINAL_ENV !== undefined) {
-      process.env.MANDU_LIBWEBVIEW_PATH = ORIGINAL_ENV;
-    } else {
-      delete process.env.MANDU_LIBWEBVIEW_PATH;
-    }
-    const mod = await import("../webview-fallback");
-    mod._resetFFICache();
-  });
-
+describe("@mandujs/core/compat/desktop/webview-fallback — loadFFILibwebview failure surface", () => {
   it("throws an actionable error enumerating every probed path", async () => {
-    const { loadFFILibwebview } = await import("../webview-fallback");
+    const { _loadFFILibwebviewCandidates } = await import("../webview-fallback");
+    const missingLibrary =
+      "/path/that/definitely/does/not/exist/libwebview.so";
     try {
-      await loadFFILibwebview();
+      await _loadFFILibwebviewCandidates([missingLibrary]);
       throw new Error("unreachable — loadFFILibwebview should have thrown");
     } catch (err) {
       expect(err).toBeInstanceOf(Error);
@@ -220,7 +200,7 @@ describe("@mandujs/core/desktop/webview-fallback — loadFFILibwebview failure s
       expect(msg).toContain("MANDU_LIBWEBVIEW_PATH");
       expect(msg).toContain("webview/webview");
       // Should enumerate the failing candidate we injected.
-      expect(msg).toContain("libwebview.so");
+      expect(msg).toContain(missingLibrary);
     }
   });
 });
@@ -237,7 +217,7 @@ const canOpenFallbackWindow =
     process.platform === "linux");
 
 describe.skipIf(!canOpenFallbackWindow)(
-  "@mandujs/core/desktop/webview-fallback — browser smoke (opt-in)",
+  "@mandujs/core/compat/desktop/webview-fallback — browser smoke (opt-in)",
   () => {
     it("opens a data: URL window via the FFI fallback", async () => {
       const { createFallbackWebview } = await import("../webview-fallback");