zyzz 0.0.19 → 0.0.21

package/src/vite/index.ts

@@ -69,6 +69,7 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
   const sourceEntrypoints = new Set<string>()
   const identities = new Map<string, string>()
   const lazyImports = new WeakMap<Parser.ParseResult, string[]>()
+  let directories: readonly string[]
   let root: string
 
   function snapshot(environment: Environment) {
@@ -94,12 +95,33 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
   function sourceId(file: string) {
     let id = identities.get(file)
     if (!id) {
-      id = `app/${Path.relative(root, file).split(Path.sep).join('/')}`
+      const directory = sourceRoot(file) ?? root
+      const namespace =
+        directory === root
+          ? 'app'
+          : `include-${directories.indexOf(directory) - 1}`
+      id = `${namespace}/${Path.relative(directory, file).split(Path.sep).join('/')}`
       identities.set(file, id)
     }
     return id
   }
 
+  // Included directories have portable namespaces rather than traversal IDs.
+  function sourceFile(id: string) {
+    const offset = id.indexOf('/')
+    const namespace = id.slice(0, offset)
+    const directory = (() => {
+      if (namespace === 'app') return root
+      if (/^include-\d+$/.test(namespace))
+        return directories[Number(namespace.slice(8)) + 1]
+      return undefined
+    })()
+
+    return directory === undefined
+      ? undefined
+      : Path.join(directory, id.slice(offset + 1))
+  }
+
   function resource(id: string) {
     const query = id.split('?')[1]?.split('#')[0]
 
@@ -119,17 +141,28 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
     if (sourceEntrypoints.has(normalize(id))) return true
     // Ids carrying foreign queries are Vite resources such as inline-module proxies, not source.
     if (resource(id)) return false
-    const relative = Path.relative(root, id)
 
     return (
       Path.isAbsolute(id) &&
-      !relative.startsWith('..') &&
-      !relative.split(Path.sep).includes('node_modules') &&
+      sourceRoot(id) !== undefined &&
       /\.[cm]?[jt]sx?$/.test(id) &&
-      !/\.(?:d|test|test-d|bench)\.[cm]?[jt]sx?$/.test(id)
+      !/\.(?:d|test|test-d|bench|bench-d)\.[cm]?[jt]sx?$/.test(id)
     )
   }
 
+  function sourceRoot(file: string) {
+    return directories.find((directory) => {
+      const relative = Path.relative(directory, file)
+
+      return (
+        relative !== '..' &&
+        !relative.startsWith(`..${Path.sep}`) &&
+        !Path.isAbsolute(relative) &&
+        !relative.split(Path.sep).includes('node_modules')
+      )
+    })
+  }
+
   function discover(environment: Environment, host: Host) {
     let pending = discoveries.get(environment)
 
@@ -137,10 +170,14 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
       pending = (async () => {
         const sources = new Map<string, string>()
         const eagerFiles = new Set<string>()
+        const visited = new Set<string>()
 
         contributionFiles.set(environment, eagerFiles)
 
         async function collect(directory: string): Promise<void> {
+          if (visited.has(directory)) return
+          visited.add(directory)
+
           for (const item of await Fs.readdir(directory, {
             withFileTypes: true,
           })) {
@@ -163,7 +200,7 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
             const file = Path.join(directory, item.name)
 
             if (item.isDirectory()) await collect(file)
-            else if (item.isFile() && eager(file)) {
+            else if (item.isFile() && eager(file, environment)) {
               host.watch(file)
 
               const source = await Fs.readFile(file, 'utf8')
@@ -175,7 +212,7 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
           }
         }
 
-        await collect(root)
+        for (const directory of directories) await collect(directory)
 
         return sources
       })()
@@ -185,10 +222,17 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
     return pending
   }
 
-  function eager(file: string) {
+  function eager(file: string, environment: Environment) {
     return (
       eligible(file) &&
-      !Path.relative(root, file)
+      file !== environment.config.configFile &&
+      !environment.config.configFileDependencies.includes(file) &&
+      // Server entrypoints must not contribute to the client stylesheet scan.
+      !(
+        environment.config.consumer === 'client' &&
+        /\.server\.[cm]?[jt]sx?$/.test(file)
+      ) &&
+      !Path.relative(sourceRoot(file)!, file)
         .split(Path.sep)
         .some((part) =>
           ['test', 'tests', '__tests__', 'fixtures', '__fixtures__'].includes(
@@ -323,7 +367,7 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
     }
 
     const pending = discoveries.get(environment)
-    if (!pending || !eager(file)) return
+    if (!pending || !eager(file, environment)) return
 
     const sources = await pending
 
@@ -733,7 +777,7 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
         map: {
           ...output.map,
           sources: output.map.sources.map((source) =>
-            source === null ? null : Path.join(root, source.slice(4)),
+            source === null ? null : (sourceFile(source) ?? source),
           ),
         },
       }
@@ -773,7 +817,7 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
     let line = 0
 
     for (const [id, output] of Object.entries(result.modules)) {
-      if (!connected.has(Path.join(root, id.slice(4)))) continue
+      if (!connected.has(sourceFile(id)!)) continue
       if (!output.css) continue
 
       for (const mapping of Mapping.allMappings(
@@ -788,7 +832,7 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
           const location = {
             generated,
             original: mapping.original,
-            source: Path.join(root, mapping.source.slice(4)),
+            source: sourceFile(mapping.source) ?? mapping.source,
           }
 
           if (mapping.name === undefined) Mapping.addMapping(map, location)
@@ -800,7 +844,7 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
         if (source !== null)
           Mapping.setSourceContent(
             map,
-            Path.join(root, source.slice(4)),
+            sourceFile(source) ?? source,
             output.cssMap.sourcesContent?.[index] ?? null,
           )
 
@@ -808,7 +852,6 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
       line += output.css.split('\n').length
     }
 
-    const appRoot = await Fs.realpath(root)
     const owners = new Map<string, string>()
 
     for (const id of new Set(Object.values(result.sharedAssetOwners ?? {}))) {
@@ -839,11 +882,9 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
       const raw = target.split(/[?#]/)[0]!
 
       const identity = result.sharedAssetOwners?.[key]
-      const path = target.startsWith('app/')
-        ? Path.join(root, decodeURIComponent(raw.slice(4)))
-        : Path.isAbsolute(raw)
-          ? decodeURIComponent(raw)
-          : undefined
+      const path =
+        sourceFile(decodeURIComponent(raw)) ??
+        (Path.isAbsolute(raw) ? decodeURIComponent(raw) : undefined)
       if (!path) throw new Error('Asset path escapes the Vite graph.')
 
       const asset = await (async () => {
@@ -852,11 +893,12 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
         } catch (error) {
           if (
             (error as NodeJS.ErrnoException).code !== 'ENOENT' ||
-            !identity?.startsWith('app/')
+            !identity ||
+            !sourceFile(identity)
           )
             throw error
 
-          const importer = Path.join(root, identity.slice(4))
+          const importer = sourceFile(identity)!
           const specifier = Path.relative(Path.dirname(importer), path)
             .split(Path.sep)
             .join('/')
@@ -872,11 +914,12 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
       })()
       const file = asset.file
 
-      const owner = identity?.startsWith('app/')
-        ? appRoot
-        : identity
-          ? owners.get(identity)
-          : undefined
+      const owner =
+        identity && sourceFile(identity)
+          ? sourceRoot(sourceFile(identity)!)
+          : identity
+            ? owners.get(identity)
+            : undefined
 
       const relative = owner ? Path.relative(owner, file) : '..'
       if (
@@ -961,7 +1004,7 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
     ) as Mapping.EncodedSourceMap
 
     sharedMap.sources = sharedMap.sources.map((source) =>
-      source?.startsWith('app/') ? Path.join(root, source.slice(4)) : source,
+      source === null ? null : (sourceFile(source) ?? source),
     )
 
     const output = result.modules[sourceId(entry.file)]!
@@ -982,7 +1025,7 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
       map: {
         ...output.map,
         sources: output.map.sources.map((source) =>
-          source === null ? null : Path.join(root, source.slice(4)),
+          source === null ? null : (sourceFile(source) ?? source),
         ),
       },
     }
@@ -1219,6 +1262,9 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
       },
     },
     configureServer(server) {
+      // Directory watches belong to the server, not module import dependencies.
+      server.watcher.add(directories.slice(1))
+
       server.middlewares.use((request, response, next) => {
         const path = new URL(request.url ?? '/', 'http://localhost').pathname
         const file = assets.get(path)
@@ -1236,8 +1282,21 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
         }, next)
       })
     },
-    configResolved(config) {
-      root = config.root
+    async configResolved(config) {
+      root = await Fs.realpath(config.root)
+      directories = [
+        root,
+        ...(await Promise.all(
+          (options.include ?? []).map(async (directory) => {
+            const file = await Fs.realpath(Path.resolve(root, directory))
+            if (!(await Fs.stat(file)).isDirectory())
+              throw new Error(
+                `Zyzz include paths must be directories: ${directory}`,
+              )
+            return file
+          }),
+        )),
+      ]
       if (native) return
       const lightning = (config.css.lightningcss ??= {})
       lightning.include =
@@ -1332,11 +1391,16 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
       await updateDiscovery(this.environment, file, change.event)
     },
     async hotUpdate({ file, modules, timestamp, type, server }) {
-      await updateDiscovery(this.environment, file, type)
-
       const state = entries(this.environment)
+      const previous = [...state.values()].map((entry) => ({
+        code: entry.code,
+        file: entry.file,
+        imports: entry.imports,
+      }))
+
+      await updateDiscovery(this.environment, file, type)
       const first = [...state.values()].find(
-        (entry) => entry.files.has(file) || eager(file),
+        (entry) => entry.files.has(file) || eager(file, this.environment),
       )
       if (!first && !removed.get(this.environment)?.has(file)) return modules
 
@@ -1358,31 +1422,51 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
               true,
             ).catch(() => undefined)
           : undefined
-      const affected = new Set(
-        modules.filter((module) => {
-          const entry = module.id && state.get(module.id)
-          return (
-            !output ||
-            !entry ||
-            entry.code !== output.modules[sourceId(entry.file)]?.code ||
-            entry.imports !==
+      const javascriptChanged = await (async () => {
+        if (!output) return true
+
+        // Portable build adapters share this module and do not require Vite.
+        const { transformWithOxc } = await import('vite')
+        const changed = await Promise.all(
+          previous.map(async (entry) => {
+            const code = output.modules[sourceId(entry.file)]?.code
+            if (
+              entry.imports !==
               JSON.stringify(output.imports[sourceId(entry.file)])
-          )
-        }),
+            )
+              return true
+            if (entry.code === code) return false
+            if (entry.code === undefined || code === undefined) return true
+
+            // Generated type assertions can change without changing runtime bindings.
+            const [before, after] = await Promise.all([
+              transformWithOxc(entry.code, entry.file, { sourcemap: false }),
+              transformWithOxc(code, entry.file, { sourcemap: false }),
+            ])
+            return before.code !== after.code
+          }),
+        )
+        return changed.some(Boolean)
+      })()
+      // Compiler-only inputs have watch edges, but their stylesheets update separately.
+      const affected = new Set(
+        modules.filter(
+          (module) =>
+            javascriptChanged ||
+            (module.id
+              ? !output?.modules[sourceId(module.id)]
+              : module.type !== 'asset'),
+        ),
       )
       const ids = new Set<string>()
       if (type === 'delete') ids.add(cssId(file))
 
       for (const entry of entries(this.environment).values()) {
-        if (!entry.files.has(file) && !eager(file)) continue
+        if (!entry.files.has(file) && !eager(file, this.environment)) continue
 
         // Theme scopes affect CSS even when Vite's JavaScript import was erased.
-        if (
-          !output ||
-          entry.code !== output.modules[sourceId(entry.file)]?.code ||
-          entry.imports !== JSON.stringify(output.imports[sourceId(entry.file)])
-        )
-          ids.add(entry.file)
+        // Rewritten importers can lose a source edge, so changed bindings must update together.
+        if (javascriptChanged) ids.add(entry.file)
         ids.add(cssId(entry.file))
         ids.add(sharedId)
       }
@@ -1635,6 +1719,8 @@ export declare namespace zyzz {
   type Options = {
     /** False retains authored calls and requires explicit identities where needed. */
     readonly compiler?: boolean | undefined
+    /** Additional source directories, absolute or relative to the Vite root. */
+    readonly include?: readonly string[] | undefined
     /** Native context captured at creation. Disables CSS delivery and initialization scripts. */
     readonly native?: Graph.compile.Options['native']
     /** Include the CSS reset. Defaults to false. */

package/src/web/Css.ts

@@ -4,6 +4,7 @@
  */
 import * as Targets from '../internal/Targets.js'
 import * as ClassName from './internal/ClassName.js'
+import * as Identity from '../internal/Identity.js'
 import * as Contributions from './internal/Contributions.js'
 import * as Binding from '../internal/Binding.js'
 import * as Cascade from '../internal/Cascade.js'
@@ -33,6 +34,7 @@ export function compile<
 >(
   options: compile.Options<name, themeName>,
 ): compile.ReturnType<name, themeName> {
+  const labels = options[ClassName.labels] ?? options.styles[ClassName.labels]
   options = {
     ...options,
     styles: { styles: options.styles.styles.map(Targets.web) },
@@ -417,6 +419,8 @@ export function compile<
 
   const identities = new Map<string, string>()
   const rules = new Map<string, string>()
+  type ConditionalRule = { conditions: readonly string[]; value: string }
+  const conditionalRules = new Map<string, ConditionalRule>()
   const identical = new Map<string, string>()
   const explicitBodies = new Map<string, string>()
   const selectors = new Map<string, string>()
@@ -470,12 +474,18 @@ export function compile<
 
     const names: string[] = explicit === undefined ? [] : [explicit]
     let ordinal = 0
-    const slots = new Map<string, number>()
-    const developmentName = options.scope
-      ? `definition-${styleIndex}`
-      : style.name
-
-    function emit(body: string, label: string, shared: boolean, output = mode) {
+    const cssName = labels?.[style.name]?.name ?? encode(style.name)
+    const cssNamespace =
+      labels?.[style.name]?.namespace ??
+      (options.scope ? Identity.name(options.scope) : undefined)
+
+    function emit(
+      body: string,
+      label: string,
+      shared: boolean,
+      output = mode,
+      conditional?: ConditionalRule,
+    ) {
       if (!body) return
 
       const independent =
@@ -483,12 +493,8 @@ export function compile<
         !options.development &&
         output === mode &&
         options.composition === 'independent'
-      const key = `${output}:${body}`
-      // Development slots belong to each style even when their initial values match.
-      const reusable =
-        explicit === undefined &&
-        !options.development &&
-        (shared || independent)
+      const key = JSON.stringify([cssNamespace, output, body])
+      const reusable = explicit === undefined && (shared || independent)
       const previous = reusable ? identical.get(key) : undefined
       if (previous && !names.includes(previous)) {
         names.push(previous)
@@ -498,43 +504,23 @@ export function compile<
       if (previous) shared = false
 
       // Contextual slots preserve authored ordering; development names survive value edits.
-      const ordinalSlot = ordinal++
-      const slot = options.development ? (slots.get(label) ?? 0) : ordinalSlot
-      slots.set(label, slot + 1)
+      const slot = ordinal++
       const identity = (() => {
         if (explicit !== undefined)
           return `${explicit}-${mode}-${encode(label)}-${slot}`
-        if (
-          output === 'grouped' &&
-          mode === 'grouped' &&
-          !options.development &&
-          options.composition === 'independent'
-        )
-          return `g_${rules.size.toString(36)}`
         if (output === 'grouped' && mode === 'grouped') {
-          const name = options.development ? developmentName : style.name
-          const scope =
-            options.development && options.scope
-              ? `_m${encode(options.scope)}`
-              : ''
-          return `g-${encode(name)}${scope}${slot ? `_s${slot}` : ''}`
+          return `z-${cssNamespace ? `${cssNamespace}-` : ''}${cssName}${slot ? `__${slot}` : ''}`
         }
         return ClassName.create({
           body,
-          context:
-            !shared || options.development
-              ? JSON.stringify([
-                  options.scope,
-                  mode,
-                  options.development ? developmentName : style.name,
-                ])
-              : options.scope,
+          context: !shared ? cssName : undefined,
+          namespace: cssNamespace,
           property: label,
-          slot: !shared || options.development ? slot : undefined,
-          stable: options.development,
+          slot: !shared ? slot : undefined,
         })
       })()
-      const owner = mode === 'atomic' ? `${style.name}:${slot}` : undefined
+      const owner =
+        mode === 'atomic' && !shared ? `${style.name}:${slot}` : undefined
       if (
         (rules.has(identity) && rules.get(identity) !== body) ||
         (owner !== undefined &&
@@ -543,12 +529,19 @@ export function compile<
       )
         diagnostics.push({
           code: 'identity_collision',
-          message: 'Distinct rules produced the same class identifier.',
+          message:
+            'Generated class names conflict. Supply distinct config or style ids.',
           path: [style.name],
         })
 
       if (owner !== undefined) identities.set(identity, owner)
       rules.set(identity, body)
+      if (
+        conditional?.conditions.some((condition) =>
+          /^@(media|supports)\b/.test(condition),
+        )
+      )
+        conditionalRules.set(identity, conditional)
       if (explicit !== undefined) selectors.set(identity, explicit)
       else {
         if (reusable) identical.set(key, identity)
@@ -611,7 +604,7 @@ export function compile<
           !nestedComposition &&
           !conditions.length &&
           groups.get(conflict(property)) !== false
-        emit(body, property, shared)
+        emit(body, property, shared, mode, { conditions, value })
       }
     }
 
@@ -673,7 +666,7 @@ export function compile<
             options.schemes ?? false,
             options[Themes.shared],
           )
-        : { classes: Object.freeze({}), css: '', resources: [] }
+        : { classes: Object.freeze({}), css: '', resources: [], rules: [] }
   } catch (error) {
     throw new CompileError([
       {
@@ -686,20 +679,57 @@ export function compile<
 
   const scopedCss = [
     scopes.css,
-    ...[...rules].map(
-      ([name, body]) => `.${selectors.get(name) ?? name}{${body}}`,
-    ),
+    ...[...rules].map((entry) => {
+      const [name, body] = entry
+      const selector = `.${ClassName.selector(selectors.get(name) ?? name)}`
+      const conditional = conditionalRules.get(name)
+      if (
+        !conditional ||
+        conditional.conditions.some(
+          (condition) =>
+            condition.startsWith('@') &&
+            !/^@(media|supports)\b/.test(condition),
+        )
+      )
+        return `${selector}{${body}}`
+
+      // Inactive conditions must surround the class rather than leave a matched empty wrapper.
+      const conditions = conditional.conditions.filter((condition) =>
+        condition.startsWith('@'),
+      )
+      const nested = conditional.conditions
+        .filter((condition) => !condition.startsWith('@'))
+        .reduceRight(
+          (body, condition) => `${condition}{${body}}`,
+          conditional.value,
+        )
+      return conditions.reduceRight(
+        (body, condition) => `${condition}{${body}}`,
+        `${selector}{${nested}}`,
+      )
+    }),
   ]
     .filter(Boolean)
     .join('\n')
 
-  return Object.freeze({
+  const result = {
     ...(scopes.resources.length ? { [Themes.shared]: scopes.resources } : {}),
     ...(contributionCss ? { contributionCss, scopedCss } : {}),
+    [ClassName.rules]: Object.freeze({
+      ...Object.fromEntries(rules),
+      ...Object.fromEntries(
+        scopes.rules.map((rule) => [
+          `@scope:${rule.selector.slice(1)}:${Identity.name(rule.property)}:${Identity.name(JSON.stringify(rule.conditions))}`,
+          rule.value,
+        ]),
+      ),
+    }),
     classes: Object.freeze(classes),
     css: [contributionCss, scopedCss].filter(Boolean).join('\n'),
     vars: scopes.classes as Readonly<Record<themeName, string>>,
-  })
+  }
+  Object.defineProperty(result, ClassName.rules, { enumerable: false })
+  return Object.freeze(result)
 }
 
 /** Input and output contracts for literal compilation. */
@@ -714,6 +744,8 @@ export declare namespace compile {
   > = {
     /** Separates generated token rules for hosts with independent CSS resources. */
     readonly [Themes.shared]?: 'all' | 'defaults' | undefined
+    /** Readable source bindings and consumer-owned configuration namespaces. */
+    readonly [ClassName.labels]?: ClassName.Labels | undefined
     /** Fixed class identities used by CSS-only consumers. */
     readonly names?: Readonly<Record<string, string>> | undefined
     /**
@@ -726,14 +758,14 @@ export declare namespace compile {
     /** CSS representation; atomic declarations are the default. */
     readonly cssOutput?: 'atomic' | 'grouped' | undefined
     readonly composition?: 'independent' | 'ordered' | undefined
-    /** Stable declaration names for CSS-only development updates. */
+    /** Retains live definitions for development updates. */
     readonly development?: boolean | undefined
     /**
      * Emit the `color-scheme` selection classes. Set by modules whose runtime
      * helpers can apply a scheme, so lowered `light-dark()` resolves there.
      */
     readonly schemes?: boolean | undefined
-    /** Optional module scope for independently delivered stylesheets. */
+    /** Explicit consumer-owned namespace for independently delivered stylesheets. */
     readonly scope?: string | undefined
     /** Ordered definitions; no themes or source adapter is required. */
     readonly styles: Style.Definition<name>
@@ -748,6 +780,8 @@ export declare namespace compile {
     name extends string = string,
     themeName extends string = string,
   > = {
+    /** Exact emitted rule bodies retained for graph-wide collision diagnostics. */
+    readonly [ClassName.rules]: Readonly<Record<string, string>>
     /** Shared token resources omitted from this module's stylesheet. */
     readonly [Themes.shared]?: readonly Themes.Resource[] | undefined
     /** Contribution text separated for graph-wide hoisting. */