@stream44.studio/encapsulate 0.2.0-rc.2 → 0.2.0-rc.4

package/src/spine-contracts/CapsuleSpineContract.v0/Membrane.v0.ts

@@ -1,90 +1,5 @@
 import { CapsulePropertyTypes } from "../../encapsulate"
-import { ContractCapsuleInstanceFactory } from "./Static.v0"
-
-function parseCallerFromStack(stack: string, spineFilesystemRoot?: string): Array<{ function?: string, filepath?: string, line?: number, column?: number }> {
-    const lines = stack.split('\n')
-    const result: Array<{ function?: string, filepath?: string, line?: number, column?: number }> = []
-
-    // Skip first line (Error message), then collect ALL frames
-    for (let i = 1; i < lines.length; i++) {
-        const line = lines[i].trim()
-
-        // Match various stack trace formats:
-        // "at functionName (/path/to/file:line:column)"
-        // "at /path/to/file:line:column"
-        // "at functionName (file:line:column)"
-        const match = line.match(/at\s+(.+)/)
-        if (match) {
-            const frame: { function?: string, filepath?: string, line?: number, column?: number } = {}
-            const content = match[1]
-
-            // Try to extract function name and location
-            const funcMatch = content.match(/^(.+?)\s+\((.+)\)$/)
-            if (funcMatch) {
-                // Has function name: "functionName (/path/to/file:line:column)"
-                const funcName = funcMatch[1].trim()
-                // Only include function name if not anonymous
-                if (funcName !== '<anonymous>' && funcName !== 'async <anonymous>') {
-                    frame.function = funcName
-                }
-                const location = funcMatch[2]
-                const locMatch = location.match(/^(.+):(\d+):(\d+)$/)
-                if (locMatch) {
-                    frame.filepath = locMatch[1]
-                    frame.line = parseInt(locMatch[2], 10)
-                    frame.column = parseInt(locMatch[3], 10)
-                }
-            } else {
-                // No function name: "/path/to/file:line:column"
-                const locMatch = content.match(/^(.+):(\d+):(\d+)$/)
-                if (locMatch) {
-                    frame.filepath = locMatch[1]
-                    frame.line = parseInt(locMatch[2], 10)
-                    frame.column = parseInt(locMatch[3], 10)
-                }
-            }
-
-            // Convert absolute paths to relative paths if spineFilesystemRoot is provided
-            if (frame.filepath && spineFilesystemRoot) {
-                if (frame.filepath.startsWith(spineFilesystemRoot)) {
-                    frame.filepath = frame.filepath.slice(spineFilesystemRoot.length)
-                    // Remove leading slash if present
-                    if (frame.filepath.startsWith('/')) {
-                        frame.filepath = frame.filepath.slice(1)
-                    }
-                }
-            }
-
-            // Include all frames, even if incomplete
-            if (frame.filepath || frame.function) {
-                result.push(frame)
-            }
-        }
-    }
-    return result
-}
-
-function extractCallerInfo(stack: Array<{ function?: string, filepath?: string, line?: number, column?: number }>, offset: number = 0) {
-    // Use offset to skip frames in the stack
-    // offset 0 = first frame, offset 1 = second frame, etc.
-
-    if (offset < stack.length) {
-        const frame = stack[offset]
-        return {
-            filepath: frame.filepath,
-            line: frame.line
-        }
-    }
-
-    // Fallback to first frame if offset is out of bounds
-    if (stack.length > 0) {
-        return {
-            filepath: stack[0].filepath,
-            line: stack[0].line
-        }
-    }
-    return {}
-}
+import { ContractCapsuleInstanceFactory, CapsuleInstanceRegistry } from "./Static.v0"
 
 type CallerContext = {
     capsuleSourceLineRef: string
@@ -144,13 +59,14 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
     private encapsulateOptions: any
     private capsuleSourceNameRef?: string
     private capsuleSourceNameRefHash?: string
-    private runtimeSpineContracts?: Record<string, any>
+    protected override runtimeSpineContracts?: Record<string, any>
     public id: string
 
     constructor({
         spineContractUri,
         capsule,
         self,
+        ownSelf,
         encapsulatedApi,
         resolve,
         importCapsule,
@@ -162,11 +78,14 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
         getEventIndex,
         incrementEventIndex,
         currentCallerContext,
-        runtimeSpineContracts
+        runtimeSpineContracts,
+        instanceRegistry,
+        extendedCapsuleInstance
     }: {
         spineContractUri: string
         capsule: any
         self: any
+        ownSelf?: any
         encapsulatedApi: Record<string, any>
         resolve?: (uri: string, parentFilepath: string) => Promise<string>
         importCapsule?: (filepath: string) => Promise<any>
@@ -179,8 +98,10 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
         incrementEventIndex: () => number
         currentCallerContext?: CallerContext
         runtimeSpineContracts?: Record<string, any>
+        instanceRegistry?: CapsuleInstanceRegistry
+        extendedCapsuleInstance?: any
     }) {
-        super({ spineContractUri, capsule, self, encapsulatedApi, resolve, importCapsule, spineFilesystemRoot, freezeCapsule })
+        super({ spineContractUri, capsule, self, ownSelf, encapsulatedApi, resolve, importCapsule, spineFilesystemRoot, freezeCapsule, instanceRegistry, extendedCapsuleInstance })
         this.getEventIndex = getEventIndex
         this.incrementEventIndex = incrementEventIndex
         this.currentCallerContext = currentCallerContext
@@ -202,9 +123,84 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
         const mappedCapsule = await this.resolveMappedCapsule({ property })
         const constants = await this.extractConstants({ mappedCapsule })
 
-        const mappingOptions = await property.definition.options?.({
-            constants
-        })
+        // delegateOptions is set by encapsulate.ts for property contract delegates
+        // options can be a function or an object for regular mappings
+        const mappingOptions = property.definition.delegateOptions
+            || (typeof property.definition.options === 'function'
+                ? await property.definition.options({ constants })
+                : property.definition.options)
+
+        // Check for existing instance in registry - reuse if available (regardless of options)
+        // Pre-registration with null allows parent capsules to "claim" a slot before child capsules process
+        const capsuleName = mappedCapsule.encapsulateOptions?.capsuleName
+
+        if (capsuleName && this.instanceRegistry) {
+            if (this.instanceRegistry.has(capsuleName)) {
+                const existingEntry = this.instanceRegistry.get(capsuleName)
+
+                // If entry is null (pre-registered) or actual instance, and current mapping has no options, use deferred proxy
+                if (!mappingOptions) {
+                    // Use deferred proxy that resolves from registry when accessed
+                    const apiTarget = this.getApiTarget({ property })
+                    const registry = this.instanceRegistry
+                    apiTarget[property.name] = new Proxy({} as any, {
+                        get: (_target: any, apiProp: string | symbol) => {
+                            if (typeof apiProp === 'symbol') return undefined
+                            const resolvedInstance = registry.get(capsuleName)
+                            if (!resolvedInstance) {
+                                throw new Error(`Capsule instance not yet resolved: ${capsuleName}`)
+                            }
+
+                            this.currentCallerContext = {
+                                capsuleSourceLineRef: this.encapsulateOptions.capsuleSourceLineRef,
+                                capsuleSourceNameRef: this.capsuleSourceNameRef,
+                                spineContractCapsuleInstanceId: this.id,
+                                capsuleSourceNameRefHash: this.capsuleSourceNameRefHash,
+                                prop: apiProp as string
+                            }
+
+                            if (this.enableCallerStackInference) {
+                                const stackStr = new Error('[MAPPED_CAPSULE]').stack
+                                if (stackStr) {
+                                    const stackFrames = parseCallerFromStack(stackStr, this.spineFilesystemRoot)
+                                    if (stackFrames.length > 0) {
+                                        const callerInfo = extractCallerInfo(stackFrames, 3)
+                                        this.currentCallerContext.filepath = callerInfo.filepath
+                                        this.currentCallerContext.line = callerInfo.line
+                                        this.currentCallerContext.stack = stackFrames
+                                    }
+                                }
+                            }
+
+                            // Access through .api if it exists (for capsule instances with getters)
+                            if (resolvedInstance.api && apiProp in resolvedInstance.api) {
+                                return resolvedInstance.api[apiProp]
+                            }
+                            return resolvedInstance[apiProp]
+                        }
+                    })
+                    this.self[property.name] = new Proxy({} as any, {
+                        get: (_target, prop) => {
+                            if (typeof prop === 'symbol') return undefined
+                            const resolvedInstance = registry.get(capsuleName)
+                            if (!resolvedInstance) {
+                                throw new Error(`Capsule instance not yet resolved: ${capsuleName}`)
+                            }
+                            const value = resolvedInstance.api?.[prop]
+                            if (value && typeof value === 'object' && value.api) {
+                                return value.api
+                            }
+                            return value
+                        }
+                    })
+                    return
+                }
+                // If current mapping has options, fall through to create new instance
+            } else {
+                // Pre-register as null to claim the slot for this capsule
+                this.instanceRegistry.set(capsuleName, null)
+            }
+        }
 
         // Transform overrides if this mapping has a propertyContractDelegate
         let mappedOverrides = overrides
@@ -237,6 +233,12 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
             runtimeSpineContracts: this.runtimeSpineContracts
         })
 
+        // Register the instance (replaces null pre-registration marker)
+        // Always register to make instance available for child capsules with deferred proxies
+        if (capsuleName && this.instanceRegistry) {
+            this.instanceRegistry.set(capsuleName, mappedCapsuleInstance)
+        }
+
         const apiTarget = this.getApiTarget({ property })
         apiTarget[property.name] = new Proxy(mappedCapsuleInstance, {
             get: (apiTarget: any, apiProp: string | symbol) => {
@@ -263,6 +265,10 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
                     }
                 }
 
+                // Access through .api if it exists (for capsule instances with getters)
+                if (apiTarget.api && apiProp in apiTarget.api) {
+                    return apiTarget.api[apiProp]
+                }
                 return apiTarget[apiProp]
             }
         })
@@ -402,27 +408,7 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
     }
 
     protected mapFunctionProperty({ property }: { property: any }) {
-
-        // Create a proxy for this.self that intercepts property access
-        // Prefer this.self (which has unwrapped APIs) over encapsulatedApi
-        const selfProxy = new Proxy(this.self, {
-            get: (target: any, prop: string | symbol) => {
-                if (typeof prop === 'symbol') return target[prop]
-
-                // First check if the property exists in target (this.self)
-                if (prop in target) {
-                    return target[prop]
-                }
-
-                // Fall back to encapsulatedApi
-                if (prop in this.encapsulatedApi) {
-                    return this.encapsulatedApi[prop]
-                }
-
-                return undefined
-            }
-        })
-
+        const selfProxy = this.createSelfProxy()
         const boundFunction = property.definition.value.bind(selfProxy)
 
         const valueKey = `__value_${property.name}`
@@ -481,26 +467,7 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
 
     protected mapGetterFunctionProperty({ property }: { property: any }) {
         const getterFn = property.definition.value
-
-        // Create a proxy for this.self that intercepts property access
-        // Prefer this.self (which has unwrapped APIs) over encapsulatedApi
-        const selfProxy = new Proxy(this.self, {
-            get: (target: any, prop: string | symbol) => {
-                if (typeof prop === 'symbol') return target[prop]
-
-                // First check if the property exists in target (this.self)
-                if (prop in target) {
-                    return target[prop]
-                }
-
-                // Fall back to encapsulatedApi
-                if (prop in this.encapsulatedApi) {
-                    return this.encapsulatedApi[prop]
-                }
-
-                return undefined
-            }
-        })
+        const selfProxy = this.createSelfProxy()
 
         Object.defineProperty(this.encapsulatedApi, property.name, {
             get: () => {
@@ -532,6 +499,18 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
             enumerable: true,
             configurable: true
         })
+
+        // Also define the getter on ownSelf so this.self.propertyName works for getter functions
+        // This ensures this.self accesses the getter, not a raw value
+        if (this.ownSelf) {
+            Object.defineProperty(this.ownSelf, property.name, {
+                get: () => {
+                    return getterFn.call(selfProxy)
+                },
+                enumerable: true,
+                configurable: true
+            })
+        }
     }
 
     private addCallerContextToEvent(event: any): void {
@@ -592,14 +571,17 @@ export function CapsuleSpineContract({
 
     let eventIndex = 0
     let currentCallerContext: CallerContext | undefined = undefined
+    const instanceRegistry: CapsuleInstanceRegistry = new Map()
 
     return {
         '#': CapsuleSpineContract['#'],
-        makeContractCapsuleInstance: ({ encapsulateOptions, spineContractUri, self, capsule, encapsulatedApi, runtimeSpineContracts }: { encapsulateOptions: any, spineContractUri: string, self: any, capsule?: any, encapsulatedApi: Record<string, any>, runtimeSpineContracts?: Record<string, any> }) => {
+        instanceRegistry,
+        makeContractCapsuleInstance: ({ encapsulateOptions, spineContractUri, self, ownSelf, capsule, encapsulatedApi, runtimeSpineContracts, extendedCapsuleInstance }: { encapsulateOptions: any, spineContractUri: string, self: any, ownSelf?: any, capsule?: any, encapsulatedApi: Record<string, any>, runtimeSpineContracts?: Record<string, any>, extendedCapsuleInstance?: any }) => {
             return new MembraneContractCapsuleInstanceFactory({
                 spineContractUri,
                 capsule,
                 self,
+                ownSelf,
                 encapsulatedApi,
                 spineFilesystemRoot,
                 freezeCapsule,
@@ -611,7 +593,9 @@ export function CapsuleSpineContract({
                 getEventIndex: () => eventIndex,
                 incrementEventIndex: () => eventIndex++,
                 currentCallerContext,
-                runtimeSpineContracts
+                runtimeSpineContracts,
+                instanceRegistry,
+                extendedCapsuleInstance
             })
         },
         hydrate: ({ capsuleSnapshot }: { capsuleSnapshot: any }): any => {
@@ -622,3 +606,91 @@ export function CapsuleSpineContract({
 
 CapsuleSpineContract['#'] = '@stream44.studio/encapsulate/spine-contracts/CapsuleSpineContract.v0'
 
+
+
+
+function parseCallerFromStack(stack: string, spineFilesystemRoot?: string): Array<{ function?: string, filepath?: string, line?: number, column?: number }> {
+    const lines = stack.split('\n')
+    const result: Array<{ function?: string, filepath?: string, line?: number, column?: number }> = []
+
+    // Skip first line (Error message), then collect ALL frames
+    for (let i = 1; i < lines.length; i++) {
+        const line = lines[i].trim()
+
+        // Match various stack trace formats:
+        // "at functionName (/path/to/file:line:column)"
+        // "at /path/to/file:line:column"
+        // "at functionName (file:line:column)"
+        const match = line.match(/at\s+(.+)/)
+        if (match) {
+            const frame: { function?: string, filepath?: string, line?: number, column?: number } = {}
+            const content = match[1]
+
+            // Try to extract function name and location
+            const funcMatch = content.match(/^(.+?)\s+\((.+)\)$/)
+            if (funcMatch) {
+                // Has function name: "functionName (/path/to/file:line:column)"
+                const funcName = funcMatch[1].trim()
+                // Only include function name if not anonymous
+                if (funcName !== '<anonymous>' && funcName !== 'async <anonymous>') {
+                    frame.function = funcName
+                }
+                const location = funcMatch[2]
+                const locMatch = location.match(/^(.+):(\d+):(\d+)$/)
+                if (locMatch) {
+                    frame.filepath = locMatch[1]
+                    frame.line = parseInt(locMatch[2], 10)
+                    frame.column = parseInt(locMatch[3], 10)
+                }
+            } else {
+                // No function name: "/path/to/file:line:column"
+                const locMatch = content.match(/^(.+):(\d+):(\d+)$/)
+                if (locMatch) {
+                    frame.filepath = locMatch[1]
+                    frame.line = parseInt(locMatch[2], 10)
+                    frame.column = parseInt(locMatch[3], 10)
+                }
+            }
+
+            // Convert absolute paths to relative paths if spineFilesystemRoot is provided
+            if (frame.filepath && spineFilesystemRoot) {
+                if (frame.filepath.startsWith(spineFilesystemRoot)) {
+                    frame.filepath = frame.filepath.slice(spineFilesystemRoot.length)
+                    // Remove leading slash if present
+                    if (frame.filepath.startsWith('/')) {
+                        frame.filepath = frame.filepath.slice(1)
+                    }
+                }
+            }
+
+            // Include all frames, even if incomplete
+            if (frame.filepath || frame.function) {
+                result.push(frame)
+            }
+        }
+    }
+    return result
+}
+
+function extractCallerInfo(stack: Array<{ function?: string, filepath?: string, line?: number, column?: number }>, offset: number = 0) {
+    // Use offset to skip frames in the stack
+    // offset 0 = first frame, offset 1 = second frame, etc.
+
+    if (offset < stack.length) {
+        const frame = stack[offset]
+        return {
+            filepath: frame.filepath,
+            line: frame.line
+        }
+    }
+
+    // Fallback to first frame if offset is out of bounds
+    if (stack.length > 0) {
+        return {
+            filepath: stack[0].filepath,
+            line: stack[0].line
+        }
+    }
+    return {}
+}
+