@wix/zero-config-implementation 1.78.0 → 1.80.0

package/src/information-extractors/css/parse.ts

@@ -128,6 +128,8 @@ function parseAllProperties(
   try {
     const ast = parse(cssString, { parseCustomProperty: true })
 
+    const valueAliases = parseValueAliases(ast)
+
     walk(ast, {
       visit: 'Rule',
       enter(this: WalkContext, rule: Rule) {
@@ -135,7 +137,7 @@ function parseAllProperties(
           const properties: CSSProperty[] = []
           for (const child of rule.block.children) {
             if (child.type !== 'Declaration') continue
-            const extracted = extractProperty(child, varUsagesByProperty)
+            const extracted = extractProperty(child, varUsagesByProperty, valueAliases)
             if (extracted) {
               properties.push(extracted)
             }
@@ -181,13 +183,18 @@ function parseAllProperties(
  * Extracts property name, value, and var() references from a css-tree Declaration node.
  * Also records var() usages in the provided tracking map.
  */
-function extractProperty(declaration: Declaration, varUsagesByProperty: Map<string, Set<string>>): CSSProperty | null {
+function extractProperty(
+  declaration: Declaration,
+  varUsagesByProperty: Map<string, Set<string>>,
+  valueAliases: Map<string, string>,
+): CSSProperty | null {
   try {
     const name = declaration.property
-    const value = generate(declaration.value)
-    if (!name || !value) return null
+    if (!name) return null
 
-    const varRefs = extractVarNames(declaration.value)
+    const varRefs = extractVarNames(declaration.value, valueAliases)
+    const value = resolveVarIdentifiers(declaration.value, valueAliases)
+    if (!value) return null
 
     for (const varName of varRefs) {
       const usageSet = varUsagesByProperty.get(varName) ?? new Set<string>()
@@ -323,11 +330,51 @@ export function resolveCssPropertyValue(
   return resolvedPropertyValue.kind === 'resolved' ? resolvedPropertyValue.value : undefined
 }
 
+/**
+ * Parses @value local declarations (e.g. `@value alias: --real-prop;`) from the
+ * CSS AST and returns a map of alias → real CSS custom property name.
+ * Import-form @value rules (`@value foo from "module"`) are ignored — they rely
+ * on the convention that the alias name matches the custom property name.
+ */
+function parseValueAliases(cssAst: CssNode): Map<string, string> {
+  const aliases = new Map<string, string>()
+  walk(cssAst, {
+    visit: 'Atrule',
+    enter(atruleNode: Atrule) {
+      if (atruleNode.name !== 'value' || atruleNode.block !== null || !atruleNode.prelude) return
+      const preludeText = generate(atruleNode.prelude).trim()
+      const match = preludeText.match(/^([\w-]+)\s*:\s*(--[\w-]+)\s*$/)
+      if (match) aliases.set(match[1], match[2])
+    },
+  })
+  return aliases
+}
+
+/**
+ * Resolves bare var() identifiers to CSS custom property names by walking the AST.
+ * Local @value aliases (e.g. `@value alias: --real-prop`) are substituted with
+ * their real property name; unaliased identifiers get `--` prepended.
+ * Operating on the AST avoids false matches inside CSS string literals (e.g. content: "var(foo)").
+ */
+function resolveVarIdentifiers(valueNode: CssNode, valueAliases: Map<string, string>): string {
+  walk(valueNode, {
+    visit: 'Function',
+    enter(functionNode: FunctionNode) {
+      if (functionNode.name !== 'var') return
+      const firstChild = functionNode.children.first
+      if (firstChild?.type === 'Identifier' && !firstChild.name.startsWith('--')) {
+        firstChild.name = valueAliases.get(firstChild.name) ?? `--${firstChild.name}`
+      }
+    },
+  })
+  return generate(valueNode)
+}
+
 /**
  * Extracts all CSS custom property names referenced via var() by walking
  * the declaration value AST for Function nodes named "var".
  */
-function extractVarNames(valueNode: CssNode): string[] {
+function extractVarNames(valueNode: CssNode, valueAliases: Map<string, string>): string[] {
   const varNames: string[] = []
 
   walk(valueNode, {
@@ -338,7 +385,7 @@ function extractVarNames(valueNode: CssNode): string[] {
       const firstChild = functionNode.children.first
       if (firstChild && firstChild.type === 'Identifier') {
         const identName = firstChild.name
-        varNames.push(identName.startsWith('--') ? identName : `--${identName}`)
+        varNames.push(identName.startsWith('--') ? identName : (valueAliases.get(identName) ?? `--${identName}`))
       }
     },
   })

package/src/information-extractors/css/sass-adapter.test.ts

@@ -0,0 +1,137 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { compileSass } from './sass-adapter'
+
+function writePackageJson(packageDir: string, content: object) {
+  writeFileSync(join(packageDir, 'package.json'), JSON.stringify(content))
+}
+
+function createPackageDir(tempDir: string, packageName: string): string {
+  const packageDir = join(tempDir, 'node_modules', packageName)
+  mkdirSync(packageDir, { recursive: true })
+  return packageDir
+}
+
+describe('compileSass — npm package importer', () => {
+  let tempDir: string
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'sass-adapter-test-'))
+  })
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true })
+  })
+
+  it('resolves a simple string export entry', () => {
+    const packageDir = createPackageDir(tempDir, 'my-pkg')
+    mkdirSync(join(packageDir, 'dist'), { recursive: true })
+    writeFileSync(join(packageDir, 'dist', '_vars.scss'), '$color: red;')
+    writePackageJson(packageDir, { exports: { './vars': './dist/_vars.scss' } })
+
+    const scssFile = join(tempDir, 'test.scss')
+    writeFileSync(scssFile, '@use "my-pkg/vars" as theme; .a { color: theme.$color; }')
+
+    const result = compileSass(scssFile)
+    expect(result.isOk()).toBe(true)
+    expect(result._unsafeUnwrap()).toContain('color: red')
+  })
+
+  it('resolves a conditional object export entry via "sass" key', () => {
+    const packageDir = createPackageDir(tempDir, 'my-pkg')
+    mkdirSync(join(packageDir, 'dist'), { recursive: true })
+    writeFileSync(join(packageDir, 'dist', '_vars.scss'), '$color: blue;')
+    writePackageJson(packageDir, {
+      exports: { './vars': { sass: './dist/_vars.scss', default: './dist/vars.css' } },
+    })
+
+    const scssFile = join(tempDir, 'test.scss')
+    writeFileSync(scssFile, '@use "my-pkg/vars" as theme; .a { color: theme.$color; }')
+
+    const result = compileSass(scssFile)
+    expect(result.isOk()).toBe(true)
+    expect(result._unsafeUnwrap()).toContain('color: blue')
+  })
+
+  it('resolves a conditional object export entry via "default" key when "sass" is absent', () => {
+    const packageDir = createPackageDir(tempDir, 'my-pkg')
+    mkdirSync(join(packageDir, 'dist'), { recursive: true })
+    writeFileSync(join(packageDir, 'dist', '_vars.scss'), '$color: green;')
+    writePackageJson(packageDir, {
+      exports: { './vars': { default: './dist/_vars.scss' } },
+    })
+
+    const scssFile = join(tempDir, 'test.scss')
+    writeFileSync(scssFile, '@use "my-pkg/vars" as theme; .a { color: theme.$color; }')
+
+    const result = compileSass(scssFile)
+    expect(result.isOk()).toBe(true)
+    expect(result._unsafeUnwrap()).toContain('color: green')
+  })
+
+  it('falls back to .scss file extension when exports field has no matching entry', () => {
+    const packageDir = createPackageDir(tempDir, 'my-pkg')
+    writeFileSync(join(packageDir, 'vars.scss'), '$color: orange;')
+    writePackageJson(packageDir, { exports: { '.': './index.js' } })
+
+    const scssFile = join(tempDir, 'test.scss')
+    writeFileSync(scssFile, '@use "my-pkg/vars" as theme; .a { color: theme.$color; }')
+
+    const result = compileSass(scssFile)
+    expect(result.isOk()).toBe(true)
+    expect(result._unsafeUnwrap()).toContain('color: orange')
+  })
+
+  it('resolves a scoped package', () => {
+    const packageDir = createPackageDir(tempDir, '@scope/pkg')
+    mkdirSync(join(packageDir, 'dist'), { recursive: true })
+    writeFileSync(join(packageDir, 'dist', '_theme.scss'), '$color: purple;')
+    writePackageJson(packageDir, { exports: { './theme': './dist/_theme.scss' } })
+
+    const scssFile = join(tempDir, 'test.scss')
+    writeFileSync(scssFile, '@use "@scope/pkg/theme" as theme; .a { color: theme.$color; }')
+
+    const result = compileSass(scssFile)
+    expect(result.isOk()).toBe(true)
+    expect(result._unsafeUnwrap()).toContain('color: purple')
+  })
+
+  it('returns err for an unresolvable package import', () => {
+    const scssFile = join(tempDir, 'test.scss')
+    writeFileSync(scssFile, '@use "nonexistent-pkg/vars";')
+
+    const result = compileSass(scssFile)
+    expect(result.isErr()).toBe(true)
+  })
+
+  it('returns err for a package with invalid JSON in package.json', () => {
+    const packageDir = createPackageDir(tempDir, 'bad-pkg')
+    mkdirSync(join(packageDir, 'dist'), { recursive: true })
+    writeFileSync(join(packageDir, 'package.json'), 'not valid json {{{')
+
+    const scssFile = join(tempDir, 'test.scss')
+    writeFileSync(scssFile, '@use "bad-pkg/vars";')
+
+    const result = compileSass(scssFile)
+    expect(result.isErr()).toBe(true)
+  })
+
+  it('traverses parent directories to find node_modules', () => {
+    const packageDir = createPackageDir(tempDir, 'my-pkg')
+    mkdirSync(join(packageDir, 'dist'), { recursive: true })
+    writeFileSync(join(packageDir, 'dist', '_vars.scss'), '$color: teal;')
+    writePackageJson(packageDir, { exports: { './vars': './dist/_vars.scss' } })
+
+    // SCSS file is in a subdirectory — node_modules is in the parent (tempDir)
+    const subDir = join(tempDir, 'src', 'components')
+    mkdirSync(subDir, { recursive: true })
+    const scssFile = join(subDir, 'test.scss')
+    writeFileSync(scssFile, '@use "my-pkg/vars" as theme; .a { color: theme.$color; }')
+
+    const result = compileSass(scssFile)
+    expect(result.isOk()).toBe(true)
+    expect(result._unsafeUnwrap()).toContain('color: teal')
+  })
+})

package/src/information-extractors/css/sass-adapter.ts

@@ -1,6 +1,7 @@
-import { existsSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { createRequire } from 'node:module'
 import { dirname, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
 import { Result, err } from 'neverthrow'
 
 function collectNodeModulesPaths(filePath: string): string[] {
@@ -16,6 +17,62 @@ function collectNodeModulesPaths(filePath: string): string[] {
   return paths
 }
 
+function resolvePackageExport(packageDir: string, subPath: string): string | null {
+  const packageJsonPath = join(packageDir, 'package.json')
+  if (!existsSync(packageJsonPath)) return null
+  let packageJson: { exports?: Record<string, string | Record<string, string>> }
+  try {
+    packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'))
+  } catch (error) {
+    console.error(`Failed to parse ${packageJsonPath}:`, error)
+    return null
+  }
+  const exportEntry = packageJson.exports?.[subPath]
+  let exportPath: string | undefined
+  if (typeof exportEntry === 'string') {
+    exportPath = exportEntry
+  } else if (typeof exportEntry === 'object' && exportEntry !== null) {
+    exportPath = exportEntry.sass ?? exportEntry.default
+  }
+  if (typeof exportPath === 'string') {
+    const resolvedPath = join(packageDir, exportPath)
+    return existsSync(resolvedPath) ? resolvedPath : null
+  }
+  return null
+}
+
+function createNodePackageImporter(startDir: string) {
+  return {
+    findFileUrl(url: string): URL | null {
+      if (url.startsWith('.') || url.startsWith('/')) return null
+
+      const isScoped = url.startsWith('@')
+      const parts = url.split('/')
+      const packageName = isScoped ? `${parts[0]}/${parts[1]}` : parts[0]
+      const subpathParts = isScoped ? parts.slice(2) : parts.slice(1)
+      const subPath = subpathParts.length > 0 ? `./${subpathParts.join('/')}` : '.'
+
+      let dir = startDir
+      while (true) {
+        const packageDir = join(dir, 'node_modules', packageName)
+        if (existsSync(packageDir)) {
+          const resolvedPath = resolvePackageExport(packageDir, subPath)
+          if (resolvedPath) return pathToFileURL(resolvedPath)
+
+          if (subpathParts.length > 0) {
+            const fallback = join(packageDir, `${subpathParts.join('/')}.scss`)
+            if (existsSync(fallback)) return pathToFileURL(fallback)
+          }
+        }
+        const parent = dirname(dir)
+        if (parent === dir) break
+        dir = parent
+      }
+      return null
+    },
+  }
+}
+
 const require = createRequire(import.meta.url)
 
 export function compileSass(filePath: string): Result<string, Error> {
@@ -34,6 +91,7 @@ export function compileSass(filePath: string): Result<string, Error> {
     () =>
       sass.compile(filePath, {
         loadPaths,
+        importers: [createNodePackageImporter(dirname(filePath))],
       }).css,
     (thrown) => (thrown instanceof Error ? thrown : new Error(String(thrown))),
   )()

package/src/information-extractors/react/extractors/prop-tracker.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
-import { createRefElementMarker } from '../../../ref-elements/path-utils'
-import type { RefElementMatch } from '../../../ref-elements/types'
+import { createRefElementMarker } from '../../../extensions/ref-elements/path-utils'
+import type { RefElementMatch } from '../../../extensions/ref-elements/types'
 import { ExtractorStore } from './core/store'
 import { createPropTrackerExtractor } from './prop-tracker'
 

package/src/information-extractors/react/extractors/prop-tracker.ts

@@ -7,9 +7,9 @@
 
 import type { HTMLAttributes } from 'react'
 import { TRACE_ATTR } from '../../../component-renderer'
-import { readRefElementComponentType } from '../../../ref-elements/component-tag'
-import { parseRefElementMarker } from '../../../ref-elements/path-utils'
-import type { RefElementMatch } from '../../../ref-elements/types'
+import { readRefElementComponentType } from '../../../extensions/ref-elements/component-tag'
+import { parseRefElementMarker } from '../../../extensions/ref-elements/path-utils'
+import type { RefElementMatch } from '../../../extensions/ref-elements/types'
 import { findPreferredSemanticClass, normalizeClassNames } from '../../../utils/css-class'
 import type { PropSpyMeta, TrackingStores } from '../types'
 import { type PropSpyRegistrar, generateMockProps, resetMockCounter } from '../utils/mock-generator'

package/src/information-extractors/react/utils/mock-generator.test.ts

@@ -1,7 +1,7 @@
-import { describe, expect, it } from 'vitest'
-import { createRefElementMarker, parseRefElementMarker } from '../../../ref-elements/path-utils'
+import { beforeEach, describe, expect, it } from 'vitest'
+import { createRefElementMarker, parseRefElementMarker } from '../../../extensions/ref-elements/path-utils'
 import type { ComponentInfo } from '../../ts/types'
-import { generateMockProps, resetMockCounter } from './mock-generator'
+import { generateMockContextValues, generateMockProps, resetMockCounter } from './mock-generator'
 
 describe('generateMockProps', () => {
   it('injects a dedicated ref-element id marker into each eligible elementProps branch', () => {
@@ -129,3 +129,107 @@ describe('generateMockProps', () => {
     expect(parseRefElementMarker(ctaProps.id)).toBe('card.elementProps.cta')
   })
 })
+
+describe('generateMockContextValues', () => {
+  beforeEach(() => {
+    resetMockCounter()
+  })
+
+  it('returns an empty object for an empty schema', () => {
+    expect(generateMockContextValues({ items: {} })).toEqual({})
+  })
+
+  it('maps text to a string', () => {
+    const result = generateMockContextValues({ items: { title: { dataType: 'text' } } })
+    expect(typeof result.title).toBe('string')
+  })
+
+  it('maps number to a number', () => {
+    const result = generateMockContextValues({ items: { count: { dataType: 'number' } } })
+    expect(typeof result.count).toBe('number')
+  })
+
+  it('maps boolean to a boolean', () => {
+    const result = generateMockContextValues({ items: { active: { dataType: 'boolean' } } })
+    expect(typeof result.active).toBe('boolean')
+  })
+
+  it('maps function to a function', () => {
+    const result = generateMockContextValues({ items: { onAction: { dataType: 'function' } } })
+    expect(typeof result.onAction).toBe('function')
+  })
+
+  it('maps richText to an HTML paragraph string', () => {
+    const result = generateMockContextValues({ items: { body: { dataType: 'richText' } } })
+    expect(result.body as string).toMatch(/^<p>/)
+  })
+
+  it('maps image to an image-shaped object', () => {
+    const result = generateMockContextValues({ items: { photo: { dataType: 'image' } } })
+    expect(result.photo).toMatchObject({
+      uri: expect.any(String),
+      url: expect.any(String),
+      width: expect.any(Number),
+      height: expect.any(Number),
+    })
+  })
+
+  it('maps link to a link-shaped object', () => {
+    const result = generateMockContextValues({ items: { destination: { dataType: 'link' } } })
+    expect(result.destination).toMatchObject({ href: expect.any(String), target: expect.any(String) })
+  })
+
+  it('maps data with a nested schema to a nested object', () => {
+    const result = generateMockContextValues({
+      items: {
+        event: {
+          dataType: 'data',
+          data: { items: { name: { dataType: 'text' } } },
+        },
+      },
+    })
+    expect(result.event).toMatchObject({ name: expect.any(String) })
+  })
+
+  it('maps data with an empty schema to a permissive mock that handles Object.keys safely', () => {
+    const result = generateMockContextValues({
+      items: { event: { dataType: 'data', data: { items: {} } } },
+    })
+    expect(() => Object.keys(result.event as object)).not.toThrow()
+    expect(Object.keys(result.event as object)).toHaveLength(0)
+  })
+
+  it('returns a permissive fallback for undeclared context fields so deep access chains do not crash', () => {
+    const result = generateMockContextValues({ items: {} })
+    const undeclared = (result as Record<string, unknown>).anything
+    expect(() => Object.keys(undeclared as object)).not.toThrow()
+    expect(Object.keys(undeclared as object)).toHaveLength(0)
+    const deeplyNested = (undeclared as Record<string, unknown>).deeply
+    expect(() => (deeplyNested as Record<string, unknown>)?.nested).not.toThrow()
+  })
+
+  it('maps arrayItems with a nested schema to a single-element array containing the element object', () => {
+    const result = generateMockContextValues({
+      items: {
+        tickets: {
+          dataType: 'arrayItems',
+          arrayItems: { item: { dataType: 'data', data: { items: { price: { dataType: 'number' } } } } },
+        },
+      },
+    })
+    expect(result.tickets).toHaveLength(1)
+    expect((result.tickets as Record<string, unknown>[])[0]).toMatchObject({ price: expect.any(Number) })
+  })
+
+  it('maps arrayItems with no item schema to an empty array', () => {
+    const result = generateMockContextValues({
+      items: { tickets: { dataType: 'arrayItems', arrayItems: {} } },
+    })
+    expect(result.tickets).toEqual([])
+  })
+
+  it('falls back to a string for unknown dataTypes', () => {
+    const result = generateMockContextValues({ items: { something: { dataType: 'unknown-type' } } })
+    expect(typeof result.something).toBe('string')
+  })
+})

package/src/information-extractors/react/utils/mock-generator.ts

@@ -4,7 +4,11 @@
  */
 
 import { faker } from '@faker-js/faker'
-import { createRefElementMarker, extractElementPropsPathFromPropPath } from '../../../ref-elements/path-utils'
+import type { ContextSchema } from '../../../extensions/context-providers/types'
+import {
+  createRefElementMarker,
+  extractElementPropsPathFromPropPath,
+} from '../../../extensions/ref-elements/path-utils'
 import type { ComponentInfo, DefaultValue, PropInfo, ResolvedType } from '../../ts/types'
 
 export const PRESETS_WRAPPER_CLASS_NAME = 'mock-presets-wrapper-probe'
@@ -484,3 +488,102 @@ function generateMockMenuItems(): unknown[] {
     link: generateMockLink(),
   }))
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Context Schema Mock Generator
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * A recursive Proxy that safely handles any property access, function call, or string coercion.
+ * Used as a fallback for context fields not declared in the schema.
+ */
+function buildPermissiveMock(): unknown {
+  const mock: unknown = new Proxy((() => {}) as (...args: unknown[]) => unknown, {
+    get(_target, prop) {
+      if (prop === 'then') return undefined // prevent thenable detection
+      if (prop === Symbol.toPrimitive) return (_hint: string) => 'mock'
+      if (prop === Symbol.iterator) return function* () {}
+      if (prop === Symbol.asyncIterator) return async function* () {}
+      if (typeof prop === 'symbol') return undefined
+      return mock
+    },
+    ownKeys() {
+      return []
+    },
+    getOwnPropertyDescriptor() {
+      return undefined
+    },
+    apply() {
+      return mock
+    },
+  })
+  return mock
+}
+
+/**
+ * Wraps schema-derived values in a Proxy so that any property NOT declared in the schema
+ * returns a permissive mock instead of undefined, preventing crashes on undeclared field access.
+ */
+function buildSchemaSeededProxy(schemaValues: Record<string, unknown>): Record<string, unknown> {
+  return new Proxy(schemaValues, {
+    get(target, prop) {
+      if (prop === 'then') return undefined // prevent thenable/Promise detection
+      if (typeof prop === 'symbol') return Reflect.get(target, prop)
+      if (Object.prototype.hasOwnProperty.call(target, prop)) return target[prop as string]
+      return buildPermissiveMock()
+    },
+  })
+}
+
+/** Generate mock context values from a context extension schema. */
+export function generateMockContextValues(schema: ContextSchema): Record<string, unknown> {
+  const result: Record<string, unknown> = {}
+  for (const [key, item] of Object.entries(schema.items)) {
+    result[key] = generateValueFromResolvedType(contextDataTypeToResolvedType(item), key, `context.${key}`)
+  }
+  return buildSchemaSeededProxy(result)
+}
+
+function contextDataTypeToResolvedType(item: ContextSchema['items'][string]): ResolvedType {
+  switch (item.dataType) {
+    case 'text':
+      return { kind: 'primitive', value: 'string' }
+    case 'richText':
+      return { kind: 'semantic', value: 'RichText' }
+    case 'image':
+      return { kind: 'semantic', value: 'Image' }
+    case 'video':
+      return { kind: 'semantic', value: 'Video' }
+    case 'vectorArt':
+      return { kind: 'semantic', value: 'VectorArt' }
+    case 'link':
+      return { kind: 'semantic', value: 'Link' }
+    case 'function':
+      return { kind: 'function' }
+    case 'number':
+      return { kind: 'primitive', value: 'number' }
+    case 'boolean':
+      return { kind: 'primitive', value: 'boolean' }
+    case 'arrayItems': {
+      const itemEntry = item.arrayItems?.item
+      if (itemEntry) {
+        const itemValue = generateValueFromResolvedType(
+          contextDataTypeToResolvedType(itemEntry),
+          'item',
+          'context.arrayItem',
+        )
+        return { kind: 'literal', value: [itemValue] }
+      }
+      return { kind: 'literal', value: [] }
+    }
+    case 'data': {
+      const nestedSchema = item.data
+      if (nestedSchema?.items && Object.keys(nestedSchema.items).length > 0) {
+        return { kind: 'literal', value: generateMockContextValues(nestedSchema) }
+      }
+      return { kind: 'literal', value: buildPermissiveMock() }
+    }
+    default:
+      return { kind: 'primitive', value: 'string' }
+  }
+}

package/src/manifest-pipeline.ts

@@ -15,10 +15,13 @@ import {
 } from './information-extractors/react'
 import type { CoupledComponentInfo, CoupledProp, DOMBinding, TrackingStores } from './information-extractors/react'
 
+import {
+  extractElementPropsPathFromPropPath,
+  extractParentElementPropsPath,
+} from './extensions/ref-elements/path-utils'
 import { matchCssSelectors, parseCss } from './information-extractors/css'
 import type { CSSParserAPI } from './information-extractors/css'
 import { compileSass } from './information-extractors/css/sass-adapter'
-import { extractElementPropsPathFromPropPath, extractParentElementPropsPath } from './ref-elements/path-utils'
 
 import type { ComponentType } from 'react'
 

package/src/module-loader.test.ts

@@ -2,9 +2,9 @@ import { createRequire } from 'node:module'
 import path from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { describe, expect, it } from 'vitest'
+import { readRefElementComponentType } from './extensions/ref-elements/component-tag'
 import { loadCjsModule, loadModuleForExtraction } from './module-loader'
 import { readLoaderPortRefStateForTests, readRegisteredRefElementModuleUrlsForTests } from './react-runtime-loader'
-import { readRefElementComponentType } from './ref-elements/component-tag'
 
 const require = createRequire(import.meta.url)
 

package/src/module-loader.ts

@@ -4,8 +4,8 @@ import React from 'react'
 import type { ComponentType } from 'react'
 import ReactDOM from 'react-dom'
 
+import type { RefElementModule } from './extensions/ref-elements/types'
 import { ensureReactRuntimeLoader, loadTaggedCjsModule, prepareRefElementEsmImport } from './react-runtime-loader'
-import type { RefElementModule } from './ref-elements/types'
 
 /**
  * Structured failure from `loadModule` when both ESM import and CJS require fail.

package/src/react-runtime-loader.ts

@@ -2,8 +2,8 @@ import { createHash } from 'node:crypto'
 import { createRequire, register } from 'node:module'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { MessageChannel, MessagePort } from 'node:worker_threads'
-import { buildRefElementTaggerSource, tagRefElementComponentForCleanup } from './ref-elements/component-tag'
-import type { RefElementModule } from './ref-elements/types'
+import { buildRefElementTaggerSource, tagRefElementComponentForCleanup } from './extensions/ref-elements/component-tag'
+import type { RefElementModule } from './extensions/ref-elements/types'
 
 const JSX_INTERCEPTOR_STATE_KEY = 'zero-config:jsx-interceptor'
 const JSX_ORIGINALS_KEY = 'zero-config:jsx-originals'
@@ -68,6 +68,32 @@ interface RefElementRuntimeState {
   originalModuleLoad: InternalModuleApi['_load'] | null
 }
 
+/**
+ * Returns the URL that the ESM loader will assign to a context provider module
+ * when it is imported transitively from a ref-entry-signed statics bundle.
+ *
+ * When runtimeModules is non-empty, the statics bundle entry URL carries a
+ * `?zero-config-ref-entry=HASH` signature, and `shouldPropagateRefElementEntrySignature`
+ * propagates that hash to every non-node_modules file: import. `captureHookContext`
+ * must import the provider at the same signed URL so both paths hit the same Node.js
+ * ESM cache entry (and therefore the same `createContext` return value).
+ *
+ * When runtimeModules is empty, no hash is ever appended, so the plain URL is correct.
+ */
+export function computeSignedContextProviderUrl(resolvedModuleUrl: string, runtimeModules: RefElementModule[]): string {
+  if (runtimeModules.length === 0) {
+    return resolvedModuleUrl
+  }
+
+  const registeredModules = mergeRefElementModules(runtimeModules)
+  const signature = buildRefElementEntrySignature(registeredModules)
+  const signedUrl = new URL(resolvedModuleUrl)
+  if (!signedUrl.searchParams.has(REF_ELEMENT_ENTRY_SIGNATURE_QUERY_PARAM)) {
+    signedUrl.searchParams.set(REF_ELEMENT_ENTRY_SIGNATURE_QUERY_PARAM, signature)
+  }
+  return signedUrl.href
+}
+
 export async function prepareRefElementEsmImport(
   entryPath: string,
   runtimeModules: RefElementModule[] = [],