@three-flatland/devtools 0.1.0-alpha.3

package/dist/devtools-client.d.ts

@@ -0,0 +1,362 @@
+import { RegistryEntryKind, TexturePixelType, BufferDisplayMode, ProviderIdentity, DebugFeature, BufferSubscriptionEntry, BufferChunkPayload, DebugMessage } from 'three-flatland/debug-protocol';
+export { BufferChunkPayload } from 'three-flatland/debug-protocol';
+
+/**
+ * Construction options for `DevtoolsClient`.
+ */
+interface DevtoolsClientOptions {
+    /** Features to subscribe to. */
+    features: DebugFeature[];
+    /**
+     * Override the discovery (bonjour) channel name. Rarely needed — only
+     * for isolated test sessions.
+     */
+    discoveryChannelName?: string;
+    /**
+     * Optional first listener, equivalent to calling `addListener(cb)`
+     * after construction.
+     */
+    onChange?: (state: DevtoolsState) => void;
+}
+/** Listener signature for `DevtoolsClient.addListener`. */
+type DevtoolsStateListener = (state: DevtoolsState) => void;
+
+type BufferChunkListener = (chunk: BufferChunkPayload) => void;
+/** Listener for raw protocol messages. Direction is `in` for messages
+ *  received from the bus, `out` for messages the client posts. */
+type RawMessageListener = (msg: DebugMessage, direction: 'in' | 'out') => void;
+/** Per-field time-series ring. */
+interface DevtoolsSeries {
+    /** Pre-allocated Float32 buffer. Read via (write - i - 1 + size) % size. */
+    readonly data: Float32Array;
+    /** Next write index. */
+    write: number;
+    /** Valid sample count (<= size). */
+    length: number;
+}
+/**
+ * Snapshot of a registered CPU array as seen by the client. The
+ * `sample` typed array is owned by this object (structured-cloned from
+ * the provider) — read-only by contract; don't mutate in place.
+ */
+interface RegistryEntrySnapshot {
+    name: string;
+    kind: RegistryEntryKind;
+    version: number;
+    count: number;
+    sample: Float32Array | Uint32Array | Int32Array;
+    label?: string;
+}
+/** Snapshot of a registered debug buffer as seen by the client. */
+/**
+ * Client-side view of one render-pass event. Shallow copies of
+ * `PassEvent` from the wire — the provider reuses its scratch pool
+ * every frame, so we copy fields into fresh objects once on receive.
+ */
+interface BatchPassSnapshot {
+    label: string;
+    calls: number;
+    triangles: number;
+    cpuMs: number;
+    depth: number;
+    parent: number;
+}
+/** Client-side view of one batched-draw row. */
+interface BatchSnapshot {
+    frame: number;
+    passes: BatchPassSnapshot[];
+    batches: Array<{
+        runKey: number;
+        materialId: number;
+        layer: number;
+        materialName: string;
+        spriteCount: number;
+        batchIdx: number;
+        /** Subsystem tag (e.g. `'sprite'`, `'tilechunk'`). Defaults to `'sprite'` on the client when absent. */
+        kind: string;
+        /** Per-batch label (e.g. `'chunk(0,2)'`). Empty string when the source didn't set one. */
+        label: string;
+    }>;
+}
+interface BufferSnapshot {
+    name: string;
+    /** Dimensions of the pixels currently stored in `pixels` — equal to
+     *  source dims in stream mode, downsampled dims in thumbnail mode. */
+    width: number;
+    height: number;
+    /** Source (pre-downsample) dimensions — the "true" buffer size.
+     *  Equals width/height in stream mode. */
+    srcWidth: number;
+    srcHeight: number;
+    pixelType: TexturePixelType;
+    /** How the consumer should visualise this buffer (defaults applied by producer). */
+    display: BufferDisplayMode;
+    version: number;
+    /** Latest CPU readback; `null` until the provider has served a sample. */
+    pixels: Uint8Array | Float32Array | null;
+    label?: string;
+}
+/**
+ * Accumulated state the consumer keeps up-to-date by merging deltas
+ * from `data` packets. Callers bind UI to this object and refresh
+ * when `onChange` fires.
+ *
+ * All fields start `undefined`; the first `data` packet (or
+ * `subscribe:ack.env` bootstrap) populates them. Subsequent deltas
+ * overwrite specific fields; `null` on the wire clears a field back
+ * to `undefined`.
+ */
+interface DevtoolsState {
+    /** Engine frame counter — last frame index covered by the latest batch. */
+    frame?: number;
+    drawCalls?: number;
+    triangles?: number;
+    /** Lines + points aggregated. */
+    primitives?: number;
+    geometries?: number;
+    textures?: number;
+    cpuMs?: number;
+    fps?: number;
+    gpuMs?: number;
+    /** JS heap used, MB. `undefined` on Safari / Firefox. */
+    heapUsedMB?: number;
+    /** JS heap limit, MB. Static per environment. */
+    heapLimitMB?: number;
+    series: {
+        fps: DevtoolsSeries;
+        cpuMs: DevtoolsSeries;
+        gpuMs: DevtoolsSeries;
+        heapUsedMB: DevtoolsSeries;
+        drawCalls: DevtoolsSeries;
+        triangles: DevtoolsSeries;
+        primitives: DevtoolsSeries;
+        geometries: DevtoolsSeries;
+        textures: DevtoolsSeries;
+    };
+    threeFlatlandVersion?: string;
+    threeRevision?: string;
+    backendName?: string;
+    backendTrackTimestamp?: boolean;
+    backendDisjoint?: boolean | null;
+    gpuModeEnabled?: boolean;
+    canvasWidth?: number;
+    canvasHeight?: number;
+    canvasPixelRatio?: number;
+    /**
+     * Named CPU arrays the provider has registered. Entries update on the
+     * `registry` feature of each data batch; keys are entry names, values
+     * are the latest sample + metadata. Removed entries are pruned.
+     */
+    registry: Map<string, RegistryEntrySnapshot>;
+    /**
+     * Named debug buffers — same lifecycle as `registry`, but backed by
+     * periodic GPU readbacks through the `buffers` feature. `pixels` is
+     * `null` until the provider has delivered a sample (metadata arrives
+     * first so the UI can list the entry for selection).
+     */
+    buffers: Map<string, BufferSnapshot>;
+    /**
+     * Most recent batch inspector snapshot — per-pass draw events + active
+     * batch registry contents. Client stores shallow copies of the arrays
+     * so subsequent bus messages don't mutate UI state under a render.
+     */
+    batches: BatchSnapshot;
+    /** All providers currently announced on the bus (updated live). */
+    providers: ProviderIdentity[];
+    /** The provider this client is subscribed to. `null` until discovery picks one. */
+    selectedProviderId: string | null;
+    /** Is the selected provider considered alive? False after `SERVER_LIVENESS_MS` silence. */
+    serverAlive: boolean;
+    /** ms since the last message from the selected provider. */
+    serverLagMs: number;
+}
+/**
+ * Bus consumer. One per viewing surface (tweakpane panel, pop-out
+ * window, remote dashboard). Owns:
+ *
+ *   - A stable consumer id (UUID v4).
+ *   - A `BroadcastChannel` subscription.
+ *   - Accumulated `DevtoolsState` derived from `data` packet deltas.
+ *   - Ack timer (1 s, starts on `subscribe:ack`).
+ *   - Server-liveness monitor; re-subscribes if no server message
+ *     within `SERVER_LIVENESS_MS`.
+ *
+ * Call `start()` to send the initial subscribe + begin timers.
+ * `dispose()` sends unsubscribe, clears timers, closes the channel.
+ */
+declare class DevtoolsClient {
+    readonly id: string;
+    readonly state: DevtoolsState;
+    /** Shared discovery bus — carries query/announce/gone only. */
+    private _discoveryBus;
+    /** Per-provider data bus. Opened when we subscribe; closed on switch / gone. */
+    private _dataBus;
+    /** Bound handler for the current `_dataBus`. Tracked so we can detach on close. */
+    private _dataHandler;
+    private _features;
+    /**
+     * Registry entry filter. `null` = all entries; `string[]` = only
+     * these. Starts empty-array so providers don't drain (sometimes
+     * expensive) registry payloads until the pane actually needs them.
+     */
+    private _registrySelection;
+    /**
+     * Buffer subscription. Map of entry-name → { mode, thumbSize? }.
+     * Empty map = metadata-only (consumer is connected to the `buffers`
+     * feature but isn't actually watching anything — provider skips all
+     * readbacks). `null` is not a distinct state; represented by `{}`.
+     */
+    private _buffersSelection;
+    private _listeners;
+    private _chunkListeners;
+    private _rawMessageListeners;
+    private _ackTimer;
+    private _livenessTimer;
+    private _queryRetryTimer;
+    private _lastServerAt;
+    private _subscribed;
+    private _disposed;
+    /** Known providers by id — updated live via `provider:announce` + `provider:gone`. */
+    private _providers;
+    constructor(options: DevtoolsClientOptions);
+    /**
+     * Begin discovery + subscription. Sends a `provider:query`, waits
+     * `DISCOVERY_WINDOW_MS` for `provider:announce` responses, then picks
+     * the best provider (user > system) and subscribes to it.
+     *
+     * Idempotent — calling again while already started is a no-op.
+     */
+    start(): void;
+    private _sendQuery;
+    /**
+     * Update the feature set. Re-posts `subscribe` on the current
+     * provider's data channel.
+     */
+    setFeatures(features: DebugFeature[]): void;
+    /**
+     * Update the registry entry filter. Pass `null` for "every entry",
+     * `[]` to stop all registry traffic, or a list of names to narrow.
+     * Re-posts `subscribe` if the filter actually changed.
+     */
+    /**
+     * Narrow which registry entries the provider should ship samples
+     * for. `null` = all entries; `[]` = none; `[name, …]` = only these.
+     * Metadata still flows regardless — only sample bytes are gated.
+     */
+    setRegistry(names: string[] | null): void;
+    /**
+     * Update the buffer subscription. Map of entry-name → (mode, thumbSize?).
+     *   - Empty map / missing names → metadata-only (provider sends no pixels,
+     *     runs no readbacks). This is the idle state when no preview or
+     *     modal is visible.
+     *   - `{ name: { mode: 'thumbnail', thumbSize: 256 } }` → small
+     *     downsampled preview. Use when a thumbnail card is visible.
+     *   - `{ name: { mode: 'stream' } }` → full-size VP9 video stream.
+     *     Use when the fullscreen modal is open.
+     *
+     * Mode changes (incl. unsubscribing) take effect on the next
+     * provider flush; the producer will drop old readbacks immediately.
+     */
+    setBuffers(subscription: Record<string, BufferSubscriptionEntry>): void;
+    private _resubscribe;
+    /**
+     * Manually switch to a different provider. No-op if unknown or if
+     * already selected. Closes the old data channel and opens the new one.
+     */
+    selectProvider(providerId: string): void;
+    dispose(): void;
+    /**
+     * Open a fresh per-provider data channel and start listening on it.
+     * Caller is responsible for posting the initial `subscribe`.
+     */
+    private _joinDataChannel;
+    /**
+     * Send `unsubscribe` (if we have someone to tell) and close the data
+     * channel. Idempotent — safe to call when there's no active channel.
+     */
+    private _leaveDataChannel;
+    /**
+     * Handler for the shared discovery bus. Only discovery messages land
+     * here by protocol; anything else is ignored.
+     */
+    private _onDiscoveryMessage;
+    /**
+     * Handler for the per-provider data channel. Everything here is
+     * already implicitly addressed to us (we opened the channel with the
+     * provider's id), so no per-message filtering is required beyond
+     * matching our consumer `id` on `subscribe:ack`.
+     */
+    private _onDataMessage;
+    private _markServerAlive;
+    /**
+     * Pick the best provider from the currently-known set and subscribe
+     * to it. Preference: `user` over `system`; first-announced as
+     * tiebreak. No-op if zero providers are known (we'll stay waiting;
+     * any future `provider:announce` that arrives doesn't auto-trigger
+     * this — call it again or restart discovery).
+     */
+    private _pickProviderAndSubscribe;
+    /** Clear all feature-derived state so the next data packet can start fresh. */
+    private _resetAccumulatedState;
+    /**
+     * Apply a stats batch. Null = reset (feature cleared / provider gone).
+     * Otherwise: decode each typed array onto the matching Float32 ring
+     * and update the scalar with the batch mean (natural smoothing for
+     * the text label).
+     */
+    private _applyStats;
+    /**
+     * Append `count` samples from a scaled integer view to a Float32 ring;
+     * return the batch mean (scaled). Zero-alloc past the ring itself.
+     */
+    private _ingestI16;
+    private _ingestU16;
+    private _ingestU32;
+    /**
+     * Apply a batches feature payload — replaces the snapshot wholesale.
+     * The wire arrays are scratch pools on the producer; we truncate by
+     * the provided counts and copy fields into persistent snapshot
+     * objects the UI can hold across subsequent frames.
+     *
+     * The client-side snapshot arrays grow monotonically to the high
+     * watermark and entries are overwritten in place — same alloc
+     * discipline as the producer.
+     */
+    private _applyBatches;
+    /**
+     * Apply a registry delta. `entries[name] === null` → remove;
+     * `entries[name]` present → upsert a snapshot keyed by `name`.
+     * A `null` batch (feature cleared) drops every entry.
+     */
+    private _applyRegistry;
+    /**
+     * Apply a buffers delta. Metadata (width/height/version/pixelType)
+     * ships regardless of the client's selection; `pixels` only arrives
+     * when this entry is in the current selection. Retain the previous
+     * `pixels` when the delta is metadata-only so the UI keeps showing
+     * the last thumbnail while browsing.
+     */
+    private _applyBuffers;
+    private _applyEnv;
+    private _checkLiveness;
+    private _sendAck;
+    private _postDiscovery;
+    private _postData;
+    private _fireRawMessage;
+    /** Subscribe to state-change events. Returns an unsubscribe function. */
+    addListener(cb: DevtoolsStateListener): () => void;
+    /** Explicit remove — equivalent to calling the unsubscribe returned from `addListener`. */
+    removeListener(cb: DevtoolsStateListener): void;
+    /** Subscribe to incoming WebCodecs buffer chunks. Returns an unsubscribe function. */
+    addChunkListener(cb: BufferChunkListener): () => void;
+    /**
+     * Subscribe to every bus message — both inbound (from providers) and
+     * outbound (our own `subscribe`/`ack`/etc.). Used by the dashboard's
+     * protocol-log panel. Listeners fire on the hot path so keep them
+     * cheap — filter and format lazily.
+     */
+    addRawMessageListener(cb: RawMessageListener): () => void;
+    private _fire;
+}
+
+export { type BatchPassSnapshot, type BatchSnapshot, type BufferChunkListener, type BufferSnapshot, DevtoolsClient, type DevtoolsClientOptions, type DevtoolsSeries, type DevtoolsState, type DevtoolsStateListener, type RawMessageListener, type RegistryEntrySnapshot };