zyzz 0.0.26 → 0.0.28

package/src/internal/Literal.ts

@@ -1588,7 +1588,10 @@ const properties = {
   direction: { kind: 'enum', values: ['ltr', 'rtl'] },
   display: {
     kind: 'enum',
+    // The Compat Standard keeps the legacy box keywords that -webkit-line-clamp requires.
     values: [
+      '-webkit-box',
+      '-webkit-inline-box',
       'block',
       'block flex',
       'block flow',

package/src/internal/Theme.ts

@@ -38,6 +38,14 @@ export type StyleFactory<tokens extends Tokens> = {
       (values extends Binding.Inputs<values> ? unknown : never),
     options?: style.DefinitionOptions,
   ): style.Dynamic<values>
+  <const entries>(
+    styles: entries & {
+      readonly [index in keyof entries]: Entry<entries[index], tokens>
+    },
+    ...options: entries extends readonly unknown[]
+      ? [options?: style.DefinitionOptions]
+      : [invalid: never, unavailable: never]
+  ): style.ReturnType
   <const styles extends Record<string, unknown>>(
     styles: styles & NoInfer<Style.Accepted<styles, tokens>>,
     options?: style.DefinitionOptions,
@@ -56,6 +64,13 @@ export type StyleFactory<tokens extends Tokens> = {
   ): style.ReturnType
 }
 
+// Distributes over mixed element unions so each member keeps its own contract.
+type Entry<entry, tokens extends Tokens> = entry extends (
+  ...args: never
+) => unknown
+  ? style.Composable<entry>
+  : entry & NoInfer<Style.Accepted<entry, tokens>>
+
 /**
  * Defines scalar tokens and typography sets without defaults or environment access.
  * Colors currently use the supported literal color grammar; spacing and radius

package/src/styleFunction.ts

@@ -29,9 +29,21 @@ type VariableOptions<input> = input extends {
     }
   : unknown
 
+// Composition entries are static definitions or exact literal objects.
+type Entries<entries> = {
+  readonly [index in keyof entries]: Entry<entries[index]>
+}
+
+// Distributes over mixed element unions so each member keeps its own contract.
+type Entry<entry> = entry extends (...args: never) => unknown
+  ? style.Composable<entry>
+  : entry & NoInfer<Style.Accepted<entry, {}, true>> & Completion.Properties
+
 /**
  * Declares literal styles for source extraction. Requires a compile-time transform.
- * @param styles - Token-free literal CSS properties. Omit for an empty definition.
+ * An array composes static definitions and literal objects in order, so later entries
+ * win as later declarations do.
+ * @param styles - Token-free literal CSS properties, or an array of static definitions and literal objects. Omit for an empty definition.
  * @returns A callable style definition after source rewriting.
  * @throws {Error} When a definition needs an explicit identity and none is supplied.
  */
@@ -53,16 +65,29 @@ export function style<
       ? [options?: style.DefinitionOptions]
       : [invalid: never, unavailable: never]
     : [invalid: never, unavailable: never]
-): style.Dynamic<values>
+  // TypeScript types a call that matches no overload with this signature. Other
+  // inputs leave `callback` at its constraint, so their definitions stay static.
+): ((...args: never[]) => unknown) extends callback
+  ? style.ReturnType
+  : style.Dynamic<values>
 export function style<const styles extends Record<string, unknown>>(
   styles: styles &
     NoInfer<Style.Accepted<styles, {}, true>> &
     Completion.Properties,
   options?: style.DefinitionOptions,
 ): style.ReturnType
+export function style<const entries>(
+  styles: entries & Entries<entries>,
+  // Exclude non-array inputs by arity so they cannot mask object-property diagnostics.
+  ...options: entries extends readonly unknown[]
+    ? [options?: style.DefinitionOptions]
+    : [invalid: never, unavailable: never]
+): style.ReturnType
 export function style(
   styles?: unknown,
   options: style.DefinitionOptions = {},
+  // Matches the arity-gated overloads, whose invalid branches add parameters.
+  ..._: readonly never[]
 ): style.ReturnType {
   return Authoring.create(styles, options)
 }
@@ -73,6 +98,10 @@ type Reference = { readonly [identity]: true }
 
 /** Contracts for the literal authoring boundary. */
 export declare namespace style {
+  /** Accepts a static definition as a composition entry. Dynamic definitions and variants require cx. */
+  type Composable<entry> = entry extends Reference & (() => unknown)
+    ? entry
+    : ReturnType<Output>
   /** Stable identity for selectors and definitions that cannot be content-addressed. */
   type DefinitionOptions = { readonly id?: string | undefined }
   /** Callable compiled bindings with required scalar inputs and styling overrides. */

package/src/vite/index.ts

@@ -9,16 +9,24 @@ import * as Contracts from '../node/internal/Contracts.js'
 import * as Mapping from '@jridgewell/gen-mapping'
 import * as Lightning from 'lightningcss'
 import * as Crypto from 'node:crypto'
+import { existsSync } from 'node:fs'
 import * as Fs from 'node:fs/promises'
 import * as Path from 'node:path'
 import * as Reset from '../node/Reset.js'
-import { isBuiltin } from 'node:module'
+import { createRequire, isBuiltin } from 'node:module'
 import * as Parser from 'oxc-parser'
 import * as Walker from 'oxc-walker'
 import * as Snapshot from '../node/internal/Snapshot.js'
 import * as Syntax from '../compiler/internal/Syntax.js'
 import * as Scope from '../compiler/internal/Scope.js'
-import type { Environment, Plugin, Rollup, ViteDevServer } from 'vite'
+import type {
+  DevEnvironment,
+  Environment,
+  Plugin,
+  Rollup,
+  UserConfig,
+  ViteDevServer,
+} from 'vite'
 import * as Graph from '../compiler/Graph.js'
 import * as Source from '../compiler/Source.js'
 import * as ThemeRules from '../web/internal/Themes.js'
@@ -51,6 +59,7 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
   const states = new WeakMap<Environment, Map<string, Entry>>()
   const removed = new WeakMap<Environment, Set<string>>()
   const reads = new WeakMap<Environment, Map<string, string>>()
+  const lookups = new WeakMap<Environment, Lookups>()
   const compilers = new WeakMap<Environment, Graph.create.ReturnType>()
   const packages = Contracts.create()
 
@@ -71,8 +80,11 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
   const initializers = new WeakMap<Environment, Entry>()
   const sourceEntrypoints = new Set<string>()
   const identities = new Map<string, string>()
+  const exclusions = new Map<string, boolean>()
   const lazyImports = new WeakMap<Parser.ParseResult, string[]>()
   let directories: readonly string[]
+  let filter: (id: unknown) => boolean
+  let optimizeRuntime = false
   let root: string
 
   function snapshot(environment: Environment) {
@@ -149,10 +161,26 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
       Path.isAbsolute(id) &&
       sourceRoot(id) !== undefined &&
       /\.[cm]?[jt]sx?$/.test(id) &&
-      !/\.(?:d|test|test-d|bench|bench-d)\.[cm]?[jt]sx?$/.test(id)
+      !/\.(?:d|test|test-d|bench|bench-d)\.[cm]?[jt]sx?$/.test(id) &&
+      !excluded(id)
     )
   }
 
+  /** Matches excluded files inside source directories. Package files never match, so packed contracts stay readable. */
+  function excluded(id: string) {
+    const file = id.split(/[?#]/)[0]!
+    let value = exclusions.get(file)
+
+    // Vite's filter recompiles each glob per call, and every compile checks each import.
+    if (value === undefined) {
+      value =
+        Path.isAbsolute(file) && sourceRoot(file) !== undefined && !filter(file)
+      exclusions.set(file, value)
+    }
+
+    return value
+  }
+
   function sourceRoot(file: string) {
     return directories.find((directory) => {
       const relative = Path.relative(directory, file)
@@ -355,6 +383,7 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
     event: string,
   ) {
     reads.delete(environment)
+    lookups.delete(environment)
     if (event === 'delete') {
       if (entries(environment).has(file)) {
         let files = removed.get(environment)
@@ -392,9 +421,32 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
     allSources = false,
     everything = false,
   ) {
+    // Every compile visits the discovered project, so modules share lookups
+    // until the watcher reports a change. Full-project compiles look up afresh.
+    const cache = (() => {
+      const fresh: Lookups = { contracts: new Map(), resolutions: new Map() }
+      if (everything) return fresh
+
+      let value = lookups.get(entry.environment)
+      if (!value) {
+        value = fresh
+        lookups.set(entry.environment, value)
+      }
+      return value
+    })()
+
     async function resolve(source: string, importer: string) {
       if (isBuiltin(source)) return { id: source, external: true }
-      const resolved = await host.resolve(source, importer)
+
+      const key = `${importer}\0${source}`
+      let pending = cache.resolutions.get(key)
+      if (!pending) {
+        pending = host.resolve(source, importer)
+        cache.resolutions.set(key, pending)
+        pending.catch(() => cache.resolutions.delete(key))
+      }
+
+      const resolved = await pending
       if (!resolved) return resolved
 
       if (entry.environment.mode === 'dev') {
@@ -416,15 +468,41 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
     const lazy: Record<string, ReadonlySet<string>> = Object.create(null)
     const modules: Record<string, string> = Object.create(null)
     const files = new Set<string>()
-    const contractHost: Contracts.read.Options = {
-      read: async (file) => {
-        const source = await snapshot(entry.environment).read(file)
-        host.watch(file)
-        files.add(file)
-        return source
-      },
-      resolve: async (specifier, importer) =>
-        (await resolve(specifier, importer))?.id.split(/[?#]/)[0],
+
+    // A package contract derives from the files it reads and the resolutions
+    // above. A cached contract still makes this compile watch those files.
+    async function readContract(file: string, required = false) {
+      const key = `${required}\0${file}`
+      let pending = cache.contracts.get(key)
+      if (!pending) {
+        const read = new Set<string>()
+
+        pending = packages
+          .read(file, {
+            read: async (path) => {
+              const source = await snapshot(entry.environment).read(path)
+              read.add(path)
+              return source
+            },
+            required,
+            resolve: async (specifier, importer) =>
+              (await resolve(specifier, importer))?.id.split(/[?#]/)[0],
+          })
+          .then((contract) => ({ contract, files: read }))
+        cache.contracts.set(key, pending)
+        pending.catch(() => cache.contracts.delete(key))
+      }
+
+      const derived = await pending
+
+      for (const path of derived.files) {
+        if (files.has(path)) continue
+
+        files.add(path)
+        host.watch(path)
+      }
+
+      return derived.contract
     }
 
     async function visit(file: string, source?: string) {
@@ -522,11 +600,18 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
           await visit(resolved.id)
           continue
         }
+
+        // An excluded source stays a runtime import instead of deriving a package contract.
+        if (excluded(resolved.id)) {
+          resolutions[specifier] = null
+          continue
+        }
+
         if (resolved.external || !eligible(resolved.id)) {
           const physical = resolved.id.split('?')[0]!.split('#')[0]!
           const contract =
             Path.isAbsolute(physical) && /\.[cm]?[jt]sx?$/.test(physical)
-              ? await packages.read(physical, contractHost)
+              ? await readContract(physical)
               : undefined
 
           if (contract !== undefined) {
@@ -648,7 +733,11 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
             continue
 
           const resolved = await resolve(specifier, file)
-          if (!resolved || (!resolved.external && eligible(resolved.id)))
+          if (
+            !resolved ||
+            (!resolved.external && eligible(resolved.id)) ||
+            excluded(resolved.id)
+          )
             continue
 
           if (resource(specifier) || resource(resolved.id)) continue
@@ -657,7 +746,7 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
           if (!Path.isAbsolute(physical) || !/\.[cm]?[jt]sx?$/.test(physical))
             continue
 
-          const contract = await packages.read(physical, contractHost)
+          const contract = await readContract(physical)
           if (contract === undefined) continue
 
           contracts[resolved.id] = contract
@@ -715,9 +804,9 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
           imports[owner] ??= Object.create(null)
           imports[owner]![specifier] = target.id
 
-          contracts[target.id] ??= (await packages.read(
+          contracts[target.id] ??= (await readContract(
             target.id.split(/[?#]/)[0]!,
-            { ...contractHost, required: true },
+            true,
           ))!
 
           await dependencies(target.id)
@@ -995,10 +1084,10 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
   async function initializations(server: ViteDevServer) {
     const environment = server.environments.client
     reads.delete(environment)
+    lookups.delete(environment)
     const host: Host = {
       asset: async (file) => file,
-      resolve: (source, importer) =>
-        environment.pluginContainer.resolveId(source, importer),
+      resolve: resolver(environment),
       watch: (file) => server.watcher.add(file),
     }
     const sources = await discover(environment, host)
@@ -1189,10 +1278,17 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
   return {
     buildStart() {
       reads.delete(this.environment)
+      lookups.delete(this.environment)
     },
     config: {
       order: 'post',
-      handler(config) {
+      handler(config, env) {
+        // Ordered after other config hooks, so plugin-provided aliases are visible.
+        optimizeRuntime =
+          env.command === 'serve' &&
+          options.compiler !== false &&
+          installed(config)
+
         if (native) return
         // Inline color-scheme changes cannot initialize Lightning's lowered helpers.
         return {
@@ -1221,6 +1317,32 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
         }
       },
     },
+    configEnvironment: {
+      // Plugins without enforce settle their environment options first.
+      order: 'post',
+      handler(name, config) {
+        if (!optimizeRuntime) return
+
+        const optimizeDeps = config.optimizeDeps ?? {}
+        const consumer =
+          config.consumer ?? (name === 'client' ? 'client' : 'server')
+
+        // Vite defaults server environments to noDiscovery. An include list there
+        // would create an explicit optimizer that otherwise never exists.
+        if (optimizeDeps.noDiscovery ?? consumer === 'server') return
+        if (
+          optimizeDeps.include?.includes(runtime) ||
+          optimizeDeps.exclude?.some((id) => id === 'zyzz' || id === runtime)
+        )
+          return
+
+        // Vite scans authored source, so the runtime import that compilation
+        // adds first appears while a request transforms a module. Discovering
+        // it then re-runs the optimizer, and modules loaded before the re-run
+        // can keep a separate copy of a shared dependency such as React.
+        return { optimizeDeps: { include: [runtime] } }
+      },
+    },
     configureServer(server) {
       // Directory watches belong to the server, not module import dependencies.
       server.watcher.add(directories.slice(1))
@@ -1257,6 +1379,14 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
           }),
         )),
       ]
+
+      // Portable build adapters share this module and do not require Vite.
+      const { createFilter } = await import('vite')
+      const patterns = [...configFiles, ...(options.exclude ?? [])]
+
+      filter = createFilter(null, patterns, { resolve: root })
+      exclusions.clear()
+
       if (native) return
       const lightning = (config.css.lightningcss ??= {})
       lightning.include =
@@ -1370,8 +1500,7 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
           ? await compile(
               first,
               {
-                resolve: (source, importer) =>
-                  this.environment.pluginContainer.resolveId(source, importer),
+                resolve: resolver(this.environment),
                 watch: (file) => {
                   server.watcher.add(file)
                 },
@@ -1465,7 +1594,10 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
       const output = await compile(
         entry,
         {
-          resolve: (source, importer) => this.resolve(source, importer),
+          resolve:
+            this.environment.mode === 'dev'
+              ? resolver(this.environment)
+              : (source, importer) => this.resolve(source, importer),
           watch: (file) => this.addWatchFile(file),
           asset: async (file) => {
             const reference = this.emitFile({
@@ -1527,7 +1659,10 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
       const output = await compile(
         entry,
         {
-          resolve: (source, importer) => this.resolve(source, importer),
+          resolve:
+            this.environment.mode === 'dev'
+              ? resolver(this.environment)
+              : (source, importer) => this.resolve(source, importer),
           watch: (file) => this.addWatchFile(file),
           asset: async (file) => {
             const reference = this.emitFile({
@@ -1629,8 +1764,7 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
           return await documentCatalogs(
             html,
             context.filename,
-            (source, importer) =>
-              environment.pluginContainer.resolveId(source, importer),
+            resolver(environment),
             state,
           )
         })()
@@ -1666,7 +1800,81 @@ type Host = {
   watch: (file: string) => void
 }
 
+type Lookups = {
+  contracts: Map<
+    string,
+    Promise<{ contract: string | undefined; files: ReadonlySet<string> }>
+  >
+  resolutions: Map<string, ReturnType<Host['resolve']>>
+}
+
+/**
+ * Whether `zyzz/runtime` resolves inside node_modules from the Vite root. Vite
+ * optimizes a discovered import only there, so linked and aliased copies stay
+ * source modules beside the other entrypoints.
+ */
+function installed(config: UserConfig) {
+  const aliases = config.resolve?.alias ?? {}
+  const entries = Array.isArray(aliases)
+    ? aliases
+    : Object.entries(aliases).map(([find, replacement]) => ({
+        find,
+        replacement,
+      }))
+
+  // Matches Vite's alias semantics: a string entry covers its subpaths.
+  if (
+    entries.some((entry) =>
+      typeof entry.find === 'string'
+        ? runtime === entry.find || runtime.startsWith(`${entry.find}/`)
+        : entry.find.test(runtime),
+    )
+  )
+    return false
+
+  try {
+    const require = createRequire(
+      Path.join(Path.resolve(config.root ?? ''), 'package.json'),
+    )
+
+    // Vite keeps a symlinked package at its node_modules path, which Node dereferences.
+    if (config.resolve?.preserveSymlinks)
+      return (require.resolve.paths('zyzz') ?? []).some((directory) =>
+        existsSync(Path.join(directory, 'zyzz/package.json')),
+      )
+
+    return require.resolve(runtime).split(Path.sep).includes('node_modules')
+  } catch {
+    return false
+  }
+}
+
+// Vite forwards `scan` to `resolveId` hooks but leaves it out of its public types.
+type ScanOptions = NonNullable<
+  Parameters<DevEnvironment['pluginContainer']['resolveId']>[2]
+> & { scan: boolean }
+
+const scan: ScanOptions = { scan: true }
+
+/**
+ * Resolves imports read from source before other plugins transform their
+ * importers. Marking them as scans, as Vite's dependency scanner does, keeps the
+ * optimizer from discovering their dependencies and lets plugins tell them apart
+ * from imports that reach the module graph.
+ */
+function resolver(environment: DevEnvironment): Host['resolve'] {
+  return (source, importer) =>
+    environment.pluginContainer.resolveId(source, importer, scan)
+}
+
+// Vite and Vitest load their own configuration modules, which application code never imports.
+const configFiles = [
+  '**/vite.config.*',
+  '**/vitest.config.*',
+  '**/vitest.workspace.*',
+]
 const prefix = '\0zyzz:'
+const runtime = 'zyzz/runtime'
 const sharedId = `${prefix}shared.css`
 
 function cssId(file: string) {
@@ -1679,6 +1887,13 @@ export declare namespace zyzz {
   type Options = {
     /** False retains authored calls and requires explicit identities where needed. */
     readonly compiler?: boolean | undefined
+    /**
+     * Source modules left out of discovery and transforms. Globs resolve against the
+     * Vite root unless they start with `**`, and regular expressions test absolute paths.
+     * Imports of excluded modules stay runtime imports. Vite and Vitest configuration
+     * modules are always excluded.
+     */
+    readonly exclude?: readonly (RegExp | string)[] | 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. */

package/src/web/internal/Themes.ts

@@ -70,6 +70,7 @@ export function create() {
     const completeDefaults = new Set<Token.Contract>()
     const empty: string[] = []
     const rules: Rule[] = []
+    const varied = variedPaths(themes)
 
     for (const [name, theme] of Object.entries(themes)) {
       if (!name) throw new Error('Theme names must be nonempty.')
@@ -132,6 +133,12 @@ export function create() {
         const value = data.values[path]
         // A set sharing its contract with an extension lacks the extension's added paths.
         if (value === undefined) continue
+        // An inherited base reference resolves through its fallback, unless a sibling set overrides it.
+        if (
+          inherited(value, path, data.contract) &&
+          !varied.get(data.contract)?.has(path)
+        )
+          continue
 
         const label = path
         declarations.push({
@@ -258,9 +265,9 @@ export function create() {
     if ('default' in value) {
       // Separate fallback properties preserve extensions and resolve references within each scope.
       const base = literal(value.default, label, owner)
-      // Rule consolidation must not change existing variable identities.
+      // Rule consolidation must not change existing variable identities, so the name hashes the fallback's CSS.
       const css = `:where(*){--fallback:${base};}${conditionalCss(value, '--fallback', ':where(*)', label, owner)}`
-      const name = `${owner ? property(owner, label ?? 'value') : variable(undefined, label ?? 'value')}-fallback-${Identity.name(css)}`
+      const name = `${owner ? property(owner, label ?? 'value') : variable(undefined, label ?? 'value')}-fallback-${Identity.hash(css)}`
       const emitted: Rule[] = [
         { conditions: [], property: name, selector: ':where(*)', value: base },
       ]
@@ -410,6 +417,44 @@ export function scope(value: string, identity?: string): string {
   return `z-theme-${namespace}${Identity.name(value)}`
 }
 
+/** Whether a set's value is its base's own reference at the same path, as named extensions inherit. */
+function inherited(value: Token.Value, path: string, contract: Token.Contract) {
+  return Token.is(value) && value.path === path && value.contract !== contract
+}
+
+/** Paths whose values differ between sets that share a contract. */
+function variedPaths(
+  themes: Readonly<Record<string, Theme.Definition | Vars.Definition>>,
+) {
+  const seen = new Map<Token.Contract, Map<string, string>>()
+  const varied = new Map<Token.Contract, Set<string>>()
+
+  for (const theme of Object.values(themes)) {
+    const data = Object.getOwnPropertyDescriptor(theme, Token.definition)
+      ?.value as Token.Metadata | undefined
+    if (!data) continue
+
+    const values = seen.get(data.contract) ?? new Map<string, string>()
+    seen.set(data.contract, values)
+
+    for (const [path, value] of Object.entries(data.values)) {
+      const key = Token.is(value)
+        ? JSON.stringify([value.contract[Token.identity], value.path])
+        : JSON.stringify(value)
+      const previous = values.get(path)
+
+      if (previous === undefined) values.set(path, key)
+      else if (previous !== key) {
+        const paths = varied.get(data.contract) ?? new Set<string>()
+        paths.add(path)
+        varied.set(data.contract, paths)
+      }
+    }
+  }
+
+  return varied
+}
+
 function variable(identity: string | undefined, path: string): string {
   const namespace = identity?.startsWith('id-') ? `${identity.slice(3)}-` : ''
   return `--z-${namespace}${path.split('.').map(Identity.name).join('-')}`