@wix/origami-transforms 0.1.15 → 0.1.17

package/dist/cssPlugins/layout/contract.d.ts

@@ -1,5 +1,6 @@
 export const CONTENT: "internal-container-content-wrapper";
 export const OVERFLOW: "internal-container-overflow-wrapper";
+export const DEFAULTS_LAYER: "origami-container-defaults";
 export const targets: Readonly<{
     "internal-container-content-wrapper": Set<string>;
     "internal-container-overflow-wrapper": Set<string>;

package/dist/cssPlugins/shapeDividers.d.ts

@@ -0,0 +1,2 @@
+/** @type {import('../transform/types.js').CssTransformPlugin} */
+export const shapeDividersPlugin: import("../transform/types.js").CssTransformPlugin;

package/dist/cssPlugins/structureFile.d.ts

@@ -2,3 +2,4 @@ export function structureFileOf(stylesheetPath: any): string | undefined;
 export function parseStructure(structurePath: any): any;
 export function walk(node: any, visit: any): void;
 export function literalIdOf(openingElement: any): any;
+export function importsById(structurePath: any): Map<any, any>;

package/dist/cssPlugins/svg.d.ts

@@ -0,0 +1,14 @@
+export function loadSvgs(ids: any): Promise<undefined> | undefined;
+export function loadedSvg(id: any): any;
+export function svgInfo(svg: any): {
+    type: any;
+    viewBox: any;
+    bbox: any;
+};
+export function viewBoxOf({ type, viewBox, bbox }: {
+    type: any;
+    viewBox: any;
+    bbox: any;
+}): any;
+export function scaleSvg(svg: any, info: any, preserveAspectRatio: any): any;
+export function svgDataUrl(svg: any): string;

package/dist/cssPlugins/wixVectorUrls.d.ts

@@ -0,0 +1,2 @@
+/** @type {import('../transform/types.js').CssTransformPlugin} */
+export const wixVectorUrlsPlugin: import("../transform/types.js").CssTransformPlugin;

package/dist/transform/css/postcssPlugin.d.ts

@@ -6,5 +6,5 @@ export function createCssPostcssPlugin({ selectPlugins, contextFor, failures }:
     postcssPlugin: string;
     Once(root: any, { result }: {
         result: any;
-    }): void;
+    }): void | Promise<void>;
 };

package/dist/transform/css/runPlugins.d.ts

@@ -1,3 +1,4 @@
+export function pluginError(plugin: any, context: any, cause: any): Error;
 export function runCssPlugins({ plugins, root, context }: {
     plugins: any;
     root: any;

package/dist/transform/pipeline.d.ts

@@ -23,7 +23,7 @@ export function createTransformPipeline({ layout, jsxPlugins, cssPlugins }: {
         postcssPlugin: string;
         Once(root: any, { result }: {
             result: any;
-        }): void;
+        }): void | Promise<void>;
     };
     babelOptionsFor: (id: any, { ssr }?: {
         ssr?: boolean | undefined;

package/dist/transform/types.d.ts

@@ -64,14 +64,12 @@ export type JsxTransformPlugin = TransformPluginBase & {
     parserPlugins?: readonly string[];
 };
 /**
- * The transform-plugin contract.
- *
- * Both stages have the same shape: an engine parses the file once, and each plugin is handed that
- * AST plus the file's context and does what it likes with it. Babel and PostCSS are engines here,
- * not plugin hosts — a plugin never has to know either one's own plugin protocol. Which stage a
- * plugin belongs to is decided by the list it is registered in, so no descriptor restates it.
+ * `prepare` loads what the plugin needs that can't be read synchronously, such as a file from a CDN, before any
+ * plugin's `validate` or `transform` runs. It returns a promise only when it has something to load, so a stylesheet
+ * that needs nothing loaded stays synchronous for PostCSS.
  */
 export type CssTransformPlugin = TransformPluginBase & {
+    prepare?: (root: import("postcss").Root, context: CssTransformContext) => Promise<void> | void;
     validate?: (root: import("postcss").Root, context: CssTransformContext) => void;
     transform: (root: import("postcss").Root, context: CssTransformContext) => void;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/origami-transforms",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "Babel and PostCSS checks and transforms for Wix origami page files.",
   "main": "./src/index.js",
   "files": [
@@ -18,7 +18,7 @@
     "@babel/parser": "^7.25.0",
     "@babel/types": "^7.25.2",
     "@wix/origami-fonts": "1.0.1",
-    "@wix/origami-system-components": "1.9.0",
+    "@wix/origami-system-components": "1.10.0",
     "postcss": "^8.5.3",
     "postcss-custom-media": "^12.0.1"
   },
@@ -64,5 +64,5 @@
   },
   "type": "module",
   "types": "./dist/index.d.ts",
-  "falconPackageHash": "08fa24b6d989c88b62d43cea5a959c50ee2a2212bc6cb279ecf53dc1"
+  "falconPackageHash": "7fd53a47a2a80ee2e831d1b608e15378825592abfb78d94393377d13"
 }

package/src/cssPlugins/customEnums.js

@@ -15,12 +15,10 @@ import { createRequire } from 'node:module'
 import { basename, dirname, join } from 'node:path'
 import postcss from 'postcss'
 import { LayoutError } from '../transform/layoutError.js'
-import { WRAPPERS_SCOPE, wrapperImport } from '../wrapperImport.js'
-import { literalIdOf, parseStructure, structureFileOf, walk } from './structureFile.js'
+import { wrapperImport } from '../wrapperImport.js'
+import { importsById, structureFileOf } from './structureFile.js'
 
 const CUSTOM_ENUMS_CSS = 'custom-enums.css'
-// `@origami-wrappers/<module>/<symbol>`, and nothing that could resolve outside its package.
-const WRAPPER_IMPORT = new RegExp(`^${WRAPPERS_SCOPE}/[\\w-]+/[\\w-]+$`)
 // A component type, `wixEditorElements.Button`: its module and symbol.
 const COMPONENT_TYPE = /^([\w-]+)\.([\w-]+)$/
 /** The selector's compounds, split at its combinators, outside parentheses and brackets. */
@@ -59,24 +57,6 @@ const lastMatch = (element, compounds) => {
     return -1
 }
 
-/** Id → the wrapper import it is rendered from, for elements with a literal `id` and an imported wrapper tag. */
-const importsById = structurePath => {
-    const program = parseStructure(structurePath)
-    const sources = new Map()
-    for (const node of program?.body ?? []) {
-        if (node.type !== 'ImportDeclaration' || !WRAPPER_IMPORT.test(node.source.value)) continue
-        for (const specifier of node.specifiers) sources.set(specifier.local.name, node.source.value)
-    }
-    const byId = new Map()
-    walk(program, node => {
-        if (node.type !== 'JSXOpeningElement' || node.name.type !== 'JSXIdentifier') return
-        const id = literalIdOf(node)
-        const source = sources.get(node.name.name)
-        if (id !== undefined && source !== undefined) byId.set(id, source)
-    })
-    return byId
-}
-
 /** A path with its symlinks resolved, so a wrapper reached through a package manager's links matches its folder. */
 const real = path => {
     try {

package/src/cssPlugins/index.js

@@ -12,6 +12,8 @@
 // and layout move declarations out of the instance's rule. fonts appends the `@font-face` rules that load the Wix fonts
 // the stylesheet names from Wix's CDN.
 // component-position runs after mixins, so a position a mixin body sets is kept, and before layout compiles the rules.
+// shape-dividers and wix-vector-urls run last: they load the SVGs a stylesheet names from Wix's CDN in `prepare`, and
+// write them in as data URIs.
 //
 // `@layer` needs no plugin: cascade layers have been in every browser since March 2022.
 
@@ -21,9 +23,11 @@ import { customMediaPlugin } from './customMedia.js'
 import { fontsPlugin } from './fonts.js'
 import { mixinsPlugin } from './mixins.js'
 import { presetsPlugin } from './presets.js'
+import { shapeDividersPlugin } from './shapeDividers.js'
 import { layoutPlugin } from './layout/index.js'
 import { spxPlugin } from './spx/index.js'
 import { stackChildrenPlugin } from './stackChildren.js'
+import { wixVectorUrlsPlugin } from './wixVectorUrls.js'
 
 /** @type {readonly import('../transform/types.js').CssTransformPlugin[]} */
 export const cssPlugins = Object.freeze([
@@ -36,4 +40,6 @@ export const cssPlugins = Object.freeze([
     componentPositionPlugin,
     layoutPlugin,
     spxPlugin,
+    shapeDividersPlugin,
+    wixVectorUrlsPlugin,
 ])

package/src/cssPlugins/layout/README.md

@@ -32,15 +32,21 @@ the outer element.
 ## What the plugin adds
 
 The outer element and overflow wrapper get a one-cell grid so the wrappers fill
-the container. The content wrapper gets sizing and positioning styles, including
-a maximum width and left, center or right alignment. It lets pointer events pass
-through empty space while its children remain clickable.
-
-Each container starts with no content width limit and centered alignment. These
-defaults live in a separate CSS layer so authored settings can override them.
-Media queries, scopes and other surrounding conditions still apply to generated
-rules. Vertical overflow also sets `--sticky-offset` to `0px` for `scroll` and
-resets it for other values.
+the container. The content wrapper lets pointer events pass through empty space
+while its children stay clickable. Vertical overflow also sets `--sticky-offset`
+to `0px` for `scroll` and resets it for other values.
+
+Each container's alignment defaults to center in a separate first CSS layer, so
+authored values always win. Media queries and scopes around a rule still apply.
+
+### Content max width
+
+Where DM writes `--content-max-width` (usually a section's content wrapper), the
+plugin adds `max-width` and an alignment `margin-left` next to it, and nowhere else.
+
+- Those two properties do not inherit, so nested containers are not boxed in.
+- `--content-max-width` does inherit, so nested containers use it as their SPX cap
+  (see the SPX plugin README). With none above, SPX is uncapped.
 
 ## Why validation runs before transformations
 

package/src/cssPlugins/layout/compiler.js

@@ -1,9 +1,11 @@
 import postcss from 'postcss'
 import { buildContainerClasses } from '@wix/origami-system-components/layout-contract'
-import { CONTENT } from './contract.js'
+import { CONTENT, DEFAULTS_LAYER } from './contract.js'
 import { isLayoutSource, parseTargets } from './parser.js'
 
 const grid = { display: 'grid', 'grid-template-rows': '1fr', 'grid-template-columns': 'minmax(0, 1fr)' }
+const contentMargin =
+    'clamp(0px, (100% - var(--content-max-width)) * var(--origami-content-align), 100 * var(--one-unit, 1%))'
 
 /** Preserve source locations on every emitted declaration and selector. */
 const ruleFor = (owner, selector, declarations) => {
@@ -21,12 +23,12 @@ const ruleFor = (owner, selector, declarations) => {
 export const compileContainers = (root, context) => {
     const owners = parseTargets(root, context)
     if (!owners.size) return
-    // Thunderbolt writes max-width and margin-left directly; neither property inherits.
-    // We use custom properties so width and alignment can change independently at breakpoints.
-    // Those do inherit, so each container needs defaults to avoid taking its parent's settings.
+    // max-width and margin-left are written only where a content max width is set.
+    // Alignment is a custom property so it can change independently at breakpoints.
+    // That inherits, so each container needs a default to avoid taking its parent's alignment.
     // This first layer keeps defaults weaker than authored rules, including rules in later layers.
     // Clone only conditional/scope envelopes into it so the defaults apply under the same conditions.
-    const defaultsLayer = postcss.atRule({ name: 'layer', params: 'origami-container-defaults' })
+    const defaultsLayer = postcss.atRule({ name: 'layer', params: DEFAULTS_LAYER })
     if (root.source) defaultsLayer.source = root.source
     root.prepend(defaultsLayer)
     // Source identity prevents a matching selector in another carrier from becoming an owner.
@@ -64,10 +66,7 @@ export const compileContainers = (root, context) => {
                 defaultsParent = clone
             }
             defaultsParent.append(
-                ruleFor(owner, `:where(${content})`, {
-                    '--content-max-width': 'none',
-                    '--origami-content-align': '0.5',
-                })
+                ruleFor(owner, `:where(${content})`, { '--origami-content-align': '0.5' })
             )
             owner.before(ruleFor(owner, selector, grid))
             owner.before(ruleFor(owner, overflow, { ...grid, position: 'relative', 'align-self': 'stretch' }))
@@ -76,10 +75,6 @@ export const compileContainers = (root, context) => {
                     'box-sizing': 'border-box',
                     position: 'relative',
                     'pointer-events': 'none',
-                    'max-width': 'var(--content-max-width)',
-                    '--section-max-width': 'var(--content-max-width)',
-                    'margin-left':
-                        'clamp(0px, (100% - var(--content-max-width, 100%)) * var(--origami-content-align), 100 * var(--one-unit, 1%))',
                 })
             )
             owner.before(ruleFor(owner, `${content} > *`, { 'pointer-events': 'auto' }))
@@ -98,6 +93,11 @@ export const compileContainers = (root, context) => {
                         // Left margin uses none, half or all of the extra space to align the content.
                         clone.value = { left: '0', center: '0.5', right: '1' }[clone.value]
                     }
+                    if (clone.prop === '--content-max-width')
+                        generated.append(
+                            clone.clone({ prop: 'max-width', value: 'var(--content-max-width)' }),
+                            clone.clone({ prop: 'margin-left', value: contentMargin })
+                        )
                     if (clone.prop === 'overflow-y')
                         generated.append(
                             clone.clone({

package/src/cssPlugins/layout/contract.js

@@ -2,6 +2,7 @@
 // Consumer routing only: component eligibility is validated by DM against JSX.
 export const CONTENT = 'internal-container-content-wrapper'
 export const OVERFLOW = 'internal-container-overflow-wrapper'
+export const DEFAULTS_LAYER = 'origami-container-defaults'
 export const targets = Object.freeze({
     [CONTENT]: new Set([
         'position',

package/src/cssPlugins/shapeDividers.js

@@ -0,0 +1,136 @@
+// Draws the shape divider. A site sets only a BackgroundShapeDivider's vars (`--svgId`, `--side`, `--color`,
+// `--repeats`, …); its wrapper's CSS paints each `[data-divider-layer]` from vars nothing sets, so the divider
+// stays empty. A live Wix site writes one more rule per instance, from the divider's SVG
+// (Thunderbolt's `SVGBackgroundImage` feature, keyed on the same component type); this writes the same rule after
+// each instance rule that sets a divider var, in the same place, from the instance's base vars and that rule's.
+// The color is written into the SVG, so a `--color` that is a var stays unresolved there.
+
+import postcss from 'postcss'
+import { wrapperImport } from '../wrapperImport.js'
+import { loadedSvg, loadSvgs, scaleSvg, svgDataUrl, svgInfo, viewBoxOf } from './svg.js'
+import { importsById, structureFileOf } from './structureFile.js'
+
+const SHAPE_DIVIDER_IMPORT = wrapperImport({ module: 'wixSystemElements', symbol: 'BackgroundShapeDivider' })
+const LAYER = '[data-divider-layer]'
+const DIVIDER_VARS = ['--svgId', '--side', '--color', '--invert', '--keepAspectRatio', '--repeats', '--flip', '--layerPinFactor']
+// One class or id: DM writes `.compId`.
+const SINGLE_CLASS_OR_ID = /^[.#]([\w-]+)$/
+// Closes the hairline Safari draws between the inverted path and its frame.
+const HAIRLINE_FIX_FACTOR = 1
+
+/** `--svgId`'s file id, `"0da768_….svg"` unquoted; '' for the `""` that turns the divider off. */
+const svgIdOf = value => value.trim().replace(/^(['"])(.*)\1$/, '$2')
+
+/** The instance rules that set a divider var: `.compId { … }`, at the top level or in an at-rule. */
+const instanceRules = (root, dividerIds) => {
+    const rules = []
+    root.walkRules(rule => {
+        const id = rule.selector.match(SINGLE_CLASS_OR_ID)?.[1]
+        if (id === undefined || !dividerIds.has(id)) return
+        const vars = {}
+        for (const node of rule.nodes) if (node.type === 'decl' && DIVIDER_VARS.includes(node.prop)) vars[node.prop] = node.value.trim()
+        if (Object.keys(vars).length) rules.push({ rule, id, vars, base: rule.parent?.type === 'root' })
+    })
+    return rules
+}
+
+/** The divider's ids in the stylesheet's structure file. */
+const dividerIdsOf = (filePath, context) => {
+    const structurePath = filePath === undefined ? undefined : structureFileOf(filePath)
+    if (structurePath === undefined) return new Set()
+    context.addDependency?.(structurePath)
+    return new Set([...importsById(structurePath)].filter(([, source]) => source === SHAPE_DIVIDER_IMPORT).map(([id]) => id))
+}
+
+/** The path filled outside its shape, closing it with the frame of its box; Thunderbolt's `invertSvgContent`. */
+const invertSvg = (svg, x, y, width, height) => {
+    const pathTag = svg.match(/(<path)[^>]*>/)?.[1] || ''
+    const pathData = svg.match(/<path.*\s*d="([^"]+)"/)?.[1] || ''
+    const frame = `M${x},${y - HAIRLINE_FIX_FACTOR} h${width} v${height + HAIRLINE_FIX_FACTOR} h${-width} Z`
+    return svg.replace(pathData, `${pathData} ${frame}`).replace(pathTag, `${pathTag} fill-rule="evenodd"`)
+}
+
+/** The SVG with its id set, colored, inverted when asked, and sized to fill the layer; Thunderbolt's `getBackgroundProps`.
+ * Undefined for an SVG with no box to size it by. */
+const dividerSvg = (svg, { id, color, invert, aspectRatio }) => {
+    const info = svgInfo(svg)
+    const [x, y, width, height] = viewBoxOf(info).trim().split(/[\s,]+/).map(Number.parseFloat)
+    if (![x, y, width, height].every(Number.isFinite)) return undefined
+    let content = scaleSvg(svg, { ...info, viewBox: `${x} ${y} ${width} ${height}`, bbox: `${x} ${y} ${width} ${height}` }, aspectRatio)
+        .replace(/^(.*\s*)<svg/, '<svg')
+        .replace(/<\/svg>(\s*)$/, '</svg>')
+    if (invert) content = invertSvg(content, x, y, width, height)
+    const idMatch = content.match(/<svg[^>]*>/)[0].match(/id="[-\w]+"/)
+    content = idMatch ? content.replace(idMatch[0], `id="${id}"`) : content.replace('<svg ', `<svg id="${id}" `)
+    const inverting = invert ? `#${id} > g { transform: scaleY(-1) translateY(${-(2 * y + height)}px); } ` : ''
+    const coloring = info.type === 'color' && !/data-color="2"/.test(svg) ? `, #${id} [data-color="1"] ` : ''
+    content = content.replace(/(<svg[^>]*>)/, `$1<defs><style>${inverting}#${id}${coloring} { fill: ${color}; }</style></defs>`)
+    content = content
+        .replace(/(<svg[^>]*\s)width="[^"]*"/, '$1width="100%"')
+        .replace(/(<svg[^>]*\s)height="[^"]*"/, '$1height="100%"')
+    if (!/<svg[^>]*\swidth="/.test(content)) content = content.replace(/(<svg[^>]*)(>)/, `$1 width="${width.toFixed(2)}"$2`)
+    if (!/<svg[^>]*\sheight="/.test(content)) content = content.replace(/(<svg[^>]*)(>)/, `$1 height="${height.toFixed(2)}"$2`)
+    return { image: svgDataUrl(content), width, height }
+}
+
+/** The `[data-divider-layer]` declarations for an instance's vars, or undefined when its SVG isn't loaded or has no box. */
+const layerDeclarations = (compId, vars) => {
+    const svgId = svgIdOf(vars['--svgId'] ?? '')
+    if (vars['--svgId'] !== undefined && svgId === '') return { 'background-image': 'none' }
+    const svg = svgId && loadedSvg(svgId)
+    if (!svg) return undefined
+    const side = vars['--side'] === 'top' ? 'top' : 'bottom'
+    const keepAspectRatio = vars['--keepAspectRatio'] !== 'stretch'
+    const repeats = vars['--repeats'] === undefined ? 1 : Number.parseInt(vars['--repeats'], 10)
+    const drawn = dividerSvg(svg, {
+        id: `${compId}-${side}`,
+        color: vars['--color'] || '#000',
+        invert: vars['--invert'] === 'invert',
+        aspectRatio: keepAspectRatio ? (repeats !== 0 ? 'xMinYMax meet' : 'xMidYMax slice') : 'none',
+    })
+    if (drawn === undefined) return undefined
+    const { image, width, height } = drawn
+    const size = keepAspectRatio ? `calc(${width} * var(--height) / ${height})` : `${((1 / (repeats + 1)) * 100).toFixed(2)}%`
+    const pinFactor = { out: '1', in: '-1' }[vars['--layerPinFactor']] ?? '0'
+    return {
+        'background-image': image,
+        'background-size': `${size} 100%`,
+        ...(side === 'top' ? { top: '0', '--scaleY': '-1', '--side-flip': '-1' } : { bottom: '0', '--scaleY': '1', '--side-flip': '1' }),
+        '--divider-flip': vars['--flip'] === 'flip' ? '-1' : '1',
+        '--divider-layers-pin-factor': pinFactor,
+    }
+}
+
+/** @type {import('../transform/types.js').CssTransformPlugin} */
+export const shapeDividersPlugin = {
+    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.
+    order: 25,
+    prepare(root) {
+        const ids = new Set()
+        root.walkDecls('--svgId', declaration => {
+            const id = svgIdOf(declaration.value)
+            if (id) ids.add(id)
+        })
+        return loadSvgs(ids)
+    },
+    transform(root, context) {
+        const dividerIds = dividerIdsOf(context.filePath, context)
+        if (!dividerIds.size) return
+        const rules = instanceRules(root, dividerIds)
+        const baseVars = new Map()
+        for (const { id, vars, base } of rules) if (base) baseVars.set(id, { ...baseVars.get(id), ...vars })
+        for (const { rule, id, vars } of rules) {
+            const allVars = { ...baseVars.get(id), ...vars }
+            const declarations = layerDeclarations(id, allVars)
+            if (declarations === undefined) {
+                if (allVars['--svgId']) context.warn?.(rule, `Couldn't draw the shape divider's SVG ${allVars['--svgId']}: it didn't load from Wix's CDN, or has no view box`)
+                continue
+            }
+            const layerRule = postcss.rule({ selector: `${rule.selector} ${LAYER}`, source: rule.source })
+            for (const [prop, value] of Object.entries(declarations)) layerRule.append({ prop, value, source: rule.source })
+            rule.after(layerRule)
+        }
+    },
+}

package/src/cssPlugins/spx/README.md

@@ -29,13 +29,21 @@ styles onto their runtime wrappers; this plugin then converts every `--spx(numbe
 In scale mode, the size is approximately:
 
 ```text
-number × (scaling-factor − scrollbar-width) / spx-ref-width
+number × (clamp(spx-stopper-min, scaling-factor, min(spx-stopper-max, content-max-width)) − scrollbar-width) / spx-ref-width
 ```
 
+This matches DM's `--spx()` in the `theme.css` preamble.
+
+- **Stoppers:** DM writes them inside `@layer spx-preamble`, so the viewer's unlayered global CSS
+  values (`0px` / `9999px`) win.
+- **Cap:** `--content-max-width`, set by DM on each section's content wrapper and inherited by its
+  descendants. With none above, the cap is 99999px. A `--content-max-width` that uses `--spx()` is
+  compiled without the cap, since a custom property can't read itself.
+
 Nonzero scaled values have a minimum magnitude of 0.5px, preserving their sign.
 In fixed mode, the number is a pixel value, including fractional pixels. Zero stays zero.
 
-The plugin keeps reference width, scaling factor and scrollbar width as `var()` reads
+The plugin keeps reference width, scaling factor, scrollbar width and stoppers as `var()` reads
 inside each expression. It translates `--spx-resolver-type: scale` to a private numeric
 switch of 1, and `fixed` to 0. That switch selects scaled lengths or fixed pixels using
 ordinary CSS arithmetic, without requiring CSS custom functions or style queries.
@@ -53,9 +61,9 @@ own effective settings. No per-container SPX reset is needed.
 
 Existing preamble declarations remain in CSS and participate in the normal cascade.
 When settings are absent, expressions fall back to reference width 1280, scale mode,
-viewport width 100vw and scrollbar width 0px. Nested components inherit settings unless
-they override them. As with any CSS custom property, an authored token containing an
-SPX expression resolves where the token is declared; inheriting the token does not
+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.
 
 ## Files and boundaries
@@ -65,9 +73,8 @@ re-evaluate it using a child's settings.
 - `calls.js` parses literal numeric SPX calls and rejects unsupported arguments.
 
 Reference widths must be positive numbers and resolver modes must be `scale` or `fixed`.
-SPX stopper clamping is still outside this plugin: it uses the effective
-`--scaling-factor` supplied by CSS and does not generate Thunderbolt's clamp formula.
+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 and zero.
+settings in separate stylesheets, cascade priority, fixed fractions, signs, zero, stoppers and cap.
 Run it together with the container browser checks using the package's `test:browser` script.

package/src/cssPlugins/spx/cascade.js

@@ -3,8 +3,12 @@ import { lowerCalls } 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 UNIT = `(${SCALE} * (var(--scaling-factor, 100vw) - var(--scrollbar-width, 0px)) / var(--spx-ref-width, 1280) + (1 - ${SCALE}) * 1px)`
 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)`
+const UNIT = unitCappedAt('var(--content-max-width, 99999px)')
+const UNCAPPED_UNIT = unitCappedAt('99999px')
 
 /** Compile settings and calls in place, retaining their cascade and source locations.
  * @param {import('postcss').Declaration} declaration
@@ -30,11 +34,12 @@ export const compileCascadeDeclaration = declaration => {
     ) {
         throw declaration.error('SPX reference width must be positive')
     }
+    const unit = declaration.prop === '--content-max-width' ? UNCAPPED_UNIT : UNIT
     lowerCalls(
         declaration,
         number => {
             if (number === 0) return '0px'
-            return number < 0 ? `min(calc(-1 * ${FLOOR}), ${number} * ${UNIT})` : `max(${FLOOR}, ${number} * ${UNIT})`
+            return number < 0 ? `min(calc(-1 * ${FLOOR}), ${number} * ${unit})` : `max(${FLOOR}, ${number} * ${unit})`
         },
         () => declaration.error('SPX calls --spx() with a non-literal argument')
     )

package/src/cssPlugins/structureFile.js

@@ -5,9 +5,12 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { basename, dirname, join } from 'node:path'
 import { parseSync } from '@babel/core'
+import { WRAPPERS_SCOPE } from '../wrapperImport.js'
 
 const STRUCTURE_FILES = ['structure.tsx', 'structure.jsx']
 const GENERATED = '_generated'
+// `@origami-wrappers/<module>/<symbol>`, and nothing that could resolve outside its package.
+const WRAPPER_IMPORT = new RegExp(`^${WRAPPERS_SCOPE}/[\\w-]+/[\\w-]+$`)
 
 /** The structure file `stylesheetPath` is checked against, or undefined when its item has none. */
 export const structureFileOf = stylesheetPath => {
@@ -41,3 +44,21 @@ export const literalIdOf = openingElement =>
         attribute =>
             attribute.type === 'JSXAttribute' && attribute.name.name === 'id' && attribute.value?.type === 'StringLiteral'
     )?.value.value
+
+/** Id → the wrapper import it is rendered from, for elements with a literal `id` and an imported wrapper tag. */
+export const importsById = structurePath => {
+    const program = parseStructure(structurePath)
+    const sources = new Map()
+    for (const node of program?.body ?? []) {
+        if (node.type !== 'ImportDeclaration' || !WRAPPER_IMPORT.test(node.source.value)) continue
+        for (const specifier of node.specifiers) sources.set(specifier.local.name, node.source.value)
+    }
+    const byId = new Map()
+    walk(program, node => {
+        if (node.type !== 'JSXOpeningElement' || node.name.type !== 'JSXIdentifier') return
+        const id = literalIdOf(node)
+        const source = sources.get(node.name.name)
+        if (id !== undefined && source !== undefined) byId.set(id, source)
+    })
+    return byId
+}

package/src/cssPlugins/svg.js

@@ -0,0 +1,87 @@
+// The vector art a site's CSS names by id (`0da768_67d39d1bdd9c48cc96409e0810c6144a.svg`): loading it from Wix's CDN,
+// and the edits Thunderbolt makes before it inlines one as a data URI (thunderbolt-commons' `vectorImage`). A CSS
+// plugin loads the ids it needs in `prepare`, then reads them with `loadedSvg` in its sync `transform`.
+
+const SHAPES_URL = 'https://static.wixstatic.com/shapes/'
+const FETCH_TIMEOUT_MS = 10_000
+const SVG_TAG = /(<svg[^>]*)(>)/
+
+/** id → the SVG's markup, or null when the CDN has no SVG under it. Vector art never changes under its id. A load
+ * the network failed is tried again next run. */
+const loaded = new Map()
+/** id → its pending load. */
+const loading = new Map()
+
+/** The id as the CDN names the file, with its `.svg`. */
+const svgFileName = id => (id.endsWith('.svg') ? id : `${id}.svg`)
+
+const load = async id => {
+    try {
+        const response = await fetch(SHAPES_URL + svgFileName(id), { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) })
+        const svg = response.ok ? await response.text() : ''
+        loaded.set(id, SVG_TAG.test(svg) ? svg : null)
+    } catch {
+        // Not loaded: the plugin warns and keeps the value as written.
+    }
+}
+
+/** Loads the SVGs of `ids` that aren't loaded yet. */
+export const loadSvgs = ids => {
+    const pending = [...ids]
+        .filter(id => !loaded.has(id))
+        .map(id => {
+            if (!loading.has(id)) loading.set(id, load(id).finally(() => loading.delete(id)))
+            return loading.get(id)
+        })
+    return pending.length ? Promise.all(pending).then(() => undefined) : undefined
+}
+
+/** The SVG's markup, once `loadSvgs` loaded it. */
+export const loadedSvg = id => loaded.get(id) ?? undefined
+
+const VIEW_BOX = /(viewBox=")([^"]*)(")/i
+const PRESERVE_ASPECT_RATIO = /(preserveAspectRatio=")([^"]*)(")/i
+const attribute = (tag, name) => tag.match(new RegExp(`\\s${name}="([^"]*)"`))?.[1]
+
+/** What Thunderbolt's svgParser reads from the `<svg>` tag: its type, view box and the drawing's box. */
+export const svgInfo = svg => {
+    const tag = svg.match(SVG_TAG)?.[0] ?? ''
+    const type = attribute(tag, 'data-type') ?? 'shape'
+    const width = attribute(tag, 'width')
+    const height = attribute(tag, 'height')
+    const viewBox = attribute(tag, 'viewBox') ?? (type === 'ugc' && width && height ? `0 0 ${width} ${height}` : '')
+    return { type, viewBox, bbox: attribute(tag, 'data-bbox') ?? '' }
+}
+
+/** The box the art is drawn in: the drawing's own box, except for an uploaded SVG (ugc). */
+export const viewBoxOf = ({ type, viewBox, bbox }) => (type !== 'ugc' && bbox ? bbox : viewBox)
+
+/** The SVG fit to the box `viewBoxOf` gives, with `preserveAspectRatio`; Thunderbolt's `getScaledSvgViewBox`. */
+export const scaleSvg = (svg, info, preserveAspectRatio) => {
+    const tag = svg.match(SVG_TAG)?.[0]
+    if (tag === undefined) return svg
+    svg = PRESERVE_ASPECT_RATIO.test(tag)
+        ? svg.replace(tag, tag.replace(PRESERVE_ASPECT_RATIO, `$1${preserveAspectRatio}$3`))
+        : svg.replace(/<svg/, `<svg preserveAspectRatio="${preserveAspectRatio}"`)
+    if (!VIEW_BOX.test(tag)) {
+        if (info.type === 'ugc' && info.viewBox) svg = svg.replace(/<svg/, `<svg viewBox="${info.viewBox}"`)
+        if (info.type !== 'ugc' && info.bbox) svg = svg.replace(/<svg/, `<svg viewBox="${info.bbox}"`)
+    }
+    if (info.type !== 'ugc' && info.bbox) {
+        const scaledTag = svg.match(SVG_TAG)[0]
+        svg = svg.replace(scaledTag, scaledTag.replace(VIEW_BOX, `$1${info.bbox}$3`))
+    }
+    return svg
+}
+
+const URL_SYMBOLS = /[\r\n%#()<>?[\\\]^`{|}]/g
+
+/** The SVG as a CSS `url()` of a data URI, encoded as Thunderbolt's `encodeSVG` does. */
+export const svgDataUrl = svg => {
+    const escaped = svg
+        .replace(/"/g, "'")
+        .replace(/>\s+</g, '><')
+        .replace(/\s{2,}/g, ' ')
+        .replace(URL_SYMBOLS, encodeURIComponent)
+    return `url("data:image/svg+xml,${escaped}")`
+}

package/src/cssPlugins/wixVectorUrls.js

@@ -0,0 +1,39 @@
+// Inlines the vector art a value names with Wix's own url scheme, `url(wix:vector://v1/<id>.svg)`, which no browser
+// can load: Image's `--maskImage`, for one. A live Wix site writes it as a data URI of the SVG stretched to its
+// drawing's box (Thunderbolt's `replaceWixUrl` and `createSvgCssVar`); this writes the same data URI in its place.
+// An SVG that can't be loaded stays as written, with a warning.
+
+import { loadedSvg, loadSvgs, scaleSvg, svgDataUrl, svgInfo } from './svg.js'
+
+const WIX_VECTOR_URL = /url\(\s*(['"]?)wix:vector:\/\/v1\/([^'")\s]+)\1\s*\)/gi
+const HAS_WIX_VECTOR_URL = /wix:vector:\/\//i
+
+/** The ids every `wix:vector` url in the stylesheet names. */
+const idsIn = root => {
+    const ids = new Set()
+    root.walkDecls(declaration => {
+        for (const [, , id] of declaration.value.matchAll(WIX_VECTOR_URL)) ids.add(id)
+    })
+    return ids
+}
+
+/** @type {import('../transform/types.js').CssTransformPlugin} */
+export const wixVectorUrlsPlugin = {
+    name: 'wix-vector-urls',
+    // Last, so a url a mixin or preset copies elsewhere is inlined wherever it ends up.
+    order: 25,
+    prepare: root => loadSvgs(idsIn(root)),
+    transform(root, context) {
+        root.walkDecls(declaration => {
+            if (!HAS_WIX_VECTOR_URL.test(declaration.value)) return
+            declaration.value = declaration.value.replace(WIX_VECTOR_URL, (url, _quote, id) => {
+                const svg = loadedSvg(id)
+                if (svg === undefined) {
+                    context.warn?.(declaration, `Couldn't load the SVG ${id} from Wix's CDN, so ${url} stays as written`)
+                    return url
+                }
+                return svgDataUrl(scaleSvg(svg, svgInfo(svg), 'none'))
+            })
+        })
+    },
+}

package/src/transform/css/postcssPlugin.js

@@ -9,7 +9,7 @@
 // depends on it in another arrive in the same document.
 
 import { removeCustomEnums } from '../../cssPlugins/customEnums.js'
-import { runCssPlugins } from './runPlugins.js'
+import { pluginError, runCssPlugins } from './runPlugins.js'
 
 const DEPENDENCY_DIRECTORY = 'node_modules/'
 
@@ -55,12 +55,28 @@ export const createCssPostcssPlugin = ({ selectPlugins, contextFor, failures })
         // A plugin reports a problem that need not stop the build as a PostCSS warning, which Vite prints with the
         // node's code frame.
         const warn = (node, text) => node.warn(result, text)
-        try {
-            runCssPlugins({ plugins, root, context: { ...fileContext, addDependency, warn } })
-            failures?.delete(from)
-        } catch (error) {
+        const context = { ...fileContext, addDependency, warn }
+        const fail = error => {
             failures?.set(from, declared)
             throw error
         }
+        const run = () => {
+            try {
+                runCssPlugins({ plugins, root, context })
+                failures?.delete(from)
+            } catch (error) {
+                fail(error)
+            }
+        }
+        // PostCSS awaits the hook only when it returns a promise; a stylesheet nothing loads for stays synchronous.
+        const loading = plugins.flatMap(plugin => {
+            try {
+                const prepared = plugin.prepare?.(root, context)
+                return prepared ? [prepared.catch(cause => fail(pluginError(plugin, context, cause)))] : []
+            } catch (cause) {
+                return fail(pluginError(plugin, context, cause))
+            }
+        })
+        return loading.length ? Promise.all(loading).then(run) : run()
     },
 })

package/src/transform/css/runPlugins.js

@@ -9,6 +9,14 @@ import { LayoutError } from '../layoutError.js'
 
 const reason = cause => (cause instanceof Error ? cause.message : String(cause))
 
+/** A plugin's failure, in `prepare` or a phase, attributed to the plugin and the file. */
+export const pluginError = (plugin, context, cause) =>
+    // Tooling such as Vite's error overlay prints only the message, so the reason goes in it as well. A
+    // plugin may throw any value, so it is read without assuming an Error.
+    new Error(`CSS transform "${plugin.name}" failed for ${context.relativePath ?? context.filePath}: ${reason(cause)}`, {
+        cause,
+    })
+
 export const runCssPlugins = ({ plugins, root, context }) => {
     /** @type {LayoutError[]} */
     const layoutErrors = []
@@ -21,12 +29,7 @@ export const runCssPlugins = ({ plugins, root, context }) => {
                     layoutErrors.push(cause)
                     continue
                 }
-                // Tooling such as Vite's error overlay prints only the message, so the reason goes in it as well. A
-                // plugin may throw any value, so it is read without assuming an Error.
-                throw new Error(
-                    `CSS transform "${plugin.name}" failed for ${context.relativePath ?? context.filePath}: ${reason(cause)}`,
-                    { cause }
-                )
+                throw pluginError(plugin, context, cause)
             }
         }
     }

package/src/transform/types.js

@@ -36,9 +36,13 @@
  * and applied before any of them run.
  *
  * @typedef {TransformPluginBase & {
+ *     prepare?: (root: import('postcss').Root, context: CssTransformContext) => Promise<void> | void,
  *     validate?: (root: import('postcss').Root, context: CssTransformContext) => void,
  *     transform: (root: import('postcss').Root, context: CssTransformContext) => void
  * }} CssTransformPlugin
+ * `prepare` loads what the plugin needs that can't be read synchronously, such as a file from a CDN, before any
+ * plugin's `validate` or `transform` runs. It returns a promise only when it has something to load, so a stylesheet
+ * that needs nothing loaded stays synchronous for PostCSS.
  *
  * @typedef {TransformContext & {
  *     addDependency?: (file: string) => void,