zyzz 0.0.28 → 0.0.30

package/src/internal/Addon.ts

@@ -0,0 +1,118 @@
+/**
+ * Loads the Rust compiler addon for the current platform, falling back to its WebAssembly build.
+ * @module
+ */
+import * as Fs from 'node:fs'
+import * as Module from 'node:module'
+import * as Path from 'node:path'
+import * as Url from 'node:url'
+
+/** Functions the Rust addon exports. Structured values cross as JSON strings. */
+export type Exports = {
+  /** Runs a named compiler operation on UTF-8 JSON input and returns its UTF-8 JSON result. */
+  readonly call: (operation: string, input: string) => string
+  /** An incremental graph compiler whose caches live as long as the instance. */
+  readonly Graph: new () => {
+    /** Compiles one JSON graph snapshot and returns its JSON result. */
+    readonly compile: (input: string) => string
+  }
+  /** Version of the compiler crate, which also proves the addon loaded. */
+  readonly version: () => string
+}
+
+/** Thrown when no addon build loads for the current platform. */
+export class LoadError extends Error {
+  /** Lists every candidate and why it failed. */
+  constructor(failures: readonly (readonly [string, unknown])[]) {
+    super(
+      `Unable to load the Zyzz compiler addon for ${process.platform}-${process.arch}. Tried:\n${failures
+        .map(
+          ([candidate, error]) =>
+            `- ${candidate}: ${error instanceof Error ? error.message : String(error)}`,
+        )
+        .join('\n')}`,
+    )
+  }
+  /** Stable namespaced error identifier. */
+  override name = 'Addon.LoadError'
+}
+
+// Node caches native addons per process, so one resolved handle serves every caller.
+let loaded: Exports | undefined
+
+/**
+ * Returns the addon, resolving it on first use.
+ * Candidates are the repository's local build, the platform package, then the local and packaged
+ * WebAssembly builds.
+ * @returns The addon exports.
+ * @throws {LoadError} If no candidate loads.
+ */
+export function load(): Exports {
+  loaded ??= resolve()
+
+  return loaded
+}
+
+function resolve(): Exports {
+  const require = Module.createRequire(import.meta.url)
+  const directory = Path.dirname(Url.fileURLToPath(import.meta.url))
+  const failures: [string, unknown][] = []
+
+  for (const target of targets()) {
+    // Source and built modules both sit two levels below the package root.
+    const local = Path.resolve(
+      directory,
+      '../../binding',
+      `zyzz.${target}.node`,
+    )
+
+    for (const candidate of [local, `@zyzz/binding-${target}`]) {
+      if (candidate === local && !Fs.existsSync(local)) continue
+
+      try {
+        return require(candidate) as Exports
+      } catch (error) {
+        failures.push([candidate, error])
+      }
+    }
+  }
+
+  const wasi = Path.resolve(directory, '../../binding/wasi/zyzz.wasi.cjs')
+
+  for (const candidate of [wasi, '@zyzz/binding-wasm32-wasi']) {
+    if (candidate === wasi && !Fs.existsSync(wasi)) continue
+
+    try {
+      return require(candidate) as Exports
+    } catch (error) {
+      failures.push([candidate, error])
+    }
+  }
+
+  throw new LoadError(failures)
+}
+
+/** Lists the napi-rs platform suffixes this process can load, most specific first. */
+function targets(): readonly string[] {
+  const { arch, platform } = process
+
+  if (platform === 'darwin') return [`darwin-${arch}`, 'darwin-universal']
+  if (platform === 'win32') return [`win32-${arch}-msvc`]
+  if (platform === 'linux') return [`linux-${arch}-${musl() ? 'musl' : 'gnu'}`]
+
+  return [`${platform}-${arch}`]
+}
+
+/** Detects musl libc, whose binaries differ from glibc builds. */
+function musl(): boolean {
+  const report = process.report?.getReport() as
+    | { header?: { glibcVersionRuntime?: string } }
+    | undefined
+  if (report?.header?.glibcVersionRuntime) return false
+
+  try {
+    return Fs.readFileSync('/usr/bin/ldd', 'utf8').includes('musl')
+  } catch {
+    return true
+  }
+}

package/src/internal/Literal.ts

@@ -528,7 +528,8 @@ const fragmentation = {
     'verso',
   ],
 } as const
-const globals = new Set<string>([
+/** CSS-wide keywords accepted by every property. */
+export const globals = new Set<string>([
   'inherit',
   'initial',
   'revert',
@@ -744,7 +745,8 @@ export const namedColors = [
   'yellow',
   'yellowgreen',
 ] as const
-const systemColors = [
+/** Deprecated and current system color keywords. */
+export const systemColors = [
   'ActiveBorder',
   'ActiveCaption',
   'AppWorkspace',

package/src/internal/Token.ts

@@ -11,8 +11,8 @@ import type * as VariableSets from '../Vars.js'
 import * as Literal from './Literal.js'
 import * as VariableData from './VariableSets.js'
 
-// Ordered category fallbacks shared by runtime lookup and inferred token names.
-const propertyGroups = {
+/** Ordered category fallbacks shared by runtime lookup and inferred token names. */
+export const propertyGroups = {
   accentColor: ['accentColor', 'color'],
   animation: ['animate'],
   aspectRatio: ['aspect'],

package/src/internal/Vlq.ts

@@ -0,0 +1,59 @@
+/** Encodes and decodes one source map segment of Base64 VLQ fields. @module */
+
+const alphabet =
+  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
+const digits = new Map(
+  [...alphabet].map((character, index) => [character, index]),
+)
+
+/**
+ * Reads every field of one segment.
+ * @param segment - Base64 VLQ text between separators.
+ * @returns Each signed field, in order.
+ */
+export function decode(segment: string): number[] {
+  const fields: number[] = []
+  let shift = 0
+  let value = 0
+
+  for (const character of segment) {
+    const digit = digits.get(character)
+    if (digit === undefined) throw new Error('Invalid source map segment.')
+
+    value += (digit & 31) << shift
+
+    if (digit & 32) {
+      shift += 5
+      continue
+    }
+
+    fields.push(value & 1 ? -(value >>> 1) : value >>> 1)
+    shift = 0
+    value = 0
+  }
+
+  return fields
+}
+
+/**
+ * Writes the fields of one segment.
+ * @param fields - Signed fields, in order.
+ * @returns Base64 VLQ text without separators.
+ */
+export function encode(fields: readonly number[]): string {
+  let output = ''
+
+  for (const field of fields) {
+    let value = field < 0 ? (-field << 1) | 1 : field << 1
+
+    do {
+      let digit = value & 31
+
+      value >>>= 5
+      if (value > 0) digit |= 32
+      output += alphabet[digit]
+    } while (value > 0)
+  }
+
+  return output
+}

package/src/internal/Wasm.ts

@@ -0,0 +1,111 @@
+/**
+ * Instantiates the WebAssembly compiler synchronously from its bytes, for hosts without the native addon.
+ * @module
+ */
+
+/** Operations the WebAssembly module runs on UTF-8 JSON input. */
+export type Instance = {
+  /** Runs a named operation and returns its UTF-8 JSON result. */
+  readonly call: (operation: string, input: string) => string
+}
+
+type Exports = {
+  readonly memory: WebAssembly.Memory
+  readonly zyzz_alloc: (length: number) => number
+  readonly zyzz_call: (
+    operation: number,
+    operationLength: number,
+    input: number,
+    inputLength: number,
+  ) => bigint
+  readonly zyzz_free: (pointer: number, length: number) => void
+}
+
+/** Thrown when the module traps, with the panic message it printed. */
+export class TrapError extends Error {
+  /** Stable namespaced error identifier. */
+  override name = 'Wasm.TrapError'
+}
+
+/**
+ * Compiles and instantiates the module without awaiting, so synchronous APIs can call it.
+ * A trap leaves Rust state undefined, so the next call starts a fresh instance.
+ * @param bytes - The `crates/wasm` module.
+ * @returns The instance's operations.
+ */
+export function instantiate(bytes: BufferSource): Instance {
+  const module = new WebAssembly.Module(bytes)
+  const encoder = new TextEncoder()
+  const decoder = new TextDecoder()
+  let exports: Exports | undefined
+  let stderr = ''
+
+  function start(): Exports {
+    stderr = ''
+    // The reactor reads no files, clock, or environment. WASI output only carries panic messages.
+    const wasi = {
+      environ_get: () => 0,
+      environ_sizes_get: (count: number, size: number) => {
+        const view = new DataView(exports!.memory.buffer)
+        view.setUint32(count, 0, true)
+        view.setUint32(size, 0, true)
+        return 0
+      },
+      fd_write: (_: number, iovs: number, length: number, written: number) => {
+        const memory = exports!.memory.buffer
+        const view = new DataView(memory)
+        let total = 0
+        for (let index = 0; index < length; index++) {
+          const pointer = view.getUint32(iovs + index * 8, true)
+          const size = view.getUint32(iovs + index * 8 + 4, true)
+          stderr += decoder.decode(new Uint8Array(memory, pointer, size))
+          total += size
+        }
+        view.setUint32(written, total, true)
+        return 0
+      },
+      proc_exit: (code: number) => {
+        throw new TrapError(`WebAssembly compiler exited with code ${code}.`)
+      },
+    }
+    const instance = new WebAssembly.Instance(module, {
+      wasi_snapshot_preview1: wasi,
+    })
+    return instance.exports as unknown as Exports
+  }
+
+  function write(target: Exports, text: string): readonly [number, number] {
+    const bytes = encoder.encode(text)
+    const pointer = target.zyzz_alloc(bytes.length)
+    new Uint8Array(target.memory.buffer, pointer, bytes.length).set(bytes)
+    return [pointer, bytes.length]
+  }
+
+  return {
+    call(operation, input) {
+      const target = (exports ??= start())
+      try {
+        const [operationPointer, operationLength] = write(target, operation)
+        const [inputPointer, inputLength] = write(target, input)
+        const packed = target.zyzz_call(
+          operationPointer,
+          operationLength,
+          inputPointer,
+          inputLength,
+        )
+        const pointer = Number(packed >> 32n)
+        const length = Number(packed & 0xffffffffn)
+        const output = decoder.decode(
+          new Uint8Array(target.memory.buffer, pointer, length),
+        )
+        target.zyzz_free(pointer, length)
+        return output
+      } catch (error) {
+        exports = undefined
+        if (error instanceof WebAssembly.RuntimeError)
+          throw new TrapError(stderr.trim() || error.message, { cause: error })
+        throw error
+      }
+    },
+  }
+}

package/src/metro/transformer.ts

@@ -120,7 +120,6 @@ export function create(
               [Compilation.key]: {
                 compile: compiler.compile,
                 parse: snapshot.parse,
-                programs: snapshot.programs(graph.modules),
               },
             },
           ],

package/src/next/internal/Project.ts

@@ -1,10 +1,10 @@
 /** Retains filesystem snapshots and an incremental graph within a Next.js loader worker. @module */
-import * as Contract from '../../compiler/internal/Contract.js'
 import * as Contracts from '../../node/internal/Contracts.js'
 import * as Fs from 'node:fs/promises'
 import * as Graph from '../../compiler/Graph.js'
 import * as Path from 'node:path'
 import * as Reset from '../../node/Reset.js'
+import * as Results from '../../compiler/internal/Results.js'
 import * as Stylesheets from '../../compiler/internal/Stylesheets.js'
 import * as Syntax from '../../compiler/internal/Syntax.js'
 
@@ -80,7 +80,6 @@ export function create(options: create.Options) {
       if (tracked.has(file)) return
       tracked.add(file)
     }
-    const programs = new Map<string, ReturnType<typeof Syntax.parse>>()
     const reads = new Map<string, Promise<string>>()
     function read(file: string) {
       let pending = reads.get(file)
@@ -266,7 +265,6 @@ export function create(options: create.Options) {
       const links: Record<string, string | null> = Object.create(null)
       imports[name] = links
       const parsed = parse(name, modules[name]!)
-      programs.set(name, parsed)
 
       const resolutions = await Promise.all(
         parsed.program.body.map(async (node) => {
@@ -355,11 +353,7 @@ export function create(options: create.Options) {
       if (!library || library.source !== contracts[file]) {
         library = {
           source: contracts[file]!,
-          dependencies: Contract.read(
-            contracts[file]!,
-            new Map(),
-            file,
-          ).stylesheets.map((section) => section.dependency ?? []),
+          dependencies: Results.dependencies(contracts[file]!, file),
         }
         libraries.set(file, library)
       }
@@ -384,7 +378,6 @@ export function create(options: create.Options) {
     for (const file of Object.keys(contracts)) await dependencies(file)
 
     const graph = compiler.compile({
-      [Syntax.cache]: programs,
       [Stylesheets.entry]: id(context.resourcePath),
       contracts,
       development: options.development,

package/src/node/Host.ts

@@ -17,7 +17,6 @@ import * as Contracts from './internal/Contracts.js'
 import * as Relative from '../compiler/internal/Relative.js'
 import * as Scheme from '../internal/Scheme.js'
 import * as Snapshot from './internal/Snapshot.js'
-import * as Syntax from '../compiler/internal/Syntax.js'
 import * as Source from '../compiler/Source.js'
 import * as Transform from '../compiler/Transform.js'
 import * as ThemeRules from '../web/internal/Themes.js'
@@ -464,7 +463,6 @@ export async function create(options: create.Options): Promise<Runtime> {
       [ClassName.complete]: true,
       [ThemeRules.shared]:
         options.modules === false && !native ? 'all' : undefined,
-      [Syntax.cache]: snapshot.programs(modules),
       compiler: options.compiler,
       native,
       modules,

package/src/node/internal/Contracts.ts

@@ -2,7 +2,7 @@
 import * as Crypto from 'node:crypto'
 import * as Path from 'node:path'
 import * as Graph from '../../compiler/Graph.js'
-import * as Contract from '../../compiler/internal/Contract.js'
+import * as Results from '../../compiler/internal/Results.js'
 import * as Syntax from '../../compiler/internal/Syntax.js'
 
 /** Creates a reader whose derived contracts persist across the builds of one adapter instance. */
@@ -50,7 +50,6 @@ export function create() {
       Record<string, string | null>
     > = Object.create(null)
     const modules: Record<string, string> = Object.create(null)
-    const programs = new Map<string, ReturnType<typeof Syntax.parse>>()
     const next = new Set(active).add(file)
     let authored = false
 
@@ -67,10 +66,9 @@ export function create() {
       if (contract === undefined) return undefined
 
       contracts[target] = contract
-      for (const section of Contract.read(contract, new Map(), target)
-        .stylesheets) {
+      for (const dependency of Results.dependencies(contract, target)) {
         let owner = target
-        for (const specifier of section.dependency ?? []) {
+        for (const specifier of dependency) {
           const resolved = await options.resolve(specifier, owner)
           if (!resolved)
             throw new Error(
@@ -191,7 +189,6 @@ export function create() {
 
       const entry = await parse(path)
       modules[moduleId] = entry.source
-      programs.set(moduleId, entry.parsed)
       const links: Record<string, string | null> = Object.create(null)
       imports[moduleId] = links
 
@@ -290,7 +287,6 @@ export function create() {
     const graph = (() => {
       try {
         return Graph.compile({
-          [Syntax.cache]: programs,
           compiler: false,
           contracts,
           imports,

package/src/node/internal/Snapshot.ts

@@ -29,14 +29,6 @@ export function create() {
       syntax.delete(moduleId)
     },
     parse,
-    programs(modules: Readonly<Record<string, string>>) {
-      return new Map(
-        Object.entries(modules).map(([moduleId, source]) => [
-          moduleId,
-          parse({ moduleId, source }),
-        ]),
-      )
-    },
     async read(file: string) {
       try {
         const stat = await Fs.promises.stat(file, { bigint: true })

package/src/runtime/Composition.ts

@@ -29,39 +29,62 @@ export function create(options: create.Options) {
     ...input,
     classes: new Set(input.className.split(/\s+/).filter(Boolean)),
   }))
+  // Only conditional arguments select a precompiled case.
+  const conditional = inputs.some((input) => input.condition !== undefined)
 
   return (...entries: readonly Entry[]) => {
     let mask = 0
-    for (const [index, input] of inputs.entries())
-      if (input.condition !== undefined && entries[index])
-        mask |= 1 << input.condition
+    if (conditional)
+      for (let index = 0; index < inputs.length; index++) {
+        const condition = inputs[index]!.condition
+        if (condition !== undefined && entries[index]) mask |= 1 << condition
+      }
     const className = options.cases?.[mask] ?? options.className
-    const result: style.Props & Record<string, unknown> = {
-      className,
-    }
-    const external: string[] = []
-    const style: Record<string, string | number | undefined> = {}
-    for (const [index, entry] of entries.entries()) {
+    // Mutable while entries merge, then returned as immutable props.
+    const result: {
+      className: string
+      style?: Record<string, string | number | undefined>
+    } & Record<string, unknown> = { className }
+    let attributes = false
+    let external: string[] | undefined
+    let style: Record<string, string | number | undefined> | undefined
+    for (let index = 0; index < entries.length; index++) {
+      const entry = entries[index]
       if (!entry) continue
       const input = inputs[index]!
-      for (const owner of input.owners) {
-        for (const attribute of owner.attributes) delete result[attribute]
-        for (const slot of owner.slots) delete style[slot]
-      }
-      for (const name of entry.className.split(/\s+/))
-        if (name && !input.classes.has(name)) external.push(name)
-      for (const [name, value] of Object.entries(entry))
-        if (name.startsWith('data-')) result[name] = value
-      for (const [name, value] of Object.entries(entry.style ?? {})) {
-        // Reinsert overwritten keys so inline shorthand/longhand ordering follows arguments.
-        delete style[name]
-        style[name] = value
+      // Owners replace only what earlier entries added, so the first contributions skip deletion.
+      if (attributes || style)
+        for (const owner of input.owners) {
+          if (attributes)
+            for (const attribute of owner.attributes) delete result[attribute]
+          if (style) for (const slot of owner.slots) delete style[slot]
+        }
+      // An application's own class list adds nothing beyond the composition class.
+      if (entry.className !== input.className)
+        for (const name of entry.className.split(/\s+/))
+          if (name && !input.classes.has(name)) (external ??= []).push(name)
+      for (const name in entry)
+        if (name.startsWith('data-') && Object.hasOwn(entry, name)) {
+          result[name] = entry[name as `data-${string}`]
+          attributes = true
+        }
+      const inline = entry.style
+      if (inline) {
+        style ??= {}
+        for (const name in inline) {
+          if (!Object.hasOwn(inline, name)) continue
+          // Reinsert overwritten keys so inline shorthand/longhand ordering follows arguments.
+          delete style[name]
+          style[name] = inline[name as keyof typeof inline]
+        }
       }
     }
-    return {
-      ...result,
-      className: [className, ...external].filter(Boolean).join(' '),
-      ...(Object.keys(style).length ? { style } : {}),
+    result.className = external
+      ? [className, ...external].filter(Boolean).join(' ')
+      : className || ''
+    if (style && Object.keys(style).length) result.style = style
+    return result as style.Props & {
+      readonly [name: `data-${string}`]: string | undefined
     }
   }
 }

package/src/runtime/Recipe.ts

@@ -37,25 +37,32 @@ export type Payload = {
  */
 export function create(options: create.Options) {
   const props = Props.create({ className: options.className })
-  const axes = Object.keys(options.axes)
+  // Attribute names and defaults are fixed, so calls only read the selection.
+  const axes = Object.keys(options.axes).map((axis) => ({
+    attribute: `data-${axis}` as const,
+    axis,
+    fallback: Object.hasOwn(options.defaults, axis)
+      ? options.defaults[axis]
+      : undefined,
+  }))
 
   return (input: Record<string, unknown> & style.Options = {}) => {
     const overrides: style.Options = input
-    const result: style.Props & Record<`data-${string}`, string> = {
-      ...props(overrides),
-    }
+    // Props are fresh on every call, so selection attributes extend them in place.
+    const result = props(overrides) as style.Props &
+      Record<`data-${string}`, string>
 
-    for (const axis of axes) {
-      const selected = Object.hasOwn(input, axis) ? input[axis] : undefined
-      const value = (
-        selected === undefined
-          ? Object.hasOwn(options.defaults, axis)
-            ? options.defaults[axis]
-            : undefined
-          : selected
-      ) as string | boolean | null | undefined
+    for (const entry of axes) {
+      const selected = Object.hasOwn(input, entry.axis)
+        ? input[entry.axis]
+        : undefined
+      const value = (selected === undefined ? entry.fallback : selected) as
+        | string
+        | boolean
+        | null
+        | undefined
       if (value !== null && value !== undefined)
-        result[`data-${axis}`] = String(value)
+        result[entry.attribute] = String(value)
     }
 
     return options.html ? Html.from(result) : result

package/src/unplugin/index.ts

@@ -5,15 +5,14 @@ import * as Fs from 'node:fs/promises'
 import * as Path from 'node:path'
 import * as Reset from '../node/Reset.js'
 import * as Snapshot from '../node/internal/Snapshot.js'
-import * as Syntax from '../compiler/internal/Syntax.js'
 import { createUnplugin } from 'unplugin'
 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 Results from '../compiler/internal/Results.js'
 import * as Vite from '../vite/index.js'
 import * as ThemeRules from '../web/internal/Themes.js'
 
@@ -218,10 +217,12 @@ const portable = createUnplugin<Options | undefined, false>(
             })
             if (source === undefined) return false
             contracts[file] = source
-            const metadata = Contract.read(contracts[file]!, new Map(), file)
-            for (const section of metadata.stylesheets) {
+            for (const dependency of Results.dependencies(
+              contracts[file]!,
+              file,
+            )) {
               let owner = file
-              for (const specifier of section.dependency ?? []) {
+              for (const specifier of dependency) {
                 const target = await resolve(specifier, owner)
                 if (!target)
                   throw new Error(
@@ -289,7 +290,6 @@ const portable = createUnplugin<Options | undefined, false>(
           const result = compiler.compile({
             [ClassName.complete]: true,
             [ThemeRules.shared]: 'all',
-            [Syntax.cache]: snapshot.programs(modules),
             compiler: options.compiler,
             reset: options.reset ? Reset.read() : undefined,
             contracts,