@solidrt/flux-types 0.0.10 → 0.0.13

package/README.md

@@ -1,6 +1,13 @@
 # @solidrt/flux-types
 
-TypeScript type definitions for the `Flux` runtime global in [SolidRT](https://github.com/wellawaretech/solidrt) apps.
+TypeScript type definitions for the [SolidRT](https://github.com/wellawaretech/solidrt)
+`flux` runtime: the `Flux` global, the `flux:*` capability modules, the
+web-standard globals flux provides, and the GUI globals.
+
+The runtime is QuickJS, not a browser or Node, so it ships neither `lib.dom` nor
+the Bun/Node libraries. This package is the single source of truth for everything
+the flux runtime exposes, including web standards like `fetch`, `Response`,
+`WebSocket`, `console`, and timers.
 
 ## Installation
 
@@ -8,31 +15,45 @@ TypeScript type definitions for the `Flux` runtime global in [SolidRT](https://g
 bun add -d @solidrt/flux-types
 ```
 
-Then **you must add it to the `types` array** in your `tsconfig.json`. This is
-required: the `flux:*` modules are ambient declarations, so they are only
-visible to TypeScript when the package is listed in `types`. Without this you
-will get `Cannot find module 'flux:fs'` (and the same for `flux:http`,
-`flux:process`, etc.).
+Then configure `tsconfig.json` so TypeScript uses these types and does **not**
+pull in browser or Bun/Node globals that the runtime does not have:
 
 ```json
 {
   "compilerOptions": {
+    "lib": ["ESNext"],
     "types": ["@solidrt/flux-types"]
   }
 }
 ```
 
-If you already have a `types` array (for example with `@types/bun`), **add to
-it** rather than replacing it — listing `types` disables TypeScript's automatic
-type inclusion, so every package you rely on must be named:
-
-```json
-{
-  "compilerOptions": {
-    "types": ["bun", "@solidrt/flux-types"]
-  }
-}
-```
+- `lib: ["ESNext"]` keeps the genuine ECMAScript types (Promise, Array, Map,
+  TypedArrays, `Symbol.asyncIterator`) while dropping the DOM. Including `"dom"`
+  would advertise `document`, `window`, `localStorage`, and other APIs that do
+  not exist in flux.
+- `types: ["@solidrt/flux-types"]` makes the `flux:*` modules (ambient module
+  declarations) and the runtime globals visible.
+
+Do **not** also add `@types/bun` or `@types/node`: they declare `Bun.*`,
+`bun:*`/`node:*` modules, `process`, `Buffer`, and other APIs the runtime does
+not provide, and they collide with the web-standard globals declared here.
+
+If you already maintain a `types` array, add to it rather than replacing it:
+listing `types` disables TypeScript's automatic inclusion, so every package you
+rely on must be named.
+
+## What's covered
+
+- `Flux` global (`version`, `capabilities`).
+- `flux:*` modules: `flux:http`, `flux:fs`, `flux:sqlite`, `flux:subprocess`,
+  `flux:p2p`, `flux:process`, `flux:path`, and (on a gui-enabled runtime)
+  `flux:camera`, `flux:microphone`, `flux:gpu`.
+- Web-standard globals: `console`, `fetch` + `Headers`/`Request`/`Response`,
+  `setTimeout`/`setInterval`/`queueMicrotask`, `performance`, `WebSocket`,
+  `TextEncoder`/`TextDecoder`. These are deliberate subsets matching exactly what
+  the runtime implements.
+- GUI globals (gui-enabled runtime only): `requestAnimationFrame` /
+  `cancelAnimationFrame` (web-standard names, so kept global).
 
 ## License
 

package/gui/camera.d.ts

@@ -0,0 +1,67 @@
+// Camera capture (gui-enabled runtime only). The imperative primitive;
+// @solidrt/core's createCamera wraps it with SolidJS reactivity. `open` resolves
+// to a bound session object, so the raw handle never leaves the runtime.
+
+declare module "flux:camera" {
+  /** A camera device from {@link listCameras}. */
+  type CameraDevice = {
+    /** Device id to pass as `open({ camera })`. */
+    id: number
+    /** Human-readable device name. */
+    name: string
+    /** Which way the camera faces. */
+    facing: "front" | "back" | "unknown"
+  }
+
+  /** Options for {@link open}. */
+  type CameraOpenOptions = {
+    /** Device id from {@link CameraDevice}. Omit to let the runtime choose. */
+    camera?: number
+    /** Prefer a front- or back-facing camera. */
+    facing?: "front" | "back"
+    /** Requested capture width in pixels. */
+    width?: number
+    /** Requested capture height in pixels. */
+    height?: number
+    /** Barcode formats to scan each frame for. Only "qr" is supported. */
+    scan?: "qr"[]
+  }
+
+  /** A decoded barcode. */
+  type Barcode = {
+    /** The decoded payload. */
+    data: string
+    /** The barcode format (currently always "qr"). */
+    format: "qr"
+  }
+
+  /** An opened camera session: the frame texture plus controls bound to it. */
+  type CameraSession = {
+    /** GPU texture id the latest frame is uploaded into (use as a texture source). */
+    texture: number
+    /** Frame width in pixels. */
+    width: number
+    /** Frame height in pixels. */
+    height: number
+    /**
+     * Register (or replace) the callback that receives decoded barcodes (only
+     * fires when the session was opened with a `scan` option).
+     */
+    onBarcode(callback: (barcode: Barcode) => void): void
+    /** Release the device. */
+    close(): void
+  }
+
+  /** List the available camera devices. */
+  export function listCameras(): CameraDevice[]
+  /**
+   * Open a camera. Opening is also the permission request: the promise rejects
+   * if permission is denied, and resolves once the first frame is ready.
+   */
+  export function open(options?: CameraOpenOptions): Promise<CameraSession>
+  /**
+   * One-shot scan of an RGBA8 pixel buffer (exactly width*height*4 bytes).
+   * Returns every decoded barcode.
+   */
+  export function scanImage(data: Uint8Array, width: number, height: number): Barcode[]
+}

package/gui/gpu.d.ts

@@ -0,0 +1,39 @@
+// Low-level GPU textures and fragment shaders (gui-enabled runtime only). The
+// imperative primitive; @solidrt/core's gpu helpers add reactive auto-cleanup on
+// top. Texture ids are the public token (used as `<texture src>` and shader
+// sampler inputs), so there is no handle to hide here.
+
+declare module "flux:gpu" {
+  /**
+   * Create an immutable texture from an RGBA8 pixel buffer (exactly
+   * width*height*4 bytes). Returns the texture id.
+   */
+  export function createTexture(data: Uint8Array, width: number, height: number): number
+  /**
+   * Create a texture intended to be updated later via {@link uploadTexture}. The
+   * seed buffer must hold at least one frame (width*height*4 bytes) and may hold
+   * more (uploadTexture selects a frame by offset).
+   */
+  export function createMutableTexture(data: Uint8Array, width: number, height: number): number
+  /**
+   * Replace a mutable texture's pixels. `data` may hold several frames; `offset`
+   * (default 0) selects which frame to upload.
+   */
+  export function uploadTexture(id: number, data: Uint8Array, offset?: number): void
+  /** Destroy a texture (immutable, mutable, or shader). */
+  export function destroyTexture(id: number): void
+  /**
+   * Compile a GLSL ES fragment shader into an offscreen texture of the given
+   * size. `params` sets float uniforms by name; `textures` binds sampler2D
+   * uniforms to texture ids. Returns the resulting texture id.
+   */
+  export function createShader(
+    fragmentSrc: string,
+    width: number,
+    height: number,
+    params?: Record<string, number>,
+    textures?: Record<string, number>,
+  ): number
+  /** Update a shader texture's float uniforms by name and re-render it. */
+  export function setShaderParams(id: number, params: Record<string, number>): void
+}

package/gui/microphone.d.ts

@@ -0,0 +1,39 @@
+// Microphone capture (gui-enabled runtime only). The imperative primitive;
+// @solidrt/core's createMicrophone wraps it with SolidJS reactivity. `open`
+// returns a bound session object, so the raw handle never leaves the runtime.
+
+declare module "flux:microphone" {
+  /** A microphone device from {@link listMicrophones}. */
+  type MicrophoneDevice = {
+    /** Device id to pass as `open({ microphone })`. */
+    id: number
+    /** Human-readable device name. */
+    name: string
+  }
+
+  /** Options for {@link open}. */
+  type MicrophoneOpenOptions = {
+    /** Device id from {@link MicrophoneDevice}. Omit to use the default. */
+    microphone?: number
+    /** Capture sample rate in Hz. Defaults to 16000. */
+    sampleRate?: number
+  }
+
+  /** An opened microphone session with controls bound to it. */
+  type MicrophoneSession = {
+    /** The actual capture sample rate in Hz. */
+    sampleRate: number
+    /** Drain the mono float samples captured since the last read. */
+    read(): Float32Array
+    /** Release the device. */
+    close(): void
+  }
+
+  /** List the available microphone devices. */
+  export function listMicrophones(): MicrophoneDevice[]
+  /**
+   * Open a microphone. Synchronous: current platforms expose no audio permission
+   * prompt.
+   */
+  export function open(options?: MicrophoneOpenOptions): MicrophoneSession
+}

package/gui/raf.d.ts

@@ -0,0 +1,14 @@
+// Animation-frame scheduling globals (gui-enabled runtime only).
+
+declare global {
+  /**
+   * Request that `callback` run before the next rendered frame, receiving the
+   * frame timestamp in milliseconds. Returns an id for
+   * {@link cancelAnimationFrame}. Available only on a gui-enabled runtime.
+   */
+  function requestAnimationFrame(callback: (timestamp: number) => void): number
+  /** Cancel a frame callback scheduled with {@link requestAnimationFrame}. */
+  function cancelAnimationFrame(id: number): void
+}
+
+export {}

package/gui/rendertree.d.ts

@@ -0,0 +1,47 @@
+// The render-tree bridge (gui-enabled runtime only): the low-level surface the
+// renderer drives to build and mutate the native tree - create/insert/delete
+// nodes, write properties, query layout, measure text. Displaying the built
+// tree is the runner's concern ("srt:render" in lattice), not part of this
+// module; requestFrame here only schedules a future frame.
+
+declare module "flux:rendertree" {
+  /** Font options for {@link measureText}. */
+  export interface MeasureTextOptions {
+    fontFamily?: "sans" | "mono" | (string & {})
+    fontSize?: number
+    fontStyle?: "normal" | "italic"
+    fontWeight?: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900
+    maxLines?: number
+  }
+
+  /** Create the window root node with the given id. */
+  export function createRoot(id: number): void
+  /** Create a node of `kind` (the primitive element name) with the given id. */
+  export function createNode(id: number, kind: string): void
+  /** Insert `nodeId` under `parentId`, before `anchorId` if given (else appended). */
+  export function insertNode(parentId: number, nodeId: number, anchorId?: number): void
+  /** Detach and destroy `nodeId` from under `parentId`. */
+  export function deleteNode(parentId: number, nodeId: number): void
+  /** Write a single property on a node; `value` is marshalled per property. */
+  export function setProperty(nodeId: number, name: string, value: unknown): void
+  /** Enable or disable text-input capture / the on-screen keyboard. */
+  export function setTextInputActive(active: boolean): void
+  /** Request that a frame be rendered soon (coalesced by the demand-driven loop). */
+  export function requestFrame(): void
+  /**
+   * Lay out, paint and submit the whole tree to the screen now (one frame). The
+   * direct draw path for a flux + alloy app; requestFrame only schedules a
+   * future frame and leaves the actual draw to the runner.
+   */
+  export function render(): void
+  /**
+   * Measure the rendered size of `text` under the given font options, without
+   * adding it to the tree.
+   */
+  export function measureText(text: string, options?: MeasureTextOptions): { width: number, height: number }
+  /**
+   * The node's window-relative bounding box from the most recent layout, or
+   * `null` if it has no layout or has not been laid out yet.
+   */
+  export function getBoundingBox(id: number): { x: number, y: number, width: number, height: number } | null
+}

package/index.d.ts

@@ -1,206 +1,37 @@
+/// <reference path="./modules/process.d.ts" />
+/// <reference path="./modules/path.d.ts" />
+/// <reference path="./modules/http.d.ts" />
+/// <reference path="./modules/fs.d.ts" />
+/// <reference path="./modules/sqlite.d.ts" />
+/// <reference path="./modules/subprocess.d.ts" />
+/// <reference path="./modules/p2p.d.ts" />
+
+// Web-standard globals. The runtime is QuickJS, not a browser or Node, so it
+// ships no lib.dom / @types/bun: these declarations are the sole source for
+// console, fetch, the Fetch types, timers, WebSocket, and the encoders.
+/// <reference path="./standards/console.d.ts" />
+/// <reference path="./standards/time.d.ts" />
+/// <reference path="./standards/text.d.ts" />
+/// <reference path="./standards/fetch.d.ts" />
+/// <reference path="./standards/websocket.d.ts" />
+
+// GUI capabilities (present only on a gui-enabled runtime). rendertree/camera/
+// microphone/gpu are flux:* modules like the rest; requestAnimationFrame stays a
+// global (web-standard name). flux:rendertree is the render-tree bridge the
+// renderer drives; displaying the built tree (renderFrame) is the runner's
+// concern (srt:render in lattice), not part of flux.
+/// <reference path="./gui/rendertree.d.ts" />
+/// <reference path="./gui/camera.d.ts" />
+/// <reference path="./gui/microphone.d.ts" />
+/// <reference path="./gui/gpu.d.ts" />
+/// <reference path="./gui/raf.d.ts" />
+
 declare let Flux: {
+  /** The flux runtime version. */
   version: string
-}
-
-declare module "flux:process" {
-  /**
-   * The program's command-line arguments. `argv[0]` is the script path;
-   * `argv[1]` onward are the user-supplied arguments.
-   */
-  export let argv: string[]
-  /** The host OS: "darwin", "win32", "linux", "android", ... */
-  export let platform: string
-  /** The CPU architecture: "x64", "arm64", ... */
-  export let arch: string
-  /**
-   * Listen for an OS signal. The callback receives the signal name. Returns an
-   * unsubscribe function. Unix only; a no-op elsewhere.
-   *
-   * @param signal  One of "SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT", "SIGUSR1",
-   *                "SIGUSR2".
-   * @param callback  Invoked on each delivery with the signal name.
-   * @returns An unsubscribe function.
-   */
-  export function on(signal: string, callback: (signal: string) => void): () => void
-  /**
-   * Like {@link on}, but the listener fires at most once and then unsubscribes.
-   *
-   * @param signal  One of "SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT", "SIGUSR1",
-   *                "SIGUSR2".
-   * @param callback  Invoked once with the signal name.
-   * @returns An unsubscribe function.
-   */
-  export function once(signal: string, callback: (signal: string) => void): () => void
-}
-
-declare module "flux:path" {
-  /**
-   * Resolves `path` against the trusted base directory `base`, returning the
-   * absolute result only if it stays inside `base`; otherwise `null`. Fusing
-   * normalization and containment means a `..`-laden or absolute `path` that
-   * would escape `base` is rejected rather than silently resolved.
-   *
-   * Purely lexical: it does not resolve symlinks, so a symlink inside `base`
-   * pointing out of it is not caught.
-   *
-   * @param base  Trusted root directory. Relative values resolve against cwd.
-   * @param path  Untrusted path to place within `base`.
-   * @returns The contained absolute path, or `null` if it would escape `base`.
-   *
-   * @example
-   * let target = resolveWithin(".", req.params.page)
-   * if (!target) return new Response("Not found", { status: 404 })
-   */
-  export function resolveWithin(base: string, path: string): string | null
-
-  /**
-   * Joins and normalizes path `segments`. Lexical only, with no containment
-   * guarantee; use `resolveWithin` when a segment is untrusted.
-   */
-  export function join(...segments: string[]): string
-}
-
-declare module "flux:http" {
-  /** Path parameters captured from a route pattern (e.g. ":page"). */
-  type RouteParams = Record<string, string>
-
-  /** The request passed to a route handler, with captured route params. */
-  type FluxRequest = Request & {
-    params: RouteParams
-  }
-
-  /** Handles a matched route, returning a `Response` (or a promise of one). */
-  type RouteHandler = (req: FluxRequest) => Response | Promise<Response>
-
-  type ServeOptions = {
-    /** Port to listen on. */
-    port?: number
-    /** Hostname/interface to bind. Defaults to all interfaces. */
-    hostname?: string
-    /**
-     * Route table keyed by path pattern. Patterns may contain `:name`
-     * segments, exposed on `req.params`.
-     */
-    routes: Record<string, RouteHandler>
-  }
-
-  type Server = {
-    port: number
-    hostname: string
-    /** Stop accepting connections and shut the server down. */
-    stop(): void
-  }
-
-  /**
-   * Start an HTTP server with the given route table.
-   *
-   * @param options  Port, hostname, and routes.
-   * @returns The running {@link Server}.
-   */
-  export function serve(options: ServeOptions): Server
-}
-
-declare module "flux:fs" {
-  type DirEntry = {
-    name: string
-    type: "file" | "directory" | "symlink" | "other"
-  }
-
-  type FileStat = {
-    size: number
-    type: string
-    mtime?: number
-  }
-
-  type FluxFile = {
-    path: string
-    /** Read the whole file as UTF-8 text. */
-    text(): Promise<string>
-    /** Read the whole file as raw bytes. */
-    bytes(): Promise<Uint8Array>
-    /** Read and parse the file as JSON. */
-    json(): Promise<any>
-    /** Resolve to whether the file exists. */
-    exists(): Promise<boolean>
-    /** Resolve to the file's metadata (size, type, mtime). */
-    stat(): Promise<FileStat>
-    /** Write `data`, replacing any existing contents. */
-    write(data: string | Uint8Array): Promise<void>
-  }
-
-  type FluxDir = {
-    path: string
-    /** List the directory's immediate entries (non-recursive). */
-    entries(): Promise<DirEntry[]>
-    /** Resolve to whether the directory exists. */
-    exists(): Promise<boolean>
-  }
-
-  /**
-   * Reference a file by path. Lazy: no I/O happens until a method is called.
-   *
-   * @param path  Path to the file.
-   */
-  export function file(path: string): FluxFile
   /**
-   * Reference a directory by path. Lazy: no I/O happens until a method is
-   * called.
-   *
-   * @param path  Path to the directory.
+   * Feature names this build/runtime provides. Branch on availability rather
+   * than the OS, e.g. `Flux.capabilities.includes("subprocess")`.
    */
-  export function dir(path: string): FluxDir
-}
-
-declare module "flux:sqlite" {
-  /** Values accepted as bound parameters. booleans bind as 0/1. */
-  type SqlParam = null | boolean | number | string | Uint8Array
-  /** Values returned in result rows. BLOB comes back as Uint8Array. */
-  type SqlValue = null | number | string | Uint8Array
-  type Row = Record<string, SqlValue>
-
-  /** The outcome of a write. */
-  type RunResult = { changes: number; lastInsertRowid: number }
-
-  /**
-   * A reusable prepared statement. Created with {@link Database.query}; its
-   * executions reuse the compiled statement (cached on the connection).
-   */
-  export class Statement {
-    /** Run the statement and resolve to all matching rows. */
-    all(params?: SqlParam[]): Promise<Row[]>
-    /** Run the statement and resolve to the first row, or `undefined`. */
-    get(params?: SqlParam[]): Promise<Row | undefined>
-    /** Run the statement as a write and resolve to its {@link RunResult}. */
-    run(params?: SqlParam[]): Promise<RunResult>
-  }
-
-  /**
-   * Open mode: "ro" (default, read-only, must exist), "rw" (read-write, must
-   * exist), "rw+" (read-write, create if missing).
-   */
-  type OpenMode = "ro" | "rw" | "rw+"
-
-  export class Database {
-    /**
-     * Open a connection to the database at `path`.
-     *
-     * @param path  Database file path.
-     * @param mode  Open mode; defaults to "ro".
-     */
-    static connect(path: string, mode?: OpenMode): Promise<Database>
-    /** Create a reusable prepared statement (synchronous; compiles on first run). */
-    query(sql: string): Statement
-    /** One-shot write; uses plain prepare (no caching). */
-    run(sql: string, params?: SqlParam[]): Promise<RunResult>
-    /** Run a multi-statement script (no params), e.g. schema setup / migrations. */
-    exec(sql: string): Promise<void>
-    /**
-     * Run a batch of [sql, params] statements in one transaction (BEGIN/COMMIT,
-     * ROLLBACK on any error). Resolves to one result per statement. Statements
-     * must be writes/DDL. Cannot branch on intermediate results.
-     */
-    transaction(statements: [string, SqlParam[]?][]): Promise<RunResult[]>
-    /** Close the connection. */
-    close(): Promise<void>
-  }
+  capabilities: string[]
 }

package/modules/fs.d.ts

@@ -0,0 +1,50 @@
+declare module "flux:fs" {
+  type DirEntry = {
+    name: string
+    type: "file" | "directory" | "symlink" | "other"
+  }
+
+  type FileStat = {
+    size: number
+    type: string
+    mtime?: number
+  }
+
+  type FluxFile = {
+    path: string
+    /** Read the whole file as UTF-8 text. */
+    text(): Promise<string>
+    /** Read the whole file as raw bytes. */
+    bytes(): Promise<Uint8Array>
+    /** Read and parse the file as JSON. */
+    json(): Promise<any>
+    /** Resolve to whether the file exists. */
+    exists(): Promise<boolean>
+    /** Resolve to the file's metadata (size, type, mtime). */
+    stat(): Promise<FileStat>
+    /** Write `data`, replacing any existing contents. */
+    write(data: string | Uint8Array): Promise<void>
+  }
+
+  type FluxDir = {
+    path: string
+    /** List the directory's immediate entries (non-recursive). */
+    entries(): Promise<DirEntry[]>
+    /** Resolve to whether the directory exists. */
+    exists(): Promise<boolean>
+  }
+
+  /**
+   * Reference a file by path. Lazy: no I/O happens until a method is called.
+   *
+   * @param path  Path to the file.
+   */
+  export function file(path: string): FluxFile
+  /**
+   * Reference a directory by path. Lazy: no I/O happens until a method is
+   * called.
+   *
+   * @param path  Path to the directory.
+   */
+  export function dir(path: string): FluxDir
+}