@wix/origami-site-runtime 1.0.0

package/src/cssPlugins/spx/cascade.js

@@ -0,0 +1,41 @@
+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})`
+
+/** Compile settings and calls in place, retaining their cascade and source locations.
+ * @param {import('postcss').Declaration} declaration
+ */
+export const compileCascadeDeclaration = declaration => {
+    if (declaration.prop === '--spx-resolver-type') {
+        const resolver = declaration.value.trim()
+        if (!['scale', 'fixed'].includes(resolver)) throw declaration.error('Unsupported SPX resolver')
+        const value = resolver === 'scale' ? '1' : '0'
+        const previous = declaration.prev()
+        if (
+            previous?.type !== 'decl' ||
+            previous.prop !== '--origami-spx-scale' ||
+            previous.value !== value ||
+            previous.important !== declaration.important
+        ) {
+            declaration.before(declaration.clone({ prop: '--origami-spx-scale', value }))
+        }
+    }
+    if (
+        declaration.prop === '--spx-ref-width' &&
+        (!Number.isFinite(Number(declaration.value)) || Number(declaration.value) <= 0)
+    ) {
+        throw declaration.error('SPX reference width must be positive')
+    }
+    lowerCalls(
+        declaration,
+        number => {
+            if (number === 0) return '0px'
+            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/spx/index.js

@@ -0,0 +1,13 @@
+import { compileCascadeDeclaration } from './cascade.js'
+
+/** @type {import('../../transform/types.js').CssTransformPlugin} */
+export const spxPlugin = {
+    name: 'spx',
+    order: 20,
+    transform(root) {
+        root.walkAtRules('function', atRule => {
+            if (atRule.params.trimStart().startsWith('--spx(')) atRule.remove()
+        })
+        root.walkDecls(compileCascadeDeclaration)
+    },
+}

package/src/default-error-404.jsx

@@ -0,0 +1,9 @@
+import React from 'react'
+import { createRoot } from 'react-dom/client'
+import { DefaultError404 } from '@wix/builder-error-pages'
+import { PilerPage } from '@wix/builder-piler-components'
+import '@wix/builder-error-pages/style.css'
+
+createRoot(document.getElementById('root')).render(
+    React.createElement(React.StrictMode, null, React.createElement(PilerPage, { Page: DefaultError404 }))
+)

package/src/index.js

@@ -0,0 +1,4 @@
+export { createSiteViteConfig } from './siteViteConfig.js'
+export { cssPlugins } from './cssPlugins/index.js'
+export { jsxPlugins } from './jsxPlugins/index.js'
+export { pagesToRoutes } from './routing/pagesToRoutes.js'

package/src/jsxPlugins/index.js

@@ -0,0 +1,8 @@
+// The JSX stage's plugins, in no particular order — the pipeline sorts by each descriptor's
+// `order`. A descriptor needs a `name`, an `order`, and `transform(program, context)`, where
+// `program` is the Babel Program path for the module; see `../transform/types.js`.
+
+import { origamiCompatibilityPlugin } from './origamiCompatibility/index.js'
+
+/** @type {readonly import('../transform/types.js').JsxTransformPlugin[]} */
+export const jsxPlugins = Object.freeze([origamiCompatibilityPlugin])

package/src/jsxPlugins/origamiCompatibility/ast.js

@@ -0,0 +1,30 @@
+// Shared JSX/object-literal reads used by the compatibility rules.
+
+export const findAttribute = (attributes, name) =>
+    attributes.find(attribute => attribute.type === 'JSXAttribute' && attribute.name.name === name)
+
+const propertyName = property => {
+    if (property.computed) return undefined
+    if (property.key.type === 'Identifier') return property.key.name
+    if (property.key.type === 'StringLiteral') return property.key.value
+    return undefined
+}
+
+// Later duplicate keys win, matching how the object literal itself would evaluate.
+export const indexProperties = properties => {
+    const fields = new Map()
+    for (const property of properties) {
+        if (property.type !== 'ObjectProperty') continue
+        const name = propertyName(property)
+        if (name !== undefined) fields.set(name, property)
+    }
+    return fields
+}
+
+/** The object literal a JSX prop was given, or undefined when it is anything else. */
+export const objectPropValue = (openingElement, name) => {
+    const attribute = findAttribute(openingElement.attributes, name)
+    if (attribute?.value?.type !== 'JSXExpressionContainer') return undefined
+    const { expression } = attribute.value
+    return expression.type === 'ObjectExpression' ? expression : undefined
+}

package/src/jsxPlugins/origamiCompatibility/componentBindings.js

@@ -0,0 +1,43 @@
+// Which local names in a module refer to an Origami component the rules care about. Resolved by
+// import identity rather than by JSX tag name, so a local component that happens to share a name
+// with an Origami one is left alone.
+
+const ORIGAMI_MODULES = new Set(['document', 'document/components', 'wixEditorElements'])
+const COMPONENTS_DIRECTORY = 'components'
+
+const importedName = specifier => {
+    if (specifier.type !== 'ImportSpecifier') return undefined
+    return specifier.imported.type === 'Identifier' ? specifier.imported.name : specifier.imported.value
+}
+
+// A default import is an Origami component only when it comes from a bare `.../components/<Name>`
+// specifier; relative paths are the site's own global components.
+const defaultComponentName = source => {
+    if (source.startsWith('.') || source.startsWith('/')) return undefined
+
+    const segments = source.replace(/\/+$/u, '').split('/')
+    return segments.at(-2) === COMPONENTS_DIRECTORY ? segments.at(-1) : undefined
+}
+
+const componentName = (source, specifier) => {
+    if (specifier.type === 'ImportDefaultSpecifier') return defaultComponentName(source)
+    return ORIGAMI_MODULES.has(source) ? importedName(specifier) : undefined
+}
+
+/**
+ * @param {object} program
+ * @param {Map<string, readonly object[]>} rulesByComponent
+ * @returns {Map<string, readonly object[]>} local binding name -> rules to apply to it
+ */
+export const collectComponentBindings = (program, rulesByComponent) => {
+    const bindings = new Map()
+    for (const statement of program.body) {
+        if (statement.type !== 'ImportDeclaration') continue
+        for (const specifier of statement.specifiers) {
+            const name = componentName(statement.source.value, specifier)
+            const rules = name === undefined ? undefined : rulesByComponent.get(name)
+            if (rules !== undefined) bindings.set(specifier.local.name, rules)
+        }
+    }
+    return bindings
+}

package/src/jsxPlugins/origamiCompatibility/index.js

@@ -0,0 +1,48 @@
+// Bridges generated Origami structures to the piler component contract by forcing a few props onto
+// the components that need them.
+//
+// Each forced prop is a rule in `rules/`, declaring the components it applies to. That table is
+// also what defines which imported names count as Origami components, so adding a rule extends
+// import recognition with it — there is no second list to keep in sync.
+
+import { basename } from 'node:path'
+import { collectComponentBindings } from './componentBindings.js'
+import { containerPropsRule } from './rules/containerProps.js'
+import { richTextHtmlRule } from './rules/richTextHtml.js'
+
+const STRUCTURE_FILE = 'structure.jsx'
+
+const RULES = [containerPropsRule, richTextHtmlRule]
+
+/** Origami component name -> the rules that force props on it. */
+const RULES_BY_COMPONENT = new Map(
+    RULES.flatMap(rule => rule.components).map(component => [
+        component,
+        RULES.filter(rule => rule.components.includes(component)),
+    ])
+)
+
+/** @type {import('../../transform/types.js').JsxTransformPlugin} */
+export const origamiCompatibilityPlugin = {
+    name: 'wix-import-origami-compatibility',
+    order: 0,
+    appliesTo: context => basename(context.filePath) === STRUCTURE_FILE,
+
+    transform: program => {
+        // Import identity, not tag name, decides what is an Origami component — so a module that
+        // imports none cannot match a rule, and the tree is never walked.
+        const rulesByLocalName = collectComponentBindings(program.node, RULES_BY_COMPONENT)
+        if (rulesByLocalName.size === 0) return
+
+        program.traverse({
+            JSXOpeningElement(path) {
+                if (path.node.name.type !== 'JSXIdentifier') return
+
+                const rules = rulesByLocalName.get(path.node.name.name)
+                if (rules === undefined) return
+
+                for (const rule of rules) rule.apply(path.node)
+            },
+        })
+    },
+}

package/src/jsxPlugins/origamiCompatibility/rules/containerProps.js

@@ -0,0 +1,15 @@
+// Container components need a `containerProps` object to satisfy the piler component contract.
+
+import { types as t } from '@babel/core'
+import { findAttribute } from '../ast.js'
+
+export const containerPropsRule = {
+    components: ['Section', 'RefComponent', 'HeaderSection', 'FooterSection'],
+    apply: openingElement => {
+        if (findAttribute(openingElement.attributes, 'containerProps')) return
+
+        openingElement.attributes.push(
+            t.jsxAttribute(t.jsxIdentifier('containerProps'), t.jsxExpressionContainer(t.objectExpression([])))
+        )
+    },
+}

package/src/jsxPlugins/origamiCompatibility/rules/richTextHtml.js

@@ -0,0 +1,22 @@
+// Rich text needs an `html` field, which the export only provides as `text`.
+
+import { types as t } from '@babel/core'
+import { indexProperties, objectPropValue } from '../ast.js'
+
+export const richTextHtmlRule = {
+    components: ['WRichText'],
+    apply: openingElement => {
+        const richText = objectPropValue(openingElement, 'richText')
+        if (!richText) return
+
+        const fields = indexProperties(richText.properties)
+        if (fields.has('html')) return
+
+        // Only a literal text/linkList pair is safe to derive from statically.
+        const text = fields.get('text')
+        const linkList = fields.get('linkList')
+        if (text?.value.type !== 'StringLiteral' || linkList?.value.type !== 'ArrayExpression') return
+
+        richText.properties.push(t.objectProperty(t.identifier('html'), t.cloneNode(text.value, true)))
+    },
+}

package/src/routing/documentHtml.js

@@ -0,0 +1,19 @@
+// Fill the title and entry placeholders in src/site/document.html.
+const TITLE_PLACEHOLDER = '<!-- WIX_IMPORT_TITLE -->'
+const ENTRY_PLACEHOLDER = '<!-- WIX_IMPORT_ENTRY -->'
+const HTML_ENTITIES = Object.freeze({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })
+const escapeHtml = value => String(value).replace(/[&<>"']/g, character => HTML_ENTITIES[character])
+
+// Function replacements keep dollar sequences in data literal.
+const fillPlaceholder = (template, placeholder, value) => template.replace(placeholder, () => value)
+const renderEntryScript = entry =>
+    entry.startsWith('/')
+        ? `<script type="module" src="${escapeHtml(entry)}"></script>`
+        : `<script type="module">import ${JSON.stringify(entry).replace(/</g, '\\u003c')}</script>`
+
+export const renderPageDocument = ({ template, route }) =>
+    fillPlaceholder(
+        fillPlaceholder(template, TITLE_PLACEHOLDER, escapeHtml(route.title)),
+        ENTRY_PLACEHOLDER,
+        renderEntryScript(route.entry)
+    )

package/src/routing/pagesToRoutes.js

@@ -0,0 +1,110 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { basename, resolve } from 'node:path'
+import { parse } from '@babel/parser'
+import * as t from '@babel/types'
+import { runtimeDefaultError404Module, siteLayout } from './siteLayout.js'
+
+// Dev re-walks the pages on every document request, so a title is parsed again only when its
+// structure.jsx changed.
+/** @type {Map<string, { mtimeMs: number, title: string | undefined }>} */
+const titleCache = new Map()
+
+const pageTitle = (folder, fallback) => {
+    const structure = resolve(folder, 'structure.jsx')
+    if (!existsSync(structure)) return fallback
+    const { mtimeMs } = statSync(structure)
+    let cached = titleCache.get(structure)
+    if (cached?.mtimeMs !== mtimeMs) {
+        cached = { mtimeMs, title: readTitle(structure) }
+        titleCache.set(structure, cached)
+    }
+    return cached.title ?? fallback
+}
+
+const readTitle = structure => {
+    const ast = parse(readFileSync(structure, 'utf8'), { sourceType: 'module', plugins: ['jsx'] })
+    let title
+    t.traverseFast(ast, node => {
+        if (title !== undefined || !t.isJSXOpeningElement(node) || !t.isJSXIdentifier(node.name, { name: 'Page' }))
+            return
+        const data = node.attributes.find(
+            attribute => t.isJSXAttribute(attribute) && t.isJSXIdentifier(attribute.name, { name: 'data' })
+        )
+        if (
+            !t.isJSXAttribute(data) ||
+            !t.isJSXExpressionContainer(data.value) ||
+            !t.isObjectExpression(data.value.expression)
+        )
+            return
+        const property = data.value.expression.properties.find(
+            candidate =>
+                t.isObjectProperty(candidate) &&
+                !candidate.computed &&
+                (t.isIdentifier(candidate.key, { name: 'title' }) ||
+                    t.isStringLiteral(candidate.key, { value: 'title' }))
+        )
+        if (t.isObjectProperty(property) && t.isStringLiteral(property.value)) title = property.value.value
+    })
+    return title
+}
+
+const findPageItems = layout => {
+    const items = []
+    const walk = itemPath => {
+        const folder = resolve(layout.root, 'src', itemPath)
+        const entries = readdirSync(folder, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))
+        if (/^\[.*\]$/.test(basename(folder)) || entries.some(entry => entry.name === 'route.json'))
+            throw new Error(`Router pages are not supported yet: src/${itemPath}`)
+        if (entries.some(entry => entry.isFile() && !entry.name.startsWith('.'))) {
+            items.push({
+                itemPath,
+                title: pageTitle(folder, basename(folder).replace(/^\(([^()]+)\)$/, '$1')),
+                entry: `/src/${itemPath}/_generated/index.jsx`,
+            })
+        }
+        for (const entry of entries) {
+            if (
+                entry.isDirectory() &&
+                !entry.name.startsWith('.') &&
+                !['_generated', 'node_modules'].includes(entry.name)
+            )
+                walk(`${itemPath}/${entry.name}`)
+        }
+    }
+    if (existsSync(layout.pagesDir)) walk('pages')
+    return items
+}
+
+/** @returns {import('@wix/origami-types').RouteTable} */
+const buildRouteTable = items => {
+    const notFound = items.find(item => item.itemPath === 'pages/error404') ?? {
+        title: 'Page not found',
+        entry: runtimeDefaultError404Module,
+    }
+    const routes = items
+        .filter(item => item.itemPath !== 'pages/error404')
+        .map(item => ({
+            type: /** @type {const} */ ('static'),
+            url:
+                '/' +
+                item.itemPath
+                    .slice('pages/'.length)
+                    .split('/')
+                    .filter(segment => !/^\([^()]+\)$/.test(segment))
+                    .join('/'),
+            ...item,
+        }))
+    const pathsByUrl = new Map()
+    for (const route of routes) {
+        const previous = pathsByUrl.get(route.url)
+        if (previous) throw new Error(`Pages "${previous}" and "${route.itemPath}" both serve "${route.url}".`)
+        pathsByUrl.set(route.url, route.itemPath)
+    }
+    return { routes, notFound, popups: [] }
+}
+
+/** @returns {import('@wix/origami-types').RouteTable} */
+export const pagesToRoutes = root => {
+    const layout = siteLayout(root)
+    return buildRouteTable(findPageItems(layout))
+}

package/src/routing/siteLayout.js

@@ -0,0 +1,31 @@
+// Single source of truth for where things live: the on-disk shape of a generated site, and the
+// module id this package exposes to a generated site's browser bundle.
+
+import { createRequire } from 'node:module'
+import { isAbsolute, relative, resolve, sep } from 'node:path'
+
+export const runtimeDefaultError404Module = '@wix/origami-site-runtime/default-error-404'
+
+export const runtimeDefaultError404Path = createRequire(import.meta.url).resolve(runtimeDefaultError404Module)
+
+export const siteLayout = root => {
+    if (typeof root !== 'string' || !root) throw new TypeError('root must be a non-empty string.')
+    const rootPath = resolve(root)
+
+    return Object.freeze({
+        root: rootPath,
+        pagesDir: resolve(rootPath, 'src/pages'),
+        template: resolve(rootPath, 'src/site/document.html'),
+        outDir: 'dist',
+        documentId: url =>
+            url === undefined ? resolve(rootPath, '404.html') : resolve(rootPath, `.${url}`, 'index.html'),
+    })
+}
+
+// Path of `id` relative to the site root in posix form, or undefined when `id` escapes the root.
+export const relativeToSite = (root, id) => {
+    const filePath = id.split('?', 1)[0]
+    const fromRoot = relative(resolve(root), filePath)
+    if (!fromRoot || fromRoot === '..' || fromRoot.startsWith(`..${sep}`) || isAbsolute(fromRoot)) return undefined
+    return fromRoot.split(sep).join('/')
+}

package/src/routing/urlPath.js

@@ -0,0 +1,62 @@
+// URL path normalization shared by route declarations and incoming requests. A normalized path is
+// absolute, percent-decoded, and free of anything that could escape the route table: traversal
+// segments, embedded separators, control characters.
+
+const RESERVED_IN_RAW_PATH = /[\\?#]/
+const SEGMENT_SEPARATORS = '\\/?#'
+const HIGHEST_CONTROL_CODE = 0x1f
+const DELETE_CODE = 0x7f
+
+export class UrlPathError extends Error {
+    constructor(reason) {
+        super(reason)
+        this.name = 'UrlPathError'
+        this.reason = reason
+    }
+}
+
+const hasUnsafeCharacter = value => {
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index)
+        if (code <= HIGHEST_CONTROL_CODE || code === DELETE_CODE) return true
+        if (SEGMENT_SEPARATORS.includes(value[index])) return true
+    }
+    return false
+}
+
+const decodeSegment = segment => {
+    let decoded
+    try {
+        decoded = decodeURIComponent(segment)
+    } catch {
+        throw new UrlPathError('unsafe-segment')
+    }
+    if (decoded === '.' || decoded === '..' || hasUnsafeCharacter(decoded)) throw new UrlPathError('unsafe-segment')
+    return decoded
+}
+
+export const normalizeUrlPath = value => {
+    if (
+        typeof value !== 'string' ||
+        !value.startsWith('/') ||
+        RESERVED_IN_RAW_PATH.test(value) ||
+        value.includes('//')
+    ) {
+        throw new UrlPathError('not-absolute')
+    }
+
+    const trimmed = value === '/' ? value : value.replace(/\/+$/, '')
+    if (trimmed === '/') return trimmed
+
+    return `/${trimmed.slice(1).split('/').map(decodeSegment).join('/')}`
+}
+
+// Requests are attacker-controlled, so an unusable path is a routing outcome (404), not an error.
+export const normalizeRequestPath = requestUrl => {
+    if (typeof requestUrl !== 'string' || !requestUrl.startsWith('/')) return undefined
+    try {
+        return normalizeUrlPath(new URL(requestUrl, 'http://site.local').pathname)
+    } catch {
+        return undefined
+    }
+}

package/src/siteViteConfig.js

@@ -0,0 +1,91 @@
+// Vite configuration for a generated wix-import site: a multi-page app whose HTML entries are
+// derived from item folders.
+
+import { dirname, relative, sep } from 'node:path'
+import { defineConfig, searchForWorkspaceRoot } from 'vite'
+import { pagesToRoutes } from './routing/pagesToRoutes.js'
+import { itemFolderImports } from './vitePlugins/itemFolderImports.js'
+import { runtimeDefaultError404Path, siteLayout } from './routing/siteLayout.js'
+import { createTransformPipeline } from './transform/pipeline.js'
+import { reactBabelPlugin } from './vitePlugins/reactBabel.js'
+import { siteDocumentsPlugin } from './vitePlugins/siteDocumentsPlugin.js'
+
+const DEFAULT_DEVELOPMENT_PORT = 3000
+
+// One virtual HTML document per render target. The same table drives Rollup's inputs and the
+// plugin's resolveId/load pair, so build entries and served documents cannot drift apart.
+const collectPageDocuments = layout => {
+    const table = pagesToRoutes(layout.root)
+    const documents = new Map()
+    for (const route of table.routes) documents.set(layout.documentId(route.url), route)
+    documents.set(layout.documentId(), table.notFound)
+    return documents
+}
+
+const isStylesheet = asset => (asset.names?.[0] ?? asset.originalFileNames?.[0] ?? '').endsWith('.css')
+
+/**
+ * @param {{
+ *     root?: string,
+ *     jsxPlugins?: readonly import('./transform/types.js').JsxTransformPlugin[],
+ *     cssPlugins?: readonly import('./transform/types.js').CssTransformPlugin[],
+ * }} [options]
+ */
+export const createSiteViteConfig = ({ root, jsxPlugins, cssPlugins } = {}) => {
+    const layout = siteLayout(root)
+    const documents = collectPageDocuments(layout)
+    const pipeline = createTransformPipeline({
+        layout,
+        ...(jsxPlugins ? { jsxPlugins } : {}),
+        ...(cssPlugins ? { cssPlugins } : {}),
+    })
+
+    return defineConfig({
+        root: layout.root,
+        appType: 'custom',
+        // The host and user code must share service contexts and signal tracking scopes.
+        resolve: {
+            dedupe: [
+                'react',
+                'react-dom',
+                '@wix/services-manager-react',
+                '@wix/sdk-react-context',
+                '@preact/signals-react',
+                '@preact/signals-core',
+            ],
+        },
+        plugins: [
+            itemFolderImports(layout.root),
+            siteDocumentsPlugin({ layout, documents, pipeline }),
+            reactBabelPlugin({ pipeline }),
+        ],
+        // Stating the PostCSS plugins here also opts out of Vite's search for a project postcss
+        // config, which a generated site does not have. The CSS stage has to run as a PostCSS
+        // plugin rather than a Vite one — see transform/css/postcssPlugin.js.
+        css: { postcss: { plugins: [pipeline.postcssPlugin] } },
+        server: {
+            port: DEFAULT_DEVELOPMENT_PORT,
+            fs: { allow: [searchForWorkspaceRoot(layout.root), dirname(runtimeDefaultError404Path)] },
+        },
+        build: {
+            outDir: layout.outDir,
+            rollupOptions: {
+                input: Object.fromEntries(
+                    [...documents.keys()].map(id => [
+                        relative(layout.root, id)
+                            .split(sep)
+                            .join('/')
+                            .replace(/\.html$/, ''),
+                        id,
+                    ])
+                ),
+                output: {
+                    entryFileNames: 'js/[name]-[hash].js',
+                    chunkFileNames: 'js/[name]-[hash].js',
+                    assetFileNames: asset =>
+                        isStylesheet(asset) ? 'css/[name]-[hash][extname]' : 'assets/[name]-[hash][extname]',
+                },
+            },
+        },
+    })
+}

package/src/transform/context.js

@@ -0,0 +1,13 @@
+import { relativeToSite } from '../routing/siteLayout.js'
+
+export const createContextFactory =
+    ({ layout, command }) =>
+    (id, { ssr = false } = {}) =>
+        Object.freeze({
+            id,
+            filePath: id.split('?', 1)[0],
+            relativePath: relativeToSite(layout.root, id),
+            layout,
+            command,
+            ssr,
+        })

package/src/transform/css/postcssPlugin.js

@@ -0,0 +1,35 @@
+// The CSS stage, exposed as a PostCSS plugin rather than a Vite `transform` hook.
+//
+// That placement is load-bearing. A generated page imports one stylesheet that `@import`s the
+// Origami carriers (layout.css, style.css); Vite inlines those with its own postcss-import, which
+// reads them straight from disk and never runs plugin transform hooks over them. A Vite hook at
+// `enforce: 'pre'` therefore sees the page's `@import` statements and nothing else. Vite installs
+// postcss-import ahead of the configured PostCSS plugins, so by the time this one runs the
+// stylesheet the plugins see is the whole page: a rule declared in one carrier and a rule that
+// depends on it in another arrive in the same document.
+
+import { runCssPlugins } from './runPlugins.js'
+
+const DEPENDENCY_DIRECTORY = 'node_modules/'
+
+// The site's own files, and only those. A stylesheet outside the root belongs to a dependency; so
+// does one reached through the site's own node_modules, which merely happens to live inside it.
+const isSiteOwned = relativePath =>
+    relativePath !== undefined &&
+    !relativePath.startsWith(DEPENDENCY_DIRECTORY) &&
+    !relativePath.includes(`/${DEPENDENCY_DIRECTORY}`)
+
+export const createCssPostcssPlugin = ({ selectPlugins, contextFor }) => ({
+    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 plugins = selectPlugins(context)
+        if (plugins.length) runCssPlugins({ plugins, root, context })
+    },
+})

package/src/transform/css/runPlugins.js

@@ -0,0 +1,22 @@
+// 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.
+
+const reason = cause => (cause instanceof Error ? cause.message : String(cause))
+
+export const runCssPlugins = ({ plugins, root, context }) => {
+    for (const phase of ['validate', 'transform']) {
+        for (const plugin of plugins) {
+            try {
+                plugin[phase]?.(root, context)
+            } catch (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(
+                    `CSS transform "${plugin.name}" failed for ${context.relativePath ?? context.filePath}: ${reason(cause)}`,
+                    { cause }
+                )
+            }
+        }
+    }
+}