zyzz 0.0.27 → 0.0.29

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/Authoring.ts

@@ -10,6 +10,10 @@ import type * as Theme from './Theme.js'
 /** Private ownership used by uncompiled composition; never spread onto DOM props. */
 export const metadata = Symbol.for('zyzz.authoring')
 
+// Static definitions retain their style data so later compositions can read it,
+// including definitions created by another bundled copy of the runtime.
+const data = Symbol.for('zyzz.style')
+
 /** Identity and replaceable attribute/slot ownership for an applied definition. */
 export type Owner = {
   readonly name: string
@@ -77,24 +81,54 @@ export function create(
   if (!dynamic && !id && Object.keys(input as object).length === 0)
     Identity.requireId(undefined, 'Empty style')
 
-  if (id && !dynamic && options.theme)
-    Style.define({ style: body(input as Record<string, unknown>) } as never, {
-      vars: options.theme,
-    })
-  const className = id
-    ? `z-style-${id}`
-    : Identity.style(
-        (
-          Style.define as (
-            input: Record<string, unknown>,
-            options: Style.define.Options,
-          ) => Style.Definition
-        )(
-          { style: body(input as Record<string, unknown>) },
-          { vars: options.theme },
-        ).styles[0]!,
-        namespace,
-      )
+  const define = (input: unknown) =>
+    (
+      Style.define as (
+        input: Record<string, unknown>,
+        options: Style.define.Options,
+      ) => Style.Definition
+    )(
+      { style: body(input as Record<string, unknown>) },
+      { vars: options.theme },
+    ).styles[0]!
+
+  const style = (() => {
+    if (dynamic) return undefined
+    if (!Array.isArray(input)) return define(input)
+
+    // Mirrors compiled composition: each entry is one ordered declaration segment.
+    const rules: Style.Rule[] = []
+    for (const [index, entry] of (input as readonly unknown[]).entries()) {
+      if (typeof entry !== 'function') {
+        rules.push({ style: define(entry) })
+        continue
+      }
+
+      const style = Object.getOwnPropertyDescriptor(entry, data)?.value as
+        | Style.NamedStyle
+        | undefined
+      if (style) {
+        rules.push({ style })
+        continue
+      }
+
+      // Compiled callables carry only class names, so an explicit id names the composite.
+      if (id) return undefined
+
+      throw new Style.InvalidError([
+        {
+          code: 'invalid_structure',
+          message:
+            'Composition entries require literal objects or static style definitions. Compositions of compiled definitions require an explicit id, and variants and dynamic styles are applied with cx.',
+          path: [String(index)],
+        },
+      ])
+    }
+
+    return { name: 'style', declarations: [], rules } satisfies Style.NamedStyle
+  })()
+
+  const className = id ? `z-style-${id}` : Identity.style(style!, namespace)
   const props = Props.create({ className })
   const apply = (values?: style.Options & Record<string, unknown>) => {
     let result = props(values as style.Options)
@@ -124,6 +158,7 @@ export function create(
   Object.defineProperty(apply, Symbol.toPrimitive, {
     value: () => `.${className}`,
   })
+  if (style) Object.defineProperty(apply, data, { value: style })
   return apply as style.ReturnType
 }
 

package/src/internal/Configuration.ts

@@ -625,15 +625,52 @@ export type StyleFactory<
         ? [options?: style.DefinitionOptions]
         : [invalid: never, unavailable: never]
       : [invalid: never, unavailable: never]
-  ): style.Dynamic<values, output>
+    // 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<output>
+    : style.Dynamic<values, output>
   <const styles extends Record<string, unknown>>(
     styles: styles &
       NoInfer<Body<styles, tokens, layers, mappings>> &
       Completion.Properties<tokens>,
     options?: style.DefinitionOptions,
   ): style.ReturnType<output>
+  <const entries>(
+    styles: entries & Entries<entries, tokens, layers, mappings>,
+    ...options: entries extends readonly unknown[]
+      ? [options?: style.DefinitionOptions]
+      : [invalid: never, unavailable: never]
+  ): style.ReturnType<output>
 }
 
+// Composition entries are static definitions or checked literal objects.
+type Entries<
+  entries,
+  tokens extends Theme.Tokens,
+  layers extends string,
+  mappings extends Shorthands.Map,
+> = {
+  readonly [index in keyof entries]: Entry<
+    entries[index],
+    tokens,
+    layers,
+    mappings
+  >
+}
+
+// Distributes over mixed element unions so each member keeps its own contract.
+type Entry<
+  entry,
+  tokens extends Theme.Tokens,
+  layers extends string,
+  mappings extends Shorthands.Map,
+> = entry extends (...args: never) => unknown
+  ? style.Composable<entry>
+  : entry &
+      NoInfer<Body<entry, tokens, layers, mappings>> &
+      Completion.Properties<tokens>
+
 type Keys<styles> = styles extends unknown ? keyof styles : never
 
 /** Checked declaration body shared by configured styles and recipe choices. */

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',
@@ -1588,7 +1590,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/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 })