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

package/dist/surface/transforms.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Typed Transform Wrappers
+ *
+ * Typed runtime wrappers for TransformDescriptor.config.
+ * These do NOT modify @pwfabric/contracts. They provide typed alternatives
+ * that narrow the opaque Record<string, unknown> config.
+ *
+ * @module @pwfabric/runtime/surface/transforms
+ */
+import { z } from 'zod';
+import type { TransformDescriptor } from '@pwfabric/contracts';
+/**
+ * Config for 'map' transforms
+ */
+export interface MapTransformConfig {
+    readonly field: string;
+    readonly mapper: string;
+}
+/**
+ * Config for 'filter' transforms
+ */
+export interface FilterTransformConfig {
+    readonly field: string;
+    readonly predicate: string;
+}
+/**
+ * Config for 'pick' transforms
+ */
+export interface PickTransformConfig {
+    readonly fields: readonly string[];
+}
+/**
+ * Config for 'omit' transforms
+ */
+export interface OmitTransformConfig {
+    readonly fields: readonly string[];
+}
+/**
+ * Config for 'custom' transforms
+ */
+export interface CustomTransformConfig {
+    readonly handler: string;
+    readonly params?: Record<string, unknown>;
+}
+/**
+ * Discriminated union of all typed transform configs
+ */
+export type TypedTransformConfig = {
+    readonly type: 'map';
+    readonly config: MapTransformConfig;
+} | {
+    readonly type: 'filter';
+    readonly config: FilterTransformConfig;
+} | {
+    readonly type: 'pick';
+    readonly config: PickTransformConfig;
+} | {
+    readonly type: 'omit';
+    readonly config: OmitTransformConfig;
+} | {
+    readonly type: 'custom';
+    readonly config: CustomTransformConfig;
+};
+export declare const mapTransformConfigSchema: z.ZodObject<{
+    field: z.ZodString;
+    mapper: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    field: string;
+    mapper: string;
+}, {
+    field: string;
+    mapper: string;
+}>;
+export declare const filterTransformConfigSchema: z.ZodObject<{
+    field: z.ZodString;
+    predicate: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    field: string;
+    predicate: string;
+}, {
+    field: string;
+    predicate: string;
+}>;
+export declare const pickTransformConfigSchema: z.ZodObject<{
+    fields: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    fields: string[];
+}, {
+    fields: string[];
+}>;
+export declare const omitTransformConfigSchema: z.ZodObject<{
+    fields: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    fields: string[];
+}, {
+    fields: string[];
+}>;
+export declare const customTransformConfigSchema: z.ZodObject<{
+    handler: z.ZodString;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    handler: string;
+    params?: Record<string, unknown> | undefined;
+}, {
+    handler: string;
+    params?: Record<string, unknown> | undefined;
+}>;
+/**
+ * Result of validating a transform config
+ */
+export interface TransformValidationResult {
+    readonly valid: boolean;
+    readonly errors: readonly string[];
+}
+/**
+ * Validate a transform descriptor's config against the typed schema
+ * for the given transform type.
+ */
+export declare function validateTransformConfig(type: TransformDescriptor['type'], config: Record<string, unknown>): TransformValidationResult;
+/**
+ * Type guard that narrows an opaque TransformDescriptor into
+ * a TypedTransformConfig if the config passes validation.
+ */
+export declare function narrowTransformDescriptor(descriptor: TransformDescriptor): TypedTransformConfig | null;
+/**
+ * Create a typed 'map' transform descriptor
+ */
+export declare function createMapTransform(config: MapTransformConfig): TransformDescriptor;
+/**
+ * Create a typed 'filter' transform descriptor
+ */
+export declare function createFilterTransform(config: FilterTransformConfig): TransformDescriptor;
+/**
+ * Create a typed 'pick' transform descriptor
+ */
+export declare function createPickTransform(config: PickTransformConfig): TransformDescriptor;
+/**
+ * Create a typed 'omit' transform descriptor
+ */
+export declare function createOmitTransform(config: OmitTransformConfig): TransformDescriptor;
+/**
+ * Create a typed 'custom' transform descriptor
+ */
+export declare function createCustomTransform(config: CustomTransformConfig): TransformDescriptor;

package/dist/surface/transforms.js

@@ -0,0 +1,120 @@
+/**
+ * Typed Transform Wrappers
+ *
+ * Typed runtime wrappers for TransformDescriptor.config.
+ * These do NOT modify @pwfabric/contracts. They provide typed alternatives
+ * that narrow the opaque Record<string, unknown> config.
+ *
+ * @module @pwfabric/runtime/surface/transforms
+ */
+import { z } from 'zod';
+// ============================================================
+// ZOD SCHEMAS
+// ============================================================
+export const mapTransformConfigSchema = z.object({
+    field: z.string().min(1),
+    mapper: z.string().min(1),
+});
+export const filterTransformConfigSchema = z.object({
+    field: z.string().min(1),
+    predicate: z.string().min(1),
+});
+export const pickTransformConfigSchema = z.object({
+    fields: z.array(z.string().min(1)).min(1),
+});
+export const omitTransformConfigSchema = z.object({
+    fields: z.array(z.string().min(1)).min(1),
+});
+export const customTransformConfigSchema = z.object({
+    handler: z.string().min(1),
+    params: z.record(z.unknown()).optional(),
+});
+/**
+ * Map of transform types to their Zod schemas
+ */
+const transformConfigSchemas = {
+    map: mapTransformConfigSchema,
+    filter: filterTransformConfigSchema,
+    pick: pickTransformConfigSchema,
+    omit: omitTransformConfigSchema,
+    custom: customTransformConfigSchema,
+};
+// ============================================================
+// VALIDATION FUNCTION
+// ============================================================
+/**
+ * Validate a transform descriptor's config against the typed schema
+ * for the given transform type.
+ */
+export function validateTransformConfig(type, config) {
+    const schema = transformConfigSchemas[type];
+    const result = schema.safeParse(config);
+    if (result.success) {
+        return { valid: true, errors: [] };
+    }
+    return {
+        valid: false,
+        errors: result.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`),
+    };
+}
+// ============================================================
+// TYPE GUARD
+// ============================================================
+/**
+ * Type guard that narrows an opaque TransformDescriptor into
+ * a TypedTransformConfig if the config passes validation.
+ */
+export function narrowTransformDescriptor(descriptor) {
+    if (!descriptor.config) {
+        return null;
+    }
+    const schema = transformConfigSchemas[descriptor.type];
+    const result = schema.safeParse(descriptor.config);
+    if (!result.success) {
+        return null;
+    }
+    // The type assertion is safe because Zod validated the config shape
+    return {
+        type: descriptor.type,
+        config: result.data,
+    };
+}
+// ============================================================
+// FACTORY FUNCTIONS
+// ============================================================
+/**
+ * Create a typed 'map' transform descriptor
+ */
+export function createMapTransform(config) {
+    const parsed = mapTransformConfigSchema.parse(config);
+    return { type: 'map', config: parsed };
+}
+/**
+ * Create a typed 'filter' transform descriptor
+ */
+export function createFilterTransform(config) {
+    const parsed = filterTransformConfigSchema.parse(config);
+    return { type: 'filter', config: parsed };
+}
+/**
+ * Create a typed 'pick' transform descriptor
+ */
+export function createPickTransform(config) {
+    const parsed = pickTransformConfigSchema.parse(config);
+    return { type: 'pick', config: { ...parsed, fields: [...parsed.fields] } };
+}
+/**
+ * Create a typed 'omit' transform descriptor
+ */
+export function createOmitTransform(config) {
+    const parsed = omitTransformConfigSchema.parse(config);
+    return { type: 'omit', config: { ...parsed, fields: [...parsed.fields] } };
+}
+/**
+ * Create a typed 'custom' transform descriptor
+ */
+export function createCustomTransform(config) {
+    const parsed = customTransformConfigSchema.parse(config);
+    return { type: 'custom', config: parsed };
+}
+//# sourceMappingURL=transforms.js.map

package/dist/surface/transforms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transforms.js","sourceRoot":"","sources":["../../src/surface/transforms.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Typed Transform Wrappers\n *\n * Typed runtime wrappers for TransformDescriptor.config.\n * These do NOT modify @pwfabric/contracts. They provide typed alternatives\n * that narrow the opaque Record<string, unknown> config.\n *\n * @module @pwfabric/runtime/surface/transforms\n */\n\nimport { z } from 'zod'\nimport type { TransformDescriptor } from '@pwfabric/contracts'\n\n// ============================================================\n// TYPED TRANSFORM CONFIG INTERFACES\n// ============================================================\n\n/**\n * Config for 'map' transforms\n */\nexport interface MapTransformConfig {\n  readonly field: string\n  readonly mapper: string\n}\n\n/**\n * Config for 'filter' transforms\n */\nexport interface FilterTransformConfig {\n  readonly field: string\n  readonly predicate: string\n}\n\n/**\n * Config for 'pick' transforms\n */\nexport interface PickTransformConfig {\n  readonly fields: readonly string[]\n}\n\n/**\n * Config for 'omit' transforms\n */\nexport interface OmitTransformConfig {\n  readonly fields: readonly string[]\n}\n\n/**\n * Config for 'custom' transforms\n */\nexport interface CustomTransformConfig {\n  readonly handler: string\n  readonly params?: Record<string, unknown>\n}\n\n/**\n * Discriminated union of all typed transform configs\n */\nexport type TypedTransformConfig =\n  | { readonly type: 'map'; readonly config: MapTransformConfig }\n  | { readonly type: 'filter'; readonly config: FilterTransformConfig }\n  | { readonly type: 'pick'; readonly config: PickTransformConfig }\n  | { readonly type: 'omit'; readonly config: OmitTransformConfig }\n  | { readonly type: 'custom'; readonly config: CustomTransformConfig }\n\n// ============================================================\n// ZOD SCHEMAS\n// ============================================================\n\nexport const mapTransformConfigSchema = z.object({\n  field: z.string().min(1),\n  mapper: z.string().min(1),\n})\n\nexport const filterTransformConfigSchema = z.object({\n  field: z.string().min(1),\n  predicate: z.string().min(1),\n})\n\nexport const pickTransformConfigSchema = z.object({\n  fields: z.array(z.string().min(1)).min(1),\n})\n\nexport const omitTransformConfigSchema = z.object({\n  fields: z.array(z.string().min(1)).min(1),\n})\n\nexport const customTransformConfigSchema = z.object({\n  handler: z.string().min(1),\n  params: z.record(z.unknown()).optional(),\n})\n\n/**\n * Map of transform types to their Zod schemas\n */\nconst transformConfigSchemas = {\n  map: mapTransformConfigSchema,\n  filter: filterTransformConfigSchema,\n  pick: pickTransformConfigSchema,\n  omit: omitTransformConfigSchema,\n  custom: customTransformConfigSchema,\n} as const\n\n// ============================================================\n// VALIDATION TYPES\n// ============================================================\n\n/**\n * Result of validating a transform config\n */\nexport interface TransformValidationResult {\n  readonly valid: boolean\n  readonly errors: readonly string[]\n}\n\n// ============================================================\n// VALIDATION FUNCTION\n// ============================================================\n\n/**\n * Validate a transform descriptor's config against the typed schema\n * for the given transform type.\n */\nexport function validateTransformConfig(\n  type: TransformDescriptor['type'],\n  config: Record<string, unknown>\n): TransformValidationResult {\n  const schema = transformConfigSchemas[type]\n\n  const result = schema.safeParse(config)\n\n  if (result.success) {\n    return { valid: true, errors: [] }\n  }\n\n  return {\n    valid: false,\n    errors: result.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`),\n  }\n}\n\n// ============================================================\n// TYPE GUARD\n// ============================================================\n\n/**\n * Type guard that narrows an opaque TransformDescriptor into\n * a TypedTransformConfig if the config passes validation.\n */\nexport function narrowTransformDescriptor(\n  descriptor: TransformDescriptor\n): TypedTransformConfig | null {\n  if (!descriptor.config) {\n    return null\n  }\n\n  const schema = transformConfigSchemas[descriptor.type]\n  const result = schema.safeParse(descriptor.config)\n\n  if (!result.success) {\n    return null\n  }\n\n  // The type assertion is safe because Zod validated the config shape\n  return {\n    type: descriptor.type,\n    config: result.data,\n  } as TypedTransformConfig\n}\n\n// ============================================================\n// FACTORY FUNCTIONS\n// ============================================================\n\n/**\n * Create a typed 'map' transform descriptor\n */\nexport function createMapTransform(config: MapTransformConfig): TransformDescriptor {\n  const parsed = mapTransformConfigSchema.parse(config)\n  return { type: 'map', config: parsed }\n}\n\n/**\n * Create a typed 'filter' transform descriptor\n */\nexport function createFilterTransform(config: FilterTransformConfig): TransformDescriptor {\n  const parsed = filterTransformConfigSchema.parse(config)\n  return { type: 'filter', config: parsed }\n}\n\n/**\n * Create a typed 'pick' transform descriptor\n */\nexport function createPickTransform(config: PickTransformConfig): TransformDescriptor {\n  const parsed = pickTransformConfigSchema.parse(config)\n  return { type: 'pick', config: { ...parsed, fields: [...parsed.fields] } }\n}\n\n/**\n * Create a typed 'omit' transform descriptor\n */\nexport function createOmitTransform(config: OmitTransformConfig): TransformDescriptor {\n  const parsed = omitTransformConfigSchema.parse(config)\n  return { type: 'omit', config: { ...parsed, fields: [...parsed.fields] } }\n}\n\n/**\n * Create a typed 'custom' transform descriptor\n */\nexport function createCustomTransform(config: CustomTransformConfig): TransformDescriptor {\n  const parsed = customTransformConfigSchema.parse(config)\n  return { type: 'custom', config: parsed }\n}\n"]}

package/dist/surface/types.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Surface Rendering Types
+ *
+ * Internal types for surface rendering pipeline
+ *
+ * @module @pwfabric/runtime/surface/types
+ */
+import type { CapabilityId, SurfaceId } from '@pwfabric/contracts';
+/**
+ * Primitive types supported by the runtime
+ */
+export type PrimitiveType = 'text' | 'container' | 'button' | 'input' | 'image' | 'link' | 'list' | 'list-item' | 'divider' | 'spacer' | 'heading' | 'paragraph' | 'slot' | 'fragment' | 'conditional' | 'loop';
+/**
+ * Base properties shared by all render nodes
+ */
+export interface BaseNodeProps {
+    readonly id?: string;
+    readonly key?: string;
+    readonly className?: string;
+    readonly style?: Record<string, string | number>;
+    readonly data?: Record<string, unknown>;
+}
+/**
+ * Render node - the output of surface rendering
+ */
+export interface RenderNode {
+    readonly type: PrimitiveType | string;
+    readonly props: BaseNodeProps & Record<string, unknown>;
+    readonly children: readonly RenderNode[];
+}
+/**
+ * Create a render node
+ */
+export declare function createNode(type: PrimitiveType | string, props?: BaseNodeProps & Record<string, unknown>, children?: readonly RenderNode[]): RenderNode;
+/**
+ * Surface JSON definition (input format)
+ */
+export interface SurfaceJSON {
+    readonly $schema?: string;
+    readonly id: string;
+    readonly version: string;
+    readonly environment: string;
+    readonly metadata?: {
+        readonly name?: string;
+        readonly description?: string;
+        readonly tags?: readonly string[];
+    };
+    readonly bindings?: readonly BindingJSON[];
+    readonly layout: LayoutJSON;
+}
+/**
+ * Capability binding in JSON
+ */
+export interface BindingJSON {
+    readonly capability: string;
+    readonly alias?: string;
+    readonly transform?: {
+        readonly input?: Record<string, unknown>;
+        readonly output?: Record<string, unknown>;
+    };
+}
+/**
+ * Layout definition in JSON
+ */
+export interface LayoutJSON {
+    readonly type: PrimitiveType | string;
+    readonly props?: Record<string, unknown>;
+    readonly children?: readonly LayoutJSON[];
+    readonly slot?: string;
+    readonly if?: string;
+    readonly each?: {
+        readonly items: string;
+        readonly as: string;
+        readonly key?: string;
+    };
+}
+/**
+ * Context passed during rendering
+ */
+export interface RenderContext {
+    readonly surfaceId: SurfaceId;
+    readonly bindings: Map<string, CapabilityId>;
+    readonly data: Record<string, unknown>;
+    readonly slots: Map<string, readonly RenderNode[]>;
+    readonly parent?: RenderContext;
+}
+/**
+ * Create a render context
+ */
+export declare function createRenderContext(options: {
+    surfaceId: SurfaceId;
+    bindings?: Map<string, CapabilityId>;
+    data?: Record<string, unknown>;
+    slots?: Map<string, readonly RenderNode[]>;
+    parent?: RenderContext;
+}): RenderContext;
+/**
+ * Create a child context with additional data
+ */
+export declare function createChildContext(parent: RenderContext, additionalData: Record<string, unknown>): RenderContext;
+/**
+ * Result of rendering a surface
+ */
+export type RenderResult = {
+    readonly success: true;
+    readonly output: RenderOutput;
+} | {
+    readonly success: false;
+    readonly error: RenderError;
+};
+/**
+ * Render output
+ */
+export interface RenderOutput {
+    readonly surfaceId: SurfaceId;
+    readonly root: RenderNode;
+    readonly metadata: {
+        readonly renderTime: number;
+        readonly nodeCount: number;
+        readonly bindings: readonly string[];
+    };
+}
+/**
+ * Formalized error code vocabulary for render errors
+ */
+export type RenderErrorCode = 'invalid_surface' | 'missing_binding' | 'layout_error' | 'slot_error' | 'expression_error';
+/**
+ * Render error types
+ */
+export type RenderError = {
+    readonly type: 'invalid_surface';
+    readonly message: string;
+    readonly details?: Record<string, unknown>;
+} | {
+    readonly type: 'missing_binding';
+    readonly binding: string;
+    readonly details?: Record<string, unknown>;
+} | {
+    readonly type: 'layout_error';
+    readonly message: string;
+    readonly details?: Record<string, unknown>;
+} | {
+    readonly type: 'slot_error';
+    readonly slot: string;
+    readonly message: string;
+    readonly details?: Record<string, unknown>;
+} | {
+    readonly type: 'expression_error';
+    readonly expression: string;
+    readonly message: string;
+    readonly details?: Record<string, unknown>;
+};
+/**
+ * Create a successful render result
+ */
+export declare function renderSuccess(output: RenderOutput): RenderResult;
+/**
+ * Create a failed render result
+ */
+export declare function renderError(error: RenderError): RenderResult;

package/dist/surface/types.js

@@ -0,0 +1,51 @@
+/**
+ * Surface Rendering Types
+ *
+ * Internal types for surface rendering pipeline
+ *
+ * @module @pwfabric/runtime/surface/types
+ */
+/**
+ * Create a render node
+ */
+export function createNode(type, props = {}, children = []) {
+    return { type, props, children };
+}
+/**
+ * Create a render context
+ */
+export function createRenderContext(options) {
+    const result = {
+        surfaceId: options.surfaceId,
+        bindings: options.bindings ?? new Map(),
+        data: options.data ?? {},
+        slots: options.slots ?? new Map(),
+    };
+    if (options.parent) {
+        return { ...result, parent: options.parent };
+    }
+    return result;
+}
+/**
+ * Create a child context with additional data
+ */
+export function createChildContext(parent, additionalData) {
+    return {
+        ...parent,
+        data: { ...parent.data, ...additionalData },
+        parent,
+    };
+}
+/**
+ * Create a successful render result
+ */
+export function renderSuccess(output) {
+    return { success: true, output };
+}
+/**
+ * Create a failed render result
+ */
+export function renderError(error) {
+    return { success: false, error };
+}
+//# sourceMappingURL=types.js.map

package/dist/surface/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/surface/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAiDH;;GAEG;AACH,MAAM,UAAU,UAAU,CACxB,IAA4B,EAC5B,QAAiD,EAAE,EACnD,WAAkC,EAAE;IAEpC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAA;AAClC,CAAC;AAkED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAMnC;IACC,MAAM,MAAM,GAAkB;QAC5B,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,IAAI,GAAG,EAAE;QACvC,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,EAAE;QACxB,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,IAAI,GAAG,EAAE;KAClC,CAAA;IACD,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,OAAO,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAA;IAC9C,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAqB,EACrB,cAAuC;IAEvC,OAAO;QACL,GAAG,MAAM;QACT,IAAI,EAAE,EAAE,GAAG,MAAM,CAAC,IAAI,EAAE,GAAG,cAAc,EAAE;QAC3C,MAAM;KACP,CAAA;AACH,CAAC;AAoED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,MAAoB;IAChD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAA;AAClC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,KAAkB;IAC5C,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAA;AAClC,CAAC","sourcesContent":["/**\n * Surface Rendering Types\n *\n * Internal types for surface rendering pipeline\n *\n * @module @pwfabric/runtime/surface/types\n */\n\nimport type { CapabilityId, SurfaceId } from '@pwfabric/contracts'\n\n// ============================================================\n// RENDER NODE TYPES\n// ============================================================\n\n/**\n * Primitive types supported by the runtime\n */\nexport type PrimitiveType =\n  | 'text'\n  | 'container'\n  | 'button'\n  | 'input'\n  | 'image'\n  | 'link'\n  | 'list'\n  | 'list-item'\n  | 'divider'\n  | 'spacer'\n  | 'heading'\n  | 'paragraph'\n  | 'slot'\n  | 'fragment'\n  | 'conditional'\n  | 'loop'\n\n/**\n * Base properties shared by all render nodes\n */\nexport interface BaseNodeProps {\n  readonly id?: string\n  readonly key?: string\n  readonly className?: string\n  readonly style?: Record<string, string | number>\n  readonly data?: Record<string, unknown>\n}\n\n/**\n * Render node - the output of surface rendering\n */\nexport interface RenderNode {\n  readonly type: PrimitiveType | string\n  readonly props: BaseNodeProps & Record<string, unknown>\n  readonly children: readonly RenderNode[]\n}\n\n/**\n * Create a render node\n */\nexport function createNode(\n  type: PrimitiveType | string,\n  props: BaseNodeProps & Record<string, unknown> = {},\n  children: readonly RenderNode[] = []\n): RenderNode {\n  return { type, props, children }\n}\n\n// ============================================================\n// SURFACE JSON SCHEMA\n// ============================================================\n\n/**\n * Surface JSON definition (input format)\n */\nexport interface SurfaceJSON {\n  readonly $schema?: string\n  readonly id: string\n  readonly version: string\n  readonly environment: string\n  readonly metadata?: {\n    readonly name?: string\n    readonly description?: string\n    readonly tags?: readonly string[]\n  }\n  readonly bindings?: readonly BindingJSON[]\n  readonly layout: LayoutJSON\n}\n\n/**\n * Capability binding in JSON\n */\nexport interface BindingJSON {\n  readonly capability: string\n  readonly alias?: string\n  readonly transform?: {\n    readonly input?: Record<string, unknown>\n    readonly output?: Record<string, unknown>\n  }\n}\n\n/**\n * Layout definition in JSON\n */\nexport interface LayoutJSON {\n  readonly type: PrimitiveType | string\n  readonly props?: Record<string, unknown>\n  readonly children?: readonly LayoutJSON[]\n  readonly slot?: string\n  readonly if?: string\n  readonly each?: {\n    readonly items: string\n    readonly as: string\n    readonly key?: string\n  }\n}\n\n// ============================================================\n// RENDER CONTEXT\n// ============================================================\n\n/**\n * Context passed during rendering\n */\nexport interface RenderContext {\n  readonly surfaceId: SurfaceId\n  readonly bindings: Map<string, CapabilityId>\n  readonly data: Record<string, unknown>\n  readonly slots: Map<string, readonly RenderNode[]>\n  readonly parent?: RenderContext\n}\n\n/**\n * Create a render context\n */\nexport function createRenderContext(options: {\n  surfaceId: SurfaceId\n  bindings?: Map<string, CapabilityId>\n  data?: Record<string, unknown>\n  slots?: Map<string, readonly RenderNode[]>\n  parent?: RenderContext\n}): RenderContext {\n  const result: RenderContext = {\n    surfaceId: options.surfaceId,\n    bindings: options.bindings ?? new Map(),\n    data: options.data ?? {},\n    slots: options.slots ?? new Map(),\n  }\n  if (options.parent) {\n    return { ...result, parent: options.parent }\n  }\n  return result\n}\n\n/**\n * Create a child context with additional data\n */\nexport function createChildContext(\n  parent: RenderContext,\n  additionalData: Record<string, unknown>\n): RenderContext {\n  return {\n    ...parent,\n    data: { ...parent.data, ...additionalData },\n    parent,\n  }\n}\n\n// ============================================================\n// RENDER RESULT\n// ============================================================\n\n/**\n * Result of rendering a surface\n */\nexport type RenderResult =\n  | { readonly success: true; readonly output: RenderOutput }\n  | { readonly success: false; readonly error: RenderError }\n\n/**\n * Render output\n */\nexport interface RenderOutput {\n  readonly surfaceId: SurfaceId\n  readonly root: RenderNode\n  readonly metadata: {\n    readonly renderTime: number\n    readonly nodeCount: number\n    readonly bindings: readonly string[]\n  }\n}\n\n/**\n * Formalized error code vocabulary for render errors\n */\nexport type RenderErrorCode =\n  | 'invalid_surface'\n  | 'missing_binding'\n  | 'layout_error'\n  | 'slot_error'\n  | 'expression_error'\n\n/**\n * Render error types\n */\nexport type RenderError =\n  | {\n      readonly type: 'invalid_surface'\n      readonly message: string\n      readonly details?: Record<string, unknown>\n    }\n  | {\n      readonly type: 'missing_binding'\n      readonly binding: string\n      readonly details?: Record<string, unknown>\n    }\n  | {\n      readonly type: 'layout_error'\n      readonly message: string\n      readonly details?: Record<string, unknown>\n    }\n  | {\n      readonly type: 'slot_error'\n      readonly slot: string\n      readonly message: string\n      readonly details?: Record<string, unknown>\n    }\n  | {\n      readonly type: 'expression_error'\n      readonly expression: string\n      readonly message: string\n      readonly details?: Record<string, unknown>\n    }\n\n/**\n * Create a successful render result\n */\nexport function renderSuccess(output: RenderOutput): RenderResult {\n  return { success: true, output }\n}\n\n/**\n * Create a failed render result\n */\nexport function renderError(error: RenderError): RenderResult {\n  return { success: false, error }\n}\n"]}

package/dist/surface/validation.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Block Props Validation
+ *
+ * Runtime validation of block props using injected Zod schemas.
+ * the legacy `blockSchemas` map is gone — production
+ * callers supply a schema map sourced from the install pipeline (per-atom
+ * `manifest.definition.props[*].jsonSchema` rebuilt into Zod). Without a
+ * schema map the validator runs in lenient mode and passes everything
+ * through.
+ *
+ * @module @pwfabric/runtime/surface/validation
+ */
+import type { ZodSchema } from 'zod';
+/** Map of block type → Zod schema. Supply via options to enable strict checks. */
+export type BlockSchemaMap = Readonly<Record<string, ZodSchema>>;
+/**
+ * Options for block props validation
+ */
+export interface BlockPropsValidationOptions {
+    /**
+     * When true, unknown block types cause validation failure.
+     * When false (default), unknown block types pass through.
+     */
+    readonly strict?: boolean;
+    /**
+     * Per-block-type Zod schemas. the runtime no longer
+     * ships a built-in schema map — callers that want prop validation
+     * supply their own (typically rebuilt from
+     * each installed block manifest's `definition.props[*].jsonSchema`).
+     * Omitting the map yields lenient pass-through behaviour.
+     */
+    readonly schemas?: BlockSchemaMap;
+    /**
+     * Per-block-type manifest props. When supplied, props a manifest
+     * does not declare and templates on `bindable: false` props are reported as
+     * WARNINGS (`manifestPropFindings`); they never fail validation.
+     */
+    readonly manifests?: BlockManifestPropsMap;
+}
+/**
+ * Result of validating block props against the schema
+ */
+export interface BlockPropsValidationResult {
+    readonly valid: boolean;
+    readonly errors: readonly string[];
+    readonly coerced?: Record<string, unknown>;
+}
+/**
+ * Validate block props against the known Zod schema for the given block type.
+ *
+ * - Known block types are validated against the schema from @pwfabric/core.
+ * - Unknown block types pass through in lenient mode (default) and fail in strict mode.
+ * - On success, returns coerced data (with defaults applied by Zod).
+ */
+export declare function validateBlockProps(type: string, props: Record<string, unknown>, options?: BlockPropsValidationOptions): BlockPropsValidationResult;
+/**
+ * Layout node shape for recursive validation.
+ * Matches LayoutJSON structure without importing it to avoid circular deps.
+ */
+interface LayoutNode {
+    readonly type: string;
+    readonly props?: Record<string, unknown>;
+    readonly children?: readonly LayoutNode[];
+}
+/**
+ * A single validation issue with path context
+ */
+export interface LayoutPropsIssue {
+    readonly path: string;
+    readonly type: string;
+    readonly errors: readonly string[];
+}
+/**
+ * Validate all block props in a layout tree recursively.
+ *
+ * Returns a flat list of validation issues with path context.
+ */
+export declare function validateLayoutProps(layout: LayoutNode, options?: BlockPropsValidationOptions, path?: string): readonly LayoutPropsIssue[];
+/**
+ * One prop a pack manifest declares: `manifest.definition.props[*]`. Only the
+ * two fields the check reads; a full manifest entry passes as it is.
+ */
+export interface ManifestPropSpec {
+    readonly name: string;
+    /** `false` = the prop takes a literal only; a `{{ }}` template is not resolved for it. */
+    readonly bindable?: boolean;
+}
+/** Block type → the props its manifest declares. */
+export type BlockManifestPropsMap = Readonly<Record<string, readonly ManifestPropSpec[]>>;
+export type ManifestPropFindingCode = 'UNKNOWN_PROP' | 'TEMPLATE_ON_UNBINDABLE';
+/**
+ * A prop that does not match its block's manifest. Always a WARNING:
+ * existing apps carry such props and must keep rendering; a caller
+ * decides whether to show, count or (later) refuse them.
+ */
+export interface ManifestPropFinding {
+    readonly path: string;
+    readonly type: string;
+    readonly prop: string;
+    readonly code: ManifestPropFindingCode;
+    readonly severity: 'warning';
+    readonly message: string;
+}
+/**
+ * The props of ONE block that its manifest does not allow.
+ *
+ * WHY: a prop the manifest does not declare was
+ * accepted silently. The schema check rebuilds each prop's JSON schema into a
+ * passthrough object, so a misspelt or invented prop (`tone` on a block that
+ * has none, `paddingY` where the block reads `padding`) validated clean and
+ * did nothing on screen. And a `{{ }}` template on a `bindable: false` prop was
+ * shown to the visitor as literal braces. Both are now named.
+ *
+ * @param specs the block's declared props; `undefined` (block not in the map)
+ *   yields nothing, because an unknown block type is a different finding.
+ */
+export declare function blockManifestPropFindings(type: string, props: Record<string, unknown> | undefined, specs: readonly ManifestPropSpec[] | undefined, path?: string): ManifestPropFinding[];
+/**
+ * Every manifest finding in a layout tree, with path context. Blocks whose
+ * type is not in `manifests` are skipped.
+ */
+export declare function manifestPropFindings(layout: LayoutNode, manifests: BlockManifestPropsMap, path?: string): ManifestPropFinding[];
+export {};