@wix/origami-transforms 0.1.28 → 0.1.30

package/src/cssPlugins/fonts.js

@@ -49,8 +49,12 @@ const fontIdsOf = declaration => {
     return family.split(',').map(name => name.trim().replace(/^(['"])(.*)\1$/, '$2').toLowerCase())
 }
 
-/** @type {import('../transform/types.js').CssTransformPlugin} */
+const checks = /** @type {const} */ ([])
+/** @typedef {typeof checks[number]} Check */
+
+/** @type {import('../transform/types.js').CssTransformPlugin<Check>} */
 export const fontsPlugin = {
+    checks,
     name: 'fonts',
     // Reads the declarations as authored, before spx rewrites the sizes the family follows.
     order: 5,

package/src/cssPlugins/index.js

@@ -26,10 +26,11 @@ import { presetsPlugin } from './presets.js'
 import { shapeDividersPlugin } from './shapeDividers.js'
 import { layoutPlugin } from './layout/index.js'
 import { spxPlugin } from './spx/index.js'
+import { spxThemeVariablesPlugin } from './spxThemeVariables/index.js'
 import { stackChildrenPlugin } from './stackChildren.js'
 import { wixVectorUrlsPlugin } from './wixVectorUrls.js'
 
-/** @type {readonly import('../transform/types.js').CssTransformPlugin[]} */
+/** @type {readonly import('../transform/types.js').CssTransformPlugin<string>[]} */
 export const cssPlugins = Object.freeze([
     customMediaPlugin,
     fontsPlugin,
@@ -39,6 +40,7 @@ export const cssPlugins = Object.freeze([
     presetsPlugin,
     componentPositionPlugin,
     layoutPlugin,
+    spxThemeVariablesPlugin,
     spxPlugin,
     shapeDividersPlugin,
     wixVectorUrlsPlugin,

package/src/cssPlugins/layout/index.js

@@ -1,8 +1,15 @@
 import { compileContainers } from './compiler.js'
 import { parseTargets } from './parser.js'
 
-/** @type {import('../../transform/types.js').CssTransformPlugin} */
+export const checks = /** @type {const} */ (['unknown_target', 'target_requires_component_id', 'invalid_target_envelope', 'target_not_site_layout', 'duplicate_target', 'target_requires_declarations', 'duplicate_target_property', 'property_wrong_target', 'content_position_not_relative', 'unsupported_overflow', 'unsupported_content_alignment', 'inconsistent_container_display', 'duplicate_root_property', 'property_requires_target'])
+/** @typedef {typeof checks[number]} Check */
+
+/** @template {Error} E @param {Check} check @param {E} error */
+export const fail = (check, error) => Object.assign(error, { check })
+
+/** @type {import('../../transform/types.js').CssTransformPlugin<Check>} */
 export const layoutPlugin = {
+    checks,
     name: 'layout',
     order: 15,
     validate: (root, context) => {

package/src/cssPlugins/layout/parser.js

@@ -1,3 +1,4 @@
+import { fail } from './index.js'
 import { basename } from 'node:path'
 import { isValidContainerId } from '@wix/origami-system-components/layout-contract'
 import { relativeToSite } from '../../transform/relativeToSite.js'
@@ -20,7 +21,7 @@ export const parseTargets = (root, context) => {
     const owners = new Map()
     root.walkAtRules('origami-target', target => {
         const name = target.params.trim()
-        if (!Object.hasOwn(targets, name)) throw target.error(`Unknown @origami-target ${name}`)
+        if (!Object.hasOwn(targets, name)) throw fail('unknown_target', target.error(`Unknown @origami-target ${name}`))
         const owner = target.parent
         // DM writes component rules as .compId; #compId is still accepted.
         if (
@@ -28,34 +29,34 @@ export const parseTargets = (root, context) => {
             !['.', '#'].includes(owner.selector[0]) ||
             !isValidContainerId(owner.selector.slice(1))
         ) {
-            throw target.error('@origami-target requires a single component ID rule')
+            throw fail('target_requires_component_id', target.error('@origami-target requires a single component ID rule'))
         }
         for (let ancestor = owner.parent; ancestor && ancestor.type !== 'root'; ancestor = ancestor.parent) {
             if (
                 ancestor.type !== 'atrule' ||
                 !['scope', 'media', 'layer', 'supports', 'container'].includes(ancestor.name)
             ) {
-                throw target.error('@origami-target is only allowed inside layout rule envelopes')
+                throw fail('invalid_target_envelope', target.error('@origami-target is only allowed inside layout rule envelopes'))
             }
         }
         if (!isLayoutSource(target, context))
-            throw target.error('@origami-target must originate in site-owned layout.css')
+            throw fail('target_not_site_layout', target.error('@origami-target must originate in site-owned layout.css'))
         const siblings = owners.get(owner) ?? []
-        if (siblings.some(sibling => sibling.params.trim() === name)) throw target.error(`Duplicate target ${name}`)
+        if (siblings.some(sibling => sibling.params.trim() === name)) throw fail('duplicate_target', target.error(`Duplicate target ${name}`))
         const seen = new Set()
         for (const node of target.nodes ?? []) {
             if (node.type === 'comment') continue
-            if (node.type !== 'decl') throw node.error('Target bodies must contain declarations only')
-            if (seen.has(node.prop)) throw node.error(`Duplicate target property ${node.prop}`)
+            if (node.type !== 'decl') throw fail('target_requires_declarations', node.error('Target bodies must contain declarations only'))
+            if (seen.has(node.prop)) throw fail('duplicate_target_property', node.error(`Duplicate target property ${node.prop}`))
             seen.add(node.prop)
-            if (!targets[name].has(node.prop)) throw node.error(`${node.prop} does not belong to ${name}`)
+            if (!targets[name].has(node.prop)) throw fail('property_wrong_target', node.error(`${node.prop} does not belong to ${name}`))
             if (node.prop === 'position' && node.value !== 'relative')
-                throw node.error('Content position must be relative')
+                throw fail('content_position_not_relative', node.error('Content position must be relative'))
             if (name === OVERFLOW && !['auto', 'scroll', 'hidden', 'visible', 'clip'].includes(node.value)) {
-                throw node.error(`Unsupported overflow value ${node.value}`)
+                throw fail('unsupported_overflow', node.error(`Unsupported overflow value ${node.value}`))
             }
             if (node.prop === '--content-max-width-align' && !['left', 'center', 'right'].includes(node.value)) {
-                throw node.error(`Unsupported content alignment ${node.value}`)
+                throw fail('unsupported_content_alignment', node.error(`Unsupported content alignment ${node.value}`))
             }
             if (node.prop === 'display') {
                 const type = owner.nodes.find(item => item.type === 'decl' && item.prop === '--container-layout-type')
@@ -64,7 +65,7 @@ export const parseTargets = (root, context) => {
                     (type?.type === 'decl' &&
                         (!Object.hasOwn(displays, type.value) || displays[type.value] !== node.value))
                 ) {
-                    throw node.error('Container type and content display are inconsistent')
+                    throw fail('inconsistent_container_display', node.error('Container type and content display are inconsistent'))
                 }
             }
         }
@@ -75,10 +76,10 @@ export const parseTargets = (root, context) => {
         const seen = new Set()
         for (const node of owner.nodes) {
             if (node.type !== 'decl') continue
-            if (seen.has(node.prop)) throw node.error(`Duplicate root property ${node.prop}`)
+            if (seen.has(node.prop)) throw fail('duplicate_root_property', node.error(`Duplicate root property ${node.prop}`))
             seen.add(node.prop)
             if ((targets[CONTENT].has(node.prop) && node.prop !== 'position') || targets[OVERFLOW].has(node.prop)) {
-                throw node.error(`${node.prop} belongs inside @origami-target`)
+                throw fail('property_requires_target', node.error(`${node.prop} belongs inside @origami-target`))
             }
         }
     }

package/src/cssPlugins/mixins.js

@@ -7,8 +7,15 @@ const MAX_CLONED_BYTES = 10 * 1024 * 1024
 /** @param {import('postcss').AtRule} atRule */
 const mixinName = atRule => atRule.params.trim().replace(/\(\)$/, '')
 
-/** @type {import('../transform/types.js').CssTransformPlugin} */
+export const checks = /** @type {const} */ (['missing_mixin', 'cyclic_apply', 'expansion_depth_exceeded', 'cloned_node_budget_exceeded', 'cloned_css_budget_exceeded'])
+/** @typedef {typeof checks[number]} Check */
+
+/** @template {Error} E @param {Check} check @param {E} error */
+export const fail = (check, error) => Object.assign(error, { check })
+
+/** @type {import('../transform/types.js').CssTransformPlugin<Check>} */
 export const mixinsPlugin = {
+    checks,
     name: 'mixins',
     order: 10,
     transform(root) {
@@ -30,16 +37,16 @@ export const mixinsPlugin = {
             container.walkAtRules('apply', atRule => {
                 const name = mixinName(atRule)
                 const body = bodies.get(name)
-                if (!body) throw new Error(`@apply ${atRule.params} has no @mixin definition`)
-                if (stack.includes(name)) throw new Error(`Cyclic @apply: ${[...stack, name].join(' -> ')}`)
+                if (!body) throw fail('missing_mixin', new Error(`@apply ${atRule.params} has no @mixin definition`))
+                if (stack.includes(name)) throw fail('cyclic_apply', new Error(`Cyclic @apply: ${[...stack, name].join(' -> ')}`))
                 if (stack.length >= MAX_EXPANSION_DEPTH) {
-                    throw new Error(`@apply ${name} exceeds maximum expansion depth (${MAX_EXPANSION_DEPTH})`)
+                    throw fail('expansion_depth_exceeded', new Error(`@apply ${name} exceeds maximum expansion depth (${MAX_EXPANSION_DEPTH})`))
                 }
                 const pending = [...body]
                 while (pending.length) {
                     const node = pending.pop()
                     if (++clonedNodes > MAX_CLONED_NODES) {
-                        throw new Error(`@apply ${name} exceeds stylesheet cloned-node budget (${MAX_CLONED_NODES})`)
+                        throw fail('cloned_node_budget_exceeded', new Error(`@apply ${name} exceeds stylesheet cloned-node budget (${MAX_CLONED_NODES})`))
                     }
                     if (node && 'nodes' in node && node.nodes) {
                         for (const child of node.nodes) pending.push(child)
@@ -48,7 +55,7 @@ export const mixinsPlugin = {
                 for (const node of body) {
                     clonedBytes += Buffer.byteLength((node.raws.before ?? '') + node.toString(), 'utf8')
                     if (clonedBytes > MAX_CLONED_BYTES) {
-                        throw new Error(`@apply ${name} exceeds stylesheet cloned-CSS byte budget (${MAX_CLONED_BYTES})`)
+                        throw fail('cloned_css_budget_exceeded', new Error(`@apply ${name} exceeds stylesheet cloned-CSS byte budget (${MAX_CLONED_BYTES})`))
                     }
                 }
                 // PostCSS does not revisit nodes inserted in place of the current at-rule.

package/src/cssPlugins/presets.js

@@ -23,8 +23,12 @@ const target = (selector, key) => {
     return selector === first ? `.${id}${WRAPPER}` : null
 }
 
-/** @type {import('../transform/types.js').CssTransformPlugin} */
+const checks = /** @type {const} */ ([])
+/** @typedef {typeof checks[number]} Check */
+
+/** @type {import('../transform/types.js').CssTransformPlugin<Check>} */
 export const presetsPlugin = {
+    checks,
     name: 'presets',
     order: 13,
     transform(root, context) {

package/src/cssPlugins/shapeDividers.js

@@ -101,8 +101,12 @@ const layerDeclarations = (compId, vars) => {
     }
 }
 
-/** @type {import('../transform/types.js').CssTransformPlugin} */
+const checks = /** @type {const} */ ([])
+/** @typedef {typeof checks[number]} Check */
+
+/** @type {import('../transform/types.js').CssTransformPlugin<Check>} */
 export const shapeDividersPlugin = {
+    checks,
     name: 'shape-dividers',
     // Last, with wix-vector-urls: it only adds rules, which no other plugin needs to see, and it reads only `--height` as
     // `var(--height)`, so spx converts that var's `--spx()` where it is declared.

package/src/cssPlugins/spx/README.md

@@ -64,17 +64,26 @@ When settings are absent, expressions fall back to reference width 1280, scale m
 viewport width 100vw, scrollbar width 0px, stoppers 0px / 99999px and no cap. Nested components inherit settings unless
 they override them. As with any CSS custom property, an authored variable containing an
 SPX expression resolves where the variable is declared; inheriting the variable does not
-re-evaluate it using a child's settings.
+re-evaluate it using a child's settings. So `../spxThemeVariables/` copies the SPX-dependent theme
+variables onto capped containers.
+
+## Theme calls
+
+`../spxThemeVariables/` rewrites each theme `--spx(N)` as `--theme-spx(N, W)`, W being the theme's
+reference width; authors never write it. It compiles like `--spx(N)` but divides by the literal W
+instead of `var(--spx-ref-width, 1280)`, so a copied theme value keeps its theme size while still
+following the section's cap and scaling factor. N must be a literal number and W a positive one.
 
 ## Files and boundaries
 
 - `index.js` removes the SPX function definition and visits declarations.
 - `cascade.js` translates resolver settings and generates browser-evaluated expressions.
-- `calls.js` parses literal numeric SPX calls and rejects unsupported arguments.
+- `calls.js` parses literal numeric `--spx()` and `--theme-spx()` calls and rejects unsupported arguments.
 
 Reference widths must be positive numbers and resolver modes must be `scale` or `fixed`.
 Stoppers and `--content-max-width` are not validated.
 
 `test/spx.browser.mjs` checks computed styles for the button example, nested overrides,
-settings in separate stylesheets, cascade priority, fixed fractions, signs, zero, stoppers and cap.
+settings in separate stylesheets, cascade priority, fixed fractions, signs, zero, stoppers, cap
+and theme copies on capped sections.
 Run it together with the container browser checks using the package's `test:browser` script.

package/src/cssPlugins/spx/calls.js

@@ -1,4 +1,8 @@
+import { fail } from './index.js'
 const CALL = /--spx\(\s*(-?(?:\d+\.?\d*|\.\d+))\s*\)/g
+const THEME_CALL = /--theme-spx\(\s*(-?(?:\d+\.?\d*|\.\d+))\s*,\s*(\d+\.?\d*|\.\d+)\s*\)/g
+
+export const THEME_SPX = '--theme-spx('
 
 /** Replace literal SPX calls, reporting unsupported arguments at their declaration.
  * @param {import('postcss').Declaration} declaration
@@ -8,5 +12,28 @@ const CALL = /--spx\(\s*(-?(?:\d+\.?\d*|\.\d+))\s*\)/g
 export const lowerCalls = (declaration, resolve, invalidCall) => {
     if (!declaration.value.includes('--spx(')) return
     declaration.value = declaration.value.replace(CALL, (_, literal) => resolve(Number(literal)))
-    if (declaration.value.includes('--spx(')) throw invalidCall()
+    if (declaration.value.includes('--spx(')) throw fail('non_literal_spx_argument', invalidCall())
+}
+
+/**
+ * @param {import('postcss').Declaration} declaration
+ * @param {(value: number, themeRefWidth: number) => string} resolve
+ * @param {() => Error} invalidCall
+ */
+export const lowerThemeCalls = (declaration, resolve, invalidCall) => {
+    if (!declaration.value.includes(THEME_SPX)) return
+    declaration.value = declaration.value.replace(THEME_CALL, (call, literal, themeRefWidthLiteral) => {
+        const themeRefWidth = Number(themeRefWidthLiteral)
+        if (themeRefWidth <= 0) return call
+        const number = Number(literal)
+        return resolve(number, themeRefWidth)
+    })
+    if (declaration.value.includes(THEME_SPX)) throw invalidCall()
 }
+
+/**
+ * @param {string} value
+ * @param {number} themeRefWidth
+ */
+export const toThemeCalls = (value, themeRefWidth) =>
+    value.replace(CALL, (_, literal) => `--theme-spx(${literal}, ${themeRefWidth})`)

package/src/cssPlugins/spx/cascade.js

@@ -1,22 +1,41 @@
-import { lowerCalls } from './calls.js'
+import { fail } from './index.js'
+import { lowerCalls, lowerThemeCalls } from './calls.js'
 
 // Keep arithmetic at the call site: an inherited derived custom property would already
 // be computed against its parent's settings. Only the numeric resolver switch inherits.
 const SCALE = 'var(--origami-spx-scale, 1)'
 const FLOOR = `calc(0.5px * ${SCALE})`
-/** @param {string} cap */
-const unitCappedAt = cap =>
-    `(${SCALE} * (clamp(var(--spx-stopper-min, 0px), var(--scaling-factor, 100vw), min(var(--spx-stopper-max, 99999px), ${cap})) - var(--scrollbar-width, 0px)) / var(--spx-ref-width, 1280) + (1 - ${SCALE}) * 1px)`
+/**
+ * @param {string} cap
+ * @param {string} [divisor]
+ */
+const unitCappedAt = (cap, divisor = 'var(--spx-ref-width, 1280)') =>
+    `(${SCALE} * (clamp(var(--spx-stopper-min, 0px), var(--scaling-factor, 100vw), min(var(--spx-stopper-max, 99999px), ${cap})) - var(--scrollbar-width, 0px)) / ${divisor} + (1 - ${SCALE}) * 1px)`
 const UNIT = unitCappedAt('var(--content-max-width, 99999px)')
 const UNCAPPED_UNIT = unitCappedAt('99999px')
 
+/** @param {import('postcss').Declaration} declaration */
+const compileThemeCalls = declaration => {
+    const cap = declaration.prop === '--content-max-width' ? '99999px' : 'var(--content-max-width, 99999px)'
+    lowerThemeCalls(
+        declaration,
+        (number, themeRefWidth) => {
+            if (number === 0) return '0px'
+            const divisor = String(themeRefWidth)
+            const unit = unitCappedAt(cap, divisor)
+            return number < 0 ? `min(calc(-1 * ${FLOOR}), ${number} * ${unit})` : `max(${FLOOR}, ${number} * ${unit})`
+        },
+        () => declaration.error('SPX calls --theme-spx() without a literal number and a positive literal theme reference width')
+    )
+}
+
 /** Compile settings and calls in place, retaining their cascade and source locations.
  * @param {import('postcss').Declaration} declaration
  */
 export const compileCascadeDeclaration = declaration => {
     if (declaration.prop === '--spx-resolver-type') {
         const resolver = declaration.value.trim()
-        if (!['scale', 'fixed'].includes(resolver)) throw declaration.error('Unsupported SPX resolver')
+        if (!['scale', 'fixed'].includes(resolver)) throw fail('unsupported_spx_resolver', declaration.error('Unsupported SPX resolver'))
         const value = resolver === 'scale' ? '1' : '0'
         const previous = declaration.prev()
         if (
@@ -32,8 +51,9 @@ export const compileCascadeDeclaration = declaration => {
         declaration.prop === '--spx-ref-width' &&
         (!Number.isFinite(Number(declaration.value)) || Number(declaration.value) <= 0)
     ) {
-        throw declaration.error('SPX reference width must be positive')
+        throw fail('invalid_spx_reference_width', declaration.error('SPX reference width must be positive'))
     }
+    compileThemeCalls(declaration)
     const unit = declaration.prop === '--content-max-width' ? UNCAPPED_UNIT : UNIT
     lowerCalls(
         declaration,

package/src/cssPlugins/spx/index.js

@@ -1,7 +1,14 @@
 import { compileCascadeDeclaration } from './cascade.js'
 
-/** @type {import('../../transform/types.js').CssTransformPlugin} */
+export const checks = /** @type {const} */ (['unsupported_spx_resolver', 'invalid_spx_reference_width', 'non_literal_spx_argument'])
+/** @typedef {typeof checks[number]} Check */
+
+/** @template {Error} E @param {Check} check @param {E} error */
+export const fail = (check, error) => Object.assign(error, { check })
+
+/** @type {import('../../transform/types.js').CssTransformPlugin<Check>} */
 export const spxPlugin = {
+    checks,
     name: 'spx',
     order: 20,
     transform(root) {

package/src/cssPlugins/spxThemeVariables/README.md

@@ -0,0 +1,14 @@
+# Theme SPX variables follow each section's settings
+
+A custom property resolves `--spx()` where it is declared, so theme variables on `:root` ignore a section's `--content-max-width`. Like Thunderbolt, this plugin re-declares them on each capped section.
+
+- **Theme:** the `:root` rules from `src/global/themes/theme.css`, at the top level or under one `(max-width: Npx)` `@media`. Theme variables are their custom properties except the SPX settings. Without a site folder in the context, the plugin does nothing.
+- **Cascade:** at a breakpoint, the theme value of a variable is the one CSS gives `:root` there: among desktop, that breakpoint and every wider one, the declaration that comes last in the stylesheet wins, whatever the widths. So a wider block written after a narrower one overrides it.
+- **Restate:** a theme variable holding `--spx(` that a breakpoint inherits, through the cascade, from a breakpoint with another `--spx-ref-width` is re-declared on that breakpoint's last theme `:root`, widest breakpoint first, so it is tagged with the breakpoint's own reference width, like the `:root` value it had before. When a narrower breakpoint that sets the variable comes before that `:root`, the restatement goes in a new `:root` block of that breakpoint placed just before the narrower one, so the narrower value still wins. `var()` readers are not restated, and neither is a value written after that last `:root`, since the restatement would lose to it.
+- **Tag:** each theme `--spx(N)` becomes `--theme-spx(N, W)`, W being that breakpoint's `--spx-ref-width`, so a section's own reference width never changes it.
+- **Capped:** a section whose desktop rule sets `--content-max-width`.
+- **Copied:** desktop copies every SPX-dependent variable (it holds `--theme-spx(` or reads one through `var()`, at any depth), except `--content-max-width`. Each breakpoint copies the variables whose cascade winner it sets that are SPX-dependent or override a wider copy, plus inherited ones that first become SPX-dependent there. Copies are written widest first, so each breakpoint copy holds the value `:root` has there.
+- **Written:** one `@layer origami-theme-copies` at the top, after any `@charset` and `@import`, so it is the lowest layer: any section rule wins, and a copy still beats the value inherited from `:root`. Inside it, one `:where(#a, #b, …)` rule for desktop, then one `@media` per breakpoint, widest first. Sections inside `@scope`, `@supports` or `@container` get their own list, wrapped in a copy of those wrapping at-rules, so the copies keep the section's condition. Copies drop `!important`. Nothing is written without copies or capped sections.
+- **Order:** 16, after layout (15) and before SPX (20), which compiles `--theme-spx()`.
+
+Code: `index.js` runs `stylesheetUtils.js` (scan), `themeUtils.js` (read), `copyPlanUtils.js` (breakpoint order, shared by restate and plan), `restateUtils.js`, `themeUtils.js` (tag), `sectionUtils.js` (with `wrappingAtRuleUtils.js`), `copyPlanUtils.js`, then `writeUtils.js`. Tests: `test/spxThemeVariables.spec.js`.

package/src/cssPlugins/spxThemeVariables/index.js

@@ -0,0 +1,36 @@
+import { planBreakpoints, planThemeCopies } from './utils/copyPlanUtils.js'
+import { readSectionRules } from './utils/sectionUtils.js'
+import { restateThemeVariables } from './utils/restateUtils.js'
+import { scanStylesheet } from './utils/stylesheetUtils.js'
+import { readThemeVariables, tagThemeVariables } from './utils/themeUtils.js'
+import { writeCopies } from './utils/writeUtils.js'
+
+/**
+ * @param {import('postcss').Root} root
+ * @param {string} siteFolder
+ */
+const copyThemeVariables = (root, siteFolder) => {
+    const { themeRules, layoutRules } = scanStylesheet(root, siteFolder)
+    const theme = readThemeVariables(themeRules)
+    const breakpointPlan = planBreakpoints(theme)
+    restateThemeVariables(theme, breakpointPlan)
+    tagThemeVariables(theme.rules.map(({ scanned }) => scanned), theme)
+    const sections = readSectionRules(layoutRules)
+    const themeCopies = planThemeCopies(theme, breakpointPlan)
+    writeCopies(root, themeCopies, sections)
+}
+
+const checks = /** @type {const} */ ([])
+/** @typedef {typeof checks[number]} Check */
+
+/** @type {import('../../transform/types.js').CssTransformPlugin<Check>} */
+export const spxThemeVariablesPlugin = {
+    checks,
+    name: 'spx-theme-variables',
+    order: 16,
+    transform(root, context) {
+        const siteFolder = context?.layout?.root
+        if (siteFolder === undefined) return
+        copyThemeVariables(root, siteFolder)
+    },
+}

package/src/cssPlugins/spxThemeVariables/utils/breakpointUtils.js

@@ -0,0 +1,126 @@
+import { DESKTOP, collapseWhitespace, isMedia } from './cssTreeUtils.js'
+
+/** @typedef {Map<string, import('postcss').Declaration>} VariableMap */
+
+/**
+ * @typedef {object} ThemeRule
+ * @property {import('./stylesheetUtils.js').ScannedRule} scanned
+ * @property {VariableMap} variables
+ */
+
+/**
+ * @typedef {object} ThemeVariables
+ * @property {ThemeRule[]} rules
+ * @property {string[]} breakpoints
+ * @property {Map<string, number>} refWidthByBreakpoint
+ */
+
+/**
+ * @typedef {object} CascadedVariable
+ * @property {import('postcss').Declaration} declaration
+ * @property {string} breakpoint
+ * @property {number} index
+ */
+
+const DEFAULT_REF_WIDTH = 1280
+
+const MAX_WIDTH = /^\(\s*max-width\s*:\s*(\d+(?:\.\d+)?)px\s*\)$/i
+
+/** @param {string} query */
+export const maxWidthOf = query => {
+    const trimmed = query.trim()
+    const match = MAX_WIDTH.exec(trimmed)
+    return match === null ? undefined : Number(match[1])
+}
+
+/** @param {string} query */
+const breakpointKeyOf = query => {
+    const maxWidth = maxWidthOf(query)
+    return maxWidth === undefined ? collapseWhitespace(query) : `(max-width: ${maxWidth}px)`
+}
+
+/** @param {readonly import('postcss').Node[]} ancestors */
+export const breakpointOf = ancestors => {
+    const media = ancestors.find(isMedia)
+    return media === undefined ? DESKTOP : breakpointKeyOf(media.params)
+}
+
+/** @param {readonly string[]} breakpoints */
+export const widestFirst = breakpoints =>
+    [...breakpoints].sort((left, right) => (maxWidthOf(right) ?? 0) - (maxWidthOf(left) ?? 0))
+
+/** @param {ThemeVariables} theme */
+export const themeBreakpointsOf = ({ breakpoints }) => breakpoints
+
+/**
+ * @param {readonly string[]} breakpoints
+ * @param {string} breakpoint
+ */
+const enclosingBreakpointsOf = (breakpoints, breakpoint) => {
+    const maxWidth = maxWidthOf(breakpoint)
+    if (maxWidth === undefined) return [breakpoint]
+    return breakpoints.filter(candidate => (maxWidthOf(candidate) ?? -1) >= maxWidth)
+}
+
+/**
+ * @param {ThemeVariables} theme
+ * @param {string} breakpoint
+ */
+export const inheritedBreakpointsOf = ({ breakpoints }, breakpoint) => {
+    if (breakpoint === DESKTOP) return []
+    const enclosing = enclosingBreakpointsOf(breakpoints, breakpoint)
+    const outer = enclosing.filter(candidate => candidate !== breakpoint)
+    return [DESKTOP, ...outer]
+}
+
+/**
+ * @param {ThemeRule} rule
+ * @param {number} index
+ * @returns {[string, CascadedVariable][]}
+ */
+const cascadedVariablesOf = ({ scanned, variables }, index) => {
+    const { breakpoint } = scanned
+    return [...variables].map(([prop, declaration]) => [prop, { declaration, breakpoint, index }])
+}
+
+/**
+ * @param {ThemeVariables} theme
+ * @param {readonly string[]} cascadeBreakpoints
+ * @returns {Map<string, CascadedVariable>}
+ */
+export const cascadeAt = ({ rules }, cascadeBreakpoints) => {
+    const matching = new Set(cascadeBreakpoints)
+    const entries = rules.flatMap((rule, index) => (matching.has(rule.scanned.breakpoint) ? cascadedVariablesOf(rule, index) : []))
+    return new Map(entries)
+}
+
+/**
+ * @param {readonly string[]} breakpoints
+ * @param {Map<string, number>} ownRefWidths
+ * @param {string} breakpoint
+ */
+const resolveRefWidth = (breakpoints, ownRefWidths, breakpoint) => {
+    const own = ownRefWidths.get(breakpoint)
+    if (own !== undefined) return own
+    const enclosing = enclosingBreakpointsOf(breakpoints, breakpoint)
+    const defined = enclosing.flatMap(candidate => ownRefWidths.get(candidate) ?? [])
+    return defined.at(-1) ?? ownRefWidths.get(DESKTOP) ?? DEFAULT_REF_WIDTH
+}
+
+/**
+ * @param {readonly string[]} breakpoints
+ * @param {Map<string, number>} ownRefWidths
+ */
+export const resolveRefWidths = (breakpoints, ownRefWidths) => {
+    const entries = [DESKTOP, ...breakpoints].map(breakpoint => {
+        const refWidth = resolveRefWidth(breakpoints, ownRefWidths, breakpoint)
+        return /** @type {const} */ ([breakpoint, refWidth])
+    })
+    return new Map(entries)
+}
+
+/**
+ * @param {ThemeVariables} theme
+ * @param {string} breakpoint
+ */
+export const refWidthAt = ({ refWidthByBreakpoint }, breakpoint) => refWidthByBreakpoint.get(breakpoint) ?? DEFAULT_REF_WIDTH