@wix/origami-site-runtime 1.0.1 → 1.0.2

package/README.md

@@ -26,7 +26,7 @@ cannot hide an illegally placed target. Diagnostics retain the original node sou
 `@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
+`@wix/origami-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)).
@@ -70,8 +70,8 @@ limitations, not claims of Thunderbolt parity; they need a separate producer/run
 
 ## 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,
+- `pnpm --filter @wix/origami-site-runtime run test`: parser/compiler, Vite and packed tests.
+- `pnpm --filter @wix/origami-site-runtime run 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/origami-site-runtime",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Vite development and build helpers for wix-import static sites",
   "main": "./src/index.js",
   "files": [
@@ -19,7 +19,7 @@
     "@babel/types": "^7.25.2",
     "@wix/builder-error-pages": "^1.1.6",
     "@wix/builder-piler-components": "^1.6.7",
-    "@wix/origami-react-runtime": "1.1.0",
+    "@wix/origami-runtime": "0.8.0",
     "postcss": "^8.5.3",
     "postcss-custom-media": "^12.0.1",
     "react": "^18.3.1",
@@ -64,5 +64,5 @@
     "./default-error-404": "./src/default-error-404.jsx"
   },
   "type": "module",
-  "falconPackageHash": "e47c7dc0872fc8f72c857c2eb238c0fd694ab3713e3eb68247abf768"
+  "falconPackageHash": "3fcbcf21abe9563da3da6312bc4bfe3f95fc4f7e93d351370dca2193"
 }

package/src/cssPlugins/index.js

@@ -5,7 +5,9 @@
 // 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.
+// layout routes declarations to wrappers and SPX converts calls using the browser's active settings. stack-children
+// only checks, and runs between mixins and layout: it needs the mixins' declarations and the stack rules as authored,
+// before layout compiles them away.
 //
 // `@layer` needs no plugin: cascade layers have been in every browser since March 2022.
 
@@ -13,6 +15,7 @@ import { customMediaPlugin } from './customMedia.js'
 import { mixinsPlugin } from './mixins.js'
 import { layoutPlugin } from './layout/index.js'
 import { spxPlugin } from './spx/index.js'
+import { stackChildrenPlugin } from './stackChildren.js'
 
 /** @type {readonly import('../transform/types.js').CssTransformPlugin[]} */
-export const cssPlugins = Object.freeze([customMediaPlugin, mixinsPlugin, layoutPlugin, spxPlugin])
+export const cssPlugins = Object.freeze([customMediaPlugin, mixinsPlugin, stackChildrenPlugin, layoutPlugin, spxPlugin])

package/src/cssPlugins/layout/compiler.js

@@ -1,5 +1,5 @@
 import postcss from 'postcss'
-import { buildContainerClasses } from '@wix/origami-react-runtime/layout-contract'
+import { buildContainerClasses } from '@wix/origami-runtime/layout-contract'
 import { CONTENT } from './contract.js'
 import { isLayoutSource, parseTargets } from './parser.js'
 

package/src/cssPlugins/layout/parser.js

@@ -1,5 +1,5 @@
 import { basename } from 'node:path'
-import { isValidContainerId } from '@wix/origami-react-runtime/layout-contract'
+import { isValidContainerId } from '@wix/origami-runtime/layout-contract'
 import { relativeToSite } from '../../routing/siteLayout.js'
 import { CONTENT, OVERFLOW, targets, displays } from './contract.js'
 

package/src/cssPlugins/stackChildren.js

@@ -0,0 +1,205 @@
+// Checks the CSS of a stack's direct children (rule S2-STACK-001). It changes nothing: every violation in the
+// stylesheet is collected, and the build fails once with all of them.
+//
+// A stack is a parent whose rule declares `--container-layout-type: StackContainerLayout`; its
+// `flex-direction` says which way it stacks (column → vertical, anything else → horizontal, as in
+// CSS). Parent and child are the JSX tree's, so the tree comes from the item's `structure.tsx` (or `.jsx`): next
+// to the stylesheet, or one folder up when the stylesheet is the generated one in `_generated/`. Elements and
+// rules meet on `id` and `#id`. The stylesheet is the page's, with its
+// carriers already inlined (see ../transform/css/postcssPlugin.js), so every rule is in view.
+
+import { existsSync, readFileSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { parseSync } from '@babel/core'
+import { LayoutError } from '../transform/layoutError.js'
+
+const STRUCTURE_FILES = ['structure.tsx', 'structure.jsx']
+const GENERATED = '_generated'
+const STACK_CONTAINER = 'StackContainerLayout'
+const BASE = ''
+
+// What a stack child may write, per direction. `0` is allowed wherever a length is.
+const ALLOWED = {
+    vertical: { width: ['spx', 'px', 'vw', 'vh', '%', 'calc'], margin: ['spx', 'px', 'vw', 'vh', '%'] },
+    horizontal: { width: ['spx', 'px', 'vw', 'vh', 'calc'], margin: ['spx', 'px', 'vw', 'vh'] },
+}
+
+const UNIT = /^-?(?:\d+\.?\d*|\.\d+)(px|vw|vh|%)$/i
+const LABELS = { spx: '--spx()', px: 'px', vw: 'vw', vh: 'vh', '%': '%', calc: 'calc()' }
+
+/** `width` → 'width', `margin`/`margin-*` → 'margin', anything else → undefined. */
+const kindOf = prop =>
+    prop === 'width' ? 'width' : prop === 'margin' || prop.startsWith('margin-') ? 'margin' : undefined
+
+/** A value split on top-level whitespace, so `calc(1px + 2%)` stays one token. */
+const tokens = value => {
+    const result = []
+    let depth = 0
+    let current = ''
+    for (const char of value.replace(/!important\s*$/i, '').trim()) {
+        if (char === '(') depth++
+        else if (char === ')') depth--
+        if (depth === 0 && /\s/.test(char)) {
+            if (current) result.push(current)
+            current = ''
+        } else current += char
+    }
+    if (current) result.push(current)
+    return result
+}
+
+/** The kind of length a token is: 'spx', 'px', 'vw', 'vh', '%', 'calc', 'zero', or undefined. */
+const lengthOf = token => {
+    if (/^--spx\(.*\)$/.test(token)) return 'spx'
+    if (/^calc\(.*\)$/i.test(token)) return 'calc'
+    if (/^-?0*\.?0+$/.test(token)) return 'zero'
+    return UNIT.exec(token)?.[1].toLowerCase()
+}
+
+/** The folder holding the structure file a stylesheet is checked against: its own, or its item's for `_generated/`. */
+const structureFolderOf = stylesheetPath => {
+    const folder = dirname(stylesheetPath)
+    return basename(folder) === GENERATED ? dirname(folder) : folder
+}
+
+/** Child id → its direct parent's id, for elements with a literal `id`. Slot props are not children. */
+const parentsIn = structurePath => {
+    const ast = parseSync(readFileSync(structurePath, 'utf8'), {
+        babelrc: false,
+        configFile: false,
+        filename: structurePath,
+        parserOpts: { plugins: structurePath.endsWith('.tsx') ? ['jsx', 'typescript'] : ['jsx'] },
+    })
+    const parents = new Map()
+    const idOf = element => {
+        const attribute = element.openingElement.attributes.find(
+            node => node.type === 'JSXAttribute' && node.name.name === 'id' && node.value?.type === 'StringLiteral'
+        )
+        return attribute?.value.value
+    }
+    const directChildren = node =>
+        node.children.flatMap(child =>
+            child.type === 'JSXElement' ? [child] : child.type === 'JSXFragment' ? directChildren(child) : []
+        )
+    const visit = node => {
+        if (Array.isArray(node)) return node.forEach(visit)
+        if (!node || typeof node.type !== 'string') return
+        if (node.type === 'JSXElement') {
+            const parent = idOf(node)
+            for (const child of directChildren(node)) {
+                const id = idOf(child)
+                if (parent !== undefined && id !== undefined) parents.set(id, parent)
+            }
+        }
+        for (const [key, value] of Object.entries(node)) {
+            if (key !== 'loc' && value && typeof value === 'object') visit(value)
+        }
+    }
+    visit(ast?.program)
+    return parents
+}
+
+/** The at-rule conditions a rule sits under, e.g. `media (max-width: 750px)`, or BASE. */
+const conditionOf = rule => {
+    const conditions = []
+    for (let node = rule.parent; node && node.type !== 'root'; node = node.parent) {
+        if (node.type === 'atrule') conditions.unshift(`${node.name} ${node.params}`)
+    }
+    return conditions.join(' / ')
+}
+
+/** Id → condition → the declarations that rules selecting exactly `#id` make there, in source order. */
+const declarationsById = root => {
+    const byId = new Map()
+    root.walkRules(rule => {
+        const ids = rule.selectors.map(selector => /^#([\w-]+)$/.exec(selector.trim())?.[1]).filter(Boolean)
+        if (!ids.length) return
+        const condition = conditionOf(rule)
+        for (const id of ids) {
+            const byCondition = byId.get(id) ?? new Map()
+            byId.set(id, byCondition)
+            const declarations = byCondition.get(condition) ?? []
+            byCondition.set(condition, declarations)
+            rule.each(node => {
+                if (node.type === 'decl') declarations.push(node)
+            })
+        }
+    })
+    return byId
+}
+
+/** The declarations in effect under `condition`: the base ones, then the condition's own. */
+const effective = (byCondition, condition) => {
+    const result = new Map()
+    for (const key of condition === BASE ? [BASE] : [BASE, condition]) {
+        for (const declaration of byCondition?.get(key) ?? []) result.set(declaration.prop, declaration)
+    }
+    return result
+}
+
+/** 'vertical' or 'horizontal' when these declarations make a stack, else undefined. */
+const directionOf = declarations => {
+    if (declarations.get('--container-layout-type')?.value.trim() !== STACK_CONTAINER) return undefined
+    return /^column/.test(declarations.get('flex-direction')?.value.trim() ?? '') ? 'vertical' : 'horizontal'
+}
+
+/** ` (layout.css:12)`: the carrier the declaration was written in, which the bundler doesn't name. */
+const where = declaration => {
+    const file = declaration.source?.input.file
+    const line = declaration.source?.start?.line
+    return file ? ` (${basename(file)}${line ? `:${line}` : ''})` : ''
+}
+
+const or = items => (items.length === 1 ? items[0] : `${items.slice(0, -1).join(', ')} or ${items.at(-1)}`)
+
+/** @type {import('../transform/types.js').CssTransformPlugin} */
+export const stackChildrenPlugin = {
+    name: 'stack-children',
+    // After mixins copy their bodies in, before spx rewrites --spx() calls away.
+    order: 12,
+    transform(root, context) {
+        const structurePath = STRUCTURE_FILES.map(file => join(structureFolderOf(context.filePath), file)).find(
+            existsSync
+        )
+        if (structurePath === undefined) return
+        context.addDependency?.(structurePath)
+        const parents = parentsIn(structurePath)
+        if (parents.size === 0) return
+        const byId = declarationsById(root)
+
+        const violations = new Set()
+        let first
+        for (const [child, parent] of parents) {
+            const childRules = byId.get(child)
+            const parentRules = byId.get(parent)
+            if (childRules === undefined || parentRules === undefined) continue
+            for (const condition of new Set([BASE, ...parentRules.keys(), ...childRules.keys()])) {
+                const direction = directionOf(effective(parentRules, condition))
+                if (direction === undefined) continue
+                for (const declaration of effective(childRules, condition).values()) {
+                    const kind = kindOf(declaration.prop)
+                    if (kind === undefined) continue
+                    const allowed = ALLOWED[direction][kind]
+                    const bad = tokens(declaration.value).filter(token => {
+                        const length = lengthOf(token)
+                        return length === undefined || (length !== 'zero' && !allowed.includes(length))
+                    })
+                    if (!bad.length) continue
+                    first ??= declaration.source
+                    violations.add(
+                        `#${child}${where(declaration)}, a ${direction} stack child: ${declaration.prop} must be ` +
+                            `${or(allowed.map(unit => LABELS[unit]))}; found ${bad.join(' ')}.`
+                    )
+                }
+            }
+        }
+
+        if (violations.size) {
+            throw new LayoutError([...violations], {
+                file: first?.input.file,
+                line: first?.start?.line,
+                column: first?.start?.column,
+            })
+        }
+    },
+}

package/src/jsxPlugins/index.js

@@ -3,6 +3,7 @@
 // `program` is the Babel Program path for the module; see `../transform/types.js`.
 
 import { origamiCompatibilityPlugin } from './origamiCompatibility/index.js'
+import { layoutValidationPlugin } from './validation/index.js'
 
 /** @type {readonly import('../transform/types.js').JsxTransformPlugin[]} */
-export const jsxPlugins = Object.freeze([origamiCompatibilityPlugin])
+export const jsxPlugins = Object.freeze([layoutValidationPlugin, origamiCompatibilityPlugin])

package/src/jsxPlugins/validation/checks.js

@@ -0,0 +1,105 @@
+// The checks behind the constraints in ./rules.js. Each gets the element a rule applies to and
+// reports what it found; the message states the rule's whole constraint and how to fix it, so one
+// error is enough to write the correct structure.
+//
+// To add a kind of constraint: add a function to CHECKS, use its key in rules.js, and extend
+// expectation() so messages state it.
+
+import { describe } from './tree.js'
+
+const CHILD_CONSTRAINTS = ['allowedChildren', 'minChildren', 'maxChildren']
+
+const list = names => {
+    const items = names.map(name => `<${name}>`)
+    return items.length === 1 ? items[0] : `${items.slice(0, -1).join(', ')} or ${items.at(-1)}`
+}
+
+// "must have exactly one <InternalContainer> child"
+const childrenExpectation = ({ allowedChildren, minChildren: min, maxChildren: max }) => {
+    const count =
+        min !== undefined && min === max
+            ? `exactly ${min === 1 ? 'one' : min}`
+            : min !== undefined && max !== undefined
+              ? `between ${min} and ${max}`
+              : min !== undefined
+                ? `at least ${min}`
+                : max !== undefined
+                  ? `at most ${max}`
+                  : 'only'
+    const kind = allowedChildren ? list(allowedChildren) : 'JSX element'
+    const noun = min === 1 && max === 1 ? 'child' : 'children'
+    return `must have ${count} ${kind} ${noun}`
+}
+
+const expectation = rule => {
+    const parts = []
+    if (rule.allowedChildren || rule.minChildren !== undefined || rule.maxChildren !== undefined) {
+        parts.push(childrenExpectation(rule))
+    }
+    return parts.join(', and ')
+}
+
+const at = node => (node.loc ? ` (line ${node.loc.start.line})` : '')
+
+/** A constrained parent's children must be literal JSX tags. */
+const checkLiteral = ({ node, fail }) => {
+    const unseen = what => fail(`${what}; write each child as a JSX tag`)
+    for (const attribute of node.openingElement.attributes) {
+        if (attribute.type === 'JSXSpreadAttribute') unseen(`spread props${at(attribute)}`)
+        else if (attribute.name.name === 'children') unseen(`a children= prop${at(attribute)}`)
+    }
+    for (const child of node.children) {
+        if (child.type === 'JSXExpressionContainer' && child.expression.type !== 'JSXEmptyExpression') {
+            unseen(`a {…} expression${at(child)}`)
+        } else if (child.type === 'JSXSpreadChild') unseen(`a {...spread} child${at(child)}`)
+        else if (child.type === 'JSXFragment') unseen(`a fragment${at(child)}`)
+        else if (child.type === 'JSXText' && child.value.trim()) unseen(`text${at(child)}`)
+    }
+}
+
+const CHECKS = {
+    allowedChildren: (allowed, { elements, fail }) => {
+        for (const { element, component } of elements) {
+            if (!allowed.includes(component)) fail(`${describe(element)}`)
+        }
+    },
+    minChildren: (min, { elements, fail }) => {
+        if (elements.length < min) fail(elements.length === 0 ? 'none' : `${elements.length}`)
+    },
+    maxChildren: (max, { elements, fail }) => {
+        if (elements.length > max) fail(`${elements.length}`)
+    },
+}
+
+// Fail fast on a typo in rules.js.
+export const assertKnownConstraints = rules => {
+    for (const rule of rules) {
+        for (const key of Object.keys(rule)) {
+            if (key !== 'id' && key !== 'components' && !CHECKS[key]) {
+                throw new Error(
+                    `layout rules: unknown constraint "${key}" on ${rule.id}. Known: ${Object.keys(CHECKS).join(', ')}`
+                )
+            }
+        }
+    }
+}
+
+export const constrainsChildren = rule => CHILD_CONSTRAINTS.some(key => key in rule)
+
+/** Runs every constraint of `rule` on one element; `report` receives each full message. */
+export const checkRule = (rule, { node, componentOf, report }) => {
+    const prefix = `${describe(node)} ${expectation(rule)}`
+    const fail = got => report(`${prefix}; found ${got}.`)
+
+    const elements = node.children
+        .filter(child => child.type === 'JSXElement')
+        .map(element => ({ element, component: componentOf(element) }))
+    const context = { node, elements, fail }
+
+    if (constrainsChildren(rule)) checkLiteral(context)
+    for (const [key, value] of Object.entries(rule)) CHECKS[key]?.(value, context)
+}
+
+/** `createElement(Section, …)` would hide a constrained component's children from the checks. */
+export const checkCreateElement = (rule, { node, component, report }) =>
+    report(`<${component}>${at(node)} ${expectation(rule)}; found createElement(${component}), write it as a JSX tag.`)

package/src/jsxPlugins/validation/index.js

@@ -0,0 +1,65 @@
+// Checks authored structures against the Studio 2 site rulebook layout rules. It changes
+// nothing: every violation in the file is collected, and the build fails once with all of them.
+//
+// One walk serves every rule. Rules are data (./rules.js); each names the components it looks at,
+// identified for now by JSX tag name as written (<Section>, <InternalContainer>), whatever they are
+// imported from, and the checks (./checks.js) run on each matching element.
+
+import { basename } from 'node:path'
+import { LayoutError } from '../../transform/layoutError.js'
+import { assertKnownConstraints, checkCreateElement, checkRule, constrainsChildren } from './checks.js'
+import { RULES } from './rules.js'
+
+const STRUCTURE_FILES = new Set(['structure.tsx', 'structure.jsx'])
+
+assertKnownConstraints(RULES)
+
+/** Component (tag) name -> the rules that check it. */
+const RULES_BY_COMPONENT = new Map(
+    RULES.flatMap(rule => rule.components).map(component => [
+        component,
+        RULES.filter(rule => rule.components.includes(component)),
+    ])
+)
+
+const isCreateElement = callee =>
+    (callee.type === 'Identifier' && callee.name === 'createElement') ||
+    (callee.type === 'MemberExpression' && !callee.computed && callee.property.name === 'createElement')
+
+/** @type {import('../../transform/types.js').JsxTransformPlugin} */
+export const layoutValidationPlugin = {
+    name: 'wix-import-layout-validation',
+    // Before any plugin that rewrites the tree, so the rules see it as authored.
+    order: -100,
+    appliesTo: context => STRUCTURE_FILES.has(basename(context.filePath)),
+
+    transform: program => {
+        // The component an element is: its tag name, as written.
+        const componentOf = node => {
+            const name = node.openingElement.name
+            return name.type === 'JSXIdentifier' ? name.name : undefined
+        }
+
+        const violations = []
+        const report = message => violations.push(message)
+        program.traverse({
+            JSXElement(path) {
+                const component = componentOf(path.node)
+                const rules = component === undefined ? undefined : RULES_BY_COMPONENT.get(component)
+                if (rules === undefined) return
+                for (const rule of rules) checkRule(rule, { node: path.node, componentOf, report })
+            },
+
+            CallExpression({ node }) {
+                const [type] = node.arguments
+                if (!isCreateElement(node.callee) || type?.type !== 'Identifier') return
+                const component = type.name
+                for (const rule of RULES_BY_COMPONENT.get(component) ?? []) {
+                    if (constrainsChildren(rule)) checkCreateElement(rule, { node, component, report })
+                }
+            },
+        })
+
+        if (violations.length) throw new LayoutError(violations)
+    },
+}

package/src/jsxPlugins/validation/rules.js

@@ -0,0 +1,24 @@
+// The Studio 2 site rulebook rules (rev 1.40) this build checks, as data.
+// A rule lives here unless TypeScript can enforce all of it; a rule is never split between the two.
+//
+// A rule names the components it applies to, by JSX tag name, and the constraints they must meet. Each
+// constraint is a check in ./checks.js, keyed by its name:
+//   allowedChildren:  string[]  — the only components allowed as direct children
+//   minChildren:      number    — minimum number of direct child elements
+//   maxChildren:      number    — maximum number of direct child elements
+//
+// A component whose children a rule constrains must be written as literal JSX with literal child
+// tags: {expressions}, fragments, text, spread props, a children= prop and createElement() are
+// errors, so the check always sees the real structure.
+
+const STANDARD_SECTIONS = ['Section', 'HeaderSection', 'FooterSection']
+
+export const RULES = [
+    {
+        id: 'S2-SECTION-001',
+        components: STANDARD_SECTIONS,
+        allowedChildren: ['InternalContainer'],
+        minChildren: 1,
+        maxChildren: 1,
+    },
+]

package/src/jsxPlugins/validation/tree.js

@@ -0,0 +1,15 @@
+// Reads over the authored JSX tree, shared by the layout rules.
+
+/** `<Section id="x">` at line 12 → `<Section id="x"> (line 12)`, for error messages. */
+export const describe = node => {
+    const opening = node.openingElement
+    const tag = opening.name.type === 'JSXIdentifier' ? opening.name.name : 'element'
+    const id = opening.attributes.find(
+        attribute =>
+            attribute.type === 'JSXAttribute' &&
+            attribute.name.name === 'id' &&
+            attribute.value?.type === 'StringLiteral'
+    )
+    const line = node.loc ? ` (line ${node.loc.start.line})` : ''
+    return `<${tag}${id ? ` id="${id.value.value}"` : ''}>${line}`
+}

package/src/transform/css/postcssPlugin.js

@@ -19,17 +19,39 @@ const isSiteOwned = relativePath =>
     !relativePath.startsWith(DEPENDENCY_DIRECTORY) &&
     !relativePath.includes(`/${DEPENDENCY_DIRECTORY}`)
 
-export const createCssPostcssPlugin = ({ selectPlugins, contextFor }) => ({
+/**
+ * @param {{
+ *     selectPlugins: (context: import('../types.js').TransformContext) => readonly object[],
+ *     contextFor: (id: string) => import('../types.js').TransformContext,
+ *     failures?: Map<string, Set<string>>,
+ * }} options `failures` maps each stylesheet whose last run failed to the files it declared before failing.
+ */
+export const createCssPostcssPlugin = ({ selectPlugins, contextFor, failures }) => ({
     postcssPlugin: 'wix-import-css-transform',
 
     Once(root, { result }) {
         const from = result.opts.from
         if (from === undefined) return
 
-        const context = contextFor(from)
-        if (!isSiteOwned(context.relativePath)) return
+        const fileContext = contextFor(from)
+        if (!isSiteOwned(fileContext.relativePath)) return
 
-        const plugins = selectPlugins(context)
-        if (plugins.length) runCssPlugins({ plugins, root, context })
+        const plugins = selectPlugins(fileContext)
+        if (!plugins.length) return
+        // A plugin that reads another file declares it, so the bundler re-runs this stylesheet when that file
+        // changes. Vite reads these messages only from a run that succeeds, so a failed run's declarations are
+        // kept in `failures` instead; see vitePlugins/siteDocumentsPlugin.js.
+        const declared = new Set()
+        const addDependency = file => {
+            declared.add(file)
+            result.messages.push({ type: 'dependency', plugin: 'wix-import-css-transform', file, parent: from })
+        }
+        try {
+            runCssPlugins({ plugins, root, context: { ...fileContext, addDependency } })
+            failures?.delete(from)
+        } catch (error) {
+            failures?.set(from, declared)
+            throw error
+        }
     },
 })

package/src/transform/css/runPlugins.js

@@ -1,6 +1,8 @@
 // Runs the selected CSS plugins over one shared Root, in order. Parsing, stringifying and source
 // maps belong to PostCSS, which drives this stage — the only thing added here is attributing a
-// failure to the plugin and the file that caused it.
+// failure to the plugin and the file that caused it. A LayoutError is the author's, so it passes through.
+
+import { LayoutError } from '../layoutError.js'
 
 const reason = cause => (cause instanceof Error ? cause.message : String(cause))
 
@@ -10,6 +12,7 @@ export const runCssPlugins = ({ plugins, root, context }) => {
             try {
                 plugin[phase]?.(root, context)
             } catch (cause) {
+                if (cause instanceof LayoutError) throw 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.
                 throw new Error(

package/src/transform/jsx/runPlugins.js

@@ -1,6 +1,8 @@
 // Runs the selected JSX plugins over one shared Program path, in order. Parsing and printing belong
 // to Babel, which drives this stage — the only thing added here is attributing a failure to the
-// plugin and the file that caused it.
+// plugin and the file that caused it. A LayoutError is the author's, so it passes through.
+
+import { LayoutError } from '../layoutError.js'
 
 const reason = cause => (cause instanceof Error ? cause.message : String(cause))
 
@@ -9,6 +11,7 @@ export const runJsxPlugins = ({ plugins, program, context }) => {
         try {
             plugin.transform(program, context)
         } catch (cause) {
+            if (cause instanceof LayoutError) throw 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.
             throw new Error(

package/src/transform/layoutError.js

@@ -0,0 +1,17 @@
+// A broken layout rule is the author's to fix, not a plugin crash. The stages pass it through as is,
+// without naming the plugin, and it carries no stack: the bundler already names the file, and the
+// messages say where in it.
+
+export class LayoutError extends Error {
+    /**
+     * @param {readonly string[]} violations
+     * @param {{ file?: string, line?: number, column?: number }} [location] The first violation's, which the
+     *     bundler prints as the error's position (Vite's CSS stage reads `file`, `line` and `column`).
+     */
+    constructor(violations, location = {}) {
+        super(violations.length === 1 ? violations[0] : `\n  ${violations.join('\n  ')}`)
+        this.name = 'LayoutError'
+        this.stack = ''
+        Object.assign(this, location)
+    }
+}

package/src/transform/pipeline.js

@@ -42,11 +42,16 @@ export const createTransformPipeline = ({ layout, jsxPlugins = defaultJsxPlugins
     const currentState = () => (state ??= createState({ layout, registries, command }))
     const contextFor = (id, options) => currentState().contextFactory(id, options)
     const selectFor = stage => context => currentState().selectPlugins(stage, context)
+    /** @type {Map<string, Set<string>>} stylesheet whose last CSS run failed -> the files it declared */
+    const cssFailures = new Map()
 
     return {
-        postcssPlugin: createCssPostcssPlugin({ contextFor, selectPlugins: selectFor('css') }),
+        postcssPlugin: createCssPostcssPlugin({ contextFor, selectPlugins: selectFor('css'), failures: cssFailures }),
         babelOptionsFor: createBabelOptionsSelector({ contextFor, selectPlugins: selectFor('jsx') }),
 
+        /** Whether a stylesheet whose last CSS run failed declared `file`, so an edit to it may fix the stylesheet. */
+        failedStylesheetDependsOn: file => [...cssFailures.values()].some(files => files.has(file)),
+
         setCommand: value => {
             command = value
             state = undefined

package/src/transform/types.js

@@ -31,9 +31,15 @@
  * and applied before any of them run.
  *
  * @typedef {TransformPluginBase & {
- *     validate?: (root: import('postcss').Root, context: TransformContext) => void,
- *     transform: (root: import('postcss').Root, context: TransformContext) => void
+ *     validate?: (root: import('postcss').Root, context: CssTransformContext) => void,
+ *     transform: (root: import('postcss').Root, context: CssTransformContext) => void
  * }} CssTransformPlugin
+ *
+ * @typedef {TransformContext & {
+ *     addDependency?: (file: string) => void
+ * }} CssTransformContext
+ * `addDependency` declares a file the plugin read besides the stylesheet, so the bundler re-runs the
+ * stylesheet when it changes. Absent when no bundler drives the run.
  */
 
 export {}

package/src/vitePlugins/siteDocumentsPlugin.js

@@ -1,7 +1,9 @@
 // The `wix-import-site` Vite plugin: serves route-matched documents in development, synthesizes one
-// virtual HTML entry per render target for the build.
+// virtual HTML entry per render target for the build, and reloads the page when a file a failing stylesheet read
+// changes.
 
 import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
 import { renderPageDocument } from '../routing/documentHtml.js'
 import { createDocumentMiddleware } from './documentMiddleware.js'
 
@@ -23,6 +25,13 @@ export const siteDocumentsPlugin = ({ layout, documents, pipeline }) => ({
             )
     },
 
+    // A file a CSS plugin read, like the structure file the stack check reads, is declared as a dependency of the
+    // stylesheet, so Vite hot-updates the stylesheet when it changes. Vite drops the declarations of a run that
+    // fails, though, so a stylesheet would keep its error after the file was fixed: the page is reloaded instead.
+    handleHotUpdate({ file, server }) {
+        if (pipeline.failedStylesheetDependsOn(resolve(file))) server.ws.send({ type: 'full-reload', path: '*' })
+    },
+
     resolveId(id) {
         return documents.has(id) ? id : undefined
     },