zyzz 0.0.28 → 0.0.30

package/src/web/internal/Block.ts

@@ -13,17 +13,3 @@ export type Entry =
       readonly header: string
       readonly entries: readonly Entry[]
     }
-/** Renders a structured block while delegating ordinary property serialization to the CSS compiler. */
-export function render(
-  entries: readonly Entry[],
-  style: (value: Style.NamedStyle) => string,
-): string {
-  return entries
-    .map((entry) => {
-      if (entry.kind === 'style') return style(entry.style)
-      if (entry.kind === 'block')
-        return `${entry.header}{${render(entry.entries, style)}}`
-      return `${entry.name}:${entry.value};`
-    })
-    .join('')
-}

package/src/web/internal/ClassName.ts

@@ -1,88 +1,4 @@
-/** Names atomic declarations with readable values and scoped conflict identities. @module */
-import * as Literal from '../../internal/Literal.js'
-
-/** Creates a CSS identifier without embedding arbitrary CSS syntax. */
-export function create(options: create.Options): string {
-  const property = Object.hasOwn(aliases, options.property)
-    ? aliases[options.property]!
-    : Literal.name(options.property)
-  const condition =
-    /^&:(hover|focus|focus-visible|active|disabled)\{([^{}]+)\}$/.exec(
-      options.body,
-    )
-  const body = condition?.[2] ?? options.body
-  const prefix = `${Literal.name(options.property)}:`
-  const literal =
-    body.startsWith(prefix) && body.endsWith(';')
-      ? body.slice(prefix.length, -1)
-      : ''
-  const simple = /^[a-zA-Z0-9-]{1,24}$/.test(literal)
-  const namespace = options.namespace ? `${options.namespace}-` : ''
-  if (options.context !== undefined)
-    return `z-${namespace}${options.context}-${encode(property)}${options.slot === undefined ? '' : `-${options.slot}`}`
-
-  const value = simple ? literal : `[${literal || body}]`
-  const readable =
-    options.property === 'display' && displays.has(literal)
-      ? literal
-      : property.startsWith('--')
-        ? `[${property}:${literal || body}]`
-        : `${property}-${value}`
-  // DOM class tokens cannot contain whitespace; preserve its spelling reversibly.
-  return `z-${namespace}${condition ? `${condition[1]}-` : ''}${readable.replace(/[\s_"'<>]/gu, (character) => `_${character.codePointAt(0)!.toString(16)}_`)}`
-}
-
-/** Atomic naming inputs; context retains declaration ordering and module ownership. */
-export declare namespace create {
-  /** Serialized declaration and its optional stable slot identity. */
-  type Options = {
-    /** Complete declaration, including fallbacks and conditions. */
-    readonly body: string
-    /** Identity required when the declaration cannot share a global rule. */
-    readonly context?: string | undefined
-    /** Optional consumer-owned configuration namespace. */
-    readonly namespace?: string | undefined
-    /** Authoring property spelling. */
-    readonly property: string
-    /** Ordered declaration slot inside a contextual style. */
-    readonly slot?: number | undefined
-  }
-}
-
-const aliases: Readonly<Record<string, string>> = {
-  backgroundColor: 'bg',
-  color: 'text',
-  height: 'h',
-  margin: 'm',
-  marginBottom: 'mb',
-  marginLeft: 'ml',
-  marginRight: 'mr',
-  marginTop: 'mt',
-  opacity: 'opacity',
-  padding: 'p',
-  paddingBottom: 'pb',
-  paddingLeft: 'pl',
-  paddingRight: 'pr',
-  paddingTop: 'pt',
-  width: 'w',
-}
-
-// Flex and grid also name shorthand properties, so retain their display prefix.
-const displays = new Set([
-  'block',
-  'inline',
-  'inline-block',
-  'inline-flex',
-  'inline-grid',
-  'none',
-])
-
-function encode(value: string): string {
-  return value.replace(
-    /[^a-zA-Z0-9-]/g,
-    (character) => `_${character.charCodeAt(0).toString(16)}_`,
-  )
-}
+/** Escapes class tokens and shares unit names across a graph's compilations. @module */
 
 /** Escapes a generated class token for use as a CSS selector. */
 export function selector(value: string): string {
@@ -108,10 +24,35 @@ export const complete = Symbol('zyzz.css.complete')
 export type Units = {
   /** Names a declaration unit, reusing a visible earlier name for an equal body. */
   readonly name: (body: string, namespace: string | undefined) => string
+  /** Shared table access for compilers outside this JavaScript realm. */
+  readonly [state]?: State | undefined
   /** Names chosen so far, keyed by namespace and body, and whether each was reused. */
   readonly used: ReadonlyMap<string, Decision>
 }
 
+/** Exposes a scope's shared name table to compilers outside this JavaScript realm. */
+export const state = Symbol('zyzz.css.units.state')
+
+/** Reads and updates one scope's shared name table without naming units. */
+export type State = {
+  /** Snapshots every registered name, this scope's identity, and the owners it may borrow from. */
+  readonly read: () => Snapshot
+  /** Applies decisions made outside this realm, as if this scope had named each unit. */
+  readonly record: (used: ReadonlyMap<string, Decision>) => void
+}
+
+/** A scope's view of the shared name table. */
+export type Snapshot = {
+  /** Registered names as `[key, name, owner]`, in registration order. */
+  readonly names: readonly (readonly [string, string, string])[]
+  /** Compilation identity recorded on the names it introduces. */
+  readonly owner: string
+  /** Fixed prefix distinguishing this compilation's new names. */
+  readonly qualifier: string
+  /** Owners whose names this scope may reuse, or `undefined` for every owner. */
+  readonly visible: readonly string[] | undefined
+}
+
 /** A naming decision recorded so cached output can be validated against a later build. */
 export type Decision = {
   /** Whether the name was introduced by an earlier compilation. */
@@ -171,6 +112,32 @@ export function registry(): registry.ReturnType {
 
           return name
         },
+        [state]: {
+          read() {
+            const owners = new Set([
+              options.owner,
+              ...[...names.values()].map((entry) => entry.owner),
+            ])
+
+            return {
+              names: [...names].map(
+                ([key, entry]) => [key, entry.name, entry.owner] as const,
+              ),
+              owner: options.owner,
+              qualifier: options.qualifier,
+              visible: options.visible
+                ? [...owners].filter(options.visible)
+                : undefined,
+            }
+          },
+          record(decisions) {
+            for (const [key, decision] of decisions) {
+              if (!names.has(key))
+                names.set(key, { name: decision.name, owner: options.owner })
+              used.set(key, decision)
+            }
+          },
+        },
         used,
       }
     },

package/src/web/internal/Contributions.ts

@@ -1,6 +1,6 @@
-/** Pure ordered stylesheet contribution data and layer ordering. @module */
-import * as Block from './Block.js'
-import * as Namespace from './Namespace.js'
+/** Ordered stylesheet contribution data and layer ordering. @module */
+import type * as Block from './Block.js'
+import type * as Namespace from './Namespace.js'
 import type * as Style from '../../Style.js'
 
 /** Explicit stylesheet data supplied by source adapters or in-memory callers. */
@@ -161,59 +161,3 @@ export function order(
 
   return result
 }
-
-/** Renders static contributions without registration or environment access. */
-export function render(
-  definitions: readonly Definition[],
-  style: (value: Style.NamedStyle) => string,
-): string {
-  const layers = order(
-    definitions.flatMap((value) =>
-      value.kind === 'layers' ? [value.names] : [],
-    ),
-  )
-
-  return [
-    layers.length ? `@layer ${layers.join(',')};` : '',
-    ...definitions
-      .toSorted((a, b) => rank(a) - rank(b))
-      .map((value) => {
-        if (value.kind === 'layers') return ''
-        const css = (() => {
-          if (value.kind === 'namespace') return Namespace.statement(value)
-          if (value.kind === 'custom-media')
-            return `@custom-media ${value.name} ${value.query};`
-          if (value.kind === 'import')
-            return `@import url(${JSON.stringify(value.url)})${value.layer === true ? ' layer' : value.layer ? ` layer(${value.layer})` : ''}${value.supports ? ` supports(${value.supports})` : ''}${value.media ? ` ${value.media}` : ''};`
-          if (value.kind === 'block')
-            return `${value.header}{${Block.render(value.entries, style)}}`
-          if (value.kind === 'rule')
-            return `${value.selector}{${style(value.style)}}`
-          if (value.kind === 'property')
-            return `@property ${value.name}{syntax:${JSON.stringify(value.syntax)};inherits:${value.inherits};${value.initialValue === undefined ? '' : `initial-value:${value.initialValue};`}}`
-          if (value.kind === 'font-face' || value.kind === 'descriptor')
-            return `@${value.kind === 'font-face' ? 'font-face' : `${value.rule} ${value.name}`}{${Object.entries(
-              value.declarations,
-            )
-              .map(
-                ([key, value]) =>
-                  `${key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}:${value};`,
-              )
-              .join('')}}`
-          return `@keyframes ${value.name}{${value.frames.map((frame) => `${frame.stop}{${style(frame.style)}}`).join('')}}`
-        })()
-        return (value.within ?? []).reduceRight(
-          (body, header) => `${header}{${body}}`,
-          css,
-        )
-      }),
-  ]
-    .filter(Boolean)
-    .join('\n')
-}
-
-function rank(value: Definition): number {
-  if (value.kind === 'import') return 0
-  if (value.kind === 'namespace') return 1
-  return 2
-}

package/src/web/internal/Engine.browser.ts

@@ -0,0 +1,51 @@
+/**
+ * Runs compiler operations in the WebAssembly build inlined into the bundle, for browsers and
+ * workers. It needs no Node built-ins, network, or asynchronous start.
+ * @module
+ */
+import * as Module from '#wasm'
+import * as Wasm from '../../internal/Wasm.js'
+
+// Compiling the module is the expensive step, so one instance serves the realm.
+let instance: Wasm.Instance | undefined
+
+/**
+ * Runs a named compiler operation on JSON input.
+ * @param operation - Operation name, such as `css.compile`.
+ * @param input - UTF-8 JSON input.
+ * @returns UTF-8 JSON output, including encoded failures.
+ */
+export function call(operation: string, input: string): string {
+  instance ??= Wasm.instantiate(decode(Module.base64))
+
+  return instance.call(operation, input)
+}
+
+const alphabet =
+  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
+
+// Decodes without `atob`, which bare realms such as Node `vm` contexts lack.
+function decode(text: string): Uint8Array<ArrayBuffer> {
+  const values = new Uint8Array(128)
+
+  for (let index = 0; index < alphabet.length; index++)
+    values[alphabet.charCodeAt(index)] = index
+
+  const padding = text.length - text.replace(/=+$/u, '').length
+  const output = new Uint8Array((text.length / 4) * 3 - padding)
+  let position = 0
+
+  for (let index = 0; index < text.length; index += 4) {
+    const bits =
+      (values[text.charCodeAt(index)]! << 18) |
+      (values[text.charCodeAt(index + 1)]! << 12) |
+      (values[text.charCodeAt(index + 2)]! << 6) |
+      values[text.charCodeAt(index + 3)]!
+
+    output[position++] = bits >> 16
+    if (position < output.length) output[position++] = (bits >> 8) & 255
+    if (position < output.length) output[position++] = bits & 255
+  }
+
+  return output
+}

package/src/web/internal/Engine.ts

@@ -0,0 +1,17 @@
+/**
+ * Runs compiler operations in the native addon. The package.json `browser` field replaces this
+ * module with `Engine.browser.ts`, so browser bundles never import Node built-ins.
+ * @module
+ */
+import * as Addon from '../../internal/Addon.js'
+// The type import keeps both engines' contracts identical and the browser engine in the build.
+import type * as Browser from './Engine.browser.js'
+
+/**
+ * Runs a named compiler operation on JSON input.
+ * @param operation - Operation name, such as `css.compile`.
+ * @param input - UTF-8 JSON input.
+ * @returns UTF-8 JSON output, including encoded failures.
+ */
+export const call: typeof Browser.call = (operation, input) =>
+  Addon.load().call(operation, input)

package/src/web/internal/Themes.ts

@@ -1,14 +1,11 @@
 /**
- * Collects live theme references and emits graph-local variables and scope rules.
+ * Serializes live theme references and combines generated scope rules.
  * @module
  */
 import * as Identity from '../../internal/Identity.js'
-import * as Scheme from '../../internal/Scheme.js'
 import * as Token from '../../internal/Token.js'
-import type * as Vars from '../../Vars.js'
-import type * as Theme from '../../internal/Theme.js'
 
-/** Collects live token references within one in-memory compilation graph. */
+/** Serializes live token references with graph-local variable names. */
 export function create() {
   const contracts = new Map<
     Token.Contract,
@@ -33,9 +30,6 @@ export function create() {
     return name
   }
 
-  const defaults = new Map<string, readonly Rule[]>()
-  const defaultGroups = new Map<Token.Contract, Set<string>>()
-
   function serialize(token: Token.Reference): string {
     const value = token.value
     let contract = contracts.get(token.contract)
@@ -59,198 +53,6 @@ export function create() {
     return `var(${name},${literal(value, label, token.contract)})`
   }
 
-  function emit(
-    themes: Readonly<Record<string, Theme.Definition | Vars.Definition>>,
-    schemes = false,
-    separate?: 'all' | 'defaults',
-  ) {
-    const classes: Record<string, string> = Object.create(null)
-    let nextScope = 0
-    const scopeBodies = new Map<string, string>()
-    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.')
-
-      const data =
-        theme &&
-        (Object.getOwnPropertyDescriptor(theme, Token.definition)?.value as
-          | Token.Metadata
-          | undefined)
-      if (!data) throw new Error('Expected a theme definition.')
-
-      // Anonymous contracts are graph-local. Source-owned contracts retain stable
-      // identities across separately compiled components and theme scopes.
-      const className =
-        data.contract[Token.identity] || data.cssName
-          ? scope(
-              data.cssName ??
-                (data.contract[Token.identity] &&
-                name.startsWith(`${data.contract[Token.identity]}-`)
-                  ? name.slice(data.contract[Token.identity]!.length + 1)
-                  : name),
-              data.contract[Token.identity],
-            )
-          : `z${(nextScope++).toString(36)}`
-
-      classes[name] = className
-
-      let contract = contracts.get(data.contract)
-
-      if (data.contract[Token.complete]) {
-        contract ??= {
-          identity: data.contract[Token.identity],
-          paths: new Map(),
-        }
-
-        // Separately compiled components may reference tokens absent from this graph.
-        for (const path of Object.keys(data.values)) {
-          if (contract.paths.has(path)) continue
-
-          contract.paths.set(path, property(data.contract, path))
-        }
-
-        contracts.set(data.contract, contract)
-      }
-
-      if (!contract) continue
-
-      // Independently compiled consumers must import identical fallback contents.
-      if (separate === 'all' && contract.identity) {
-        completeDefaults.add(data.contract)
-        for (const [path, value] of Object.entries(data.values))
-          literal(value, path, data.contract)
-      }
-      if (!contract.paths.size) empty.push(`.${className}{}`)
-
-      const declarations: Rule[] = []
-      // Resolving a value can add references to this contract.
-      const paths = [...contract.paths]
-      for (const [path, name] of paths) {
-        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({
-          conditions: [],
-          property: name,
-          selector: `.${className}`,
-          value: literal(value, label, data.contract),
-        })
-      }
-
-      rules.push(...declarations)
-      for (const [path, name] of contract.paths)
-        if (Object.hasOwn(data.values, path))
-          conditional(
-            data.values[path]!,
-            name,
-            `.${className}`,
-            rules,
-            path,
-            [],
-            data.contract,
-          )
-    }
-
-    for (const rule of rules) {
-      const key = JSON.stringify([
-        rule.selector,
-        rule.conditions,
-        rule.property,
-      ])
-      const previous = scopeBodies.get(key)
-      if (previous !== undefined && previous !== rule.value)
-        throw new Error(
-          `Generated scope ${rule.selector.slice(1)} conflicts. Supply distinct config ids.`,
-        )
-      scopeBodies.set(key, rule.value)
-    }
-
-    const scopes = new Map<string, Rule[]>()
-    for (const rule of rules) {
-      const entries = scopes.get(rule.property) ?? []
-      entries.push(rule)
-      scopes.set(rule.property, entries)
-    }
-
-    const grouped = new Set<string>()
-    const resources: Resource[] = []
-    if (separate === 'all')
-      for (const [contract, names] of defaultGroups) {
-        if (!completeDefaults.has(contract)) continue
-
-        // Sort independent properties only. Each property retains its authored conditional order.
-        const rules = [...names].sort().flatMap((name) => defaults.get(name)!)
-        resources.push({
-          css: render(rules),
-          id: JSON.stringify([
-            contract[Token.identity],
-            'fallbacks',
-            Object.entries(themes)
-              .filter(
-                ([, theme]) => theme[Token.definition].contract === contract,
-              )
-              .map(([name]) => name)
-              .sort(),
-          ]),
-          rules,
-        })
-        for (const name of names) grouped.add(name)
-      }
-
-    return {
-      classes: Object.freeze(classes),
-      css:
-        separate === 'all'
-          ? ''
-          : [
-              ...empty,
-              render([
-                ...(separate ? [] : [...defaults.values()].flat()),
-                ...rules,
-              ]),
-              ...(schemes ? [Scheme.css] : []),
-            ]
-              .filter(Boolean)
-              .join('\n'),
-      rules,
-      resources: separate
-        ? [
-            ...resources,
-            ...[...defaults]
-              .filter(([id]) => !grouped.has(id))
-              .map(([id, rules]) => ({
-                css: render(rules),
-                id,
-                rules,
-              })),
-            // Keep every scope of a property together so overlapping themes retain precedence.
-            ...(separate === 'all'
-              ? [...scopes].map(([property, rules]) => ({
-                  css: render(rules),
-                  id: JSON.stringify([classes, property]),
-                  rules,
-                }))
-              : []),
-            ...(separate === 'all' && schemes
-              ? [{ css: Scheme.css, id: 'zyzz-color-scheme' }]
-              : []),
-          ]
-        : [],
-    }
-  }
-
   function literal(
     value: Token.Value,
     label?: string,
@@ -268,16 +70,6 @@ export function create() {
       // 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.hash(css)}`
-      const emitted: Rule[] = [
-        { conditions: [], property: name, selector: ':where(*)', value: base },
-      ]
-      conditional(value, name, ':where(*)', emitted, label, [], owner)
-      defaults.set(name, emitted)
-      if (owner) {
-        const names = defaultGroups.get(owner) ?? new Set<string>()
-        names.add(name)
-        defaultGroups.set(owner, names)
-      }
       return `var(${name})`
     }
     return `light-dark(${literal(value.light, label, owner)},${literal(value.dark, label, owner)})`
@@ -309,37 +101,7 @@ export function create() {
     )
   }
 
-  function conditional(
-    value: Token.Value,
-    name: string,
-    selector: string,
-    rules: Rule[],
-    label?: string,
-    conditions: readonly string[] = [],
-    owner?: Token.Contract,
-  ) {
-    if (
-      !value ||
-      typeof value !== 'object' ||
-      Token.is(value) ||
-      !('default' in value)
-    )
-      return
-    conditional(value.default, name, selector, rules, label, conditions, owner)
-    for (const [query, entry] of Object.entries(value)) {
-      if (query === 'default') continue
-      const nested = [...conditions, query]
-      rules.push({
-        conditions: nested,
-        property: name,
-        selector,
-        value: literal(entry, label, owner),
-      })
-      conditional(entry, name, selector, rules, label, nested, owner)
-    }
-  }
-
-  return { emit, serialize }
+  return { serialize }
 }
 
 /** Combines generated declarations without crossing competing declarations of the same property. */
@@ -417,44 +179,6 @@ 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('-')}`