openpencil/packages/docs/reference/dom-css-mapping.md

DOM/CSS mapping reference

OpenPencil maps browser-computed DOM/CSS styles into SceneGraph fields through @open-pencil/dom-css. Browser adapters should use native DOM/CSSOM and getComputedStyle() as the source of truth. Headless conversion is an approximation for tests and CLI usage.

Layout

CSS	SceneGraph	Notes
display: flex / inline-flex	layoutMode	flex-direction: row maps to horizontal; column maps to vertical.
justify-content	primaryAxisAlign	Supports start, center, end/flex-end, and space-between.
align-items	counterAxisAlign	Supports start, center, end/flex-end, stretch, and baseline.
align-self	layoutAlignSelf	Supports start, center, end/flex-end, stretch, and baseline.
flex-wrap: wrap	layoutWrap: WRAP	Counter-axis spacing is preserved when gaps are available.
gap, row-gap, column-gap	itemSpacing, counterAxisSpacing	Axis-aware: row and column gaps swap meaning for column flex direction.
padding-*	paddingTop/Right/Bottom/Left	Browser-computed physical values are preferred.
position: absolute/fixed, left, top	layoutPositioning, x, y	Right/bottom constraints are not mapped yet.
overflow: hidden/clip	clipsContent	Other overflow values are ignored.
width, height, min/max sizes	node size constraints	Browser-computed pixel values are preferred.
aspect-ratio	fallback width/height sizing	Used when one axis is available and the other is auto/missing.

Paint, stroke, and effects

CSS	SceneGraph	Notes
background-color	solid fill	Transparent values are ignored.
border-color, border-*-color	stroke color	First available border color is used.
border-width, border-*-width	stroke weight / independent stroke weights	Side-specific widths set independent stroke weights.
border-style: dashed/dotted	dashPattern	Unsupported border styles fall back to solid.
border-radius, border-*-radius	corner radii	Independent corners are preserved when sides differ.
opacity	node opacity	Numeric computed value.
box-shadow	drop shadow	First simple outer shadow only; complex shadow lists require maintained parser or browser-computed support before mapping.
<img src="data:...">	image fill	Data URL images are stored in the graph image map.
<img src="https://...">	preserved source URL metadata	External URL fetching is not performed; the URL is retained for HTML round-trip.
object-fit: contain/cover	image FIT / FILL scale mode	scale-down maps to FIT; other object-fit values are not mapped yet.

Text

CSS	SceneGraph	Notes
color	text fill	Uses core color parsing.
font-family	fontFamily	Uses first family token.
font-size	fontSize	Pixel/rem-ish numeric values.
font-weight	fontWeight	Numeric values.
font-style: italic	italic	Other styles ignored.
line-height	lineHeight	Numeric computed values.
letter-spacing	letterSpacing	Numeric computed values.
text-align	horizontal text alignment	Supports center, right, justified; defaults left.
text-decoration-line	underline / strikethrough	Decoration style/thickness are not mapped yet.
text-transform	textCase	Uppercase, lowercase, and capitalize map to SceneGraph text case.
white-space: nowrap	maxLines = 1	Other white-space values are not mapped yet.
text-shadow	drop shadow effect	Simple shadows only.

Browser-oracle but not mapped yet

These values are collected or covered by browser oracle tests but do not yet have a stable SceneGraph mapping:

• complex gradients
• CSS filters
• multi-shadow lists
• media-query-specific provenance
• pseudo-elements

Headless limitations

The headless runtime uses maintained parsers for HTML (parse5) and stylesheets/inline declarations (@acemir/cssom), but still has limited approximations for selector matching, shorthand expansion, calc(), and simple shadows. Do not expand those with ad hoc parsers; prefer browser getComputedStyle() oracle coverage or maintained parser dependencies for new CSS behavior.