@wix/zero-config-implementation 1.99.0 → 1.100.0

package/package.json

@@ -4,7 +4,7 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "version": "1.99.0",
+  "version": "1.100.0",
   "description": "Core library for extracting component manifests from JS and CSS files",
   "type": "module",
   "main": "dist/index.js",
@@ -106,5 +106,5 @@
       ]
     }
   },
-  "falconPackageHash": "905a961b05476216ee10b85e56b0d50818e5247abe594c0917619c0a"
+  "falconPackageHash": "80ef17ffc1549b6c4d3f51396955cb0517fe8eceb7b20eed65fc7e7d"
 }

package/src/converters/css-longhand-resolver.test.ts

@@ -131,6 +131,41 @@ describe('resolveLonghand', () => {
     expect(resolveLonghand('paddingTop', new Map())).toBeUndefined()
   })
 
+  describe('margin family', () => {
+    it('marginTop falls back through marginBlockStart → marginBlock → margin', () => {
+      expect(resolveLonghand('marginTop', new Map([['marginBlockStart', '1px']]))).toBe('1px')
+      expect(resolveLonghand('marginTop', new Map([['marginBlock', '4px 8px']]))).toBe('4px')
+      expect(resolveLonghand('marginTop', new Map([['margin', '1rem 2rem']]))).toBe('1rem')
+    })
+
+    it('marginBottom falls back through marginBlockEnd → marginBlock → margin', () => {
+      expect(resolveLonghand('marginBottom', new Map([['marginBlockEnd', '2px']]))).toBe('2px')
+      expect(resolveLonghand('marginBottom', new Map([['marginBlock', '4px 8px']]))).toBe('8px')
+      expect(resolveLonghand('marginBottom', new Map([['margin', '1rem 2rem']]))).toBe('1rem')
+    })
+
+    it('marginInlineStart falls back through marginLeft → marginInline → margin', () => {
+      expect(resolveLonghand('marginInlineStart', new Map([['marginLeft', '7px']]))).toBe('7px')
+      expect(resolveLonghand('marginInlineStart', new Map([['marginInline', '12px']]))).toBe('12px')
+      expect(resolveLonghand('marginInlineStart', new Map([['marginInline', '12px 24px']]))).toBe('12px')
+      expect(resolveLonghand('marginInlineStart', new Map([['margin', '1px 2px 3px 4px']]))).toBe('4px')
+    })
+
+    it('marginInlineEnd falls back through marginRight → marginInline → margin', () => {
+      expect(resolveLonghand('marginInlineEnd', new Map([['marginRight', '9px']]))).toBe('9px')
+      expect(resolveLonghand('marginInlineEnd', new Map([['marginInline', '12px 24px']]))).toBe('24px')
+      expect(resolveLonghand('marginInlineEnd', new Map([['margin', '1px 2px 3px 4px']]))).toBe('2px')
+    })
+
+    it('prefers the literal longhand over any fallback', () => {
+      const values = new Map([
+        ['marginTop', '5px'],
+        ['margin', '10px'],
+      ])
+      expect(resolveLonghand('marginTop', values)).toBe('5px')
+    })
+  })
+
   describe('padding family', () => {
     it('paddingTop falls back through paddingBlockStart → paddingBlock → padding', () => {
       expect(resolveLonghand('paddingTop', new Map([['paddingBlockStart', '1px']]))).toBe('1px')

package/src/converters/css-longhand-resolver.ts

@@ -215,6 +215,18 @@ const fromTextDecorationLine: Fallback = (values) => {
   return lineTokens.join(' ')
 }
 
+/**
+ * `flex-flow: <flex-direction> || <flex-wrap>` — order is free and either
+ * part may be omitted. Pick out just the direction keyword for the schema.
+ */
+const FLEX_DIRECTION_KEYWORDS = new Set(['row', 'row-reverse', 'column', 'column-reverse'])
+
+const fromFlexFlowDirection: Fallback = (values) => {
+  const shorthand = values.get('flexFlow')
+  if (shorthand === undefined) return undefined
+  return splitTopLevelTokens(shorthand).find((token) => FLEX_DIRECTION_KEYWORDS.has(token.toLowerCase()))
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Resolution table
 //
@@ -233,6 +245,12 @@ const FALLBACKS: Partial<Record<CssPropertyName, Fallback[]>> = {
   paddingInlineStart: [fromKey('paddingLeft'), fromAxis('paddingInline', 'start'), fromBox('padding', 'left')],
   paddingInlineEnd: [fromKey('paddingRight'), fromAxis('paddingInline', 'end'), fromBox('padding', 'right')],
 
+  // Margin — same block/inline convention as padding above.
+  marginTop: [fromKey('marginBlockStart'), fromAxis('marginBlock', 'start'), fromBox('margin', 'top')],
+  marginBottom: [fromKey('marginBlockEnd'), fromAxis('marginBlock', 'end'), fromBox('margin', 'bottom')],
+  marginInlineStart: [fromKey('marginLeft'), fromAxis('marginInline', 'start'), fromBox('margin', 'left')],
+  marginInlineEnd: [fromKey('marginRight'), fromAxis('marginInline', 'end'), fromBox('margin', 'right')],
+
   // Border radius — schema uses all-logical corner names; physical names map under LTR/horizontal-tb.
   borderStartStartRadius: [fromKey('borderTopLeftRadius'), fromCorner('borderRadius', 'tl')],
   borderStartEndRadius: [fromKey('borderTopRightRadius'), fromCorner('borderRadius', 'tr')],
@@ -255,6 +273,10 @@ const FALLBACKS: Partial<Record<CssPropertyName, Fallback[]>> = {
   // and color in one declaration. Pick out just the line tokens for the schema.
   textDecorationLine: [fromTextDecorationLine],
 
+  // Flex — `flex-flow: column wrap` carries both direction and wrap; pick out
+  // just the direction keyword for the schema.
+  flexDirection: [fromFlexFlowDirection],
+
   // Shorthand targets (e.g. `font`) live in css-shorthand-composer.ts and are
   // merged in here — composer-driven, conceptually the inverse of the rows above.
   ...SHORTHAND_FALLBACKS,

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

@@ -346,6 +346,72 @@ describe('toEditorReactComponent — cssProperties defaultValue', () => {
       defaultValue: 'var(--wst-primary-background-color)',
     })
   })
+
+  it('excludes width/height from the root element (sizing is handled via layout config)', () => {
+    const extractorData = new Map<string, unknown>()
+    extractorData.set('css-matcher', matcherDataFromCss('width: 100px; height: 50px; overflow: hidden;'))
+    extractorData.set('css-properties', {
+      relevant: [
+        CSS_PROPERTIES.CSS_PROPERTY_TYPE.width,
+        CSS_PROPERTIES.CSS_PROPERTY_TYPE.height,
+        CSS_PROPERTIES.CSS_PROPERTY_TYPE.overflow,
+      ],
+    })
+
+    const rootElement: ExtractedElement = {
+      traceId: 'trace-root',
+      name: 'root',
+      tag: 'div',
+      attributes: {},
+      extractorData,
+      children: [],
+    }
+
+    const result = toEditorReactComponent(createComponent(rootElement))
+
+    expect(result.editorElement?.cssProperties?.width).toBeUndefined()
+    expect(result.editorElement?.cssProperties?.height).toBeUndefined()
+    expect(result.editorElement?.cssProperties?.overflow).toEqual({ defaultValue: 'hidden' })
+  })
+
+  it('keeps width/height on inner (non-root) elements', () => {
+    const rootExtractorData = new Map<string, unknown>()
+    rootExtractorData.set('css-matcher', matcherDataFromCss(''))
+    rootExtractorData.set('css-properties', { relevant: [] })
+
+    const childExtractorData = new Map<string, unknown>()
+    childExtractorData.set('css-matcher', matcherDataFromCss('width: 24px; height: 24px;'))
+    childExtractorData.set('css-properties', {
+      relevant: [CSS_PROPERTIES.CSS_PROPERTY_TYPE.width, CSS_PROPERTIES.CSS_PROPERTY_TYPE.height],
+    })
+
+    const childElement: ExtractedElement = {
+      traceId: 'trace-icon',
+      name: 'icon',
+      tag: 'img',
+      attributes: {},
+      extractorData: childExtractorData,
+      children: [],
+    }
+
+    const rootElement: ExtractedElement = {
+      traceId: 'trace-root',
+      name: 'root',
+      tag: 'div',
+      attributes: {},
+      extractorData: rootExtractorData,
+      children: [childElement],
+    }
+
+    const result = toEditorReactComponent(createComponent(rootElement))
+
+    expect(result.editorElement?.elements?.icon?.inlineElement?.cssProperties?.width).toEqual({
+      defaultValue: '24px',
+    })
+    expect(result.editorElement?.elements?.icon?.inlineElement?.cssProperties?.height).toEqual({
+      defaultValue: '24px',
+    })
+  })
 })
 
 describe('toEditorReactComponent selector conversion', () => {

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

@@ -25,7 +25,11 @@ import type {
   ExtractedElement,
   TrackingStores,
 } from '../information-extractors/react'
-import { getDefaultDisplayForTag, resolveDisplayValue } from '../information-extractors/react'
+import {
+  ROOT_DISPLAY_CUSTOM_PROPERTY,
+  getDefaultDisplayForTag,
+  resolveDisplayValue,
+} from '../information-extractors/react'
 import { findPreferredSemanticClass, normalizeClassNames } from '../utils/css-class'
 import { buildActiveItemDisplayGroups, buildActiveItemIndexDisplayFilters } from './active-item-index-builder'
 import { resolveLonghand } from './css-longhand-resolver'
@@ -307,7 +311,7 @@ function buildNearestCommonAncestorCustomProps(
   const nearestCommonAncestorCustomProps = new Map<string, Record<string, CssCustomPropertyItem>>()
 
   for (const varName of varNames) {
-    if (varName === '--display') continue
+    if (varName === ROOT_DISPLAY_CUSTOM_PROPERTY) continue
 
     const registration = registeredByVar.get(varName)
     // Prefer a concrete declared value; fall back to the @property initial-value so a
@@ -563,6 +567,10 @@ function toDisplayEnumValue(cssValue: string): DisplayEnumValue {
   return (CSS_DISPLAY_TO_ENUM[cssValue] ?? cssValue) as DisplayEnumValue
 }
 
+// Root sizing is handled separately via layout config, so `width`/`height`
+// are excluded from the root element's own `cssProperties`.
+const ROOT_EXCLUDED_CSS_PROPERTIES = new Set<string>([CSS_PROPERTY_TYPE.width, CSS_PROPERTY_TYPE.height])
+
 function buildCssProperties(
   element: ExtractedElement | undefined,
   isRootElement: boolean,
@@ -576,6 +584,9 @@ function buildCssProperties(
   }
   const cssPropertyValues = element ? getMatchedPropertyValues(element) : new Map<string, string>()
   for (const propName of decidedProperties) {
+    if (isRootElement && ROOT_EXCLUDED_CSS_PROPERTIES.has(propName)) {
+      continue
+    }
     if (propName === CSS_PROPERTY_TYPE.display && element) {
       if (!isRootElement) {
         result[propName] = buildDisplayProperty(element)

package/src/information-extractors/react/extractors/css-properties.test.ts

@@ -5,6 +5,7 @@ import type { MatchedCssData } from '../../css/types'
 import type { ExtractedElement } from './core/tree-builder'
 import {
   enrichContainerProperties,
+  enrichFlexProperties,
   getCssPropertiesForTag,
   getDefaultDisplayForTag,
   hasContainerLikeDisplay,
@@ -252,6 +253,131 @@ describe('getCssPropertiesForTag', () => {
     expect(relevantProperties).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.paddingTop)
     expect(relevantProperties).not.toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.font)
   })
+
+  it('gives block/replaced elements the full margin family regardless of box/text/media semantics', () => {
+    for (const tag of ['div', 'p', 'img']) {
+      const relevantProperties = getCssPropertiesForTag(tag)
+
+      expect(relevantProperties).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.marginTop)
+      expect(relevantProperties).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.marginBottom)
+      expect(relevantProperties).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.marginInlineStart)
+      expect(relevantProperties).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.marginInlineEnd)
+    }
+  })
+
+  it('gives non-replaced inline elements only the horizontal margins, per CSS margin-on-inline-boxes rules', () => {
+    for (const tag of ['span', 'a', 'em', 'b', 'i']) {
+      const relevantProperties = getCssPropertiesForTag(tag)
+
+      expect(relevantProperties).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.marginInlineStart)
+      expect(relevantProperties).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.marginInlineEnd)
+      expect(relevantProperties).not.toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.marginTop)
+      expect(relevantProperties).not.toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.marginBottom)
+    }
+  })
+
+  it('gives internal table display elements no margin at all, per CSS 2.1 §17.6.1', () => {
+    for (const tag of ['tr', 'thead', 'tbody', 'tfoot', 'col', 'colgroup', 'td', 'th']) {
+      const relevantProperties = getCssPropertiesForTag(tag)
+
+      expect(relevantProperties).not.toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.marginTop)
+      expect(relevantProperties).not.toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.marginBottom)
+      expect(relevantProperties).not.toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.marginInlineStart)
+      expect(relevantProperties).not.toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.marginInlineEnd)
+    }
+  })
+
+  it('gives box-generating elements width, height, overflow and mix-blend-mode', () => {
+    const relevantProperties = getCssPropertiesForTag('div')
+
+    expect(relevantProperties).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.width)
+    expect(relevantProperties).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.height)
+    expect(relevantProperties).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.overflow)
+    expect(relevantProperties).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.mixBlendMode)
+  })
+
+  it('gives media elements sizing, object-fit/position and mix-blend-mode', () => {
+    const relevantProperties = getCssPropertiesForTag('img')
+
+    expect(relevantProperties).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.width)
+    expect(relevantProperties).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.height)
+    expect(relevantProperties).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.overflow)
+    expect(relevantProperties).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.objectFit)
+    expect(relevantProperties).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.objectPosition)
+    expect(relevantProperties).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.mixBlendMode)
+  })
+
+  it('keeps text-only tags without width/height/overflow/object-fit', () => {
+    const relevantProperties = getCssPropertiesForTag('p')
+
+    expect(relevantProperties).not.toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.width)
+    expect(relevantProperties).not.toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.height)
+    expect(relevantProperties).not.toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.objectFit)
+  })
+})
+
+describe('enrichFlexProperties', () => {
+  it('adds flexDirection/justifyContent/alignItems to a flex container', () => {
+    const elements = [createElementWithCssProperties('div', 'display: flex')]
+
+    const [enrichedElement] = enrichFlexProperties(elements)
+    const cssData = enrichedElement.extractorData.get('css-properties') as { relevant: string[] }
+
+    expect(cssData.relevant).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.flexDirection)
+    expect(cssData.relevant).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.justifyContent)
+    expect(cssData.relevant).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.alignItems)
+    expect(cssData.relevant).not.toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.alignSelf)
+  })
+
+  it('does not add flex container properties to a non-flex/grid element', () => {
+    const elements = [createElementWithCssProperties('div', 'display: block')]
+
+    const [enrichedElement] = enrichFlexProperties(elements)
+    const cssData = enrichedElement.extractorData.get('css-properties') as { relevant: string[] }
+
+    expect(cssData.relevant).not.toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.flexDirection)
+    expect(cssData.relevant).not.toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.justifyContent)
+    expect(cssData.relevant).not.toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.alignItems)
+  })
+
+  it('adds alignSelf to direct children of a flex/grid container', () => {
+    const child = createElementWithCssProperties('span', '')
+    const parent: ExtractedElement = {
+      ...createElementWithCssProperties('div', 'display: flex'),
+      children: [child],
+    }
+
+    const [enrichedParent] = enrichFlexProperties([parent])
+    const enrichedChild = enrichedParent.children[0]
+    const childCssData = enrichedChild.extractorData.get('css-properties') as { relevant: string[] }
+
+    expect(childCssData.relevant).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.alignSelf)
+  })
+
+  it('does not add alignSelf to children of a non-flex/grid container', () => {
+    const child = createElementWithCssProperties('span', '')
+    const parent: ExtractedElement = {
+      ...createElementWithCssProperties('div', 'display: block'),
+      children: [child],
+    }
+
+    const [enrichedParent] = enrichFlexProperties([parent])
+    const enrichedChild = enrichedParent.children[0]
+    const childCssData = enrichedChild.extractorData.get('css-properties') as { relevant: string[] }
+
+    expect(childCssData.relevant).not.toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.alignSelf)
+  })
+
+  it('adds flex container properties to a grid container as well', () => {
+    const elements = [createElementWithCssProperties('div', 'display: grid')]
+
+    const [enrichedElement] = enrichFlexProperties(elements)
+    const cssData = enrichedElement.extractorData.get('css-properties') as { relevant: string[] }
+
+    expect(cssData.relevant).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.flexDirection)
+    expect(cssData.relevant).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.justifyContent)
+    expect(cssData.relevant).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.alignItems)
+  })
 })
 
 describe('getDefaultDisplayForTag', () => {
@@ -404,4 +530,14 @@ describe('enrichContainerProperties', () => {
     expect(cssData.relevant).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.font)
     expect(cssData.relevant).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.paddingTop)
   })
+
+  it('adds box properties to span when display is signaled only via the --display root convention, not a literal display declaration', () => {
+    const elements = [createElementWithCssProperties('span', '--display: block')]
+
+    const [enrichedElement] = enrichContainerProperties(elements)
+    const cssData = enrichedElement.extractorData.get('css-properties') as { relevant: string[] }
+
+    expect(cssData.relevant).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.font)
+    expect(cssData.relevant).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.paddingTop)
+  })
 })

package/src/information-extractors/react/extractors/css-properties.ts

@@ -99,6 +99,70 @@ const BOX_CSS_PROPERTIES = [
   CSS_PROPERTY_TYPE.borderEndStartRadius,
   CSS_PROPERTY_TYPE.borderEndEndRadius,
   CSS_PROPERTY_TYPE.boxShadow,
+  CSS_PROPERTY_TYPE.width,
+  CSS_PROPERTY_TYPE.height,
+  CSS_PROPERTY_TYPE.overflow,
+  CSS_PROPERTY_TYPE.mixBlendMode,
+]
+
+/**
+ * Margin applies to most DOM elements regardless of box/text/media
+ * semantics, so it's appended in `getCssPropertiesForTag` rather than gated
+ * to one of the trait-based sets above — except for the display-dependent
+ * carve-outs in `getMarginPropertiesForTag` below.
+ */
+const MARGIN_CSS_PROPERTIES = [
+  CSS_PROPERTY_TYPE.marginTop,
+  CSS_PROPERTY_TYPE.marginBottom,
+  CSS_PROPERTY_TYPE.marginInlineStart,
+  CSS_PROPERTY_TYPE.marginInlineEnd,
+]
+
+const HORIZONTAL_MARGIN_CSS_PROPERTIES = [CSS_PROPERTY_TYPE.marginInlineStart, CSS_PROPERTY_TYPE.marginInlineEnd]
+
+/**
+ * Per CSS 2.1 §17.6.1, margin does not apply to elements with these internal
+ * table display values — the table layout algorithm ignores it entirely.
+ */
+const MARGIN_UNSUPPORTED_DISPLAY_VALUES = new Set([
+  'table-row',
+  'table-row-group',
+  'table-header-group',
+  'table-footer-group',
+  'table-column',
+  'table-column-group',
+  'table-cell',
+])
+
+/**
+ * Margin properties relevant to a tag's default display. Internal table
+ * display values (`tr`, `thead`/`tbody`/`tfoot`, `col`/`colgroup`, `td`/`th`)
+ * don't honor margin at all. Non-replaced inline elements (`span`, `a`, …)
+ * only honor the horizontal (inline) margins — `margin-top`/`margin-bottom`
+ * have no effect on them. Replaced inline elements (`img`, `video`, …) honor
+ * margin on every side, same as a block box.
+ */
+function getMarginPropertiesForTag(tag: string): string[] {
+  const normalizedTag = tag.toLowerCase()
+  const defaultDisplay = getDefaultDisplayForTag(normalizedTag)
+
+  if (MARGIN_UNSUPPORTED_DISPLAY_VALUES.has(defaultDisplay)) {
+    return []
+  }
+  if (defaultDisplay === 'inline' && !MEDIA_TAGS.has(normalizedTag)) {
+    return HORIZONTAL_MARGIN_CSS_PROPERTIES
+  }
+  return MARGIN_CSS_PROPERTIES
+}
+
+/**
+ * Child-layout controls for flex/grid containers, added post-hoc by
+ * `enrichFlexProperties` once the element's resolved `display` is known.
+ */
+const FLEX_CONTAINER_CSS_PROPERTIES = [
+  CSS_PROPERTY_TYPE.flexDirection,
+  CSS_PROPERTY_TYPE.justifyContent,
+  CSS_PROPERTY_TYPE.alignItems,
 ]
 
 /**
@@ -128,6 +192,12 @@ const MEDIA_CSS_PROPERTIES = [
   CSS_PROPERTY_TYPE.borderEndStartRadius,
   CSS_PROPERTY_TYPE.borderEndEndRadius,
   CSS_PROPERTY_TYPE.boxShadow,
+  CSS_PROPERTY_TYPE.width,
+  CSS_PROPERTY_TYPE.height,
+  CSS_PROPERTY_TYPE.overflow,
+  CSS_PROPERTY_TYPE.objectFit,
+  CSS_PROPERTY_TYPE.objectPosition,
+  CSS_PROPERTY_TYPE.mixBlendMode,
 ]
 
 function hasTextSemantics(tag: string, attributes: SemanticAttributes = {}): boolean {
@@ -180,6 +250,7 @@ export function getCssPropertiesForTag(tag: string, attributes: SemanticAttribut
     properties.push(...BOX_CSS_PROPERTIES)
   }
 
+  properties.push(...getMarginPropertiesForTag(tag))
   properties.push(CSS_PROPERTY_TYPE.display)
   return [...new Set(properties)]
 }
@@ -219,6 +290,27 @@ export function addGapProperty(existing: string[]): string[] {
   return [...existing, CSS_PROPERTY_TYPE.gap]
 }
 
+/**
+ * Adds flex/grid container CSS properties to an existing property list without duplicates.
+ */
+export function addFlexContainerProperties(existing: string[]): string[] {
+  const result = [...existing]
+  for (const property of FLEX_CONTAINER_CSS_PROPERTIES) {
+    if (!result.includes(property)) {
+      result.push(property)
+    }
+  }
+  return result
+}
+
+/**
+ * Adds the `alignSelf` CSS property to an existing property list if not already present.
+ */
+export function addAlignSelfProperty(existing: string[]): string[] {
+  if (existing.includes(CSS_PROPERTY_TYPE.alignSelf)) return existing
+  return [...existing, CSS_PROPERTY_TYPE.alignSelf]
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Display Value Resolution
 // ─────────────────────────────────────────────────────────────────────────────
@@ -412,7 +504,7 @@ function hasUnresolvableDisplayVar(matcherData: MatchedCssData): boolean {
   return resolveCssPropertyValue(displayProperty, matcherData.customProperties) === undefined
 }
 
-function hasDisplayDeclaration(matcherData: MatchedCssData): boolean {
+function hasLiteralDisplayDeclaration(matcherData: MatchedCssData): boolean {
   for (const match of matcherData.matches) {
     for (const property of match.properties) {
       if (property.name === 'display') return true
@@ -421,14 +513,30 @@ function hasDisplayDeclaration(matcherData: MatchedCssData): boolean {
   return false
 }
 
+export const ROOT_DISPLAY_CUSTOM_PROPERTY = '--display'
+
+function hasEffectiveDisplayDeclaration(matcherData: MatchedCssData): boolean {
+  return (
+    hasLiteralDisplayDeclaration(matcherData) ||
+    matcherData.customProperties[ROOT_DISPLAY_CUSTOM_PROPERTY] !== undefined
+  )
+}
+
+function resolveEffectiveDisplayValue(matcherData: MatchedCssData): string | undefined {
+  const resolved = resolveDisplayValue(matcherData)
+  if (resolved !== undefined) return resolved
+  if (hasLiteralDisplayDeclaration(matcherData)) return undefined
+  return matcherData.customProperties[ROOT_DISPLAY_CUSTOM_PROPERTY]
+}
+
 export function hasFlexOrGridDisplay(matcherData: MatchedCssData): boolean {
-  const displayValue = resolveDisplayValue(matcherData)
+  const displayValue = resolveEffectiveDisplayValue(matcherData)
   if (displayValue !== undefined) return displayUsesFlexOrGridLayout(displayValue)
   return hasUnresolvableDisplayVar(matcherData)
 }
 
 export function hasContainerLikeDisplay(matcherData: MatchedCssData): boolean {
-  const displayValue = resolveDisplayValue(matcherData)
+  const displayValue = resolveEffectiveDisplayValue(matcherData)
   if (displayValue !== undefined) return displayCreatesContainerBox(displayValue)
   return hasUnresolvableDisplayVar(matcherData)
 }
@@ -456,7 +564,7 @@ function hasDefaultBoxProperties(tag: string, role?: string): boolean {
 }
 
 function hasEffectiveContainerDisplay(tag: string, role?: string, matcherData?: MatchedCssData): boolean {
-  if (matcherData && hasDisplayDeclaration(matcherData)) {
+  if (matcherData && hasEffectiveDisplayDeclaration(matcherData)) {
     return hasContainerLikeDisplay(matcherData)
   }
 
@@ -488,6 +596,40 @@ export function enrichGapProperties(elements: ExtractedElement[]): ExtractedElem
   })
 }
 
+/**
+ * Walks the element tree and adds flex/grid layout controls to relevant CSS
+ * properties: `flexDirection`/`justifyContent`/`alignItems` on elements whose
+ * own display is flex|grid, and `alignSelf` on their direct children (the
+ * property that actually targets flex/grid items per the CSS spec).
+ * Must be called after CSS selector matching (requires css-matcher data).
+ */
+export function enrichFlexProperties(
+  elements: ExtractedElement[],
+  parentIsFlexOrGridContainer = false,
+): ExtractedElement[] {
+  return elements.map((element) => {
+    const matcherData = element.extractorData.get('css-matcher') as MatchedCssData | undefined
+    const isFlexOrGridContainer = matcherData ? hasFlexOrGridDisplay(matcherData) : false
+    const cssData = element.extractorData.get('css-properties') as CssPropertiesData | undefined
+
+    if (cssData) {
+      let relevant = cssData.relevant
+      if (isFlexOrGridContainer) {
+        relevant = addFlexContainerProperties(relevant)
+      }
+      if (parentIsFlexOrGridContainer) {
+        relevant = addAlignSelfProperty(relevant)
+      }
+      element.extractorData.set('css-properties', { relevant })
+    }
+
+    return {
+      ...element,
+      children: enrichFlexProperties(element.children, isFlexOrGridContainer),
+    }
+  })
+}
+
 /**
  * Walks the element tree and adds box properties to selected text tags
  * when CSS overrides `display` or default UA display creates a box.

package/src/information-extractors/react/extractors/index.ts

@@ -28,8 +28,10 @@ export {
   createCssPropertiesExtractor,
   enrichGapProperties,
   enrichContainerProperties,
+  enrichFlexProperties,
   resolveDisplayValue,
   getDefaultDisplayForTag,
+  ROOT_DISPLAY_CUSTOM_PROPERTY,
 } from './css-properties'
 export type { CssPropertiesData } from './css-properties'
 

package/src/information-extractors/react/index.ts

@@ -18,8 +18,10 @@ export {
   createCssPropertiesExtractor,
   enrichGapProperties,
   enrichContainerProperties,
+  enrichFlexProperties,
   resolveDisplayValue,
   getDefaultDisplayForTag,
+  ROOT_DISPLAY_CUSTOM_PROPERTY,
   inferSupportedNativeStates,
 } from './extractors'
 

package/src/manifest-pipeline.ts

@@ -10,6 +10,7 @@ import {
   createCssPropertiesExtractor,
   createPropTrackerExtractor,
   enrichContainerProperties,
+  enrichFlexProperties,
   enrichGapProperties,
   runExtractors,
 } from './information-extractors/react'
@@ -151,9 +152,10 @@ export function processComponent(
       const matchResult = matchCssSelectors(html, extractedElements, css)
       const containerEnrichedElements = enrichContainerProperties(matchResult.elements)
       const gapEnrichedElements = enrichGapProperties(containerEnrichedElements)
+      const flexEnrichedElements = enrichFlexProperties(gapEnrichedElements)
       enhancedInfo = {
         ...enhancedInfo,
-        elements: convertElements(gapEnrichedElements),
+        elements: convertElements(flexEnrichedElements),
       }
       varUsedByTraceId = matchResult.varUsedByTraceId
     } catch (thrownError) {