@procedures/splay 0.0.0-stage → 0.2.0

package/dist/components/types.d.ts

@@ -0,0 +1,264 @@
+/**
+ * Component Types
+ *
+ * Components are procedures that return serializable UI descriptors.
+ * This enables SSR, caching, and transport over wire.
+ *
+ * Components integrate with splay's rendering model where a renderer
+ * produces output based on data, size, and path context.
+ */
+import type { ZodLike } from "@procedures/client/client";
+import type { ProcedureMetadata, ProcedurePath } from "@procedures/client";
+import type { IEventBus as EventBus } from "@procedures/client";
+/**
+ * Serializable component output descriptor.
+ * Can be transported over wire, cached, and hydrated by any framework.
+ *
+ * @example
+ * ```typescript
+ * const descriptor: ComponentOutput = {
+ *   type: "user-card",
+ *   props: {
+ *     name: "John Doe",
+ *     avatar: "/images/john.png",
+ *   },
+ *   children: [
+ *     { type: "badge", props: { label: "Admin" } },
+ *   ],
+ * };
+ * ```
+ */
+export interface ComponentOutput {
+    /** Component type identifier (maps to registered component) */
+    type: string;
+    /** Serializable props for the component */
+    props: Record<string, unknown>;
+    /** Nested child descriptors (optional) */
+    children?: ComponentOutput[];
+    /** Component key for reconciliation (optional) */
+    key?: string;
+}
+/**
+ * Fragment output - multiple components without wrapper.
+ */
+export interface FragmentOutput {
+    type: "__fragment__";
+    children: ComponentOutput[];
+}
+/**
+ * Null output - render nothing.
+ */
+export interface NullOutput {
+    type: "__null__";
+}
+/**
+ * Any valid component output.
+ */
+export type AnyComponentOutput = ComponentOutput | FragmentOutput | NullOutput;
+/**
+ * Size information for responsive rendering.
+ */
+export interface Size {
+    width: number;
+    height: number;
+}
+/**
+ * Context passed to component factories.
+ * Compatible with splay's RenderContext.
+ *
+ * @example
+ * ```typescript
+ * factory: (ctx) => ({
+ *   type: "user-card",
+ *   props: {
+ *     user: ctx.data,
+ *     compact: ctx.size.width < 400,
+ *   },
+ *   children: ctx.data.posts?.map((post, i) =>
+ *     ctx.render(post, ctx.size, `${ctx.path}.posts[${i}]`)
+ *   ),
+ * })
+ * ```
+ */
+export interface ComponentContext<TData = unknown> {
+    /** Input data for the component */
+    data: TData;
+    /** Available rendering size */
+    size: Size;
+    /** Path in the render tree (for debugging and keys) */
+    path: string;
+    /** Current depth in the render tree */
+    depth: number;
+    /**
+     * Render a child component.
+     * Delegates to the renderer to produce a ComponentOutput.
+     *
+     * @param data - Data for the child component
+     * @param size - Size available for the child
+     * @param path - Path for the child (for keys and debugging)
+     * @returns ComponentOutput from the child render
+     */
+    render: (data: unknown, size: Size, path: string) => ComponentOutput | Promise<ComponentOutput>;
+    /**
+     * Event bus for streaming coordination.
+     * Available when executing in a procedure context.
+     */
+    bus?: EventBus;
+    /**
+     * Additional metadata from the procedure context.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Component factory function (single output).
+ * Returns a serializable component descriptor.
+ */
+export type ComponentFactory<TData = unknown> = (ctx: ComponentContext<TData>) => ComponentOutput | Promise<ComponentOutput>;
+/**
+ * Streaming component factory (multi-yield).
+ * Yields descriptors over time for live updates.
+ */
+export type StreamingComponentFactory<TData = unknown> = (ctx: ComponentContext<TData>) => AsyncGenerator<ComponentOutput, void, unknown>;
+/**
+ * Any component factory (single or streaming).
+ */
+export type AnyComponentFactory<TData = unknown> = ComponentFactory<TData> | StreamingComponentFactory<TData>;
+/**
+ * Component metadata (extends ProcedureMetadata).
+ */
+export interface ComponentMetadata extends ProcedureMetadata {
+    /** Component category for organization */
+    category?: string;
+    /** Whether the component supports streaming updates */
+    streaming?: boolean;
+    /** Default size constraints */
+    defaultSize?: Size;
+    /** Minimum size constraints */
+    minSize?: Size;
+    /** Maximum size constraints */
+    maxSize?: Size;
+}
+/**
+ * Component definition.
+ * Wraps a factory function with type information and metadata.
+ *
+ * @example
+ * ```typescript
+ * const userCard: ComponentDefinition<User> = {
+ *   type: "user-card",
+ *   namespace: "ui",
+ *   input: userSchema,
+ *   metadata: {
+ *     description: "Displays user information",
+ *     category: "profile",
+ *   },
+ *   factory: (ctx) => ({
+ *     type: "user-card",
+ *     props: { user: ctx.data },
+ *   }),
+ * };
+ * ```
+ */
+export interface ComponentDefinition<TData = unknown> {
+    /** Component type identifier */
+    type: string;
+    /**
+     * Namespace for the component (optional).
+     * Results in path: ["components", namespace, type]
+     *
+     * @example
+     * namespace: "ui" → ["components", "ui", "user-card"]
+     */
+    namespace?: string;
+    /**
+     * Input schema for validating component data.
+     * Optional - if not provided, accepts any data.
+     */
+    input?: ZodLike<TData>;
+    /**
+     * Component metadata for documentation and tooling.
+     */
+    metadata?: ComponentMetadata;
+    /**
+     * Whether this component streams updates.
+     * When true, factory is expected to be a generator.
+     */
+    streaming?: boolean;
+    /**
+     * Component factory function.
+     * Can be a regular function (single output) or generator (streaming).
+     */
+    factory: AnyComponentFactory<TData>;
+}
+/**
+ * Any component definition (type-erased for storage).
+ */
+export type AnyComponentDefinition = ComponentDefinition<unknown>;
+/**
+ * Registered component with resolved path.
+ */
+export interface RegisteredComponent<TData = unknown> {
+    /** Full procedure path */
+    path: ProcedurePath;
+    /** Original component definition */
+    definition: ComponentDefinition<TData>;
+}
+/**
+ * Component bundle - collection of components with shared namespace.
+ *
+ * @example
+ * ```typescript
+ * const uiComponents: ComponentBundle = {
+ *   namespace: "ui",
+ *   components: [
+ *     buttonComponent,
+ *     cardComponent,
+ *     modalComponent,
+ *   ],
+ * };
+ * ```
+ */
+export interface ComponentBundle {
+    /** Shared namespace for all components in bundle */
+    namespace: string;
+    /** Component definitions */
+    components: AnyComponentDefinition[];
+    /** Bundle metadata */
+    metadata?: {
+        /** Bundle name */
+        name?: string;
+        /** Bundle description */
+        description?: string;
+        /** Bundle version */
+        version?: string;
+    };
+}
+/**
+ * Infer input type from a component definition.
+ */
+export type InferComponentInput<T> = T extends ComponentDefinition<infer TData> ? TData : unknown;
+/**
+ * Infer whether a component is streaming.
+ */
+export type IsStreamingComponent<T> = T extends ComponentDefinition<unknown> ? T["streaming"] extends true ? true : false : false;
+/**
+ * Create a null output (render nothing).
+ */
+export declare function nullOutput(): NullOutput;
+/**
+ * Create a fragment output (multiple children without wrapper).
+ */
+export declare function fragment(...children: ComponentOutput[]): FragmentOutput;
+/**
+ * Check if output is a fragment.
+ */
+export declare function isFragment(output: AnyComponentOutput): output is FragmentOutput;
+/**
+ * Check if output is null.
+ */
+export declare function isNullOutput(output: AnyComponentOutput): output is NullOutput;
+/**
+ * Check if a factory is a streaming generator.
+ */
+export declare function isStreamingFactory<TData>(factory: AnyComponentFactory<TData>): factory is StreamingComponentFactory<TData>;
+//# sourceMappingURL=types.d.ts.map

package/dist/components/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/components/types.ts"],"names":[],"mappings":"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"}

package/dist/components/types.js

@@ -0,0 +1,46 @@
+/**
+ * Component Types
+ *
+ * Components are procedures that return serializable UI descriptors.
+ * This enables SSR, caching, and transport over wire.
+ *
+ * Components integrate with splay's rendering model where a renderer
+ * produces output based on data, size, and path context.
+ */
+// =============================================================================
+// Output Helpers
+// =============================================================================
+/**
+ * Create a null output (render nothing).
+ */
+export function nullOutput() {
+    return { type: "__null__" };
+}
+/**
+ * Create a fragment output (multiple children without wrapper).
+ */
+export function fragment(...children) {
+    return { type: "__fragment__", children };
+}
+/**
+ * Check if output is a fragment.
+ */
+export function isFragment(output) {
+    return output.type === "__fragment__";
+}
+/**
+ * Check if output is null.
+ */
+export function isNullOutput(output) {
+    return output.type === "__null__";
+}
+/**
+ * Check if a factory is a streaming generator.
+ */
+export function isStreamingFactory(factory) {
+    // The tag of the prototype, not `constructor.name`: an own `constructor` property, or a
+    // bundler that renames classes, does not change it. A plain function that returns a
+    // generator is not detected here: the handler of a component streams its result anyway.
+    return Object.prototype.toString.call(factory) === "[object AsyncGeneratorFunction]";
+}
+//# sourceMappingURL=types.js.map

package/dist/components/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/components/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAkTH,gFAAgF;AAChF,iBAAiB;AACjB,gFAAgF;AAEhF;;GAEG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;AAC9B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAG,QAA2B;IACrD,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,QAAQ,EAAE,CAAC;AAC5C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,MAA0B;IACnD,OAAO,MAAM,CAAC,IAAI,KAAK,cAAc,CAAC;AACxC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,MAA0B;IACrD,OAAO,MAAM,CAAC,IAAI,KAAK,UAAU,CAAC;AACpC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAmC;IAEnC,wFAAwF;IACxF,oFAAoF;IACpF,wFAAwF;IACxF,OAAO,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,iCAAiC,CAAC;AACvF,CAAC"}

package/dist/hydrate.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Hydration
+ *
+ * Converts serializable ComponentOutput descriptors into framework-specific
+ * components (React, Vue, Svelte, etc.).
+ *
+ * This enables the following flow:
+ * 1. Server renders ComponentOutput (serializable)
+ * 2. Output is sent over wire (JSON)
+ * 3. Client hydrates to React/Vue/Svelte components
+ */
+import type { ComponentOutput } from "./components/index.js";
+import type { ComponentMap, HydrateOptions } from "./types.js";
+/**
+ * Create a hydrate function for a specific framework.
+ *
+ * @param options - Hydration options including component map
+ * @returns Hydrate function that converts descriptors to framework components
+ *
+ * @example React:
+ * ```typescript
+ * import { createElement } from "react";
+ * import { createHydrate } from "@procedures/splay";
+ *
+ * const hydrate = createHydrate({
+ *   components: {
+ *     "user-card": UserCard,
+ *     "badge": Badge,
+ *   },
+ *   fallback: UnknownComponent,
+ * });
+ *
+ * // Use with React
+ * function App({ descriptor }) {
+ *   return hydrate(descriptor, createElement);
+ * }
+ * ```
+ */
+export declare function createHydrate<TComponent>(options: HydrateOptions<TComponent>): (descriptor: ComponentOutput | null, createElement: CreateElement<TComponent>) => TComponent | null;
+/**
+ * createElement function signature (React-compatible).
+ */
+export type CreateElement<TComponent> = (type: TComponent, props: Record<string, unknown> | null, children?: (TComponent | null)[]) => TComponent;
+/**
+ * Generic React-like component type (works with any framework that has createElement).
+ */
+type ReactLikeComponent = (props: Record<string, unknown>) => unknown;
+/**
+ * React-specific hydration options.
+ */
+export interface ReactHydrateOptions {
+    /** Map of component types to React components */
+    components: ComponentMap<ReactLikeComponent>;
+    /** Fallback component for unknown types */
+    fallback?: ReactLikeComponent;
+}
+/**
+ * React-like module interface.
+ */
+interface ReactLike {
+    createElement(type: ReactLikeComponent | symbol, props: Record<string, unknown> | null, ...children: unknown[]): unknown;
+    Fragment: symbol;
+}
+/**
+ * Create a React-specific hydrate function.
+ *
+ * @param react - React module (import * as React from "react")
+ * @param options - Hydration options
+ * @returns Hydrate function for React
+ *
+ * @example
+ * ```typescript
+ * import * as React from "react";
+ * import { createReactHydrate } from "@procedures/splay";
+ *
+ * const hydrate = createReactHydrate(React, {
+ *   components: {
+ *     "user-card": UserCard,
+ *     "badge": Badge,
+ *   },
+ * });
+ *
+ * function App({ descriptor }) {
+ *   return hydrate(descriptor);
+ * }
+ * ```
+ */
+export declare function createReactHydrate(react: ReactLike, options: ReactHydrateOptions): (descriptor: ComponentOutput | null) => unknown;
+/**
+ * Walk a descriptor tree and apply a visitor to each node.
+ */
+export declare function walkDescriptor(descriptor: ComponentOutput, visitor: (node: ComponentOutput, path: string[]) => void, path?: string[]): void;
+/**
+ * Transform a descriptor tree.
+ */
+export declare function transformDescriptor(descriptor: ComponentOutput, transform: (node: ComponentOutput) => ComponentOutput): ComponentOutput;
+/**
+ * Find all nodes in a descriptor tree matching a predicate.
+ */
+export declare function findInDescriptor(descriptor: ComponentOutput, predicate: (node: ComponentOutput) => boolean): ComponentOutput[];
+/**
+ * Get all component types used in a descriptor tree.
+ */
+export declare function getUsedTypes(descriptor: ComponentOutput): Set<string>;
+/**
+ * Validate that all component types in a descriptor are known.
+ */
+export declare function validateDescriptor(descriptor: ComponentOutput, knownTypes: Set<string> | string[]): {
+    valid: boolean;
+    unknownTypes: string[];
+};
+/**
+ * Serialize a descriptor to JSON string.
+ */
+export declare function serializeDescriptor(descriptor: ComponentOutput): string;
+/**
+ * Parse a descriptor from JSON string.
+ */
+export declare function parseDescriptor(json: string): ComponentOutput;
+/**
+ * Create a compact representation of a descriptor.
+ * Removes undefined values and empty arrays.
+ */
+export declare function compactDescriptor(descriptor: ComponentOutput): ComponentOutput;
+export {};
+//# sourceMappingURL=hydrate.d.ts.map

package/dist/hydrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydrate.d.ts","sourceRoot":"","sources":["../src/hydrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAc/D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,aAAa,CAAC,UAAU,EACtC,OAAO,EAAE,cAAc,CAAC,UAAU,CAAC,GAClC,CACD,UAAU,EAAE,eAAe,GAAG,IAAI,EAClC,aAAa,EAAE,aAAa,CAAC,UAAU,CAAC,KACrC,UAAU,GAAG,IAAI,CAmDrB;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,CAAC,UAAU,IAAI,CACtC,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,EACrC,QAAQ,CAAC,EAAE,CAAC,UAAU,GAAG,IAAI,CAAC,EAAE,KAC7B,UAAU,CAAC;AAMhB;;GAEG;AACH,KAAK,kBAAkB,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,iDAAiD;IACjD,UAAU,EAAE,YAAY,CAAC,kBAAkB,CAAC,CAAC;IAC7C,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC/B;AAED;;GAEG;AACH,UAAU,SAAS;IACjB,aAAa,CACX,IAAI,EAAE,kBAAkB,GAAG,MAAM,EACjC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,EACrC,GAAG,QAAQ,EAAE,OAAO,EAAE,GACrB,OAAO,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,mBAAmB,GAC3B,CAAC,UAAU,EAAE,eAAe,GAAG,IAAI,KAAK,OAAO,CAwCjD;AAMD;;GAEG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,eAAe,EAC3B,OAAO,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,IAAI,EACxD,IAAI,GAAE,MAAM,EAAO,GAClB,IAAI,CAQN;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,eAAe,EAC3B,SAAS,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,eAAe,GACpD,eAAe,CAajB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,eAAe,EAC3B,SAAS,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,OAAO,GAC5C,eAAe,EAAE,CAUnB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,eAAe,GAAG,GAAG,CAAC,MAAM,CAAC,CAUrE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,eAAe,EAC3B,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,GACjC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,CAe5C;AAMD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,eAAe,GAAG,MAAM,CAEvE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAE7D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,eAAe,GAAG,eAAe,CAe9E"}

package/dist/hydrate.js

@@ -0,0 +1,226 @@
+/**
+ * Hydration
+ *
+ * Converts serializable ComponentOutput descriptors into framework-specific
+ * components (React, Vue, Svelte, etc.).
+ *
+ * This enables the following flow:
+ * 1. Server renders ComponentOutput (serializable)
+ * 2. Output is sent over wire (JSON)
+ * 3. Client hydrates to React/Vue/Svelte components
+ */
+const log = globalThis.console;
+// =============================================================================
+// Hydration Core
+// =============================================================================
+/**
+ * Create a hydrate function for a specific framework.
+ *
+ * @param options - Hydration options including component map
+ * @returns Hydrate function that converts descriptors to framework components
+ *
+ * @example React:
+ * ```typescript
+ * import { createElement } from "react";
+ * import { createHydrate } from "@procedures/splay";
+ *
+ * const hydrate = createHydrate({
+ *   components: {
+ *     "user-card": UserCard,
+ *     "badge": Badge,
+ *   },
+ *   fallback: UnknownComponent,
+ * });
+ *
+ * // Use with React
+ * function App({ descriptor }) {
+ *   return hydrate(descriptor, createElement);
+ * }
+ * ```
+ */
+export function createHydrate(options) {
+    const { components, fallback, onNull, onFragment } = options;
+    return function hydrate(descriptor, createElement) {
+        // Handle null
+        if (descriptor === null) {
+            return onNull?.() ?? null;
+        }
+        // Handle null output type
+        if (descriptor.type === "__null__") {
+            return onNull?.() ?? null;
+        }
+        // Handle fragment
+        if (descriptor.type === "__fragment__") {
+            const children = (descriptor.children ?? []).map((child) => hydrate(child, createElement));
+            if (onFragment) {
+                return onFragment(children.filter((c) => c !== null));
+            }
+            // Default: return first child or null
+            return children[0] ?? null;
+        }
+        // Look up component
+        const Component = components[descriptor.type] ?? fallback;
+        if (!Component) {
+            log.warn(`Unknown component type: ${descriptor.type}`);
+            return null;
+        }
+        // Hydrate children recursively
+        const hydratedChildren = descriptor.children?.map((child) => hydrate(child, createElement));
+        // Create the component
+        return createElement(Component, { ...descriptor.props, key: descriptor.key }, hydratedChildren);
+    };
+}
+/**
+ * Create a React-specific hydrate function.
+ *
+ * @param react - React module (import * as React from "react")
+ * @param options - Hydration options
+ * @returns Hydrate function for React
+ *
+ * @example
+ * ```typescript
+ * import * as React from "react";
+ * import { createReactHydrate } from "@procedures/splay";
+ *
+ * const hydrate = createReactHydrate(React, {
+ *   components: {
+ *     "user-card": UserCard,
+ *     "badge": Badge,
+ *   },
+ * });
+ *
+ * function App({ descriptor }) {
+ *   return hydrate(descriptor);
+ * }
+ * ```
+ */
+export function createReactHydrate(react, options) {
+    const { components, fallback } = options;
+    function hydrate(descriptor) {
+        if (descriptor === null) {
+            return null;
+        }
+        if (descriptor.type === "__null__") {
+            return null;
+        }
+        if (descriptor.type === "__fragment__") {
+            const children = (descriptor.children ?? []).map((child) => hydrate(child));
+            return react.createElement(react.Fragment, null, ...children);
+        }
+        const Component = components[descriptor.type];
+        if (!Component) {
+            if (fallback) {
+                return react.createElement(fallback, {
+                    type: descriptor.type,
+                    props: descriptor.props,
+                });
+            }
+            log.warn(`Unknown component type: ${descriptor.type}`);
+            return null;
+        }
+        const hydratedChildren = descriptor.children?.map((child) => hydrate(child));
+        return react.createElement(Component, { ...descriptor.props, key: descriptor.key }, ...(hydratedChildren ?? []));
+    }
+    return hydrate;
+}
+// =============================================================================
+// Descriptor Utilities
+// =============================================================================
+/**
+ * Walk a descriptor tree and apply a visitor to each node.
+ */
+export function walkDescriptor(descriptor, visitor, path = []) {
+    visitor(descriptor, path);
+    if (descriptor.children) {
+        descriptor.children.forEach((child, index) => {
+            walkDescriptor(child, visitor, [...path, `children[${index}]`]);
+        });
+    }
+}
+/**
+ * Transform a descriptor tree.
+ */
+export function transformDescriptor(descriptor, transform) {
+    const transformed = transform(descriptor);
+    if (transformed.children) {
+        return {
+            ...transformed,
+            children: transformed.children.map((child) => transformDescriptor(child, transform)),
+        };
+    }
+    return transformed;
+}
+/**
+ * Find all nodes in a descriptor tree matching a predicate.
+ */
+export function findInDescriptor(descriptor, predicate) {
+    const results = [];
+    walkDescriptor(descriptor, (node) => {
+        if (predicate(node)) {
+            results.push(node);
+        }
+    });
+    return results;
+}
+/**
+ * Get all component types used in a descriptor tree.
+ */
+export function getUsedTypes(descriptor) {
+    const types = new Set();
+    walkDescriptor(descriptor, (node) => {
+        if (node.type !== "__null__" && node.type !== "__fragment__") {
+            types.add(node.type);
+        }
+    });
+    return types;
+}
+/**
+ * Validate that all component types in a descriptor are known.
+ */
+export function validateDescriptor(descriptor, knownTypes) {
+    const known = knownTypes instanceof Set ? knownTypes : new Set(knownTypes);
+    const used = getUsedTypes(descriptor);
+    const unknownTypes = [];
+    for (const type of used) {
+        if (!known.has(type)) {
+            unknownTypes.push(type);
+        }
+    }
+    return {
+        valid: unknownTypes.length === 0,
+        unknownTypes,
+    };
+}
+// =============================================================================
+// Serialization Helpers
+// =============================================================================
+/**
+ * Serialize a descriptor to JSON string.
+ */
+export function serializeDescriptor(descriptor) {
+    return JSON.stringify(descriptor);
+}
+/**
+ * Parse a descriptor from JSON string.
+ */
+export function parseDescriptor(json) {
+    return JSON.parse(json);
+}
+/**
+ * Create a compact representation of a descriptor.
+ * Removes undefined values and empty arrays.
+ */
+export function compactDescriptor(descriptor) {
+    const result = {
+        type: descriptor.type,
+        props: descriptor.props,
+    };
+    if (descriptor.children && descriptor.children.length > 0) {
+        result.children = descriptor.children.map(compactDescriptor);
+    }
+    if (descriptor.key !== undefined) {
+        result.key = descriptor.key;
+    }
+    return result;
+}
+//# sourceMappingURL=hydrate.js.map

package/dist/hydrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydrate.js","sourceRoot":"","sources":["../src/hydrate.ts"],"names":[],"mappings":"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"}