# Core Types
URL: /docs/api/types



Core Types [#core-types]

Use these types when handling kernel operation results, errors, geometry output, and worker state. They form the shared contract between the client and worker runtime.

Result Types [#result-types]

All kernel operations return a discriminated union: `KernelSuccessResult<T> | KernelErrorResult`. Check the `success` field to narrow the result.

```typescript @ts-nocheck
type KernelResult<T> = KernelSuccessResult<T> | KernelErrorResult;
```

<TypeTable
  type={{
  "name": "KernelSuccessResult",
  "description": "Successful kernel operation outcome. Non-fatal warnings are preserved in `issues` alongside the operation data.",
  "entries": [
    {
      "name": "success",
      "description": "",
      "tags": [],
      "type": "true",
      "simplifiedType": "true",
      "required": true,
      "deprecated": false
    },
    {
      "name": "data",
      "description": "",
      "tags": [],
      "type": "T",
      "simplifiedType": "T",
      "required": true,
      "deprecated": false
    },
    {
      "name": "issues",
      "description": "",
      "tags": [],
      "type": "KernelIssue[]",
      "simplifiedType": "array",
      "required": true,
      "deprecated": false
    },
    {
      "name": "serializedHandle",
      "description": "",
      "tags": [],
      "type": "unknown",
      "simplifiedType": "unknown",
      "required": false,
      "deprecated": false
    }
  ]
}}
/>

<TypeTable
  type={{
  "name": "KernelErrorResult",
  "description": "Failed kernel operation outcome. Inspect `issues` for error messages, source locations, and stack traces.",
  "entries": [
    {
      "name": "success",
      "description": "",
      "tags": [],
      "type": "false",
      "simplifiedType": "false",
      "required": true,
      "deprecated": false
    },
    {
      "name": "issues",
      "description": "",
      "tags": [],
      "type": "KernelIssue[]",
      "simplifiedType": "array",
      "required": true,
      "deprecated": false
    }
  ]
}}
/>

Issue and Location Types [#issue-and-location-types]

<TypeTable
  type={{
  "name": "KernelIssue",
  "description": "Diagnostic produced by a kernel operation — displayed in the editor's problem panel and used for error markers.",
  "entries": [
    {
      "name": "message",
      "description": "",
      "tags": [],
      "type": "string",
      "simplifiedType": "string",
      "required": true,
      "deprecated": false
    },
    {
      "name": "location",
      "description": "",
      "tags": [],
      "type": "ErrorLocation | undefined",
      "simplifiedType": "ErrorLocation",
      "required": false,
      "deprecated": false
    },
    {
      "name": "stack",
      "description": "",
      "tags": [],
      "type": "string | undefined",
      "simplifiedType": "string",
      "required": false,
      "deprecated": false
    },
    {
      "name": "stackFrames",
      "description": "",
      "tags": [],
      "type": "KernelStackFrame[] | undefined",
      "simplifiedType": "array",
      "required": false,
      "deprecated": false
    },
    {
      "name": "type",
      "description": "",
      "tags": [],
      "type": "KernelIssueType | undefined",
      "simplifiedType": "\"unknown\" | \"connection\" | \"kernel\" | \"runtime\" | \"compilation\"",
      "required": false,
      "deprecated": false
    },
    {
      "name": "severity",
      "description": "",
      "tags": [],
      "type": "IssueSeverity",
      "simplifiedType": "IssueSeverity",
      "required": true,
      "deprecated": false
    }
  ]
}}
/>

<TypeTable
  type={{
  "name": "KernelStackFrame",
  "description": "Stack frame captured during a kernel error, enriched with source mapping and visibility context for error reporting UI.",
  "entries": [
    {
      "name": "fileName",
      "description": "",
      "tags": [],
      "type": "string | undefined",
      "simplifiedType": "string",
      "required": false,
      "deprecated": false
    },
    {
      "name": "functionName",
      "description": "",
      "tags": [],
      "type": "string | undefined",
      "simplifiedType": "string",
      "required": false,
      "deprecated": false
    },
    {
      "name": "lineNumber",
      "description": "",
      "tags": [],
      "type": "number | undefined",
      "simplifiedType": "number",
      "required": false,
      "deprecated": false
    },
    {
      "name": "columnNumber",
      "description": "",
      "tags": [],
      "type": "number | undefined",
      "simplifiedType": "number",
      "required": false,
      "deprecated": false
    },
    {
      "name": "source",
      "description": "",
      "tags": [],
      "type": "string | undefined",
      "simplifiedType": "string",
      "required": false,
      "deprecated": false
    },
    {
      "name": "context",
      "description": "Classification of the frame's origin for visibility and error location purposes",
      "tags": [],
      "type": "FrameContext | undefined",
      "simplifiedType": "\"runtime\" | \"framework\" | \"library\" | \"user\"",
      "required": false,
      "deprecated": false
    }
  ]
}}
/>

<TypeTable
  type={{
  "name": "ErrorLocation",
  "description": "Source location for an error (file, line, column range) used for editor markers and navigation.",
  "entries": [
    {
      "name": "fileName",
      "description": "",
      "tags": [],
      "type": "string",
      "simplifiedType": "string",
      "required": true,
      "deprecated": false
    },
    {
      "name": "startLineNumber",
      "description": "",
      "tags": [],
      "type": "number",
      "simplifiedType": "number",
      "required": true,
      "deprecated": false
    },
    {
      "name": "startColumn",
      "description": "",
      "tags": [],
      "type": "number",
      "simplifiedType": "number",
      "required": true,
      "deprecated": false
    },
    {
      "name": "endLineNumber",
      "description": "",
      "tags": [],
      "type": "number | undefined",
      "simplifiedType": "number",
      "required": false,
      "deprecated": false
    },
    {
      "name": "endColumn",
      "description": "",
      "tags": [],
      "type": "number | undefined",
      "simplifiedType": "number",
      "required": false,
      "deprecated": false
    }
  ]
}}
/>

Worker State and Render Phase [#worker-state-and-render-phase]

`WorkerState` is the worker's current lifecycle state: `'idle'`, `'rendering'`, or `'error'`. Subscribe via `client.on('state', handler)`.

`RenderPhase` identifies the current phase of a render: `'resolvingDeps'`, `'bundling'`, `'extractingParams'`, `'computingGeometry'`, `'postProcessing'`. Subscribe via `client.on('progress', handler)`.

Dependency Types [#dependency-types]

Dependencies represent what a kernel's geometry depends on. The `Dependency` union type is used for cache key computation, middleware, and change detection:

<TypeTable
  type={{
  "name": "FileDependency",
  "description": "A file dependency representing a source file or font file.\nThe contentHash is a SHA-256 hash of the file's contents.",
  "entries": [
    {
      "name": "type",
      "description": "",
      "tags": [],
      "type": "\"file\"",
      "simplifiedType": "\"file\"",
      "required": true,
      "deprecated": false
    },
    {
      "name": "path",
      "description": "Path to the file relative to the build directory",
      "tags": [],
      "type": "string",
      "simplifiedType": "string",
      "required": true,
      "deprecated": false
    },
    {
      "name": "contentHash",
      "description": "SHA-256 hash of the file contents",
      "tags": [],
      "type": "string",
      "simplifiedType": "string",
      "required": true,
      "deprecated": false
    }
  ]
}}
/>

<TypeTable
  type={{
  "name": "MiddlewareDependency",
  "description": "A middleware dependency representing a middleware in the chain.\nThe index preserves the execution order in the chain.",
  "entries": [
    {
      "name": "type",
      "description": "",
      "tags": [],
      "type": "\"middleware\"",
      "simplifiedType": "\"middleware\"",
      "required": true,
      "deprecated": false
    },
    {
      "name": "name",
      "description": "Name of the middleware",
      "tags": [],
      "type": "string",
      "simplifiedType": "string",
      "required": true,
      "deprecated": false
    },
    {
      "name": "version",
      "description": "Version of the middleware",
      "tags": [],
      "type": "string",
      "simplifiedType": "string",
      "required": true,
      "deprecated": false
    },
    {
      "name": "index",
      "description": "Position in the middleware chain (0-indexed)",
      "tags": [],
      "type": "number",
      "simplifiedType": "number",
      "required": true,
      "deprecated": false
    },
    {
      "name": "options",
      "description": "Raw options object -- serialized in the final dependency hash pass",
      "tags": [],
      "type": "Record<string, unknown>",
      "simplifiedType": "Record<string, unknown>",
      "required": true,
      "deprecated": false
    }
  ]
}}
/>

<TypeTable
  type={{
  "name": "FrameworkDependency",
  "description": "A framework dependency representing the Tau framework version.",
  "entries": [
    {
      "name": "type",
      "description": "",
      "tags": [],
      "type": "\"framework\"",
      "simplifiedType": "\"framework\"",
      "required": true,
      "deprecated": false
    },
    {
      "name": "name",
      "description": "Framework name (always 'tau')",
      "tags": [],
      "type": "\"tau\"",
      "simplifiedType": "\"tau\"",
      "required": true,
      "deprecated": false
    },
    {
      "name": "version",
      "description": "Version string from package.json",
      "tags": [],
      "type": "string",
      "simplifiedType": "string",
      "required": true,
      "deprecated": false
    }
  ]
}}
/>

<TypeTable
  type={{
  "name": "OptionDependency",
  "description": "An option dependency representing a kernel configuration option.\nUsed to track mesh tolerances, backend arguments, etc.",
  "entries": [
    {
      "name": "type",
      "description": "",
      "tags": [],
      "type": "\"option\"",
      "simplifiedType": "\"option\"",
      "required": true,
      "deprecated": false
    },
    {
      "name": "key",
      "description": "Option key (e.g., 'tessellation', 'arguments')",
      "tags": [],
      "type": "string",
      "simplifiedType": "string",
      "required": true,
      "deprecated": false
    },
    {
      "name": "value",
      "description": "Option value (serialized to JSON for hashing)",
      "tags": [],
      "type": "unknown",
      "simplifiedType": "unknown",
      "required": true,
      "deprecated": false
    }
  ]
}}
/>

<TypeTable
  type={{
  "name": "ParameterDependency",
  "description": "A parameter dependency representing user-provided parameter values.\nUsed to invalidate cache when parameter values change.",
  "entries": [
    {
      "name": "type",
      "description": "",
      "tags": [],
      "type": "\"parameter\"",
      "simplifiedType": "\"parameter\"",
      "required": true,
      "deprecated": false
    },
    {
      "name": "parameters",
      "description": "Raw parameters object -- serialized in the final dependency hash pass",
      "tags": [],
      "type": "Record<string, unknown>",
      "simplifiedType": "Record<string, unknown>",
      "required": true,
      "deprecated": false
    }
  ]
}}
/>

<TypeTable
  type={{
  "name": "AssetDependency",
  "description": "An asset dependency representing a bundled asset (font, WASM, etc.).\nUsed to invalidate cache when assets change between deployments.",
  "entries": [
    {
      "name": "type",
      "description": "",
      "tags": [],
      "type": "\"asset\"",
      "simplifiedType": "\"asset\"",
      "required": true,
      "deprecated": false
    },
    {
      "name": "name",
      "description": "Asset identifier (e.g., 'font:Geist-Regular.ttf', 'wasm:opencascade')",
      "tags": [],
      "type": "string",
      "simplifiedType": "string",
      "required": true,
      "deprecated": false
    },
    {
      "name": "contentHash",
      "description": "SHA-256 hash of the asset content",
      "tags": [],
      "type": "string",
      "simplifiedType": "string",
      "required": true,
      "deprecated": false
    }
  ]
}}
/>

`Dependency` is the union: `FileDependency | MiddlewareDependency | FrameworkDependency | OptionDependency | ParameterDependency | AssetDependency`.

Filesystem Types [#filesystem-types]

<TypeTable
  type={{
  "name": "RuntimeFileSystemBase",
  "description": "Base filesystem interface -- 11 Node.js `fs.promises`-compatible primitives.\nAll paths are absolute. This is the minimal surface that filesystem backends\nmust implement (e.g. fromFsLike, fromMemoryFS, fromNodeFS).",
  "entries": [
    {
      "name": "readFile",
      "description": "Read file as text.\nRead file as binary.",
      "tags": [],
      "type": "{ (path: string, encoding: \"utf8\"): Promise<string>; (path: string): Promise<Uint8Array<ArrayBuffer>>; }",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "writeFile",
      "description": "Write file (text or binary).",
      "tags": [],
      "type": "(path: string, data: Uint8Array<ArrayBuffer> | string) => Promise<void>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "mkdir",
      "description": "Create directory, optionally recursive.",
      "tags": [],
      "type": "(path: string, options?: { recursive?: boolean; }) => Promise<void>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "readdir",
      "description": "List directory entries (file/dir names).",
      "tags": [],
      "type": "(path: string) => Promise<string[]>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "unlink",
      "description": "Delete file.",
      "tags": [],
      "type": "(path: string) => Promise<void>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "rmdir",
      "description": "Remove an empty directory.",
      "tags": [],
      "type": "(path: string) => Promise<void>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "rename",
      "description": "Rename / move a file or directory.",
      "tags": [],
      "type": "(oldPath: string, newPath: string) => Promise<void>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "stat",
      "description": "Get file or directory metadata.",
      "tags": [],
      "type": "(path: string) => Promise<FileStat>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "lstat",
      "description": "Get file or directory metadata without following symlinks.",
      "tags": [],
      "type": "(path: string) => Promise<FileStat>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "exists",
      "description": "Check if path exists.",
      "tags": [],
      "type": "(path: string) => Promise<boolean>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "watch",
      "description": "Subscribe to filesystem change events for the given paths.\nReturns an unsubscribe function. Events are filtered server-side.",
      "tags": [],
      "type": "((request: RuntimeWatchRequest, handler: (event: RuntimeWatchEvent) => void) => () => void) | undefined",
      "simplifiedType": "function",
      "required": false,
      "deprecated": false
    }
  ]
}}
/>

<TypeTable
  type={{
  "name": "RuntimeFileSystem",
  "description": "Enhanced filesystem interface for runtime workers.\nExtends the 11 base primitives with higher-level helper methods that have\ndefault implementations built from the primitives (via `createRuntimeFileSystem`).\nBackends may supply optimized overrides for any of the enhanced methods.",
  "entries": [
    {
      "name": "readFile",
      "description": "Read file as text.\nRead file as binary.",
      "tags": [],
      "type": "{ (path: string, encoding: \"utf8\"): Promise<string>; (path: string): Promise<Uint8Array<ArrayBuffer>>; }",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "writeFile",
      "description": "Write file (text or binary).",
      "tags": [],
      "type": "(path: string, data: Uint8Array<ArrayBuffer> | string) => Promise<void>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "mkdir",
      "description": "Create directory, optionally recursive.",
      "tags": [],
      "type": "(path: string, options?: { recursive?: boolean; }) => Promise<void>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "readdir",
      "description": "List directory entries (file/dir names).",
      "tags": [],
      "type": "(path: string) => Promise<string[]>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "unlink",
      "description": "Delete file.",
      "tags": [],
      "type": "(path: string) => Promise<void>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "rmdir",
      "description": "Remove an empty directory.",
      "tags": [],
      "type": "(path: string) => Promise<void>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "rename",
      "description": "Rename / move a file or directory.",
      "tags": [],
      "type": "(oldPath: string, newPath: string) => Promise<void>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "stat",
      "description": "Get file or directory metadata.",
      "tags": [],
      "type": "(path: string) => Promise<FileStat>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "lstat",
      "description": "Get file or directory metadata without following symlinks.",
      "tags": [],
      "type": "(path: string) => Promise<FileStat>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "exists",
      "description": "Check if path exists.",
      "tags": [],
      "type": "(path: string) => Promise<boolean>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "watch",
      "description": "Subscribe to filesystem change events for the given paths.\nReturns an unsubscribe function. Events are filtered server-side.",
      "tags": [],
      "type": "((request: RuntimeWatchRequest, handler: (event: RuntimeWatchEvent) => void) => () => void) | undefined",
      "simplifiedType": "function",
      "required": false,
      "deprecated": false
    },
    {
      "name": "readFiles",
      "description": "Batch-read multiple files as binary. Default: `Promise.all(paths.map(readFile))`.",
      "tags": [],
      "type": "(paths: string[]) => Promise<Record<string, Uint8Array<ArrayBuffer>>>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "readdirContents",
      "description": "Read all file contents in a directory (skips subdirectories).",
      "tags": [],
      "type": "(directoryPath: string) => Promise<Record<string, Uint8Array<ArrayBuffer>>>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "readdirStat",
      "description": "Get stat information for all entries in a directory.",
      "tags": [],
      "type": "(directoryPath: string) => Promise<FileStatEntry[]>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "ensureDir",
      "description": "Ensure a directory exists, creating parents as needed. Default: `mkdir(path, { recursive: true })`.",
      "tags": [],
      "type": "(path: string) => Promise<void>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    }
  ]
}}
/>

Kernel Types [#kernel-types]

<TypeTable
  type={{
  "name": "KernelDefinition",
  "description": "Definition for a kernel module loaded via defineKernel().\nKernel modules are ES modules dynamically imported by the worker runtime.\nThe API is designed to be simple (no class inheritance, no `this` binding)\nwith all state managed through the typed context returned by initialize().\n\nAll six type parameters are inferred automatically:\n- Context from the return type of initialize()\n- NativeHandle from the nativeHandle field of createGeometry()'s return\n- SerializedHandle from the return type of serializeHandle() (when provided)\n- Options from optionsSchema (when provided)\n- ExportSchemas from exportSchemas (when provided)\n- RenderSchema from renderSchema (when provided)",
  "entries": [
    {
      "name": "name",
      "description": "Human-readable kernel name, used in logs and error messages",
      "tags": [],
      "type": "string",
      "simplifiedType": "string",
      "required": true,
      "deprecated": false
    },
    {
      "name": "version",
      "description": "Semantic version string for cache-key computation and diagnostics",
      "tags": [],
      "type": "string",
      "simplifiedType": "string",
      "required": true,
      "deprecated": false
    },
    {
      "name": "optionsSchema",
      "description": "Zod schema for validating and typing kernel options. Options type is inferred from this schema.",
      "tags": [],
      "type": "z.ZodType<Options, unknown, z.core.$ZodTypeInternals<Options, unknown>> | undefined",
      "simplifiedType": "object",
      "required": false,
      "deprecated": false
    },
    {
      "name": "renderSchema",
      "description": "Zod schema for kernel-specific render options. Type is inferred and threaded to createGeometry input.",
      "tags": [],
      "type": "RenderSchema | undefined",
      "simplifiedType": "RenderSchema",
      "required": false,
      "deprecated": false
    },
    {
      "name": "exportSchemas",
      "description": "Zod schemas for per-format export options. Keys define supported formats; provides type-safe narrowing in exportGeometry.",
      "tags": [],
      "type": "ExportSchemas | undefined",
      "simplifiedType": "ExportSchemas",
      "required": false,
      "deprecated": false
    },
    {
      "name": "initialize",
      "description": "Initialize kernel with typed options. Options type is inferred from optionsSchema.",
      "tags": [],
      "type": "(options: Options, runtime: KernelRuntime) => Promise<Context>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "getDependencies",
      "description": "Return resolved and unresolved dependency paths for change-detection, cache invalidation, and watch-set expansion.",
      "tags": [],
      "type": "(input: GetDependenciesInput, runtime: KernelRuntime, context: Context) => Promise<GetDependenciesResult>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "getParameters",
      "description": "Extract user-facing parameters (and their JSON Schema) from the active file.",
      "tags": [],
      "type": "(input: GetParametersInput, runtime: KernelRuntime, context: Context) => Promise<GetParametersResult>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "createGeometry",
      "description": "Evaluate the active file and produce tessellated geometry plus a native handle for export.",
      "tags": [],
      "type": "(input: CreateGeometryInput<RenderSchema>, runtime: KernelRuntime, context: Context) => Promise<CreateGeometryOutput<NativeHandle>>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "exportGeometry",
      "description": "Convert a previously created native geometry handle into one or more export file blobs.",
      "tags": [],
      "type": "(input: ExportGeometryInput<NativeHandle, ExportSchemas>, runtime: KernelRuntime, context: Context) => Promise<ExportGeometryResult>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "serializeHandle",
      "description": "Serialize the native geometry handle to a cacheable representation.",
      "tags": [],
      "type": "((nativeHandle: NativeHandle, context: Context) => SerializedHandle) | undefined",
      "simplifiedType": "function",
      "required": false,
      "deprecated": false
    },
    {
      "name": "deserializeHandle",
      "description": "Restore native geometry handle from cached serialized data.",
      "tags": [],
      "type": "((data: SerializedHandle, context: Context) => NativeHandle) | undefined",
      "simplifiedType": "function",
      "required": false,
      "deprecated": false
    },
    {
      "name": "cleanup",
      "description": "Tear down kernel resources (WASM instances, temp files, etc.) when the worker is disposed.",
      "tags": [],
      "type": "((context: Context) => Promise<void>) | undefined",
      "simplifiedType": "function",
      "required": false,
      "deprecated": false
    }
  ]
}}
/>

<TypeTable
  type={{
  "name": "KernelRuntime",
  "description": "Runtime services provided to kernel methods.\nThe bundler and execute services are lazily initialised -- kernels that\nnever call them (OpenSCAD, Tau) pay zero cost.",
  "entries": [
    {
      "name": "filesystem",
      "description": "Filesystem interface (all paths are absolute)",
      "tags": [],
      "type": "RuntimeFileSystem",
      "simplifiedType": "RuntimeFileSystem",
      "required": true,
      "deprecated": false
    },
    {
      "name": "logger",
      "description": "Logger with kernel name pre-configured",
      "tags": [],
      "type": "RuntimeLogger",
      "simplifiedType": "RuntimeLogger",
      "required": true,
      "deprecated": false
    },
    {
      "name": "fileContentCache",
      "description": "Read-only view of cached file contents (absolute paths), populated during dependency computation",
      "tags": [],
      "type": "ReadonlyMap<string, string | Uint8Array<ArrayBuffer>>",
      "simplifiedType": "object",
      "required": true,
      "deprecated": false
    },
    {
      "name": "bundler",
      "description": "Esbuild bundler for JS/TS kernels. Lazily initialised on first access.",
      "tags": [],
      "type": "KernelBundler",
      "simplifiedType": "KernelBundler",
      "required": true,
      "deprecated": false
    },
    {
      "name": "tracer",
      "description": "Span tracer for kernel-authored performance instrumentation",
      "tags": [],
      "type": "RuntimeSpanTracer",
      "simplifiedType": "RuntimeSpanTracer",
      "required": true,
      "deprecated": false
    },
    {
      "name": "execute",
      "description": "Execute bundled JS/TS code via dynamic import and return the module exports.\nBrowser uses Blob URL, Node.js uses data URL.",
      "tags": [],
      "type": "(code: string) => Promise<ExecuteResult>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    }
  ]
}}
/>

Bundler Types [#bundler-types]

<TypeTable
  type={{
  "name": "BundlerDefinition",
  "description": "Definition for a bundler module loaded via defineBundler().\nBundler modules are ES modules dynamically imported by the worker runtime.\nThe bundler owns both bundling AND execution because the execution model\nis inherently tied to the bundler's output format.\n\nDetection (detectImports) and production (bundle) are separate operations:\n- detectImports: discovers what bare specifiers are used (no modules needed)\n- bundle: produces runnable code (modules must be registered first)\n\nThis separation eliminates the chicken-and-egg problem: detection runs\nwithout modules registered, then the framework selects and initializes\nthe kernel (which registers real modules), then bundle() produces code.\n\nType parameters are inferred automatically:\n- Context from initialize() return type\n- Options from optionsSchema (when provided)",
  "entries": [
    {
      "name": "name",
      "description": "Human-readable bundler name, used in logs and error messages",
      "tags": [],
      "type": "string",
      "simplifiedType": "string",
      "required": true,
      "deprecated": false
    },
    {
      "name": "version",
      "description": "Semantic version string for cache-key computation and diagnostics",
      "tags": [],
      "type": "string",
      "simplifiedType": "string",
      "required": true,
      "deprecated": false
    },
    {
      "name": "extensions",
      "description": "File extensions this bundler handles (e.g., ['ts', 'js', 'tsx', 'jsx']).",
      "tags": [],
      "type": "string[]",
      "simplifiedType": "array",
      "required": true,
      "deprecated": false
    },
    {
      "name": "optionsSchema",
      "description": "Zod schema for validating and typing bundler options. Options type is inferred from this schema.",
      "tags": [],
      "type": "z.ZodType<Options, unknown, z.core.$ZodTypeInternals<Options, unknown>> | undefined",
      "simplifiedType": "object",
      "required": false,
      "deprecated": false
    },
    {
      "name": "initialize",
      "description": "Initialize the bundler. Receives framework init options plus user-provided options.",
      "tags": [],
      "type": "(initOptions: BundlerInitOptions, options: Options) => Promise<Context>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "detectImports",
      "description": "Detect which bare-specifier modules are imported transitively.\nResolves relative imports normally but marks bare specifiers as external.\nReturns detected modules and project dependencies without producing runnable code.\nThis is the primary mechanism for kernel selection -- no module stubs required.",
      "tags": [],
      "type": "(input: BundleInput, context: Context) => Promise<DetectImportsResult>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "bundle",
      "description": "Produce runnable code with all registered modules resolved.\nCalled AFTER kernel selection and initialization (modules are registered).",
      "tags": [],
      "type": "(input: BundleInput, context: Context) => Promise<BundleResult>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "execute",
      "description": "Execute bundled code (tied to this bundler's output format).",
      "tags": [],
      "type": "(code: string, context: Context) => Promise<ExecuteResult>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "registerModule",
      "description": "Register a builtin module for resolution during bundle().",
      "tags": [],
      "type": "(name: string, builtinModule: BuiltinModule, context: Context) => void",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "resolveDependencies",
      "description": "Optional fast-path dependency resolution without full bundling.\nFalls back to bundle().dependencies when not implemented.",
      "tags": [],
      "type": "((input: BundleInput, context: Context) => Promise<GetDependenciesResult>) | undefined",
      "simplifiedType": "function",
      "required": false,
      "deprecated": false
    },
    {
      "name": "cleanup",
      "description": "Clean up bundler resources (e.g., esbuild.stop()).",
      "tags": [],
      "type": "((context: Context) => Promise<void>) | undefined",
      "simplifiedType": "function",
      "required": false,
      "deprecated": false
    }
  ]
}}
/>

<TypeTable
  type={{
  "name": "KernelBundler",
  "description": "Bundler service provided to kernel modules via KernelRuntime.\nWraps esbuild-wasm with virtual filesystem integration and CDN module resolution.\nCreated lazily on first access -- non-JS kernels incur zero cost.",
  "entries": [
    {
      "name": "bundle",
      "description": "Bundle a file and all its transitive dependencies.",
      "tags": [],
      "type": "(entryPath: string) => Promise<BundleResult>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "resolveDependencies",
      "description": "Resolve all transitive dependencies without generating output code.\nReturns both resolved dependencies and unresolved import paths.",
      "tags": [],
      "type": "(entryPath: string) => Promise<GetDependenciesResult>",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    },
    {
      "name": "registerModule",
      "description": "Register a built-in module that will be served from memory during bundling.\nUsed by JS/TS kernels to register WASM-loaded libraries (replicad,",
      "tags": [
        {
          "name": "jscad",
          "text": "/modeling).\nMust be called before the first bundle() call."
        }
      ],
      "type": "(name: string, entry: BuiltinModule) => void",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    }
  ]
}}
/>

<TypeTable
  type={{
  "name": "BundleResult",
  "description": "Result of bundling a file and its dependencies via esbuild.\nUsed by JS/TS kernels through runtime.bundler.",
  "entries": [
    {
      "name": "code",
      "description": "The bundled code as a string",
      "tags": [],
      "type": "string",
      "simplifiedType": "string",
      "required": true,
      "deprecated": false
    },
    {
      "name": "sourceMap",
      "description": "Source map (if enabled)",
      "tags": [],
      "type": "string | undefined",
      "simplifiedType": "string",
      "required": false,
      "deprecated": false
    },
    {
      "name": "issues",
      "description": "Compilation issues (errors, warnings)",
      "tags": [],
      "type": "KernelIssue[]",
      "simplifiedType": "array",
      "required": true,
      "deprecated": false
    },
    {
      "name": "success",
      "description": "Whether bundling succeeded",
      "tags": [],
      "type": "boolean",
      "simplifiedType": "boolean",
      "required": true,
      "deprecated": false
    },
    {
      "name": "dependencies",
      "description": "Absolute paths of all project files that were resolved during bundling (transitive dependencies).",
      "tags": [],
      "type": "string[]",
      "simplifiedType": "array",
      "required": true,
      "deprecated": false
    },
    {
      "name": "unresolvedPaths",
      "description": "Absolute paths of imports that could not be resolved during bundling — used for watch-set expansion.",
      "tags": [],
      "type": "string[]",
      "simplifiedType": "array",
      "required": true,
      "deprecated": false
    }
  ]
}}
/>

<TypeTable
  type={{
  "name": "BuiltinModule",
  "description": "A built-in module registered on the bundler for pre-loaded libraries.\nThese modules are served directly from memory without filesystem I/O.",
  "entries": [
    {
      "name": "code",
      "description": "Pre-bundled ESM code string",
      "tags": [],
      "type": "string",
      "simplifiedType": "string",
      "required": true,
      "deprecated": false
    },
    {
      "name": "version",
      "description": "Package version",
      "tags": [],
      "type": "string",
      "simplifiedType": "string",
      "required": true,
      "deprecated": false
    },
    {
      "name": "globalName",
      "description": "Optional CommonJS global variable name for banner injection",
      "tags": [],
      "type": "string | undefined",
      "simplifiedType": "string",
      "required": false,
      "deprecated": false
    }
  ]
}}
/>

Tracer Types [#tracer-types]

<TypeTable
  type={{
  "name": "SpanHandle",
  "description": "Handle returned by `RuntimeSpanTracer.startSpan()`.\nCall `end()` when the traced operation completes.",
  "entries": [
    {
      "name": "end",
      "description": "",
      "tags": [],
      "type": "() => void",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    }
  ]
}}
/>

<TypeTable
  type={{
  "name": "RuntimeSpanTracer",
  "description": "Lightweight tracing interface exposed to kernel modules and middleware.\nCreates hierarchical spans without requiring an OpenTelemetry SDK dependency.\nSpans are collected by the framework and displayed in the Kernel Panel.",
  "entries": [
    {
      "name": "startSpan",
      "description": "Begin a new named span, optionally attaching key-value attributes for filtering.",
      "tags": [],
      "type": "(name: string, attributes?: Record<string, string | number | boolean>) => SpanHandle",
      "simplifiedType": "function",
      "required": true,
      "deprecated": false
    }
  ]
}}
/>

Geometry and Export Types [#geometry-and-export-types]

<TypeTable
  type={{
  "name": "CreateGeometryResult",
  "description": "Result type for createGeometry.\nUsed by kernel workers and middleware - geometries don't have hash yet.\nThe hash is added by kernel-worker.ts after the middleware chain.",
  "entries": [
    {
      "name": "success",
      "description": "",
      "tags": [],
      "type": "boolean",
      "simplifiedType": "boolean",
      "required": true,
      "deprecated": false
    },
    {
      "name": "issues",
      "description": "",
      "tags": [],
      "type": "KernelIssue[]",
      "simplifiedType": "array",
      "required": true,
      "deprecated": false
    }
  ]
}}
/>

<TypeTable
  type={{
  "name": "HashedGeometryResult",
  "description": "Completed result type for createGeometry.\nReturned to consumers - geometries have hash for React keys and caching.",
  "entries": [
    {
      "name": "success",
      "description": "",
      "tags": [],
      "type": "boolean",
      "simplifiedType": "boolean",
      "required": true,
      "deprecated": false
    },
    {
      "name": "issues",
      "description": "",
      "tags": [],
      "type": "KernelIssue[]",
      "simplifiedType": "array",
      "required": true,
      "deprecated": false
    }
  ]
}}
/>

<TypeTable
  type={{
  "name": "GetParametersResult",
  "description": "Outcome of extracting customizer parameters from a CAD script, used to render the parameter editor UI.",
  "entries": [
    {
      "name": "success",
      "description": "",
      "tags": [],
      "type": "boolean",
      "simplifiedType": "boolean",
      "required": true,
      "deprecated": false
    },
    {
      "name": "issues",
      "description": "",
      "tags": [],
      "type": "KernelIssue[]",
      "simplifiedType": "array",
      "required": true,
      "deprecated": false
    }
  ]
}}
/>

<TypeTable
  type={{
  "name": "ExportGeometryResult",
  "description": "Outcome of exporting CAD geometry to a downloadable file format (STL, STEP, glTF, etc.).",
  "entries": [
    {
      "name": "success",
      "description": "",
      "tags": [],
      "type": "boolean",
      "simplifiedType": "boolean",
      "required": true,
      "deprecated": false
    },
    {
      "name": "issues",
      "description": "",
      "tags": [],
      "type": "KernelIssue[]",
      "simplifiedType": "array",
      "required": true,
      "deprecated": false
    }
  ]
}}
/>

Usage [#usage]

```typescript @ts-nocheck
const result = await client.render({ file: 'main.ts' });

if (result.success) {
  console.log(result.data.length);
} else {
  console.error(result.issues);
}
```

Related [#related]

* [Handle Errors](../guides/error-handling)
* [API: Client](./client)
* [API: Filesystem](./filesystem)