openuispec 0.2.12 → 0.2.14

package/mcp-server/preview.ts

@@ -0,0 +1,292 @@
+/**
+ * preview.ts — Orchestrates spec loading, mock data, and HTML rendering
+ * for the openuispec_preview tool.
+ */
+
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import YAML from "yaml";
+import { findProjectDir } from "../drift/index.js";
+import { getBrowser, type ScreenshotResult } from "./screenshot-shared.js";
+import { renderPage, type PreviewContext } from "./preview-render.js";
+
+// ── types ───────────────────────────────────────────────────────────
+
+export interface PreviewOptions {
+  screen: string;
+  size_class?: "compact" | "regular" | "expanded";
+  theme?: "light" | "dark";
+  locale?: string;
+  viewport?: { width: number; height: number };
+  include_html?: boolean;
+}
+
+// ── viewport defaults per size class ────────────────────────────────
+
+const SIZE_CLASS_VIEWPORTS: Record<string, { width: number; height: number }> = {
+  compact: { width: 390, height: 844 },
+  regular: { width: 820, height: 1180 },
+  expanded: { width: 1280, height: 800 },
+};
+
+// ── spec loading helpers ────────────────────────────────────────────
+
+function loadManifest(projectDir: string): any {
+  const manifestPath = join(projectDir, "openuispec.yaml");
+  if (!existsSync(manifestPath)) {
+    throw new Error(`Manifest not found at ${manifestPath}`);
+  }
+  return YAML.parse(readFileSync(manifestPath, "utf-8"));
+}
+
+function loadScreen(projectDir: string, manifest: any, screenName: string): any {
+  const screensDir = resolve(projectDir, manifest.includes?.screens ?? "./screens/");
+
+  // Try exact filename first
+  const candidates = [
+    join(screensDir, `${screenName}.yaml`),
+    join(screensDir, `${screenName}.yml`),
+  ];
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      return YAML.parse(readFileSync(candidate, "utf-8"));
+    }
+  }
+
+  // Scan all screen files for matching screen name key
+  if (existsSync(screensDir)) {
+    for (const file of readdirSync(screensDir)) {
+      if (!file.endsWith(".yaml") && !file.endsWith(".yml")) continue;
+      const content = YAML.parse(readFileSync(join(screensDir, file), "utf-8"));
+      if (content && typeof content === "object" && screenName in content) {
+        return content;
+      }
+    }
+  }
+
+  throw new Error(
+    `Screen "${screenName}" not found in ${screensDir}. ` +
+    `Available: ${existsSync(screensDir) ? readdirSync(screensDir).filter(f => f.endsWith(".yaml")).map(f => f.replace(".yaml", "")).join(", ") : "none"}`,
+  );
+}
+
+function loadAllTokens(projectDir: string, manifest: any): Record<string, any> {
+  const tokensDir = resolve(projectDir, manifest.includes?.tokens ?? "./tokens/");
+  const tokens: Record<string, any> = {};
+
+  if (!existsSync(tokensDir)) return tokens;
+
+  for (const file of readdirSync(tokensDir)) {
+    if (!file.endsWith(".yaml") && !file.endsWith(".yml")) continue;
+    const category = file.replace(/\.ya?ml$/, "");
+    try {
+      tokens[category] = YAML.parse(readFileSync(join(tokensDir, file), "utf-8"));
+    } catch {
+      // Skip malformed token files
+    }
+  }
+
+  return tokens;
+}
+
+function loadLocale(projectDir: string, manifest: any, localeName: string): Record<string, string> {
+  const localesDir = resolve(projectDir, manifest.includes?.locales ?? "./locales/");
+
+  const candidates = [
+    join(localesDir, `${localeName}.json`),
+    join(localesDir, `${localeName}.yaml`),
+    join(localesDir, `${localeName}.yml`),
+  ];
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      const content = readFileSync(candidate, "utf-8");
+      if (candidate.endsWith(".json")) {
+        return JSON.parse(content);
+      }
+      return YAML.parse(content) ?? {};
+    }
+  }
+
+  // Fallback to default locale
+  const defaultLocale = manifest.i18n?.default_locale ?? "en";
+  if (localeName !== defaultLocale) {
+    return loadLocale(projectDir, manifest, defaultLocale);
+  }
+
+  return {};
+}
+
+function loadContractDefs(projectDir: string, manifest: any): Record<string, any> {
+  const contractsDir = resolve(projectDir, manifest.includes?.contracts ?? "./contracts/");
+  const defs: Record<string, any> = {};
+
+  if (!existsSync(contractsDir)) return defs;
+
+  for (const file of readdirSync(contractsDir)) {
+    if (!file.endsWith(".yaml") && !file.endsWith(".yml")) continue;
+    try {
+      const content = YAML.parse(readFileSync(join(contractsDir, file), "utf-8"));
+      if (content && typeof content === "object") {
+        const name = file.replace(/\.ya?ml$/, "");
+        defs[name] = content;
+      }
+    } catch {
+      // Skip malformed contract files
+    }
+  }
+
+  return defs;
+}
+
+function loadComponentDefs(projectDir: string, manifest: any): Record<string, any> {
+  const componentsDir = resolve(projectDir, manifest.includes?.components ?? "./components/");
+  const defs: Record<string, any> = {};
+
+  if (!existsSync(componentsDir)) return defs;
+
+  for (const file of readdirSync(componentsDir)) {
+    if (!file.endsWith(".yaml") && !file.endsWith(".yml")) continue;
+    try {
+      const content = YAML.parse(readFileSync(join(componentsDir, file), "utf-8"));
+      if (content && typeof content === "object") {
+        for (const [name, def] of Object.entries(content)) {
+          defs[name] = def;
+        }
+      }
+    } catch {
+      // Skip malformed component files
+    }
+  }
+
+  return defs;
+}
+
+function loadMockData(projectDir: string, screenName: string): { data: Record<string, any>; params: Record<string, any> } {
+  const mockDir = join(projectDir, "mock");
+
+  const candidates = [
+    join(mockDir, `${screenName}.yaml`),
+    join(mockDir, `${screenName}.yml`),
+    join(mockDir, `${screenName}.json`),
+  ];
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      const content = readFileSync(candidate, "utf-8");
+      let parsed: any;
+      if (candidate.endsWith(".json")) {
+        parsed = JSON.parse(content);
+      } else {
+        parsed = YAML.parse(content);
+      }
+      return {
+        data: parsed?.data ?? parsed ?? {},
+        params: parsed?.params ?? {},
+      };
+    }
+  }
+
+  return { data: {}, params: {} };
+}
+
+// ── main preview function ───────────────────────────────────────────
+
+export async function renderPreview(
+  projectCwd: string,
+  options: PreviewOptions,
+): Promise<ScreenshotResult> {
+  const {
+    screen,
+    size_class = "compact",
+    theme = "light",
+    locale: localeName = "en",
+    viewport,
+    include_html = false,
+  } = options;
+
+  // 1. Find project directory
+  const projectDir = findProjectDir(projectCwd);
+
+  // 2. Load specs
+  const manifest = loadManifest(projectDir);
+  const screenSpec = loadScreen(projectDir, manifest, screen);
+  const tokens = loadAllTokens(projectDir, manifest);
+  const locale = loadLocale(projectDir, manifest, localeName);
+
+  // 3. Load contract definitions (project extensions) and component definitions
+  const contractDefs = loadContractDefs(projectDir, manifest);
+  manifest._contractDefs = contractDefs;
+  const componentDefs = loadComponentDefs(projectDir, manifest);
+  manifest._componentDefs = componentDefs;
+
+  // 4. Load mock data
+  const { data: mockData, params: mockParams } = loadMockData(projectDir, screen);
+
+  // 5. Build render context
+  const ctx: PreviewContext = {
+    manifest,
+    screen: screenSpec,
+    screenName: screen,
+    tokens,
+    locale,
+    mockData,
+    mockParams,
+    sizeClass: size_class,
+    theme,
+  };
+
+  // 6. Render HTML
+  const html = renderPage(ctx);
+
+  // 7. Screenshot with Puppeteer
+  const vp = viewport ?? SIZE_CLASS_VIEWPORTS[size_class];
+  const browser = await getBrowser();
+  const page = await browser.newPage();
+
+  try {
+    await page.setViewport({
+      width: vp.width,
+      height: vp.height,
+      deviceScaleFactor: 2,
+    });
+
+    if (theme === "dark") {
+      await page.emulateMediaFeatures([
+        { name: "prefers-color-scheme", value: "dark" },
+      ]);
+    }
+
+    await page.setContent(html, { waitUntil: "load", timeout: 10_000 });
+
+    // Small delay for CSS to settle
+    await new Promise((r) => setTimeout(r, 200));
+
+    const buffer = await page.screenshot({ type: "png", fullPage: true });
+    const base64 = buffer.toString("base64");
+
+    const content: ScreenshotResult["content"] = [
+      { type: "image" as const, data: base64, mimeType: "image/png" },
+      {
+        type: "text" as const,
+        text: JSON.stringify({
+          screen,
+          size_class,
+          theme,
+          locale: localeName,
+          viewport: vp,
+          mock_data_loaded: Object.keys(mockData).length > 0,
+        }, null, 2),
+      },
+    ];
+
+    if (include_html) {
+      content.push({ type: "text" as const, text: html });
+    }
+
+    return { content };
+  } finally {
+    await page.close();
+  }
+}

package/mcp-server/screenshot-shared.ts

@@ -8,6 +8,44 @@ import { createHash } from "node:crypto";
 import YAML from "yaml";
 import { findProjectDir } from "../drift/index.js";
 
+// ── shared browser manager ──────────────────────────────────────────
+
+let browserInstance: any = null;
+let launchPromise: Promise<any> | null = null;
+
+export async function getBrowser(): Promise<any> {
+  if (browserInstance?.connected) return browserInstance;
+
+  if (!launchPromise) {
+    launchPromise = (async () => {
+      let puppeteer: any;
+      try {
+        puppeteer = await import("puppeteer");
+      } catch {
+        throw new Error(
+          "puppeteer is not installed. Run:\n  npm install -g puppeteer\n" +
+          "or add it to your project's devDependencies.",
+        );
+      }
+
+      browserInstance = await puppeteer.launch({
+        headless: true,
+        args: ["--no-sandbox", "--disable-setuid-sandbox"],
+      });
+      return browserInstance;
+    })();
+  }
+  return launchPromise;
+}
+
+export async function closeBrowser(): Promise<void> {
+  launchPromise = null;
+  if (browserInstance) {
+    try { await browserInstance.close(); } catch { /* ignore */ }
+    browserInstance = null;
+  }
+}
+
 // ── shared result type ──────────────────────────────────────────────
 
 export interface ScreenshotResult {

package/mcp-server/screenshot.ts

@@ -11,6 +11,7 @@ import { join, resolve } from "node:path";
 import { createServer, type AddressInfo } from "node:net";
 import YAML from "yaml";
 import { findProjectDir } from "../drift/index.js";
+import { getBrowser, closeBrowser, type ScreenshotResult } from "./screenshot-shared.js";
 
 // ── types ───────────────────────────────────────────────────────────
 
@@ -25,11 +26,6 @@ export interface ScreenshotOptions {
   output_dir?: string;
 }
 
-export interface ScreenshotResult {
-  content: Array<{ type: "text"; text: string } | { type: "image"; data: string; mimeType: string }>;
-  isError?: true;
-}
-
 // ── free port finder ────────────────────────────────────────────────
 
 function findFreePort(): Promise<number> {
@@ -145,29 +141,7 @@ async function startDevServer(webDir: string): Promise<ServerInstance> {
   return instance;
 }
 
-// ── browser manager ─────────────────────────────────────────────────
-
-let browserInstance: any = null;
-
-async function getBrowser(): Promise<any> {
-  if (browserInstance?.connected) return browserInstance;
-
-  let puppeteer: any;
-  try {
-    puppeteer = await import("puppeteer");
-  } catch {
-    throw new Error(
-      "puppeteer is not installed. Run:\n  npm install -g puppeteer\n" +
-      "or add it to your project's devDependencies.",
-    );
-  }
-
-  browserInstance = await puppeteer.launch({
-    headless: true,
-    args: ["--no-sandbox", "--disable-setuid-sandbox"],
-  });
-  return browserInstance;
-}
+// ── browser manager (imported from screenshot-shared.ts) ────────────
 
 // ── screenshot capture ──────────────────────────────────────────────
 
@@ -360,10 +334,7 @@ export async function shutdownAll() {
     try { instance.process.kill(); } catch { /* already dead */ }
   }
   servers.clear();
-  if (browserInstance) {
-    try { await browserInstance.close(); } catch { /* ignore */ }
-    browserInstance = null;
-  }
+  await closeBrowser();
 }
 
 process.on("exit", () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openuispec",
-  "version": "0.2.12",
+  "version": "0.2.14",
   "license": "MIT",
   "type": "module",
   "description": "A semantic UI specification format for AI-native, platform-native app development",

package/prepare/index.ts

@@ -935,7 +935,7 @@ function referenceExamples(): string[] {
   const packageRoot = resolvePackageRoot();
   const candidates = [
     join(packageRoot, "README.md"),
-    join(packageRoot, "spec", "openuispec-v0.1.md"),
+    join(packageRoot, "spec", "openuispec-v0.2.md"),
     join(packageRoot, "examples", "taskflow", "openuispec"),
     join(packageRoot, "schema"),
   ];

package/schema/component.schema.json

@@ -0,0 +1,278 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openuispec.rsteam.uz/schema/component.schema.json",
+  "title": "OpenUISpec Component",
+  "description": "Reusable composition of contracts with named slots — root key is the component name",
+  "type": "object",
+  "minProperties": 1,
+  "maxProperties": 1,
+  "propertyNames": {
+    "pattern": "^[a-z][a-z0-9_]*$"
+  },
+  "additionalProperties": {
+    "$ref": "#/$defs/component_def"
+  },
+  "$defs": {
+    "component_def": {
+      "type": "object",
+      "description": "A component definition — composition of contracts with named slots, states, variants, and layout",
+      "properties": {
+        "semantic": {
+          "type": "string",
+          "description": "Human-readable description of this component's purpose"
+        },
+        "props": {
+          "type": "object",
+          "description": "Typed property definitions for this component",
+          "additionalProperties": {
+            "$ref": "https://openuispec.rsteam.uz/schema/custom-contract.schema.json#/$defs/prop_def"
+          }
+        },
+        "slots": {
+          "type": "object",
+          "description": "Named slots — each slot wraps a contract instance",
+          "additionalProperties": {
+            "$ref": "#/$defs/slot_def"
+          }
+        },
+        "layout": {
+          "$ref": "#/$defs/component_layout"
+        },
+        "states": {
+          "type": "object",
+          "description": "Composite states that control slot visibility and props",
+          "additionalProperties": {
+            "$ref": "#/$defs/component_state_def"
+          }
+        },
+        "variants": {
+          "type": "object",
+          "description": "Named component variants with layout and slot overrides",
+          "additionalProperties": {
+            "$ref": "#/$defs/component_variant_def"
+          }
+        },
+        "tokens": {
+          "type": "object",
+          "description": "Token bindings for the component container",
+          "additionalProperties": true
+        },
+        "a11y": {
+          "type": "object",
+          "description": "Accessibility requirements",
+          "properties": {
+            "role": {
+              "type": "string",
+              "description": "ARIA/accessibility role"
+            },
+            "label": {
+              "type": "string",
+              "description": "Accessibility label source"
+            }
+          },
+          "additionalProperties": true
+        },
+        "platform_mapping": {
+          "type": "object",
+          "description": "Per-platform native component mapping",
+          "properties": {
+            "ios": { "type": "object", "additionalProperties": true },
+            "android": { "type": "object", "additionalProperties": true },
+            "web": { "type": "object", "additionalProperties": true }
+          },
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": true
+          }
+        },
+        "dependencies": {
+          "type": "object",
+          "description": "Per-platform library/framework requirements",
+          "additionalProperties": {
+            "$ref": "https://openuispec.rsteam.uz/schema/custom-contract.schema.json#/$defs/dependency_def"
+          }
+        },
+        "generation": {
+          "type": "object",
+          "description": "AI generation compliance hints",
+          "properties": {
+            "must_handle": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "should_handle": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "may_handle": {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          },
+          "additionalProperties": false
+        },
+        "test_cases": {
+          "type": "array",
+          "description": "Behavioral verification scenarios",
+          "items": {
+            "$ref": "https://openuispec.rsteam.uz/schema/custom-contract.schema.json#/$defs/test_case"
+          }
+        }
+      },
+      "required": ["semantic", "slots"],
+      "additionalProperties": false
+    },
+    "slot_def": {
+      "type": "object",
+      "description": "A named slot wrapping a contract instance",
+      "properties": {
+        "contract": {
+          "type": "string",
+          "description": "Base contract family (e.g. action_trigger, input_field, data_display)"
+        },
+        "variant": {
+          "type": "string",
+          "description": "Contract variant"
+        },
+        "input_type": {
+          "type": "string",
+          "description": "Input type for input_field contracts (e.g. slider, text)"
+        },
+        "props": {
+          "type": "object",
+          "description": "Default props passed to the contract",
+          "additionalProperties": true
+        },
+        "hideable": {
+          "type": "boolean",
+          "description": "Whether this slot can be hidden by states or screen overrides"
+        },
+        "tokens_override": {
+          "type": "object",
+          "description": "Token overrides for this slot",
+          "additionalProperties": true
+        }
+      },
+      "required": ["contract"],
+      "additionalProperties": false
+    },
+    "component_layout": {
+      "type": "object",
+      "description": "Layout definition for the component",
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "Layout type (e.g. stack, row, grid)"
+        },
+        "spacing": {
+          "type": "string"
+        },
+        "align": {
+          "type": "string"
+        },
+        "justify": {
+          "type": "string"
+        },
+        "sections": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/component_layout_item"
+          }
+        }
+      },
+      "additionalProperties": true
+    },
+    "component_layout_item": {
+      "description": "A layout item — either a slot reference or a nested layout",
+      "type": "object",
+      "properties": {
+        "slot": {
+          "type": "string",
+          "description": "Reference to a named slot"
+        },
+        "layout": {
+          "$ref": "#/$defs/component_layout"
+        }
+      },
+      "additionalProperties": true
+    },
+    "component_state_def": {
+      "type": "object",
+      "description": "A composite state affecting slot visibility and props",
+      "properties": {
+        "semantic": {
+          "type": "string"
+        },
+        "hide_slots": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Slots to hide in this state"
+        },
+        "slot_overrides": {
+          "type": "object",
+          "description": "Per-slot prop/variant overrides in this state",
+          "additionalProperties": {
+            "$ref": "#/$defs/slot_override"
+          }
+        },
+        "transitions_to": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "States this state can transition to"
+        }
+      },
+      "additionalProperties": false
+    },
+    "component_variant_def": {
+      "type": "object",
+      "description": "A named component variant with layout and slot overrides",
+      "properties": {
+        "semantic": {
+          "type": "string"
+        },
+        "hide_slots": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Slots to hide in this variant"
+        },
+        "layout": {
+          "$ref": "#/$defs/component_layout"
+        },
+        "tokens": {
+          "type": "object",
+          "description": "Token overrides for this variant",
+          "additionalProperties": true
+        },
+        "slot_overrides": {
+          "type": "object",
+          "description": "Per-slot prop/variant overrides in this variant",
+          "additionalProperties": {
+            "$ref": "#/$defs/slot_override"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "slot_override": {
+      "type": "object",
+      "description": "Override for a specific slot",
+      "properties": {
+        "variant": {
+          "type": "string"
+        },
+        "props": {
+          "type": "object",
+          "additionalProperties": true
+        },
+        "tokens_override": {
+          "type": "object",
+          "additionalProperties": true
+        },
+        "hidden": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}