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

package/dist/surface/index.js

@@ -0,0 +1,25 @@
+/**
+ * Surface Rendering Module
+ *
+ * Surface JSON interpreter, renderer, layout system, and primitives
+ *
+ * This module provides the complete surface rendering pipeline:
+ * - JSON interpretation and validation
+ * - Layout resolution (slots, conditionals, loops)
+ * - Deterministic rendering
+ * - Built-in primitives
+ *
+ * @module @pwfabric/runtime/surface
+ */
+export { createNode, createRenderContext, createChildContext, renderSuccess, renderError, } from './types.js';
+export { evaluate, interpolate, resolvePath, createExpressionContext, DEFAULT_HELPERS, } from './expression.js';
+export { resolveLayout, createSlotMap, extractSlots, composeLayouts, wrapInContainer, validateLayout, } from './layout.js';
+export { PRIMITIVE_DEFINITIONS, text, container, button, heading, spacer, divider, isPrimitive, getPrimitiveDefinition, } from './primitives.js';
+// Schemas
+export { surfaceJsonSchema, layoutJsonSchema, bindingJsonSchema, environmentSchema, isSurfaceJSON, isLayoutJSON, isBindingJSON, } from './schemas.js';
+export { interpretSurface, parseSurfaceJSON, SurfaceBuilder, surface, createSurfaceContext, } from './interpreter.js';
+export { DeterministicRenderer, createRenderer, renderSurface, isRenderSuccess, isRenderError, serializeNode, serializeOutput, hashNode, verifyDeterminism, } from './renderer.js';
+export { validateBlockProps, validateLayoutProps, blockManifestPropFindings, manifestPropFindings, } from './validation.js';
+export { mapTransformConfigSchema, filterTransformConfigSchema, pickTransformConfigSchema, omitTransformConfigSchema, customTransformConfigSchema, validateTransformConfig, narrowTransformDescriptor, createMapTransform, createFilterTransform, createPickTransform, createOmitTransform, createCustomTransform, } from './transforms.js';
+export { createWebOutput, createApiOutput, createCliOutput } from './output.js';
+//# sourceMappingURL=index.js.map

package/dist/surface/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/surface/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAiBH,OAAO,EACL,UAAU,EACV,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,EACb,WAAW,GACZ,MAAM,YAAY,CAAA;AAInB,OAAO,EACL,QAAQ,EACR,WAAW,EACX,WAAW,EACX,uBAAuB,EACvB,eAAe,GAChB,MAAM,iBAAiB,CAAA;AAIxB,OAAO,EACL,aAAa,EACb,aAAa,EACb,YAAY,EACZ,cAAc,EACd,eAAe,EACf,cAAc,GACf,MAAM,aAAa,CAAA;AAqBpB,OAAO,EACL,qBAAqB,EACrB,IAAI,EACJ,SAAS,EACT,MAAM,EACN,OAAO,EACP,MAAM,EACN,OAAO,EACP,WAAW,EACX,sBAAsB,GACvB,MAAM,iBAAiB,CAAA;AAExB,UAAU;AACV,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,aAAa,GACd,MAAM,cAAc,CAAA;AAQrB,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,OAAO,EACP,oBAAoB,GACrB,MAAM,kBAAkB,CAAA;AAIzB,OAAO,EACL,qBAAqB,EACrB,cAAc,EACd,aAAa,EACb,eAAe,EACf,aAAa,EACb,aAAa,EACb,eAAe,EACf,QAAQ,EACR,iBAAiB,GAClB,MAAM,eAAe,CAAA;AAYtB,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,iBAAiB,CAAA;AAYxB,OAAO,EACL,wBAAwB,EACxB,2BAA2B,EAC3B,yBAAyB,EACzB,yBAAyB,EACzB,2BAA2B,EAC3B,uBAAuB,EACvB,yBAAyB,EACzB,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,iBAAiB,CAAA;AASxB,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA","sourcesContent":["/**\n * Surface Rendering Module\n *\n * Surface JSON interpreter, renderer, layout system, and primitives\n *\n * This module provides the complete surface rendering pipeline:\n * - JSON interpretation and validation\n * - Layout resolution (slots, conditionals, loops)\n * - Deterministic rendering\n * - Built-in primitives\n *\n * @module @pwfabric/runtime/surface\n */\n\n// Types\nexport type {\n  PrimitiveType,\n  BaseNodeProps,\n  RenderNode,\n  SurfaceJSON,\n  BindingJSON,\n  LayoutJSON,\n  RenderContext,\n  RenderResult,\n  RenderOutput,\n  RenderError,\n  RenderErrorCode,\n} from './types.js'\n\nexport {\n  createNode,\n  createRenderContext,\n  createChildContext,\n  renderSuccess,\n  renderError,\n} from './types.js'\n\n// Expression evaluation\nexport type { ExpressionResult, ExpressionContext } from './expression.js'\nexport {\n  evaluate,\n  interpolate,\n  resolvePath,\n  createExpressionContext,\n  DEFAULT_HELPERS,\n} from './expression.js'\n\n// Layout system\nexport type { LayoutResult } from './layout.js'\nexport {\n  resolveLayout,\n  createSlotMap,\n  extractSlots,\n  composeLayouts,\n  wrapInContainer,\n  validateLayout,\n} from './layout.js'\n\n// Primitives\nexport type {\n  TextProps,\n  ContainerProps,\n  ButtonProps,\n  InputProps,\n  ImageProps,\n  LinkProps,\n  ListProps,\n  HeadingProps,\n  SpacerProps,\n  DividerProps,\n  SlotProps,\n  ConditionalProps,\n  LoopProps,\n  PrimitiveDefinition,\n  PropDefinition,\n} from './primitives.js'\n\nexport {\n  PRIMITIVE_DEFINITIONS,\n  text,\n  container,\n  button,\n  heading,\n  spacer,\n  divider,\n  isPrimitive,\n  getPrimitiveDefinition,\n} from './primitives.js'\n\n// Schemas\nexport {\n  surfaceJsonSchema,\n  layoutJsonSchema,\n  bindingJsonSchema,\n  environmentSchema,\n  isSurfaceJSON,\n  isLayoutJSON,\n  isBindingJSON,\n} from './schemas.js'\n\n// Interpreter\nexport type {\n  InterpretedSurface,\n  InterpretationResult,\n  InterpretSurfaceOptions,\n} from './interpreter.js'\nexport {\n  interpretSurface,\n  parseSurfaceJSON,\n  SurfaceBuilder,\n  surface,\n  createSurfaceContext,\n} from './interpreter.js'\n\n// Renderer\nexport type { RenderOptions, SurfaceRenderer } from './renderer.js'\nexport {\n  DeterministicRenderer,\n  createRenderer,\n  renderSurface,\n  isRenderSuccess,\n  isRenderError,\n  serializeNode,\n  serializeOutput,\n  hashNode,\n  verifyDeterminism,\n} from './renderer.js'\n\n// Block Props Validation\nexport type {\n  BlockPropsValidationResult,\n  BlockPropsValidationOptions,\n  LayoutPropsIssue,\n  ManifestPropSpec,\n  BlockManifestPropsMap,\n  ManifestPropFinding,\n  ManifestPropFindingCode,\n} from './validation.js'\nexport {\n  validateBlockProps,\n  validateLayoutProps,\n  blockManifestPropFindings,\n  manifestPropFindings,\n} from './validation.js'\n\n// Typed Transform Wrappers\nexport type {\n  MapTransformConfig,\n  FilterTransformConfig,\n  PickTransformConfig,\n  OmitTransformConfig,\n  CustomTransformConfig,\n  TypedTransformConfig,\n  TransformValidationResult,\n} from './transforms.js'\nexport {\n  mapTransformConfigSchema,\n  filterTransformConfigSchema,\n  pickTransformConfigSchema,\n  omitTransformConfigSchema,\n  customTransformConfigSchema,\n  validateTransformConfig,\n  narrowTransformDescriptor,\n  createMapTransform,\n  createFilterTransform,\n  createPickTransform,\n  createOmitTransform,\n  createCustomTransform,\n} from './transforms.js'\n\n// Typed Output Factories\nexport type {\n  TypedWebOutput,\n  TypedApiOutput,\n  TypedCliOutput,\n  OutputFactoryResult,\n} from './output.js'\nexport { createWebOutput, createApiOutput, createCliOutput } from './output.js'\n"]}

package/dist/surface/interpreter.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Surface JSON Interpreter
+ *
+ * Parse and validate Surface JSON definitions
+ *
+ * The interpreter converts Surface JSON into a validated Surface object
+ * that can be rendered by the renderer.
+ *
+ * @module @pwfabric/runtime/surface/interpreter
+ */
+import type { SurfaceId, CapabilityId } from '@pwfabric/contracts';
+import type { SurfaceJSON, LayoutJSON, RenderContext } from './types.js';
+import { type BlockPropsValidationOptions, type ManifestPropFinding } from './validation.js';
+import type { EnvironmentType } from '@pwfabric/contracts';
+/**
+ * Interpreted surface
+ */
+export interface InterpretedSurface {
+    readonly id: SurfaceId;
+    readonly version: string;
+    readonly environment: EnvironmentType;
+    readonly metadata: {
+        readonly name: string;
+        readonly description?: string;
+        readonly tags?: readonly string[];
+    };
+    readonly bindings: Map<string, CapabilityId>;
+    readonly layout: LayoutJSON;
+}
+/**
+ * Interpretation result
+ */
+export type InterpretationResult = {
+    readonly success: true;
+    readonly surface: InterpretedSurface;
+    /**
+     * Manifest findings when `validation.manifests` was supplied.
+     * Warnings only: the surface is interpreted all the same.
+     */
+    readonly warnings?: readonly ManifestPropFinding[];
+} | {
+    readonly success: false;
+    readonly errors: readonly string[];
+};
+/**
+ * Options for surface interpretation
+ */
+export interface InterpretSurfaceOptions {
+    /**
+     * Block props validation options.
+     * Set to false to disable prop validation entirely.
+     */
+    readonly validation?: BlockPropsValidationOptions | false;
+}
+/**
+ * Interpret a Surface JSON definition
+ */
+export declare function interpretSurface(json: SurfaceJSON, options?: InterpretSurfaceOptions): InterpretationResult;
+/**
+ * Parse Surface JSON from a string
+ */
+export declare function parseSurfaceJSON(jsonString: string): InterpretationResult;
+/**
+ * Surface builder for programmatic construction
+ */
+export declare class SurfaceBuilder {
+    private _id;
+    private _version;
+    private _environment;
+    private _metadata;
+    private _bindings;
+    private _layout;
+    private _validationOptions;
+    constructor(id: string);
+    version(v: string): this;
+    environment(env: EnvironmentType): this;
+    name(n: string): this;
+    description(d: string): this;
+    tags(...t: string[]): this;
+    bind(capability: string, alias?: string): this;
+    layout(l: LayoutJSON): this;
+    /**
+     * Configure block props validation.
+     * Pass false to disable validation entirely.
+     */
+    validation(options: BlockPropsValidationOptions | false): this;
+    build(): InterpretationResult;
+}
+/**
+ * Create a surface builder
+ */
+export declare function surface(id: string): SurfaceBuilder;
+/**
+ * Create a render context for an interpreted surface
+ */
+export declare function createSurfaceContext(surface: InterpretedSurface, data?: Record<string, unknown>): RenderContext;

package/dist/surface/interpreter.js

@@ -0,0 +1,231 @@
+/**
+ * Surface JSON Interpreter
+ *
+ * Parse and validate Surface JSON definitions
+ *
+ * The interpreter converts Surface JSON into a validated Surface object
+ * that can be rendered by the renderer.
+ *
+ * @module @pwfabric/runtime/surface/interpreter
+ */
+import { surfaceId, capabilityId, parseVersion } from '@pwfabric/contracts';
+import { createRenderContext } from './types.js';
+import { validateLayout } from './layout.js';
+import { manifestPropFindings, validateLayoutProps, } from './validation.js';
+// ============================================================
+// SCHEMA VALIDATION
+// ============================================================
+/**
+ * Validate Surface JSON structure
+ */
+function validateSurfaceJSON(json) {
+    const errors = [];
+    if (!json || typeof json !== 'object') {
+        return { valid: false, errors: ['Surface JSON must be an object'] };
+    }
+    const obj = json;
+    // Required fields
+    if (typeof obj.id !== 'string' || !obj.id) {
+        errors.push('Surface must have a string id');
+    }
+    if (typeof obj.version !== 'string' || !obj.version) {
+        errors.push('Surface must have a string version');
+    }
+    if (typeof obj.environment !== 'string' || !obj.environment) {
+        errors.push('Surface must have a string environment');
+    }
+    // Validate environment
+    const validEnvironments = ['web', 'api', 'cli', 'worker', 'edge', 'node', 'native', 'test'];
+    if (obj.environment && !validEnvironments.includes(obj.environment)) {
+        errors.push(`Invalid environment: ${obj.environment}. Must be one of: ${validEnvironments.join(', ')}`);
+    }
+    // Validate layout
+    if (!obj.layout || typeof obj.layout !== 'object') {
+        errors.push('Surface must have a layout object');
+    }
+    else {
+        const layoutResult = validateLayout(obj.layout);
+        if (!layoutResult.valid) {
+            errors.push(...layoutResult.errors.map((e) => `layout: ${e}`));
+        }
+    }
+    // Validate bindings if present
+    if (obj.bindings !== undefined) {
+        if (!Array.isArray(obj.bindings)) {
+            errors.push('bindings must be an array');
+        }
+        else {
+            for (let i = 0; i < obj.bindings.length; i++) {
+                const binding = obj.bindings[i];
+                if (typeof binding.capability !== 'string') {
+                    errors.push(`bindings[${i}]: capability must be a string`);
+                }
+            }
+        }
+    }
+    // Validate metadata if present
+    if (obj.metadata !== undefined && typeof obj.metadata !== 'object') {
+        errors.push('metadata must be an object');
+    }
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * Interpret a Surface JSON definition
+ */
+export function interpretSurface(json, options = {}) {
+    // Validate structure
+    const validation = validateSurfaceJSON(json);
+    if (!validation.valid) {
+        return { success: false, errors: validation.errors };
+    }
+    // Parse version
+    const version = parseVersion(json.version);
+    if (!version) {
+        return { success: false, errors: [`Invalid version format: ${json.version}`] };
+    }
+    // Validate block props if not disabled
+    if (options.validation !== false) {
+        const propIssues = validateLayoutProps(json.layout, options.validation ?? {});
+        if (propIssues.length > 0) {
+            const propErrors = propIssues.flatMap((issue) => issue.errors.map((e) => `${issue.path} (${issue.type}): ${e}`));
+            return { success: false, errors: propErrors };
+        }
+    }
+    // Build bindings map
+    const bindings = new Map();
+    if (json.bindings) {
+        for (const binding of json.bindings) {
+            const alias = binding.alias ?? binding.capability;
+            bindings.set(alias, capabilityId(binding.capability));
+        }
+    }
+    // Build metadata with only defined properties
+    const metadata = {
+        name: json.metadata?.name ?? json.id,
+    };
+    if (json.metadata?.description !== undefined) {
+        ;
+        metadata.description = json.metadata.description;
+    }
+    if (json.metadata?.tags !== undefined) {
+        ;
+        metadata.tags = json.metadata.tags;
+    }
+    // Build interpreted surface
+    const surface = {
+        id: surfaceId(json.id),
+        version: json.version,
+        environment: json.environment,
+        metadata,
+        bindings,
+        layout: json.layout,
+    };
+    const manifests = options.validation !== false ? options.validation?.manifests : undefined;
+    if (manifests) {
+        const warnings = manifestPropFindings(json.layout, manifests);
+        if (warnings.length > 0)
+            return { success: true, surface, warnings };
+    }
+    return { success: true, surface };
+}
+/**
+ * Parse Surface JSON from a string
+ */
+export function parseSurfaceJSON(jsonString) {
+    try {
+        const json = JSON.parse(jsonString);
+        return interpretSurface(json);
+    }
+    catch (e) {
+        return { success: false, errors: [`Invalid JSON: ${e}`] };
+    }
+}
+// ============================================================
+// SURFACE BUILDER
+// ============================================================
+/**
+ * Surface builder for programmatic construction
+ */
+export class SurfaceBuilder {
+    _id;
+    _version = '1.0.0';
+    _environment = 'web';
+    _metadata = {};
+    _bindings = [];
+    _layout = null;
+    _validationOptions = {};
+    constructor(id) {
+        this._id = id;
+    }
+    version(v) {
+        this._version = v;
+        return this;
+    }
+    environment(env) {
+        this._environment = env;
+        return this;
+    }
+    name(n) {
+        this._metadata.name = n;
+        return this;
+    }
+    description(d) {
+        this._metadata.description = d;
+        return this;
+    }
+    tags(...t) {
+        this._metadata.tags = t;
+        return this;
+    }
+    bind(capability, alias) {
+        const binding = alias ? { capability, alias } : { capability };
+        this._bindings.push(binding);
+        return this;
+    }
+    layout(l) {
+        this._layout = l;
+        return this;
+    }
+    /**
+     * Configure block props validation.
+     * Pass false to disable validation entirely.
+     */
+    validation(options) {
+        this._validationOptions = options;
+        return this;
+    }
+    build() {
+        if (!this._layout) {
+            return { success: false, errors: ['Surface must have a layout'] };
+        }
+        const json = {
+            id: this._id,
+            version: this._version,
+            environment: this._environment,
+            metadata: this._metadata,
+            bindings: this._bindings,
+            layout: this._layout,
+        };
+        return interpretSurface(json, { validation: this._validationOptions });
+    }
+}
+/**
+ * Create a surface builder
+ */
+export function surface(id) {
+    return new SurfaceBuilder(id);
+}
+// ============================================================
+// RENDER CONTEXT CREATION
+// ============================================================
+/**
+ * Create a render context for an interpreted surface
+ */
+export function createSurfaceContext(surface, data) {
+    return createRenderContext({
+        surfaceId: surface.id,
+        bindings: surface.bindings,
+        data: data ?? {},
+    });
+}
+//# sourceMappingURL=interpreter.js.map

package/dist/surface/interpreter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interpreter.js","sourceRoot":"","sources":["../../src/surface/interpreter.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Surface JSON Interpreter\n *\n * Parse and validate Surface JSON definitions\n *\n * The interpreter converts Surface JSON into a validated Surface object\n * that can be rendered by the renderer.\n *\n * @module @pwfabric/runtime/surface/interpreter\n */\n\nimport type { SurfaceId, CapabilityId } from '@pwfabric/contracts'\nimport { surfaceId, capabilityId, parseVersion } from '@pwfabric/contracts'\nimport type { SurfaceJSON, LayoutJSON, BindingJSON, RenderContext } from './types.js'\nimport { createRenderContext } from './types.js'\nimport { validateLayout } from './layout.js'\nimport {\n  manifestPropFindings,\n  validateLayoutProps,\n  type BlockPropsValidationOptions,\n  type ManifestPropFinding,\n} from './validation.js'\nimport type { EnvironmentType } from '@pwfabric/contracts'\n\n// ============================================================\n// INTERPRETATION TYPES\n// ============================================================\n\n/**\n * Interpreted surface\n */\nexport interface InterpretedSurface {\n  readonly id: SurfaceId\n  readonly version: string\n  readonly environment: EnvironmentType\n  readonly metadata: {\n    readonly name: string\n    readonly description?: string\n    readonly tags?: readonly string[]\n  }\n  readonly bindings: Map<string, CapabilityId>\n  readonly layout: LayoutJSON\n}\n\n/**\n * Interpretation result\n */\nexport type InterpretationResult =\n  | {\n      readonly success: true\n      readonly surface: InterpretedSurface\n      /**\n       * Manifest findings when `validation.manifests` was supplied.\n       * Warnings only: the surface is interpreted all the same.\n       */\n      readonly warnings?: readonly ManifestPropFinding[]\n    }\n  | { readonly success: false; readonly errors: readonly string[] }\n\n// ============================================================\n// SCHEMA VALIDATION\n// ============================================================\n\n/**\n * Validate Surface JSON structure\n */\nfunction validateSurfaceJSON(json: unknown): { valid: boolean; errors: string[] } {\n  const errors: string[] = []\n\n  if (!json || typeof json !== 'object') {\n    return { valid: false, errors: ['Surface JSON must be an object'] }\n  }\n\n  const obj = json as Record<string, unknown>\n\n  // Required fields\n  if (typeof obj.id !== 'string' || !obj.id) {\n    errors.push('Surface must have a string id')\n  }\n\n  if (typeof obj.version !== 'string' || !obj.version) {\n    errors.push('Surface must have a string version')\n  }\n\n  if (typeof obj.environment !== 'string' || !obj.environment) {\n    errors.push('Surface must have a string environment')\n  }\n\n  // Validate environment\n  const validEnvironments = ['web', 'api', 'cli', 'worker', 'edge', 'node', 'native', 'test']\n  if (obj.environment && !validEnvironments.includes(obj.environment as string)) {\n    errors.push(\n      `Invalid environment: ${obj.environment}. Must be one of: ${validEnvironments.join(', ')}`\n    )\n  }\n\n  // Validate layout\n  if (!obj.layout || typeof obj.layout !== 'object') {\n    errors.push('Surface must have a layout object')\n  } else {\n    const layoutResult = validateLayout(obj.layout as LayoutJSON)\n    if (!layoutResult.valid) {\n      errors.push(...layoutResult.errors.map((e) => `layout: ${e}`))\n    }\n  }\n\n  // Validate bindings if present\n  if (obj.bindings !== undefined) {\n    if (!Array.isArray(obj.bindings)) {\n      errors.push('bindings must be an array')\n    } else {\n      for (let i = 0; i < obj.bindings.length; i++) {\n        const binding = obj.bindings[i] as Record<string, unknown>\n        if (typeof binding.capability !== 'string') {\n          errors.push(`bindings[${i}]: capability must be a string`)\n        }\n      }\n    }\n  }\n\n  // Validate metadata if present\n  if (obj.metadata !== undefined && typeof obj.metadata !== 'object') {\n    errors.push('metadata must be an object')\n  }\n\n  return { valid: errors.length === 0, errors }\n}\n\n// ============================================================\n// INTERPRETER\n// ============================================================\n\n/**\n * Options for surface interpretation\n */\nexport interface InterpretSurfaceOptions {\n  /**\n   * Block props validation options.\n   * Set to false to disable prop validation entirely.\n   */\n  readonly validation?: BlockPropsValidationOptions | false\n}\n\n/**\n * Interpret a Surface JSON definition\n */\nexport function interpretSurface(\n  json: SurfaceJSON,\n  options: InterpretSurfaceOptions = {}\n): InterpretationResult {\n  // Validate structure\n  const validation = validateSurfaceJSON(json)\n  if (!validation.valid) {\n    return { success: false, errors: validation.errors }\n  }\n\n  // Parse version\n  const version = parseVersion(json.version)\n  if (!version) {\n    return { success: false, errors: [`Invalid version format: ${json.version}`] }\n  }\n\n  // Validate block props if not disabled\n  if (options.validation !== false) {\n    const propIssues = validateLayoutProps(json.layout, options.validation ?? {})\n    if (propIssues.length > 0) {\n      const propErrors = propIssues.flatMap((issue) =>\n        issue.errors.map((e) => `${issue.path} (${issue.type}): ${e}`)\n      )\n      return { success: false, errors: propErrors }\n    }\n  }\n\n  // Build bindings map\n  const bindings = new Map<string, CapabilityId>()\n  if (json.bindings) {\n    for (const binding of json.bindings) {\n      const alias = binding.alias ?? binding.capability\n      bindings.set(alias, capabilityId(binding.capability))\n    }\n  }\n\n  // Build metadata with only defined properties\n  const metadata: InterpretedSurface['metadata'] = {\n    name: json.metadata?.name ?? json.id,\n  }\n  if (json.metadata?.description !== undefined) {\n    ;(metadata as { description?: string }).description = json.metadata.description\n  }\n  if (json.metadata?.tags !== undefined) {\n    ;(metadata as { tags?: readonly string[] }).tags = json.metadata.tags\n  }\n\n  // Build interpreted surface\n  const surface: InterpretedSurface = {\n    id: surfaceId(json.id),\n    version: json.version,\n    environment: json.environment as EnvironmentType,\n    metadata,\n    bindings,\n    layout: json.layout,\n  }\n\n  const manifests = options.validation !== false ? options.validation?.manifests : undefined\n  if (manifests) {\n    const warnings = manifestPropFindings(json.layout, manifests)\n    if (warnings.length > 0) return { success: true, surface, warnings }\n  }\n  return { success: true, surface }\n}\n\n/**\n * Parse Surface JSON from a string\n */\nexport function parseSurfaceJSON(jsonString: string): InterpretationResult {\n  try {\n    const json = JSON.parse(jsonString) as SurfaceJSON\n    return interpretSurface(json)\n  } catch (e) {\n    return { success: false, errors: [`Invalid JSON: ${e}`] }\n  }\n}\n\n// ============================================================\n// SURFACE BUILDER\n// ============================================================\n\n/**\n * Surface builder for programmatic construction\n */\nexport class SurfaceBuilder {\n  private _id: string\n  private _version = '1.0.0'\n  private _environment: EnvironmentType = 'web'\n  private _metadata: { name?: string; description?: string; tags?: string[] } = {}\n  private _bindings: BindingJSON[] = []\n  private _layout: LayoutJSON | null = null\n  private _validationOptions: BlockPropsValidationOptions | false = {}\n\n  constructor(id: string) {\n    this._id = id\n  }\n\n  version(v: string): this {\n    this._version = v\n    return this\n  }\n\n  environment(env: EnvironmentType): this {\n    this._environment = env\n    return this\n  }\n\n  name(n: string): this {\n    this._metadata.name = n\n    return this\n  }\n\n  description(d: string): this {\n    this._metadata.description = d\n    return this\n  }\n\n  tags(...t: string[]): this {\n    this._metadata.tags = t\n    return this\n  }\n\n  bind(capability: string, alias?: string): this {\n    const binding: BindingJSON = alias ? { capability, alias } : { capability }\n    this._bindings.push(binding)\n    return this\n  }\n\n  layout(l: LayoutJSON): this {\n    this._layout = l\n    return this\n  }\n\n  /**\n   * Configure block props validation.\n   * Pass false to disable validation entirely.\n   */\n  validation(options: BlockPropsValidationOptions | false): this {\n    this._validationOptions = options\n    return this\n  }\n\n  build(): InterpretationResult {\n    if (!this._layout) {\n      return { success: false, errors: ['Surface must have a layout'] }\n    }\n\n    const json: SurfaceJSON = {\n      id: this._id,\n      version: this._version,\n      environment: this._environment,\n      metadata: this._metadata,\n      bindings: this._bindings,\n      layout: this._layout,\n    }\n\n    return interpretSurface(json, { validation: this._validationOptions })\n  }\n}\n\n/**\n * Create a surface builder\n */\nexport function surface(id: string): SurfaceBuilder {\n  return new SurfaceBuilder(id)\n}\n\n// ============================================================\n// RENDER CONTEXT CREATION\n// ============================================================\n\n/**\n * Create a render context for an interpreted surface\n */\nexport function createSurfaceContext(\n  surface: InterpretedSurface,\n  data?: Record<string, unknown>\n): RenderContext {\n  return createRenderContext({\n    surfaceId: surface.id,\n    bindings: surface.bindings,\n    data: data ?? {},\n  })\n}\n"]}

package/dist/surface/layout.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Layout System
+ *
+ * Slot and layout resolution for surfaces
+ *
+ * The layout system handles:
+ * - Slot resolution (named slots with fallback content)
+ * - Layout composition (nesting surfaces)
+ * - Conditional rendering
+ * - Loop expansion
+ *
+ * @module @pwfabric/runtime/surface/layout
+ */
+import type { RenderNode, RenderContext, LayoutJSON } from './types.js';
+/**
+ * Layout resolution result
+ */
+export type LayoutResult = {
+    readonly success: true;
+    readonly nodes: readonly RenderNode[];
+} | {
+    readonly success: false;
+    readonly error: string;
+};
+/**
+ * Resolve a layout definition into render nodes
+ */
+export declare function resolveLayout(layout: LayoutJSON, context: RenderContext): LayoutResult;
+/**
+ * Create a slot map from slot content
+ */
+export declare function createSlotMap(slots: Record<string, readonly RenderNode[]>): Map<string, readonly RenderNode[]>;
+/**
+ * Extract slots from children based on slot attribute
+ */
+export declare function extractSlots(children: readonly RenderNode[]): {
+    default: readonly RenderNode[];
+    named: Map<string, readonly RenderNode[]>;
+};
+/**
+ * Compose multiple layouts into one
+ */
+export declare function composeLayouts(layouts: readonly LayoutJSON[], context: RenderContext): LayoutResult;
+/**
+ * Wrap nodes in a container
+ */
+export declare function wrapInContainer(nodes: readonly RenderNode[], props?: Record<string, unknown>): RenderNode;
+/**
+ * Validate a layout definition
+ */
+export declare function validateLayout(layout: LayoutJSON): {
+    valid: boolean;
+    errors: string[];
+};