@stream44.studio/encapsulate 0.4.0-rc.38 → 0.4.0-rc.42

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

@@ -1,8 +1,10 @@
 import { join, dirname, relative, resolve as pathResolve } from 'path'
-import { writeFile, mkdir, readFile, stat } from 'fs/promises'
+import { writeFile, mkdir, readFile, stat, access } from 'fs/promises'
+import { createHash } from 'crypto'
 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"
+import { TimingObserver, type TimingObserverInterface } from "./TimingObserver"
 
 
 export { merge }
@@ -129,10 +131,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')
@@ -337,6 +368,31 @@ function createNpmUriForFilepath(): (filepath: string) => Promise<string | null>
     }
 }
 
+// Cross-factory cache for module imports — avoids re-importing the same file
+// across factory instances. The capsule() call still runs per-factory (spine-specific),
+// but the import() is only done once per filepath globally.
+const _moduleImportCache = new Map<string, Promise<any>>()
+
+// Cross-factory stat cache — avoids redundant filesystem stat() calls for the same
+// file across factory instances within a single process. Source file stats are cached
+// permanently (source files don't change within a single build). Cache file stats are
+// invalidated on write.
+const _statCache = new Map<string, Promise<{ mtime: Date } | null>>()
+function cachedStat(filepath: string): Promise<{ mtime: Date } | null> {
+    let cached = _statCache.get(filepath)
+    if (!cached) {
+        cached = stat(filepath).then(
+            s => ({ mtime: s.mtime }),
+            () => null
+        )
+        _statCache.set(filepath, cached)
+    }
+    return cached
+}
+function invalidateStatCache(filepath: string) {
+    _statCache.delete(filepath)
+}
+
 export async function CapsuleSpineFactory({
     spineFilesystemRoot,
     capsuleModuleProjectionRoot,
@@ -354,13 +410,16 @@ export async function CapsuleSpineFactory({
     onMembraneEvent?: (event: any) => void,
     enableCallerStackInference?: boolean,
     spineContracts: Record<string, any>,
-    timing?: { record: (step: string) => void, recordMajor: (step: string) => void, chalk?: any }
+    timing?: TimingObserverInterface | null
 }) {
 
     if (capsuleModuleProjectionRoot) capsuleModuleProjectionRoot = capsuleModuleProjectionRoot.replace(/^file:\/\//, '')
     if (spineFilesystemRoot) spineFilesystemRoot = spineFilesystemRoot.replace(/^file:\/\//, '')
 
-    const timing = timingParam
+    // Auto-create timing when ENCAPSULATE_TRACE env var is set
+    const timing: TimingObserverInterface | undefined = timingParam || (
+        process.env.ENCAPSULATE_TRACE ? TimingObserver() : undefined
+    )
 
     timing?.recordMajor('CAPSULE SPINE FACTORY: INITIALIZATION')
 
@@ -368,6 +427,7 @@ export async function CapsuleSpineFactory({
         const registry = new Map<string, Promise<any>>()
 
         return {
+            has(id: string) { return registry.has(id) },
             async ensure(id: string, createHandler: () => Promise<any>) {
                 if (!registry.has(id)) {
                     registry.set(id, createHandler())
@@ -390,6 +450,7 @@ export async function CapsuleSpineFactory({
     const sourceSpine: { encapsulate?: any } = {}
     const npmUriForFilepath = createNpmUriForFilepath()
     const commonSpineContractOpts = {
+        timing,
         spineFilesystemRoot,
         npmUriForFilepath,
         resolve: async (uri: string, parentFilepath: string) => {
@@ -401,24 +462,25 @@ export async function CapsuleSpineFactory({
             return await resolve(uri, parentFilepath, spineFilesystemRoot)
         },
         importCapsule: (() => {
-            return async (filepath: string) => {
+            const importFn = async (filepath: string) => {
                 const shortPath = filepath.replace(/^.*\/genesis\//, '')
 
                 timing?.record(`importCapsule: Called for ${shortPath}`)
                 const result = await registry.ensure(filepath, async () => {
                     timing?.recordMajor(`importCapsule: Starting import for ${shortPath}`)
                     const importStart = Date.now()
-                    const exports = await import(filepath)
+                    if (!_moduleImportCache.has(filepath)) {
+                        _moduleImportCache.set(filepath, import(filepath))
+                    }
+                    const exports = await _moduleImportCache.get(filepath)!
                     const importDuration = Date.now() - importStart
                     timing?.recordMajor(`importCapsule: import() took ${importDuration}ms for ${shortPath}`)
 
-                    if (importDuration > 10) {
-                        if (timing) {
-                            console.log(timing.chalk.red(`\n⚠️  WARNING: Slow module load detected!`))
-                            console.log(timing.chalk.red(`   Module: ${filepath}`))
-                            console.log(timing.chalk.red(`   Load time: ${importDuration}ms`))
-                            console.log(timing.chalk.red(`   Consider using dynamic imports to load heavy dependencies only when needed.\n`))
-                        }
+                    if (importDuration > 10 && timing) {
+                        console.log(timing.chalk.red(`\n⚠️  WARNING: Slow module load detected!`))
+                        console.log(timing.chalk.red(`   Module: ${filepath}`))
+                        console.log(timing.chalk.red(`   Load time: ${importDuration}ms`))
+                        console.log(timing.chalk.red(`   Consider using dynamic imports to load heavy dependencies only when needed.\n`))
                     }
 
                     if (typeof exports.capsule !== 'function') throw new Error(`Module at '${filepath}' does not export 'capsule'!`)
@@ -438,6 +500,7 @@ export async function CapsuleSpineFactory({
                 })
                 return result
             }
+            return importFn
         })(),
         encapsulateOpts: {
             CapsulePropertyTypes
@@ -541,10 +604,7 @@ export async function CapsuleSpineFactory({
 
     timing?.recordMajor('SPINE: INITIALIZATION')
 
-    let { encapsulate, freeze, capsules } = await Spine({
-        spineFilesystemRoot,
-        timing,
-        staticAnalyzer: staticAnalysisEnabled ? StaticAnalyzer({
+    const staticAnalyzer = staticAnalysisEnabled ? StaticAnalyzer({
             timing,
             cacheStore: {
                 writeFile: async (filepath: string, content: string) => {
@@ -552,6 +612,7 @@ export async function CapsuleSpineFactory({
                     const centralPath = join(spineFilesystemRoot, '.~o/encapsulate.dev/static-analysis', filepath)
                     await mkdir(dirname(centralPath), { recursive: true })
                     await writeFile(centralPath, content, 'utf-8')
+                    invalidateStatCache(centralPath)
                     // Also write to local project cache if available
                     if (capsuleModuleProjectionRoot) {
                         try {
@@ -575,29 +636,20 @@ export async function CapsuleSpineFactory({
                     return content
                 },
                 getStats: async (filepath: string) => {
-                    filepath = join(spineFilesystemRoot, '.~o/encapsulate.dev/static-analysis', filepath)
-                    try {
-                        const stats = await stat(filepath)
-                        return { mtime: stats.mtime }
-                    } catch (error) {
-                        // File doesn't exist
-                        return null
-                    }
+                    return cachedStat(join(spineFilesystemRoot, '.~o/encapsulate.dev/static-analysis', filepath))
                 },
             },
             spineStore: {
                 getStats: async (filepath: string) => {
-                    filepath = join(spineFilesystemRoot, filepath)
-                    try {
-                        const stats = await stat(filepath)
-                        return { mtime: stats.mtime }
-                    } catch (error) {
-                        // File doesn't exist
-                        return null
-                    }
+                    return cachedStat(join(spineFilesystemRoot, filepath))
                 },
             },
-        }) : undefined,
+        }) : undefined
+
+    let { encapsulate, freeze, capsules } = await Spine({
+        spineFilesystemRoot,
+        timing,
+        staticAnalyzer,
         spineContracts: spineContractInstances.encapsulation,
         projectionContext: capsuleModuleProjectionRoot ? {
             capsuleModuleProjectionPackage,
@@ -653,10 +705,16 @@ export async function CapsuleSpineFactory({
         return capsule
     }
 
+    // Track capsule refs known at freeze time so we can identify dynamic imports later
+    let frozenCapsuleRefs: Set<string> | null = null
+
     // Wrap freeze to also write spine instance (.sit.json) files
     const wrappedFreeze = async function () {
         const snapshot = await freeze()
 
+        // Record capsule refs at freeze time (before any dynamic imports)
+        frozenCapsuleRefs = new Set(Object.keys(capsules))
+
         // Write spine instance files if capsuleModuleProjectionRoot is available
         if (capsuleModuleProjectionRoot) {
             try {
@@ -693,6 +751,10 @@ export async function CapsuleSpineFactory({
                     }
                 }
 
+                // Check if any CSTs were regenerated — if not, we can skip SIT writes
+                // when existing files are still valid
+                const cstsChanged = !staticAnalyzer || staticAnalyzer.hasCacheMisses()
+
                 for (const [, capsule] of Object.entries(uniqueCapsules)) {
                     const cst = capsule.cst
                     const rootCapsuleName = cst?.source?.capsuleName
@@ -708,6 +770,16 @@ export async function CapsuleSpineFactory({
                     const sitDir = join(capsuleModuleProjectionRoot, '.~o/encapsulate.dev/spine-instances', dirName)
                     const sitFilePath = join(sitDir, `root-capsule.sit.json`)
 
+                    // Skip SIT generation if CSTs are unchanged and the file already exists
+                    if (!cstsChanged) {
+                        try {
+                            await access(sitFilePath)
+                            continue // File exists and no CSTs changed — skip
+                        } catch {
+                            // File doesn't exist — need to generate even though CSTs are cached
+                        }
+                    }
+
                     // Build the capsules map
                     const capsuleEntries: Record<string, { capsuleSourceUriLineRef: string }> = {}
                     for (const [, cap] of Object.entries(uniqueCapsules)) {
@@ -721,7 +793,7 @@ export async function CapsuleSpineFactory({
 
                     // Collect capsuleInstances from the cached root instance using an
                     // iterative stack — each instance stores its ID and parent ID from init
-                    const rootInstance = await capsule.makeInstance()
+                    const rootInstance = await capsule.makeInstance({ freezePhase: true })
                     const capsuleInstances: Record<string, { capsuleName: string, capsuleSourceUriLineRef: string, parentCapsuleSourceUriLineRefInstanceId: string }> = {}
 
                     // Iterative stack-based collection from instance tree
@@ -761,8 +833,18 @@ export async function CapsuleSpineFactory({
                         capsuleInstances
                     }
 
+                    const sitContent = JSON.stringify(sitData, null, 2)
+
+                    // Compare-before-write: skip disk write if content is identical
+                    try {
+                        const existing = await readFile(sitFilePath, 'utf-8')
+                        if (existing === sitContent) continue
+                    } catch {
+                        // File doesn't exist — write it
+                    }
+
                     await mkdir(sitDir, { recursive: true })
-                    await writeFile(sitFilePath, JSON.stringify(sitData, null, 2), 'utf-8')
+                    await writeFile(sitFilePath, sitContent, 'utf-8')
                 }
             } catch (error) {
                 // Spine instance file writing is best-effort
@@ -773,6 +855,55 @@ export async function CapsuleSpineFactory({
         return snapshot
     }
 
+    /**
+     * Write a dynamic SIT file capturing capsules that were loaded at runtime
+     * via importCapsule (not part of the static capsule tree).
+     * Call this after run() to record which dynamic capsules were used.
+     * The filename includes a content hash so unchanged combos produce the same file.
+     */
+    const writeDynamicSit = async function () {
+        if (!capsuleModuleProjectionRoot || !frozenCapsuleRefs) return
+
+        // Find capsules that were added after freeze (dynamic imports)
+        const dynamicCapsuleRefs: string[] = []
+        for (const key of Object.keys(capsules)) {
+            if (!frozenCapsuleRefs.has(key) && key.includes(':') && /:\d+$/.test(key)) {
+                dynamicCapsuleRefs.push(key)
+            }
+        }
+
+        if (dynamicCapsuleRefs.length === 0) return
+
+        // Build a sorted list of dynamic capsule entries for deterministic output
+        const dynamicEntries: Record<string, { capsuleSourceUriLineRef: string, capsuleName?: string }> = {}
+        for (const ref of dynamicCapsuleRefs.sort()) {
+            const cap = capsules[ref]
+            dynamicEntries[ref] = {
+                capsuleSourceUriLineRef: ref,
+                capsuleName: cap?.cst?.source?.capsuleName
+            }
+        }
+
+        const sitData = { dynamicCapsules: dynamicEntries }
+        const sitContent = JSON.stringify(sitData, null, 2)
+
+        // Content hash for the filename — same dynamic import combo = same file
+        const contentHash = createHash('sha256').update(sitContent).digest('hex').slice(0, 16)
+        const sitDir = join(capsuleModuleProjectionRoot, '.~o/encapsulate.dev/spine-instances')
+        const sitFilePath = join(sitDir, `dynamic-imports.${contentHash}.sit.json`)
+
+        // Skip write if file already exists (hash match = identical content)
+        try {
+            await access(sitFilePath)
+            return // Already exists with same content
+        } catch {
+            // File doesn't exist — write it
+        }
+
+        await mkdir(sitDir, { recursive: true })
+        await writeFile(sitFilePath, sitContent, 'utf-8')
+    }
+
     return {
         commonSpineContractOpts,
         CapsulePropertyTypes,
@@ -780,7 +911,9 @@ export async function CapsuleSpineFactory({
         encapsulate,
         run,
         freeze: wrappedFreeze,
+        writeDynamicSit,
         loadCapsule,
+        staticAnalyzer,
         spineContractInstances, // Expose for testing
         hoistSnapshot: async ({ snapshot }: { snapshot: any }) => {
 

package/src/spine-factories/TimingObserver.ts

@@ -1,26 +1,36 @@
 
 import chalk from 'chalk';
 
-export function TimingObserver({ startTime }: { startTime: number }) {
-    let lastTime = startTime
+export type TimingOptions = { color?: 'red' | 'green' | 'yellow' | 'cyan' | 'gray' }
+
+export type TimingObserverInterface = {
+    record: (step: string, opts?: TimingOptions) => void,
+    recordMajor: (step: string, opts?: TimingOptions) => void,
+    chalk: typeof chalk,
+}
+
+export function TimingObserver(): TimingObserverInterface {
+    let lastTime = performance.now()
+
+    function format(msg: string, diff: string, opts?: TimingOptions): string {
+        const line = `[+${diff}ms] ${msg}`
+        if (opts?.color) return (chalk as any)[opts.color](line)
+        return line
+    }
 
     return {
         chalk,
-        record: (step: string) => {
-            const now = Date.now()
-            const diff = now - lastTime
+        record: (step: string, opts?: TimingOptions) => {
+            const now = performance.now()
+            const diff = (now - lastTime).toFixed(1)
             lastTime = now
-
-            const line = `[+${diff}ms]   ${step}`
-            console.log(diff > 10 ? chalk.red(line) : line)
+            console.log(format(`  ${step}`, diff, opts))
         },
-        recordMajor: (step: string) => {
-            const now = Date.now()
-            const diff = now - lastTime
+        recordMajor: (step: string, opts?: TimingOptions) => {
+            const now = performance.now()
+            const diff = (now - lastTime).toFixed(1)
             lastTime = now
-
-            const line = `[+${diff}ms] ${step}`
-            console.log(diff > 10 ? chalk.red(line) : chalk.cyan(line))
+            console.log(format(`★ ${step}`, diff, opts))
         }
     }
 }

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

@@ -3,6 +3,7 @@ import { join, normalize, dirname, resolve, relative } from 'path'
 import { readFile, stat } from 'fs/promises'
 import * as ts from 'typescript'
 import { createHash } from 'crypto'
+import type { TimingObserverInterface } from './spine-factories/TimingObserver'
 
 // Known exports from @stream44.studio/encapsulate/encapsulate that can be imported
 const ENCAPSULATE_MODULE_EXPORTS = new Set([
@@ -85,6 +86,7 @@ const MODULE_GLOBAL_BUILTINS = new Set([
 
     // Bun runtime
     'Bun',
+    'HTMLRewriter',
 
     // Node.js Buffer
     'Buffer',
@@ -218,6 +220,7 @@ const MODULE_GLOBAL_BUILTINS = new Set([
     'decodeURIComponent',
     'escape',
     'unescape',
+    'eval',
 ])
 
 export function StaticAnalyzer({
@@ -225,7 +228,7 @@ export function StaticAnalyzer({
     cacheStore,
     spineStore
 }: {
-    timing?: { record: (step: string) => void, chalk?: any },
+    timing?: TimingObserverInterface,
     cacheStore?: {
         writeFile?: (filepath: string, content: string) => Promise<void>,
         readFile?: (filepath: string) => Promise<string | undefined>,
@@ -238,8 +241,16 @@ export function StaticAnalyzer({
 
     timing?.record('StaticAnalyzer: Initialized')
 
+    let _cacheMissCount = 0
+
     return {
 
+        /** Returns true if any parseModule call resulted in a cache miss (CST regeneration) */
+        hasCacheMisses: () => _cacheMissCount > 0,
+
+        /** Reset the cache miss counter (call before a new freeze cycle) */
+        resetCacheMisses: () => { _cacheMissCount = 0 },
+
         parseModule: async ({ spineOptions, encapsulateOptions }: { spineOptions: any, encapsulateOptions: any }) => {
 
             const moduleFilepath = join(spineOptions.spineFilesystemRoot, encapsulateOptions.moduleFilepath)
@@ -280,7 +291,8 @@ export function StaticAnalyzer({
                             // Check cache bust version - if mismatch, regenerate
                             const cachedVersion = cachedCsts?.[capsuleSourceLineRef]?.cacheBustVersion
                             if (encapsulateOptions.cacheBustVersion !== undefined && cachedVersion !== encapsulateOptions.cacheBustVersion) {
-                                timing?.record(timing?.chalk?.red?.(`StaticAnalyzer: Cache BUST (version mismatch: ${cachedVersion} !== ${encapsulateOptions.cacheBustVersion}) for ${encapsulateOptions.moduleFilepath}`))
+                                _cacheMissCount++
+                                timing?.record(`StaticAnalyzer: Cache BUST (version mismatch: ${cachedVersion} !== ${encapsulateOptions.cacheBustVersion}) for ${encapsulateOptions.moduleFilepath}`, { color: 'red' })
                             } else {
                                 timing?.record(`StaticAnalyzer: Cache HIT for ${encapsulateOptions.moduleFilepath}`)
                                 return {
@@ -291,10 +303,12 @@ export function StaticAnalyzer({
                             }
                         }
                     }
-                    timing?.record(timing?.chalk?.red?.(`StaticAnalyzer: Cache MISS for ${encapsulateOptions.moduleFilepath}`))
+                    _cacheMissCount++
+                    timing?.record(`StaticAnalyzer: Cache MISS for ${encapsulateOptions.moduleFilepath}`, { color: 'red' })
                 } catch (error) {
                     // Cache miss or error, continue with normal parsing
-                    timing?.record(timing?.chalk?.red?.(`StaticAnalyzer: Cache error for ${encapsulateOptions.moduleFilepath}`))
+                    _cacheMissCount++
+                    timing?.record(`StaticAnalyzer: Cache error for ${encapsulateOptions.moduleFilepath}`, { color: 'red' })
                 }
             }
 
@@ -1939,6 +1953,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/Capsule.ts

@@ -11,6 +11,11 @@ export async function capsule({
                     type: CapsulePropertyTypes.Literal,
                     value: undefined
                 },
+
+                spineFilesystemRoot: {
+                    type: CapsulePropertyTypes.Literal,
+                    value: undefined as string | undefined
+                },
             }
         }
     }, {

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'