@wix/origami-transforms 0.1.29 → 0.1.31

package/dist/cssPlugins/spx/calls.d.ts

@@ -1 +1,4 @@
+export const THEME_SPX: "--theme-spx(";
 export function lowerCalls(declaration: import("postcss").Declaration, resolve: (value: number) => string, invalidCall: () => Error): void;
+export function lowerThemeCalls(declaration: import("postcss").Declaration, resolve: (value: number, themeRefWidth: number) => string, invalidCall: () => Error): void;
+export function toThemeCalls(value: string, themeRefWidth: number): string;

package/dist/cssPlugins/spxThemeVariables/index.d.ts

@@ -0,0 +1,6 @@
+/** @typedef {typeof checks[number]} Check */
+/** @type {import('../../transform/types.js').CssTransformPlugin<Check>} */
+export const spxThemeVariablesPlugin: import("../../transform/types.js").CssTransformPlugin<Check>;
+export type Check = (typeof checks)[number];
+declare const checks: readonly [];
+export {};

package/dist/cssPlugins/spxThemeVariables/utils/breakpointUtils.d.ts

@@ -0,0 +1,23 @@
+export function maxWidthOf(query: string): number | undefined;
+export function breakpointOf(ancestors: readonly import("postcss").Node[]): string;
+export function widestFirst(breakpoints: readonly string[]): string[];
+export function themeBreakpointsOf({ breakpoints }: ThemeVariables): string[];
+export function inheritedBreakpointsOf({ breakpoints }: ThemeVariables, breakpoint: string): string[];
+export function cascadeAt({ rules }: ThemeVariables, cascadeBreakpoints: readonly string[]): Map<string, CascadedVariable>;
+export function resolveRefWidths(breakpoints: readonly string[], ownRefWidths: Map<string, number>): Map<string, number>;
+export function refWidthAt({ refWidthByBreakpoint }: ThemeVariables, breakpoint: string): number;
+export type VariableMap = Map<string, import("postcss").Declaration>;
+export type ThemeRule = {
+    scanned: import("./stylesheetUtils.js").ScannedRule;
+    variables: VariableMap;
+};
+export type ThemeVariables = {
+    rules: ThemeRule[];
+    breakpoints: string[];
+    refWidthByBreakpoint: Map<string, number>;
+};
+export type CascadedVariable = {
+    declaration: import("postcss").Declaration;
+    breakpoint: string;
+    index: number;
+};

package/dist/cssPlugins/spxThemeVariables/utils/copyPlanUtils.d.ts

@@ -0,0 +1,14 @@
+export function planBreakpoints(theme: ThemeVariables): BreakpointPlan;
+export function planThemeCopies(theme: ThemeVariables, breakpointPlan: BreakpointPlan): ThemeCopies;
+export type CascadedVariable = import("./breakpointUtils.js").CascadedVariable;
+export type ThemeVariables = import("./breakpointUtils.js").ThemeVariables;
+export type VariableMap = import("./breakpointUtils.js").VariableMap;
+export type Declaration = import("postcss").Declaration;
+export type ThemeCopies = Map<string, VariableMap>;
+export type VariableReferences = Map<string, string[]>;
+export type BreakpointPlan = Map<string, string[]>;
+export type CopyCriteria = {
+    ownVariables: VariableMap;
+    scaleDependent: Set<string>;
+    widerCopied: Set<string>;
+};

package/dist/cssPlugins/spxThemeVariables/utils/cssTreeUtils.d.ts

@@ -0,0 +1,10 @@
+export const DESKTOP: "";
+export function ancestorsOf(node: import("postcss").Node): import("postcss").Node[];
+export function isAtRule(node: import("postcss").Node): node is import("postcss").AtRule;
+export function collapseWhitespace(text: string): string;
+export function isInContainerDefaults(ancestors: readonly import("postcss").Node[]): boolean;
+export function isTopLevel(ancestors: readonly import("postcss").Node[]): ancestors is readonly import("postcss").AtRule[];
+export function hasRootSelector(rule: import("postcss").Rule): boolean;
+export function isCustomProperty(prop: string): boolean;
+export function isMedia(node: import("postcss").Node): node is import("postcss").AtRule;
+export function declarationsOf(rule: import("postcss").Rule): import("postcss").Declaration[];

package/dist/cssPlugins/spxThemeVariables/utils/restateUtils.d.ts

@@ -0,0 +1,9 @@
+export function restateThemeVariables(theme: ThemeVariables, breakpointPlan: BreakpointPlan): void;
+export type CascadedVariable = import("./breakpointUtils.js").CascadedVariable;
+export type ThemeVariables = import("./breakpointUtils.js").ThemeVariables;
+export type BreakpointPlan = import("./copyPlanUtils.js").BreakpointPlan;
+export type RestateTarget = {
+    breakpoint: string;
+    index: number;
+    refWidth: number;
+};

package/dist/cssPlugins/spxThemeVariables/utils/sectionUtils.d.ts

@@ -0,0 +1,6 @@
+/** @typedef {import('./stylesheetUtils.js').ScannedRule} ScannedRule */
+/** @typedef {import('./wrappingAtRuleUtils.js').Section} Section */
+export const CONTENT_MAX_WIDTH: "--content-max-width";
+export function readSectionRules(layoutRules: readonly ScannedRule[]): Section[];
+export type ScannedRule = import("./stylesheetUtils.js").ScannedRule;
+export type Section = import("./wrappingAtRuleUtils.js").Section;

package/dist/cssPlugins/spxThemeVariables/utils/stylesheetUtils.d.ts

@@ -0,0 +1,10 @@
+export function scanStylesheet(root: import("postcss").Root, siteFolder: string): StylesheetScan;
+export type ScannedRule = {
+    rule: import("postcss").Rule;
+    breakpoint: string;
+    declarations: import("postcss").Declaration[];
+};
+export type StylesheetScan = {
+    themeRules: ScannedRule[];
+    layoutRules: ScannedRule[];
+};

package/dist/cssPlugins/spxThemeVariables/utils/themeUtils.d.ts

@@ -0,0 +1,6 @@
+export function readThemeVariables(themeRules: readonly ScannedRule[]): ThemeVariables;
+export function tagThemeVariables(themeRules: readonly ScannedRule[], theme: ThemeVariables): void;
+export type ThemeRule = import("./breakpointUtils.js").ThemeRule;
+export type ThemeVariables = import("./breakpointUtils.js").ThemeVariables;
+export type VariableMap = import("./breakpointUtils.js").VariableMap;
+export type ScannedRule = import("./stylesheetUtils.js").ScannedRule;

package/dist/cssPlugins/spxThemeVariables/utils/wrappingAtRuleUtils.d.ts

@@ -0,0 +1,10 @@
+export function wrappingAtRulesOf(rule: import("postcss").Rule): import("postcss").AtRule[];
+export function groupSectionsByWrappingAtRules(sections: readonly Section[]): SectionGroup[];
+export type Section = {
+    selector: string;
+    wrappingAtRules: import("postcss").AtRule[];
+};
+export type SectionGroup = {
+    wrappingAtRules: import("postcss").AtRule[];
+    selectors: string[];
+};

package/dist/cssPlugins/spxThemeVariables/utils/writeUtils.d.ts

@@ -0,0 +1,17 @@
+/** @typedef {import('./copyPlanUtils.js').ThemeCopies} ThemeCopies */
+/** @typedef {import('./wrappingAtRuleUtils.js').Section} Section */
+/** @typedef {import('./wrappingAtRuleUtils.js').SectionGroup} SectionGroup */
+/**
+ * @typedef {object} BreakpointCopies
+ * @property {string} breakpoint
+ * @property {import('postcss').Declaration[]} declarations
+ */
+export const THEME_COPIES_LAYER: "origami-theme-copies";
+export function writeCopies(root: import("postcss").Root, themeCopies: ThemeCopies, sections: readonly Section[]): void;
+export type ThemeCopies = import("./copyPlanUtils.js").ThemeCopies;
+export type Section = import("./wrappingAtRuleUtils.js").Section;
+export type SectionGroup = import("./wrappingAtRuleUtils.js").SectionGroup;
+export type BreakpointCopies = {
+    breakpoint: string;
+    declarations: import("postcss").Declaration[];
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/origami-transforms",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "description": "Babel and PostCSS checks and transforms for Wix origami page files.",
   "main": "./src/index.js",
   "files": [
@@ -23,7 +23,7 @@
     "@wix/origami-system-components": "1.10.6",
     "postcss": "^8.5.3",
     "postcss-custom-media": "^12.0.1",
-    "@wix/origami-bi": "0.10.0"
+    "@wix/origami-bi": "0.11.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
@@ -71,5 +71,5 @@
   },
   "type": "module",
   "types": "./dist/index.d.ts",
-  "falconPackageHash": "26f18af79b8f5dd98a7aba58e68be7f9dd09c52bdd522e0eb33180c4"
+  "falconPackageHash": "eea52f454e6f8d604431d5d69e6ce0bae25496f2528518f4dbdb43dd"
 }

package/src/cssPlugins/index.js

@@ -26,6 +26,7 @@ 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'
 
@@ -39,6 +40,7 @@ export const cssPlugins = Object.freeze([
     presetsPlugin,
     componentPositionPlugin,
     layoutPlugin,
+    spxThemeVariablesPlugin,
     spxPlugin,
     shapeDividersPlugin,
     wixVectorUrlsPlugin,

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,5 +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
@@ -11,3 +14,26 @@ export const lowerCalls = (declaration, resolve, invalidCall) => {
     declaration.value = declaration.value.replace(CALL, (_, literal) => resolve(Number(literal)))
     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,16 +1,34 @@
 import { fail } from './index.js'
-import { lowerCalls } from './calls.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
  */
@@ -35,6 +53,7 @@ export const compileCascadeDeclaration = declaration => {
     ) {
         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/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

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

@@ -0,0 +1,162 @@
+import { THEME_SPX } from '../../spx/calls.js'
+import { cascadeAt, inheritedBreakpointsOf, themeBreakpointsOf, widestFirst } from './breakpointUtils.js'
+import { DESKTOP } from './cssTreeUtils.js'
+import { CONTENT_MAX_WIDTH } from './sectionUtils.js'
+
+/** @typedef {import('./breakpointUtils.js').CascadedVariable} CascadedVariable */
+/** @typedef {import('./breakpointUtils.js').ThemeVariables} ThemeVariables */
+/** @typedef {import('./breakpointUtils.js').VariableMap} VariableMap */
+/** @typedef {import('postcss').Declaration} Declaration */
+/** @typedef {Map<string, VariableMap>} ThemeCopies */
+/** @typedef {Map<string, string[]>} VariableReferences */
+/** @typedef {Map<string, string[]>} BreakpointPlan */
+
+const VAR_REFERENCE = /var\(\s*(--[\w-]+)/g
+
+/** @param {ThemeVariables} theme */
+const getPlanOrder = theme => {
+    const breakpoints = themeBreakpointsOf(theme)
+    const widest = widestFirst(breakpoints)
+    return [DESKTOP, ...widest]
+}
+
+/**
+ * @param {ThemeVariables} theme
+ * @returns {BreakpointPlan}
+ */
+export const planBreakpoints = theme => {
+    const breakpoints = getPlanOrder(theme)
+    const entries = breakpoints.map(breakpoint => {
+        const inheritedBreakpoints = inheritedBreakpointsOf(theme, breakpoint)
+        return /** @type {const} */ ([breakpoint, inheritedBreakpoints])
+    })
+    return new Map(entries)
+}
+
+/** @param {Declaration} declaration */
+const getReferencedNames = declaration => {
+    const matches = [...declaration.value.matchAll(VAR_REFERENCE)]
+    return matches.map(([, name]) => name)
+}
+
+/**
+ * @param {VariableMap} variables
+ * @returns {VariableReferences}
+ */
+const buildReferenceMap = variables => {
+    /** @type {VariableReferences} */
+    const references = new Map()
+    for (const [prop, declaration] of variables) {
+        const names = getReferencedNames(declaration)
+        references.set(prop, names)
+    }
+    return references
+}
+
+/**
+ * @param {Set<string>} targets
+ * @param {readonly string[]} names
+ */
+const readsAny = (targets, names) => names.some(name => targets.has(name))
+
+/**
+ * @param {VariableReferences} references
+ * @param {Set<string>} seeds
+ */
+const collectReaders = (references, seeds) => {
+    const reached = new Set(seeds)
+    let previousSize = -1
+    while (reached.size !== previousSize) {
+        previousSize = reached.size
+        for (const [prop, names] of references) {
+            if (readsAny(reached, names)) reached.add(prop)
+        }
+    }
+    return reached
+}
+
+/** @param {VariableMap} variables */
+const findScaleDependent = variables => {
+    const scaledVariables = [...variables].filter(([, declaration]) => declaration.value.includes(THEME_SPX))
+    const scaledProps = scaledVariables.map(([prop]) => prop)
+    const scaled = new Set(scaledProps)
+    const references = buildReferenceMap(variables)
+    return collectReaders(references, scaled)
+}
+
+/**
+ * @param {Map<string, CascadedVariable>} cascaded
+ * @returns {VariableMap}
+ */
+const mergeCascade = cascaded => {
+    const variables = [...cascaded].map(([prop, { declaration }]) => /** @type {const} */ ([prop, declaration]))
+    return new Map(variables)
+}
+
+/**
+ * @param {Map<string, CascadedVariable>} cascaded
+ * @param {string} breakpoint
+ * @returns {VariableMap}
+ */
+const ownVariablesOf = (cascaded, breakpoint) => {
+    const own = [...cascaded].filter(([, cascadedVariable]) => cascadedVariable.breakpoint === breakpoint)
+    const variables = own.map(([prop, { declaration }]) => /** @type {const} */ ([prop, declaration]))
+    return new Map(variables)
+}
+
+/**
+ * @param {ThemeCopies} themeCopies
+ * @param {readonly string[]} inheritedBreakpoints
+ */
+const getWiderCopiedNames = (themeCopies, inheritedBreakpoints) => {
+    const props = inheritedBreakpoints.flatMap(breakpoint => {
+        const copies = themeCopies.get(breakpoint) ?? new Map()
+        return [...copies.keys()]
+    })
+    return new Set(props)
+}
+
+/**
+ * @typedef {object} CopyCriteria
+ * @property {VariableMap} ownVariables
+ * @property {Set<string>} scaleDependent
+ * @property {Set<string>} widerCopied
+ */
+
+/**
+ * @param {string} prop
+ * @param {CopyCriteria} criteria
+ */
+const shouldCopy = (prop, { ownVariables, scaleDependent, widerCopied }) =>
+    ownVariables.has(prop)
+        ? scaleDependent.has(prop) || widerCopied.has(prop)
+        : scaleDependent.has(prop) && !widerCopied.has(prop)
+
+/**
+ * @param {string} prop
+ * @param {CopyCriteria} criteria
+ */
+const shouldCopyVariable = (prop, criteria) => prop !== CONTENT_MAX_WIDTH && shouldCopy(prop, criteria)
+
+/**
+ * @param {ThemeVariables} theme
+ * @param {BreakpointPlan} breakpointPlan
+ * @returns {ThemeCopies}
+ */
+export const planThemeCopies = (theme, breakpointPlan) => {
+    /** @type {ThemeCopies} */
+    const themeCopies = new Map()
+    for (const [breakpoint, inheritedBreakpoints] of breakpointPlan) {
+        const cascadeBreakpoints = [...inheritedBreakpoints, breakpoint]
+        const cascaded = cascadeAt(theme, cascadeBreakpoints)
+        const ownVariables = ownVariablesOf(cascaded, breakpoint)
+        const effectiveVariables = mergeCascade(cascaded)
+        const scaleDependent = findScaleDependent(effectiveVariables)
+        const widerCopied = getWiderCopiedNames(themeCopies, inheritedBreakpoints)
+        const criteria = { ownVariables, scaleDependent, widerCopied }
+        const copiedEntries = [...effectiveVariables].filter(([prop]) => shouldCopyVariable(prop, criteria))
+        const copies = new Map(copiedEntries)
+        themeCopies.set(breakpoint, copies)
+    }
+    return themeCopies
+}

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

@@ -0,0 +1,58 @@
+import { DEFAULTS_LAYER } from '../../layout/contract.js'
+
+export const DESKTOP = ''
+
+/**
+ * @param {import('postcss').Node} node
+ * @returns {import('postcss').Node[]}
+ */
+export const ancestorsOf = node => {
+    /** @type {import('postcss').Node[]} */
+    const ancestors = []
+    let current = node.parent
+    while (current !== undefined && current.type !== 'root' && current.type !== 'document') {
+        ancestors.push(current)
+        current = current.parent
+    }
+    return ancestors
+}
+
+/**
+ * @param {import('postcss').Node} node
+ * @returns {node is import('postcss').AtRule}
+ */
+export const isAtRule = node => node.type === 'atrule'
+
+/** @param {string} text */
+export const collapseWhitespace = text => text.replace(/\s+/g, ' ').trim()
+
+/**
+ * @param {import('postcss').Node} node
+ * @param {string} name
+ */
+const isLayerNamed = (node, name) => isAtRule(node) && node.name === 'layer' && node.params.trim() === name
+
+/** @param {readonly import('postcss').Node[]} ancestors */
+export const isInContainerDefaults = ancestors => ancestors.some(node => isLayerNamed(node, DEFAULTS_LAYER))
+
+/** @param {readonly import('postcss').Node[]} ancestors */
+export const isTopLevel = ancestors => ancestors.every(isAtRule)
+
+/** @param {import('postcss').Rule} rule */
+export const hasRootSelector = rule => rule.selector.trim() === ':root'
+
+/** @param {string} prop */
+export const isCustomProperty = prop => prop.startsWith('--')
+
+/**
+ * @param {import('postcss').Node} node
+ * @returns {node is import('postcss').AtRule}
+ */
+export const isMedia = node => isAtRule(node) && node.name === 'media'
+
+/**
+ * @param {import('postcss').Rule} rule
+ * @returns {import('postcss').Declaration[]}
+ */
+export const declarationsOf = rule =>
+    rule.nodes.filter(/** @returns {node is import('postcss').Declaration} */ node => node.type === 'decl')

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

@@ -0,0 +1,134 @@
+import { cascadeAt, maxWidthOf, refWidthAt } from './breakpointUtils.js'
+import { isAtRule } from './cssTreeUtils.js'
+
+/** @typedef {import('./breakpointUtils.js').CascadedVariable} CascadedVariable */
+/** @typedef {import('./breakpointUtils.js').ThemeVariables} ThemeVariables */
+/** @typedef {import('./copyPlanUtils.js').BreakpointPlan} BreakpointPlan */
+
+/**
+ * @typedef {object} RestateTarget
+ * @property {string} breakpoint
+ * @property {number} index
+ * @property {number} refWidth
+ */
+
+const SPX_CALL = '--spx('
+
+/**
+ * @param {ThemeVariables} theme
+ * @param {string} breakpoint
+ */
+const lastIndexAt = ({ rules }, breakpoint) => {
+    const indexes = rules.flatMap(({ scanned }, index) => (scanned.breakpoint === breakpoint ? [index] : []))
+    return indexes.at(-1)
+}
+
+/**
+ * @param {ThemeVariables} theme
+ * @param {RestateTarget} target
+ * @param {[string, CascadedVariable]} entry
+ */
+const needsRestate = (theme, target, [, source]) => {
+    if (source.breakpoint === target.breakpoint) return false
+    if (source.index > target.index) return false
+    if (!source.declaration.value.includes(SPX_CALL)) return false
+    const sourceRefWidth = refWidthAt(theme, source.breakpoint)
+    return sourceRefWidth !== target.refWidth
+}
+
+/**
+ * @param {ThemeVariables} theme
+ * @param {RestateTarget} target
+ * @param {[string, CascadedVariable]} entry
+ */
+const narrowerRuleIndexOf = ({ rules }, target, [prop, source]) => {
+    const targetWidth = maxWidthOf(target.breakpoint)
+    if (targetWidth === undefined) return -1
+    const sourceIndex = rules.findIndex(({ scanned }) => scanned.rule === source.declaration.parent)
+    const declaresNarrower = ({ scanned, variables }, index) => {
+        const width = maxWidthOf(scanned.breakpoint)
+        return index > sourceIndex && width !== undefined && width < targetWidth && variables.has(prop)
+    }
+    return rules.findIndex(declaresNarrower)
+}
+
+/**
+ * @param {import('./breakpointUtils.js').ThemeRule} target
+ * @param {[string, CascadedVariable]} entry
+ */
+const restateInto = ({ scanned, variables }, [prop, { declaration }]) => {
+    const clone = declaration.clone({ raws: {} })
+    scanned.rule.append(clone)
+    scanned.declarations.push(clone)
+    variables.set(prop, clone)
+}
+
+/**
+ * @param {import('postcss').Declaration} clone
+ * @param {import('postcss').Rule} targetRule
+ * @param {import('postcss').AtRule} targetMedia
+ */
+const wrapperOf = (clone, targetRule, targetMedia) => {
+    const rule = targetRule.clone({ raws: {} }).removeAll()
+    rule.append(clone)
+    const wrapper = targetMedia.clone({ raws: {} }).removeAll()
+    wrapper.append(rule)
+    return { rule, wrapper }
+}
+
+/**
+ * @param {ThemeVariables} theme
+ * @param {import('./breakpointUtils.js').ThemeRule} targetRule
+ * @param {number} index
+ * @param {[string, CascadedVariable]} entry
+ */
+const restateBefore = (theme, targetRule, index, entry) => {
+    const [prop, { declaration }] = entry
+    const targetMedia = targetRule.scanned.rule.parent
+    const narrowerMedia = theme.rules[index].scanned.rule.parent
+    if (targetMedia === undefined || narrowerMedia === undefined) return restateInto(targetRule, entry)
+    if (!isAtRule(targetMedia) || !isAtRule(narrowerMedia)) return restateInto(targetRule, entry)
+    const clone = declaration.clone({ raws: {} })
+    const { rule, wrapper } = wrapperOf(clone, targetRule.scanned.rule, targetMedia)
+    narrowerMedia.before(wrapper)
+    const { breakpoint } = targetRule.scanned
+    const scanned = { rule, breakpoint, declarations: [clone] }
+    theme.rules.splice(index, 0, { scanned, variables: new Map([[prop, clone]]) })
+}
+
+/**
+ * @param {ThemeVariables} theme
+ * @param {import('./breakpointUtils.js').ThemeRule} targetRule
+ * @param {RestateTarget} target
+ * @param {[string, CascadedVariable]} entry
+ */
+const restate = (theme, targetRule, target, entry) => {
+    const index = narrowerRuleIndexOf(theme, target, entry)
+    const targetIndex = theme.rules.indexOf(targetRule)
+    if (index === -1 || index >= targetIndex) return restateInto(targetRule, entry)
+    restateBefore(theme, targetRule, index, entry)
+}
+
+/**
+ * @param {ThemeVariables} theme
+ * @param {string} breakpoint
+ * @param {readonly string[]} inheritedBreakpoints
+ */
+const restateAt = (theme, breakpoint, inheritedBreakpoints) => {
+    const index = lastIndexAt(theme, breakpoint)
+    if (index === undefined) return
+    const refWidth = refWidthAt(theme, breakpoint)
+    const target = { breakpoint, index, refWidth }
+    const cascaded = cascadeAt(theme, [...inheritedBreakpoints, breakpoint])
+    const stale = [...cascaded].filter(entry => needsRestate(theme, target, entry))
+    const targetRule = theme.rules[index]
+    for (const entry of stale) restate(theme, targetRule, target, entry)
+}
+
+/**
+ * @param {ThemeVariables} theme
+ * @param {BreakpointPlan} breakpointPlan
+ */
+export const restateThemeVariables = (theme, breakpointPlan) => {
+    for (const [breakpoint, inheritedBreakpoints] of breakpointPlan) restateAt(theme, breakpoint, inheritedBreakpoints)
+}

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

@@ -0,0 +1,32 @@
+import { DESKTOP } from './cssTreeUtils.js'
+import { wrappingAtRulesOf } from './wrappingAtRuleUtils.js'
+
+/** @typedef {import('./stylesheetUtils.js').ScannedRule} ScannedRule */
+/** @typedef {import('./wrappingAtRuleUtils.js').Section} Section */
+
+export const CONTENT_MAX_WIDTH = '--content-max-width'
+
+/** @param {ScannedRule} layoutRule */
+const capsAtDesktop = ({ breakpoint, declarations }) => {
+    if (breakpoint !== DESKTOP) return false
+    return declarations.some(({ prop }) => prop === CONTENT_MAX_WIDTH)
+}
+
+/**
+ * @param {ScannedRule} layoutRule
+ * @returns {Section}
+ */
+const sectionOf = ({ rule }) => {
+    const selector = rule.selector.trim()
+    const wrappingAtRules = wrappingAtRulesOf(rule)
+    return { selector, wrappingAtRules }
+}
+
+/**
+ * @param {readonly ScannedRule[]} layoutRules
+ * @returns {Section[]}
+ */
+export const readSectionRules = layoutRules => {
+    const sectionsWithMaxWidthRules = layoutRules.filter(capsAtDesktop)
+    return sectionsWithMaxWidthRules.map(sectionOf)
+}

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

@@ -0,0 +1,98 @@
+import { breakpointOf, maxWidthOf } from './breakpointUtils.js'
+import {
+    ancestorsOf,
+    declarationsOf,
+    hasRootSelector,
+    isInContainerDefaults,
+    isMedia,
+    isTopLevel,
+} from './cssTreeUtils.js'
+import { relativeToSite } from '../../../transform/relativeToSite.js'
+
+/**
+ * @typedef {object} ScannedRule
+ * @property {import('postcss').Rule} rule
+ * @property {string} breakpoint
+ * @property {import('postcss').Declaration[]} declarations
+ */
+
+/**
+ * @typedef {object} StylesheetScan
+ * @property {ScannedRule[]} themeRules
+ * @property {ScannedRule[]} layoutRules
+ */
+
+const THEME_FILE = 'src/global/themes/theme.css'
+
+/** @param {readonly import('postcss').Node[]} ancestors */
+const isThemeContext = ancestors => {
+    const [parent] = ancestors
+    if (parent === undefined) return true
+    return ancestors.length === 1 && isMedia(parent) && maxWidthOf(parent.params) !== undefined
+}
+
+/**
+ * @param {import('postcss').Rule} rule
+ * @param {string} siteFolder
+ */
+const isFromThemeFile = (rule, siteFolder) => {
+    const file = rule.source?.input.file
+    if (file === undefined) return false
+    const relative = relativeToSite(siteFolder, file)
+    return relative === THEME_FILE
+}
+
+/** @param {readonly import('postcss').Node[]} ancestors */
+const isLayoutRule = ancestors => isTopLevel(ancestors) && !isInContainerDefaults(ancestors)
+
+/**
+ * @param {import('postcss').Rule} rule
+ * @param {import('postcss').Node[]} ancestors
+ * @returns {ScannedRule}
+ */
+const scannedRuleOf = (rule, ancestors) => {
+    const breakpoint = breakpointOf(ancestors)
+    const declarations = declarationsOf(rule)
+    return { rule, breakpoint, declarations }
+}
+
+/**
+ * @param {import('postcss').Rule} rule
+ * @param {string} siteFolder
+ * @returns {ScannedRule[]}
+ */
+const themeRuleOf = (rule, siteFolder) => {
+    if (!isFromThemeFile(rule, siteFolder)) return []
+    const ancestors = ancestorsOf(rule)
+    if (!isThemeContext(ancestors)) return []
+    return [scannedRuleOf(rule, ancestors)]
+}
+
+/**
+ * @param {import('postcss').Rule} rule
+ * @returns {ScannedRule[]}
+ */
+const layoutRuleOf = rule => {
+    const ancestors = ancestorsOf(rule)
+    return isLayoutRule(ancestors) ? [scannedRuleOf(rule, ancestors)] : []
+}
+
+/**
+ * @param {import('postcss').Root} root
+ * @param {string} siteFolder
+ * @returns {StylesheetScan}
+ */
+export const scanStylesheet = (root, siteFolder) => {
+    /** @type {StylesheetScan} */
+    const scan = { themeRules: [], layoutRules: [] }
+    root.walkRules(rule => {
+        if (hasRootSelector(rule)) {
+            const themeRules = themeRuleOf(rule, siteFolder)
+            scan.themeRules.push(...themeRules)
+            return
+        }
+        const layoutRules = layoutRuleOf(rule)
+        scan.layoutRules.push(...layoutRules)
+    })
+    return scan
+}

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

@@ -0,0 +1,90 @@
+import { toThemeCalls } from '../../spx/calls.js'
+import { refWidthAt, resolveRefWidths } from './breakpointUtils.js'
+import { DESKTOP, isCustomProperty } from './cssTreeUtils.js'
+
+/** @typedef {import('./breakpointUtils.js').ThemeRule} ThemeRule */
+/** @typedef {import('./breakpointUtils.js').ThemeVariables} ThemeVariables */
+/** @typedef {import('./breakpointUtils.js').VariableMap} VariableMap */
+/** @typedef {import('./stylesheetUtils.js').ScannedRule} ScannedRule */
+
+const REF_WIDTH = '--spx-ref-width'
+
+const SPX_SETTINGS = new Set([
+    REF_WIDTH,
+    '--spx-resolver-type',
+    '--spx-stopper-min',
+    '--spx-stopper-max',
+    '--scaling-factor',
+    '--scrollbar-width',
+])
+
+/** @param {string} prop */
+const isThemeVariable = prop => isCustomProperty(prop) && !SPX_SETTINGS.has(prop)
+
+/** @param {number} refWidth */
+const isUsableRefWidth = refWidth => Number.isFinite(refWidth) && refWidth > 0
+
+/** @param {readonly ScannedRule[]} themeRules */
+const rootDeclarationsByBreakpointOf = themeRules => {
+    /** @type {Map<string, VariableMap>} */
+    const declarationsByBreakpoint = new Map()
+    for (const { breakpoint, declarations } of themeRules) {
+        const declarationMap = declarationsByBreakpoint.get(breakpoint) ?? new Map()
+        declarationsByBreakpoint.set(breakpoint, declarationMap)
+        for (const declaration of declarations) {
+            declarationMap.set(declaration.prop, declaration)
+        }
+    }
+    return declarationsByBreakpoint
+}
+
+/**
+ * @param {ScannedRule} scanned
+ * @returns {ThemeRule}
+ */
+const themeRuleOf = scanned => {
+    const themeVariables = scanned.declarations.filter(({ prop }) => isThemeVariable(prop))
+    const entries = themeVariables.map(declaration => /** @type {const} */ ([declaration.prop, declaration]))
+    const variables = new Map(entries)
+    return { scanned, variables }
+}
+
+/** @param {Map<string, VariableMap>} declarationsByBreakpoint */
+const breakpointsOf = declarationsByBreakpoint => {
+    const breakpoints = [...declarationsByBreakpoint.keys()]
+    return breakpoints.filter(breakpoint => breakpoint !== DESKTOP)
+}
+
+/** @param {Map<string, VariableMap>} declarationsByBreakpoint */
+const refWidthByBreakpointOf = declarationsByBreakpoint => {
+    const refWidths = [...declarationsByBreakpoint].flatMap(([breakpoint, declarationMap]) => {
+        const refWidth = Number(declarationMap.get(REF_WIDTH)?.value)
+        return isUsableRefWidth(refWidth) ? [/** @type {const} */ ([breakpoint, refWidth])] : []
+    })
+    return new Map(refWidths)
+}
+
+/**
+ * @param {readonly ScannedRule[]} themeRules
+ * @returns {ThemeVariables}
+ */
+export const readThemeVariables = themeRules => {
+    const declarationsByBreakpoint = rootDeclarationsByBreakpointOf(themeRules)
+    const rules = themeRules.map(themeRuleOf)
+    const breakpoints = breakpointsOf(declarationsByBreakpoint)
+    const ownRefWidths = refWidthByBreakpointOf(declarationsByBreakpoint)
+    const refWidthByBreakpoint = resolveRefWidths(breakpoints, ownRefWidths)
+    return { rules, breakpoints, refWidthByBreakpoint }
+}
+
+/**
+ * @param {readonly ScannedRule[]} themeRules
+ * @param {ThemeVariables} theme
+ */
+export const tagThemeVariables = (themeRules, theme) => {
+    for (const { breakpoint, declarations } of themeRules) {
+        const refWidth = refWidthAt(theme, breakpoint)
+        const variables = declarations.filter(({ prop }) => isThemeVariable(prop))
+        for (const declaration of variables) declaration.value = toThemeCalls(declaration.value, refWidth)
+    }
+}

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

@@ -0,0 +1,68 @@
+import { ancestorsOf, collapseWhitespace, isAtRule } from './cssTreeUtils.js'
+
+/**
+ * @typedef {object} Section
+ * @property {string} selector
+ * @property {import('postcss').AtRule[]} wrappingAtRules
+ */
+
+/**
+ * @typedef {object} SectionGroup
+ * @property {import('postcss').AtRule[]} wrappingAtRules
+ * @property {string[]} selectors
+ */
+
+const UNWRAPPED_KEY = ''
+
+/**
+ * @param {import('postcss').Node} node
+ * @returns {node is import('postcss').AtRule}
+ */
+const isWrappingAtRule = node => isAtRule(node) && node.name !== 'layer'
+
+/**
+ * @param {import('postcss').Rule} rule
+ * @returns {import('postcss').AtRule[]}
+ */
+export const wrappingAtRulesOf = rule => {
+    const ancestors = ancestorsOf(rule)
+    const wrappingAtRules = ancestors.filter(isWrappingAtRule)
+    return wrappingAtRules.reverse()
+}
+
+/** @param {import('postcss').AtRule} atRule */
+const atRuleLabelOf = ({ name, params }) => {
+    const collapsed = collapseWhitespace(params)
+    return `@${name} ${collapsed}`
+}
+
+/** @param {readonly import('postcss').AtRule[]} wrappingAtRules */
+const wrappingKeyOf = wrappingAtRules => {
+    const labels = wrappingAtRules.map(atRuleLabelOf)
+    return labels.join(' ')
+}
+
+/**
+ * @param {Map<string, SectionGroup>} groups
+ * @param {Section} section
+ */
+const addSectionToGroup = (groups, { selector, wrappingAtRules }) => {
+    const key = wrappingKeyOf(wrappingAtRules)
+    const group = groups.get(key) ?? { wrappingAtRules, selectors: [] }
+    if (!group.selectors.includes(selector)) group.selectors.push(selector)
+    groups.set(key, group)
+}
+
+/**
+ * @param {readonly Section[]} sections
+ * @returns {SectionGroup[]}
+ */
+export const groupSectionsByWrappingAtRules = sections => {
+    /** @type {Map<string, SectionGroup>} */
+    const groups = new Map()
+    for (const section of sections) addSectionToGroup(groups, section)
+    const unwrapped = groups.get(UNWRAPPED_KEY)
+    groups.delete(UNWRAPPED_KEY)
+    const wrapped = [...groups.values()]
+    return unwrapped === undefined ? wrapped : [unwrapped, ...wrapped]
+}

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

@@ -0,0 +1,98 @@
+import postcss from 'postcss'
+import { DESKTOP } from './cssTreeUtils.js'
+import { groupSectionsByWrappingAtRules } from './wrappingAtRuleUtils.js'
+
+/** @typedef {import('./copyPlanUtils.js').ThemeCopies} ThemeCopies */
+/** @typedef {import('./wrappingAtRuleUtils.js').Section} Section */
+/** @typedef {import('./wrappingAtRuleUtils.js').SectionGroup} SectionGroup */
+
+/**
+ * @typedef {object} BreakpointCopies
+ * @property {string} breakpoint
+ * @property {import('postcss').Declaration[]} declarations
+ */
+
+export const THEME_COPIES_LAYER = 'origami-theme-copies'
+
+const LEADING_AT_RULES = new Set(['charset', 'import'])
+
+/**
+ * @param {ThemeCopies} themeCopies
+ * @returns {BreakpointCopies[]}
+ */
+const breakpointCopiesOf = themeCopies => {
+    const planned = [...themeCopies].map(([breakpoint, copies]) => ({ breakpoint, declarations: [...copies.values()] }))
+    return planned.filter(({ declarations }) => declarations.length > 0)
+}
+
+/**
+ * @param {string} selector
+ * @param {BreakpointCopies} breakpointCopies
+ * @returns {import('postcss').ChildNode}
+ */
+const breakpointBlockOf = (selector, { breakpoint, declarations }) => {
+    const nodes = declarations.map(declaration => declaration.clone({ important: false, raws: {} }))
+    const rule = postcss.rule({ selector, nodes })
+    if (breakpoint === DESKTOP) return rule
+    return postcss.atRule({ name: 'media', params: breakpoint, nodes: [rule] })
+}
+
+/**
+ * @param {import('postcss').ChildNode[]} nodes
+ * @param {import('postcss').AtRule} wrappingAtRule
+ * @returns {import('postcss').ChildNode[]}
+ */
+const wrapInAtRuleClone = (nodes, wrappingAtRule) => {
+    const clone = wrappingAtRule.clone({ nodes: [] })
+    clone.append(nodes)
+    return [clone]
+}
+
+/**
+ * @param {readonly BreakpointCopies[]} allBreakpointCopies
+ * @param {SectionGroup} group
+ * @returns {import('postcss').ChildNode[]}
+ */
+const groupBlocksOf = (allBreakpointCopies, { wrappingAtRules, selectors }) => {
+    const selector = `:where(${selectors.join(', ')})`
+    const blocks = allBreakpointCopies.map(breakpointCopies => breakpointBlockOf(selector, breakpointCopies))
+    return wrappingAtRules.reduceRight(wrapInAtRuleClone, blocks)
+}
+
+/**
+ * @param {readonly BreakpointCopies[]} allBreakpointCopies
+ * @param {readonly SectionGroup[]} groups
+ */
+const copyLayerOf = (allBreakpointCopies, groups) => {
+    const nodes = groups.flatMap(group => groupBlocksOf(allBreakpointCopies, group))
+    return postcss.atRule({ name: 'layer', params: THEME_COPIES_LAYER, nodes })
+}
+
+/** @param {import('postcss').ChildNode} node */
+const isLeadingAtRule = node => node.type === 'atrule' && LEADING_AT_RULES.has(node.name)
+
+/**
+ * @param {import('postcss').Root} root
+ * @param {import('postcss').AtRule} layer
+ */
+const prependAfterLeadingAtRules = (root, layer) => {
+    const firstOther = root.nodes.find(node => node.type !== 'comment' && !isLeadingAtRule(node))
+    if (firstOther === undefined) {
+        root.append(layer)
+        return
+    }
+    firstOther.before(layer)
+}
+
+/**
+ * @param {import('postcss').Root} root
+ * @param {ThemeCopies} themeCopies
+ * @param {readonly Section[]} sections
+ */
+export const writeCopies = (root, themeCopies, sections) => {
+    const allBreakpointCopies = breakpointCopiesOf(themeCopies)
+    if (allBreakpointCopies.length === 0 || sections.length === 0) return
+    const groups = groupSectionsByWrappingAtRules(sections)
+    const layer = copyLayerOf(allBreakpointCopies, groups)
+    prependAfterLeadingAtRules(root, layer)
+}