@wix/origami-site-runtime 1.0.0

package/README.md

@@ -0,0 +1,79 @@
+# Wix import site runtime
+
+Static routes come from item folders under `src/pages`. The home page is the page folder in parentheses, e.g. `src/pages/(home)`; a folder in parentheses is left out of the URL. Each document loads its item's `_generated/index.jsx`; `pages/error404` supplies an optional custom 404 page.
+
+## Routing roadmap
+
+**Popups:** They arrive through the pages API, live at `src/popups/<slug>`, and will open via `?popup=` in their own root, like piler's `site-express-export/mountPopup.js`.
+
+**Static-dynamic pages:** A folder with `route.json` will be an app's URL prefix. Literal child folders are fixed pages under it and remain static.
+
+**Dynamic pages:** A `[param]` child will be resolved per request. A production Node server and the dev middleware will call the router service, reusing `routeToDynamicPage` from `@wix/builder-utils`, and inject `__WIX_RUNTIME_SERVICES_CONFIGS__` before the page entry, like piler's `site-express-export/server.js.ejs`. `RouteTable` already declares these types.
+
+## Layout CSS
+
+Vite serve/build compiles DM JSX era 0.42 InternalContainer semantic layout in memory.
+Caller-supplied plugin lists replace the built-in ones.
+The original layout.css, format version and unmapped.json remain available for import-back.
+Legacy flat layout and other components are not converted into semantic layout.
+
+The default order is custom media → mixins → semantic container → SPX. Selected plugins
+may expose `validate(root, context)`; all validators run before any transform so a mixin
+cannot hide an illegally placed target. Diagnostics retain the original node source.
+
+## Container contract
+
+`@origami-target internal-container-content-wrapper` routes to
+`#id > .id-overflow-wrapper > .id-container`; `internal-container-overflow-wrapper`
+routes to `#id > .id-overflow-wrapper`. Names come from the pure
+`@wix/origami-react-runtime/layout-contract` entry point. Root sizing, item placement, visibility
+and ordinary positioning remain on the ID selector. Background, border and pinned-layer
+CSS stays in the snapshot; the maintained component preserves focus and wrapper flags. Ref support is deferred
+(see the [runtime decision](../origami-runtime/README.md#decision-defer-ref-support-2026-09-24)).
+
+Only explicit targets in site-owned layout.css carriers opt in. Sources of inlined nodes
+are checked too, including dependency CSS. Targets in style/global-style CSS, mixins,
+unknown layers or malformed bodies fail with source diagnostics. CSS discovery does not
+prove the component's JSX type; DM owns that eligibility check.
+
+Content accepts DM grid/flex vocabulary (including stack and organizer), structural relative
+positioning, padding, gaps and content max-width/alignment. Root max-width remains separate.
+Sparse alignment and width overrides use independent variables. Overflow routes to the
+outer wrapper, with explicit scroll-y setting sticky offset to zero and other explicit
+values resetting it. Visibility retains layout space and ordinary descendant behavior.
+
+Scopes, media, supports, container queries, layers and separate rules retain their order.
+When an ID is also the scoping root, its selector gains `:where(:scope)` so it can match
+that root without increasing specificity. Structural rules stay in their original envelope;
+low-specificity defaults use a reserved first `origami-container-defaults` cascade layer,
+with copies of the original conditional/scope envelopes, so defaults cannot override authored
+values in later layers. Nested containers receive their own defaults.
+
+All SPX expressions read the browser's active settings, including ordinary component styles
+and semantic container wrappers. Settings-only breakpoint overrides therefore affect sizes
+without repeating the size declarations. The layout compiler does not reset SPX settings;
+wrappers and nested components follow normal CSS inheritance. Scale retains the signed
+half-pixel floor; fixed values retain fractional pixels; zero is zero. See the
+[SPX plugin README](src/cssPlugins/spx/README.md) for a simple example and implementation details.
+
+## Release and limitations
+
+Use the existing snapshot 0.4.0 baseline. Publish origami-runtime 0.2.0 (including layout-contract), then this runtime
+1.1.0, before the generator/CLI that selects these minimum versions. Explicit local/file
+runtime overrides remain supported. Packed tests verify the compiler and pure contract
+outside the workspace without loading React or the snapshot. Coordinate DM 0.42 publication
+and first-published reader loadability separately; that producer check is not established here.
+
+`--spx-stopper-max` is preserved but does not clamp scaling. The SPX plugin does not generate its runtime clamp formula. `position: stickyToHeader` is preserved
+as authored but is not a browser position value and receives no lowering. These are release
+limitations, not claims of Thunderbolt parity; they need a separate producer/runtime contract.
+
+## Verification
+
+- `yarn workspace @wix/origami-site-runtime test`: parser/compiler, Vite and packed tests.
+- `yarn workspace @wix/origami-site-runtime test:browser`: actual component/snapshot in Chromium,
+  responsive SPX and grid/flex, nested fractional fixed values, max widths/alignment, overflow,
+  visibility, focus/pointer mechanics, HMR and production build. Install Playwright Chromium or
+  set `CHROME_CHANNEL=chrome` to use installed Chrome.
+- Build, lint and test the origami runtime and site generator when changing their contract or
+  minimum versions. Static producer fixture provenance lives in test/fixtures/css/README.md.

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@wix/origami-site-runtime",
+  "version": "1.0.0",
+  "description": "Vite development and build helpers for wix-import static sites",
+  "main": "./src/index.js",
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "build": "rm -rf dist tsconfig.tsbuildinfo && tsc -b .",
+    "lint": "oxlint .",
+    "test": "pnpm run build && node --test test/*.spec.js",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "test:browser": "node test/spx.browser.mjs && node test/semanticContainer.browser.mjs"
+  },
+  "dependencies": {
+    "@babel/core": "^7.26.0",
+    "@babel/parser": "^7.25.0",
+    "@babel/types": "^7.25.2",
+    "@wix/builder-error-pages": "^1.1.6",
+    "@wix/builder-piler-components": "^1.6.7",
+    "@wix/origami-react-runtime": "1.0.0",
+    "postcss": "^8.5.3",
+    "postcss-custom-media": "^12.0.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@wix/origami-types": "1.0.0",
+    "@types/node": "^22.0.0",
+    "@vitejs/plugin-react": "^4.3.4",
+    "playwright": "^1.61.1",
+    "typescript": "^6.0.3",
+    "vite": "^6.0.0"
+  },
+  "peerDependencies": {
+    "@vitejs/plugin-react": "^4.3.4",
+    "vite": "^6.0.0"
+  },
+  "publishUnscoped": false,
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "wix": {
+    "artifact": {
+      "groupId": "com.wixpress.npm",
+      "artifactId": "origami-site-runtime-clone",
+      "targets": {
+        "docker": false
+      }
+    },
+    "validations": {
+      "source": [
+        "lint"
+      ],
+      "postBuild": [
+        "test"
+      ]
+    }
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./default-error-404": "./src/default-error-404.jsx"
+  },
+  "type": "module",
+  "falconPackageHash": "e4d43ee225d9fd6b2a984e43f7d601eb4882c251249a3d557ea756e0"
+}

package/src/cssPlugins/customMedia.js

@@ -0,0 +1,52 @@
+// `@custom-media --name (query);` with `@media (--name) {}` (Media Queries Level 5). No browser ships it, so the
+// alias is always expanded. The expansion is postcss-custom-media's, which matches the DM output exactly; this
+// descriptor only runs that plugin over the stage's shared Root, so the stage keeps its gating (site-owned files)
+// and its ordering.
+//
+// A definition is only visible within the document that declares it. DM emits the definitions in the theme
+// carrier, the generator `@import`s that into every page stylesheet, and Vite's postcss-import inlines it before
+// this stage runs — so definition and usage share one Root.
+
+import postcss from 'postcss'
+import postcssCustomMedia from 'postcss-custom-media'
+
+const processor = postcss([postcssCustomMedia()])
+
+const CUSTOM_MEDIA_QUERY = /\(\s*--/
+
+// Whether the document uses the feature at all: a definition to remove, or an alias to expand. Every carrier but
+// the theme has neither, and this walk visits only at-rules, where the expansion walks and re-marks every node.
+const usesCustomMedia = root => {
+    let used = false
+    root.walkAtRules(atRule => {
+        if (atRule.name === 'custom-media' || (atRule.name === 'media' && CUSTOM_MEDIA_QUERY.test(atRule.params))) {
+            used = true
+            return false
+        }
+    })
+    return used
+}
+
+/** @type {import('../transform/types.js').CssTransformPlugin} */
+export const customMediaPlugin = {
+    name: 'custom-media',
+    order: 0,
+    transform(root, context) {
+        if (!usesCustomMedia(root)) return
+        // A Root handed to `process` is transformed in place. The plugin has no async hooks, so `sync` is safe.
+        // Its warnings go to the nested Result and are dropped: the only one it raises is a cyclic definition,
+        // which leaves the alias unexpanded and so fails below anyway. A definition it cannot parse at all is a
+        // different matter — it emits the unparsed bytes as the query and warns about nothing, which no check
+        // here can see. DM does not emit one.
+        processor.process(root, { from: context.filePath }).sync()
+        // An unexpanded alias is left as authored, and a browser evaluates it to "unknown", which silently
+        // disables the whole block.
+        root.walkAtRules('media', atRule => {
+            if (CUSTOM_MEDIA_QUERY.test(atRule.params)) {
+                throw new Error(
+                    `@media ${atRule.params} has no usable @custom-media definition: it is missing or cyclic`
+                )
+            }
+        })
+    },
+}

package/src/cssPlugins/index.js

@@ -0,0 +1,18 @@
+// The CSS stage's plugins, in the order they run. DM authors its CSS in features no browser implements yet, or only
+// Chromium does; these compile them away so a generated site renders everywhere. A caller can still pass its own
+// list through `createSiteViteConfig({ cssPlugins })`.
+//
+// A descriptor needs a `name`, an `order`, and `transform(root, context)`, where `root` is the PostCSS Root for the
+// stylesheet; see `../transform/types.js` for the contract and `../transform/css/postcssPlugin.js` for what the
+// stage guarantees a plugin sees. The order matters once: mixin bodies are copied into their calling rules before
+// layout routes declarations to wrappers and SPX converts calls using the browser's active settings.
+//
+// `@layer` needs no plugin: cascade layers have been in every browser since March 2022.
+
+import { customMediaPlugin } from './customMedia.js'
+import { mixinsPlugin } from './mixins.js'
+import { layoutPlugin } from './layout/index.js'
+import { spxPlugin } from './spx/index.js'
+
+/** @type {readonly import('../transform/types.js').CssTransformPlugin[]} */
+export const cssPlugins = Object.freeze([customMediaPlugin, mixinsPlugin, layoutPlugin, spxPlugin])

package/src/cssPlugins/layout/README.md

@@ -0,0 +1,77 @@
+# Layout puts container styles on the right elements
+
+A container has an outer component, an overflow wrapper and a content wrapper.
+The outer component controls its place on the page. The overflow wrapper controls
+scrolling and clipping. The content wrapper arranges the children.
+
+In site-owned `layout.css`, `@origami-target` says which wrapper a style belongs to:
+
+```css
+#container {
+    --container-layout-type: FlexContainerLayout;
+
+    @origami-target internal-container-content-wrapper {
+        display: flex;
+        flex-direction: column;
+        row-gap: --spx(16);
+        --content-max-width: 1200px;
+        --content-max-width-align: center;
+    }
+
+    @origami-target internal-container-overflow-wrapper {
+        overflow-y: auto;
+    }
+}
+```
+
+The plugin replaces these target blocks with ordinary CSS rules that select the
+matching wrappers. Grid, flex, gaps, padding and content width go on the content
+wrapper; overflow goes on the overflow wrapper. Other component styles stay on
+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.
+
+## Why validation runs before transformations
+
+During development and builds, Vite first inlines CSS imports. Our CSS pipeline
+then runs every plugin's optional `validate()` before running any plugin's
+`transform()`. Currently, layout is the only plugin with this validation hook.
+If validation fails, processing stops before transformations begin.
+
+Layout needs this early check because targets are not allowed inside mixins.
+The mixin plugin runs before layout compilation: it removes mixin definitions
+and copies their contents into the rules that use them. After that, an invalid
+target could look like a normal component rule, or disappear with an unused
+mixin. Early validation checks the original placement before that evidence is lost.
+
+Previously, plugins only had a transformation step and checked input as they
+processed it. The target placement rules introduced the need for a separate
+validation phase. Layout calls `parseTargets()` again during transformation to
+check and collect the target nodes from the updated stylesheet.
+
+## Files and boundaries
+
+- `index.js` registers validation and transformation.
+- `contract.js` lists the supported targets, their properties and layout displays.
+- `parser.js` checks target placement, properties and values, and rejects duplicates.
+- `compiler.js` builds wrapper selectors, adds base styles and moves declarations.
+
+Targets must come from site-owned `layout.css` and belong to a single component ID
+rule. Unsupported targets or properties fail with an error rather than being ignored.
+
+This plugin generates CSS; the runtime supplies the wrapper elements. SPX values
+are converted afterward by the SPX plugin.
+
+`test/semanticContainer.browser.mjs` checks container behavior in the browser.
+Run it together with the SPX checks using the package's `test:browser` script.

package/src/cssPlugins/layout/compiler.js

@@ -0,0 +1,116 @@
+import postcss from 'postcss'
+import { buildContainerClasses } from '@wix/origami-react-runtime/layout-contract'
+import { CONTENT } from './contract.js'
+import { isLayoutSource, parseTargets } from './parser.js'
+
+const grid = { display: 'grid', 'grid-template-rows': '1fr', 'grid-template-columns': 'minmax(0, 1fr)' }
+
+/** Preserve source locations on every emitted declaration and selector. */
+const ruleFor = (owner, selector, declarations) => {
+    const rule = postcss.rule({ selector, source: owner.source })
+    for (const [prop, value] of Object.entries(declarations)) {
+        const declaration = postcss.decl({ prop, value: String(value) })
+        declaration.source = owner.source
+        rule.append(declaration)
+    }
+    return rule
+}
+
+/** @param {import('postcss').Root} root
+ * @param {import('../../transform/types.js').TransformContext} context */
+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.
+    // 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' })
+    if (root.source) defaultsLayer.source = root.source
+    root.prepend(defaultsLayer)
+    // Source identity prevents a matching selector in another carrier from becoming an owner.
+    const identities = new Set([...owners.keys()].map(rule => `${rule.source?.input.file}\0${rule.selector}`))
+    const rules = []
+    root.walkRules(rule => {
+        if (isLayoutSource(rule, context) && identities.has(`${rule.source?.input.file}\0${rule.selector}`))
+            rules.push(rule)
+    })
+    // Mechanics are emitted before the first rule in each envelope; authored declarations win.
+    const contexts = new WeakMap()
+    for (const owner of rules) {
+        const { contentClass, overflowClass } = buildContainerClasses(owner.selector.slice(1))
+        // In @scope, an unqualified selector cannot select the scoping root. DM emits
+        // #id there too; :where(:scope) includes that root without adding specificity.
+        let selector = owner.selector
+        for (let ancestor = owner.parent; ancestor && ancestor.type !== 'root'; ancestor = ancestor.parent) {
+            if (ancestor.type === 'atrule' && ancestor.name === 'scope') {
+                if (ancestor.params.trim() === `(${selector})`) selector = `:where(:scope)${selector}`
+                break
+            }
+        }
+        const overflow = `${selector} > .${overflowClass}`
+        const content = `${overflow} > .${contentClass}`
+        const emitted = contexts.get(owner.parent) ?? new Set()
+        if (!emitted.has(owner.selector)) {
+            let defaultsParent = defaultsLayer
+            const envelopes = []
+            for (let ancestor = owner.parent; ancestor && ancestor.type !== 'root'; ancestor = ancestor.parent) {
+                if (ancestor.type === 'atrule' && ancestor.name !== 'layer') envelopes.unshift(ancestor)
+            }
+            for (const envelope of envelopes) {
+                const clone = envelope.clone({ nodes: [] })
+                defaultsParent.append(clone)
+                defaultsParent = clone
+            }
+            defaultsParent.append(
+                ruleFor(owner, `:where(${content})`, {
+                    '--content-max-width': 'none',
+                    '--origami-content-align': '0.5',
+                })
+            )
+            owner.before(ruleFor(owner, selector, grid))
+            owner.before(ruleFor(owner, overflow, { ...grid, position: 'relative', 'align-self': 'stretch' }))
+            owner.before(
+                ruleFor(owner, content, {
+                    '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' }))
+            emitted.add(owner.selector)
+            contexts.set(owner.parent, emitted)
+        }
+        owner.selector = selector
+        let previous = owner
+        for (const target of owners.get(owner) ?? []) {
+            const generated = ruleFor(owner, target.params.trim() === CONTENT ? content : overflow, {})
+            for (const node of target.nodes ?? []) {
+                const clone = node.clone()
+                if (clone.type === 'decl') {
+                    if (clone.prop === '--content-max-width-align') {
+                        clone.prop = '--origami-content-align'
+                        // 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 === 'overflow-y')
+                        generated.append(
+                            clone.clone({
+                                prop: '--sticky-offset',
+                                value: clone.value === 'scroll' ? '0px' : 'initial',
+                            })
+                        )
+                }
+                generated.append(clone)
+            }
+            previous.after(generated)
+            previous = generated
+            target.remove()
+        }
+    }
+}

package/src/cssPlugins/layout/contract.js

@@ -0,0 +1,35 @@
+// DM JSX era 0.42, document-management ef124715766d47d0b420bb3ec5a6c54a674a7b9b.
+// 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 targets = Object.freeze({
+    [CONTENT]: new Set([
+        'position',
+        'display',
+        'grid-template-columns',
+        'grid-template-rows',
+        'grid-auto-flow',
+        'grid-auto-rows',
+        'grid-auto-columns',
+        'row-gap',
+        'column-gap',
+        'flex-direction',
+        'flex-wrap',
+        'justify-content',
+        'align-items',
+        'align-content',
+        'padding-top',
+        'padding-bottom',
+        'padding-left',
+        'padding-right',
+        '--content-max-width',
+        '--content-max-width-align',
+    ]),
+    [OVERFLOW]: new Set(['overflow-x', 'overflow-y']),
+})
+export const displays = Object.freeze({
+    GridContainerLayout: 'grid',
+    FlexContainerLayout: 'flex',
+    StackContainerLayout: 'flex',
+    OrganizerContainerLayout: 'flex',
+})

package/src/cssPlugins/layout/index.js

@@ -0,0 +1,12 @@
+import { compileContainers } from './compiler.js'
+import { parseTargets } from './parser.js'
+
+/** @type {import('../../transform/types.js').CssTransformPlugin} */
+export const layoutPlugin = {
+    name: 'layout',
+    order: 15,
+    validate: (root, context) => {
+        parseTargets(root, context)
+    },
+    transform: compileContainers,
+}

package/src/cssPlugins/layout/parser.js

@@ -0,0 +1,81 @@
+import { basename } from 'node:path'
+import { isValidContainerId } from '@wix/origami-react-runtime/layout-contract'
+import { relativeToSite } from '../../routing/siteLayout.js'
+import { CONTENT, OVERFLOW, targets, displays } from './contract.js'
+
+/** @param {import('postcss').Node} node
+ * @param {import('../../transform/types.js').TransformContext} context */
+export const isLayoutSource = (node, context) => {
+    const file = node.source?.input.file
+    if (!file || basename(file) !== 'layout.css') return false
+    const relative = context.layout ? relativeToSite(context.layout.root, file) : file
+    return relative !== undefined && !relative.split(/[\\/]/).includes('node_modules')
+}
+
+/** Validate before mixins can erase the original placement/source of a target.
+ * @param {import('postcss').Root} root
+ * @param {import('../../transform/types.js').TransformContext} context */
+export const parseTargets = (root, context) => {
+    /** @type {Map<import('postcss').Rule, import('postcss').AtRule[]>} */
+    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}`)
+        const owner = target.parent
+        if (owner?.type !== 'rule' || !owner.selector.startsWith('#') || !isValidContainerId(owner.selector.slice(1))) {
+            throw 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')
+            }
+        }
+        if (!isLayoutSource(target, context))
+            throw 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}`)
+        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}`)
+            seen.add(node.prop)
+            if (!targets[name].has(node.prop)) throw node.error(`${node.prop} does not belong to ${name}`)
+            if (node.prop === 'position' && node.value !== 'relative')
+                throw 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}`)
+            }
+            if (node.prop === '--content-max-width-align' && !['left', 'center', 'right'].includes(node.value)) {
+                throw 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')
+                if (
+                    !['grid', 'flex'].includes(node.value) ||
+                    (type?.type === 'decl' &&
+                        (!Object.hasOwn(displays, type.value) || displays[type.value] !== node.value))
+                ) {
+                    throw node.error('Container type and content display are inconsistent')
+                }
+            }
+        }
+        siblings.push(target)
+        owners.set(owner, siblings)
+    })
+    for (const owner of owners.keys()) {
+        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}`)
+            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`)
+            }
+        }
+    }
+    return owners
+}

package/src/cssPlugins/mixins.js

@@ -0,0 +1,23 @@
+/** @param {import('postcss').AtRule} atRule */
+const mixinName = atRule => atRule.params.trim().replace(/\(\)$/, '')
+
+/** @type {import('../transform/types.js').CssTransformPlugin} */
+export const mixinsPlugin = {
+    name: 'mixins',
+    order: 10,
+    transform(root) {
+        /** @type {Map<string, import('postcss').ChildNode[]>} */
+        const bodies = new Map()
+        root.walkAtRules('mixin', atRule => {
+            const first = atRule.first
+            const body = first?.type === 'atrule' && first.name === 'result' ? first : atRule
+            bodies.set(mixinName(atRule), body.nodes ?? [])
+            atRule.remove()
+        })
+        root.walkAtRules('apply', atRule => {
+            const body = bodies.get(mixinName(atRule))
+            if (!body) throw new Error(`@apply ${atRule.params} has no @mixin definition`)
+            atRule.replaceWith(body.map(node => node.clone()))
+        })
+    },
+}

package/src/cssPlugins/spx/README.md

@@ -0,0 +1,73 @@
+# SPX follows the active CSS settings
+
+A component can declare a size once and change its scaling settings at a breakpoint:
+
+```css
+#button {
+    --spx-ref-width: 1280;
+    --spx-resolver-type: scale;
+    border-width: --spx(4);
+}
+
+@media (max-width: 600px) {
+    #button {
+        --spx-ref-width: 390;
+    }
+}
+```
+
+The desktop border declaration still applies on mobile. At a 390px viewport, it should
+be 4px again because its reference width is now 390. If the build replaces `4 / 1280`
+with a constant, the mobile reference-width override can no longer affect that border.
+
+This applies to regular component styles as well as container layouts. There is one
+SPX conversion path for all declarations. Layout first moves content and overflow
+styles onto their runtime wrappers; this plugin then converts every `--spx(number)`.
+
+## What the browser calculates
+
+In scale mode, the size is approximately:
+
+```text
+number × (scaling-factor − scrollbar-width) / spx-ref-width
+```
+
+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
+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.
+
+Settings stay in their authored rules, including their media queries, scopes, layers,
+source order and `!important`. Even a stylesheet that contains only settings must be
+processed, because it can affect calls declared in another stylesheet. The original
+resolver declaration is retained alongside its numeric switch.
+
+We inline the calculation instead of inheriting a precomputed `--origami-spx-unit`.
+An inherited derived custom property has already been resolved on its parent; changing
+reference width or scaling factor on a child would not recompute it there. Reading the
+settings in each expression lets ordinary components and internal wrappers use their
+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
+re-evaluate it using a child's settings.
+
+## 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.
+
+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.
+
+`test/spx.browser.mjs` checks computed styles for the button example, nested overrides,
+settings in separate stylesheets, cascade priority, fixed fractions, signs and zero.
+Run it together with the container browser checks using the package's `test:browser` script.

package/src/cssPlugins/spx/calls.js

@@ -0,0 +1,12 @@
+const CALL = /--spx\(\s*(-?(?:\d+\.?\d*|\.\d+))\s*\)/g
+
+/** Replace literal SPX calls, reporting unsupported arguments at their declaration.
+ * @param {import('postcss').Declaration} declaration
+ * @param {(value: number) => string} resolve
+ * @param {() => Error} invalidCall
+ */
+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()
+}