@solidrt/flux-types 0.0.24 → 0.0.26

package/gui/audio.d.ts

@@ -1,9 +1,10 @@
 // Sound playback (gui-enabled runtime only). The imperative primitive; `play`
-// decodes an encoded clip (Ogg/Vorbis or WAV) and returns a handle whose
-// `stop()` halts just that sound, so the raw track id never leaves the runtime.
+// decodes and starts a clip in one call, while `load` decodes once so a clip can
+// be replayed cheaply. Handles carry a `stop()` bound to just that voice, so the
+// raw track id never leaves the runtime.
 
 declare module "flux:audio" {
-  /** Options for {@link play}. */
+  /** Options for {@link play} and {@link LoadedSound.play}. */
   type PlayOptions = {
     /** Repeat the clip until stopped. Defaults to false. */
     loop?: boolean
@@ -11,17 +12,39 @@ declare module "flux:audio" {
     gain?: number
   }
 
-  /** A playing sound with controls bound to it. */
+  /** A playing voice with controls bound to it. */
   type SoundHandle = {
-    /** Stop this sound. A no-op if it already finished. */
+    /** Stop this voice. A no-op if it already finished. */
     stop(): void
   }
 
+  /** A decoded clip that can be replayed without re-decoding. */
+  type LoadedSound = {
+    /** Start a fresh overlapping voice for this clip. */
+    play(options?: PlayOptions): SoundHandle
+    /** Release the decoded clip. Voices already playing keep going. */
+    unload(): void
+  }
+
   /**
    * Decode and start an encoded audio clip (Ogg/Vorbis or WAV). Returns
-   * immediately; the sound plays on the mixer's own thread.
+   * immediately; the sound plays on the mixer's own thread. Use {@link load} to
+   * replay a clip repeatedly without decoding it each time.
    */
   export function play(bytes: Uint8Array, options?: PlayOptions): SoundHandle
+  /**
+   * Decode an encoded clip (Ogg/Vorbis or WAV) once and keep it in memory so it
+   * can be replayed cheaply. Call `unload()` on the result when done.
+   */
+  export function load(bytes: Uint8Array): LoadedSound
+  /**
+   * Open a clip for streaming: it is decoded on demand instead of loaded fully
+   * into memory, so a large track needs little RAM. Takes a `file()` from
+   * `flux:fs` (not a path), so the source rides the `file()` proxy override - a
+   * dev-server-proxied file streams from the server. Play the result as a single
+   * voice; do not overlap a stream with itself. Call `unload()` when done.
+   */
+  export function stream(source: ReturnType<typeof import("flux:fs").file>): LoadedSound
   /** Stop every playing sound. */
-  export function stopAll(): void
+  export function stop(): void
 }

package/gui/gpu.d.ts

@@ -36,4 +36,21 @@ declare module "flux:gpu" {
   ): number
   /** Update a shader texture's float uniforms by name and re-render it. */
   export function setShaderParams(id: number, params: Record<string, number>): void
+  /**
+   * Capture a render-tree node's subtree into a new GPU texture, resolving once
+   * it has been rendered on the next paint pass. The node must be attached to
+   * the live tree (a detached node is never painted, so its capture rejects).
+   * Rendered at the current display scale, so `width`/`height` are the texture's
+   * actual pixel dimensions (ceil(logicalSize * displayScale)), not logical
+   * points. Each call returns an independent id you must {@link destroyTexture}
+   * when done. Use the returned id anywhere a texture id is accepted
+   * (`<texture src>`, a shader sampler input, {@link readTexture}).
+   */
+  export function captureSnapshot(nodeId: number): Promise<{ id: number; width: number; height: number }>
+  /**
+   * Read back a registered texture's current pixels as RGBA8 (tightly packed,
+   * top-to-bottom rows), for any texture id whatever created it (createTexture,
+   * createShader, captureSnapshot). Synchronous. Throws if the id is unknown.
+   */
+  export function readTexture(id: number): { width: number; height: number; data: Uint8Array }
 }

package/modules/fs.d.ts

@@ -22,8 +22,16 @@ declare module "flux:fs" {
     exists(): Promise<boolean>
     /** Resolve to the file's metadata (size, type, mtime). */
     stat(): Promise<FileStat>
+    /**
+     * Read exactly `length` bytes starting at byte `offset`. A range extending
+     * past end-of-file rejects rather than short-reading; clamp against
+     * `stat()` size first.
+     */
+    read(offset: number, length: number): Promise<Uint8Array>
     /** Write `data`, replacing any existing contents. */
     write(data: string | Uint8Array): Promise<void>
+    /** Append `data` to the end of the file, creating it if missing. */
+    append(data: string | Uint8Array): Promise<void>
   }
 
   type FluxDir = {

package/modules/http.d.ts

@@ -1,4 +1,6 @@
 declare module "flux:http" {
+  import type { Endpoint } from "flux:p2p"
+
   /** Path parameters captured from a route pattern (e.g. ":page"). */
   type RouteParams = Record<string, string>
 
@@ -93,6 +95,11 @@ declare module "flux:http" {
     close(code?: number, reason?: string): void
     /** Connection state: CONNECTING 0, OPEN 1, CLOSING 2, CLOSED 3. */
     readonly readyState: number
+    /**
+     * The peer's IP address (or, for a connection accepted over the `p2p`
+     * option, the peer's endpoint id), or undefined when unknown.
+     */
+    readonly remoteAddress: string | undefined
   }
 
   /**
@@ -129,6 +136,18 @@ declare module "flux:http" {
     headers?: Record<string, string> | Headers
   }
 
+  /**
+   * A peer address, as returned by {@link Server.requestIP}. A p2p peer has no
+   * IP: `address` is its endpoint id, `port` is 0, and `family` is `"p2p"`.
+   */
+  type SocketAddress = {
+    /** The peer's IP address, or a p2p peer's endpoint id. */
+    address: string
+    /** The peer's port (0 for a p2p peer). */
+    port: number
+    family: "IPv4" | "IPv6" | "p2p"
+  }
+
   type Server = {
     /** The bound port. */
     readonly port: number
@@ -151,6 +170,11 @@ declare module "flux:http" {
     publish(topic: string, data: string | Uint8Array): number
     /** How many sockets are currently subscribed to `topic`. */
     subscriberCount(topic: string): number
+    /**
+     * The peer address of the connection `req` arrived on, or null when unknown
+     * (e.g. a JS-constructed Request).
+     */
+    requestIP(req: Request): SocketAddress | null
     /**
      * Stop accepting new connections and gracefully shut down open ones. Safe to
      * call more than once.
@@ -158,6 +182,14 @@ declare module "flux:http" {
     stop(): void
   }
 
+  /** Options for accepting `flux:p2p` connections alongside the TCP listener. */
+  type P2pOptions = {
+    /** The `flux:p2p` Endpoint to accept connections on. */
+    endpoint: Endpoint
+    /** ALPN protocol matched against each incoming connection. */
+    protocol: string
+  }
+
   type ServeOptions = {
     /** Port to listen on. */
     port: number
@@ -184,6 +216,13 @@ declare module "flux:http" {
      * without it `upgrade()` always returns false.
      */
     websocket?: WebSocketHandlers
+    /**
+     * Accept connections on a `flux:p2p` Endpoint alongside the TCP listener:
+     * each incoming connection whose ALPN matches `protocol` has the HTTP/WS
+     * protocol spoken over its first bidirectional stream. `server.stop()`
+     * stops accepting; the endpoint itself stays open for its owner.
+     */
+    p2p?: P2pOptions
   }
 
   /**

package/modules/p2p.d.ts

@@ -10,6 +10,19 @@ declare module "flux:p2p" {
     relayUrl?: string
     /** Protocols this endpoint will {@link Endpoint.accept}. */
     protocols?: string[]
+    /**
+     * Bind local-only: no relay and no address publishing/lookup, so nothing
+     * about the endpoint leaves the machine except the ticket itself, whose
+     * direct IPs same-network peers dial. Excludes `relayUrl`; a bare-id
+     * `connect` cannot resolve a local endpoint (tickets only).
+     */
+    local?: boolean
+    /**
+     * Pin the UDP bind port (IPv4-only). With a persisted `secretKey` this keeps
+     * the whole ticket stable across restarts, so a paired client can re-dial
+     * the old ticket. Omit for an ephemeral port.
+     */
+    port?: number
   }
 
   /** One transport address from {@link Endpoint.connInfo}. */
@@ -54,7 +67,7 @@ declare module "flux:p2p" {
     /**
      * Bind an endpoint.
      *
-     * @param opts  secretKey, relayUrl, protocols.
+     * @param opts  secretKey, relayUrl, protocols, local, port.
      */
     static create(opts?: EndpointOptions): Promise<Endpoint>
     /** This endpoint's dial address: the string peers pass to {@link connect}. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/flux-types",
-  "version": "0.0.24",
+  "version": "0.0.26",
   "license": "MIT",
   "author": "Antoine van Wel",
   "types": "index.d.ts",

package/standards/fetch.d.ts

@@ -25,6 +25,12 @@ interface Headers {
   delete(name: string): void
   /** Add a value for `name` without replacing existing ones. */
   append(name: string, value: string): void
+  /**
+   * Call `callback(value, name, headers)` for each entry. Iterates entries as
+   * stored (insertion order, duplicates separate); WHATWG iterates sorted with
+   * duplicate names combined.
+   */
+  forEach(callback: (value: string, name: string, headers: Headers) => void, thisArg?: any): void
 }
 
 declare let Headers: {