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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@stream44.studio/encapsulate",
-    "version": "0.4.0-rc.32",
+    "version": "0.4.0-rc.38",
     "license": "MIT",
     "repository": {
         "type": "git",
@@ -14,7 +14,8 @@
         "./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-factories/TimingObserver": "./src/spine-factories/TimingObserver.ts",
-        "./structs/Capsule": "./structs/Capsule.ts"
+        "./structs/Capsule": "./structs/Capsule.ts",
+        "./structs/CapsuleProjectionContext": "./structs/CapsuleProjectionContext.ts"
     },
     "scripts": {
         "test": "bun test",

package/src/capsule-projectors/CapsuleModuleProjector.v0.ts

@@ -199,6 +199,9 @@ export function CapsuleModuleProjector({
                         for (const nestedPropName in propContract.properties) {
                             if (nestedPropName.startsWith('/')) {
                                 const nestedProp = propContract.properties[nestedPropName]
+                                // Skip if this mapping has a propertyContractDelegate — the delegate
+                                // handles its own projection via OnFreeze
+                                if (nestedProp.propertyContractDelegate) continue
                                 // Check if this is a Mapping type property
                                 if (nestedProp.type === 'CapsulePropertyTypes.Mapping') {
                                     // First try to find the mapped capsule in ambient references
@@ -287,23 +290,6 @@ export function CapsuleModuleProjector({
         return uris
     }
 
-    // Helper: Check if capsule has solidjs.com/standalone property
-    function hasSolidJsProperty(capsule: any, spineContractUri: string): boolean {
-        const spineContract = capsule.cst.spineContracts[spineContractUri]
-        // Check both top-level and nested under '#' property contract
-        const topLevelProps = spineContract?.propertyContracts || {}
-        const nestedProps = spineContract?.propertyContracts?.['#']?.properties || {}
-
-        // Check for solidjs.com/standalone specifically
-        for (const key of Object.keys(topLevelProps)) {
-            if (key === 'solidjs.com/standalone') return true
-        }
-        for (const key of Object.keys(nestedProps)) {
-            if (key === 'solidjs.com/standalone') return true
-        }
-        return false
-    }
-
     // Helper: Check if capsule has encapsulate.dev/standalone property (with optional suffix)
     function hasStandaloneProperty(capsule: any, spineContractUri: string): boolean {
         const spineContract = capsule.cst.spineContracts[spineContractUri]
@@ -321,66 +307,6 @@ export function CapsuleModuleProjector({
         return false
     }
 
-    // Helper: Extract SolidJS component function from capsule definition
-    function extractSolidJsComponent(capsule: any, spineContractUri: string): string | null {
-        const spineContract = capsule.cst.spineContracts[spineContractUri]
-
-        // Check nested under '#' property contract first, looking for solidjs.com/standalone
-        const nestedProps = spineContract?.propertyContracts?.['#']?.properties || {}
-        const topLevelProps = spineContract?.propertyContracts || {}
-
-        let solidjsProp = null
-        for (const key of Object.keys(nestedProps)) {
-            if (key === 'solidjs.com/standalone') {
-                solidjsProp = nestedProps[key]
-                break
-            }
-        }
-        if (!solidjsProp) {
-            for (const key of Object.keys(topLevelProps)) {
-                if (key === 'solidjs.com/standalone') {
-                    solidjsProp = topLevelProps[key]
-                    break
-                }
-            }
-        }
-
-        if (!solidjsProp || solidjsProp.type !== 'CapsulePropertyTypes.Function') {
-            return null
-        }
-
-        // Extract the value expression which contains the component function
-        const valueExpression = solidjsProp.valueExpression
-        if (!valueExpression) return null
-
-        // The value expression is: "function (this: any): Function {\n    return function ComponentName() { ... }\n}"
-        // We need to extract the inner function after "return "
-        // Use a more flexible regex that handles multiline and varying whitespace
-        const match = valueExpression.match(/return\s+(function\s+\w*\s*\([^)]*\)\s*\{[\s\S]*)\s*\}\s*$/m)
-        if (match) {
-            // Clean up the extracted function - remove extra indentation
-            let extracted = match[1].trim()
-            // Add back the closing brace if it was removed
-            if (!extracted.endsWith('}')) {
-                extracted += '\n}'
-            }
-            // Remove leading indentation from each line
-            const lines = extracted.split('\n')
-            const minIndent = lines
-                .filter(line => line.trim().length > 0)
-                .map(line => line.match(/^(\s*)/)?.[1].length || 0)
-                .reduce((min, indent) => Math.min(min, indent), Infinity)
-
-            if (minIndent > 0 && minIndent !== Infinity) {
-                extracted = lines.map(line => line.substring(minIndent)).join('\n')
-            }
-
-            return extracted
-        }
-
-        return null
-    }
-
     // Helper: Extract standalone function from capsule definition
     function extractStandaloneFunction(capsule: any, spineContractUri: string): string | null {
         const spineContract = capsule.cst.spineContracts[spineContractUri]
@@ -812,196 +738,15 @@ export function CapsuleModuleProjector({
 
         const allStatements = [importStatements, literalReferences, moduleLocalFunctions].filter(Boolean).join('\n')
 
-        // Check if this capsule has a solidjs.com or standalone property
-        const hasSolidJs = hasSolidJsProperty(capsule, spineContractUri)
+        // Check if this capsule has an encapsulate.dev/standalone property
         const hasStandalone = hasStandaloneProperty(capsule, spineContractUri)
-        const needsRuntime = hasSolidJs || hasStandalone
-
-        // Determine which solid-js imports are needed (avoid duplicates with ambient references)
-        const existingSolidJsImports = new Set<string>()
-        for (const [name, ref] of Object.entries(ambientReferences)) {
-            const refTyped = ref as any
-            if (refTyped.type === 'import' && refTyped.moduleUri === 'solid-js') {
-                // Parse existing imports from solid-js
-                const match = refTyped.importSpecifier?.match(/\{([^}]+)\}/)
-                if (match) {
-                    match[1].split(',').forEach((imp: string) => existingSolidJsImports.add(imp.trim()))
-                }
-            }
-        }
-
-        const neededSolidJsImports = ['createSignal', 'onMount', 'Show'].filter(imp => !existingSolidJsImports.has(imp))
-        const solidJsImport = hasSolidJs && neededSolidJsImports.length > 0 ? `import { ${neededSolidJsImports.join(', ')} } from 'solid-js'\n` : ''
 
-        // Add runtime imports for SolidJS and standalone functions
-        const runtimeImport = needsRuntime ? `"use client"\nimport { Spine, SpineRuntime } from '@stream44.studio/encapsulate/encapsulate'\nimport { CapsuleSpineContract } from '@stream44.studio/encapsulate/spine-contracts/CapsuleSpineContract.v0/Membrane.v0'\n${solidJsImport}` : ''
+        // 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` : ''
 
         // Generate default export based on capsule type
         let defaultExport = ''
-        if (hasSolidJs) {
-            // Generate a wrapper that sets up runtime and exports the SolidJS component
-            const capsuleSourceLineRef = capsule.cst.capsuleSourceLineRef
-            const solidjsComponent = extractSolidJsComponent(capsule, spineContractUri)
-            if (solidjsComponent) {
-                // Collect all capsule URIs from CST (mappings and property contracts)
-                const allCapsuleUris = collectAllCapsuleUris(capsule, spineContractUri)
-
-                // Also collect from ambient references and build import paths from snapshots
-                const capsuleDeps: Array<{ uri: string, importName: string, importPath: string }> = []
-                for (const [name, ref] of Object.entries(ambientReferences)) {
-                    const refTyped = ref as any
-                    if (refTyped.type === 'capsule') {
-                        const snapshot = await buildCapsuleSnapshotForReference(refTyped, capsules, spineContractUri)
-
-                        // Use dynamic spineContractUri instead of hardcoded URI
-                        const contractData = snapshot.spineContracts?.[spineContractUri]
-                        const structKey = Object.keys(contractData || {}).find(k => k.includes('/structs/Capsule'))
-                        const capsuleName = structKey ? contractData[structKey]?.capsuleName : undefined
-                        const projectedFilepath = structKey ? contractData[structKey]?.projectedCapsuleFilepath : undefined
-
-                        if (capsuleName && projectedFilepath) {
-                            allCapsuleUris.add(capsuleName)
-
-                            // Build import path from projected filepath
-                            const importName = `_capsule_${capsuleName.replace(/[^a-zA-Z0-9]/g, '_')}`
-                            // Remove .~o/encapsulate.dev/caps/ prefix and strip extension
-                            const importPath = projectedFilepath.replace(/^\.~o\/encapsulate\.dev\/caps\//, '').replace(/\.(ts|tsx)$/, '')
-
-                            capsuleDeps.push({ uri: capsuleName, importName, importPath })
-                        }
-                    }
-                }
-
-                // Generate static imports for all capsule dependencies
-                // Compute relative path from projected file to caps directory
-                let importPrefix: string
-                if (capsuleModuleProjectionPackage) {
-                    importPrefix = capsuleModuleProjectionPackage
-                } else {
-                    const projectedFileDir = dirname(filepath)
-                    const capsDir = '.~o/encapsulate.dev/caps'
-                    const relativePathToCaps = relative(projectedFileDir, capsDir)
-                    importPrefix = relativePathToCaps.startsWith('.') ? relativePathToCaps : './' + relativePathToCaps
-                }
-                const capsuleImports = capsuleDeps.map(dep =>
-                    `import * as ${dep.importName} from '${importPrefix}/${dep.importPath}'`
-                ).join('\n')
-
-                // Generate capsules map
-                const capsulesMapEntries = capsuleDeps.map(dep =>
-                    `    '${dep.uri}': ${dep.importName}`
-                ).join(',\n')
-
-                defaultExport = `
-${capsuleImports}
-
-// Set up runtime for browser execution
-const sourceSpine: { encapsulate?: any } = {}
-
-// Map of statically imported capsules
-const capsulesMap: Record<string, any> = {
-${capsulesMapEntries}
-}
-
-// Helper to import and instantiate a capsule from the capsules map
-const importCapsule = async (uri: string) => {
-    const capsuleModule = capsulesMap[uri]
-    if (!capsuleModule) {
-        throw new Error(\`Capsule not found in static imports: \${uri}\`)
-    }
-    const capsule = await capsuleModule.capsule({
-        encapsulate: sourceSpine.encapsulate,
-        loadCapsule
-    })
-    return capsule
-}
-
-const loadCapsule = async ({ capsuleSourceLineRef, capsuleName }: any) => {
-    // Return the capsule function from this projected file
-    if (capsuleSourceLineRef === '${capsuleSourceLineRef}') {
-        return capsule
-    }
-    
-    // Use capsuleName directly if provided
-    if (capsuleName) {
-        return await importCapsule(capsuleName)
-    }
-    
-    throw new Error(\`Cannot load capsule: \${capsuleSourceLineRef}\`)
-}
-
-const spineContractOpts = {
-    spineFilesystemRoot: '.',
-    resolve: async (uri: string) => uri,
-    importCapsule
-}
-
-const runtimeSpineContracts = {
-    ['#' + CapsuleSpineContract['#']]: CapsuleSpineContract(spineContractOpts)
-}
-
-const snapshot = {
-    capsules: {
-        ['${capsuleSourceLineRef}']: {
-            spineContracts: {}
-        }
-    }
-}
-
-// Export wrapper function that initializes runtime and returns component
-export default function({ onMembraneEvent }: { onMembraneEvent?: (event: any) => void } = {}) {
-    const [component, setComponent] = createSignal(null)
-    
-    onMount(async () => {
-        // Add onMembraneEvent to spine contract opts - use provided or default logger
-        const defaultMembraneLogger = (event: any) => {
-            console.log('[Membrane Event]', event)
-        }
-        const opts = { 
-            ...spineContractOpts, 
-            onMembraneEvent: onMembraneEvent || defaultMembraneLogger 
-        }
-        const contracts = {
-            ['#' + CapsuleSpineContract['#']]: CapsuleSpineContract(opts)
-        }
-        
-        const { encapsulate, capsules } = await Spine({ 
-            spineFilesystemRoot: '.', 
-            spineContracts: contracts 
-        })
-        
-        sourceSpine.encapsulate = encapsulate
-        
-        const capsuleInstance = await capsule({ encapsulate, loadCapsule })
-        
-        const { run } = await SpineRuntime({ 
-            spineFilesystemRoot: '.', 
-            spineContracts: contracts,
-            snapshot,
-            loadCapsule
-        })
-        
-        const Component = await run({}, async ({ apis }) => {
-            const capsuleApi = apis['${capsuleSourceLineRef}']
-            const solidjsKey = Object.keys(capsuleApi).find(k => k === 'solidjs.com/standalone')
-            if (!solidjsKey) throw new Error('solidjs.com/standalone property not found')
-            return capsuleApi[solidjsKey]()
-        })
-        
-        setComponent(() => Component)
-    })
-    
-    // Return the wrapper function itself, not call it
-    const WrapperComponent = () => {
-        const Component = component()
-        return Show({ when: Component, children: (Component) => Component() })
-    }
-    
-    return WrapperComponent
-}
-`
-            }
-        } else if (hasStandalone) {
+        if (hasStandalone) {
             // Generate a wrapper function that directly invokes the standalone function
             const capsuleSourceLineRef = capsule.cst.capsuleSourceLineRef
 
@@ -1095,6 +840,7 @@ ${capsulesMapEntries}
         }
         const capsule = await capsuleModule.capsule({
             encapsulate: sourceSpine.encapsulate,
+            CapsulePropertyTypes,
             loadCapsule
         })
         return capsule
@@ -1255,8 +1001,12 @@ ${defaultExport}
                 mappedCapsule.cst.source.moduleFilepath
             )
 
-            // Get ambient references for the mapped capsule
-            const mappedAmbientRefs = mappedCapsule.cst.source?.ambientReferences || {}
+            // Get ambient references for the mapped capsule, excluding makeImportStack
+            let mappedAmbientRefs = mappedCapsule.cst.source?.ambientReferences || {}
+            if (mappedAmbientRefs['makeImportStack']) {
+                mappedAmbientRefs = { ...mappedAmbientRefs }
+                delete mappedAmbientRefs['makeImportStack']
+            }
 
             // Generate import statements with projection CSS paths
             const mappedImportStatements = Object.entries(mappedAmbientRefs)
@@ -1315,191 +1065,17 @@ ${defaultExport}
 
             const mappedAllStatements = [mappedImportStatements, mappedLiteralReferences, mappedModuleLocalFunctions].filter(Boolean).join('\n')
 
-            // Check if mapped capsule has solidjs.com or encapsulate.dev/standalone property
-            const mappedHasSolidJs = hasSolidJsProperty(mappedCapsule, spineContractUri)
+            // Check if mapped capsule has encapsulate.dev/standalone property
             const mappedHasStandalone = hasStandaloneProperty(mappedCapsule, spineContractUri)
-            const mappedNeedsRuntime = mappedHasSolidJs || mappedHasStandalone
-
-            // Determine which solid-js imports are needed for mapped capsule
-            const mappedExistingSolidJsImports = new Set<string>()
-            for (const [name, ref] of Object.entries(mappedAmbientRefs)) {
-                const refTyped = ref as any
-                if (refTyped.type === 'import' && refTyped.moduleUri === 'solid-js') {
-                    const match = refTyped.importSpecifier?.match(/\{([^}]+)\}/)
-                    if (match) {
-                        match[1].split(',').forEach((imp: string) => mappedExistingSolidJsImports.add(imp.trim()))
-                    }
-                }
-            }
-
-            const mappedNeededSolidJsImports = ['createSignal', 'onMount', 'Show'].filter(imp => !mappedExistingSolidJsImports.has(imp))
-            const mappedSolidJsImport = mappedHasSolidJs && mappedNeededSolidJsImports.length > 0 ? `import { ${mappedNeededSolidJsImports.join(', ')} } from 'solid-js'\n` : ''
 
             // Rewrite the mapped capsule expression to include CST (reuse the same function)
             const mappedCapsuleExpression = rewriteCapsuleExpressionWithCST(mappedCapsule)
 
-            // Add runtime imports for SolidJS and standalone functions
-            const mappedRuntimeImport = mappedNeedsRuntime ? `"use client"\nimport { Spine, SpineRuntime } from '@stream44.studio/encapsulate/encapsulate'\nimport { CapsuleSpineContract } from '@stream44.studio/encapsulate/spine-contracts/CapsuleSpineContract.v0/Membrane.v0'\n${mappedSolidJsImport}` : ''
+            // 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` : ''
 
             let mappedDefaultExport = ''
-            if (mappedHasSolidJs) {
-                // Generate a wrapper that sets up runtime and exports the SolidJS component
-                const mappedCapsuleSourceLineRef = mappedCapsule.cst.capsuleSourceLineRef
-                const solidjsComponent = extractSolidJsComponent(mappedCapsule, spineContractUri)
-                if (solidjsComponent) {
-                    // Collect all capsule URIs from CST (mappings and property contracts)
-                    const allMappedCapsuleUris = collectAllCapsuleUris(mappedCapsule, spineContractUri)
-
-                    // Also collect from ambient references
-                    for (const [name, ref] of Object.entries(mappedAmbientRefs)) {
-                        const refTyped = ref as any
-                        if (refTyped.type === 'capsule') {
-                            const snapshot = await buildCapsuleSnapshotForReference(refTyped, capsules, spineContractUri)
-                            const contractData = snapshot.spineContracts?.[spineContractUri]
-                            const structKey = Object.keys(contractData || {}).find(k => k.includes('/structs/Capsule'))
-                            const capsuleName = structKey ? contractData[structKey]?.capsuleName : undefined
-                            if (capsuleName) {
-                                allMappedCapsuleUris.add(capsuleName)
-                            }
-                        }
-                    }
-
-                    // Build capsule dependencies array
-                    const mappedCapsuleDeps: Array<{ uri: string, importName: string, importPath: string }> = []
-                    for (const uri of allMappedCapsuleUris) {
-                        const importName = `_capsule_${uri.replace(/[^a-zA-Z0-9]/g, '_')}`
-                        // Strip leading @ to match caps filesystem paths
-                        const importPath = uri.startsWith('@') ? uri.substring(1) : uri
-                        mappedCapsuleDeps.push({ uri, importName, importPath })
-                    }
-
-                    // Generate static imports for all capsule dependencies
-                    // Compute relative path from projected file to caps directory
-                    let importPrefix: string
-                    if (capsuleModuleProjectionPackage) {
-                        importPrefix = capsuleModuleProjectionPackage
-                    } else {
-                        const projectedFileDir = dirname(mapped.projectionPath)
-                        const capsDir = '.~o/encapsulate.dev/caps'
-                        const relativePathToCaps = relative(projectedFileDir, capsDir)
-                        importPrefix = relativePathToCaps.startsWith('.') ? relativePathToCaps : './' + relativePathToCaps
-                    }
-                    const mappedCapsuleImports = mappedCapsuleDeps.map(dep =>
-                        `import * as ${dep.importName} from '${importPrefix}/${dep.importPath}'`
-                    ).join('\n')
-
-                    // Generate capsules map
-                    const mappedCapsulesMapEntries = mappedCapsuleDeps.map(dep =>
-                        `    '${dep.uri}': ${dep.importName}`
-                    ).join(',\n')
-
-                    mappedDefaultExport = `
-${mappedCapsuleImports}
-
-// Set up runtime for browser execution
-const sourceSpine: { encapsulate?: any } = {}
-
-// Map of statically imported capsules
-const capsulesMap: Record<string, any> = {
-${mappedCapsulesMapEntries}
-}
-
-// Helper to import and instantiate a capsule from the capsules map
-const importCapsule = async (uri: string) => {
-    const capsuleModule = capsulesMap[uri]
-    if (!capsuleModule) {
-        throw new Error(\`Capsule not found in static imports: \${uri}\`)
-    }
-    const capsule = await capsuleModule.capsule({
-        encapsulate: sourceSpine.encapsulate,
-        loadCapsule
-    })
-    return capsule
-}
-
-const loadCapsule = async ({ capsuleSourceLineRef, capsuleName }: any) => {
-    // Return the capsule function from this projected file
-    if (capsuleSourceLineRef === '${mappedCapsuleSourceLineRef}') {
-        return capsule
-    }
-    
-    // Use capsuleName directly if provided
-    if (capsuleName) {
-        return await importCapsule(capsuleName)
-    }
-    
-    throw new Error(\`Cannot load capsule: \${capsuleSourceLineRef}\`)
-}
-
-const spineContractOpts = {
-    spineFilesystemRoot: '.',
-    resolve: async (uri: string) => uri,
-    importCapsule
-}
-
-const runtimeSpineContracts = {
-    ['#' + CapsuleSpineContract['#']]: CapsuleSpineContract(spineContractOpts)
-}
-
-const snapshot = {
-    capsules: {
-        ['${mappedCapsuleSourceLineRef}']: {
-            spineContracts: {}
-        }
-    }
-}
-
-// Export wrapper function that initializes runtime and returns component
-export default function({ onMembraneEvent }: { onMembraneEvent?: (event: any) => void } = {}) {
-    const [component, setComponent] = createSignal(null)
-    
-    onMount(async () => {
-        // Add onMembraneEvent to spine contract opts - use provided or default logger
-        const defaultMembraneLogger = (event: any) => {
-            console.log('[Membrane Event]', event.type, event)
-        }
-        const opts = { 
-            ...spineContractOpts, 
-            onMembraneEvent: onMembraneEvent || defaultMembraneLogger 
-        }
-        const contracts = {
-            ['#' + CapsuleSpineContract['#']]: CapsuleSpineContract(opts)
-        }
-        
-        const { encapsulate, capsules } = await Spine({ 
-            spineFilesystemRoot: '.', 
-            spineContracts: contracts 
-        })
-        
-        sourceSpine.encapsulate = encapsulate
-        
-        const capsuleInstance = await capsule({ encapsulate, loadCapsule })
-        
-        const { run } = await SpineRuntime({ 
-            spineFilesystemRoot: '.', 
-            spineContracts: contracts,
-            snapshot,
-            loadCapsule
-        })
-        
-        const Component = await run({}, async ({ apis }) => {
-            const capsuleApi = apis['${mappedCapsuleSourceLineRef}']
-            const solidjsKey = Object.keys(capsuleApi).find(k => k === 'solidjs.com/standalone')
-            if (!solidjsKey) throw new Error('solidjs.com/standalone property not found')
-            return capsuleApi[solidjsKey]()
-        })
-        
-        setComponent(() => Component)
-    })
-    
-    return () => {
-        const Component = component()
-        return Show({ when: Component, children: (Component) => Component() })
-    }
-}
-`
-                }
-            } else if (mappedHasStandalone) {
+            if (mappedHasStandalone) {
                 // Generate a wrapper function that directly invokes the standalone function
                 const mappedCapsuleSourceLineRef = mappedCapsule.cst.capsuleSourceLineRef
 
@@ -1570,6 +1146,7 @@ ${mappedCapsulesMapEntries}
         }
         const capsule = await capsuleModule.capsule({
             encapsulate: sourceSpine.encapsulate,
+            CapsulePropertyTypes,
             loadCapsule
         })
         return capsule
@@ -1726,10 +1303,38 @@ ${mappedDefaultExport}
                         .filter(Boolean)
                         .join('\n    ')
 
-                    // Add necessary imports
-                    const imports = `import { CapsulePropertyTypes } from '@stream44.studio/encapsulate/encapsulate'
-import { makeImportStack } from '@stream44.studio/encapsulate/encapsulate'
-`
+                    // Filter out makeImportStack from ambient references (same as main capsule path)
+                    let filteredCapsuleAmbientRefs = capsuleAmbientRefs
+                    if (filteredCapsuleAmbientRefs['makeImportStack']) {
+                        filteredCapsuleAmbientRefs = { ...filteredCapsuleAmbientRefs }
+                        delete filteredCapsuleAmbientRefs['makeImportStack']
+                    }
+
+                    // Generate imports from filtered ambient references
+                    const capsuleImportStatements = Object.entries(filteredCapsuleAmbientRefs)
+                        .map(([name, ref]: [string, any]) => {
+                            if (ref.type === 'import') {
+                                if (ref.moduleUri.endsWith('.css')) {
+                                    return `import '${ref.moduleUri}'`
+                                }
+                                return `import ${ref.importSpecifier} from '${ref.moduleUri}'`
+                            }
+                            if (ref.type === 'assigned') {
+                                if (ref.moduleUri.includes('/spine-factories/')) {
+                                    return `import { ${name} } from '@stream44.studio/encapsulate/encapsulate'`
+                                }
+                            }
+                            if (ref.type === 'invocation-argument') {
+                                if (ref.isEncapsulateExport) {
+                                    return `import { ${name} } from '@stream44.studio/encapsulate/encapsulate'`
+                                }
+                            }
+                            return ''
+                        })
+                        .filter(Boolean)
+                        .join('\n')
+
+                    const imports = capsuleImportStatements ? capsuleImportStatements + '\n' : ''
 
                     // Get the capsule name for the assignment
                     const capsuleName = registryCapsule.cst.source.capsuleName || ''

package/src/encapsulate.ts

@@ -7,7 +7,16 @@ type TSpineOptions = {
     spineFilesystemRoot?: string,
     spineContracts: Record<string, any>,
     staticAnalyzer?: any,
-    timing?: { record: (step: string) => void, chalk?: any }
+    timing?: { record: (step: string) => void, chalk?: any },
+    projectionContext?: {
+        capsuleModuleProjectionPackage?: string,
+        capsuleModuleProjectionRoot?: string,
+        projectionStore?: {
+            writeFile: (filepath: string, content: string) => Promise<void>,
+            getStats?: (filepath: string) => Promise<{ mtime: Date } | null>
+        } | null,
+        capsules?: Record<string, any>
+    }
 }
 
 type TSpineRunOptions = {
@@ -115,6 +124,7 @@ export const CapsulePropertyTypes = {
     StructDispose: 'StructDispose' as const,
     Init: 'Init' as const,
     Dispose: 'Dispose' as const,
+    OnFreeze: 'OnFreeze' as const,
 }
 
 // ##################################################
@@ -430,7 +440,13 @@ export async function Spine(options: TSpineOptions): Promise<TSpine> {
 
             options.timing?.record(`Spine: Freezing ${Object.keys(capsules).length} capsules`)
 
-            await Promise.all(Object.entries(capsules).map(async ([capsuleSourceLineRef, capsule]) => {
+            const processedCapsules = new Set<any>()
+            const freezeVisited = new Set<any>()
+            for (const [capsuleSourceLineRef, capsule] of Object.entries(capsules)) {
+
+                // Skip capsuleName aliases — only process each capsule once via its capsuleSourceLineRef
+                if (processedCapsules.has(capsule)) continue
+                processedCapsules.add(capsule)
 
                 if (!capsule.cst.source.capsuleName) throw new Error(`'capsuleName' must be set for encapsulate options to enable freezing.`)
 
@@ -438,10 +454,95 @@ export async function Spine(options: TSpineOptions): Promise<TSpine> {
                     cst: capsule.cst,
                     spineContracts: {}
                 }
+                // Also register under capsuleName so SpineRuntime can resolve by name
+                if (capsule.cst.source.capsuleName && capsule.cst.source.capsuleName !== capsuleSourceLineRef) {
+                    snapshot.capsules[capsule.cst.source.capsuleName] = snapshot.capsules[capsuleSourceLineRef]
+                }
+
+                const capsuleInstance = await capsule.makeInstance()
+
+                // Run OnFreeze functions so capsules can perform side effects
+                // (e.g. file projection) at build/freeze time
+                async function runOnFreeze(instance: any, parentCapsuleCst?: any, parentCapsuleSourceLineRef?: string, projectionPath?: string, projectionSpineContractUri?: string) {
+                    if (!instance) return
+                    // Use capsuleSourceLineRef for deduplication — this is stable across different
+                    // instance objects of the same capsule (top-level vs mapped child).
+                    // Include projectionPath in the key so the same capsule can project to
+                    // multiple output paths (e.g. standalone delegate used by different parents).
+                    // Fall back to instance identity for internal capsules without a lineRef.
+                    // Use capsuleName as the base key when available (always a unique string),
+                    // otherwise fall back to capsuleSourceLineRef or instance identity.
+                    // This avoids collisions from object refs that all stringify to '[object Object]'.
+                    const baseKey = instance.capsuleName || instance.capsuleSourceLineRef || instance
+                    const freezeKey = projectionPath ? `${baseKey}::${projectionPath}` : baseKey
+                    if (freezeVisited.has(freezeKey)) return
+                    freezeVisited.add(freezeKey)
+
+                    // Inject projection context onto CapsuleProjectionContext instances
+                    // Set values on both the api (encapsulatedApi) and spine contract self
+                    // so they are visible through all proxy chains.
+                    // Scan recursively into mapped children since CapsuleProjectionContext
+                    // may be nested inside a property contract delegate (e.g. a projector capsule).
+                    const projectionCtx = options.projectionContext
+                    if (projectionCtx && instance.mappedCapsuleInstances?.length) {
+                        const injectCtx = (children: any[]) => {
+                            for (const mappedChild of children) {
+                                const childApi = mappedChild.api
+                                if (childApi && mappedChild.capsuleName === '@stream44.studio/encapsulate/structs/CapsuleProjectionContext') {
+                                    const ctx = {
+                                        parentCapsuleCst: parentCapsuleCst,
+                                        parentCapsuleSourceLineRef: parentCapsuleSourceLineRef,
+                                        capsuleModuleProjectionPackage: projectionCtx.capsuleModuleProjectionPackage,
+                                        projectionStore: projectionCtx.projectionStore,
+                                        capsuleSnapshots: projectionCtx.capsules,
+                                        projectionPath: projectionPath,
+                                        spineContractUri: projectionSpineContractUri,
+                                    }
+                                    Object.assign(childApi, ctx)
+                                    // Also update spine contract self for selfProxy access
+                                    for (const childSci of Object.values(mappedChild.spineContractCapsuleInstances || {})) {
+                                        const childSelf = (childSci as any).self
+                                        if (childSelf) Object.assign(childSelf, ctx)
+                                    }
+                                }
+                                // Recurse into delegate's mapped children
+                                if (mappedChild.mappedCapsuleInstances?.length) {
+                                    injectCtx(mappedChild.mappedCapsuleInstances)
+                                }
+                            }
+                        }
+                        injectCtx(instance.mappedCapsuleInstances)
+                    }
 
-                const { spineContractCapsuleInstances } = await capsule.makeInstance()
+                    if (instance.onFreezeFunctions?.length) {
+                        for (const fn of instance.onFreezeFunctions) {
+                            await fn()
+                        }
+                    }
 
-                await Promise.all(Object.entries(spineContractCapsuleInstances).map(async ([spineContractUri, spineContractCapsuleInstance]) => {
+                    if (instance.extendedCapsuleInstance) {
+                        await runOnFreeze(instance.extendedCapsuleInstance, parentCapsuleCst, parentCapsuleSourceLineRef, projectionPath, projectionSpineContractUri)
+                    }
+                    if (instance.mappedCapsuleInstances?.length) {
+                        for (const mappedInstance of instance.mappedCapsuleInstances) {
+                            // Determine projection path from the property name (alias) used for this mapping.
+                            // If the mapped child doesn't define its own path (no / prefix), inherit the parent's projectionPath
+                            // so it flows down to property contract delegates.
+                            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
+                            // 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
+                            const instanceSourceLineRef = instance.capsuleSourceLineRef || parentCapsuleSourceLineRef
+                            await runOnFreeze(mappedInstance, childParentCst, instanceSourceLineRef, mappedProjectionPath, Object.keys(capsuleInstance.spineContractCapsuleInstances)?.[0])
+                        }
+                    }
+                }
+                await runOnFreeze(capsuleInstance, capsule.cst, capsule.capsuleSourceLineRef)
+
+                await Promise.all(Object.entries(capsuleInstance.spineContractCapsuleInstances).map(async ([spineContractUri, spineContractCapsuleInstance]) => {
 
                     snapshot.capsules[capsuleSourceLineRef] = merge(
                         snapshot.capsules[capsuleSourceLineRef],
@@ -451,7 +552,7 @@ export async function Spine(options: TSpineOptions): Promise<TSpine> {
                         })
                     )
                 }))
-            }))
+            }
 
             options.timing?.record('Spine: Freeze complete')
 
@@ -621,7 +722,7 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                                 // Check if 'as' is defined to use as the property name alias
                                 const propDefTyped = propDef as Record<string, any>
                                 const aliasName = propDefTyped.as
-                                const delegateOptions = propDefTyped.options
+                                let delegateOptions = propDefTyped.options
                                 const contractKey = aliasName || ('#' + propContractUri.substring(1))
 
                                 if (!propertyContractDefinitions[spineContractUri]['#']) {
@@ -835,8 +936,8 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                             moduleFilepath: absoluteModuleFilepath
                         },
                         parentCapsuleSourceUriLineRefInstanceId: parentCapsuleSourceUriLineRefInstanceId
-                            ? sha256(parentCapsuleSourceUriLineRefInstanceId + ':' + (cst?.capsuleSourceUriLineRef || encapsulateOptions.capsuleSourceLineRef))
-                            : sha256(cst?.capsuleSourceUriLineRef || encapsulateOptions.capsuleSourceLineRef),
+                            ? await sha256(parentCapsuleSourceUriLineRefInstanceId + ':' + (cst?.capsuleSourceUriLineRef || encapsulateOptions.capsuleSourceLineRef))
+                            : await sha256(cst?.capsuleSourceUriLineRef || encapsulateOptions.capsuleSourceLineRef),
                         sit
                     })
 
@@ -873,8 +974,8 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                 //   child: sha256(parentCapsuleSourceUriLineRefInstanceId + ":" + capsuleSourceUriLineRef)
                 const capsuleSourceUriLineRef = cst?.capsuleSourceUriLineRef || encapsulateOptions.capsuleSourceLineRef
                 const capsuleSourceUriLineRefInstanceId = parentCapsuleSourceUriLineRefInstanceId
-                    ? sha256(parentCapsuleSourceUriLineRefInstanceId + ':' + capsuleSourceUriLineRef)
-                    : sha256(capsuleSourceUriLineRef)
+                    ? await sha256(parentCapsuleSourceUriLineRefInstanceId + ':' + capsuleSourceUriLineRef)
+                    : await sha256(capsuleSourceUriLineRef)
 
                 // Register this instance in the sit structure if provided
                 if (sit) {
@@ -893,6 +994,7 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                     structDisposeFunctions: [] as Array<() => any>,
                     initFunctions: [] as Array<() => any>,
                     disposeFunctions: [] as Array<() => any>,
+                    onFreezeFunctions: [] as Array<() => any>,
                     mappedCapsuleInstances: [] as Array<any>,
                     rootCapsule: resolvedRootCapsule,
                     capsuleSourceUriLineRefInstanceId,
@@ -987,6 +1089,9 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
                     if (sci.disposeFunctions?.length) {
                         capsuleInstance.disposeFunctions.push(...sci.disposeFunctions)
                     }
+                    if (sci.onFreezeFunctions?.length) {
+                        capsuleInstance.onFreezeFunctions.push(...sci.onFreezeFunctions)
+                    }
                     if (sci.mappedCapsuleInstances?.length) {
                         capsuleInstance.mappedCapsuleInstances.push(...sci.mappedCapsuleInstances)
                     }
@@ -1124,15 +1229,15 @@ function relative(from: string, to: string): string {
     return result || '.'
 }
 
-function sha256(input: string): string {
-    // Use Bun's native hasher for speed; falls back to Node crypto
-    if (typeof globalThis.Bun !== 'undefined') {
-        const hasher = new globalThis.Bun.CryptoHasher('sha256')
-        hasher.update(input)
-        return hasher.digest('hex') as string
+async function sha256(input: string): Promise<string> {
+    const data = new TextEncoder().encode(input)
+    const hashBuffer = await crypto.subtle.digest('SHA-256', data)
+    const hashArray = new Uint8Array(hashBuffer)
+    let hex = ''
+    for (let i = 0; i < hashArray.length; i++) {
+        hex += hashArray[i].toString(16).padStart(2, '0')
     }
-    const { createHash } = require('crypto')
-    return createHash('sha256').update(input).digest('hex')
+    return hex
 }
 
 function isObject(item: any): boolean {

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

@@ -1,7 +1,5 @@
 import { CapsulePropertyTypes } from "../../encapsulate"
 import { ContractCapsuleInstanceFactory, CapsuleInstanceRegistry } from "./Static.v0"
-import { readFileSync, existsSync } from "node:fs"
-import { dirname, relative, join } from "node:path"
 
 type CallerContext = {
     capsuleSourceLineRef: string
@@ -60,6 +58,7 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
     private setCurrentCallerContext: (ctx: CallerContext | undefined) => void
     private onMembraneEvent?: (event: any) => void
     private enableCallerStackInference: boolean
+    private npmUriForFilepathSync?: (filepath: string) => string | null
     private encapsulateOptions: any
     private capsuleSourceNameRef?: string
     private capsuleSourceNameRefHash?: string
@@ -78,6 +77,7 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
         freezeCapsule,
         onMembraneEvent,
         enableCallerStackInference,
+        npmUriForFilepathSync,
         encapsulateOptions,
         getEventIndex,
         incrementEventIndex,
@@ -99,6 +99,7 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
         freezeCapsule?: (capsule: any) => Promise<any>
         onMembraneEvent?: (event: any) => void
         enableCallerStackInference: boolean
+        npmUriForFilepathSync?: (filepath: string) => string | null
         encapsulateOptions: any
         getEventIndex: () => number
         incrementEventIndex: () => number
@@ -116,6 +117,7 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
         this.setCurrentCallerContext = setCurrentCallerContext
         this.onMembraneEvent = onMembraneEvent
         this.enableCallerStackInference = enableCallerStackInference
+        this.npmUriForFilepathSync = npmUriForFilepathSync
         this.encapsulateOptions = encapsulateOptions
         this.capsuleSourceNameRef = capsule?.cst?.capsuleSourceNameRef
         this.capsuleSourceNameRefHash = capsule?.cst?.capsuleSourceNameRefHash
@@ -184,7 +186,7 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
                                 if (this.enableCallerStackInference) {
                                     const stackStr = new Error('[MAPPED_CAPSULE]').stack
                                     if (stackStr) {
-                                        const stackFrames = parseCallerFromStack(stackStr, this.spineFilesystemRoot)
+                                        const stackFrames = parseCallerFromStack(stackStr, this.spineFilesystemRoot, this.npmUriForFilepathSync)
                                         if (stackFrames.length > 0) {
                                             const callerInfo = extractCallerInfo(stackFrames, 3)
                                             callerCtx.fileUri = callerInfo.fileUri
@@ -311,7 +313,7 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
                     if (this.enableCallerStackInference) {
                         const stackStr = new Error('[MAPPED_CAPSULE]').stack
                         if (stackStr) {
-                            const stackFrames = parseCallerFromStack(stackStr, this.spineFilesystemRoot)
+                            const stackFrames = parseCallerFromStack(stackStr, this.spineFilesystemRoot, this.npmUriForFilepathSync)
                             if (stackFrames.length > 0) {
                                 const callerInfo = extractCallerInfo(stackFrames, 3)
                                 callerCtx.fileUri = callerInfo.fileUri
@@ -374,7 +376,7 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
                                 if (this.enableCallerStackInference) {
                                     const stackStr = new Error('[PROPERTY_CONTRACT_DELEGATE]').stack
                                     if (stackStr) {
-                                        const stackFrames = parseCallerFromStack(stackStr, this.spineFilesystemRoot)
+                                        const stackFrames = parseCallerFromStack(stackStr, this.spineFilesystemRoot, this.npmUriForFilepathSync)
                                         if (stackFrames.length > 0) {
                                             const callerInfo = extractCallerInfo(stackFrames, 3)
                                             callerCtx.fileUri = callerInfo.fileUri
@@ -892,7 +894,7 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
         } else if (this.enableCallerStackInference) {
             const stackStr = new Error('[MEMBRANE_EVENT]').stack
             if (stackStr) {
-                const stackFrames = parseCallerFromStack(stackStr, this.spineFilesystemRoot)
+                const stackFrames = parseCallerFromStack(stackStr, this.spineFilesystemRoot, this.npmUriForFilepathSync)
                 if (stackFrames.length > 0) {
                     const callerInfo = extractCallerInfo(stackFrames, 3)
                     event.caller = {
@@ -911,7 +913,8 @@ export function CapsuleSpineContract({
     enableCallerStackInference = false,
     spineFilesystemRoot,
     resolve,
-    importCapsule
+    importCapsule,
+    npmUriForFilepath
 }: {
     onMembraneEvent?: (event: any) => void
     freezeCapsule?: (capsule: any) => Promise<any>
@@ -919,12 +922,28 @@ export function CapsuleSpineContract({
     spineFilesystemRoot?: string
     resolve?: (uri: string, parentFilepath: string) => Promise<string>
     importCapsule?: (filepath: string) => Promise<any>
+    npmUriForFilepath?: (filepath: string) => Promise<string | null>
 } = {}) {
 
     let eventIndex = 0
     let currentCallerContext: CallerContext | undefined = undefined
     const instanceRegistry: CapsuleInstanceRegistry = new Map()
 
+    // Sync cache for npmUriForFilepath — async calls populate the cache,
+    // sync reads return cached values (raw filepath fallback on cache miss).
+    const npmUriCache = new Map<string, string | null>()
+    const npmUriForFilepathSync = npmUriForFilepath
+        ? (filepath: string): string | null => {
+            if (npmUriCache.has(filepath)) return npmUriCache.get(filepath)!
+            // Fire async resolution to populate cache for next access
+            npmUriForFilepath(filepath).then(
+                uri => npmUriCache.set(filepath, uri),
+                () => npmUriCache.set(filepath, null)
+            )
+            return null
+        }
+        : undefined
+
     // Re-entrancy guard: suppress event emission while inside an onMembraneEvent callback.
     // This prevents consumers (e.g. JSON.stringify on event.value) from triggering proxy getters
     // that would cause spurious recursive membrane events with wrong caller context and ordering.
@@ -955,6 +974,7 @@ export function CapsuleSpineContract({
                 importCapsule,
                 onMembraneEvent: guardedOnMembraneEvent,
                 enableCallerStackInference,
+                npmUriForFilepathSync,
                 encapsulateOptions,
                 getEventIndex: () => eventIndex,
                 incrementEventIndex: () => eventIndex++,
@@ -975,67 +995,7 @@ export function CapsuleSpineContract({
 CapsuleSpineContract['#'] = '@stream44.studio/encapsulate/spine-contracts/CapsuleSpineContract.v0'
 
 
-
-
-// Cache for synchronous npm URI lookups (directory -> package name or null)
-const npmUriCache = new Map<string, string | null>()
-
-function constructNpmUriSync(absoluteFilepath: string): 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 (npmUriCache.has(currentDir)) {
-            const cachedName = npmUriCache.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 {
-            if (existsSync(packageJsonPath)) {
-                const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'))
-                const packageName = packageJson.name
-                npmUriCache.set(currentDir, packageName || null)
-                if (packageName) {
-                    const relativeFromPackage = relative(currentDir, absoluteFilepath)
-                    return `${packageName}/${relativeFromPackage}`
-                }
-            } else {
-                npmUriCache.set(currentDir, null)
-            }
-        } catch {
-            npmUriCache.set(currentDir, null)
-        }
-
-        const parentDir = dirname(currentDir)
-        if (parentDir === currentDir) break
-        currentDir = parentDir
-    }
-
-    return null
-}
-
-function parseCallerFromStack(stack: string, spineFilesystemRoot?: string): Array<{ function?: string, fileUri?: string, line?: number, column?: number }> {
+function parseCallerFromStack(stack: string, spineFilesystemRoot?: string, npmUriForFilepathSync?: (filepath: string) => string | null): Array<{ function?: string, fileUri?: string, line?: number, column?: number }> {
     const lines = stack.split('\n')
     const result: Array<{ function?: string, fileUri?: string, line?: number, column?: number }> = []
 
@@ -1082,7 +1042,7 @@ function parseCallerFromStack(stack: string, spineFilesystemRoot?: string): Arra
 
             // Convert absolute filepaths to npm URIs
             if (rawFilepath) {
-                const npmUri = constructNpmUriSync(rawFilepath)
+                const npmUri = npmUriForFilepathSync ? npmUriForFilepathSync(rawFilepath) : null
                 if (npmUri) {
                     // Strip file extension from URI for consistency
                     frame.fileUri = npmUri.replace(/\.(ts|tsx|js|jsx)$/, '')

package/src/spine-contracts/CapsuleSpineContract.v0/Static.v0.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,8 @@ 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 })
         }
     }
 
@@ -212,9 +215,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 +341,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 +359,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,
+            })
         }
     }
 
@@ -606,6 +615,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

@@ -1,4 +1,4 @@
-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"
@@ -278,6 +278,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 +388,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 +598,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/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'