db4ai 0.1.0

package/dist/index.js

@@ -0,0 +1,3164 @@
+// Import and re-export shared handler types
+export { serializeFunction, } from './handlers';
+import { serializeFunction } from './handlers';
+/**
+ * Error thrown when schema validation fails.
+ *
+ * @example
+ * try {
+ *   DB({ User: { name: 'User name' } }) // Missing $id or $context
+ * } catch (error) {
+ *   if (error instanceof SchemaValidationError) {
+ *     console.log(error.code) // 'MISSING_CONTEXT'
+ *   }
+ * }
+ */
+export class SchemaValidationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'SchemaValidationError';
+        this.code = code;
+    }
+}
+/**
+ * Error thrown when API operations fail.
+ *
+ * @example
+ * try {
+ *   await db.User('john-doe')
+ * } catch (error) {
+ *   if (error instanceof APIError) {
+ *     console.log(error.code) // 'GENERATION_FAILED'
+ *     console.log(error.statusCode) // 404
+ *   }
+ * }
+ */
+export class APIError extends Error {
+    code;
+    statusCode;
+    constructor(code, message, statusCode) {
+        super(message);
+        this.name = 'APIError';
+        this.code = code;
+        this.statusCode = statusCode;
+    }
+}
+export function UI(components) {
+    return components;
+}
+/**
+ * Parse namespace from a $id URL.
+ *
+ * @example
+ * parseNamespaceFromId('https://db.sb/sales') // 'sales' (from path)
+ * parseNamespaceFromId('https://db4.ai/startups') // 'startups' (from path)
+ * parseNamespaceFromId('https://db.sb/org/team') // 'org/team' (from path)
+ * parseNamespaceFromId('https://startup.db.sb') // 'startup' (from subdomain)
+ * parseNamespaceFromId('https://startups.db.sb') // 'startups' (from subdomain)
+ * parseNamespaceFromId('https://db.sb/') // null
+ * parseNamespaceFromId('invalid') // null
+ */
+export function parseNamespaceFromId(id) {
+    try {
+        const url = new URL(id);
+        // Remove leading slash and trailing slash
+        const path = url.pathname.replace(/^\//, '').replace(/\/$/, '');
+        if (path)
+            return path;
+        // No path - try to extract namespace from subdomain
+        // e.g., 'startup.db.sb' -> 'startup', 'startups.db4.ai' -> 'startups'
+        const hostParts = url.hostname.split('.');
+        // Need at least 3 parts for subdomain (e.g., 'startup.db.sb' or 'startups.db4.ai')
+        if (hostParts.length >= 3) {
+            const subdomain = hostParts[0];
+            // Exclude common non-namespace subdomains
+            if (subdomain && subdomain !== 'www' && subdomain !== 'api') {
+                return subdomain;
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+// ============================================================================
+// Reference Operator Constants
+// ============================================================================
+/**
+ * Reference operators used in the schema DSL.
+ *
+ * - `->` (FORWARD_EXACT): Forward exact reference - resolves by ID
+ * - `~>` (FORWARD_FUZZY): Forward fuzzy reference - resolves by semantic matching
+ * - `<-` (BACKWARD_EXACT): Backward exact reference - reverse lookup by ID
+ * - `<~` (BACKWARD_FUZZY): Backward fuzzy reference - reverse lookup by semantic matching
+ *
+ * @example
+ * // Forward references (existing)
+ * { author: '->User' }     // Exact forward ref
+ * { avatar: '~>Image' }    // Fuzzy forward ref
+ *
+ * // Backward references (new)
+ * { posts: '<-Post' }      // Find Posts that reference this entity
+ * { related: '<~Article' } // Find semantically related Articles
+ */
+export const OPERATORS = {
+    /** Forward exact reference: `->Type` - resolves to exact ID match */
+    FORWARD_EXACT: '->',
+    /** Forward fuzzy reference: `~>Type` - resolves by semantic similarity */
+    FORWARD_FUZZY: '~>',
+    /** Backward exact reference: `<-Type` - finds entities referencing this one */
+    BACKWARD_EXACT: '<-',
+    /** Backward fuzzy reference: `<~Type` - finds semantically related entities */
+    BACKWARD_FUZZY: '<~',
+};
+/**
+ * Parse a reference operator prefix into its direction and mode/fuzzy properties.
+ *
+ * This helper function converts the two-character operator prefix into structured
+ * properties for building ReferenceField objects.
+ *
+ * @param prefix - The operator prefix (`->`, `~>`, `<-`, or `<~`)
+ * @returns Parsed operator with direction and either fuzzy (forward) or mode (backward)
+ *
+ * @example
+ * parseOperator('->') // { direction: 'forward', fuzzy: false }
+ * parseOperator('~>') // { direction: 'forward', fuzzy: true }
+ * parseOperator('<-') // { direction: 'backward', mode: 'exact' }
+ * parseOperator('<~') // { direction: 'backward', mode: 'fuzzy' }
+ */
+export function parseOperator(prefix) {
+    switch (prefix) {
+        case OPERATORS.FORWARD_EXACT:
+            return { direction: 'forward', fuzzy: false };
+        case OPERATORS.FORWARD_FUZZY:
+            return { direction: 'forward', fuzzy: true };
+        case OPERATORS.BACKWARD_EXACT:
+            return { direction: 'backward', mode: 'exact' };
+        case OPERATORS.BACKWARD_FUZZY:
+            return { direction: 'backward', mode: 'fuzzy' };
+        default:
+            // Default to forward exact for unknown operators
+            return { direction: 'forward', fuzzy: false };
+    }
+}
+/**
+ * Parse $id field which can be:
+ * - Simple JSONPath: $.slug
+ * - Transform with path: PascalCase($.example)
+ * - Column name (legacy): slug
+ *
+ * @example
+ * parseIdConfig('$.slug')                    // { path: '$.slug' }
+ * parseIdConfig('PascalCase($.example)')     // { path: '$.example', transform: 'PascalCase' }
+ * parseIdConfig('kebab-case($.title)')       // { path: '$.title', transform: 'kebab-case' }
+ * parseIdConfig('slug')                      // { path: 'slug' }
+ */
+export function parseIdConfig(idField) {
+    // Check for transform pattern: Transform($.path)
+    // Supports transforms like PascalCase, camelCase, kebab-case, UPPERCASE, lowercase
+    const transformMatch = idField.match(/^([A-Za-z][A-Za-z0-9-]*)\((\$\..+)\)$/);
+    if (transformMatch) {
+        const [, transform, path] = transformMatch;
+        return { path, transform };
+    }
+    // Plain JSONPath or column name
+    return { path: idField };
+}
+// ============================================================================
+// JSONPath Validation
+// ============================================================================
+/**
+ * Validates that a string is a valid JSONPath expression.
+ *
+ * A valid JSONPath must:
+ * - Start with `$.` (root reference)
+ * - Contain valid property names, array indices, or bracket notation
+ *
+ * Supported patterns:
+ * - `$.field` - Simple property access
+ * - `$.nested.field` - Nested property access
+ * - `$.array[0]` - Array index access
+ * - `$.array[*]` - Array wildcard
+ * - `$.items[?(@.active)]` - Filter expressions
+ *
+ * @example
+ * isValidJSONPath('$.title')           // true
+ * isValidJSONPath('$.data.items[0]')   // true
+ * isValidJSONPath('$.tags[*]')         // true
+ * isValidJSONPath('title')             // false (missing $.)
+ * isValidJSONPath('$50 price')         // false (not a valid path)
+ */
+export function isValidJSONPath(path) {
+    // Must start with $.
+    if (!path.startsWith('$.')) {
+        return false;
+    }
+    // Basic validation regex for common JSONPath patterns:
+    // - Property access: .propertyName or ['property name']
+    // - Array access: [0], [*], [?(@.condition)]
+    // - Nested paths: $.a.b.c
+    const jsonPathPattern = /^\$\.[\w\[\].*@?()'"=!<>|&\s-]+$/;
+    return jsonPathPattern.test(path);
+}
+// ============================================================================
+// Type Guards for ParsedField
+// ============================================================================
+/**
+ * Type guard to check if a ParsedField is a JSONPathField.
+ *
+ * @example
+ * const field = parseFieldType('$.title')
+ * if (isJSONPathField(field)) {
+ *   console.log(field.path)  // TypeScript knows field.path exists
+ * }
+ */
+export function isJSONPathField(field) {
+    return field.type === 'jsonpath';
+}
+/**
+ * Type guard to check if a ParsedField is a JSONPathEmbeddedField.
+ *
+ * @example
+ * const field = parseFieldType('$.author ->Author')
+ * if (isJSONPathEmbeddedField(field)) {
+ *   console.log(field.embeddedType)  // TypeScript knows field.embeddedType exists
+ * }
+ */
+export function isJSONPathEmbeddedField(field) {
+    return field.type === 'jsonpath-embedded';
+}
+/**
+ * Type guard to check if a ParsedField is a PromptField.
+ *
+ * @example
+ * const field = parsed.types.Task.fields.description
+ * if (isPromptField(field)) {
+ *   console.log(field.prompt)  // TypeScript knows field.prompt exists
+ * }
+ */
+export function isPromptField(field) {
+    return field.type === 'prompt';
+}
+/**
+ * Type guard to check if a ParsedField is a StringField.
+ */
+export function isStringField(field) {
+    return field.type === 'string';
+}
+/**
+ * Validate a raw state machine configuration.
+ * Checks for: valid $initial, reachable states, no orphan states, valid transitions.
+ */
+export function validateStateConfig(config) {
+    const errors = [];
+    // Extract state names (exclude $ prefixed keys like $initial, $version, etc.)
+    const stateNames = Object.keys(config).filter((k) => !k.startsWith('$'));
+    // Check if $initial is missing or empty
+    if (!('$initial' in config) || config.$initial === undefined) {
+        errors.push({
+            code: 'MISSING_INITIAL_STATE',
+            message: 'State machine configuration is missing $initial',
+        });
+    }
+    else if (config.$initial === '' || !stateNames.includes(config.$initial)) {
+        // $initial is present but invalid (empty string or references non-existent state)
+        errors.push({
+            code: 'INVALID_INITIAL_STATE',
+            message: `Initial state '${config.$initial}' is not a valid state`,
+        });
+    }
+    // Helper to get transition target from a transition value
+    const getTransitionTarget = (value) => {
+        if (typeof value === 'string')
+            return value;
+        if (value && typeof value === 'object' && 'to' in value && typeof value.to === 'string') {
+            return value.to;
+        }
+        return null;
+    };
+    // Check all transition targets exist and have valid syntax
+    for (const stateName of stateNames) {
+        const stateConfig = config[stateName];
+        // null means terminal state - valid
+        if (stateConfig === null)
+            continue;
+        // Empty object means terminal state - valid
+        if (typeof stateConfig === 'object' && Object.keys(stateConfig).length === 0)
+            continue;
+        if (typeof stateConfig !== 'object') {
+            errors.push({
+                code: 'INVALID_STATE_CONFIG',
+                message: `State '${stateName}' has invalid configuration`,
+                state: stateName,
+            });
+            continue;
+        }
+        // Check each transition
+        for (const [eventName, transitionValue] of Object.entries(stateConfig)) {
+            // Skip handler functions ($entry, $exit)
+            if (eventName.startsWith('$'))
+                continue;
+            // Check transition syntax
+            if (Array.isArray(transitionValue)) {
+                errors.push({
+                    code: 'INVALID_TRANSITION_SYNTAX',
+                    message: `Transition '${eventName}' in state '${stateName}' cannot be an array`,
+                    state: stateName,
+                    event: eventName,
+                });
+                continue;
+            }
+            // String transition: { submit: 'pending' }
+            if (typeof transitionValue === 'string') {
+                if (!stateNames.includes(transitionValue)) {
+                    errors.push({
+                        code: 'INVALID_TRANSITION_TARGET',
+                        message: `Transition '${eventName}' in state '${stateName}' targets unknown state '${transitionValue}'`,
+                        state: stateName,
+                        event: eventName,
+                    });
+                }
+                continue;
+            }
+            // null transition: terminal (goes nowhere, like archive/delete)
+            if (transitionValue === null)
+                continue;
+            // Object transition: { submit: { to: 'pending', if: ..., do: ... } }
+            if (typeof transitionValue === 'object') {
+                const tv = transitionValue;
+                // Must have 'to' property
+                if (!('to' in tv)) {
+                    errors.push({
+                        code: 'INVALID_TRANSITION_SYNTAX',
+                        message: `Transition '${eventName}' in state '${stateName}' is missing 'to' property`,
+                        state: stateName,
+                        event: eventName,
+                    });
+                    continue;
+                }
+                // Check target exists if 'to' is specified
+                if (typeof tv.to === 'string' && !stateNames.includes(tv.to)) {
+                    errors.push({
+                        code: 'INVALID_TRANSITION_TARGET',
+                        message: `Transition '${eventName}' in state '${stateName}' targets unknown state '${tv.to}'`,
+                        state: stateName,
+                        event: eventName,
+                    });
+                }
+                continue;
+            }
+            // Unknown transition format (e.g., number)
+            errors.push({
+                code: 'INVALID_TRANSITION_SYNTAX',
+                message: `Transition '${eventName}' in state '${stateName}' has invalid format`,
+                state: stateName,
+                event: eventName,
+            });
+        }
+    }
+    // Check for orphan states (states not reachable from $initial)
+    // Only do this check if we have a valid $initial state
+    if (config.$initial && stateNames.includes(config.$initial)) {
+        const reachable = new Set();
+        const toVisit = [config.$initial];
+        while (toVisit.length > 0) {
+            const current = toVisit.pop();
+            if (reachable.has(current))
+                continue;
+            reachable.add(current);
+            // Find all states reachable from current
+            const stateConfig = config[current];
+            if (stateConfig === null || typeof stateConfig !== 'object')
+                continue;
+            for (const [eventName, transitionValue] of Object.entries(stateConfig)) {
+                if (eventName.startsWith('$'))
+                    continue;
+                const target = getTransitionTarget(transitionValue);
+                if (target && stateNames.includes(target) && !reachable.has(target)) {
+                    toVisit.push(target);
+                }
+            }
+        }
+        // Any state not in reachable set is an orphan
+        for (const stateName of stateNames) {
+            if (!reachable.has(stateName)) {
+                errors.push({
+                    code: 'ORPHAN_STATE',
+                    message: `State '${stateName}' is not reachable from initial state '${config.$initial}'`,
+                    state: stateName,
+                });
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * Parse a raw state machine configuration into the normalized format.
+ * Converts string functions to SerializedFunction objects.
+ *
+ * @param config - Raw state machine config from schema
+ * @returns Parsed state machine configuration
+ *
+ * @example
+ * const parsed = parseStateConfig({
+ *   $initial: 'draft',
+ *   draft: {
+ *     submit: 'pending',
+ *     $entry: (entity) => { console.log('entered draft') }
+ *   },
+ *   pending: {
+ *     approve: { to: 'approved', if: (e) => e.score >= 80 }
+ *   },
+ *   approved: null  // terminal state
+ * })
+ */
+export function parseStateConfig(config) {
+    const states = {};
+    for (const [stateName, stateValue] of Object.entries(config)) {
+        // Skip $initial - it's not a state
+        if (stateName === '$initial')
+            continue;
+        // Terminal state (null or empty object)
+        if (stateValue === null || (typeof stateValue === 'object' && Object.keys(stateValue).length === 0)) {
+            states[stateName] = { transitions: {} };
+            continue;
+        }
+        if (typeof stateValue !== 'object') {
+            continue; // Skip invalid state configs
+        }
+        const stateConfig = { transitions: {} };
+        const stateObj = stateValue;
+        for (const [key, value] of Object.entries(stateObj)) {
+            // Handle $entry handler
+            if (key === '$entry') {
+                if (typeof value === 'function') {
+                    stateConfig.$entry = serializeFunction('$entry', value);
+                }
+                else if (typeof value === 'string') {
+                    // String function body - parse it
+                    stateConfig.$entry = {
+                        name: '$entry',
+                        body: value,
+                        params: ['entity'],
+                        async: value.includes('await'),
+                    };
+                }
+                continue;
+            }
+            // Handle $exit handler
+            if (key === '$exit') {
+                if (typeof value === 'function') {
+                    stateConfig.$exit = serializeFunction('$exit', value);
+                }
+                else if (typeof value === 'string') {
+                    stateConfig.$exit = {
+                        name: '$exit',
+                        body: value,
+                        params: ['entity'],
+                        async: value.includes('await'),
+                    };
+                }
+                continue;
+            }
+            // Handle transitions
+            const transitionName = key;
+            // Simple string transition: { submit: 'pending' }
+            if (typeof value === 'string') {
+                stateConfig.transitions[transitionName] = { to: value };
+                continue;
+            }
+            // null transition (shouldn't happen, but handle it)
+            if (value === null) {
+                stateConfig.transitions[transitionName] = { to: null };
+                continue;
+            }
+            // Complex transition with to/if/do: { approve: { to: 'approved', if: ..., do: ... } }
+            if (typeof value === 'object') {
+                const transObj = value;
+                const transitionConfig = {
+                    to: transObj.to ?? null,
+                };
+                // Parse 'if' guard
+                if (transObj.if) {
+                    if (typeof transObj.if === 'function') {
+                        transitionConfig.if = serializeFunction('if', transObj.if);
+                    }
+                    else if (typeof transObj.if === 'string') {
+                        transitionConfig.if = {
+                            name: 'if',
+                            body: transObj.if,
+                            params: ['entity'],
+                            async: transObj.if.includes('await'),
+                        };
+                    }
+                }
+                // Parse 'do' action
+                if (transObj.do) {
+                    if (typeof transObj.do === 'function') {
+                        transitionConfig.do = serializeFunction('do', transObj.do);
+                    }
+                    else if (typeof transObj.do === 'string') {
+                        transitionConfig.do = {
+                            name: 'do',
+                            body: transObj.do,
+                            params: ['entity'],
+                            async: transObj.do.includes('await'),
+                        };
+                    }
+                }
+                stateConfig.transitions[transitionName] = transitionConfig;
+            }
+        }
+        states[stateName] = stateConfig;
+    }
+    return {
+        $initial: config.$initial,
+        states,
+    };
+}
+// Extract count from array description
+// Supports patterns like:
+// - "List 5 items" -> 5
+// - "Generate 10 samples" -> 10
+// - "Create exactly 7 categories" -> 7
+// - "List 3-5 keywords" -> { min: 3, max: 5 }
+export function extractCountFromDescription(description) {
+    // First check for range pattern: N-M (e.g., "3-5")
+    const rangeMatch = description.match(/\b(\d+)-(\d+)\b/);
+    if (rangeMatch) {
+        return { min: parseInt(rangeMatch[1], 10), max: parseInt(rangeMatch[2], 10) };
+    }
+    // Check for patterns like "List N", "Generate N", "Create exactly N"
+    // Match word followed by optional "exactly" and a number
+    const countMatch = description.match(/\b(?:List|Generate|Create)\s+(?:exactly\s+)?(\d+)\b/i);
+    if (countMatch) {
+        return parseInt(countMatch[1], 10);
+    }
+    return undefined;
+}
+/**
+ * Parse a field value into its structured field type representation.
+ *
+ * Converts the shorthand field notation used in schema definitions into
+ * a fully parsed field object with type information, references, and options.
+ *
+ * ## Reference Operators
+ *
+ * This function parses all four reference operators defined in {@link OPERATORS}:
+ *
+ * | Operator | Direction | Mode  | Description                    |
+ * |----------|-----------|-------|--------------------------------|
+ * | `->`     | forward   | exact | Resolves to exact ID match     |
+ * | `~>`     | forward   | fuzzy | Resolves by semantic similarity|
+ * | `<-`     | backward  | exact | Finds entities referencing this|
+ * | `<~`     | backward  | fuzzy | Finds semantically related     |
+ *
+ * @param value - The field value to parse. Can be:
+ *   - `string` - A field description or reference pattern (e.g., `'User name'`, `'->User'`, `'~>Image?'`, `'<-Post[]'`)
+ *   - `string[]` - An array field with description (e.g., `['Tag labels']`, `['<-Post']`)
+ *   - `Record<string, string>` - A nested object with field descriptions
+ *   - `Function` - A computed field
+ *
+ * @returns A ParsedField object representing the field type:
+ *   - `StringField` - Plain text field with description
+ *   - `ReferenceField` - Reference to another type (forward or backward)
+ *   - `ArrayField` - Array of strings or references
+ *   - `ObjectField` - Nested object with properties
+ *   - `EmbeddedField` - Embedded type (detected in second pass)
+ *   - `JSONPathField` - JSONPath expression for data mapping
+ *   - `ComputedField` - Field computed from a function
+ *
+ * @example
+ * // String field
+ * parseFieldType('User name')
+ * // { type: 'string', description: 'User name' }
+ *
+ * @example
+ * // Forward exact reference
+ * parseFieldType('->User')
+ * // { type: 'reference', ref: 'User', isArray: false, optional: false, fuzzy: false }
+ *
+ * @example
+ * // Forward fuzzy reference (optional)
+ * parseFieldType('~>Image?')
+ * // { type: 'reference', ref: 'Image', isArray: false, optional: true, fuzzy: true }
+ *
+ * @example
+ * // Forward array reference
+ * parseFieldType('->Tag[]')
+ * // { type: 'reference', ref: 'Tag', isArray: true, optional: false, fuzzy: false }
+ *
+ * @example
+ * // Backward exact reference - finds Posts that reference this entity
+ * parseFieldType('<-Post')
+ * // { type: 'reference', ref: 'Post', isArray: false, optional: false, direction: 'backward', mode: 'exact' }
+ *
+ * @example
+ * // Backward fuzzy reference array - finds semantically related Articles
+ * parseFieldType('<~Article[]')
+ * // { type: 'reference', ref: 'Article', isArray: true, optional: false, direction: 'backward', mode: 'fuzzy' }
+ *
+ * @example
+ * // Union type reference
+ * parseFieldType('->User|Organization')
+ * // { type: 'reference', refs: ['User', 'Organization'], isArray: false, optional: false, fuzzy: false }
+ *
+ * @example
+ * // String array with count hint
+ * parseFieldType(['List 5 keywords'])
+ * // { type: 'array', items: { type: 'string' }, description: 'List 5 keywords', count: 5 }
+ *
+ * @example
+ * // Nested object
+ * parseFieldType({ street: 'Street address', city: 'City name' })
+ * // { type: 'object', properties: { street: {...}, city: {...} } }
+ */
+export function parseFieldType(value) {
+    // Handle computed fields (functions)
+    if (typeof value === 'function') {
+        return {
+            type: 'computed',
+            source: value.toString(),
+        };
+    }
+    // Handle array descriptions: ['description'], ['... ->Type'], ['<-Type']
+    if (Array.isArray(value)) {
+        const desc = value[0] || '';
+        const count = extractCountFromDescription(desc);
+        // Check for back reference: ['<-Type']
+        const backRefMatch = desc.match(/^<-(\w+)$/);
+        if (backRefMatch) {
+            const result = {
+                type: 'array',
+                items: { type: 'string' },
+                description: desc,
+                backRef: backRefMatch[1],
+            };
+            if (count !== undefined)
+                result.count = count;
+            return result;
+        }
+        // Check for inline references: ['... ->Type'] or ['... ->Type1 ->Type2']
+        const inlineRefMatches = desc.match(/->(\w+)/g);
+        if (inlineRefMatches) {
+            const refs = inlineRefMatches.map((m) => m.slice(2)); // Remove '->' prefix
+            const result = {
+                type: 'array',
+                items: { type: 'string' },
+                description: desc,
+                refs,
+            };
+            if (count !== undefined)
+                result.count = count;
+            return result;
+        }
+        const result = {
+            type: 'array',
+            items: { type: 'string' },
+            description: desc,
+        };
+        if (count !== undefined)
+            result.count = count;
+        return result;
+    }
+    // Handle nested objects: { field: 'description', ... }
+    if (typeof value === 'object' && value !== null) {
+        const properties = {};
+        for (const [key, desc] of Object.entries(value)) {
+            properties[key] = { type: 'string', description: desc };
+        }
+        return {
+            type: 'object',
+            properties,
+        };
+    }
+    // Handle string patterns
+    const str = value;
+    // Check for JSONPath with transform: Transform($.path)
+    // Supports transforms like PascalCase, camelCase, kebab-case, UPPERCASE, lowercase
+    const transformMatch = str.match(/^([A-Za-z][A-Za-z0-9-]*)\((\$\..+)\)$/);
+    if (transformMatch) {
+        const [, transform, path] = transformMatch;
+        return {
+            type: 'jsonpath',
+            path,
+            transform,
+        };
+    }
+    // Check for JSONPath embedded pattern: $.path ->Type or $.path ->Type?
+    // Must check this BEFORE plain JSONPath to properly detect embedded mappings
+    // Pattern: JSONPath followed by optional whitespace, ->, optional whitespace, TypeName, optional ?
+    const jsonpathEmbeddedMatch = str.match(/^(\$\.[^\s]+?)\s*->\s*([A-Za-z][A-Za-z0-9]*)(\?)?$/);
+    if (jsonpathEmbeddedMatch) {
+        const [, path, embeddedType, optionalMarker] = jsonpathEmbeddedMatch;
+        // Determine if it's an array based on path containing [*] or [?(...)]
+        const isArray = /\[\*\]|\[\?/.test(path);
+        return {
+            type: 'jsonpath-embedded',
+            path,
+            embeddedType,
+            isArray,
+            ...(optionalMarker && { optional: true }),
+        };
+    }
+    // Check for JSONPath pattern: $.xxx (must start with $. to avoid matching "$50 price")
+    if (str.startsWith('$.')) {
+        return {
+            type: 'jsonpath',
+            path: str,
+        };
+    }
+    // Check for reference pattern: ->Type, ~>Type, <-Type, <~Type, with optional [], ?, and unions
+    // Pattern: (<-|<~|->|~>)Type1|Type2|...[]?
+    const refMatch = str.match(/^(<-|<~|->|~>)(.+?)(\[\])?(\?)?$/);
+    if (refMatch) {
+        const [, prefix, typesPart, arrayMarker, optionalMarker] = refMatch;
+        const isArray = !!arrayMarker;
+        const optional = !!optionalMarker;
+        // Check for union types (Type1|Type2|...)
+        const types = typesPart.split('|').map((t) => t.trim());
+        // Parse the operator to get direction and mode/fuzzy
+        const parsedOp = parseOperator(prefix);
+        if (parsedOp.direction === 'backward') {
+            // Backward references use direction/mode properties
+            const baseRef = {
+                type: 'reference',
+                isArray,
+                optional,
+                direction: parsedOp.direction,
+                mode: parsedOp.mode,
+            };
+            return types.length > 1 ? { ...baseRef, refs: types } : { ...baseRef, ref: types[0] };
+        }
+        else {
+            // Forward references use fuzzy property (backward compatibility)
+            const baseRef = {
+                type: 'reference',
+                isArray,
+                optional,
+                fuzzy: parsedOp.fuzzy,
+            };
+            return types.length > 1 ? { ...baseRef, refs: types } : { ...baseRef, ref: types[0] };
+        }
+    }
+    // Plain string field
+    return {
+        type: 'string',
+        description: str,
+    };
+}
+/**
+ * Parse a reference field definition for generation.
+ *
+ * Handles patterns like:
+ * - `->Person` - exact reference
+ * - `~>Industry` - fuzzy reference
+ * - `->Type[]` - array of exact references
+ * - `~>Type?` - optional fuzzy reference
+ * - `->User|Organization` - union type reference
+ *
+ * @param fieldDef - The field definition string (e.g., '->Person', '~>Industry?')
+ * @returns ParsedGenerationReference or null if not a reference field
+ *
+ * @example
+ * parseGenerationReference('->Person')
+ * // { mode: 'exact', targetType: 'Person', isOptional: false, isArray: false }
+ *
+ * @example
+ * parseGenerationReference('~>Industry?')
+ * // { mode: 'fuzzy', targetType: 'Industry', isOptional: true, isArray: false }
+ *
+ * @example
+ * parseGenerationReference('->User|Organization')
+ * // { mode: 'exact', targetType: 'User', targetTypes: ['User', 'Organization'], isOptional: false, isArray: false }
+ */
+export function parseGenerationReference(fieldDef) {
+    // Match reference patterns: ->, ~>, with optional ? and []
+    // Pattern supports union types: ->Type1|Type2|Type3
+    const match = fieldDef.match(/^(->|~>)([A-Za-z][A-Za-z0-9]*(?:\|[A-Za-z][A-Za-z0-9]*)*)(\[\])?(\?)?$/);
+    if (!match)
+        return null;
+    const [, operator, typesPart, arrayMarker, optionalMarker] = match;
+    const types = typesPart.split('|').map(t => t.trim());
+    return {
+        mode: operator === '->' ? 'exact' : 'fuzzy',
+        targetType: types[0],
+        ...(types.length > 1 && { targetTypes: types }),
+        isOptional: optionalMarker === '?',
+        isArray: arrayMarker === '[]',
+    };
+}
+/**
+ * Parse array field definition for generation.
+ *
+ * Handles array shorthand like `['~>Investor']` or `['->Person']`.
+ *
+ * @param fieldDef - The field definition array (e.g., ['~>Investor'])
+ * @returns ParsedGenerationReference or null if not a reference array
+ *
+ * @example
+ * parseGenerationArrayReference(['~>Investor'])
+ * // { mode: 'fuzzy', targetType: 'Investor', isOptional: false, isArray: true }
+ */
+export function parseGenerationArrayReference(fieldDef) {
+    if (!Array.isArray(fieldDef) || fieldDef.length !== 1)
+        return null;
+    const inner = fieldDef[0];
+    if (typeof inner !== 'string')
+        return null;
+    const parsed = parseGenerationReference(inner);
+    if (!parsed)
+        return null;
+    return {
+        ...parsed,
+        isArray: true,
+    };
+}
+/**
+ * Check if a field definition is a reference field.
+ *
+ * @param fieldDef - The field definition (string or array)
+ * @returns true if this is a reference field
+ *
+ * @example
+ * isReferenceField('->User')  // true
+ * isReferenceField('~>Industry?')  // true
+ * isReferenceField(['~>Investor'])  // true
+ * isReferenceField('User name')  // false
+ * isReferenceField(['tags'])  // false
+ */
+export function isReferenceField(fieldDef) {
+    if (typeof fieldDef === 'string') {
+        return parseGenerationReference(fieldDef) !== null;
+    }
+    if (Array.isArray(fieldDef)) {
+        return parseGenerationArrayReference(fieldDef) !== null;
+    }
+    return false;
+}
+/**
+ * Extract reference mode from a field definition.
+ *
+ * @param fieldDef - The field definition
+ * @returns 'exact' | 'fuzzy' | null
+ */
+export function getReferenceMode(fieldDef) {
+    if (typeof fieldDef === 'string') {
+        return parseGenerationReference(fieldDef)?.mode ?? null;
+    }
+    if (Array.isArray(fieldDef)) {
+        return parseGenerationArrayReference(fieldDef)?.mode ?? null;
+    }
+    return null;
+}
+/**
+ * Extract target type(s) from a reference field.
+ *
+ * @param fieldDef - The field definition
+ * @returns Target type string, array of types for unions, or null if not a reference
+ */
+export function getReferenceTargetType(fieldDef) {
+    let parsed = null;
+    if (typeof fieldDef === 'string') {
+        parsed = parseGenerationReference(fieldDef);
+    }
+    else if (Array.isArray(fieldDef)) {
+        parsed = parseGenerationArrayReference(fieldDef);
+    }
+    if (!parsed)
+        return null;
+    return parsed.targetTypes ?? parsed.targetType;
+}
+/**
+ * Parse seed configuration from a schema type's `$seed` field.
+ *
+ * Seed configuration tells the system where to fetch initial data for a type,
+ * supporting TSV, CSV, and JSON formats with pagination support.
+ *
+ * @param value - The seed configuration. Can be:
+ *   - `string` - A URL (format inferred from extension: `.csv`, `.json`, or default `.tsv`)
+ *   - `Record<string, string>` - Object with explicit options
+ *
+ * @returns A SeedConfig object with:
+ *   - `url` - The data source URL
+ *   - `format` - Data format ('tsv', 'csv', or 'json')
+ *   - `idField` - Optional field to use as entity ID
+ *   - `next` - Optional JSONPath to pagination URL
+ *   - `data` - Optional JSONPath to data array in response
+ *
+ * @example
+ * // Simple URL (format inferred)
+ * parseSeedConfig('https://example.com/data.csv')
+ * // { url: 'https://example.com/data.csv', format: 'csv' }
+ *
+ * @example
+ * // URL with TSV default
+ * parseSeedConfig('https://example.com/data')
+ * // { url: 'https://example.com/data', format: 'tsv' }
+ *
+ * @example
+ * // Object config with pagination
+ * parseSeedConfig({
+ *   url: 'https://api.example.com/items',
+ *   format: 'json',
+ *   data: '$.items',
+ *   next: '$.pagination.next'
+ * })
+ * // { url: '...', format: 'json', data: '$.items', next: '$.pagination.next' }
+ */
+export function parseSeedConfig(value) {
+    if (typeof value === 'string') {
+        // Infer format from URL extension
+        const url = value;
+        let format = 'tsv';
+        if (url.endsWith('.csv'))
+            format = 'csv';
+        else if (url.endsWith('.json'))
+            format = 'json';
+        return { url, format };
+    }
+    // Object config with explicit options
+    const config = {
+        url: value.url || value.$seed,
+        format: value.format || 'tsv',
+    };
+    if (value.idField)
+        config.idField = value.idField;
+    if (value.next)
+        config.next = value.next;
+    if (value.data)
+        config.data = value.data;
+    return config;
+}
+/**
+ * Converts string fields to prompt fields in a seeded type's field map.
+ *
+ * In seeded schemas, plain string values represent prompts for AI generation
+ * rather than simple field descriptions. This function performs the conversion
+ * after initial field parsing, ensuring that JSONPath fields and reference
+ * fields remain unchanged while string fields become prompt fields.
+ *
+ * @param fields - The parsed fields map from parseFieldType calls
+ * @returns A new fields map with string fields converted to prompt fields
+ *
+ * @example
+ * // Input: fields from a seeded type
+ * const fields = {
+ *   title: { type: 'string', description: 'Some title' },
+ *   jsonField: { type: 'jsonpath', path: '$.name' },
+ *   ref: { type: 'reference', ref: 'Other', isArray: false },
+ * }
+ *
+ * // Output: string -> prompt, others unchanged
+ * const converted = convertStringsToPromptsInSeededType(fields)
+ * // converted.title = { type: 'prompt', prompt: 'Some title' }
+ * // converted.jsonField = { type: 'jsonpath', path: '$.name' }
+ * // converted.ref = { type: 'reference', ref: 'Other', isArray: false }
+ *
+ * @remarks
+ * This function is called during parseSchema when a type has `$seed` defined.
+ * Only StringField types are converted; all other field types pass through unchanged.
+ */
+export function convertStringsToPromptsInSeededType(fields) {
+    const result = {};
+    for (const [fieldName, field] of Object.entries(fields)) {
+        if (isStringField(field)) {
+            result[fieldName] = {
+                type: 'prompt',
+                prompt: field.description,
+            };
+        }
+        else {
+            result[fieldName] = field;
+        }
+    }
+    return result;
+}
+/**
+ * Parse an entire schema definition into a structured ParsedSchema.
+ *
+ * This is the main parsing function that takes a schema definition object and
+ * produces a fully parsed representation with all types, fields, references,
+ * and metadata resolved.
+ *
+ * @param schema - The schema definition object containing type definitions and metadata.
+ *   Metadata fields are prefixed with `$` (e.g., `$id`, `$context`, `$settings`).
+ *   All other keys are treated as type definitions.
+ *
+ * @returns A ParsedSchema object containing:
+ *   - `types` - Record of parsed type definitions with fields and references
+ *   - `hash` - Deterministic hash of the schema for versioning
+ *   - `settings` - Optional schema-level settings (e.g., iconLibrary)
+ *
+ * @example
+ * const schema = parseSchema({
+ *   $id: 'https://db.sb/blog',
+ *   Post: {
+ *     title: 'Post title',
+ *     content: 'Main content',
+ *     author: '->User',
+ *     tags: ['Tag labels']
+ *   },
+ *   User: {
+ *     name: 'User name',
+ *     email: 'Email address',
+ *     posts: '->Post[]'
+ *   }
+ * })
+ *
+ * // schema.types.Post.fields.title
+ * // { type: 'string', description: 'Post title' }
+ *
+ * // schema.types.Post.references
+ * // [{ field: 'author', ref: 'User', isArray: false }]
+ *
+ * @example
+ * // Schema with seed configuration and icons
+ * const schema = parseSchema({
+ *   $context: 'startups',
+ *   $settings: { iconLibrary: 'lucide' },
+ *   Company: {
+ *     $icon: 'building',
+ *     $seed: 'https://api.example.com/companies.json',
+ *     name: 'Company name',
+ *     website: 'Website URL'
+ *   }
+ * })
+ *
+ * // schema.types.Company.icon === 'building'
+ * // schema.types.Company.seed.url === 'https://api.example.com/companies.json'
+ */
+export function parseSchema(schema) {
+    const types = {};
+    // Extract schema-level $settings
+    let settings;
+    const settingsValue = schema.$settings;
+    if (settingsValue && typeof settingsValue === 'object' && settingsValue !== null) {
+        const settingsObj = settingsValue;
+        if (settingsObj.iconLibrary || Object.keys(settingsObj).length > 0) {
+            settings = {};
+            if (typeof settingsObj.iconLibrary === 'string') {
+                settings.iconLibrary = settingsObj.iconLibrary;
+            }
+        }
+    }
+    // First pass: parse all types
+    for (const [typeName, fields] of Object.entries(schema)) {
+        // Skip metadata fields ($ prefixed)
+        if (typeName.startsWith('$'))
+            continue;
+        // Skip if not an object (metadata string values)
+        if (typeof fields !== 'object' || fields === null)
+            continue;
+        const parsedFields = {};
+        const references = [];
+        let seed;
+        let icon;
+        let group;
+        let seedNext;
+        let seedData;
+        let seedId;
+        let seedIdTransform;
+        // Entity lifecycle handlers
+        const entityHandlers = {};
+        // State machine configuration
+        let parsedState;
+        // Data source configurations
+        let source;
+        let input;
+        let from;
+        let cache;
+        // Generative format configurations
+        let image;
+        let speech;
+        let diagram;
+        let conventions;
+        let code;
+        // Entity-level eval and experiment
+        let entityEval;
+        let entityExperiment;
+        for (const [fieldName, fieldValue] of Object.entries(fields)) {
+            // Handle $seed metadata
+            if (fieldName === '$seed') {
+                seed = parseSeedConfig(fieldValue);
+                continue;
+            }
+            // Handle $next metadata (JSONPath to next page URL)
+            if (fieldName === '$next') {
+                if (typeof fieldValue === 'string') {
+                    seedNext = fieldValue;
+                }
+                continue;
+            }
+            // Handle $data metadata (JSONPath to data array)
+            if (fieldName === '$data') {
+                if (typeof fieldValue === 'string') {
+                    seedData = fieldValue;
+                }
+                continue;
+            }
+            // Handle $id metadata (JSONPath or transform for ID field)
+            // Supports: '$.taskID', 'PascalCase($.example)', etc.
+            if (fieldName === '$id') {
+                if (typeof fieldValue === 'string') {
+                    const idConfig = parseIdConfig(fieldValue);
+                    seedId = idConfig.path;
+                    seedIdTransform = idConfig.transform;
+                }
+                continue;
+            }
+            // Handle $icon metadata
+            if (fieldName === '$icon') {
+                if (typeof fieldValue === 'string') {
+                    icon = fieldValue;
+                }
+                continue;
+            }
+            // Handle $group metadata
+            if (fieldName === '$group') {
+                if (typeof fieldValue === 'string') {
+                    group = fieldValue;
+                }
+                continue;
+            }
+            // Handle entity lifecycle handlers ($created, $updated, $deleted)
+            if (fieldName === '$created' || fieldName === '$updated' || fieldName === '$deleted') {
+                if (typeof fieldValue === 'function') {
+                    entityHandlers[fieldName] = serializeFunction(fieldName, fieldValue);
+                }
+                continue;
+            }
+            // Handle $state (state machine definition)
+            if (fieldName === '$state') {
+                if (typeof fieldValue === 'object' && fieldValue !== null && '$initial' in fieldValue) {
+                    parsedState = parseStateConfig(fieldValue);
+                }
+                continue;
+            }
+            // Handle $source (external API source configuration)
+            if (fieldName === '$source') {
+                if (typeof fieldValue === 'object' && fieldValue !== null && !Array.isArray(fieldValue)) {
+                    source = fieldValue;
+                }
+                continue;
+            }
+            // Handle $input (input parameters for source)
+            if (fieldName === '$input') {
+                if (typeof fieldValue === 'object' && fieldValue !== null && !Array.isArray(fieldValue)) {
+                    input = fieldValue;
+                }
+                continue;
+            }
+            // Handle $from (multi-source aggregation)
+            if (fieldName === '$from') {
+                if (Array.isArray(fieldValue)) {
+                    from = fieldValue;
+                }
+                continue;
+            }
+            // Handle $cache (cache duration)
+            if (fieldName === '$cache') {
+                if (typeof fieldValue === 'string') {
+                    cache = fieldValue;
+                }
+                continue;
+            }
+            // Handle $image (image generation configuration)
+            if (fieldName === '$image') {
+                if (typeof fieldValue === 'object' && fieldValue !== null && !Array.isArray(fieldValue)) {
+                    image = fieldValue;
+                }
+                continue;
+            }
+            // Handle $speech (speech/TTS generation configuration)
+            if (fieldName === '$speech') {
+                if (typeof fieldValue === 'object' && fieldValue !== null && !Array.isArray(fieldValue)) {
+                    speech = fieldValue;
+                }
+                continue;
+            }
+            // Handle $diagram (diagram generation configuration)
+            if (fieldName === '$diagram') {
+                if (typeof fieldValue === 'object' && fieldValue !== null && !Array.isArray(fieldValue)) {
+                    diagram = fieldValue;
+                }
+                continue;
+            }
+            // Handle $code (code generation configuration)
+            if (fieldName === '$code') {
+                if (typeof fieldValue === 'object' && fieldValue !== null && !Array.isArray(fieldValue)) {
+                    code = fieldValue;
+                }
+                continue;
+            }
+            // Handle $conventions (naming conventions)
+            if (fieldName === '$conventions') {
+                if (typeof fieldValue === 'object' && fieldValue !== null && !Array.isArray(fieldValue)) {
+                    conventions = fieldValue;
+                }
+                continue;
+            }
+            // Handle $eval (entity-level evaluation definitions)
+            if (fieldName === '$eval') {
+                if (typeof fieldValue === 'object' && fieldValue !== null && !Array.isArray(fieldValue)) {
+                    entityEval = fieldValue;
+                }
+                continue;
+            }
+            // Handle $experiment (entity-level experiment definition)
+            if (fieldName === '$experiment') {
+                if (typeof fieldValue === 'object' && fieldValue !== null && !Array.isArray(fieldValue)) {
+                    entityExperiment = fieldValue;
+                }
+                continue;
+            }
+            const parsed = parseFieldType(fieldValue);
+            parsedFields[fieldName] = parsed;
+            if (parsed.type === 'reference') {
+                const refField = parsed;
+                references.push({
+                    field: fieldName,
+                    ref: refField.ref || refField.refs?.[0] || '',
+                    refs: refField.refs,
+                    isArray: refField.isArray,
+                    optional: refField.optional,
+                    fuzzy: refField.fuzzy,
+                });
+            }
+            else if (parsed.type === 'array') {
+                const arrField = parsed;
+                // Track inline references from arrays
+                if (arrField.refs) {
+                    for (const ref of arrField.refs) {
+                        references.push({
+                            field: fieldName,
+                            ref,
+                            isArray: true,
+                            optional: true, // Inline refs are always optional
+                        });
+                    }
+                }
+                // Track back references (for schema completeness, but these are read-only)
+                if (arrField.backRef) {
+                    references.push({
+                        field: fieldName,
+                        ref: arrField.backRef,
+                        isArray: true,
+                        optional: true, // Back refs are collections
+                        backRef: true, // Mark as back reference - should not trigger generation
+                    });
+                }
+            }
+        }
+        // Merge $next, $data, $id into seed config if present
+        if (seed) {
+            if (seedNext)
+                seed.next = seedNext;
+            if (seedData)
+                seed.data = seedData;
+            if (seedId)
+                seed.id = seedId;
+            if (seedIdTransform)
+                seed.idTransform = seedIdTransform;
+        }
+        // Post-process fields for seeded types: convert string fields to prompt fields
+        // In seeded schemas, plain strings are prompts for AI generation, not string descriptions
+        if (seed) {
+            for (const [fieldName, field] of Object.entries(parsedFields)) {
+                if (field.type === 'string') {
+                    const stringField = field;
+                    parsedFields[fieldName] = {
+                        type: 'prompt',
+                        prompt: stringField.description,
+                    };
+                }
+            }
+        }
+        // Determine if this is a source function type (provider:Type pattern)
+        const isSourceFunction = typeName.includes(':') && !!source;
+        // Determine if this is a generative type
+        const isGenerative = !!(image || speech || diagram || code);
+        types[typeName] = {
+            name: typeName,
+            fields: parsedFields,
+            references,
+            ...(seed && { seed }),
+            ...(icon && { icon }),
+            ...(group && { group }),
+            // Direct lifecycle handler access
+            ...(entityHandlers['$created'] && { $created: entityHandlers['$created'] }),
+            ...(entityHandlers['$updated'] && { $updated: entityHandlers['$updated'] }),
+            ...(entityHandlers['$deleted'] && { $deleted: entityHandlers['$deleted'] }),
+            // Grouped handlers (deprecated)
+            ...(Object.keys(entityHandlers).length > 0 && { handlers: entityHandlers }),
+            // State machine configuration
+            ...(parsedState && { $state: parsedState }),
+            // Data source configurations
+            ...(source && { source }),
+            ...(input && { input }),
+            ...(from && { from }),
+            ...(cache && { cache }),
+            ...(isSourceFunction && { isSourceFunction }),
+            // Generative format configurations
+            ...(image && { image }),
+            ...(speech && { speech }),
+            ...(diagram && { diagram }),
+            ...(code && { code }),
+            ...(conventions && { conventions }),
+            ...(isGenerative && { isGenerative }),
+            // Entity-level eval and experiment
+            ...(entityEval && { eval: entityEval }),
+            ...(entityExperiment && { experiment: entityExperiment }),
+        };
+    }
+    // Second pass: validate references (warn but don't crash on undefined types)
+    for (const type of Object.values(types)) {
+        for (const ref of type.references) {
+            // Check all refs in union types
+            const refsToCheck = ref.refs || [ref.ref];
+            for (const refType of refsToCheck) {
+                if (refType && !types[refType]) {
+                    // Warn instead of throwing - allows app to load with schema errors
+                    console.warn(`Reference to undefined type: ${refType} (in type ${type.name})`);
+                }
+            }
+        }
+        // Also validate jsonpath-embedded fields
+        for (const [fieldName, field] of Object.entries(type.fields)) {
+            if (field.type === 'jsonpath-embedded') {
+                const embeddedType = field.embeddedType;
+                if (!types[embeddedType]) {
+                    console.warn(`JSONPath embedded reference to undefined type: ${embeddedType} (in type ${type.name}.${fieldName})`);
+                }
+            }
+        }
+    }
+    // Third pass: detect embedded types (string fields that exactly match a type name)
+    for (const type of Object.values(types)) {
+        for (const [fieldName, field] of Object.entries(type.fields)) {
+            if (field.type === 'string') {
+                const desc = field.description;
+                // Check for embedded type pattern: TypeName, TypeName?, TypeName[]
+                // Only match if the entire string is a type name (possibly with ? or [] suffix)
+                const embeddedMatch = desc.match(/^(\w+)(\[\])?(\?)?$/);
+                if (embeddedMatch) {
+                    const [, typeName, arrayMarker, optionalMarker] = embeddedMatch;
+                    // Check if the type name exists in our schema
+                    if (types[typeName]) {
+                        // Convert to embedded field
+                        const embeddedField = {
+                            type: 'embedded',
+                            embeddedType: typeName,
+                            isArray: !!arrayMarker,
+                            optional: !!optionalMarker,
+                        };
+                        type.fields[fieldName] = embeddedField;
+                    }
+                }
+            }
+        }
+    }
+    // Parse schema-level directives
+    let fn;
+    let on;
+    let evalDefs;
+    let experiment;
+    let analytics;
+    const schemaObj = schema;
+    // Parse $fn - schema-level functions
+    if (schemaObj.$fn && typeof schemaObj.$fn === 'object') {
+        fn = {};
+        for (const [name, func] of Object.entries(schemaObj.$fn)) {
+            if (typeof func === 'function') {
+                fn[name] = serializeFunction(name, func);
+            }
+        }
+    }
+    // Parse $on - schema-level event handlers
+    if (schemaObj.$on && typeof schemaObj.$on === 'object') {
+        on = {};
+        for (const [name, func] of Object.entries(schemaObj.$on)) {
+            if (typeof func === 'function') {
+                on[name] = serializeFunction(name, func);
+            }
+        }
+    }
+    // Parse $eval - evaluation definitions
+    if (schemaObj.$eval && typeof schemaObj.$eval === 'object') {
+        evalDefs = schemaObj.$eval;
+    }
+    // Parse $experiment - experiment definitions
+    if (schemaObj.$experiment && typeof schemaObj.$experiment === 'object') {
+        experiment = schemaObj.$experiment;
+    }
+    // Parse $analytics - analytics configuration
+    if (schemaObj.$analytics && typeof schemaObj.$analytics === 'object') {
+        analytics = schemaObj.$analytics;
+    }
+    // Parse schema-level lifecycle handlers ($seeded, $ready, $error)
+    const schemaHandlers = {};
+    for (const key of ['$seeded', '$ready', '$error']) {
+        if (typeof schemaObj[key] === 'function') {
+            schemaHandlers[key] = serializeFunction(key, schemaObj[key]);
+        }
+    }
+    return {
+        types,
+        hash: schemaHash(schema),
+        ...(settings && { settings }),
+        ...(fn && { fn }),
+        ...(on && { on }),
+        ...(evalDefs && { eval: evalDefs }),
+        ...(experiment && { experiment }),
+        ...(analytics && { analytics }),
+        ...(Object.keys(schemaHandlers).length > 0 && { handlers: schemaHandlers }),
+    };
+}
+/**
+ * Convert a parsed type definition to a JSON Schema representation.
+ *
+ * Transforms the internal ParsedType format into a standard JSON Schema object
+ * that can be used for validation, documentation, or AI generation prompts.
+ *
+ * @param parsedType - The parsed type definition to convert
+ * @param parsedSchema - Optional full schema for resolving embedded types.
+ *   When provided, embedded types (e.g., `Address` in `address: 'Address'`) are
+ *   recursively expanded into their full JSON Schema representation.
+ * @param seen - Internal set for tracking visited types to prevent infinite recursion
+ *   in circular reference scenarios. Do not pass this parameter manually.
+ *
+ * @returns A JSON Schema object with:
+ *   - `type: 'object'` - Always an object schema
+ *   - `properties` - Map of field names to their JSON Schema definitions
+ *   - `required` - Array of required field names (non-optional fields)
+ *   - `additionalProperties: false` - Strict schema, no extra fields allowed
+ *
+ * @example
+ * const parsed = parseSchema({
+ *   $context: 'blog',
+ *   Post: {
+ *     title: 'Post title',
+ *     author: '->User',
+ *     tags: ['List 3-5 keywords']
+ *   }
+ * })
+ *
+ * const jsonSchema = toJSONSchema(parsed.types.Post, parsed)
+ * // {
+ * //   type: 'object',
+ * //   properties: {
+ * //     title: { type: 'string', description: 'Post title' },
+ * //     author: { type: 'string', description: 'Reference to User (ID)' },
+ * //     tags: { type: 'array', items: { type: 'string' }, minItems: 3, maxItems: 5 }
+ * //   },
+ * //   required: ['title', 'author', 'tags'],
+ * //   additionalProperties: false
+ * // }
+ *
+ * @example
+ * // With embedded types expanded
+ * const schema = parseSchema({
+ *   $context: 'app',
+ *   User: {
+ *     name: 'User name',
+ *     address: 'Address'  // Embedded type
+ *   },
+ *   Address: {
+ *     street: 'Street',
+ *     city: 'City'
+ *   }
+ * })
+ *
+ * const jsonSchema = toJSONSchema(schema.types.User, schema)
+ * // properties.address will contain the full Address schema inline
+ */
+export function toJSONSchema(parsedType, parsedSchemaOrIncludeRefs, seen = new Set()) {
+    // Support both old API (boolean for includeReferences) and new API (ParsedSchema)
+    const parsedSchema = typeof parsedSchemaOrIncludeRefs === 'object' ? parsedSchemaOrIncludeRefs : undefined;
+    const includeReferences = typeof parsedSchemaOrIncludeRefs === 'boolean' ? parsedSchemaOrIncludeRefs : true;
+    const properties = {};
+    const required = [];
+    for (const [fieldName, field] of Object.entries(parsedType.fields)) {
+        // Skip computed fields - they're derived, not generated
+        if (field.type === 'computed') {
+            continue;
+        }
+        const isOptional = 'optional' in field && field.optional;
+        if (field.type === 'string') {
+            properties[fieldName] = {
+                type: 'string',
+                description: field.description,
+            };
+        }
+        else if (field.type === 'reference' && includeReferences) {
+            const refName = field.refs ? field.refs.join(' | ') : field.ref;
+            if (field.isArray) {
+                properties[fieldName] = {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: `Array of ${refName} references (IDs)`,
+                };
+            }
+            else {
+                properties[fieldName] = {
+                    type: 'string',
+                    description: `Reference to ${refName} (ID)`,
+                };
+            }
+        }
+        else if (field.type === 'array') {
+            const arrayProp = {
+                type: 'array',
+                items: { type: 'string' },
+                description: field.description,
+            };
+            // Wire up minItems/maxItems from parsed count
+            if (field.count !== undefined) {
+                if (typeof field.count === 'number') {
+                    arrayProp.minItems = field.count;
+                    arrayProp.maxItems = field.count;
+                }
+                else {
+                    arrayProp.minItems = field.count.min;
+                    arrayProp.maxItems = field.count.max;
+                }
+            }
+            properties[fieldName] = arrayProp;
+        }
+        else if (field.type === 'object') {
+            const nestedProps = {};
+            const nestedRequired = [];
+            for (const [propName, propField] of Object.entries(field.properties)) {
+                nestedProps[propName] = {
+                    type: 'string',
+                    description: propField.description,
+                };
+                nestedRequired.push(propName);
+            }
+            properties[fieldName] = {
+                type: 'object',
+                properties: nestedProps,
+                required: nestedRequired,
+            };
+        }
+        else if (field.type === 'embedded' && parsedSchema) {
+            // Recursively embed the referenced type's JSON schema
+            const embeddedTypeName = field.embeddedType;
+            const embeddedType = parsedSchema.types[embeddedTypeName];
+            if (embeddedType) {
+                // Determine if we're in a circular reference situation
+                const isCircular = seen.has(embeddedTypeName);
+                // Get the embedded type's JSON schema
+                // For circular refs, stop recursion by not passing parsedSchema
+                // For normal refs, continue with updated seen set
+                const newSeen = isCircular ? seen : new Set([...seen, embeddedTypeName]);
+                const embeddedSchema = toJSONSchema(embeddedType, isCircular ? undefined : parsedSchema, newSeen);
+                // Build the embedded object schema
+                const embeddedObjectSchema = {
+                    type: 'object',
+                    properties: embeddedSchema.properties,
+                    required: embeddedSchema.required,
+                    additionalProperties: false,
+                };
+                if (field.isArray) {
+                    properties[fieldName] = {
+                        type: 'array',
+                        items: embeddedObjectSchema,
+                    };
+                }
+                else {
+                    properties[fieldName] = embeddedObjectSchema;
+                }
+            }
+        }
+        else if (field.type === 'embedded') {
+            // If no parsedSchema provided, fall back to string representation
+            properties[fieldName] = {
+                type: 'string',
+                description: field.embeddedType,
+            };
+        }
+        // Only add to required if:
+        // - not optional AND
+        // - (not a reference OR includeReferences is true)
+        const isReference = field.type === 'reference';
+        if (!isOptional && (!isReference || includeReferences)) {
+            required.push(fieldName);
+        }
+    }
+    return {
+        type: 'object',
+        properties,
+        required,
+        additionalProperties: false,
+    };
+}
+/**
+ * Generate a deterministic hash for a schema definition.
+ *
+ * Creates a consistent 8-character hexadecimal hash that uniquely identifies
+ * a schema's structure. The hash is computed using the FNV-1a algorithm on
+ * the JSON-serialized schema with sorted keys, ensuring the same schema
+ * always produces the same hash regardless of property order.
+ *
+ * @param schema - The schema definition to hash
+ *
+ * @returns An 8-character hexadecimal hash string
+ *
+ * @example
+ * const hash1 = schemaHash({
+ *   $context: 'blog',
+ *   Post: { title: 'Title' }
+ * })
+ * // e.g., 'a1b2c3d4'
+ *
+ * // Same schema, different property order = same hash
+ * const hash2 = schemaHash({
+ *   Post: { title: 'Title' },
+ *   $context: 'blog'
+ * })
+ * // hash1 === hash2
+ *
+ * @example
+ * // Used for schema versioning
+ * const schema = parseSchema({ $context: 'app', User: { name: 'Name' } })
+ * console.log(schema.hash)
+ * // The hash can be used to detect schema changes and trigger migrations
+ */
+export function schemaHash(schema) {
+    // Sort keys recursively for consistent hashing
+    const sortedSchema = sortObject(schema);
+    const json = JSON.stringify(sortedSchema);
+    // Simple hash function (FNV-1a)
+    let hash = 2166136261;
+    for (let i = 0; i < json.length; i++) {
+        hash ^= json.charCodeAt(i);
+        hash = (hash * 16777619) >>> 0;
+    }
+    return hash.toString(16).padStart(8, '0');
+}
+function sortObject(obj) {
+    if (typeof obj !== 'object' || obj === null) {
+        return obj;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map(sortObject);
+    }
+    const sorted = {};
+    for (const key of Object.keys(obj).sort()) {
+        sorted[key] = sortObject(obj[key]);
+    }
+    return sorted;
+}
+// ============================================================================
+// SDK Configuration
+// ============================================================================
+/**
+ * Get the default API base URL. Reads environment variable dynamically
+ * to support test mocking.
+ */
+function getDefaultApiBase() {
+    return (typeof process !== 'undefined' && process.env?.DB4AI_API_BASE) || 'https://db4ai.dev';
+}
+function createJob() {
+    return {
+        id: `job_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`,
+        status: 'queued',
+    };
+}
+/**
+ * Internal class for managing entity collection state
+ */
+class EntityCollectionImpl {
+    $type;
+    _items = [];
+    _baseUrl;
+    _namespace;
+    _registerSchema;
+    constructor(typeName, baseUrl, namespace, registerSchema) {
+        this.$type = typeName;
+        this._baseUrl = baseUrl;
+        this._namespace = namespace;
+        this._registerSchema = registerSchema;
+    }
+    get $count() {
+        return this._items.length;
+    }
+    _addItem(item) {
+        this._items.push(item);
+    }
+    _setItems(items) {
+        this._items = items;
+    }
+    _getItems() {
+        return this._items;
+    }
+    [Symbol.iterator]() {
+        return this._items[Symbol.iterator]();
+    }
+    forEach(fn) {
+        const job = createJob();
+        job.status = 'running';
+        try {
+            for (const item of this._items) {
+                fn(item);
+            }
+            job.status = 'completed';
+        }
+        catch (error) {
+            job.status = 'failed';
+            job.error = error instanceof Error ? error : new Error(String(error));
+        }
+        return job;
+    }
+    map(fn) {
+        const items = this._items;
+        return new Combinable(function* () {
+            for (const item of items) {
+                yield fn(item);
+            }
+        });
+    }
+    where(predicate) {
+        const items = this._items;
+        return new Combinable(function* () {
+            for (const item of items) {
+                if (predicate(item)) {
+                    yield item;
+                }
+            }
+        });
+    }
+    async fetchAll() {
+        await this._registerSchema();
+        const url = `${this._baseUrl}/api/${this._namespace}/${this.$type}`;
+        const res = await fetch(url);
+        if (!res.ok) {
+            throw new APIError('GENERATION_FAILED', `Failed to fetch ${this.$type}: ${await res.text()}`, res.status);
+        }
+        const data = await res.json();
+        const items = Array.isArray(data) ? data : data.items || [];
+        this._setItems(items);
+        return items;
+    }
+}
+/**
+ * Create a callable EntityCollection using a Proxy.
+ * The returned object is both a function (factory) and has collection methods/properties.
+ */
+function createEntityCollection(typeName, baseUrl, namespace, registerSchema, factory) {
+    const collection = new EntityCollectionImpl(typeName, baseUrl, namespace, registerSchema);
+    // Create a proxy around the factory function
+    return new Proxy(factory, {
+        get(target, prop) {
+            // Handle Symbol.iterator for iteration
+            if (prop === Symbol.iterator) {
+                return () => collection[Symbol.iterator]();
+            }
+            // Return collection properties and methods
+            if (prop === '$type')
+                return collection.$type;
+            if (prop === '$count')
+                return collection.$count;
+            if (prop === 'forEach')
+                return collection.forEach.bind(collection);
+            if (prop === 'map')
+                return collection.map.bind(collection);
+            if (prop === 'where')
+                return collection.where.bind(collection);
+            if (prop === 'fetchAll')
+                return collection.fetchAll.bind(collection);
+            // Internal methods for testing/manipulation
+            if (prop === '_addItem')
+                return collection._addItem.bind(collection);
+            if (prop === '_setItems')
+                return collection._setItems.bind(collection);
+            if (prop === '_getItems')
+                return collection._getItems.bind(collection);
+            return undefined;
+        },
+        apply(target, thisArg, args) {
+            // When called as a function, invoke the factory
+            return factory(args[0], args[1]);
+        },
+    });
+}
+/**
+ * Extract API base URL from $id
+ * @example
+ * getApiBaseFromId('https://db.sb/blogs') // 'https://db.sb'
+ * getApiBaseFromId('https://startups.db.sb') // 'https://startups.db.sb'
+ * getApiBaseFromId('my-namespace') // undefined (use default)
+ */
+function getApiBaseFromId(id) {
+    // If it's not a URL, return undefined to use default
+    if (!id.startsWith('http://') && !id.startsWith('https://')) {
+        return undefined;
+    }
+    try {
+        const url = new URL(id);
+        return `${url.protocol}//${url.host}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Parse namespace from $id - supports both full URLs and plain namespace strings
+ * @example
+ * parseIdNamespace('https://db.sb/blogs') // 'blogs'
+ * parseIdNamespace('my-namespace') // 'my-namespace'
+ * parseIdNamespace('https://db.sb/') // null
+ */
+function parseIdNamespace(id) {
+    // If it's not a URL, treat the whole string as the namespace
+    if (!id.startsWith('http://') && !id.startsWith('https://')) {
+        const trimmed = id.trim();
+        return trimmed || null;
+    }
+    // Otherwise parse as URL
+    return parseNamespaceFromId(id);
+}
+/**
+ * Resolve all references in a generated object recursively
+ */
+async function resolveReferences(obj, typeName, parsed, baseUrl, namespace, cache) {
+    const type = parsed.types[typeName];
+    if (!type)
+        return obj;
+    const resolved = { ...obj };
+    for (const [fieldName, field] of Object.entries(type.fields)) {
+        const value = obj[fieldName];
+        if (value === undefined || value === null)
+            continue;
+        if (field.type === 'array' && field.refs && Array.isArray(value)) {
+            // Inline references: ['... ->Type'] - resolve each ID to full object
+            const refType = field.refs[0];
+            const resolvedItems = await Promise.all(value.map(async (refId) => {
+                const cacheKey = `${refType}:${refId}`;
+                if (cache.has(cacheKey))
+                    return cache.get(cacheKey);
+                // If refId is already a URL, use it directly; otherwise construct URL
+                const refUrl = refId.startsWith('http://') || refId.startsWith('https://')
+                    ? refId
+                    : `${baseUrl}/api/${namespace}/${refType}/${refId}`;
+                const refRes = await fetch(refUrl);
+                if (!refRes.ok)
+                    return { id: refId, _error: 'Failed to resolve' };
+                const refObj = await refRes.json();
+                cache.set(cacheKey, refObj);
+                // Recursively resolve nested references
+                return resolveReferences(refObj, refType, parsed, baseUrl, namespace, cache);
+            }));
+            resolved[fieldName] = resolvedItems;
+        }
+        else if (field.type === 'reference' && !field.isArray && typeof value === 'string') {
+            // Single reference: ->Type - resolve to full object
+            const refType = field.ref || field.refs?.[0];
+            if (refType) {
+                const cacheKey = `${refType}:${value}`;
+                if (cache.has(cacheKey)) {
+                    resolved[fieldName] = cache.get(cacheKey);
+                }
+                else {
+                    // If value is already a URL, use it directly; otherwise construct URL
+                    const refUrl = value.startsWith('http://') || value.startsWith('https://')
+                        ? value
+                        : `${baseUrl}/api/${namespace}/${refType}/${value}`;
+                    const refRes = await fetch(refUrl);
+                    if (refRes.ok) {
+                        const refObj = await refRes.json();
+                        cache.set(cacheKey, refObj);
+                        resolved[fieldName] = await resolveReferences(refObj, refType, parsed, baseUrl, namespace, cache);
+                    }
+                }
+            }
+        }
+        else if (field.type === 'reference' && field.isArray && Array.isArray(value)) {
+            // Array reference: ->Type[] - resolve each ID to full object
+            const refType = field.ref || field.refs?.[0];
+            if (refType) {
+                const resolvedItems = await Promise.all(value.map(async (refId) => {
+                    const cacheKey = `${refType}:${refId}`;
+                    if (cache.has(cacheKey))
+                        return cache.get(cacheKey);
+                    // If refId is already a URL, use it directly; otherwise construct URL
+                    const refUrl = refId.startsWith('http://') || refId.startsWith('https://')
+                        ? refId
+                        : `${baseUrl}/api/${namespace}/${refType}/${refId}`;
+                    const refRes = await fetch(refUrl);
+                    if (!refRes.ok)
+                        return { id: refId, _error: 'Failed to resolve' };
+                    const refObj = await refRes.json();
+                    cache.set(cacheKey, refObj);
+                    return resolveReferences(refObj, refType, parsed, baseUrl, namespace, cache);
+                }));
+                resolved[fieldName] = resolvedItems;
+            }
+        }
+        // Back references (['<-Type']) are populated by the API, no client-side resolution needed
+    }
+    return resolved;
+}
+/**
+ * Create a database instance from a schema definition.
+ *
+ * This is the main entry point for defining and working with a db4.ai schema.
+ * It parses the schema, registers it with the API, and returns a typed object
+ * that provides access to all defined types as EntityCollections.
+ *
+ * ## API Base URL Configuration
+ *
+ * The SDK determines the API base URL in the following priority order:
+ * 1. Host from `$id` if it's a full URL (e.g., `'https://custom.api.com/myapp'`)
+ * 2. `DB4AI_API_BASE` environment variable
+ * 3. Default: `'https://db4ai.dev'`
+ *
+ * @param schema - The schema definition object. Must include either:
+ *   - `$id` - A URL or namespace identifier (e.g., `'https://db.sb/blog'` or `'blog'`)
+ *   - `$context` - A namespace string (e.g., `'my-app'`)
+ *
+ *   Type definitions are records where keys are type names and values define fields.
+ *
+ * @returns A DBResult object providing:
+ *   - `schema` - The original schema definition
+ *   - `types` - Parsed type definitions
+ *   - `hash` - Schema version hash
+ *   - `namespace` - The resolved namespace
+ *   - `baseUrl` - API base URL
+ *   - `toJSONSchema(typeName)` - Convert a type to JSON Schema
+ *   - `registerSchema()` - Manually register the schema with the API
+ *   - Dynamic type accessors (e.g., `db.Post`, `db.User`) as EntityCollections
+ *
+ * @throws Error if neither `$id` nor `$context` is provided
+ *
+ * @example
+ * // Define a blog schema
+ * const db = DB({
+ *   $context: 'blog',
+ *   Post: {
+ *     title: 'Post title',
+ *     content: 'Main content',
+ *     author: '->User',
+ *     tags: ['List 3-5 keywords']
+ *   },
+ *   User: {
+ *     name: 'User name',
+ *     email: 'Email address'
+ *   }
+ * })
+ *
+ * @example
+ * // Generate a new post
+ * const post = await db.Post('my-first-post', { topic: 'AI' })
+ * console.log(post.title, post.content)
+ *
+ * @example
+ * // Fetch all posts and iterate
+ * await db.Post.fetchAll()
+ * for (const post of db.Post) {
+ *   console.log(post.title)
+ * }
+ *
+ * @example
+ * // Use with full URL
+ * const db = DB({
+ *   $id: 'https://db.sb/startups',
+ *   Company: {
+ *     name: 'Company name',
+ *     description: 'Company description'
+ *   }
+ * })
+ */
+export function DB(schema) {
+    const parsed = parseSchema(schema);
+    const metadata = schema;
+    const schemaId = metadata.$id;
+    const schemaContext = metadata.$context;
+    // Either $id or $context is required
+    if (!schemaId && !schemaContext) {
+        throw new SchemaValidationError('MISSING_CONTEXT', 'Schema must have $id or $context set (e.g., $context: "my-app" or $id: "https://db4ai.dev/my-app")');
+    }
+    // Parse namespace from $id (URL or plain string) or use $context directly
+    let namespace = null;
+    let baseUrl = getDefaultApiBase();
+    if (schemaContext) {
+        // $context is always just a namespace, uses default base URL
+        namespace = schemaContext.trim() || null;
+    }
+    if (schemaId) {
+        // $id can be a full URL or plain namespace
+        namespace = parseIdNamespace(schemaId);
+        // Use $id's host if it's a URL (overrides default/env var)
+        const idBaseUrl = getApiBaseFromId(schemaId);
+        if (idBaseUrl) {
+            baseUrl = idBaseUrl;
+        }
+    }
+    if (!namespace) {
+        throw new SchemaValidationError('MISSING_NAMESPACE', 'Schema must specify a namespace via $context or $id (e.g., $context: "my-app")');
+    }
+    const instances = [];
+    // Track schema registration state
+    let schemaRegistered = false;
+    let schemaRegistrationPromise = null;
+    // Register schema with API (idempotent, cached)
+    async function registerSchema() {
+        if (schemaRegistered)
+            return;
+        if (schemaRegistrationPromise)
+            return schemaRegistrationPromise;
+        schemaRegistrationPromise = (async () => {
+            const res = await fetch(`${baseUrl}/api/${namespace}/schema`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(schema),
+            });
+            if (!res.ok) {
+                const error = await res.text();
+                throw new APIError('REGISTRATION_FAILED', `Failed to register schema: ${error}`, res.status);
+            }
+            schemaRegistered = true;
+        })();
+        return schemaRegistrationPromise;
+    }
+    // Create base result object
+    const base = {
+        schema,
+        types: parsed.types,
+        hash: parsed.hash,
+        id: schemaId,
+        context: schemaContext,
+        namespace,
+        baseUrl,
+        instances,
+        registerSchema,
+        toJSONSchema: (typeName) => {
+            const type = parsed.types[typeName];
+            if (!type)
+                throw new SchemaValidationError('INVALID_FIELD_TYPE', `Unknown type: ${typeName}`);
+            return toJSONSchema(type, parsed);
+        },
+    };
+    // Cache EntityCollections so the same instance is returned each time
+    const collectionCache = new Map();
+    // Create a proxy that handles dynamic type access
+    return new Proxy(base, {
+        get(target, prop) {
+            // Return known properties directly
+            if (prop in target) {
+                return target[prop];
+            }
+            // For type names, return an EntityCollection (cached)
+            const typeName = String(prop);
+            if (parsed.types[typeName]) {
+                // Return cached collection if exists
+                if (collectionCache.has(typeName)) {
+                    return collectionCache.get(typeName);
+                }
+                // Create factory function for this type
+                const factory = async (id, context) => {
+                    // Ensure schema is registered
+                    await registerSchema();
+                    // Build URL with context as query params if provided
+                    let url = `${baseUrl}/api/${namespace}/${typeName}/${id}`;
+                    if (context && Object.keys(context).length > 0) {
+                        const params = new URLSearchParams();
+                        for (const [key, value] of Object.entries(context)) {
+                            if (value !== undefined && value !== null) {
+                                params.set(key, String(value));
+                            }
+                        }
+                        url += `?${params.toString()}`;
+                    }
+                    // Fetch/generate the object with extended timeout for long-running generations
+                    // Default Node.js undici timeout is 300s, but Blog generation can take 80-150s
+                    // We use 10 minutes to handle complex hierarchies with AI latency variance
+                    const controller = new AbortController();
+                    const timeoutId = setTimeout(() => controller.abort(), 600000); // 10 minute timeout
+                    try {
+                        const res = await fetch(url, { signal: controller.signal });
+                        clearTimeout(timeoutId);
+                        if (!res.ok) {
+                            const error = await res.text();
+                            throw new APIError('GENERATION_FAILED', `Failed to generate ${typeName}/${id}: ${error}`, res.status);
+                        }
+                        const obj = await res.json();
+                        // Resolve all references recursively
+                        const cache = new Map();
+                        return resolveReferences(obj, typeName, parsed, baseUrl, namespace, cache);
+                    }
+                    finally {
+                        clearTimeout(timeoutId);
+                    }
+                };
+                // Create and cache the EntityCollection
+                const collection = createEntityCollection(typeName, baseUrl, namespace, registerSchema, factory);
+                collectionCache.set(typeName, collection);
+                return collection;
+            }
+            return undefined;
+        },
+    });
+}
+// ============================================================================
+// Combinable: Lazy cartesian product pipeline builder
+// ============================================================================
+/**
+ * A lazy pipeline builder for cartesian products and collection transformations.
+ *
+ * Combinable provides a fluent API for building transformation pipelines where
+ * no computation happens until a terminal operation is invoked. This enables
+ * efficient processing of large datasets and cartesian products.
+ *
+ * Key features:
+ * - Lazy evaluation: transformations are only applied when results are consumed
+ * - Chainable: all intermediate operations return new Combinable instances
+ * - Iterable: works with for...of loops and spread operator
+ *
+ * Intermediate operations (return Combinable):
+ * - `where(predicate)` - Filter items by predicate
+ * - `map(fn)` - Transform each item
+ * - `take(n)` - Limit to first n items
+ * - `skip(n)` - Skip first n items
+ *
+ * Terminal operations (trigger evaluation):
+ * - `all()` - Collect all results into an array
+ * - `first()` - Get the first result or undefined
+ * - `count()` - Count total results
+ * - Iteration via for...of or spread
+ *
+ * @example
+ * // Basic cartesian product
+ * const pairs = combine([1, 2, 3], ['a', 'b']).all()
+ * // [[1, 'a'], [1, 'b'], [2, 'a'], [2, 'b'], [3, 'a'], [3, 'b']]
+ *
+ * @example
+ * // Chained transformations
+ * const result = combine([1, 2, 3], [10, 20, 30])
+ *   .where(([a, b]) => a + b > 15)
+ *   .map(([a, b]) => a * b)
+ *   .take(3)
+ *   .all()
+ * // [20, 30, 40]
+ *
+ * @example
+ * // Lazy evaluation with for...of
+ * for (const [x, y] of combine(range(1000), range(1000)).take(10)) {
+ *   console.log(x, y)  // Only computes first 10 pairs
+ * }
+ *
+ * @example
+ * // From EntityCollection
+ * await db.User.fetchAll()
+ * const activeUsers = db.User
+ *   .where(user => user.isActive)
+ *   .map(user => user.email)
+ *   .all()
+ */
+export class Combinable {
+    source;
+    constructor(source) {
+        this.source = source;
+    }
+    /**
+     * Filter combinations by predicate
+     */
+    where(predicate) {
+        const source = this.source;
+        return new Combinable(function* () {
+            for (const item of source()) {
+                if (predicate(item)) {
+                    yield item;
+                }
+            }
+        });
+    }
+    /**
+     * Transform each combination
+     */
+    map(fn) {
+        const source = this.source;
+        return new Combinable(function* () {
+            for (const item of source()) {
+                yield fn(item);
+            }
+        });
+    }
+    /**
+     * Limit to first n items
+     */
+    take(n) {
+        const source = this.source;
+        return new Combinable(function* () {
+            let count = 0;
+            for (const item of source()) {
+                if (count >= n)
+                    break;
+                yield item;
+                count++;
+            }
+        });
+    }
+    /**
+     * Skip first n items
+     */
+    skip(n) {
+        const source = this.source;
+        return new Combinable(function* () {
+            let count = 0;
+            for (const item of source()) {
+                if (count >= n) {
+                    yield item;
+                }
+                count++;
+            }
+        });
+    }
+    /**
+     * Collect all results into an array (terminal operation)
+     */
+    all() {
+        return [...this.source()];
+    }
+    /**
+     * Get the first result or undefined (terminal operation)
+     */
+    first() {
+        const iterator = this.source();
+        const result = iterator.next();
+        return result.done ? undefined : result.value;
+    }
+    /**
+     * Count total results (terminal operation)
+     */
+    count() {
+        let count = 0;
+        for (const _ of this.source()) {
+            count++;
+        }
+        return count;
+    }
+    /**
+     * Make Combinable iterable with for...of and spread operator
+     */
+    [Symbol.iterator]() {
+        return this.source();
+    }
+}
+/**
+ * Create cartesian product of multiple iterables.
+ * Returns a lazy Combinable that only computes when iterated or terminal operation is called.
+ *
+ * @example
+ * const result = combine([1, 2], ['a', 'b']).all()
+ * // [[1, 'a'], [1, 'b'], [2, 'a'], [2, 'b']]
+ *
+ * @example
+ * const filtered = combine([1, 2, 3], [10, 20])
+ *   .where(([a, b]) => a + b > 20)
+ *   .map(([a, b]) => a * b)
+ *   .all()
+ */
+export function combine(...iterables) {
+    // Convert iterables to arrays lazily (we need to iterate multiple times)
+    // This is done inside the generator to maintain laziness
+    return new Combinable(function* () {
+        if (iterables.length === 0)
+            return;
+        // Convert to arrays (required for cartesian product - need multiple passes)
+        const arrays = iterables.map((it) => [...it]);
+        // Check for empty arrays - cartesian product with empty set is empty
+        if (arrays.some((arr) => arr.length === 0))
+            return;
+        // Generate cartesian product using indices
+        const indices = new Array(arrays.length).fill(0);
+        const maxIndices = arrays.map((arr) => arr.length);
+        while (true) {
+            // Yield current combination
+            yield indices.map((i, j) => arrays[j][i]);
+            // Increment indices (like counting in mixed radix)
+            let carry = true;
+            for (let i = indices.length - 1; i >= 0 && carry; i--) {
+                indices[i]++;
+                if (indices[i] >= maxIndices[i]) {
+                    indices[i] = 0;
+                }
+                else {
+                    carry = false;
+                }
+            }
+            // If we carried all the way, we're done
+            if (carry)
+                break;
+        }
+    });
+}
+/**
+ * Simple YAML parser for frontmatter
+ * Handles the subset of YAML commonly used in MDX frontmatter:
+ * - Key-value pairs (string values)
+ * - Nested objects (indentation-based)
+ * - Arrays with bracket notation [item1, item2]
+ * - Comments (# ...)
+ * - Multiline strings with | and >
+ */
+function parseYAML(yaml) {
+    // Normalize line endings to LF
+    const normalized = yaml.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+    const lines = normalized.split('\n');
+    const result = {};
+    // Stack for tracking nested objects: [{ obj, indent }]
+    const stack = [{ obj: result, indent: -1 }];
+    // State for multiline strings
+    let multilineKey = null;
+    let multilineIndent = 0;
+    let multilineLines = [];
+    let multilineStyle = null;
+    for (let lineNum = 0; lineNum < lines.length; lineNum++) {
+        const rawLine = lines[lineNum];
+        // Handle multiline string continuation
+        if (multilineKey !== null) {
+            // Check if this line continues the multiline string
+            const lineIndent = rawLine.match(/^(\s*)/)?.[1].length ?? 0;
+            if (lineIndent >= multilineIndent && (rawLine.trim() !== '' || multilineLines.length > 0)) {
+                // This is a continuation of the multiline string
+                multilineLines.push(rawLine.slice(multilineIndent));
+                continue;
+            }
+            else {
+                // End of multiline string - set the value
+                const current = stack[stack.length - 1];
+                if (multilineStyle === '|') {
+                    // Literal block - preserve newlines
+                    current.obj[multilineKey] = multilineLines.join('\n');
+                }
+                else {
+                    // Folded block - join with spaces (single newlines become spaces)
+                    current.obj[multilineKey] = multilineLines.join(' ').replace(/\s+/g, ' ').trim();
+                }
+                multilineKey = null;
+                multilineLines = [];
+                multilineStyle = null;
+            }
+        }
+        // Remove comments (but not inside quoted strings)
+        let line = rawLine;
+        // Simple comment removal - find # that's not inside quotes
+        const hashIndex = line.indexOf('#');
+        if (hashIndex !== -1) {
+            // Check if it's inside quotes by counting quotes before it
+            const beforeHash = line.slice(0, hashIndex);
+            const singleQuotes = (beforeHash.match(/'/g) || []).length;
+            const doubleQuotes = (beforeHash.match(/"/g) || []).length;
+            if (singleQuotes % 2 === 0 && doubleQuotes % 2 === 0) {
+                line = line.slice(0, hashIndex);
+            }
+        }
+        // Skip empty lines
+        if (line.trim() === '')
+            continue;
+        // Calculate indentation
+        const indentMatch = line.match(/^(\s*)/);
+        const indent = indentMatch ? indentMatch[1].length : 0;
+        const content = line.trim();
+        // Pop stack back to appropriate level
+        while (stack.length > 1 && stack[stack.length - 1].indent >= indent) {
+            stack.pop();
+        }
+        // Parse key-value pair
+        const colonIndex = content.indexOf(':');
+        if (colonIndex === -1) {
+            throw new Error(`Invalid YAML at line ${lineNum + 1}: expected key-value pair, got "${content}"`);
+        }
+        const key = content.slice(0, colonIndex).trim();
+        let value = content.slice(colonIndex + 1).trim();
+        // Validate key
+        if (!key) {
+            throw new Error(`Invalid YAML at line ${lineNum + 1}: empty key`);
+        }
+        const current = stack[stack.length - 1];
+        // Handle multiline string indicators
+        if (value === '|' || value === '>') {
+            multilineKey = key;
+            multilineStyle = value;
+            multilineIndent = indent + 2; // Expect content indented from the key
+            multilineLines = [];
+            continue;
+        }
+        if (value === '') {
+            // No value - this is a nested object
+            const nested = {};
+            current.obj[key] = nested;
+            stack.push({ obj: nested, indent });
+        }
+        else if (value.startsWith('[') && !value.endsWith(']')) {
+            // Unclosed array bracket
+            throw new Error(`Invalid YAML at line ${lineNum + 1}: unclosed array bracket in "${content}"`);
+        }
+        else if (value.startsWith('[') && value.endsWith(']')) {
+            // Array notation: [item1, item2, ...]
+            const arrayContent = value.slice(1, -1).trim();
+            if (arrayContent === '') {
+                current.obj[key] = [];
+            }
+            else {
+                // Parse array items - handle quoted strings and unquoted values
+                const items = [];
+                let currentItem = '';
+                let inQuote = null;
+                for (let i = 0; i < arrayContent.length; i++) {
+                    const char = arrayContent[i];
+                    if (inQuote) {
+                        if (char === inQuote) {
+                            inQuote = null;
+                        }
+                        else {
+                            currentItem += char;
+                        }
+                    }
+                    else if (char === '"' || char === "'") {
+                        inQuote = char;
+                    }
+                    else if (char === ',') {
+                        items.push(currentItem.trim());
+                        currentItem = '';
+                    }
+                    else {
+                        currentItem += char;
+                    }
+                }
+                if (currentItem.trim()) {
+                    items.push(currentItem.trim());
+                }
+                current.obj[key] = items;
+            }
+        }
+        else {
+            // String value - remove surrounding quotes if present
+            if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+                value = value.slice(1, -1);
+            }
+            current.obj[key] = value;
+        }
+    }
+    // Handle any remaining multiline string
+    if (multilineKey !== null) {
+        const current = stack[stack.length - 1];
+        if (multilineStyle === '|') {
+            current.obj[multilineKey] = multilineLines.join('\n');
+        }
+        else {
+            current.obj[multilineKey] = multilineLines.join(' ').replace(/\s+/g, ' ').trim();
+        }
+    }
+    return result;
+}
+/**
+ * Parse MDX frontmatter and extract schema definition.
+ *
+ * @param mdx - The MDX content with optional YAML frontmatter
+ * @returns Object with parsed schema and remaining body
+ * @throws Error if YAML syntax is invalid
+ *
+ * @example
+ * const mdx = `---
+ * $context: https://db.sb
+ * Idea:
+ *   concept: What is the concept?
+ * ---
+ *
+ * <App>content</App>`
+ *
+ * const { schema, body } = parseMDX(mdx)
+ * // schema = { $context: 'https://db.sb', Idea: { concept: 'What is the concept?' } }
+ * // body = '\n<App>content</App>'
+ */
+export function parseMDX(mdx) {
+    // Normalize line endings
+    const normalized = mdx.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+    // Check if MDX starts with frontmatter delimiter
+    if (!normalized.startsWith('---')) {
+        // No frontmatter - return empty schema and full content as body
+        return {
+            schema: {},
+            body: mdx,
+        };
+    }
+    // Find the closing frontmatter delimiter
+    // Start searching after the first ---
+    const startIndex = 3; // Length of '---'
+    let endIndex = -1;
+    // Look for --- at the start of a line (after a newline)
+    let searchStart = startIndex;
+    while (searchStart < normalized.length) {
+        const newlineIndex = normalized.indexOf('\n', searchStart);
+        if (newlineIndex === -1)
+            break;
+        // Check if the next line starts with ---
+        if (normalized.slice(newlineIndex + 1, newlineIndex + 4) === '---') {
+            // Verify it's actually the closing delimiter (followed by newline or EOF)
+            const afterDash = normalized[newlineIndex + 4];
+            if (afterDash === undefined || afterDash === '\n' || afterDash === '\r') {
+                endIndex = newlineIndex + 1;
+                break;
+            }
+        }
+        searchStart = newlineIndex + 1;
+    }
+    if (endIndex === -1) {
+        throw new Error('Invalid MDX: unclosed frontmatter (missing closing ---)');
+    }
+    // Extract frontmatter YAML (between the two --- markers)
+    const frontmatter = normalized.slice(startIndex, endIndex).trim();
+    // Extract body (everything after the closing ---)
+    const bodyStart = endIndex + 3; // Skip past ---
+    let body = normalized.slice(bodyStart);
+    // Remove leading newline from body if present (but preserve rest of whitespace)
+    if (body.startsWith('\n')) {
+        body = body.slice(1);
+    }
+    // Parse YAML frontmatter
+    let schema;
+    if (frontmatter === '') {
+        // Empty frontmatter
+        schema = {};
+    }
+    else {
+        try {
+            schema = parseYAML(frontmatter);
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Invalid YAML in frontmatter: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+    return { schema, body };
+}
+// ============================================================================
+// JSX UI Specification Parser
+// ============================================================================
+import { parse as babelParse } from '@babel/parser';
+function isJSXElement(node) {
+    return node?.type === 'JSXElement';
+}
+function isObjectExpression(node) {
+    return node?.type === 'ObjectExpression';
+}
+function isArrayExpression(node) {
+    return node?.type === 'ArrayExpression';
+}
+function isStringLiteral(node) {
+    return node?.type === 'StringLiteral';
+}
+function isNumericLiteral(node) {
+    return node?.type === 'NumericLiteral';
+}
+function isBooleanLiteral(node) {
+    return node?.type === 'BooleanLiteral';
+}
+function isNullLiteral(node) {
+    return node?.type === 'NullLiteral';
+}
+function isIdentifier(node) {
+    return node?.type === 'Identifier';
+}
+function isArrowFunctionExpression(node) {
+    return node?.type === 'ArrowFunctionExpression';
+}
+function isFunctionExpression(node) {
+    return node?.type === 'FunctionExpression';
+}
+function isObjectProperty(node) {
+    return node?.type === 'ObjectProperty';
+}
+/**
+ * Get the element name from a JSX element
+ */
+function getElementName(element) {
+    const name = element.openingElement.name;
+    if (name.type === 'JSXIdentifier') {
+        return name.name;
+    }
+    if (name.type === 'JSXMemberExpression') {
+        // Handle Member.Expression style names
+        const parts = [];
+        let current = name;
+        while (current.type === 'JSXMemberExpression') {
+            parts.unshift(current.property.name);
+            current = current.object;
+        }
+        if (current.type === 'JSXIdentifier') {
+            parts.unshift(current.name);
+        }
+        return parts.join('.');
+    }
+    return '';
+}
+/**
+ * Extract props from a JSX element
+ */
+function extractProps(element, sourceCode) {
+    const props = {};
+    for (const attr of element.openingElement.attributes) {
+        if (attr.type === 'JSXAttribute') {
+            const name = attr.name.type === 'JSXIdentifier' ? attr.name.name : String(attr.name.name);
+            const value = attr.value;
+            if (value === null || value === undefined) {
+                // Boolean prop: <Field searchable />
+                props[name] = true;
+            }
+            else if (value.type === 'StringLiteral') {
+                props[name] = value.value;
+            }
+            else if (value.type === 'JSXExpressionContainer') {
+                props[name] = evaluateExpression(value.expression, sourceCode);
+            }
+        }
+        else if (attr.type === 'JSXSpreadAttribute') {
+            // Handle spread attributes if needed
+            const spreadValue = evaluateExpression(attr.argument, sourceCode);
+            if (typeof spreadValue === 'object' && spreadValue !== null) {
+                Object.assign(props, spreadValue);
+            }
+        }
+    }
+    return props;
+}
+/**
+ * Evaluate a JSX expression to a JavaScript value
+ */
+function evaluateExpression(expr, sourceCode) {
+    if (expr.type === 'JSXEmptyExpression') {
+        return undefined;
+    }
+    if (isStringLiteral(expr)) {
+        return expr.value;
+    }
+    if (isNumericLiteral(expr)) {
+        return expr.value;
+    }
+    if (isBooleanLiteral(expr)) {
+        return expr.value;
+    }
+    if (isNullLiteral(expr)) {
+        return null;
+    }
+    if (isIdentifier(expr)) {
+        // Handle special identifiers
+        if (expr.name === 'undefined')
+            return undefined;
+        if (expr.name === 'true')
+            return true;
+        if (expr.name === 'false')
+            return false;
+        // Return identifier name as string (for field references)
+        return expr.name;
+    }
+    if (isArrayExpression(expr)) {
+        return expr.elements.map((el) => {
+            if (el === null)
+                return null;
+            if (el.type === 'SpreadElement') {
+                return evaluateExpression(el.argument, sourceCode);
+            }
+            return evaluateExpression(el, sourceCode);
+        });
+    }
+    if (isObjectExpression(expr)) {
+        const obj = {};
+        for (const prop of expr.properties) {
+            if (isObjectProperty(prop)) {
+                const key = isIdentifier(prop.key)
+                    ? prop.key.name
+                    : isStringLiteral(prop.key)
+                        ? prop.key.value
+                        : String(prop.key);
+                obj[key] = evaluateExpression(prop.value, sourceCode);
+            }
+            // ObjectMethod handling for hooks
+            if (prop.type === 'ObjectMethod') {
+                const key = isIdentifier(prop.key)
+                    ? prop.key.name
+                    : isStringLiteral(prop.key)
+                        ? prop.key.value
+                        : String(prop.key);
+                // Preserve function as source code string
+                if (prop.start !== null && prop.end !== null) {
+                    obj[key] = sourceCode.slice(prop.start, prop.end);
+                }
+            }
+        }
+        return obj;
+    }
+    if (isArrowFunctionExpression(expr) || isFunctionExpression(expr)) {
+        // Preserve function source for hooks
+        if (expr.start !== null && expr.end !== null) {
+            return sourceCode.slice(expr.start, expr.end);
+        }
+        return '[Function]';
+    }
+    // For complex expressions, preserve as string
+    if (expr.start !== null && expr.end !== null) {
+        return sourceCode.slice(expr.start, expr.end);
+    }
+    return undefined;
+}
+/**
+ * Get child elements of a JSX element, filtering out whitespace-only text
+ */
+function getChildElements(element) {
+    return element.children.filter((child) => {
+        if (!isJSXElement(child))
+            return false;
+        return true;
+    });
+}
+/**
+ * Parse Field configuration from a JSX element
+ */
+function parseFieldConfig(element, sourceCode) {
+    const props = extractProps(element, sourceCode);
+    const config = {
+        name: String(props.name || ''),
+    };
+    if (typeof props.lines === 'number')
+        config.lines = props.lines;
+    if (typeof props.placeholder === 'string')
+        config.placeholder = props.placeholder;
+    if (typeof props.display === 'string')
+        config.display = props.display;
+    if (props.allowCreate === true)
+        config.allowCreate = true;
+    if (props.searchable === true)
+        config.searchable = true;
+    if (Array.isArray(props.preview))
+        config.preview = props.preview;
+    if (props.collapsed === true)
+        config.collapsed = true;
+    if (props.readOnly === true)
+        config.readOnly = true;
+    if (props.required === true)
+        config.required = true;
+    if (typeof props.min === 'number')
+        config.min = props.min;
+    if (typeof props.max === 'number')
+        config.max = props.max;
+    if (typeof props.span === 'number')
+        config.span = props.span;
+    if (props.autoFocus === true)
+        config.autoFocus = true;
+    return config;
+}
+/**
+ * Parse Section configuration from a JSX element
+ */
+function parseSectionConfig(element, sourceCode) {
+    const props = extractProps(element, sourceCode);
+    const config = {
+        label: String(props.label || ''),
+    };
+    if (props.collapsed === true)
+        config.collapsed = true;
+    // Parse child fields and sections
+    const children = [];
+    for (const child of getChildElements(element)) {
+        const childName = getElementName(child);
+        if (childName === 'Field') {
+            children.push(parseFieldConfig(child, sourceCode));
+        }
+        else if (childName === 'Section') {
+            children.push(parseSectionConfig(child, sourceCode));
+        }
+    }
+    if (children.length > 0) {
+        config.children = children;
+    }
+    return config;
+}
+/**
+ * Parse Form configuration from a JSX element
+ */
+function parseFormConfig(element, sourceCode) {
+    const props = extractProps(element, sourceCode);
+    const config = {};
+    if (typeof props.layout === 'string')
+        config.layout = props.layout;
+    if (Array.isArray(props.fields))
+        config.fields = props.fields;
+    // Parse child fields and sections
+    const children = [];
+    for (const child of getChildElements(element)) {
+        const childName = getElementName(child);
+        if (childName === 'Field') {
+            children.push(parseFieldConfig(child, sourceCode));
+        }
+        else if (childName === 'Section') {
+            children.push(parseSectionConfig(child, sourceCode));
+        }
+    }
+    if (children.length > 0) {
+        config.children = children;
+    }
+    return config;
+}
+/**
+ * Parse Template configuration, preserving JSX for runtime
+ */
+function parseTemplateConfig(element, sourceCode) {
+    // Preserve the entire template JSX as a string
+    if (element.start !== null && element.end !== null) {
+        // Get just the children content
+        const openingEnd = element.openingElement.end ?? element.start;
+        const closingStart = element.closingElement?.start ?? element.end;
+        const jsx = sourceCode.slice(openingEnd, closingStart).trim();
+        return { jsx };
+    }
+    return { jsx: '' };
+}
+/**
+ * Parse display component (Table, Grid, Cards)
+ */
+function parseDisplayConfig(element, sourceCode) {
+    const name = getElementName(element);
+    const props = extractProps(element, sourceCode);
+    const config = {
+        type: name.toLowerCase(),
+    };
+    if (Array.isArray(props.columns))
+        config.columns = props.columns;
+    if (props.sortable === true)
+        config.sortable = true;
+    // Look for Template child
+    for (const child of getChildElements(element)) {
+        if (getElementName(child) === 'Template') {
+            config.template = parseTemplateConfig(child, sourceCode);
+            break;
+        }
+    }
+    return config;
+}
+/**
+ * Parse Search configuration
+ */
+function parseSearchConfig(element, sourceCode) {
+    const props = extractProps(element, sourceCode);
+    const config = {};
+    if (Array.isArray(props.fields))
+        config.fields = props.fields;
+    return config;
+}
+/**
+ * Parse Filter configuration
+ */
+function parseFilterConfig(element, sourceCode) {
+    const props = extractProps(element, sourceCode);
+    return {
+        field: String(props.field || ''),
+        exists: props.exists === true ? true : undefined,
+    };
+}
+/**
+ * Parse view configuration (List, Detail, Edit, Create)
+ */
+function parseViewConfig(element, sourceCode) {
+    const config = {};
+    for (const child of getChildElements(element)) {
+        const childName = getElementName(child);
+        switch (childName) {
+            case 'Search':
+                config.search = parseSearchConfig(child, sourceCode);
+                break;
+            case 'Filters': {
+                config.filters = [];
+                for (const filterChild of getChildElements(child)) {
+                    if (getElementName(filterChild) === 'Filter') {
+                        config.filters.push(parseFilterConfig(filterChild, sourceCode));
+                    }
+                }
+                break;
+            }
+            case 'Table':
+            case 'Grid':
+            case 'Cards':
+                config.display = parseDisplayConfig(child, sourceCode);
+                break;
+            case 'Form':
+                config.form = parseFormConfig(child, sourceCode);
+                break;
+            case 'Template':
+                config.template = parseTemplateConfig(child, sourceCode);
+                break;
+            case 'Editor': {
+                const props = extractProps(child, sourceCode);
+                config.editor = { language: String(props.language || 'yaml') };
+                break;
+            }
+        }
+    }
+    return config;
+}
+/**
+ * Parse Actions container
+ */
+function parseActionsConfig(element, schemaTypes, sourceCode) {
+    const actions = [];
+    for (const child of getChildElements(element)) {
+        const childName = getElementName(child);
+        const props = extractProps(child, sourceCode);
+        if (childName === 'Delete') {
+            actions.push({
+                type: 'delete',
+                confirm: typeof props.confirm === 'string' ? props.confirm : undefined,
+            });
+        }
+        else if (childName === 'Duplicate') {
+            actions.push({ type: 'duplicate' });
+        }
+        else if (childName === 'Export') {
+            actions.push({
+                type: 'export',
+                formats: Array.isArray(props.formats) ? props.formats : undefined,
+            });
+        }
+        else if (childName === 'Import') {
+            actions.push({ type: 'import' });
+        }
+        else if (schemaTypes.has(childName)) {
+            // Entity reference = generate action
+            actions.push({
+                type: 'generate',
+                entity: childName,
+                context: Array.isArray(props.context) ? props.context : undefined,
+            });
+        }
+    }
+    return actions;
+}
+/**
+ * Parse Permissions container
+ */
+function parsePermissionsConfig(element, sourceCode) {
+    const roles = [];
+    for (const child of getChildElements(element)) {
+        if (getElementName(child) === 'Role') {
+            const props = extractProps(child, sourceCode);
+            roles.push({
+                name: String(props.name || ''),
+                actions: Array.isArray(props.actions) ? props.actions : [],
+            });
+        }
+    }
+    return roles;
+}
+/**
+ * Parse a collection element (schema type)
+ */
+function parseCollectionConfig(element, schemaTypes, sourceCode) {
+    const props = extractProps(element, sourceCode);
+    const config = {};
+    // Top-level collection props
+    if (typeof props.view === 'string')
+        config.view = props.view;
+    if (Array.isArray(props.columns))
+        config.columns = props.columns;
+    if (props.searchable === true)
+        config.searchable = true;
+    if (typeof props.path === 'string')
+        config.path = props.path;
+    if (typeof props.slug === 'string')
+        config.slug = props.slug;
+    // Parse child views and configurations
+    for (const child of getChildElements(element)) {
+        const childName = getElementName(child);
+        switch (childName) {
+            case 'List':
+                config.list = parseViewConfig(child, sourceCode);
+                break;
+            case 'Detail':
+                config.detail = parseViewConfig(child, sourceCode);
+                break;
+            case 'Edit':
+                config.edit = parseViewConfig(child, sourceCode);
+                break;
+            case 'Create':
+                config.create = parseViewConfig(child, sourceCode);
+                break;
+            case 'Actions':
+                config.actions = parseActionsConfig(child, schemaTypes, sourceCode);
+                break;
+            case 'Permissions':
+                config.permissions = parsePermissionsConfig(child, sourceCode);
+                break;
+        }
+    }
+    return config;
+}
+/**
+ * Parse navigation structure, distinguishing between groups and collections
+ */
+function parseNavigationElement(element, schemaTypes, collections, sourceCode) {
+    const name = getElementName(element);
+    const props = extractProps(element, sourceCode);
+    // If this is a schema type, it's a collection
+    if (schemaTypes.has(name)) {
+        // Parse and store collection config
+        collections[name] = parseCollectionConfig(element, schemaTypes, sourceCode);
+        return name;
+    }
+    // Otherwise it's a navigation group
+    const group = {
+        name,
+        children: [],
+    };
+    if (typeof props.icon === 'string') {
+        group.icon = props.icon;
+    }
+    // Parse children
+    for (const child of getChildElements(element)) {
+        const childResult = parseNavigationElement(child, schemaTypes, collections, sourceCode);
+        group.children.push(childResult);
+    }
+    return group;
+}
+/**
+ * Parse hooks from the App element's hooks prop
+ */
+function parseHooksFromProp(hooksProp, sourceCode) {
+    const hooks = {};
+    if (typeof hooksProp !== 'object' || hooksProp === null) {
+        return hooks;
+    }
+    for (const [typeName, typeHooks] of Object.entries(hooksProp)) {
+        if (typeof typeHooks !== 'object' || typeHooks === null)
+            continue;
+        const entityHooks = {};
+        const hooksObj = typeHooks;
+        // Preserve hooks as function source strings
+        if (hooksObj.onCreate !== undefined) {
+            entityHooks.onCreate = hooksObj.onCreate;
+        }
+        if (hooksObj.onUpdate !== undefined) {
+            entityHooks.onUpdate = hooksObj.onUpdate;
+        }
+        if (hooksObj.onDelete !== undefined) {
+            entityHooks.onDelete = hooksObj.onDelete;
+        }
+        if (Object.keys(entityHooks).length > 0) {
+            hooks[typeName] = entityHooks;
+        }
+    }
+    return hooks;
+}
+/**
+ * Parse JSX UI specification into UIConfig
+ *
+ * @param jsx - The JSX string to parse
+ * @param schema - The parsed schema to determine which elements are collections
+ * @returns Parsed UI configuration
+ * @throws Error if JSX syntax is invalid or no App root element
+ *
+ * @example
+ * const jsx = `
+ *   <App hooks={{ Startup: { onCreate: async () => {} } }}>
+ *     <Planning icon="lightbulb">
+ *       <Idea view="cards" />
+ *     </Planning>
+ *   </App>
+ * `
+ * const config = parseJSXUI(jsx, schema)
+ * // config.hooks = { Startup: { onCreate: ... } }
+ * // config.navigation = [{ name: 'Planning', icon: 'lightbulb', children: ['Idea'] }]
+ * // config.collections = { Idea: { view: 'cards' } }
+ */
+export function parseJSXUI(jsx, schema) {
+    // Parse JSX using Babel
+    let ast;
+    try {
+        ast = babelParse(jsx, {
+            plugins: ['jsx'],
+            sourceType: 'module',
+        });
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            throw new Error(`Invalid JSX syntax: ${error.message}`);
+        }
+        throw new Error('Invalid JSX syntax');
+    }
+    // Get schema type names for distinguishing collections from groups
+    const schemaTypes = new Set(Object.keys(schema.types));
+    // Find the root App element
+    let appElement = null;
+    // Walk the AST to find JSX elements
+    function findApp(node) {
+        if (isJSXElement(node)) {
+            if (getElementName(node) === 'App') {
+                appElement = node;
+                return;
+            }
+            // Check children
+            for (const child of node.children) {
+                findApp(child);
+            }
+        }
+        // Handle ExpressionStatement wrapping JSX
+        if (node.type === 'ExpressionStatement' && isJSXElement(node.expression)) {
+            findApp(node.expression);
+        }
+        // Handle Program body
+        if (node.type === 'Program') {
+            for (const stmt of node.body) {
+                findApp(stmt);
+            }
+        }
+        // Handle File
+        if (node.type === 'File') {
+            findApp(node.program);
+        }
+    }
+    findApp(ast);
+    if (!appElement) {
+        throw new Error('No <App> root element found in JSX');
+    }
+    // Initialize result
+    const result = {
+        hooks: {},
+        navigation: [],
+        collections: {},
+    };
+    // Extract hooks from App props
+    const appProps = extractProps(appElement, jsx);
+    if (appProps.hooks) {
+        result.hooks = parseHooksFromProp(appProps.hooks, jsx);
+    }
+    // Parse children of App as navigation/collections
+    for (const child of getChildElements(appElement)) {
+        const parsed = parseNavigationElement(child, schemaTypes, result.collections, jsx);
+        if (typeof parsed === 'string') {
+            // Top-level collection (unusual but possible)
+            result.navigation.push({
+                name: parsed,
+                children: [],
+            });
+        }
+        else {
+            result.navigation.push(parsed);
+        }
+    }
+    return result;
+}
+/**
+ * Process an MDX file and return all parsed components.
+ */
+export function processMDX(mdx) {
+    const { schema, body } = parseMDX(mdx);
+    const parsedSchema = parseSchema(schema);
+    const uiConfig = parseJSXUI(body, parsedSchema);
+    return { schema, parsedSchema, uiConfig, rawBody: body };
+}
+//# sourceMappingURL=index.js.map