zyzz 0.0.28 → 0.0.30

package/src/compiler/internal/AtRules.ts

@@ -1,73 +1,38 @@
 /** Adapts standard descriptor extensions that precede the pinned parser's grammar. @module */
-import * as ColorProfiles from './ColorProfiles.js'
-import * as Descriptors from './Descriptors.js'
-import * as Functions from './Functions.js'
-import * as Identifiers from './Identifiers.js'
-import * as Keyframes from './Keyframes.js'
 import * as Lightning from 'lightningcss'
-import * as Properties from './Properties.js'
-import * as ViewTransitions from './ViewTransitions.js'
+import * as Results from './Results.js'
 
-/** Parses structured contributions while retaining newer font descriptors. */
+/** A stylesheet whose newer at-keywords travel through the parser under markers. */
+type Transport = {
+  readonly code: string
+  readonly features: string
+  readonly import: string
+  readonly palette: string
+  readonly property: string
+}
+
+/**
+ * Parses structured contributions while retaining newer font descriptors.
+ * The engine validates newer at-rules and renames the at-keywords the parser cannot round-trip.
+ */
 export function transform<C extends Lightning.CustomAtRules>(
   options: Lightning.TransformOptions<C>,
 ): Lightning.TransformResult {
   // Stylesheets without an @ byte cannot require at-keyword transport.
   if (!options.code.includes(64)) return Lightning.transform(options)
 
-  const source = new TextDecoder().decode(options.code)
-  if (
-    /@(?:counter-style|custom-media|document|font-face|font-palette-values|page)\b/i.test(
-      source,
-    )
-  )
-    Descriptors.validate(source)
-  if (/@function\b/i.test(source)) Functions.validate(source)
-  const properties = /@property\b/i.test(source) && Properties.validate(source)
-  let propertyMarker = 'zyzz-property'
-  while (source.includes(propertyMarker)) propertyMarker += '-x'
-  validateFeatures(source)
-  // The pinned visitor cannot round-trip the nested Option used for anonymous import layers.
-  // Give emitted anonymous layers a temporary name while URL visitors run, then restore them.
-  let importMarker = 'zyzz-anonymous-import'
-  while (source.includes(importMarker)) importMarker += '-x'
-  const imports = options.visitor
-    ? source.replace(
-        /^(\s*@import\s+(?:url\()?"(?:\\.|[^"\\])*"\)?\s+)layer(?=[\s;])/gm,
-        `$1layer(${importMarker})`,
-      )
-    : source
-  const lower = source.toLowerCase()
-  let marker = '-zyzz-ffv-000000000'
-  let suffix = 0
-  while (lower.includes(marker))
-    marker = `-zyzz-ffv-${(++suffix).toString(36).padStart(9, '0')}`
-  let paletteMarker = '-zyzz-fpv-000000000'
-  let paletteSuffix = 0
-  while (lower.includes(paletteMarker))
-    paletteMarker = `-zyzz-fpv-${(++paletteSuffix).toString(36).padStart(9, '0')}`
-  // The pinned parser silently drops font-family lists from palette rules.
-  const registered = properties
-    ? rename(imports, 'property', propertyMarker)
-    : imports
-  const features = lower.includes('@font-feature-values')
-    ? rename(registered, 'font-feature-values', marker)
-    : registered
-  const renamed = lower.includes('@font-palette-values')
-    ? rename(features, 'font-palette-values', paletteMarker)
-    : features
-  if (lower.includes('@color-profile')) ColorProfiles.validate(renamed)
-  if (lower.includes('@keyframes')) Keyframes.validate(renamed)
-  if (source.toLowerCase().includes('@view-transition')) {
-    let marker = '-zyzz-view-transition'
-    while (source.includes(marker)) marker += '-x'
-    ViewTransitions.validate(rename(renamed, 'view-transition', marker), marker)
-  }
-  if (source === renamed) return Lightning.transform(options)
+  const transport = Results.call<Transport | null>('css.transport', {
+    code: new TextDecoder().decode(options.code),
+    visitor: Boolean(options.visitor),
+  })
+
+  if (!transport) return Lightning.transform(options)
+
   const result = Lightning.transform({
     ...options,
-    code: new TextEncoder().encode(renamed),
+    code: new TextEncoder().encode(transport.code),
   })
+
   return {
     ...result,
     code: new TextEncoder().encode(
@@ -76,22 +41,20 @@ export function transform<C extends Lightning.CustomAtRules>(
           rename(
             new TextDecoder()
               .decode(result.code)
-              .replaceAll(`layer(${importMarker})`, 'layer'),
-            propertyMarker,
+              .replaceAll(`layer(${transport.import})`, 'layer'),
+            transport.property,
             'property',
           ),
-          marker,
+          transport.features,
           'font-feature-values',
         ),
-        paletteMarker,
+        transport.palette,
         'font-palette-values',
       ),
     ),
   }
 }
 
-// Contribution extraction validates feature blocks and their descriptors before this adapter.
-// At-keyword substitution keeps Lightning's token/URL traversal without discarding newer descriptors.
 /** Renames actual at-keywords without touching strings, comments, or function arguments. */
 export function rename(source: string, before: string, after: string): string {
   let output = ''
@@ -149,54 +112,3 @@ export function relocateImport(
     },
   }
 }
-
-// Validate the standard rule before shielding the newer font-display descriptor.
-function validateFeatures(source: string): void {
-  if (!source.toLowerCase().includes('@font-feature-values')) return
-  const masked = source.replace(
-    /"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|\/\*[\s\S]*?\*\//g,
-    (value) => ' '.repeat(value.length),
-  )
-  for (const match of masked.matchAll(/@font-feature-values(?=[\s{])/gi)) {
-    const start = match.index
-    const open = masked.indexOf('{', start)
-    if (open < 0) throw new Error('Invalid font-feature-values block.')
-    let depth = 1
-    let end = open + 1
-    let plain = source.slice(start, open + 1)
-    let cursor = open + 1
-    for (; end < masked.length && depth; end++) {
-      const char = masked[end]
-      if (char === '{') depth++
-      else if (char === '}') depth--
-      else if (depth === 1 && masked.slice(end).match(/^font-display\s*:/i)) {
-        const finish = masked.indexOf(';', end)
-        const close = masked.indexOf('}', end)
-        const boundary = finish >= 0 && finish < close ? finish : close
-        if (boundary < 0) throw new Error('Invalid font-display descriptor.')
-        const descriptor = source.slice(end, boundary)
-        const names = Identifiers.list(
-          descriptor.slice(descriptor.indexOf(':') + 1),
-          'space',
-        )
-        if (
-          names?.length !== 1 ||
-          !['auto', 'block', 'fallback', 'optional', 'swap'].includes(
-            names[0]!.replace(/[A-Z]/g, (letter) => letter.toLowerCase()),
-          )
-        )
-          throw new Error('Invalid font-display descriptor.')
-        plain += source.slice(cursor, end)
-        cursor = boundary + (boundary === finish ? 1 : 0)
-        end = cursor - 1
-      }
-    }
-    if (depth) throw new Error('Invalid font-feature-values block.')
-    plain += source.slice(cursor, end)
-    Lightning.transform({
-      filename: 'font-feature-values.css',
-      code: new TextEncoder().encode(plain),
-      errorRecovery: false,
-    })
-  }
-}

package/src/compiler/internal/Context.ts

@@ -0,0 +1,11 @@
+/**
+ * Marks native compilation inside a host-owned graph context.
+ * @module
+ */
+
+/**
+ * Option key of `Native.compile` for an adapter that compiles a module as a member of its own
+ * graph. Extraction then validates contributed CSS without relocating relative assets, and it
+ * links no other module.
+ */
+export const key = Symbol('zyzz.source.graph')

package/src/compiler/internal/Results.ts

@@ -0,0 +1,406 @@
+/**
+ * Runs compiler operations in the Rust engine and rebuilds their frozen results and errors.
+ * @module
+ */
+import type * as Mapping from '@jridgewell/gen-mapping'
+import * as StyleSheet from '../../react-native/StyleSheet.js'
+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 Stylesheets from './Stylesheets.js'
+
+/** A failure as the engine encodes it. */
+type Failure = {
+  readonly diagnostics?: readonly unknown[] | undefined
+  readonly message: string
+  readonly name: string
+  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
+  readonly edits: readonly Edits.Edit[]
+  readonly map: Mapping.EncodedSourceMap
+}
+
+/** A `native.compile` result as the engine encodes it. */
+export type NativeOutput = {
+  readonly code: string
+  readonly edits: readonly Edits.Edit[]
+  readonly map: string
+  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>>
+  readonly css: string
+  readonly id?: string | undefined
+  readonly map: Mapping.EncodedSourceMap
+  readonly owners: Readonly<Record<string, string>>
+}
+
+/**
+ * A graph result as the engine encodes it. Modules whose output the host last decoded are `0`,
+ * and `prune` drops every other decoded module.
+ */
+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 packed?: readonly Rendered[] | undefined
+  readonly prune?: true | undefined
+  readonly reset?: Rendered | undefined
+  readonly same?: true | undefined
+  readonly shared?: Rendered | undefined
+}
+
+/**
+ * Runs an engine operation on JSON input.
+ * @param operation - Operation name, such as `graph.compile`.
+ * @param input - Input data, serialized as JSON.
+ * @returns The parsed result.
+ * @throws {Source.ExtractError} For source the compiler does not support.
+ * @throws {Css.CompileError} For CSS emission failures.
+ * @throws {Native.CompileError} For native features outside the static boundary.
+ */
+export function call<result>(operation: string, input: unknown): result {
+  return decode(Engine.call(operation, JSON.stringify(input)))
+}
+
+/**
+ * Runs `transform.compile`. JSON text never holds a raw NUL, so a string source follows one and
+ * crosses without escaping. The engine writes the module's records after one, and they decode
+ * when first read.
+ * @param input - Options, with the source when it is not a string.
+ * @param source - Module text.
+ * @returns The output `Transform.compile` returns.
+ * @throws {Source.ExtractError} For source the compiler does not support.
+ * @throws {Css.CompileError} For CSS emission failures.
+ */
+export function transform(
+  input: unknown,
+  source?: string | undefined,
+): Transform.compile.ReturnType {
+  const json = JSON.stringify(input)
+  const text = Engine.call(
+    'transform.compile',
+    source === undefined ? json : `${json}\0${source}`,
+  )
+  const split = text.indexOf('\0')
+
+  // Failures write no records, and decoding throws them.
+  if (split === -1) return module(decode<Module>(text), source)
+
+  return module(
+    decode<Omit<Module, keyof Records>>(text.slice(0, split)),
+    source,
+    text.slice(split + 1),
+  )
+}
+
+/**
+ * Parses an engine result, throwing the failure it encodes.
+ * @param json - The engine's JSON result.
+ * @returns The parsed result.
+ * @throws {Source.ExtractError} For source the compiler does not support.
+ * @throws {Css.CompileError} For CSS emission failures.
+ * @throws {Native.CompileError} For native features outside the static boundary.
+ */
+export function decode<result>(json: string): result {
+  const output = JSON.parse(json) as {
+    readonly error?: Failure | undefined
+  } | null
+
+  if (output?.error) throw failure(output.error)
+
+  return output as result
+}
+
+/**
+ * Lists each packed stylesheet section's import chain of a library contract, which hosts
+ * resolve before compiling the graph.
+ * @param contract - Serialized library contract.
+ * @param moduleId - Host-resolved identity of the contract's module.
+ * @returns One specifier chain per stylesheet section, in section order.
+ * @throws {SyntaxError} For malformed contract JSON.
+ * @throws {Error} For unsupported or invalid contract metadata.
+ */
+export function dependencies(
+  contract: string,
+  moduleId: string,
+): readonly (readonly string[])[] {
+  return call<{ readonly dependencies: readonly (readonly string[])[] }>(
+    'contract.dependencies',
+    { contract, moduleId },
+  ).dependencies
+}
+
+function failure(error: Failure): Error {
+  if (error.name === 'Source.ExtractError')
+    return new Source.ExtractError(
+      error.diagnostics as readonly Source.Diagnostic[],
+    )
+  if (error.name === 'Css.CompileError')
+    return new Css.CompileError(error.diagnostics as readonly Css.Diagnostic[])
+  if (error.name === 'Native.CompileError')
+    return new Native.CompileError(error.message)
+  if (error.name === 'StyleSheet.CompileError')
+    return new StyleSheet.CompileError(
+      error.diagnostics as readonly StyleSheet.Diagnostic[],
+    )
+  if (error.name === 'StyleSheet.SelectionError')
+    return new StyleSheet.SelectionError(error.message)
+  if (error.name === 'Stylesheets.ConflictError')
+    return new Stylesheets.ConflictError(error.source ?? '', error.message)
+  if (error.name === 'Variants.CompileError')
+    return new Variants.CompileError(error.message)
+  if (error.name === 'SyntaxError') return new SyntaxError(error.message)
+
+  return new Error(error.message)
+}
+
+/**
+ * Deeply freezes decoded JSON data, giving its objects null prototypes as compiled tables have.
+ * @param value - Data parsed from engine JSON.
+ * @returns The same data, frozen.
+ */
+export function frozen(value: unknown): unknown {
+  if (Array.isArray(value)) return Object.freeze(value.map(frozen))
+  if (value === null || typeof value !== 'object') return value
+
+  return Object.freeze(
+    Object.assign(
+      Object.create(null),
+      Object.fromEntries(
+        Object.entries(value).map(([key, entry]) => [key, frozen(entry)]),
+      ),
+    ),
+  )
+}
+
+/**
+ * Rebuilds a frozen graph result, keeping the decoded module objects the engine reports
+ * unchanged.
+ * @param value - The encoded graph result.
+ * @param previous - The result of the same compiler's previous call.
+ * @param decoded - The same compiler's last decoded module per identity, updated in place.
+ * @returns The output `Graph.compile` returns.
+ */
+export function graph(
+  value: Output,
+  previous?: Graph.compile.ReturnType | undefined,
+  decoded?: Map<string, Transform.compile.ReturnType> | undefined,
+): Graph.compile.ReturnType {
+  if (value.same && previous) return previous
+
+  const modules = Object.fromEntries(
+    Object.entries(value.modules).map(([id, encoded]) => [
+      id,
+      (() => {
+        if (encoded === 0) return decoded!.get(id)!
+        if ('edits' in encoded) return nativeModule(encoded)
+
+        return module(encoded)
+      })(),
+    ]),
+  )
+
+  if (decoded) {
+    for (const [id, output] of Object.entries(modules)) decoded.set(id, output)
+    if (value.prune)
+      for (const id of decoded.keys())
+        if (!Object.hasOwn(modules, id)) decoded.delete(id)
+  }
+
+  return Object.freeze({
+    ...(value.reset
+      ? { [Stylesheets.reset]: rendered(value.reset) as Stylesheets.Resource }
+      : {}),
+    ...(value.packed
+      ? {
+          [Stylesheets.packed]: Object.freeze(
+            value.packed.map((resource) => rendered(resource)),
+          ) as readonly Stylesheets.Resource[],
+        }
+      : {}),
+    ...(value.shared
+      ? {
+          sharedCss: value.shared.css,
+          sharedCssMap: value.shared.map,
+          sharedAssets: Object.freeze(
+            Object.assign(Object.create(null), value.shared.assets),
+          ),
+          sharedAssetOwners: Object.freeze(
+            Object.assign(Object.create(null), value.shared.owners),
+          ),
+        }
+      : {}),
+    contracts: Object.freeze({ ...value.contracts }),
+    dependencies: Object.freeze(
+      Object.assign(
+        Object.create(null),
+        Object.fromEntries(
+          Object.entries(value.dependencies).map(([id, targets]) => [
+            id,
+            Object.freeze([...targets]),
+          ]),
+        ),
+      ),
+    ),
+    modules: Object.freeze(modules),
+  }) as Graph.compile.ReturnType
+}
+
+/** 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.
+ * @param options - Native options of `Native.compile` or a native graph.
+ * @returns The engine's native input.
+ */
+export function native(
+  options: Omit<Native.compile.Options, 'moduleId' | 'source'>,
+) {
+  return {
+    colorScheme: options.colorScheme,
+    contextual: options.contextual,
+    fonts: options.fonts,
+    platform: options.platform,
+    runtime: options[Edits.runtime],
+    set: options.set,
+    units: options.units,
+    vars:
+      options.vars === undefined
+        ? undefined
+        : Wire.encode({
+            styles: { styles: [] },
+            vars: options.vars,
+          } as unknown as Css.compile.Options),
+  }
+}
+
+// A graph's native module carries the web output shape with empty CSS.
+function nativeModule(value: NativeModule): Transform.compile.ReturnType {
+  return Object.freeze({
+    [ClassName.rules]: Object.freeze({}),
+    classes: Object.freeze({}),
+    [Edits.key]: value.edits,
+    code: value.code,
+    css: '',
+    cssMap: {
+      version: 3 as const,
+      names: [],
+      sources: [],
+      mappings: '',
+    },
+    map: value.map,
+    vars: Object.freeze({}),
+  }) as Transform.compile.ReturnType
+}
+
+function rendered(value: Rendered) {
+  return Object.freeze({
+    ...(value.id === undefined ? {} : { id: value.id }),
+    css: value.css,
+    map: value.map,
+    assets: Object.freeze(Object.assign(Object.create(null), value.assets)),
+    owners: Object.freeze(Object.assign(Object.create(null), value.owners)),
+  })
+}

package/src/compiler/internal/Syntax.ts

@@ -1,9 +1,6 @@
 /** Parses authoring modules while retaining TypeScript assertion syntax. @module */
 import * as Parser from 'oxc-parser'
 
-/** Parsed modules supplied by the host for a single compilation. */
-export const cache = Symbol('parsed modules')
-
 /** Preserves JSX authoring and retries TypeScript files with assertion-aware grammar. */
 export function parse(options: parse.Options) {
   const settings = {