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

package/README.md

@@ -1,7 +1,7 @@
 <table>
   <tr>
-    <td><a href="https://Stream44.Studio"><img src=".o/stream44.studio/assets/Icon-v1.svg" width="42" height="42"></a></td>
-    <td><strong><a href="https://Stream44.Studio">Stream44 Studio</a></strong><br/>Open Development Project</td>
+    <td><a href="https://Stream44.Systems"><img src=".o/stream44.studio/assets/Icon-v1.svg" width="42" height="42"></a></td>
+    <td><strong><a href="https://Stream44.Systems">Stream44 Systems</a></strong><br/>Open Development Project</td>
     <td>Preview release for community feedback.<br/>Get in touch on <a href="https://discord.gg/9eBcQXEJAN">discord</a>.</td>
     <td>Designed by Hand<br/><b>AI assisted Code</a></td>
   </tr>

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@stream44.studio/encapsulate",
-    "version": "0.4.0-rc.38",
+    "version": "0.4.0-rc.39",
     "license": "MIT",
     "repository": {
         "type": "git",
@@ -10,9 +10,9 @@
     "type": "module",
     "exports": {
         "./encapsulate": "./src/encapsulate.ts",
-        "./spine-contracts/CapsuleSpineContract.v0/Static.v0": "./src/spine-contracts/CapsuleSpineContract.v0/Static.v0.ts",
-        "./spine-contracts/CapsuleSpineContract.v0/Membrane.v0": "./src/spine-contracts/CapsuleSpineContract.v0/Membrane.v0.ts",
-        "./spine-factories/CapsuleSpineFactory.v0": "./src/spine-factories/CapsuleSpineFactory.v0.ts",
+        "./spine-contracts/CapsuleSpineContract.v0/Static": "./src/spine-contracts/CapsuleSpineContract.v0/Static.ts",
+        "./spine-contracts/CapsuleSpineContract.v0/Membrane": "./src/spine-contracts/CapsuleSpineContract.v0/Membrane.ts",
+        "./spine-factories/CapsuleSpineFactory": "./src/spine-factories/CapsuleSpineFactory.ts",
         "./spine-factories/TimingObserver": "./src/spine-factories/TimingObserver.ts",
         "./structs/Capsule": "./structs/Capsule.ts",
         "./structs/CapsuleProjectionContext": "./structs/CapsuleProjectionContext.ts"

package/src/capsule-projectors/{CapsuleModuleProjector.v0.ts → CapsuleModuleProjector.ts}

@@ -50,7 +50,7 @@ async function constructCacheFilePath(moduleFilepath: string, importStackLine: n
  * Finds the nearest package.json and constructs an npm URI for cache files.
  * First checks if the path contains /node_modules/ and if so, extracts the portion
  * after the last /node_modules/ occurrence for consistent paths in dev and installed mode.
- * This matches the logic from static-analyzer.v0.ts
+ * This matches the logic from static-analyzer.ts
  */
 async function constructNpmUriForCache(absoluteFilepath: string, spineRoot: string): Promise<string | null> {
     // Check for /node_modules/ in the path — use the last occurrence to handle nested node_modules
@@ -742,7 +742,7 @@ export function CapsuleModuleProjector({
         const hasStandalone = hasStandaloneProperty(capsule, spineContractUri)
 
         // Add runtime imports for standalone functions
-        const runtimeImport = hasStandalone ? `"use client"\nimport { Spine, SpineRuntime } from '@stream44.studio/encapsulate/encapsulate'\nimport { CapsuleSpineContract } from '@stream44.studio/encapsulate/spine-contracts/CapsuleSpineContract.v0/Membrane.v0'\n` : ''
+        const runtimeImport = hasStandalone ? `"use client"\nimport { Spine, SpineRuntime } from '@stream44.studio/encapsulate/encapsulate'\nimport { CapsuleSpineContract } from '@stream44.studio/encapsulate/spine-contracts/CapsuleSpineContract.v0/Membrane'\n` : ''
 
         // Generate default export based on capsule type
         let defaultExport = ''
@@ -1072,7 +1072,7 @@ ${defaultExport}
             const mappedCapsuleExpression = rewriteCapsuleExpressionWithCST(mappedCapsule)
 
             // Add runtime imports for standalone functions
-            const mappedRuntimeImport = mappedHasStandalone ? `"use client"\nimport { Spine, SpineRuntime } from '@stream44.studio/encapsulate/encapsulate'\nimport { CapsuleSpineContract } from '@stream44.studio/encapsulate/spine-contracts/CapsuleSpineContract.v0/Membrane.v0'\n` : ''
+            const mappedRuntimeImport = mappedHasStandalone ? `"use client"\nimport { Spine, SpineRuntime } from '@stream44.studio/encapsulate/encapsulate'\nimport { CapsuleSpineContract } from '@stream44.studio/encapsulate/spine-contracts/CapsuleSpineContract.v0/Membrane'\n` : ''
 
             let mappedDefaultExport = ''
             if (mappedHasStandalone) {

package/src/encapsulate.ts

@@ -125,6 +125,7 @@ export const CapsulePropertyTypes = {
     Init: 'Init' as const,
     Dispose: 'Dispose' as const,
     OnFreeze: 'OnFreeze' as const,
+    ProxyFunction: 'ProxyFunction' as const,
 }
 
 // ##################################################
@@ -198,8 +199,8 @@ export async function SpineRuntime(options: TSpineRuntimeOptions): Promise<TSpin
 
                             // If the value is a raw capsule instance (has spineContractCapsuleInstances
                             // but is NOT a Proxy that handles API access), unwrap it
-                            // Static.v0 sets apiTarget[property.name] = mappedInstance (raw)
-                            // Membrane.v0 sets apiTarget[property.name] = new Proxy(...) which handles API access
+                            // Static sets apiTarget[property.name] = mappedInstance (raw)
+                            // Membrane sets apiTarget[property.name] = new Proxy(...) which handles API access
                             if (value && typeof value === 'object' && value.spineContractCapsuleInstances) {
                                 // Check if this is a raw capsule instance by seeing if it has .api
                                 // and the .api doesn't have the same spineContractCapsuleInstances
@@ -531,7 +532,7 @@ export async function Spine(options: TSpineOptions): Promise<TSpine> {
                             const mappedProjectionPath = mappedInstance.mappedPropertyName?.startsWith('/') ? mappedInstance.mappedPropertyName : projectionPath
                             // For regular mapped capsules (non-struct delegates), use their own CST as
                             // parentCapsuleCst so nested property contract delegates see the correct parent.
-                            // Property contract delegates (flagged by Static.v0) pass through the current
+                            // Property contract delegates (flagged by Static) pass through the current
                             // parentCapsuleCst so their OnFreeze sees the declaring capsule's CST.
                             const mappedCapsule = (!mappedInstance.isPropertyContractDelegate && mappedInstance.capsuleName) ? capsules[mappedInstance.capsuleName] : undefined
                             const childParentCst = mappedCapsule?.cst || parentCapsuleCst

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

@@ -1,5 +1,5 @@
 import { CapsulePropertyTypes } from "../../encapsulate"
-import { ContractCapsuleInstanceFactory, CapsuleInstanceRegistry } from "./Static.v0"
+import { ContractCapsuleInstanceFactory, CapsuleInstanceRegistry } from "./Static"
 
 type CallerContext = {
     capsuleSourceLineRef: string
@@ -620,6 +620,86 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
         })
     }
 
+    protected override mapProxyFunctionProperty({ property }: { property: any }) {
+        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 }
+
+        const boundProxyFn = (...args: any[]) => {
+            const transformedArgs = invokeFn.call(selfProxy, ...args)
+            const target = targetFn.call(selfProxy)
+            if (transformedArgs && typeof transformedArgs.then === 'function') {
+                return transformedArgs.then((resolved: any) => target(resolved))
+            }
+            return target(transformedArgs)
+        }
+
+        Object.defineProperty(this.encapsulatedApi, property.name, {
+            get: () => {
+                return (...args: any[]) => {
+                    const callEvent: any = {
+                        event: 'call',
+                        eventIndex: this.incrementEventIndex(),
+                        membrane: 'external',
+                        target: {
+                            capsuleSourceLineRef: this.encapsulateOptions.capsuleSourceLineRef,
+                            spineContractCapsuleInstanceId: this.id,
+                            prop: property.name,
+                        },
+                        args
+                    }
+
+                    if (this.capsuleSourceNameRef) {
+                        callEvent.target.capsuleSourceNameRef = this.capsuleSourceNameRef
+                    }
+                    if (this.capsuleSourceNameRefHash) {
+                        callEvent.target.capsuleSourceNameRefHash = this.capsuleSourceNameRefHash
+                    }
+                    if (this.capsuleInstance?.capsuleSourceUriLineRefInstanceId) {
+                        callEvent.target.capsuleSourceUriLineRefInstanceId = this.capsuleInstance.capsuleSourceUriLineRefInstanceId
+                    }
+
+                    this.addCallerContextToEvent(callEvent)
+                    this.onMembraneEvent?.(callEvent)
+
+                    const previousCallerContext = this.getCurrentCallerContext()
+                    this.setCurrentCallerContext(this.buildCallerContext(property.name))
+                    const result = boundProxyFn(...args)
+                    this.setCurrentCallerContext(previousCallerContext)
+
+                    const resultEvent: any = {
+                        event: 'call-result',
+                        eventIndex: this.incrementEventIndex(),
+                        membrane: 'external',
+                        callEventIndex: callEvent.eventIndex,
+                        target: {
+                            spineContractCapsuleInstanceId: this.id,
+                        },
+                        result
+                    }
+
+                    this.onMembraneEvent?.(resultEvent)
+
+                    return result
+                }
+            },
+            enumerable: true,
+            configurable: true
+        })
+    }
+
     protected mapGetterFunctionProperty({ property }: { property: any }) {
         const getterFn = property.definition.value
         const selfProxy = this.createSelfProxy()
@@ -749,16 +829,13 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
                 }
 
                 // Determine the value source and get the value
+                // Virtual dispatch: child overrides take precedence over both
+                // self and own encapsulatedApi, matching class-inheritance semantics
                 let value: any
                 let source: 'self' | 'encapsulatedApi' | 'childApi' | 'extendedApi' | undefined
 
-                if (prop in target) {
-                    value = target[prop]
-                    source = 'self'
-                } else if (prop in factory.encapsulatedApi) {
-                    value = factory.encapsulatedApi[prop]
-                    source = 'encapsulatedApi'
-                } else if (factory.childEncapsulatedApis) {
+                // Check child capsule APIs first for virtual dispatch
+                if (factory.childEncapsulatedApis) {
                     for (const childApi of factory.childEncapsulatedApis) {
                         if (prop in childApi) {
                             value = childApi[prop]
@@ -768,6 +845,16 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
                     }
                 }
 
+                if (source === undefined) {
+                    if (prop in target) {
+                        value = target[prop]
+                        source = 'self'
+                    } else if (prop in factory.encapsulatedApi) {
+                        value = factory.encapsulatedApi[prop]
+                        source = 'encapsulatedApi'
+                    }
+                }
+
                 if (source === undefined && extendedApi && prop in extendedApi) {
                     value = extendedApi[prop]
                     source = 'extendedApi'

package/src/spine-contracts/CapsuleSpineContract.v0/README.md

@@ -263,6 +263,7 @@ All value types accept a `value` in their definition. `undefined` means "no defa
 | `Function` | `api.name(...args)` | `function(this, ...args)` | Callable method. Bound to self proxy. |
 | `GetterFunction` | `api.name` (no parens) | `function(this)` | Lazy getter. Evaluated on each access (unless memoized). |
 | `SetterFunction` | `api.name = value` | `function(this, value)` | Triggered on assignment. Enables validation/transformation logic. |
+| `ProxyFunction` | `api.name(...args)` | `{ target(this), invoke(this, ...args) }` | Wraps a target function with argument transformation. See below. |
 
 All function types are bound to a **self proxy** where:
 - `this.<prop>` resolves through: self → encapsulatedApi → extendedCapsuleApi
@@ -290,6 +291,31 @@ Applies to `Function` and `GetterFunction`. Added as a sibling to `type` and `va
 
 Memoize caches are scoped per spine contract capsule instance and cleared automatically when `run()` completes.
 
+#### ProxyFunction
+
+`ProxyFunction` wraps calling a target function with argument transformation. Its `value` is an object with two methods:
+
+- **`target(this)`** — resolves the function to call (bound to self proxy)
+- **`invoke(this, ...args)`** — transforms the caller's arguments before passing to target (bound to self proxy, may be async)
+
+```ts
+{
+    type: CapsulePropertyTypes.ProxyFunction,
+    value: {
+        target() { return this.service.fetchData },           // resolve target fn
+        async invoke(pathname: string) {                      // transform args
+            const origin = this.origin
+            return { url: `http://${origin}${pathname}`, headers: { Host: origin } }
+        }
+    }
+}
+```
+
+When `api.name(...args)` is called:
+1. `invoke(...args)` runs with self proxy as `this`, returning transformed args
+2. `target()` runs with self proxy as `this`, returning the function to call
+3. The target function is called with the transformed args (awaited if `invoke` returns a promise)
+
 ### Mapping
 
 `Mapping` composes another capsule as a sub-component.
@@ -382,13 +408,13 @@ A capsule can inherit properties from a parent capsule:
 - `this.self` in a parent function returns the parent's own values (`ownSelf`), not the merged context.
 - Multiple capsules can extend the same parent — each gets a separate parent instance with its own `self`.
 
-### Spine Contracts: Static.v0 vs Membrane.v0
+### Spine Contracts: Static vs Membrane
 
 Both implement the same property mapping logic. The difference is observability.
 
-**Static.v0** — direct property assignment. No interception. Minimal overhead.
+**Static** — direct property assignment. No interception. Minimal overhead.
 
-**Membrane.v0** — wraps the API in proxies that emit events for every property access:
+**Membrane** — wraps the API in proxies that emit events for every property access:
 
 | Event | Emitted When | Payload |
 |---|---|---|

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

@@ -107,6 +107,8 @@ export class ContractCapsuleInstanceFactory {
             this.mapDisposeProperty({ property })
         } else if (property.definition.type === CapsulePropertyTypes.OnFreeze) {
             this.mapOnFreezeProperty({ property })
+        } else if (property.definition.type === CapsulePropertyTypes.ProxyFunction) {
+            this.mapProxyFunctionProperty({ property })
         }
     }
 
@@ -134,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' &&
@@ -405,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]
@@ -447,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
             }
@@ -565,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

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

@@ -1,8 +1,8 @@
 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')

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/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'