@stream44.studio/encapsulate 0.4.0-rc.34 → 0.4.0-rc.39

package/src/spine-contracts/CapsuleSpineContract.v0/{Static.v0.ts → Static.ts}

@@ -23,6 +23,7 @@ export class ContractCapsuleInstanceFactory {
     public structDisposeFunctions: Array<() => any> = []
     public initFunctions: Array<() => any> = []
     public disposeFunctions: Array<() => any> = []
+    public onFreezeFunctions: Array<() => any> = []
     public mappedCapsuleInstances: Array<any> = []
     protected memoizeCache: Map<string, any> = new Map()
     protected memoizeTimeouts: Map<string, ReturnType<typeof setTimeout>> = new Map()
@@ -104,6 +105,10 @@ export class ContractCapsuleInstanceFactory {
             this.mapInitProperty({ property })
         } else if (property.definition.type === CapsulePropertyTypes.Dispose) {
             this.mapDisposeProperty({ property })
+        } else if (property.definition.type === CapsulePropertyTypes.OnFreeze) {
+            this.mapOnFreezeProperty({ property })
+        } else if (property.definition.type === CapsulePropertyTypes.ProxyFunction) {
+            this.mapProxyFunctionProperty({ property })
         }
     }
 
@@ -131,11 +136,76 @@ export class ContractCapsuleInstanceFactory {
 
             // Use cst.source.moduleFilepath (always filesystem-relative) for path resolution.
             // encapsulateOptions.moduleFilepath may be an npm URI when loaded from projected files.
-            const moduleFilepath = this.capsule.cst?.source?.moduleFilepath || this.capsule.encapsulateOptions?.moduleFilepath
+            // However, cst.source.moduleFilepath may be relative to a different package root than
+            // the current spineFilesystemRoot (e.g. cross-package capsule references). In that case,
+            // fall back to encapsulateOptions.moduleFilepath which is always relative to current spine root.
+            let moduleFilepath = this.capsule.cst?.source?.moduleFilepath || this.capsule.encapsulateOptions?.moduleFilepath
             if (!moduleFilepath) throw new Error(`'moduleFilepath' not available on capsule!`)
 
-            const parentPath = join(this.spineFilesystemRoot, moduleFilepath)
-            const filepath = await this.resolve(property.definition.value, parentPath)
+            // moduleFilepath may be a relative filesystem path (e.g. "../../../caps/Foo.ts")
+            // or an npm-style URI (e.g. "@stream44.studio/t44-docker.com/caps/Project")
+            // after freeze/hoist cycles. join(spineRoot, npmUri) produces a bogus path when
+            // the URI is npm-style and spineRoot is narrow. Detect this by checking if the
+            // moduleFilepath looks like an npm URI (starts with @, or doesn't start with / or .),
+            // and resolve it to get the actual filesystem path.
+            let parentPath = join(this.spineFilesystemRoot, moduleFilepath)
+            if (!moduleFilepath.startsWith('/') && !moduleFilepath.startsWith('.')) {
+                // Looks like an npm-style URI or filesystem-convention path — resolve it
+                try {
+                    // Try with @ prefix first (npm URI convention)
+                    if (moduleFilepath.startsWith('@')) {
+                        parentPath = await this.resolve(moduleFilepath, this.spineFilesystemRoot)
+                    } else {
+                        // May be a filesystem-convention path like "scope/packages/pkg/path"
+                        // Try resolving as @scope/pkg/path by extracting scope and package name
+                        const parts = moduleFilepath.split('/')
+                        if (parts.length >= 3 && parts[1] === 'packages') {
+                            const scope = parts[0]
+                            const pkg = parts[2]
+                            const subpath = parts.slice(3).join('/')
+                            const npmUri = subpath ? `@${scope}/${pkg}/${subpath}` : `@${scope}/${pkg}`
+                            parentPath = await this.resolve(npmUri, this.spineFilesystemRoot)
+                        }
+                    }
+                } catch {
+                    // Fall back to the joined path if resolution fails
+                }
+            }
+            let filepath: string
+            try {
+                filepath = await this.resolve(property.definition.value, parentPath)
+            } catch (resolveError) {
+                // cst.source.moduleFilepath may be relative to a different package root than spineFilesystemRoot
+                // (e.g. cross-package capsule references). Fall back to encapsulateOptions.moduleFilepath
+                // which is always relative to the current spine root.
+                const fallbackModuleFilepath = this.capsule.encapsulateOptions?.moduleFilepath
+                if (fallbackModuleFilepath && fallbackModuleFilepath !== moduleFilepath) {
+                    // The fallback moduleFilepath may be a relative path or an npm URI.
+                    // Apply the same resolution logic as the primary path.
+                    let fallbackParentPath = join(this.spineFilesystemRoot, fallbackModuleFilepath)
+                    if (!fallbackModuleFilepath.startsWith('/') && !fallbackModuleFilepath.startsWith('.')) {
+                        try {
+                            if (fallbackModuleFilepath.startsWith('@')) {
+                                fallbackParentPath = await this.resolve!(fallbackModuleFilepath, this.spineFilesystemRoot)
+                            } else {
+                                const parts = fallbackModuleFilepath.split('/')
+                                if (parts.length >= 3 && parts[1] === 'packages') {
+                                    const scope = parts[0]
+                                    const pkg = parts[2]
+                                    const subpath = parts.slice(3).join('/')
+                                    const npmUri = subpath ? `@${scope}/${pkg}/${subpath}` : `@${scope}/${pkg}`
+                                    fallbackParentPath = await this.resolve!(npmUri, this.spineFilesystemRoot)
+                                }
+                            }
+                        } catch {
+                            // Fall back to the joined path
+                        }
+                    }
+                    filepath = await this.resolve(property.definition.value, fallbackParentPath)
+                } else {
+                    throw resolveError
+                }
+            }
             mappedCapsule = await this.importCapsule(filepath)
         } else if (
             typeof property.definition.value === 'object' &&
@@ -212,9 +282,12 @@ export class ContractCapsuleInstanceFactory {
 
         // Check for existing instance in registry - reuse if available when no options
         // Pre-registration with null allows parent capsules to "claim" a slot before child capsules process
-        // Property contract delegates (structs) always get a fresh instance per parent capsule
+        // Property contract delegates (structs) always get a fresh instance per parent capsule.
+        // CapsuleProjectionContext also needs fresh instances so context injection can find it
+        // in mappedCapsuleInstances during freeze traversal.
         const capsuleName = mappedCapsule.encapsulateOptions?.capsuleName
         const isCapsuleStruct = property.definition.propertyContractDelegate === '#@stream44.studio/encapsulate/structs/Capsule'
+            || property.definition.propertyContractDelegate === '#@stream44.studio/encapsulate/structs/CapsuleProjectionContext'
 
         if (capsuleName && this.instanceRegistry && !isCapsuleStruct) {
             if (this.instanceRegistry.has(capsuleName)) {
@@ -335,6 +408,10 @@ export class ContractCapsuleInstanceFactory {
         }
 
         apiTarget[property.name] = mappedInstance
+        mappedInstance.mappedPropertyName = property.name
+        if (property.definition.propertyContractDelegate) {
+            mappedInstance.isPropertyContractDelegate = true
+        }
         this.mappedCapsuleInstances.push(mappedInstance)
         // Use proxy to unwrap .api for this.self so internal references work
         this.self[property.name] = mappedInstance.api ? new Proxy(mappedInstance.api, {
@@ -349,18 +426,17 @@ export class ContractCapsuleInstanceFactory {
         }) : mappedInstance
 
         // If this mapping has a propertyContractDelegate, also mount the mapped capsule's API
-        // to the property contract namespace for direct access
+        // to the property contract namespace for direct access.
+        // Use a proxy so that later mutations to the delegate's API (e.g. CapsuleProjectionContext
+        // injection during freeze) are visible through the parent's encapsulatedApi.
         if (property.definition.propertyContractDelegate) {
-            // Create the property contract namespace if it doesn't exist
-            if (!this.encapsulatedApi[property.definition.propertyContractDelegate]) {
-                this.encapsulatedApi[property.definition.propertyContractDelegate] = {}
-            }
-
-            // Mount all properties from the mapped capsule's API to the property contract namespace
-            const delegateTarget = this.encapsulatedApi[property.definition.propertyContractDelegate]
-            for (const [key, value] of Object.entries(mappedInstance.api)) {
-                delegateTarget[key] = value
-            }
+            this.encapsulatedApi[property.definition.propertyContractDelegate] = new Proxy(mappedInstance.api, {
+                get: (target: any, prop: string | symbol) => target[prop],
+                set: (target: any, prop: string | symbol, value: any) => { target[prop] = value; return true },
+                ownKeys: (target: any) => Reflect.ownKeys(target),
+                getOwnPropertyDescriptor: (target: any, prop: string | symbol) => Object.getOwnPropertyDescriptor(target, prop) || { configurable: true, enumerable: true, writable: true, value: target[prop] },
+                has: (target: any, prop: string | symbol) => prop in target,
+            })
         }
     }
 
@@ -396,21 +472,29 @@ export class ContractCapsuleInstanceFactory {
 
                 // First check if the property exists in target (this.self)
                 if (prop in target) {
+                    // Virtual dispatch: if child has an override for this property,
+                    // prefer the child's version over self (which may hold the parent's bound fn)
+                    if (factory.childEncapsulatedApis) {
+                        for (const childApi of factory.childEncapsulatedApis) {
+                            if (prop in childApi) return childApi[prop]
+                        }
+                    }
                     return target[prop]
                 }
 
-                // Fall back to encapsulatedApi
-                if (prop in factory.encapsulatedApi) {
-                    return factory.encapsulatedApi[prop]
-                }
-
-                // Fall back to child capsule APIs (for parent→child function delegation)
+                // Check child capsule APIs (virtual dispatch —
+                // child overrides take precedence over parent's own API)
                 if (factory.childEncapsulatedApis) {
                     for (const childApi of factory.childEncapsulatedApis) {
                         if (prop in childApi) return childApi[prop]
                     }
                 }
 
+                // Fall back to own encapsulatedApi
+                if (prop in factory.encapsulatedApi) {
+                    return factory.encapsulatedApi[prop]
+                }
+
                 // Fall back to extended capsule's API
                 if (extendedApi && prop in extendedApi) {
                     return extendedApi[prop]
@@ -438,12 +522,12 @@ export class ContractCapsuleInstanceFactory {
             getOwnPropertyDescriptor: (target: any, prop: string | symbol) => {
                 if (typeof prop === 'symbol') return Object.getOwnPropertyDescriptor(target, prop)
                 if (prop in target) return Object.getOwnPropertyDescriptor(target, prop)
-                if (prop in factory.encapsulatedApi) return { configurable: true, enumerable: true, writable: true, value: factory.encapsulatedApi[prop as string] }
                 if (factory.childEncapsulatedApis) {
                     for (const childApi of factory.childEncapsulatedApis) {
                         if (prop in childApi) return { configurable: true, enumerable: true, writable: true, value: childApi[prop as string] }
                     }
                 }
+                if (prop in factory.encapsulatedApi) return { configurable: true, enumerable: true, writable: true, value: factory.encapsulatedApi[prop as string] }
                 if (extendedApi && prop in extendedApi) return { configurable: true, enumerable: true, writable: true, value: extendedApi[prop as string] }
                 return undefined
             }
@@ -556,6 +640,38 @@ export class ContractCapsuleInstanceFactory {
         }
     }
 
+    protected mapProxyFunctionProperty({ property }: { property: any }) {
+        const apiTarget = this.getApiTarget({ property })
+        const selfProxy = this.createSelfProxy()
+
+        const childTargetFn = property.definition.value.target
+        const childInvokeFn = property.definition.value.invoke
+
+        // Inherit missing parts from parent's ProxyFunction (if extending)
+        const parentParts = this.self[`__proxyFn_${property.name}`]
+        const targetFn = childTargetFn ?? parentParts?.target
+        const invokeFn = childInvokeFn ?? parentParts?.invoke
+
+        if (!targetFn) throw new Error(`ProxyFunction '${property.name}': target() is required`)
+        if (!invokeFn) throw new Error(`ProxyFunction '${property.name}': invoke() is required`)
+
+        // Store parts for potential child override
+        this.self[`__proxyFn_${property.name}`] = { target: targetFn, invoke: invokeFn }
+
+        apiTarget[property.name] = (...args: any[]) => {
+            // 1. Call invoke() bound to selfProxy to transform args
+            const transformedArgs = invokeFn.call(selfProxy, ...args)
+            // 2. Call target() bound to selfProxy to get the function to call
+            const target = targetFn.call(selfProxy)
+            // 3. If invoke returned a promise, await it then call target
+            if (transformedArgs && typeof transformedArgs.then === 'function') {
+                return transformedArgs.then((resolved: any) => target(resolved))
+            }
+            // 4. Call target with the transformed args
+            return target(transformedArgs)
+        }
+    }
+
     protected mapSetterFunctionProperty({ property }: { property: any }) {
         const apiTarget = this.getApiTarget({ property })
         const setterFn = property.definition.value
@@ -606,6 +722,12 @@ export class ContractCapsuleInstanceFactory {
         this.disposeFunctions.push(boundFunction)
     }
 
+    protected mapOnFreezeProperty({ property }: { property: any }) {
+        const selfProxy = this.createSelfProxy()
+        const boundFunction = property.definition.value.bind(selfProxy)
+        this.onFreezeFunctions.push(boundFunction)
+    }
+
     async freeze(options: any): Promise<any> {
         return this.freezeCapsule?.(options) || {}
     }

package/src/spine-factories/{CapsuleSpineFactory.v0.ts → CapsuleSpineFactory.ts}

@@ -1,8 +1,8 @@
-import { join, dirname, resolve as pathResolve } from 'path'
+import { join, dirname, relative, resolve as pathResolve } from 'path'
 import { writeFile, mkdir, readFile, stat } from 'fs/promises'
 import { Spine, SpineRuntime, CapsulePropertyTypes, makeImportStack, merge } from "../encapsulate"
-import { StaticAnalyzer } from "../../src/static-analyzer.v0"
-import { CapsuleModuleProjector } from "../../src/capsule-projectors/CapsuleModuleProjector.v0"
+import { StaticAnalyzer } from "../../src/static-analyzer"
+import { CapsuleModuleProjector } from "../../src/capsule-projectors/CapsuleModuleProjector"
 
 
 export { merge }
@@ -129,10 +129,39 @@ async function resolve(uri: string, fromPath: string, spineRoot?: string): Promi
             }
 
             // Also traverse up from fromPath (the importing file) checking:
-            // 1. If current dir IS the package (self-package resolution)
-            // 2. node_modules/@scope/pkg at each level
+            // 1. The scope/packages/pkg filesystem convention at each level
+            // 2. If current dir IS the package (self-package resolution)
+            // 3. node_modules/@scope/pkg at each level
             let fromDir = dirname(fromPath)
             while (true) {
+                // Check scope/packages/pkg filesystem convention
+                if (subpath) {
+                    const fsPath = join(fromDir, scope, 'packages', pkg, subpath + '.ts')
+                    try { await stat(fsPath); return fsPath } catch { }
+                    try { await stat(join(fromDir, scope, 'packages', pkg, subpath)); return join(fromDir, scope, 'packages', pkg, subpath) } catch { }
+                }
+                const fsPkgDir = join(fromDir, scope, 'packages', pkg)
+                try {
+                    const fsPjPath = join(fsPkgDir, 'package.json')
+                    const fsPj = JSON.parse(await readFile(fsPjPath, 'utf-8'))
+                    if (fsPj.name === `@${scope}/${pkg}`) {
+                        if (subpath && fsPj.exports) {
+                            const exportKey = './' + subpath
+                            const exportValue = fsPj.exports[exportKey]
+                            if (typeof exportValue === 'string') {
+                                return pathResolve(fsPkgDir, exportValue)
+                            }
+                        } else if (!subpath && fsPj.exports?.['.']) {
+                            const mainExport = fsPj.exports['.']
+                            if (typeof mainExport === 'string') {
+                                return pathResolve(fsPkgDir, mainExport)
+                            }
+                        } else if (!subpath && fsPj.main) {
+                            return pathResolve(fsPkgDir, fsPj.main)
+                        }
+                    }
+                } catch { }
+
                 // Check if this directory's package.json matches the requested package
                 try {
                     const pjPath = join(fromDir, 'package.json')
@@ -278,6 +307,65 @@ async function resolve(uri: string, fromPath: string, spineRoot?: string): Promi
 }
 
 
+// Build an async npmUriForFilepath resolver backed by a directory→package-name cache.
+// Walks up the directory tree from a given filepath to find the nearest package.json
+// and constructs an npm-style URI (e.g. "package-name/src/foo.ts").
+function createNpmUriForFilepath(): (filepath: string) => Promise<string | null> {
+    const cache = new Map<string, string | null>()
+
+    return async (absoluteFilepath: string): Promise<string | null> => {
+        // Only process absolute paths — skip V8 internal markers like "native", "node:*", etc.
+        if (!absoluteFilepath.startsWith('/')) {
+            return null
+        }
+
+        // Check for /node_modules/ in the path — use the last occurrence to handle nested node_modules
+        const nodeModulesMarker = '/node_modules/'
+        const lastIdx = absoluteFilepath.lastIndexOf(nodeModulesMarker)
+        if (lastIdx !== -1) {
+            return absoluteFilepath.substring(lastIdx + nodeModulesMarker.length)
+        }
+
+        let currentDir = dirname(absoluteFilepath)
+        const maxDepth = 20
+
+        for (let i = 0; i < maxDepth; i++) {
+            if (cache.has(currentDir)) {
+                const cachedName = cache.get(currentDir)
+                if (cachedName) {
+                    const relativeFromPackage = relative(currentDir, absoluteFilepath)
+                    return `${cachedName}/${relativeFromPackage}`
+                }
+                // null means no package.json with name found at this level, continue up
+                const parentDir = dirname(currentDir)
+                if (parentDir === currentDir) break
+                currentDir = parentDir
+                continue
+            }
+
+            const packageJsonPath = join(currentDir, 'package.json')
+            try {
+                await stat(packageJsonPath)
+                const packageJson = JSON.parse(await readFile(packageJsonPath, 'utf-8'))
+                const packageName = packageJson.name
+                cache.set(currentDir, packageName || null)
+                if (packageName) {
+                    const relativeFromPackage = relative(currentDir, absoluteFilepath)
+                    return `${packageName}/${relativeFromPackage}`
+                }
+            } catch {
+                cache.set(currentDir, null)
+            }
+
+            const parentDir = dirname(currentDir)
+            if (parentDir === currentDir) break
+            currentDir = parentDir
+        }
+
+        return null
+    }
+}
+
 export async function CapsuleSpineFactory({
     spineFilesystemRoot,
     capsuleModuleProjectionRoot,
@@ -329,8 +417,10 @@ export async function CapsuleSpineFactory({
     }
 
     const sourceSpine: { encapsulate?: any } = {}
+    const npmUriForFilepath = createNpmUriForFilepath()
     const commonSpineContractOpts = {
         spineFilesystemRoot,
+        npmUriForFilepath,
         resolve: async (uri: string, parentFilepath: string) => {
             // For relative paths, join with parent directory first
             if (/^\.\.?\//.test(uri)) {
@@ -537,7 +627,28 @@ export async function CapsuleSpineFactory({
                 },
             },
         }) : undefined,
-        spineContracts: spineContractInstances.encapsulation
+        spineContracts: spineContractInstances.encapsulation,
+        projectionContext: capsuleModuleProjectionRoot ? {
+            capsuleModuleProjectionPackage,
+            capsuleModuleProjectionRoot,
+            projectionStore: {
+                writeFile: async (filepath: string, content: string) => {
+                    filepath = join(capsuleModuleProjectionRoot, filepath)
+                    await mkdir(dirname(filepath), { recursive: true })
+                    await writeFile(filepath, content, 'utf-8')
+                },
+                getStats: async (filepath: string) => {
+                    filepath = join(capsuleModuleProjectionRoot, filepath)
+                    try {
+                        const stats = await stat(filepath)
+                        return { mtime: stats.mtime }
+                    } catch (error) {
+                        return null
+                    }
+                },
+            },
+            get capsules() { return capsules }
+        } : undefined
     })
     sourceSpine.encapsulate = encapsulate
 

package/src/{static-analyzer.v0.ts → static-analyzer.ts}

@@ -85,6 +85,7 @@ const MODULE_GLOBAL_BUILTINS = new Set([
 
     // Bun runtime
     'Bun',
+    'HTMLRewriter',
 
     // Node.js Buffer
     'Buffer',
@@ -218,6 +219,7 @@ const MODULE_GLOBAL_BUILTINS = new Set([
     'decodeURIComponent',
     'escape',
     'unescape',
+    'eval',
 ])
 
 export function StaticAnalyzer({
@@ -1939,6 +1941,19 @@ function extractAndValidateAmbientReferences(
         extractBindingIdentifiers(param.name)
     }
 
+    // Pre-collect all function declarations from the function body (hoisting)
+    // Function declarations are hoisted in JavaScript, so they can be referenced
+    // before their source position. We must collect them before the main visit pass.
+    function preCollectDeclarations(node: ts.Node) {
+        if (ts.isFunctionDeclaration(node) && node.name && ts.isIdentifier(node.name)) {
+            localIdentifiers.add(node.name.text)
+        }
+        ts.forEachChild(node, preCollectDeclarations)
+    }
+    if (fn.body) {
+        preCollectDeclarations(fn.body)
+    }
+
     // Traverse the function body to find identifiers
     function visit(node: ts.Node) {
         // Skip type nodes to avoid false positives from type annotations

package/structs/CapsuleProjectionContext.ts

@@ -0,0 +1,53 @@
+
+export async function capsule({
+    encapsulate,
+    CapsulePropertyTypes,
+    makeImportStack
+}: any) {
+    return encapsulate({
+        '#@stream44.studio/encapsulate/spine-contracts/CapsuleSpineContract.v0': {
+            '#': {
+                // The parent capsule's full CST (source, spineContracts, ambient references, etc.)
+                parentCapsuleCst: {
+                    type: CapsulePropertyTypes.Literal,
+                    value: undefined
+                },
+                // The parent capsule's capsuleSourceLineRef
+                parentCapsuleSourceLineRef: {
+                    type: CapsulePropertyTypes.Literal,
+                    value: undefined
+                },
+                // Package prefix for projected capsule imports (e.g. '~caps')
+                capsuleModuleProjectionPackage: {
+                    type: CapsulePropertyTypes.Literal,
+                    value: undefined
+                },
+                // Store for writing projected files
+                projectionStore: {
+                    type: CapsulePropertyTypes.Literal,
+                    value: undefined
+                },
+                // All capsule snapshots for dependency resolution
+                capsuleSnapshots: {
+                    type: CapsulePropertyTypes.Literal,
+                    value: undefined
+                },
+                // The property contract delegate alias (e.g. '/apps/web/src/components/Counter1.tsx')
+                projectionPath: {
+                    type: CapsulePropertyTypes.Literal,
+                    value: undefined
+                },
+                // Spine contract URI
+                spineContractUri: {
+                    type: CapsulePropertyTypes.Literal,
+                    value: undefined
+                },
+            }
+        }
+    }, {
+        importMeta: import.meta,
+        importStack: makeImportStack(),
+        capsuleName: capsule['#'],
+    })
+}
+capsule['#'] = '@stream44.studio/encapsulate/structs/CapsuleProjectionContext'

package/structs/StructFactory.ts

@@ -0,0 +1,90 @@
+
+export async function capsule({
+    encapsulate,
+    CapsulePropertyTypes,
+    makeImportStack
+}: any) {
+    return encapsulate({
+        '#@stream44.studio/encapsulate/spine-contracts/CapsuleSpineContract.v0': {
+            '#': {
+                // --------------------------------------------------------
+                // _instances — internal store for keyed instances
+                // --------------------------------------------------------
+                _instances: {
+                    type: CapsulePropertyTypes.GetterFunction,
+                    value: function () {
+                        return new Map<string, any>();
+                    },
+                    memoize: true,
+                },
+
+                // --------------------------------------------------------
+                // _defaults — override in extending structs to provide
+                // default config for each new instance
+                // --------------------------------------------------------
+                _defaults: {
+                    type: CapsulePropertyTypes.GetterFunction,
+                    value: function () {
+                        return {};
+                    },
+                    memoize: true,
+                },
+
+                // --------------------------------------------------------
+                // config — user-provided overrides applied to all instances
+                // --------------------------------------------------------
+                config: {
+                    type: CapsulePropertyTypes.Literal,
+                    value: {} as any,
+                },
+
+                // --------------------------------------------------------
+                // forInstance — get-or-create a config instance by key
+                // Pass an object whose keys together form a composite key.
+                // Returns a merged config (defaults + factory config + instance overrides).
+                // --------------------------------------------------------
+                forInstance: {
+                    type: CapsulePropertyTypes.Function,
+                    value: function (this: any, keyObj: Record<string, any>, instanceConfig?: Record<string, any>) {
+                        const serializedKey = JSON.stringify(
+                            Object.keys(keyObj).sort().reduce((acc: any, k: string) => {
+                                acc[k] = keyObj[k];
+                                return acc;
+                            }, {} as any)
+                        );
+
+                        if (!instanceConfig && this._instances.has(serializedKey)) {
+                            return this._instances.get(serializedKey);
+                        }
+
+                        const merged = {
+                            ...this._defaults,
+                            ...this.config,
+                            ...keyObj,
+                            ...(instanceConfig || {}),
+                            ...(this._instances.get(serializedKey) || {}),
+                        };
+
+                        this._instances.set(serializedKey, merged);
+                        return merged;
+                    },
+                },
+
+                // --------------------------------------------------------
+                // getInstances — return all tracked instances
+                // --------------------------------------------------------
+                getInstances: {
+                    type: CapsulePropertyTypes.Function,
+                    value: function (this: any) {
+                        return Array.from(this._instances.values());
+                    },
+                },
+            }
+        }
+    }, {
+        importMeta: import.meta,
+        importStack: makeImportStack(),
+        capsuleName: capsule['#'],
+    })
+}
+capsule['#'] = '@stream44.studio/encapsulate/structs/StructFactory'