@wix/zero-config-implementation 1.71.0 → 1.73.0

package/dist/{index-DT1jTZEG.js → index-NbI-_ozJ.js}

@@ -1,4 +1,4 @@
-import { g as x } from "./index-C4cP1dwy.js";
+import { g as x } from "./index-K3lIO4FC.js";
 function h(r, a) {
   for (var i = 0; i < a.length; i++) {
     const o = a[i];

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { ComponentType } from 'react';
+import { CssNode } from 'css-tree';
 import { default as default_2 } from 'typescript';
 import { EditorReactComponent } from '@wix/react-component-schema';
 import { Program } from 'typescript';
@@ -302,7 +303,10 @@ export declare interface CoupledComponentInfo {
     componentName: string;
     props: Record<string, CoupledProp>;
     elements: ExtractedElement[];
-    innerElementProps?: Map<string, Record<string, CoupledProp>>;
+    innerElementProps?: Map<string, {
+        elementPropsPath: string;
+        props: Record<string, CoupledProp>;
+    }>;
     propUsages: TrackingStores['propUsages'];
 }
 
@@ -318,13 +322,12 @@ export declare interface CoupledProp extends PropInfo {
  */
 export declare function createCssPropertiesExtractor(): ReactExtractor;
 
-/**
- * Event emitted for each DOM element created during render.
- */
 export declare interface CreateElementEvent {
-    tag: string;
+    type: unknown;
+    isDomElement: boolean;
+    tag?: string;
     props: Record<string, unknown>;
-    traceId: string;
+    traceId?: string;
     children: unknown[];
     store: ExtractorStore;
 }
@@ -337,13 +340,18 @@ export declare interface CreateElementListener {
  * Creates a prop tracker extractor that:
  * 1. Generates spy-instrumented mock props during beforeRender
  * 2. Detects spy markers in element props during onCreateElement
- * 3. propUsages tracking data to the store namespaced by 'prop-tracker'
+ * 3. Tracks runtime refElement markers from composite components to rendered DOM
+ * 4. Writes prop usage data to the store namespaced by 'prop-tracker'
  */
-export declare function createPropTrackerExtractor(): {
+export declare function createPropTrackerExtractor(options?: CreatePropTrackerExtractorOptions): {
     extractor: ReactExtractor;
     state: PropTrackerExtractorState;
 };
 
+declare interface CreatePropTrackerExtractorOptions {
+    eligiblePaths?: string[];
+}
+
 /**
  * `ErrorClass.subclass()`
  *
@@ -412,6 +420,11 @@ export declare interface CSSParserAPI {
      * @returns DOM-matchable selector string or null
      */
     getDomSelector: (selector: string) => string | null;
+    /**
+     * Gets the selector specificity tuple as [ids, classes/attrs/pseudo-classes, elements/pseudo-elements].
+     * Returns null when the selector was not parsed.
+     */
+    getSelectorSpecificity: (selector: string) => [number, number, number] | null;
     /**
      * Determines the CSS property type for a custom property based on how it is used.
      * If all usages of varName are within the same CSS property, returns that property name.
@@ -437,6 +450,8 @@ export declare interface CssPropertiesData {
 declare interface CSSProperty {
     name: string;
     value: string;
+    /** Parsed css-tree AST for the property's value. */
+    valueAst?: CssNode;
     /** CSS variable names referenced via var() in this property's value */
     varRefs?: string[];
 }

package/dist/index.js

@@ -1,4 +1,4 @@
-import { B as t, D as e, E as o, I as n, N as c, P as l, R as i, a as p, V as E, b as m, c as x, d as f, e as d, f as u, h as C, i as I, j as k, k as y, l as A, m as D, n as P, o as R, p as h, q as B, r as M, s as T, t as b, w } from "./index-C4cP1dwy.js";
+import { B as t, D as e, E as o, I as n, N as c, P as l, R as i, a as p, V as E, b as m, c as x, d as f, e as d, f as u, h as C, i as I, j as k, k as y, l as A, m as D, n as P, o as R, p as h, q as B, r as M, s as T, t as b, w } from "./index-K3lIO4FC.js";
 import "react";
 export {
   t as BaseError,

package/package.json

@@ -4,7 +4,7 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "version": "1.71.0",
+  "version": "1.73.0",
   "description": "Core library for extracting component manifests from JS and CSS files",
   "type": "module",
   "main": "dist/index.js",
@@ -40,7 +40,8 @@
   },
   "dependencies": {
     "@wix/builder-services-wrapper": "^1.42.0",
-    "@wix/react-component-schema": "1.7.0"
+    "@wix/react-component-schema": "1.7.0",
+    "import-meta-resolve": "^4.2.0"
   },
   "devDependencies": {
     "@faker-js/faker": "^10.2.0",
@@ -81,5 +82,5 @@
       ]
     }
   },
-  "falconPackageHash": "d6c8e03493b96fe9947b6b075e997e8ba6e5fea0f79a417f6e26c201"
+  "falconPackageHash": "398dcee4762e04fdaa11211df36bfb4ac7e2ea328d412a68f2e363f8"
 }

package/src/__fixtures__/cjs-ref-element-entry.cjs

@@ -0,0 +1 @@
+module.exports = require('./cjs-ref-element-target.cjs')

package/src/__fixtures__/cjs-ref-element-lazy-entry.cjs

@@ -0,0 +1,3 @@
+exports.loadTargetModule = function loadTargetModule() {
+  return require('./cjs-ref-element-target.cjs')
+}

package/src/__fixtures__/cjs-ref-element-order-entry.cjs

@@ -0,0 +1,8 @@
+globalThis.__zeroConfigRefElementEvaluationOrder = ['entry']
+
+const target = require('./cjs-ref-element-order-target.cjs')
+
+module.exports = {
+  evaluationOrder: globalThis.__zeroConfigRefElementEvaluationOrder,
+  target,
+}

package/src/__fixtures__/cjs-ref-element-order-target.cjs

@@ -0,0 +1,7 @@
+globalThis.__zeroConfigRefElementEvaluationOrder.push('target')
+
+function FixtureRefElementOrderTarget() {
+  return null
+}
+
+module.exports = FixtureRefElementOrderTarget

package/src/__fixtures__/cjs-ref-element-target.cjs

@@ -0,0 +1,5 @@
+function FixtureRefElementTarget() {
+  return null
+}
+
+module.exports = FixtureRefElementTarget

package/src/__fixtures__/esm-ref-element-entry.mjs

@@ -0,0 +1,3 @@
+import RefElementTarget from '@wix/zero-config-ref-element-fixtures/BareRefButton'
+
+export default RefElementTarget

package/src/component-renderer.ts

@@ -10,7 +10,7 @@
  * Four complementary layers ensure interception regardless of how JSX is compiled
  * AND regardless of how many React module instances are loaded in the process:
  *
- * 1. **Node.js ESM loader hook** — registered by `registerJsxLoaderHook()` in
+ * 1. **Node.js ESM loader hook** — registered by `ensureReactRuntimeLoader()` in
  *    `module-loader.ts` before any user bundle is imported. Redirects
  *    `react/jsx-runtime` and `react/jsx-dev-runtime` bare-specifier imports to
  *    an in-memory `data:` URL interceptor that reads mutable state from
@@ -75,7 +75,7 @@ import {
   getOriginals,
   setCreateElementInterceptor,
   setJsxInterceptors,
-} from './jsx-runtime-interceptor'
+} from './react-runtime-interceptor'
 
 export const TRACE_ATTR = 'data-trace-id'
 
@@ -104,18 +104,17 @@ function createInterceptor(
   store: ExtractorStore,
 ): ElementCreator {
   return (type, elementProps, ...rest) => {
-    if (!isDOMTag(type)) {
-      return original(type, elementProps, ...rest)
-    }
-
     const props = (elementProps ?? {}) as Record<string, unknown>
-    const traceId = getNextId()
+    const isDomElement = isDOMTag(type)
+    const traceId = isDomElement ? getNextId() : undefined
 
     // Children location differs: createElement uses rest params, jsx/jsxs uses props.children
     const children = rest.length > 0 ? rest : props.children ? [props.children] : []
 
     const event: CreateElementEvent = {
-      tag: type,
+      type,
+      isDomElement,
+      tag: isDomElement ? type : undefined,
       props: { ...props, children },
       traceId,
       children: children as unknown[],
@@ -124,6 +123,10 @@ function createInterceptor(
 
     listeners.forEach((listener) => listener.onCreateElement(event))
 
+    if (!isDomElement || !traceId) {
+      return original(type, elementProps, ...rest)
+    }
+
     const stampedProps = { ...props, [TRACE_ATTR]: traceId }
     return original(type, stampedProps, ...rest)
   }
@@ -248,7 +251,7 @@ export function renderWithExtractors(
   try {
     // @ts-expect-error Monkey-patch createElement for default-import callers
     React.createElement = interceptedCreateElement
-    // The data: URL react shim (registered by registerJsxLoaderHook) reads this state on every
+    // The data: URL react shim (registered by ensureReactRuntimeLoader) reads this state on every
     // createElement call, covering Rspack/webpack bundles that use `import * as React from 'react'`.
     setCreateElementInterceptor(interceptedCreateElement)
     // Use the interceptor API for jsx-runtime (includes jsxDEV for dev mode)

package/src/converters/to-editor-component.test.ts

@@ -0,0 +1,88 @@
+import { CSS_PROPERTIES } from '@wix/react-component-schema'
+import { describe, expect, it } from 'vitest'
+import { parseCss } from '../information-extractors/css/parse'
+import type { MatchedCssData } from '../information-extractors/css/types'
+import type { ExtractedElement } from '../information-extractors/react'
+import type { ComponentInfoWithCss } from '../manifest-pipeline'
+import { toEditorReactComponent } from './to-editor-component'
+
+function matcherDataFromCss(declarations: string): MatchedCssData {
+  const properties = parseCss(`.test { ${declarations} }`).getPropertiesForSelector('.test')
+  const customProperties: Record<string, string> = {}
+
+  for (const property of properties) {
+    if (property.name.startsWith('--')) {
+      customProperties[property.name] = property.value
+    }
+  }
+
+  return {
+    matches: [
+      {
+        selector: '.test',
+        properties: properties.filter((property) => !property.name.startsWith('--')),
+        specificity: [0, 1, 0],
+      },
+    ],
+    customProperties,
+  }
+}
+
+function createElementWithDisplayMatcher(tag: string, matcherData: MatchedCssData): ExtractedElement {
+  const extractorData = new Map<string, unknown>()
+  extractorData.set('css-matcher', matcherData)
+  extractorData.set('css-properties', { relevant: [CSS_PROPERTIES.CSS_PROPERTY_TYPE.display] })
+
+  return {
+    traceId: 'trace-root',
+    name: 'root',
+    tag,
+    attributes: {},
+    extractorData,
+    children: [],
+  }
+}
+
+function createComponent(rootElement: ExtractedElement): ComponentInfoWithCss {
+  return {
+    componentName: 'DisplayComponent',
+    props: {},
+    elements: [rootElement],
+    propUsages: new Map(),
+    css: [],
+    varUsedByTraceId: new Map(),
+  }
+}
+
+describe('toEditorReactComponent display conversion', () => {
+  it('resolves local display fallback chains before emitting the manifest display value', () => {
+    const rootElement = createElementWithDisplayMatcher(
+      'span',
+      matcherDataFromCss(
+        'display: var(--component-display, inline); --component-display: var(--theme-display, inline-flex)',
+      ),
+    )
+
+    const result = toEditorReactComponent(createComponent(rootElement))
+    expect(result.editorElement).toBeDefined()
+
+    expect(result.editorElement?.cssProperties?.display).toEqual({
+      display: {
+        displayValues: [CSS_PROPERTIES.DISPLAY_VALUE.none, 'inlineFlex'],
+      },
+    })
+  })
+
+  it('keeps using the tag default when no display declaration exists', () => {
+    const rootElement = createElementWithDisplayMatcher('span', matcherDataFromCss(''))
+
+    const result = toEditorReactComponent(createComponent(rootElement))
+    expect(result.editorElement).toBeDefined()
+
+    expect(result.editorElement?.cssProperties?.display).toEqual({
+      display: {
+        displayValues: [CSS_PROPERTIES.DISPLAY_VALUE.none, 'inline'],
+      },
+    })
+  })
+})

package/src/converters/to-editor-component.ts

@@ -20,7 +20,9 @@ import type {
   TrackingStores,
 } from '../information-extractors/react'
 import { getDefaultDisplayForTag, resolveDisplayValue } from '../information-extractors/react'
-import { findPreferredSemanticClass } from '../utils/css-class'
+import { buildRefElementManifestKey } from '../ref-elements/path-utils'
+import type { RefElementMatch } from '../ref-elements/types'
+import { findPreferredSemanticClass, normalizeClassNames } from '../utils/css-class'
 import { resolveLonghand } from './css-longhand-resolver'
 import { type CustomClassTrigger, buildCustomStatesBlock } from './custom-states-builder'
 import { buildDataItem } from './data-item-builder'
@@ -102,12 +104,12 @@ function buildEditorElement(
 
 function getSemanticBlockName(element: ExtractedElement | undefined): string | undefined {
   if (!element?.attributes.class) return undefined
-  return findPreferredSemanticClass(element.attributes.class.split(' '))
+  return findPreferredSemanticClass(normalizeClassNames(element.attributes.class))
 }
 
 function buildSelector(rootElement?: ExtractedElement): string {
   if (rootElement?.attributes.class) {
-    const semanticClass = findPreferredSemanticClass(rootElement.attributes.class.split(' '))
+    const semanticClass = findPreferredSemanticClass(normalizeClassNames(rootElement.attributes.class))
     if (semanticClass) return `.${semanticClass}`
   }
   return rootElement?.tag ?? ''
@@ -141,16 +143,31 @@ function buildElements(
   customClassTriggers: CustomClassTrigger[],
   innerElementProps?: CoupledComponentInfo['innerElementProps'],
   propUsages?: TrackingStores['propUsages'],
+  parentElementPropsPath?: string,
 ): Record<string, ElementItem> {
   const result: Record<string, ElementItem> = {}
 
   for (const element of elements) {
-    const elementData = innerElementProps?.get(element.traceId)
-    const data = elementData && propUsages ? buildData(elementData, propUsages) : undefined
+    const innerEntry = innerElementProps?.get(element.traceId)
+    const refElementMatch = element.extractorData.get('ref-element') as RefElementMatch | undefined
+
+    if (refElementMatch) {
+      result[buildRefElementManifestKey(refElementMatch.elementPropsPath, parentElementPropsPath)] = {
+        elementType: ELEMENTS.ELEMENT_TYPE.refElement,
+        refElement: {
+          selector: refElementMatch.selector,
+          type: refElementMatch.refComponentType,
+        },
+      }
+      continue
+    }
+
+    const semanticClass = getSemanticBlockName(element)
+
+    const data = innerEntry && propUsages ? buildData(innerEntry.props, propUsages) : undefined
     const cssProps = buildCssProperties(element)
     const cssCustomProps = nearestCommonAncestorCustomProps.get(element.traceId) ?? {}
 
-    const semanticClass = getSemanticBlockName(element)
     // Inner-element custom states come from custom-class triggers only; prop
     // triggers (`ElementState<>`) are component-level and attach to the root.
     const states = mergeStates(
@@ -180,6 +197,7 @@ function buildElements(
                 customClassTriggers,
                 innerElementProps,
                 propUsages,
+                innerEntry?.elementPropsPath ?? parentElementPropsPath,
               )
             : undefined,
       },
@@ -418,6 +436,17 @@ function buildCssProperties(element: ExtractedElement | undefined): Record<strin
 function buildDisplayProperty(element: ExtractedElement): CssPropertyItem {
   const matcherData = element.extractorData.get('css-matcher') as MatchedCssData | undefined
   const resolvedFromCss = matcherData ? resolveDisplayValue(matcherData) : undefined
+  const hasExplicitDisplayDeclaration =
+    matcherData?.matches.some((match) => match.properties.some((property) => property.name === 'display')) ?? false
+
+  if (hasExplicitDisplayDeclaration && resolvedFromCss === undefined) {
+    return {
+      display: {
+        displayValues: [DISPLAY_VALUE.none],
+      },
+    }
+  }
+
   const currentValue = resolvedFromCss ?? getDefaultDisplayForTag(element.tag)
   const currentEnumValue = toDisplayEnumValue(currentValue)
 

package/src/index.ts

@@ -1,16 +1,19 @@
 import { WixServicesWrapper } from '@wix/builder-services-wrapper'
 import type { EditorReactComponent } from '@wix/react-component-schema'
-import { Result, type ResultAsync, errAsync, okAsync } from 'neverthrow'
+import { Result, ResultAsync, errAsync, okAsync } from 'neverthrow'
 import React, { type ComponentType } from 'react'
 
 import { toEditorReactComponent } from './converters'
-import { IoError, type NotFoundError, ParseError } from './errors'
+import { BaseError, IoError, type NotFoundError, ParseError } from './errors'
 import type { ExtractionError } from './extraction-types'
 import type { RunExtractorsOptions } from './information-extractors/react'
 import { extractCssImports, extractDefaultComponentInfo } from './information-extractors/ts'
+import type { ComponentInfo } from './information-extractors/ts/types'
 import { processComponent } from './manifest-pipeline'
-import { findComponent, findDefaultComponent, loadModule } from './module-loader'
+import { findComponent, findDefaultComponent, loadModuleForExtraction } from './module-loader'
 import type { LoadModuleFailure } from './module-loader'
+import { buildRefElementContext } from './ref-elements/context'
+import type { RefElementContext } from './ref-elements/types'
 import { compileTsFile } from './ts-compiler'
 
 const defaultWrapper = (Component: ComponentType<unknown>): ComponentType<unknown> => {
@@ -65,7 +68,6 @@ export function extractComponentManifestResult(
     ...options,
     wrapper: options?.wrapper ?? defaultWrapper,
   }
-
   // Step 1: Compile TypeScript (fatal)
   return compileTsFile(componentPath)
     .andThen((program) => {
@@ -89,66 +91,131 @@ export function extractComponentManifestResult(
     .andThen(({ program, componentInfo }) => {
       const { componentName } = componentInfo
 
-      // Step 3: Load the compiled package module (non-fatal) — done after TS extraction
-      // so componentName is known when reporting failures
-      return loadModule(compiledEntryPath)
-        .map((moduleExports) => ({
-          loadComponent: (name: string) => findComponent(moduleExports, name) ?? findDefaultComponent(moduleExports),
-          failure: null as LoadModuleFailure | null,
-        }))
-        .orElse((failure) => okAsync({ loadComponent: () => null as ComponentType<unknown> | null, failure }))
-        .andThen(({ loadComponent, failure }) => {
-          if (failure) {
-            if (failure.esmError) {
+      return ResultAsync.fromPromise(
+        buildRefElementContext(program, componentPath, componentInfo, compiledEntryPath),
+        (thrown) =>
+          new ParseError(
+            `Failed to build the ref-element context for "${componentPath}": ${thrown instanceof Error ? thrown.message : String(thrown)}`,
+            { cause: thrown instanceof Error ? thrown : undefined, props: { phase: 'extract' } },
+          ),
+      ).andThen((refElementContext) =>
+        // Step 3: Load the compiled package module (non-fatal) — done after TS extraction
+        // so componentName is known when reporting failures
+        loadModuleForExtraction(compiledEntryPath, refElementContext.runtimeModules)
+          .map(({ cleanup, moduleExports }) => ({
+            loadComponent: (name: string) => findComponent(moduleExports, name) ?? findDefaultComponent(moduleExports),
+            failure: null as LoadModuleFailure | null,
+            cleanup,
+          }))
+          .orElse((failure) =>
+            okAsync({
+              loadComponent: () => null as ComponentType<unknown> | null,
+              cleanup: async () => {},
+              failure,
+            }),
+          )
+          .andThen(({ cleanup, failure, loadComponent }) => {
+            if (failure) {
+              if (failure.esmError) {
+                report({
+                  componentName,
+                  phase: 'loader',
+                  error: new IoError('ESM import failed', { cause: failure.esmError, props: { phase: 'loader' } }),
+                })
+              }
               report({
                 componentName,
                 phase: 'loader',
-                error: new IoError('ESM import failed', { cause: failure.esmError, props: { phase: 'loader' } }),
+                error: new IoError('CJS require failed', { cause: failure.cjsError, props: { phase: 'loader' } }),
               })
             }
-            report({
-              componentName,
-              phase: 'loader',
-              error: new IoError('CJS require failed', { cause: failure.cjsError, props: { phase: 'loader' } }),
-            })
-          }
 
-          // Step 4: Extract CSS imports (non-fatal)
-          let cssImportPaths: string[] = []
-          const cssResult = Result.fromThrowable(extractCssImports, (thrown) => thrown)(program)
-          if (cssResult.isOk()) {
-            cssImportPaths = cssResult.value
-          } else {
-            const thrown = cssResult.error
-            report({
-              componentName,
-              phase: 'css',
-              error: new ParseError(
-                `Failed to extract CSS imports: ${thrown instanceof Error ? thrown.message : String(thrown)}`,
-                { cause: thrown instanceof Error ? thrown : undefined, props: { phase: 'css' } },
-              ),
-            })
-          }
+            // Step 4: Extract CSS imports (non-fatal)
+            let cssImportPaths: string[] = []
+            const cssResult = Result.fromThrowable(extractCssImports, (thrown) => thrown)(program)
+            if (cssResult.isOk()) {
+              cssImportPaths = cssResult.value
+            } else {
+              const thrown = cssResult.error
+              report({
+                componentName,
+                phase: 'css',
+                error: new ParseError(
+                  `Failed to extract CSS imports: ${thrown instanceof Error ? thrown.message : String(thrown)}`,
+                  { cause: thrown instanceof Error ? thrown : undefined, props: { phase: 'css' } },
+                ),
+              })
+            }
 
-          // Step 5: Process the default-exported component (non-fatal unless render fails after load)
-          const processResult = processComponent(
-            componentInfo,
-            loadComponent,
-            cssImportPaths,
-            !!failure,
-            report,
-            optionsWithDefaults,
-            compiledEntryPath,
-          )
-          if (!processResult.ok) {
-            return errAsync(processResult.error)
-          }
-          const component = toEditorReactComponent(processResult.component)
-          return okAsync({ component, errors })
-        })
+            // Step 5: Process the default-exported component (non-fatal unless render fails after load)
+            return ResultAsync.fromPromise(
+              processComponentWithCleanup(
+                componentInfo,
+                loadComponent,
+                cssImportPaths,
+                !!failure,
+                report,
+                optionsWithDefaults,
+                compiledEntryPath,
+                refElementContext,
+                cleanup,
+                errors,
+              ),
+              normalizeComponentExtractionCleanupFailure,
+            )
+          }),
+      )
     })
 }
 
+function normalizeComponentExtractionCleanupFailure(thrown: unknown): InstanceType<typeof BaseError> {
+  const normalizedError = BaseError.normalize(thrown)
+  if (normalizedError instanceof BaseError) {
+    return normalizedError
+  }
+
+  return new IoError('Unexpected failure during component extraction cleanup', {
+    cause: normalizedError,
+    props: { phase: 'loader' },
+  })
+}
+
+async function processComponentWithCleanup(
+  componentInfo: ComponentInfo,
+  loadComponent: (name: string) => ComponentType<unknown> | null,
+  cssImportPaths: string[],
+  didModuleLoadFail: boolean,
+  report: (error: ExtractionError) => void,
+  options: ExtractComponentManifestOptions,
+  compiledEntryPath: string,
+  refElementContext: RefElementContext,
+  cleanup: () => Promise<void>,
+  errors: ExtractionError[],
+): Promise<ManifestResult> {
+  try {
+    const processResult = processComponent(
+      componentInfo,
+      loadComponent,
+      cssImportPaths,
+      didModuleLoadFail,
+      report,
+      options,
+      compiledEntryPath,
+      refElementContext.eligiblePaths,
+    )
+    if (!processResult.ok) {
+      throw processResult.error
+    }
+
+    return {
+      component: toEditorReactComponent(processResult.component),
+      errors,
+    }
+  } finally {
+    await cleanup()
+  }
+}
+
 export async function extractComponentManifest(
   componentPath: string,
   compiledEntryPath: string,

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

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { parseCss } from './parse'
+import { parseCss, resolveCssPropertyValue } from './parse'
 
 describe('parseCss — getStateClasses', () => {
   it('extracts a custom-class modifier with no paired pseudo', () => {
@@ -120,3 +120,51 @@ describe('parseCss — getStateClasses', () => {
     expect(stateClasses).toEqual([])
   })
 })
+
+describe('resolveCssPropertyValue', () => {
+  it('uses the fallback when a referenced custom property is missing from the property-level map', () => {
+    const [displayProperty] = parseCss(`
+      .title {
+        display: var(--layout-display, inline);
+      }
+    `).getPropertiesForSelector('.title')
+
+    expect(resolveCssPropertyValue(displayProperty, {})).toBe('inline')
+  })
+
+  it('uses the outer fallback when a referenced custom property is known locally but resolves cyclically', () => {
+    const [displayProperty] = parseCss(`
+      .title {
+        display: var(--layout-display, inline);
+      }
+    `).getPropertiesForSelector('.title')
+
+    expect(resolveCssPropertyValue(displayProperty, { '--layout-display': 'var(--layout-display)' })).toBe('inline')
+  })
+
+  it('does not use an inner fallback from a cyclic custom property definition', () => {
+    const [displayProperty] = parseCss(`
+      .title {
+        display: var(--layout-display, inline);
+      }
+    `).getPropertiesForSelector('.title')
+
+    expect(resolveCssPropertyValue(displayProperty, { '--layout-display': 'var(--layout-display, inline-flex)' })).toBe(
+      'inline',
+    )
+  })
+
+  it('resolves a local custom property chain through its nested fallback when the missing variable is local to the chain', () => {
+    const [displayProperty] = parseCss(`
+      .title {
+        display: var(--component-display, inline);
+      }
+    `).getPropertiesForSelector('.title')
+
+    expect(
+      resolveCssPropertyValue(displayProperty, {
+        '--component-display': 'var(--theme-display, inline-flex)',
+      }),
+    ).toBe('inline-flex')
+  })
+})