zyzz 0.0.23 → 0.0.25

package/src/react-native/internal/Store.ts

@@ -6,8 +6,12 @@ import * as React from 'react'
 export type Patch = {
   /** Runtime-local mounted view identifier. */
   readonly id: number
+  /** Mounted Fabric node, sent until the binding's first patch commits. */
+  readonly node?: object | undefined
   /** Processed native style properties. */
   readonly props: Record<string, unknown>
+  /** Processed style React rendered, sent with `node`. */
+  readonly rendered?: Record<string, unknown> | undefined
 }
 
 type Selection = {

package/src/react-native/internal/Viewport.ts

@@ -1,4 +1,5 @@
 /** Connects the native device adapter to framework subscriptions. @module */
+import type * as NativeContext from '../../runtime/NativeContext.js'
 import type * as Media from '../../runtime/internal/NativeMedia.js'
 import * as React from 'react'
 
@@ -6,3 +7,9 @@ import * as React from 'react'
 export const context = React.createContext<Media.Viewport | undefined>(
   undefined,
 )
+
+/** Device appearance for `colorScheme: 'system'`, with the platform's appearance-following color when it has one. */
+export const appearance = React.createContext<{
+  readonly adaptive?: NativeContext.Context['adaptive']
+  readonly colorScheme: 'dark' | 'light'
+}>({ colorScheme: 'light' })

package/src/react-native/react.ts

@@ -12,7 +12,6 @@ import * as Viewport from './internal/Viewport.js'
 export function defineConfig<const options extends Config.create.Options = {}>(
   options: options & Parameters<typeof Config.create<options>>[0] = {} as never,
 ): defineConfig.ReturnType<options> {
-  const config = Config.create<options>(options)
   const defaultVars = (options as Config.VariableOptions).defaultVars
   const names =
     defaultVars === undefined
@@ -29,10 +28,71 @@ export function defineConfig<const options extends Config.create.Options = {}>(
     })
   }
 
+  if ((options as Config.VariableOptions).vars === undefined)
+    return Object.freeze({
+      ...Config.create<options>(options),
+      Provider: BoundProvider,
+    }) as defineConfig.ReturnType<options>
+
+  // Compiled native styles and `useVars` read precompiled tables, so variable
+  // configurations build their authoring helpers on first runtime use.
+  let config: Helpers | undefined
+  const create = () =>
+    (config ??= (Config.create as (options: object) => Helpers)(options))
   return Object.freeze({
-    ...config,
+    get appearance() {
+      return create().appearance
+    },
     Provider: BoundProvider,
-  }) as defineConfig.ReturnType<options>
+    get script() {
+      return create().script
+    },
+    style: (...args: never[]) => create().style(...args),
+    variants: (...args: never[]) => create().variants(...args),
+    vars: deferred(() => create().vars),
+  }) as unknown as defineConfig.ReturnType<options>
+}
+
+/** Untyped view of a variable configuration's helpers. */
+type Helpers = {
+  readonly appearance: unknown
+  readonly script: unknown
+  readonly style: (...args: never[]) => unknown
+  readonly variants: (...args: never[]) => unknown
+  readonly vars: object
+}
+
+/** Forwards every operation to a value built on first use, mirroring it onto the proxy target so invariants hold. */
+function deferred<value extends object>(create: () => value): value {
+  const target = (() => {}) as unknown as value
+  let ready = false
+  function resolve() {
+    if (ready) return target
+    const value = create()
+    Object.defineProperties(target, Object.getOwnPropertyDescriptors(value))
+    Object.setPrototypeOf(target, Object.getPrototypeOf(value))
+    if (Object.isFrozen(value)) Object.freeze(target)
+    ready = true
+    return target
+  }
+  return new Proxy(target, {
+    apply: (_, self, args) =>
+      Reflect.apply(create() as (...args: unknown[]) => unknown, self, args),
+    defineProperty: (_, key, descriptor) =>
+      Reflect.defineProperty(resolve(), key, descriptor),
+    deleteProperty: (_, key) => Reflect.deleteProperty(resolve(), key),
+    get: (_, key) => Reflect.get(resolve(), key),
+    getOwnPropertyDescriptor: (_, key) =>
+      Reflect.getOwnPropertyDescriptor(resolve(), key),
+    getPrototypeOf: () => Reflect.getPrototypeOf(resolve()),
+    has: (_, key) => Reflect.has(resolve(), key),
+    isExtensible: () => Reflect.isExtensible(resolve()),
+    ownKeys: () => Reflect.ownKeys(resolve()),
+    preventExtensions: () => Reflect.preventExtensions(resolve()),
+    set: (_, key, value) => Reflect.set(resolve(), key, value),
+    setPrototypeOf: (_, prototype) =>
+      Reflect.setPrototypeOf(resolve(), prototype),
+  })
 }
 
 /** Native configuration helpers and inferred Provider props. */
@@ -62,23 +122,30 @@ export function Provider(props: Provider.Props) {
   if (Object.hasOwn(props, 'set'))
     throw new Error('Provider uses vars instead of set.')
   if (
-    (props.colorScheme !== 'light' && props.colorScheme !== 'dark') ||
+    (props.colorScheme !== 'light' &&
+      props.colorScheme !== 'dark' &&
+      props.colorScheme !== 'system') ||
     (props.vars !== undefined &&
       (typeof props.vars !== 'string' || !props.vars.trim()))
   )
     throw new Error(
-      'Native appearance requires a resolved light/dark scheme and a nonempty vars name.',
+      'Native appearance requires a light, dark, or system scheme and a nonempty vars name.',
     )
 
   const viewport = React.useContext(Viewport.context)
+  const system = React.useContext(Viewport.appearance)
+  const colorScheme =
+    props.colorScheme === 'system' ? system.colorScheme : props.colorScheme
+  const adaptive = props.colorScheme === 'system' ? system.adaptive : undefined
   const [store] = React.useState(() =>
-    Store.create({ colorScheme: props.colorScheme, set: props.vars, viewport }),
+    Store.create({ adaptive, colorScheme, set: props.vars, viewport }),
   )
   const [, publish] = React.useReducer((version: number) => version + 1, 0)
   const committed = React.useRef(props.children)
   const snapshot = store.getSnapshot()
   const pending =
-    snapshot.colorScheme !== props.colorScheme ||
+    snapshot.adaptive !== adaptive ||
+    snapshot.colorScheme !== colorScheme ||
     snapshot.set !== props.vars ||
     snapshot.viewport?.width !== viewport?.width ||
     snapshot.viewport?.height !== viewport?.height
@@ -89,9 +156,9 @@ export function Provider(props: Provider.Props) {
     // Keep the committed subtree until its selection is published. This avoids
     // rendering new application props with the previous store snapshot, without
     // mutating an external store during a potentially abandoned React render.
-    store.update({ colorScheme: props.colorScheme, set: props.vars, viewport })
+    store.update({ adaptive, colorScheme, set: props.vars, viewport })
     publish()
-  }, [children, pending, props.colorScheme, props.vars, store, viewport])
+  }, [adaptive, children, colorScheme, pending, props.vars, store, viewport])
 
   return React.createElement(Store.context.Provider, { value: store }, children)
 }
@@ -102,8 +169,11 @@ export declare namespace Provider {
   type Props = {
     /** Components that consume compiled native styling or values. */
     readonly children?: React.ReactNode | undefined
-    /** Resolved device scheme or an application override. */
-    readonly colorScheme: 'dark' | 'light'
+    /**
+     * Resolved device scheme, an application override, or `system` to follow the device.
+     * On iOS, `system` styles whose schemes differ only in color switch without updates.
+     */
+    readonly colorScheme: 'dark' | 'light' | 'system'
     /** Selected variables. Omission uses each configuration's default. */
     readonly vars?: string | undefined
   }

package/src/runtime/NativeContext.ts

@@ -7,6 +7,14 @@ const dependency = Symbol('zyzz.native.dependency')
 
 /** Render-local set and resolved appearance. */
 export type Context = {
+  /**
+   * Builds a color that follows the platform appearance. When present, styles whose
+   * light and dark selections differ only in color use it and need no scheme update.
+   * Must be stable, since adapted styles are cached per selection pair.
+   */
+  readonly adaptive?:
+    | ((light: string | number, dark: string | number) => unknown)
+    | undefined
   /** Resolved system appearance or an explicit override. */
   readonly colorScheme: 'dark' | 'light'
   /** Named compiled set; omission uses each configuration default. */
@@ -37,7 +45,15 @@ export function create<const tables extends Tables>(
     const set = context.set ?? defaultVars
     const table = tables[set] ?? fallback
     if (!table) throw new Error(`Unknown native set: ${set}.`)
-    return table[context.colorScheme](input!).style
+    const style = table[context.colorScheme](input!).style
+    if (!context.adaptive) return style
+    return (
+      adapt(
+        table.light(input!).style,
+        table.dark(input!).style,
+        context.adaptive,
+      ) ?? style
+    )
   }
   return bind(select, (context) => {
     const table = tables[context.set ?? defaultVars] ?? fallback
@@ -94,10 +110,10 @@ export function responsive<
 export function application(value: unknown, input?: unknown): unknown {
   return {
     [binding]: (context: Context) => resolve(value, context, input),
-    [dependency]: (context: Context) => [
-      ...key(value, context),
-      ...key(input, context),
-    ],
+    [dependency]: (context: Context) =>
+      input === undefined
+        ? key(value, context)
+        : [...key(value, context), ...key(input, context)],
   }
 }
 
@@ -117,6 +133,64 @@ export function key(value: unknown, context: Context): readonly unknown[] {
   return []
 }
 
+const adapted = new WeakMap<object, WeakMap<object, object | null>>()
+
+/** Merges selections that differ only in color, or returns undefined. Results keep their identity across schemes. */
+function adapt(
+  light: unknown,
+  dark: unknown,
+  color: NonNullable<Context['adaptive']>,
+): unknown {
+  if (light === dark) return light
+  if (!record(light) || !record(dark)) return undefined
+  let pairs = adapted.get(light)
+  if (!pairs) adapted.set(light, (pairs = new WeakMap()))
+  if (pairs.has(dark)) return pairs.get(dark) ?? undefined
+  const result: Record<string, unknown> | null = (() => {
+    const keys = Object.keys(light)
+    if (keys.length !== Object.keys(dark).length) return null
+    const merged: Record<string, unknown> = {}
+    for (const key of keys) {
+      if (!Object.hasOwn(dark, key)) return null
+      const [first, second] = [light[key], dark[key]]
+      if (equal(first, second)) merged[key] = first
+      else if (
+        (key === 'color' || key.endsWith('Color')) &&
+        (typeof first === 'string' || typeof first === 'number') &&
+        (typeof second === 'string' || typeof second === 'number')
+      )
+        merged[key] = color(first, second)
+      else return null
+    }
+    return merged
+  })()
+  const value = result && Object.freeze(result)
+  pairs.set(dark, value)
+  return value ?? undefined
+}
+
+function equal(left: unknown, right: unknown): boolean {
+  if (Object.is(left, right)) return true
+  if (Array.isArray(left))
+    return (
+      Array.isArray(right) &&
+      left.length === right.length &&
+      left.every((value, index) => equal(value, right[index]))
+    )
+  if (!record(left) || !record(right)) return false
+  const keys = Object.keys(left)
+  return (
+    keys.length === Object.keys(right).length &&
+    keys.every(
+      (key) => Object.hasOwn(right, key) && equal(left[key], right[key]),
+    )
+  )
+}
+
+function record(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
 function bind(
   select: (context: Context, input?: never) => unknown,
   read: (context: Context) => readonly unknown[],
@@ -125,10 +199,10 @@ function bind(
     return {
       style: {
         [binding]: (context: Context) => select(context, input),
-        [dependency]: (context: Context) => [
-          ...read(context),
-          ...key(input, context),
-        ],
+        [dependency]: (context: Context) =>
+          input === undefined
+            ? read(context)
+            : [...read(context), ...key(input, context)],
       },
     }
   }

package/src/unplugin/index.ts

@@ -11,8 +11,11 @@ import type { UnpluginBuildContext } from 'unplugin'
 import * as Graph from '../compiler/Graph.js'
 import * as AtRules from '../compiler/internal/AtRules.js'
 import * as Catalogs from '../compiler/internal/Catalogs.js'
+import * as ClassName from '../web/internal/ClassName.js'
 import * as Contract from '../compiler/internal/Contract.js'
+import * as Contracts from '../node/internal/Contracts.js'
 import * as Vite from '../vite/index.js'
+import * as ThemeRules from '../web/internal/Themes.js'
 
 /** Portable build configuration. Vite uses the options from `zyzz/vite` instead. */
 export type Options = {
@@ -31,6 +34,7 @@ const portable = createUnplugin<Options | undefined, false>(
   (options = {}, meta) => {
     const root = Path.resolve(options.root ?? process.cwd())
     const compiler = Graph.create()
+    const packages = Contracts.create()
     const snapshot = Snapshot.create()
     let graph: Graph.compile.ReturnType | undefined
     let pending: Promise<void> | undefined
@@ -203,20 +207,17 @@ const portable = createUnplugin<Options | undefined, false>(
             required = false,
           ): Promise<boolean> {
             if (Object.hasOwn(contracts, file)) return true
-            const sidecar = `${file}.zyzz.json`
 
-            files.add(sidecar)
-            try {
-              contracts[file] = await snapshot.read(sidecar)
-            } catch (error) {
-              if (
-                !required &&
-                (error as NodeJS.ErrnoException).code === 'ENOENT'
-              )
-                return false
-
-              throw error
-            }
+            const source = await packages.read(file, {
+              read(path) {
+                files.add(path)
+                return snapshot.read(path)
+              },
+              required,
+              resolve,
+            })
+            if (source === undefined) return false
+            contracts[file] = source
             const metadata = Contract.read(contracts[file]!, new Map(), file)
             for (const section of metadata.stylesheets) {
               let owner = file
@@ -284,7 +285,10 @@ const portable = createUnplugin<Options | undefined, false>(
             }
           }
 
+          // Only the combined stylesheet is emitted, so generated theme rules are shared once.
           const result = compiler.compile({
+            [ClassName.complete]: true,
+            [ThemeRules.shared]: 'all',
             [Syntax.cache]: snapshot.programs(modules),
             compiler: options.compiler,
             reset: options.reset ? Reset.read() : undefined,
@@ -351,6 +355,7 @@ const portable = createUnplugin<Options | undefined, false>(
             boundary: string,
             outputDirectory = '.',
             targets?: Readonly<Record<string, string>>,
+            emitted: ReadonlySet<string> = new Set(),
           ) {
             const urls = new Set<string>()
             AtRules.transform({
@@ -402,6 +407,18 @@ const portable = createUnplugin<Options | undefined, false>(
                 : { inputSourceMap: map, sourceMap: true }),
               visitor: {
                 Rule(rule) {
+                  // Shared rules repeat in each module that uses them, so keep the first.
+                  if (rule.type === 'style') {
+                    const [selector, ...others] = rule.value.selectors
+                    const [component, ...rest] = selector ?? []
+                    if (
+                      !others.length &&
+                      !rest.length &&
+                      component?.type === 'class' &&
+                      emitted.has(component.name)
+                    )
+                      return []
+                  }
                   if (rule.type !== 'import') return
                   const url = replacements.get(rule.value.url)
                   if (url) return AtRules.relocateImport(rule.value, url)
@@ -432,6 +449,7 @@ const portable = createUnplugin<Options | undefined, false>(
             },
           ]
           const seen = new Set<string>()
+          const units = new Set<string>()
           async function visit(id: string): Promise<void> {
             if (seen.has(id)) return
             seen.add(id)
@@ -439,12 +457,19 @@ const portable = createUnplugin<Options | undefined, false>(
               await visit(dependency)
             const output = result.modules[id]
             if (output) {
+              const names = [...(output[ClassName.units]?.values() ?? [])].map(
+                (decision) => decision.name,
+              )
               const processed = await stylesheet(
                 output.css,
                 JSON.stringify(output.cssMap),
                 Path.join(root, id.slice(4)),
                 await Fs.realpath(root),
+                '.',
+                undefined,
+                new Set(names.filter((name) => units.has(name))),
               )
+              for (const name of names) units.add(name)
               chunks.push({
                 code: Buffer.from(processed.code).toString(),
                 map: Buffer.from(processed.map!).toString(),
@@ -460,7 +485,7 @@ const portable = createUnplugin<Options | undefined, false>(
           let line = 0
           css = ''
           for (const chunk of chunks) {
-            if (!chunk.code) continue
+            if (!chunk.code.trim()) continue
             const traced = Mapping.fromMap(chunk.map)
             for (const mapping of Mapping.allMappings(traced)) {
               const generated = {

package/src/variants.ts

@@ -26,8 +26,9 @@ type ChoiceName<choices> = keyof choices extends infer key
       ? key
       : never
   : never
+/** `void` targets skip dynamic choice return types, which resolve through `Checked` and cycle when selections are read first. */
 type DynamicKeys<choices> = {
-  [key in keyof choices]: choices[key] extends (...args: never[]) => unknown
+  [key in keyof choices]: choices[key] extends (...args: never[]) => void
     ? key
     : never
 }[keyof choices]
@@ -36,7 +37,7 @@ type Choice<choices> =
   | {
       [key in DynamicKeys<choices>]: choices[key] extends (
         values: infer values,
-      ) => unknown
+      ) => void
         ? { readonly [name in key]: values } & {
             readonly [name in Exclude<keyof choices, key>]?: never
           }

package/src/vite/index.ts

@@ -5,6 +5,7 @@
 import * as Namespaces from '../compiler/internal/Namespaces.js'
 import * as AtRules from '../compiler/internal/AtRules.js'
 import * as Catalogs from '../compiler/internal/Catalogs.js'
+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'
@@ -51,6 +52,7 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
   const removed = new WeakMap<Environment, Set<string>>()
   const reads = new WeakMap<Environment, Map<string, string>>()
   const compilers = new WeakMap<Environment, Graph.create.ReturnType>()
+  const packages = Contracts.create()
 
   function compiler(environment: Environment) {
     let value = compilers.get(environment)
@@ -414,6 +416,16 @@ 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],
+    }
 
     async function visit(file: string, source?: string) {
       if (files.has(file)) return
@@ -512,19 +524,15 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
         }
         if (resolved.external || !eligible(resolved.id)) {
           const physical = resolved.id.split('?')[0]!.split('#')[0]!
-          const sidecar = `${physical}.zyzz.json`
-
-          if (Path.isAbsolute(physical) && /\.[cm]?[jt]sx?$/.test(physical)) {
-            try {
-              contracts[resolved.id] = await Fs.readFile(sidecar, 'utf8')
-              host.watch(sidecar)
-              files.add(sidecar)
-              resolutions[specifier] = resolved.id
-              continue
-            } catch (error) {
-              if ((error as NodeJS.ErrnoException).code !== 'ENOENT')
-                throw error
-            }
+          const contract =
+            Path.isAbsolute(physical) && /\.[cm]?[jt]sx?$/.test(physical)
+              ? await packages.read(physical, contractHost)
+              : undefined
+
+          if (contract !== undefined) {
+            contracts[resolved.id] = contract
+            resolutions[specifier] = resolved.id
+            continue
           }
 
           resolutions[specifier] = null
@@ -649,25 +657,19 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
           if (!Path.isAbsolute(physical) || !/\.[cm]?[jt]sx?$/.test(physical))
             continue
 
-          try {
-            const sidecar = `${physical}.zyzz.json`
+          const contract = await packages.read(physical, contractHost)
+          if (contract === undefined) continue
 
-            contracts[resolved.id] = await Fs.readFile(sidecar, 'utf8')
-            host.watch(sidecar)
-            files.add(sidecar)
+          contracts[resolved.id] = contract
 
-            // Discover the package contribution without compiling unrelated authoring
-            // expressions in an otherwise unreachable source file.
-            const discovery = `${sourceId(file)}.zyzz-discovery`
+          // Discover the package contribution without compiling unrelated authoring
+          // expressions in an otherwise unreachable source file.
+          const discovery = `${sourceId(file)}.zyzz-discovery`
 
-            modules[discovery] =
-              (modules[discovery] ?? '') +
-              `import ${JSON.stringify(specifier)};\n`
-            ;(imports[discovery] ??= Object.create(null))[specifier] =
-              resolved.id
-          } catch (error) {
-            if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
-          }
+          modules[discovery] =
+            (modules[discovery] ?? '') +
+            `import ${JSON.stringify(specifier)};\n`
+          ;(imports[discovery] ??= Object.create(null))[specifier] = resolved.id
         }
       }
 
@@ -713,13 +715,10 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
           imports[owner] ??= Object.create(null)
           imports[owner]![specifier] = target.id
 
-          if (!Object.hasOwn(contracts, target.id)) {
-            const sidecar = `${target.id.split(/[?#]/)[0]}.zyzz.json`
-
-            contracts[target.id] = await Fs.readFile(sidecar, 'utf8')
-            host.watch(sidecar)
-            files.add(sidecar)
-          }
+          contracts[target.id] ??= (await packages.read(
+            target.id.split(/[?#]/)[0]!,
+            { ...contractHost, required: true },
+          ))!
 
           await dependencies(target.id)
           owner = target.id