zyzz 0.0.33 → 0.0.34

package/src/compiler/internal/Results.ts

@@ -8,13 +8,13 @@ import * as Variants from '../../react-native/Variants.js'
 import * as Css from '../../web/Css.js'
 import * as ClassName from '../../web/internal/ClassName.js'
 import * as Engine from '../../web/internal/Engine.js'
-import * as ThemeRules from '../../web/internal/Themes.js'
 import * as Wire from '../../web/internal/Wire.js'
 import type * as Graph from '../Graph.js'
 import * as Native from '../Native.js'
 import * as Source from '../Source.js'
 import type * as Transform from '../Transform.js'
 import * as Edits from './Edits.js'
+import * as Modules from './Modules.js'
 import * as Stylesheets from './Stylesheets.js'
 
 /** A failure as the engine encodes it. */
@@ -25,16 +25,6 @@ type Failure = {
   readonly source?: string | undefined
 }
 
-/** One module's transform output as the engine encodes it. */
-export type Module = Records & {
-  readonly code: string
-  readonly css: string
-  readonly cssMap: Mapping.EncodedSourceMap
-  readonly map: Transform.compile.ReturnType['map']
-  readonly shared?: readonly ThemeRules.Resource[] | undefined
-  readonly vars: Readonly<Record<string, string>>
-}
-
 /** One native graph module as the engine encodes it. */
 type NativeModule = {
   readonly code: string
@@ -50,13 +40,6 @@ export type NativeOutput = {
   readonly recipes: Readonly<Record<string, unknown>>
 }
 
-/** A module's class, rule, and unit records as the engine encodes them. */
-type Records = {
-  readonly classes: Readonly<Record<string, string>>
-  readonly rules: Readonly<Record<string, string>>
-  readonly units: readonly (readonly [string, boolean, string])[]
-}
-
 /** One rendered stylesheet as the engine encodes it. */
 type Rendered = {
   readonly assets: Readonly<Record<string, string>>
@@ -73,7 +56,7 @@ type Rendered = {
 export type Output = {
   readonly contracts: Readonly<Record<string, string>>
   readonly dependencies: Readonly<Record<string, readonly string[]>>
-  readonly modules: Readonly<Record<string, Module | NativeModule | 0>>
+  readonly modules: Readonly<Record<string, Modules.Encoded | NativeModule | 0>>
   readonly packed?: readonly Rendered[] | undefined
   readonly prune?: true | undefined
   readonly reset?: Rendered | undefined
@@ -116,10 +99,10 @@ export function transform(
   const split = text.indexOf('\0')
 
   // Failures write no records, and decoding throws them.
-  if (split === -1) return module(decode<Module>(text), source)
+  if (split === -1) return Modules.decode(decode<Modules.Encoded>(text), source)
 
-  return module(
-    decode<Omit<Module, keyof Records>>(text.slice(0, split)),
+  return Modules.decode(
+    decode<Omit<Modules.Encoded, keyof Modules.Records>>(text.slice(0, split)),
     source,
     text.slice(split + 1),
   )
@@ -227,7 +210,7 @@ export function graph(
         if (encoded === 0) return decoded!.get(id)!
         if ('edits' in encoded) return nativeModule(encoded)
 
-        return module(encoded)
+        return Modules.decode(encoded)
       })(),
     ]),
   )
@@ -281,74 +264,6 @@ export function graph(
 /** Graph option for hosts that read module code, stylesheets, and configuration catalogs only. */
 export const lean = Symbol('lean graph output')
 
-/**
- * Rebuilds one module's frozen transform output. Records decode when first read, so a module
- * whose classes, rules, and units are never read skips their parsing.
- * @param value - The encoded module, with its records unless `records` holds them.
- * @param source - Module text the engine left out of the maps' `sourcesContent`.
- * @param records - The encoded records, which `transform.compile` writes apart.
- * @returns The output `Transform.compile` returns.
- */
-export function module(
-  value: Omit<Module, keyof Records> & Partial<Records>,
-  source?: string | undefined,
-  records?: string | undefined,
-): Transform.compile.ReturnType {
-  // The engine writes `0` for content the caller supplied separately, so it crosses once.
-  if (source !== undefined)
-    for (const map of [value.cssMap, value.map]) {
-      const contents = map.sourcesContent as (string | null | 0)[] | undefined
-
-      for (let index = 0; index < (contents?.length ?? 0); index++)
-        if (contents![index] === 0) contents![index] = source
-    }
-
-  let decoded: Records | undefined =
-    records === undefined ? (value as Records) : undefined
-  let classes: Transform.compile.ReturnType['classes'] | undefined
-  let rules: Transform.compile.ReturnType[typeof ClassName.rules] | undefined
-  let units: Transform.compile.ReturnType[typeof ClassName.units] | undefined
-  const read = () => (decoded ??= JSON.parse(records!) as Records)
-
-  const result = {
-    ...(value.shared
-      ? {
-          [ThemeRules.shared]: Object.freeze(
-            value.shared.map((resource) => Object.freeze(resource)),
-          ),
-        }
-      : {}),
-    // Parsed records are fresh, so they freeze in place rather than as copies.
-    get classes() {
-      return (classes ??= Object.freeze(read().classes))
-    },
-    code: value.code,
-    css: value.css,
-    cssMap: value.cssMap,
-    map: value.map,
-    vars: Object.freeze(Object.setPrototypeOf(value.vars, null)),
-  }
-
-  Object.defineProperties(result, {
-    [ClassName.rules]: {
-      enumerable: false,
-      get: () => (rules ??= Object.freeze(read().rules)),
-    },
-    [ClassName.units]: {
-      enumerable: false,
-      get: () =>
-        (units ??= new Map(
-          read().units.map(([key, borrowed, name]) => [
-            key,
-            { borrowed, name },
-          ]),
-        )),
-    },
-  })
-
-  return Object.freeze(result) as Transform.compile.ReturnType
-}
-
 /**
  * Encodes native options as the engine reads them. Sets are written in the `Css.compile` wire
  * format, so the engine decodes them as it decodes literal definitions.

package/src/compiler/wasm/Graph.ts

@@ -0,0 +1,178 @@
+/**
+ * Compiles source graphs in the WebAssembly compiler, for browsers and workers without the native
+ * addon. The host loads the module, and compilation reads no files and imports no Node built-ins.
+ * @module
+ */
+import type * as Css from '../../web/Css.js'
+import * as Wasm from '../../internal/Wasm.js'
+import type * as Graph from '../Graph.js'
+import * as Modules from '../internal/Modules.js'
+import type * as Source from '../Source.js'
+
+/** A failure as the engine encodes it. */
+type Failure = {
+  readonly diagnostics?: readonly CompileError.Diagnostic[] | undefined
+  readonly message: string
+  readonly name: string
+}
+
+/** A web graph result as the engine encodes it. */
+type Output = {
+  readonly contracts: Readonly<Record<string, string>>
+  readonly dependencies: Readonly<Record<string, readonly string[]>>
+  readonly modules: Readonly<Record<string, Modules.Encoded>>
+  readonly shared?: Shared | undefined
+}
+
+/** Shared contributions and responsive token defaults as the engine encodes them. */
+type Shared = {
+  readonly assets: Readonly<Record<string, string>>
+  readonly css: string
+  readonly map: NonNullable<Graph.compile.ReturnType['sharedCssMap']>
+  readonly owners: Readonly<Record<string, string>>
+}
+
+/** Contracts of one web graph compilation. */
+export declare namespace compile {
+  /** Failures the compiler reports, and a trap of the WebAssembly module. */
+  type ErrorType = CompileError | Wasm.TrapError
+  /** The web options of `Graph.compile` from `zyzz/compiler`. */
+  type Options = Pick<
+    Graph.compile.Options,
+    | 'compiler'
+    | 'composition'
+    | 'contracts'
+    | 'cssOutput'
+    | 'development'
+    | 'imports'
+    | 'modules'
+  >
+  /** The output of `Graph.compile` from `zyzz/compiler` for the same options. */
+  type ReturnType = Graph.compile.ReturnType
+}
+
+/**
+ * A graph the compiler rejects. `failure` names the error that `Graph.compile` from
+ * `zyzz/compiler` throws for the same input, and the message matches it.
+ */
+export class CompileError extends Error {
+  /** Freezes the reported diagnostics in the compiler's reporting order. */
+  constructor(options: CompileError.Options) {
+    super(options.message)
+    this.diagnostics = Object.freeze(
+      options.diagnostics.map((item) => Object.freeze({ ...item })),
+    )
+    this.failure = options.failure
+  }
+  /** Source and CSS failures. Empty when the failure has no location, such as a missing import. */
+  readonly diagnostics: readonly CompileError.Diagnostic[]
+  /** Error name the native compiler reports, such as `Source.ExtractError` or `Css.CompileError`. */
+  readonly failure: string
+  /** Stable namespaced error identifier. */
+  override name = 'Graph.CompileError'
+}
+
+/** Compile error contracts. */
+export declare namespace CompileError {
+  /** A source extraction or CSS compilation diagnostic. */
+  type Diagnostic = Css.Diagnostic | Source.Diagnostic
+  /** The failure the compiler reports. */
+  type Options = {
+    /** Source and CSS failures, in the compiler's reporting order. */
+    readonly diagnostics: readonly Diagnostic[]
+    /** Error name the native compiler reports. */
+    readonly failure: string
+    /** The native error's message. */
+    readonly message: string
+  }
+}
+
+/**
+ * Instantiates the compiler from the `zyzz/compiler.wasm` module, which the host loads as an
+ * asset. Each compilation is independent, as `Graph.compile` from `zyzz/compiler` is.
+ * @param options - The WebAssembly module, compiled or as bytes.
+ * @returns A compiler that owns one WebAssembly instance.
+ */
+export function create(options: create.Options): create.ReturnType {
+  const engine = Wasm.instantiate(options.module)
+
+  return Object.freeze({
+    compile(options: compile.Options): compile.ReturnType {
+      const output = JSON.parse(
+        engine.call(
+          'graph.compile',
+          JSON.stringify({
+            compiler: options.compiler,
+            composition: options.composition,
+            contracts: options.contracts,
+            cssOutput: options.cssOutput,
+            development: options.development,
+            imports: options.imports,
+            modules: options.modules,
+          }),
+        ),
+      ) as Output & { readonly error?: Failure | undefined }
+
+      if (output.error)
+        throw new CompileError({
+          diagnostics: output.error.diagnostics ?? [],
+          failure: output.error.name,
+          message: output.error.message,
+        })
+
+      // Keys follow the order `Graph.compile` from `zyzz/compiler` writes, so both outputs
+      // serialize identically.
+      return Object.freeze({
+        ...(output.shared
+          ? {
+              sharedCss: output.shared.css,
+              sharedCssMap: output.shared.map,
+              sharedAssets: Object.freeze(
+                Object.assign(Object.create(null), output.shared.assets),
+              ),
+              sharedAssetOwners: Object.freeze(
+                Object.assign(Object.create(null), output.shared.owners),
+              ),
+            }
+          : {}),
+        contracts: Object.freeze({ ...output.contracts }),
+        dependencies: Object.freeze(
+          Object.assign(
+            Object.create(null),
+            Object.fromEntries(
+              Object.entries(output.dependencies).map((entry) => [
+                entry[0],
+                Object.freeze([...entry[1]]),
+              ]),
+            ),
+          ),
+        ),
+        modules: Object.freeze(
+          Object.fromEntries(
+            Object.entries(output.modules).map((entry) => [
+              entry[0],
+              Modules.decode(entry[1]),
+            ]),
+          ),
+        ),
+      }) as compile.ReturnType
+    },
+  })
+}
+
+/** WebAssembly compiler contracts. */
+export declare namespace create {
+  /** The compiler module. */
+  type Options = {
+    /**
+     * The `zyzz/compiler.wasm` module. Bytes compile synchronously, which Cloudflare Workers
+     * forbid and browsers limit on the main thread, so those hosts pass a compiled module.
+     */
+    readonly module: BufferSource | WebAssembly.Module
+  }
+  /** A compiler that owns one WebAssembly instance and its memory. */
+  type ReturnType = {
+    /** Compiles one complete web graph snapshot. */
+    readonly compile: (options: compile.Options) => compile.ReturnType
+  }
+}

package/src/compiler/wasm/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Exposes source graph compilation in the WebAssembly compiler, for browsers and workers without
+ * the native addon. The host loads the module from `zyzz/compiler.wasm`.
+ * @module
+ */
+/** Web graph compilation in a host-loaded WebAssembly compiler. */
+export * as Graph from './Graph.js'

package/src/internal/Wasm.ts

@@ -1,5 +1,5 @@
 /**
- * Instantiates the WebAssembly compiler synchronously from its bytes, for hosts without the native addon.
+ * Instantiates the WebAssembly compiler synchronously, for hosts without the native addon.
  * @module
  */
 
@@ -28,13 +28,20 @@ export class TrapError extends Error {
 }
 
 /**
- * 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.
+ * Instantiates the module without awaiting, so synchronous APIs can call it. Bytes compile
+ * synchronously first. Hosts that forbid runtime compilation, such as Cloudflare Workers, pass
+ * a compiled module instead. A trap leaves Rust state undefined, so the next call starts a
+ * fresh instance.
+ * @param source - The `crates/wasm` module, compiled or as bytes.
  * @returns The instance's operations.
  */
-export function instantiate(bytes: BufferSource): Instance {
-  const module = new WebAssembly.Module(bytes)
+export function instantiate(
+  source: BufferSource | WebAssembly.Module,
+): Instance {
+  const module =
+    source instanceof WebAssembly.Module
+      ? source
+      : new WebAssembly.Module(source)
   const encoder = new TextEncoder()
   const decoder = new TextDecoder()
   let exports: Exports | undefined
@@ -42,7 +49,8 @@ export function instantiate(bytes: BufferSource): Instance {
 
   function start(): Exports {
     stderr = ''
-    // The reactor reads no files, clock, or environment. WASI output only carries panic messages.
+    // The reactor reads no files, clock, or environment. Parser dependencies seed internal hash
+    // tables with entropy, but emitted class identities use the compiler's deterministic hashes.
     const wasi = {
       environ_get: () => 0,
       environ_sizes_get: (count: number, size: number) => {
@@ -67,6 +75,13 @@ export function instantiate(bytes: BufferSource): Instance {
       proc_exit: (code: number) => {
         throw new TrapError(`WebAssembly compiler exited with code ${code}.`)
       },
+      random_get: (pointer: number, length: number) => {
+        const bytes = new Uint8Array(exports!.memory.buffer, pointer, length)
+        // Web Crypto limits each request to 65,536 bytes.
+        for (let offset = 0; offset < length; offset += 65536)
+          crypto.getRandomValues(bytes.subarray(offset, offset + 65536))
+        return 0
+      },
     }
     const instance = new WebAssembly.Instance(module, {
       wasi_snapshot_preview1: wasi,

package/src/vite/index.ts

@@ -948,7 +948,17 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
         }
 
         const resolved = await resolve(specifier, file)
-        if (!resolved)
+        if (!resolved) {
+          // Framework transforms can remove server-only protocols from client code.
+          // Resolve first so aliases and plugins can still supply analyzable source.
+          if (
+            !Path.isAbsolute(specifier) &&
+            /^[a-z][a-z\d+.-]*:/i.test(specifier)
+          ) {
+            resolutions[specifier] = null
+            continue
+          }
+
           throw new Source.ExtractError([
             {
               code: 'unsupported_syntax',
@@ -958,6 +968,7 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
               start: node.start,
             },
           ])
+        }
 
         if (resource(specifier) || resource(resolved.id)) {
           resolutions[specifier] = null