@pwfabric/runtime 0.0.0-stage → 1.0.0-rc.1

package/dist/surface/renderer.js

@@ -0,0 +1,190 @@
+/**
+ * Surface Renderer
+ *
+ * Deterministic surface rendering engine
+ *
+ * The renderer takes an interpreted surface and produces a render tree.
+ * Rendering is deterministic: same input + context = same output.
+ *
+ * INVARIANTS:
+ * - Rendering is pure (no side effects)
+ * - Same input always produces same output
+ * - Render order is deterministic
+ * - All expressions are evaluated synchronously
+ *
+ * @module @pwfabric/runtime/surface/renderer
+ */
+import { createRenderContext, renderSuccess, renderError, createNode } from './types.js';
+import { resolveLayout } from './layout.js';
+// ============================================================
+// DETERMINISTIC RENDERER
+// ============================================================
+/**
+ * Deterministic surface renderer implementation
+ *
+ * This renderer guarantees:
+ * - Same input produces same output
+ * - No hidden state or side effects
+ * - Predictable ordering
+ */
+export class DeterministicRenderer {
+    render(surface, options = {}) {
+        const startTime = performance.now();
+        // Create render context
+        const context = createRenderContext({
+            surfaceId: surface.id,
+            bindings: surface.bindings,
+            data: options.data ?? {},
+            slots: options.slots ? new Map(Object.entries(options.slots)) : new Map(),
+        });
+        // Resolve layout to render nodes
+        const layoutResult = resolveLayout(surface.layout, context);
+        if (!layoutResult.success) {
+            return renderError({
+                type: 'layout_error',
+                message: layoutResult.error,
+            });
+        }
+        // Build root node
+        const root = createRootNode(surface.id, layoutResult.nodes);
+        const nodeCount = countNodes(root);
+        const renderTime = performance.now() - startTime;
+        const output = {
+            surfaceId: surface.id,
+            root,
+            metadata: {
+                renderTime,
+                nodeCount,
+                bindings: Array.from(surface.bindings.keys()),
+            },
+        };
+        return renderSuccess(output);
+    }
+    renderLayout(layout, context) {
+        return resolveLayout(layout, context);
+    }
+}
+/**
+ * Create a root container node
+ */
+function createRootNode(surfaceId, children) {
+    return createNode('fragment', {
+        'data-surface-id': surfaceId,
+        'data-surface-root': true,
+    }, children);
+}
+/**
+ * Count total nodes in a tree
+ */
+function countNodes(node) {
+    let count = 1;
+    for (const child of node.children) {
+        count += countNodes(child);
+    }
+    return count;
+}
+// ============================================================
+// FACTORY
+// ============================================================
+/**
+ * Create a new surface renderer
+ */
+export function createRenderer() {
+    return new DeterministicRenderer();
+}
+// ============================================================
+// RENDER HELPERS
+// ============================================================
+/**
+ * Render a surface to a render tree
+ */
+export function renderSurface(surface, options) {
+    const renderer = createRenderer();
+    return renderer.render(surface, options);
+}
+/**
+ * Check if a render result is successful
+ */
+export function isRenderSuccess(result) {
+    return result.success;
+}
+/**
+ * Check if a render result is a failure
+ */
+export function isRenderError(result) {
+    return !result.success;
+}
+// ============================================================
+// SERIALIZATION
+// ============================================================
+/**
+ * Serialize a render node to JSON
+ */
+export function serializeNode(node) {
+    return {
+        type: node.type,
+        props: node.props,
+        children: node.children.map(serializeNode),
+    };
+}
+/**
+ * Serialize render output to JSON
+ */
+export function serializeOutput(output) {
+    return {
+        surfaceId: output.surfaceId,
+        root: serializeNode(output.root),
+        metadata: output.metadata,
+    };
+}
+// ============================================================
+// HASH FOR DETERMINISM VERIFICATION
+// ============================================================
+/**
+ * Compute a hash of a render node for determinism verification
+ *
+ * Same input should always produce same hash
+ */
+export function hashNode(node) {
+    const parts = [node.type];
+    // Add sorted props
+    const propKeys = Object.keys(node.props).sort();
+    for (const key of propKeys) {
+        const value = node.props[key];
+        parts.push(`${key}=${JSON.stringify(value)}`);
+    }
+    // Add child hashes
+    for (const child of node.children) {
+        parts.push(hashNode(child));
+    }
+    return simpleHash(parts.join('|'));
+}
+/**
+ * Simple string hash (djb2)
+ */
+function simpleHash(str) {
+    let hash = 5381;
+    for (let i = 0; i < str.length; i++) {
+        hash = (hash * 33) ^ str.charCodeAt(i);
+    }
+    return (hash >>> 0).toString(16);
+}
+/**
+ * Verify determinism by rendering twice and comparing hashes
+ */
+export function verifyDeterminism(surface, options) {
+    const renderer = createRenderer();
+    const result1 = renderer.render(surface, options);
+    const result2 = renderer.render(surface, options);
+    if (!result1.success || !result2.success) {
+        return { deterministic: false, hash1: 'error', hash2: 'error' };
+    }
+    const hash1 = hashNode(result1.output.root);
+    const hash2 = hashNode(result2.output.root);
+    return {
+        deterministic: hash1 === hash2,
+        hash1,
+        hash2,
+    };
+}
+//# sourceMappingURL=renderer.js.map

package/dist/surface/renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.js","sourceRoot":"","sources":["../../src/surface/renderer.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Surface Renderer\n *\n * Deterministic surface rendering engine\n *\n * The renderer takes an interpreted surface and produces a render tree.\n * Rendering is deterministic: same input + context = same output.\n *\n * INVARIANTS:\n * - Rendering is pure (no side effects)\n * - Same input always produces same output\n * - Render order is deterministic\n * - All expressions are evaluated synchronously\n *\n * @module @pwfabric/runtime/surface/renderer\n */\n\nimport type { SurfaceId } from '@pwfabric/contracts'\nimport type {\n  RenderNode,\n  RenderContext,\n  RenderResult,\n  RenderOutput,\n  RenderError,\n  LayoutJSON,\n} from './types.js'\nimport { createRenderContext, renderSuccess, renderError, createNode } from './types.js'\nimport { resolveLayout, type LayoutResult } from './layout.js'\nimport type { InterpretedSurface } from './interpreter.js'\n\n// ============================================================\n// RENDERER INTERFACE\n// ============================================================\n\n/**\n * Surface renderer options\n */\nexport interface RenderOptions {\n  readonly data?: Record<string, unknown>\n  readonly slots?: Record<string, readonly RenderNode[]>\n  readonly strict?: boolean\n}\n\n/**\n * Surface renderer\n */\nexport interface SurfaceRenderer {\n  /**\n   * Render an interpreted surface\n   */\n  render(surface: InterpretedSurface, options?: RenderOptions): RenderResult\n\n  /**\n   * Render a layout directly\n   */\n  renderLayout(layout: LayoutJSON, context: RenderContext): LayoutResult\n}\n\n// ============================================================\n// DETERMINISTIC RENDERER\n// ============================================================\n\n/**\n * Deterministic surface renderer implementation\n *\n * This renderer guarantees:\n * - Same input produces same output\n * - No hidden state or side effects\n * - Predictable ordering\n */\nexport class DeterministicRenderer implements SurfaceRenderer {\n  render(surface: InterpretedSurface, options: RenderOptions = {}): RenderResult {\n    const startTime = performance.now()\n\n    // Create render context\n    const context = createRenderContext({\n      surfaceId: surface.id,\n      bindings: surface.bindings,\n      data: options.data ?? {},\n      slots: options.slots ? new Map(Object.entries(options.slots)) : new Map(),\n    })\n\n    // Resolve layout to render nodes\n    const layoutResult = resolveLayout(surface.layout, context)\n\n    if (!layoutResult.success) {\n      return renderError({\n        type: 'layout_error',\n        message: layoutResult.error,\n      })\n    }\n\n    // Build root node\n    const root = createRootNode(surface.id, layoutResult.nodes)\n    const nodeCount = countNodes(root)\n    const renderTime = performance.now() - startTime\n\n    const output: RenderOutput = {\n      surfaceId: surface.id,\n      root,\n      metadata: {\n        renderTime,\n        nodeCount,\n        bindings: Array.from(surface.bindings.keys()),\n      },\n    }\n\n    return renderSuccess(output)\n  }\n\n  renderLayout(layout: LayoutJSON, context: RenderContext): LayoutResult {\n    return resolveLayout(layout, context)\n  }\n}\n\n/**\n * Create a root container node\n */\nfunction createRootNode(surfaceId: SurfaceId, children: readonly RenderNode[]): RenderNode {\n  return createNode(\n    'fragment',\n    {\n      'data-surface-id': surfaceId,\n      'data-surface-root': true,\n    },\n    children\n  )\n}\n\n/**\n * Count total nodes in a tree\n */\nfunction countNodes(node: RenderNode): number {\n  let count = 1\n  for (const child of node.children) {\n    count += countNodes(child)\n  }\n  return count\n}\n\n// ============================================================\n// FACTORY\n// ============================================================\n\n/**\n * Create a new surface renderer\n */\nexport function createRenderer(): SurfaceRenderer {\n  return new DeterministicRenderer()\n}\n\n// ============================================================\n// RENDER HELPERS\n// ============================================================\n\n/**\n * Render a surface to a render tree\n */\nexport function renderSurface(surface: InterpretedSurface, options?: RenderOptions): RenderResult {\n  const renderer = createRenderer()\n  return renderer.render(surface, options)\n}\n\n/**\n * Check if a render result is successful\n */\nexport function isRenderSuccess(\n  result: RenderResult\n): result is { success: true; output: RenderOutput } {\n  return result.success\n}\n\n/**\n * Check if a render result is a failure\n */\nexport function isRenderError(\n  result: RenderResult\n): result is { success: false; error: RenderError } {\n  return !result.success\n}\n\n// ============================================================\n// SERIALIZATION\n// ============================================================\n\n/**\n * Serialize a render node to JSON\n */\nexport function serializeNode(node: RenderNode): object {\n  return {\n    type: node.type,\n    props: node.props,\n    children: node.children.map(serializeNode),\n  }\n}\n\n/**\n * Serialize render output to JSON\n */\nexport function serializeOutput(output: RenderOutput): object {\n  return {\n    surfaceId: output.surfaceId,\n    root: serializeNode(output.root),\n    metadata: output.metadata,\n  }\n}\n\n// ============================================================\n// HASH FOR DETERMINISM VERIFICATION\n// ============================================================\n\n/**\n * Compute a hash of a render node for determinism verification\n *\n * Same input should always produce same hash\n */\nexport function hashNode(node: RenderNode): string {\n  const parts: string[] = [node.type]\n\n  // Add sorted props\n  const propKeys = Object.keys(node.props).sort()\n  for (const key of propKeys) {\n    const value = node.props[key]\n    parts.push(`${key}=${JSON.stringify(value)}`)\n  }\n\n  // Add child hashes\n  for (const child of node.children) {\n    parts.push(hashNode(child))\n  }\n\n  return simpleHash(parts.join('|'))\n}\n\n/**\n * Simple string hash (djb2)\n */\nfunction simpleHash(str: string): string {\n  let hash = 5381\n  for (let i = 0; i < str.length; i++) {\n    hash = (hash * 33) ^ str.charCodeAt(i)\n  }\n  return (hash >>> 0).toString(16)\n}\n\n/**\n * Verify determinism by rendering twice and comparing hashes\n */\nexport function verifyDeterminism(\n  surface: InterpretedSurface,\n  options?: RenderOptions\n): { deterministic: boolean; hash1: string; hash2: string } {\n  const renderer = createRenderer()\n\n  const result1 = renderer.render(surface, options)\n  const result2 = renderer.render(surface, options)\n\n  if (!result1.success || !result2.success) {\n    return { deterministic: false, hash1: 'error', hash2: 'error' }\n  }\n\n  const hash1 = hashNode(result1.output.root)\n  const hash2 = hashNode(result2.output.root)\n\n  return {\n    deterministic: hash1 === hash2,\n    hash1,\n    hash2,\n  }\n}\n"]}

package/dist/surface/schemas.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Surface JSON Zod Schemas
+ *
+ * Zod validation schemas for Surface JSON definitions
+ *
+ * Provides schema-based validation to replace manual string-based
+ * validation in the interpreter. Ensures SurfaceJSON, LayoutJSON,
+ * and BindingJSON conform to their TypeScript interfaces.
+ *
+ * @module @pwfabric/runtime/surface/schemas
+ */
+import { z } from 'zod';
+import type { SurfaceJSON, LayoutJSON, BindingJSON } from './types.js';
+/**
+ * Valid environment types for surfaces
+ */
+export declare const environmentSchema: z.ZodEnum<["web", "api", "cli", "worker", "edge", "node", "native", "test"]>;
+/**
+ * Zod schema for BindingJSON
+ *
+ * Validates capability bindings in surface definitions.
+ * - capability: required string identifying the capability
+ * - alias: optional string alias for the binding
+ * - transform: optional input/output transform configuration
+ */
+export declare const bindingJsonSchema: z.ZodObject<{
+    capability: z.ZodString;
+    alias: z.ZodOptional<z.ZodString>;
+    transform: z.ZodOptional<z.ZodObject<{
+        input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        output: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        input?: Record<string, unknown> | undefined;
+        output?: Record<string, unknown> | undefined;
+    }, {
+        input?: Record<string, unknown> | undefined;
+        output?: Record<string, unknown> | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    capability: string;
+    alias?: string | undefined;
+    transform?: {
+        input?: Record<string, unknown> | undefined;
+        output?: Record<string, unknown> | undefined;
+    } | undefined;
+}, {
+    capability: string;
+    alias?: string | undefined;
+    transform?: {
+        input?: Record<string, unknown> | undefined;
+        output?: Record<string, unknown> | undefined;
+    } | undefined;
+}>;
+/**
+ * Zod schema for LayoutJSON
+ *
+ * Uses z.lazy() for recursive children validation.
+ * - type: required string identifying the layout element type
+ * - props: optional record of properties
+ * - children: optional array of nested LayoutJSON (recursive)
+ * - slot: optional named slot reference
+ * - if: optional conditional expression
+ * - each: optional loop configuration (items, as, key)
+ */
+export declare const layoutJsonSchema: z.ZodType;
+/**
+ * Zod schema for SurfaceJSON
+ *
+ * Validates the top-level surface definition structure.
+ * - id: required non-empty string
+ * - version: required non-empty string (semver)
+ * - environment: required enum of valid environment types
+ * - $schema: optional schema reference
+ * - metadata: optional name, description, tags
+ * - bindings: optional array of capability bindings
+ * - layout: required recursive layout definition
+ */
+export declare const surfaceJsonSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    version: z.ZodString;
+    environment: z.ZodEnum<["web", "api", "cli", "worker", "edge", "node", "native", "test"]>;
+    metadata: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        description?: string | undefined;
+        name?: string | undefined;
+        tags?: string[] | undefined;
+    }, {
+        description?: string | undefined;
+        name?: string | undefined;
+        tags?: string[] | undefined;
+    }>>;
+    bindings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        capability: z.ZodString;
+        alias: z.ZodOptional<z.ZodString>;
+        transform: z.ZodOptional<z.ZodObject<{
+            input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            output: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, "strip", z.ZodTypeAny, {
+            input?: Record<string, unknown> | undefined;
+            output?: Record<string, unknown> | undefined;
+        }, {
+            input?: Record<string, unknown> | undefined;
+            output?: Record<string, unknown> | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        capability: string;
+        alias?: string | undefined;
+        transform?: {
+            input?: Record<string, unknown> | undefined;
+            output?: Record<string, unknown> | undefined;
+        } | undefined;
+    }, {
+        capability: string;
+        alias?: string | undefined;
+        transform?: {
+            input?: Record<string, unknown> | undefined;
+            output?: Record<string, unknown> | undefined;
+        } | undefined;
+    }>, "many">>;
+    layout: z.ZodType<any, z.ZodTypeDef, any>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    version: string;
+    environment: "web" | "api" | "cli" | "worker" | "edge" | "node" | "native" | "test";
+    metadata?: {
+        description?: string | undefined;
+        name?: string | undefined;
+        tags?: string[] | undefined;
+    } | undefined;
+    $schema?: string | undefined;
+    bindings?: {
+        capability: string;
+        alias?: string | undefined;
+        transform?: {
+            input?: Record<string, unknown> | undefined;
+            output?: Record<string, unknown> | undefined;
+        } | undefined;
+    }[] | undefined;
+    layout?: any;
+}, {
+    id: string;
+    version: string;
+    environment: "web" | "api" | "cli" | "worker" | "edge" | "node" | "native" | "test";
+    metadata?: {
+        description?: string | undefined;
+        name?: string | undefined;
+        tags?: string[] | undefined;
+    } | undefined;
+    $schema?: string | undefined;
+    bindings?: {
+        capability: string;
+        alias?: string | undefined;
+        transform?: {
+            input?: Record<string, unknown> | undefined;
+            output?: Record<string, unknown> | undefined;
+        } | undefined;
+    }[] | undefined;
+    layout?: any;
+}>;
+/**
+ * Type guard for SurfaceJSON
+ *
+ * Returns true if the provided data conforms to the SurfaceJSON schema.
+ */
+export declare function isSurfaceJSON(data: unknown): data is SurfaceJSON;
+/**
+ * Type guard for LayoutJSON
+ *
+ * Returns true if the provided data conforms to the LayoutJSON schema.
+ */
+export declare function isLayoutJSON(data: unknown): data is LayoutJSON;
+/**
+ * Type guard for BindingJSON
+ *
+ * Returns true if the provided data conforms to the BindingJSON schema.
+ */
+export declare function isBindingJSON(data: unknown): data is BindingJSON;

package/dist/surface/schemas.js

@@ -0,0 +1,142 @@
+/**
+ * Surface JSON Zod Schemas
+ *
+ * Zod validation schemas for Surface JSON definitions
+ *
+ * Provides schema-based validation to replace manual string-based
+ * validation in the interpreter. Ensures SurfaceJSON, LayoutJSON,
+ * and BindingJSON conform to their TypeScript interfaces.
+ *
+ * @module @pwfabric/runtime/surface/schemas
+ */
+import { z } from 'zod';
+// ============================================================
+// ENVIRONMENT SCHEMA
+// ============================================================
+/**
+ * Valid environment types for surfaces
+ */
+export const environmentSchema = z.enum([
+    'web',
+    'api',
+    'cli',
+    'worker',
+    'edge',
+    'node',
+    'native',
+    'test',
+]);
+// ============================================================
+// BINDING JSON SCHEMA
+// ============================================================
+/**
+ * Zod schema for BindingJSON
+ *
+ * Validates capability bindings in surface definitions.
+ * - capability: required string identifying the capability
+ * - alias: optional string alias for the binding
+ * - transform: optional input/output transform configuration
+ */
+export const bindingJsonSchema = z.object({
+    capability: z.string().min(1, 'Binding capability must be a non-empty string'),
+    alias: z.string().optional(),
+    transform: z
+        .object({
+        input: z.record(z.unknown()).optional(),
+        output: z.record(z.unknown()).optional(),
+    })
+        .optional(),
+});
+// ============================================================
+// LAYOUT JSON SCHEMA (RECURSIVE)
+// ============================================================
+/**
+ * Zod schema for LayoutJSON
+ *
+ * Uses z.lazy() for recursive children validation.
+ * - type: required string identifying the layout element type
+ * - props: optional record of properties
+ * - children: optional array of nested LayoutJSON (recursive)
+ * - slot: optional named slot reference
+ * - if: optional conditional expression
+ * - each: optional loop configuration (items, as, key)
+ */
+// Recursive schema uses z.lazy() with a forward-declared type variable.
+// The explicit ZodType cast is required because z.lazy() needs the
+// schema variable to exist at the point of self-reference in children.
+export const layoutJsonSchema = z.lazy(() => z.object({
+    type: z.string().min(1, 'Layout must have a type'),
+    props: z.record(z.unknown()).optional(),
+    children: z.array(layoutJsonSchema).optional(),
+    slot: z.string().optional(),
+    if: z.string().optional(),
+    each: z
+        .object({
+        items: z.string().min(1, 'Loop layout must have items expression'),
+        as: z.string().min(1, 'Loop layout must have as variable name'),
+        key: z.string().optional(),
+    })
+        .optional(),
+}));
+// ============================================================
+// SURFACE JSON SCHEMA
+// ============================================================
+/**
+ * Metadata schema for surface definitions
+ */
+const metadataSchema = z
+    .object({
+    name: z.string().optional(),
+    description: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+})
+    .optional();
+/**
+ * Zod schema for SurfaceJSON
+ *
+ * Validates the top-level surface definition structure.
+ * - id: required non-empty string
+ * - version: required non-empty string (semver)
+ * - environment: required enum of valid environment types
+ * - $schema: optional schema reference
+ * - metadata: optional name, description, tags
+ * - bindings: optional array of capability bindings
+ * - layout: required recursive layout definition
+ */
+export const surfaceJsonSchema = z.object({
+    $schema: z.string().optional(),
+    id: z.string().min(1, 'Surface must have a string id'),
+    version: z.string().min(1, 'Surface must have a string version'),
+    environment: environmentSchema,
+    metadata: metadataSchema,
+    bindings: z.array(bindingJsonSchema).optional(),
+    layout: layoutJsonSchema,
+});
+// ============================================================
+// TYPE GUARDS
+// ============================================================
+/**
+ * Type guard for SurfaceJSON
+ *
+ * Returns true if the provided data conforms to the SurfaceJSON schema.
+ */
+export function isSurfaceJSON(data) {
+    return surfaceJsonSchema.safeParse(data).success;
+}
+/**
+ * Type guard for LayoutJSON
+ *
+ * Returns true if the provided data conforms to the LayoutJSON schema.
+ */
+export function isLayoutJSON(data) {
+    return layoutJsonSchema.safeParse(data).success;
+}
+/**
+ * Type guard for BindingJSON
+ *
+ * Returns true if the provided data conforms to the BindingJSON schema.
+ */
+export function isBindingJSON(data) {
+    return bindingJsonSchema.safeParse(data).success;
+}
+//# sourceMappingURL=schemas.js.map

package/dist/surface/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../src/surface/schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Surface JSON Zod Schemas\n *\n * Zod validation schemas for Surface JSON definitions\n *\n * Provides schema-based validation to replace manual string-based\n * validation in the interpreter. Ensures SurfaceJSON, LayoutJSON,\n * and BindingJSON conform to their TypeScript interfaces.\n *\n * @module @pwfabric/runtime/surface/schemas\n */\n\nimport { z } from 'zod'\nimport type { SurfaceJSON, LayoutJSON, BindingJSON } from './types.js'\n\n// ============================================================\n// ENVIRONMENT SCHEMA\n// ============================================================\n\n/**\n * Valid environment types for surfaces\n */\nexport const environmentSchema = z.enum([\n  'web',\n  'api',\n  'cli',\n  'worker',\n  'edge',\n  'node',\n  'native',\n  'test',\n])\n\n// ============================================================\n// BINDING JSON SCHEMA\n// ============================================================\n\n/**\n * Zod schema for BindingJSON\n *\n * Validates capability bindings in surface definitions.\n * - capability: required string identifying the capability\n * - alias: optional string alias for the binding\n * - transform: optional input/output transform configuration\n */\nexport const bindingJsonSchema = z.object({\n  capability: z.string().min(1, 'Binding capability must be a non-empty string'),\n  alias: z.string().optional(),\n  transform: z\n    .object({\n      input: z.record(z.unknown()).optional(),\n      output: z.record(z.unknown()).optional(),\n    })\n    .optional(),\n})\n\n// ============================================================\n// LAYOUT JSON SCHEMA (RECURSIVE)\n// ============================================================\n\n/**\n * Zod schema for LayoutJSON\n *\n * Uses z.lazy() for recursive children validation.\n * - type: required string identifying the layout element type\n * - props: optional record of properties\n * - children: optional array of nested LayoutJSON (recursive)\n * - slot: optional named slot reference\n * - if: optional conditional expression\n * - each: optional loop configuration (items, as, key)\n */\n// Recursive schema uses z.lazy() with a forward-declared type variable.\n// The explicit ZodType cast is required because z.lazy() needs the\n// schema variable to exist at the point of self-reference in children.\nexport const layoutJsonSchema: z.ZodType = z.lazy(() =>\n  z.object({\n    type: z.string().min(1, 'Layout must have a type'),\n    props: z.record(z.unknown()).optional(),\n    children: z.array(layoutJsonSchema).optional(),\n    slot: z.string().optional(),\n    if: z.string().optional(),\n    each: z\n      .object({\n        items: z.string().min(1, 'Loop layout must have items expression'),\n        as: z.string().min(1, 'Loop layout must have as variable name'),\n        key: z.string().optional(),\n      })\n      .optional(),\n  })\n)\n\n// ============================================================\n// SURFACE JSON SCHEMA\n// ============================================================\n\n/**\n * Metadata schema for surface definitions\n */\nconst metadataSchema = z\n  .object({\n    name: z.string().optional(),\n    description: z.string().optional(),\n    tags: z.array(z.string()).optional(),\n  })\n  .optional()\n\n/**\n * Zod schema for SurfaceJSON\n *\n * Validates the top-level surface definition structure.\n * - id: required non-empty string\n * - version: required non-empty string (semver)\n * - environment: required enum of valid environment types\n * - $schema: optional schema reference\n * - metadata: optional name, description, tags\n * - bindings: optional array of capability bindings\n * - layout: required recursive layout definition\n */\nexport const surfaceJsonSchema = z.object({\n  $schema: z.string().optional(),\n  id: z.string().min(1, 'Surface must have a string id'),\n  version: z.string().min(1, 'Surface must have a string version'),\n  environment: environmentSchema,\n  metadata: metadataSchema,\n  bindings: z.array(bindingJsonSchema).optional(),\n  layout: layoutJsonSchema,\n})\n\n// ============================================================\n// TYPE GUARDS\n// ============================================================\n\n/**\n * Type guard for SurfaceJSON\n *\n * Returns true if the provided data conforms to the SurfaceJSON schema.\n */\nexport function isSurfaceJSON(data: unknown): data is SurfaceJSON {\n  return surfaceJsonSchema.safeParse(data).success\n}\n\n/**\n * Type guard for LayoutJSON\n *\n * Returns true if the provided data conforms to the LayoutJSON schema.\n */\nexport function isLayoutJSON(data: unknown): data is LayoutJSON {\n  return layoutJsonSchema.safeParse(data).success\n}\n\n/**\n * Type guard for BindingJSON\n *\n * Returns true if the provided data conforms to the BindingJSON schema.\n */\nexport function isBindingJSON(data: unknown): data is BindingJSON {\n  return bindingJsonSchema.safeParse(data).success\n}\n"]}