@stream44.studio/encapsulate 0.4.0-rc.28 → 0.4.0-rc.29

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@stream44.studio/encapsulate",
-    "version": "0.4.0-rc.28",
+    "version": "0.4.0-rc.29",
     "license": "MIT",
     "repository": {
         "type": "git",

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

@@ -174,7 +174,7 @@ export function CapsuleModuleProjector({
                             for (const [key, potentialCapsule] of Object.entries(capsules)) {
                                 if (potentialCapsule === capsule) continue
 
-                                const mappedModulePath = potentialCapsule.cst?.source?.moduleFilepath
+                                const mappedModulePath = potentialCapsule.cst?.source?.moduleUri
 
                                 if (mappedModulePath && (
                                     mappedModulePath === mappingValue ||
@@ -224,7 +224,7 @@ export function CapsuleModuleProjector({
                                         for (const [key, potentialCapsule] of Object.entries(capsules)) {
                                             if (potentialCapsule === capsule) continue
 
-                                            const mappedModulePath = potentialCapsule.cst?.source?.moduleFilepath
+                                            const mappedModulePath = potentialCapsule.cst?.source?.moduleUri
 
                                             if (mappedModulePath && (
                                                 mappedModulePath === mappingValue ||
@@ -515,7 +515,7 @@ export function CapsuleModuleProjector({
             projectingCapsules.add(capsuleId)
         }
 
-        timing?.record(`Projector: Start projection for ${capsule.cst.source.moduleFilepath}`)
+        timing?.record(`Projector: Start projection for ${capsule.cst.source.moduleUri || capsule.cst.source.moduleFilepath}`)
 
         // Only project capsules that have the Capsule struct property
         const spineContract = capsule.cst.spineContracts[spineContractUri]
@@ -571,10 +571,10 @@ export function CapsuleModuleProjector({
                         if (allProjectedFilesExist) {
                             // Restore snapshotValues from cache
                             Object.assign(snapshotValues, merge(snapshotValues, cachedData.snapshotData))
-                            timing?.record(`Projector: Cache HIT for ${capsule.cst.source.moduleFilepath}`)
+                            timing?.record(`Projector: Cache HIT for ${capsule.cst.source.moduleUri || capsule.cst.source.moduleFilepath}`)
                             return true
                         } else {
-                            timing?.record(timing?.chalk?.yellow?.(`Projector: Cache INVALID (projected files missing) for ${capsule.cst.source.moduleFilepath}`))
+                            timing?.record(timing?.chalk?.yellow?.(`Projector: Cache INVALID (projected files missing) for ${capsule.cst.source.moduleUri || capsule.cst.source.moduleFilepath}`))
                         }
                     }
                 }
@@ -588,7 +588,7 @@ export function CapsuleModuleProjector({
 
                         // Check if this capsule has the Capsule struct (meaning it should be projected)
                         if (potentialMappedCapsule.cst?.spineContracts?.[spineContractUri]?.propertyContracts?.['#@stream44.studio/encapsulate/structs/Capsule']) {
-                            // Check if this capsule's moduleFilepath is referenced in any mapping property
+                            // Check if this capsule's moduleUri is referenced in any mapping property
                             const mappedModulePath = potentialMappedCapsule.cst.source.moduleFilepath
 
                             for (const [propContractKey, propContract] of Object.entries(spineContract.propertyContracts)) {
@@ -612,7 +612,7 @@ export function CapsuleModuleProjector({
                         }
                     }
                 }
-                timing?.record(timing?.chalk?.red?.(`Projector: Cache MISS for ${capsule.cst.source.moduleFilepath}`))
+                timing?.record(timing?.chalk?.red?.(`Projector: Cache MISS for ${capsule.cst.source.moduleUri || capsule.cst.source.moduleFilepath}`))
             } catch (error) {
                 // Cache miss or error, proceed with projection
             }
@@ -633,13 +633,13 @@ export function CapsuleModuleProjector({
 
             const cstJson = JSON.stringify(targetCapsule.cst, null, 4)
             const crtJson = JSON.stringify(targetCapsule.crt || {}, null, 4)
-            const moduleFilepath = targetCapsule.cst.source.moduleFilepath
+            const moduleUri = targetCapsule.cst.source.moduleUri
             const importStackLine = targetCapsule.cst.source.importStackLine
 
-            // Replace importMeta: import.meta with moduleFilepath: '...'
+            // Replace importMeta: import.meta with moduleFilepath: '...' (using npm URI)
             expression = expression.replace(
                 /importMeta:\s*import\.meta/g,
-                `moduleFilepath: '${moduleFilepath}'`
+                `moduleFilepath: '${moduleUri}'`
             )
 
             // Replace importStack: makeImportStack() with importStackLine: ..., crt: {...}, cst: {...}
@@ -1662,7 +1662,7 @@ ${mappedDefaultExport}
                 await projectionCacheStore.writeFile(cacheFilename, JSON.stringify(cacheData, null, 2))
             } catch (error) {
                 // Cache write error, continue without failing
-                console.warn(`Warning: Failed to write projection cache for ${capsule.cst.source.moduleFilepath}:`, error)
+                console.warn(`Warning: Failed to write projection cache for ${capsule.cst.source.moduleUri || capsule.cst.source.moduleFilepath}:`, error)
             }
         }
 
@@ -1749,7 +1749,7 @@ capsule['#'] = ${JSON.stringify(capsuleName)}
                         await projectionStore.writeFile(projectedPath, capsuleFileContent)
                     }
                 } catch (error) {
-                    console.warn(`Warning: Failed to write projection cache for capsule ${registryCapsule.cst.source.moduleFilepath}:`, error)
+                    console.warn(`Warning: Failed to write projection cache for capsule ${registryCapsule.cst.source.moduleUri || registryCapsule.cst.source.moduleFilepath}:`, error)
                 }
             }
         }

package/src/encapsulate.ts

@@ -1,7 +1,7 @@
 
 // CACHE_BUST_VERSION: Increment this whenever CST cache must be invalidated due to structural changes
 // This ensures projected capsules are regenerated when the CST format changes
-const CACHE_BUST_VERSION = 21
+const CACHE_BUST_VERSION = 22
 
 type TSpineOptions = {
     spineFilesystemRoot?: string,
@@ -505,21 +505,30 @@ async function encapsulate(definition: TCapsuleDefinition, options: TCapsuleOpti
 
     if (typeof importStackLine !== 'number') throw new Error(`Could not determine importStackLine from options`)
 
-    const capsuleSourceLineRef = `${moduleFilepath}:${importStackLine}`
+    // Temporary filesystem-based ref used only for passing to static analyzer
+    const fsBasedRef = `${moduleFilepath}:${importStackLine}`
 
     spine.spineOptions.timing?.record(`Encapsulate: Start for ${moduleFilepath}`)
 
-    const { csts, crts } = await spine.spineOptions.staticAnalyzer?.parseModule({
+    const parseResult = await spine.spineOptions.staticAnalyzer?.parseModule({
         spineOptions: spine.spineOptions,
         encapsulateOptions: {
             moduleFilepath,
             importStackLine,
-            capsuleSourceLineRef,
+            capsuleSourceLineRef: fsBasedRef,
             capsuleName: options.capsuleName,
             ambientReferences: options.ambientReferences,
             cacheBustVersion: CACHE_BUST_VERSION
         }
-    }) || {
+    })
+
+    // Use moduleUri from static analyzer for npm URI-based capsuleSourceLineRef
+    const moduleUri = parseResult?.moduleUri
+    const capsuleSourceLineRef = moduleUri
+        ? `${moduleUri}:${importStackLine}`
+        : fsBasedRef
+
+    const { csts, crts } = parseResult || {
         csts: options.cst ? { [capsuleSourceLineRef]: options.cst } : undefined,
         crts: options.crt ? { [capsuleSourceLineRef]: options.crt } : undefined
     }

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

@@ -140,11 +140,16 @@ class MembraneContractCapsuleInstanceFactory extends ContractCapsuleInstanceFact
 
         // delegateOptions is set by encapsulate.ts for property contract delegates
         // options can be a function or an object for regular mappings
-        // Always pass { self, constants } - self is populated when depends is specified, empty otherwise
+        // Always pass { self, constants } - self contains full parent self when depends is specified,
+        // otherwise just the Capsule metadata struct (moduleFilepath, capsuleName, etc.)
         const optionsFn = property.definition.options
+        const capsuleStructKey = '#@stream44.studio/encapsulate/structs/Capsule'
+        const minimalSelf = this.self[capsuleStructKey]
+            ? { [capsuleStructKey]: this.self[capsuleStructKey] }
+            : {}
         const mappingOptions = property.definition.delegateOptions
             || (typeof optionsFn === 'function'
-                ? await optionsFn({ self: property.definition.depends ? this.self : {}, constants })
+                ? await optionsFn({ self: property.definition.depends ? this.self : minimalSelf, constants })
                 : optionsFn)
 
         // Check for existing instance in registry - reuse if available (regardless of options)

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

@@ -308,8 +308,8 @@ prop: {
 - **`options`** — forwarded to the mapped capsule. Keys starting with `'#'` target the mapped capsule's own property contracts. Keys without `'#'` are matched against capsule names deeper in the mapping tree (nested capsule-name-targeted options).
 - **`options({ self, constants })`** — when `options` is a function, it receives `{ self, constants }`.
   - `constants` — all `Literal`/`String` values from the mapped capsule's definition.
-  - `self` — the parent capsule's `self` object with resolved sibling mappings. Only populated when `depends` is specified (empty `{}` otherwise).
-- **`depends`** — array of sibling property names that must be resolved before this mapping's `options` function runs. Enables `options({ self })` to access already-resolved siblings (e.g. `self.$auth.realm`) and the Capsule metadata struct (e.g. `self['#@stream44.studio/encapsulate/structs/Capsule'].capsuleName`). Can be declared explicitly or auto-injected by the static analyzer when it detects `self.<name>` references in the options function body.
+  - `self` — always contains the Capsule metadata struct (`self['#@stream44.studio/encapsulate/structs/Capsule']` with `moduleFilepath`, `capsuleName`, etc.). When `depends` is specified, `self` also contains the full parent capsule's resolved sibling mappings.
+- **`depends`** — array of sibling property names that must be resolved before this mapping's `options` function runs. Enables `options({ self })` to access already-resolved siblings (e.g. `self.$auth.realm`). Can be declared explicitly or auto-injected by the static analyzer when it detects `self.<name>` references in the options function body.
 - **Instance reuse** — named capsules are registered in an instance registry. If a capsule with the same name is mapped multiple times without options, the existing instance is reused via a deferred proxy.
 
 Mapped capsules are accessible via `this.<prop>` (unwrapped API) and `api.<prop>` (raw instance with `.api`).

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

@@ -129,8 +129,9 @@ export class ContractCapsuleInstanceFactory {
             if (!this.spineFilesystemRoot) throw new Error(`'spineFilesystemRoot' not set!`)
             if (!this.importCapsule) throw new Error(`'importCapsule' not set!`)
 
-            // Use encapsulateOptions.moduleFilepath (always available) instead of cst.source.moduleFilepath
-            const moduleFilepath = this.capsule.encapsulateOptions?.moduleFilepath || this.capsule.cst?.source?.moduleFilepath
+            // 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
             if (!moduleFilepath) throw new Error(`'moduleFilepath' not available on capsule!`)
 
             const parentPath = join(this.spineFilesystemRoot, moduleFilepath)
@@ -197,11 +198,16 @@ export class ContractCapsuleInstanceFactory {
 
         // delegateOptions is set by encapsulate.ts for property contract delegates
         // options can be a function or an object for regular mappings
-        // Always pass { self, constants } - self is populated when depends is specified, empty otherwise
+        // Always pass { self, constants } - self contains full parent self when depends is specified,
+        // otherwise just the Capsule metadata struct (moduleFilepath, capsuleName, etc.)
         const optionsFn = property.definition.options
+        const capsuleStructKey = '#@stream44.studio/encapsulate/structs/Capsule'
+        const minimalSelf = this.self[capsuleStructKey]
+            ? { [capsuleStructKey]: this.self[capsuleStructKey] }
+            : {}
         const mappingOptions = property.definition.delegateOptions
             || (typeof optionsFn === 'function'
-                ? await optionsFn({ self: property.definition.depends ? this.self : {}, constants })
+                ? await optionsFn({ self: property.definition.depends ? this.self : minimalSelf, constants })
                 : optionsFn)
 
         // Check for existing instance in registry - reuse if available when no options

package/src/static-analyzer.v0.ts

@@ -244,25 +244,13 @@ export function StaticAnalyzer({
 
             const moduleFilepath = join(spineOptions.spineFilesystemRoot, encapsulateOptions.moduleFilepath)
 
-            // Determine the cache file path based on whether the module is external or internal
-            let cacheFilePath: string
-            const isExternal = encapsulateOptions.moduleFilepath.startsWith('../')
-            const hasNodeModules = encapsulateOptions.moduleFilepath.includes('node_modules/')
-
-            if (isExternal || hasNodeModules) {
-                // External module or node_modules path - construct npm URI
-                const npmUri = await constructNpmUri(moduleFilepath, spineOptions.spineFilesystemRoot)
-                if (npmUri) {
-                    // Prefix with o/npmjs.com/node_modules/ for external modules
-                    cacheFilePath = `o/npmjs.com/node_modules/${npmUri}`
-                } else {
-                    // Fallback to normalized path if npm URI construction fails
-                    cacheFilePath = normalize(encapsulateOptions.moduleFilepath).replace(/^\.\.\//, '').replace(/\.\.\//g, '')
-                }
-            } else {
-                // Internal module - use relative path as-is
-                cacheFilePath = encapsulateOptions.moduleFilepath
-            }
+            // Construct npm URI for the module upfront — used for cache paths and CST keys
+            const rawModuleUri: string = await constructNpmUri(moduleFilepath, spineOptions.spineFilesystemRoot) || encapsulateOptions.moduleFilepath
+            // Strip file extension from URI
+            const moduleUriWithoutExt = rawModuleUri.replace(/\.(ts|tsx|js|jsx)$/, '')
+
+            // Cache file path always uses npm URI (never filesystem-relative paths)
+            const cacheFilePath = moduleUriWithoutExt
 
             const capsuleSourceLineRef = `${cacheFilePath}:${encapsulateOptions.importStackLine}`
 
@@ -297,7 +285,8 @@ export function StaticAnalyzer({
                                 timing?.record(`StaticAnalyzer: Cache HIT for ${encapsulateOptions.moduleFilepath}`)
                                 return {
                                     csts: cachedCsts,
-                                    crts: JSON.parse(crtsContent)
+                                    crts: JSON.parse(crtsContent),
+                                    moduleUri: moduleUriWithoutExt
                                 }
                             }
                         }
@@ -369,24 +358,12 @@ export function StaticAnalyzer({
                         continue
                     }
 
-                    const capsuleSourceLineRef = `${encapsulateOptions.moduleFilepath}:${encapsulateOptions.importStackLine}`
-                    const capsuleSourceNameRef = encapsulateOptions.capsuleName && `${encapsulateOptions.moduleFilepath}:${encapsulateOptions.capsuleName}`
+                    // Use npm URI for all CST references (never filesystem-relative paths)
+                    const capsuleSourceLineRef = `${moduleUriWithoutExt}:${encapsulateOptions.importStackLine}`
+                    const capsuleSourceNameRef = encapsulateOptions.capsuleName && `${moduleUriWithoutExt}:${encapsulateOptions.capsuleName}`
                     const capsuleSourceNameRefHash = capsuleSourceNameRef && createHash('sha256').update(capsuleSourceNameRef).digest('hex')
 
-                    // Construct npm URI for the module - try for all modules
-                    let moduleUri: string | null = await constructNpmUri(moduleFilepath, spineOptions.spineFilesystemRoot)
-
-                    // If npm URI construction failed, fall back to moduleFilepath
-                    if (!moduleUri) {
-                        moduleUri = encapsulateOptions.moduleFilepath
-                    }
-
-                    // Strip file extension from URI
-                    const moduleUriWithoutExt = moduleUri.replace(/\.(ts|tsx|js|jsx)$/, '')
-                    const capsuleSourceUriLineRef = `${moduleUriWithoutExt}:${encapsulateOptions.importStackLine}`
-
-                    // Store moduleUri without extension
-                    moduleUri = moduleUriWithoutExt
+                    const capsuleSourceUriLineRef = capsuleSourceLineRef
 
                     // Extract the capsule expression text from the source
                     const capsuleExpression = call.getText(sourceFile)
@@ -407,7 +384,7 @@ export function StaticAnalyzer({
                         capsuleSourceUriLineRef,
                         source: {
                             moduleFilepath: encapsulateOptions.moduleFilepath,
-                            moduleUri,
+                            moduleUri: moduleUriWithoutExt,
                             capsuleName: encapsulateOptions.capsuleName,
                             declarationLine,
                             importStackLine: encapsulateOptions.importStackLine,
@@ -760,6 +737,7 @@ export function StaticAnalyzer({
             return {
                 csts,
                 crts,
+                moduleUri: moduleUriWithoutExt
             }
         }
     }