@tuongaz/seeflow 0.1.109 → 0.1.111

package/dist/web/assets/stateDiagram-v2-BHNVJYJU-BzWj6i1l.js

@@ -1 +0,0 @@
-import{b as r,a as e,s as a,S as s}from"./chunk-AQP2D5EJ-DB0ZGTqs.js";import{a as i}from"./mermaid.core-Cmch2GTm.js";import"./index-08hmlCqO.js";import"./chunk-55IACEB6-YeyA7Efg.js";import"./chunk-2J33WTMH-CYHRe8M7.js";import"./purify.es-CLGrRn1w.js";import"./step-CWvwoXpJ.js";var n={parser:a,get db(){return new s(2)},renderer:e,styles:r,init:i(t=>{t.state||(t.state={}),t.state.arrowMarkerAbsolute=t.arrowMarkerAbsolute},"init")};export{n as diagram};

package/src/share/sse-frame.ts

@@ -1,85 +0,0 @@
-/**
- * SSE bridge envelope payload schema for live-share `sse` frames.
- *
- * Single source of truth for the wire shape of runtime events relayed from
- * the host studio's local EventBus to peers over the share WebSocket. Both
- * sides parse against the same Zod schema; drift between this file and the
- * peer SPA's mirror (`seeflow-viewer/src/lib/share-sse-frame.ts`) is gated
- * by `apps/studio/scripts/check-sse-frame-sync.ts`.
- */
-
-import { z } from 'zod';
-import type { StudioEvent } from '../events.ts';
-
-// SYNC-WITH-PEER:BEGIN
-export const SSE_EVENT_TYPES = [
-  'flow:reload',
-  'node:running',
-  'node:done',
-  'node:error',
-  'node:status',
-] as const;
-
-export const SseEventTypeSchema = z.enum(SSE_EVENT_TYPES);
-export type SseEventType = z.infer<typeof SseEventTypeSchema>;
-
-export const SsePayloadSchema = z.object({
-  t: SseEventTypeSchema,
-  flowId: z.string().min(1),
-  ts: z.number().int().nonnegative(),
-  data: z.unknown(),
-  seq: z.number().int().nonnegative(),
-});
-
-export type SsePayload = z.infer<typeof SsePayloadSchema>;
-
-export interface SseEnvelope {
-  v: 1;
-  type: 'sse';
-  from: 'host';
-  to: 'all';
-  payload: SsePayload;
-}
-
-export function isSseEventType(t: string): t is SseEventType {
-  return (SSE_EVENT_TYPES as readonly string[]).includes(t);
-}
-
-/**
- * Snapshot replay payload sent to a freshly-joined peer so its canvas badges
- * match the host without waiting for the next live tick. `flows` is a 2-level
- * map of flowId -> nodeId -> latest SsePayload observed by the host's tap.
- * When the serialized snapshot exceeds the 256 KB per-frame cap, the host
- * splits per-flow and stamps each frame with `chunk` (zero-based) + `total`
- * so the peer can reassemble before applying.
- */
-export const SseSnapshotPayloadSchema = z.object({
-  flows: z.record(z.string(), z.record(z.string(), SsePayloadSchema)),
-  chunk: z.number().int().nonnegative().optional(),
-  total: z.number().int().positive().optional(),
-});
-
-export type SseSnapshotPayload = z.infer<typeof SseSnapshotPayloadSchema>;
-// SYNC-WITH-PEER:END
-
-/**
- * Wrap a local StudioEvent into a relay-shaped `sse` envelope. Returns null
- * when the event type is not one of the SSE-bridged kinds (`file:changed`,
- * `registry:reload`) so callers can filter without try/catch.
- */
-export function wrapAsSseFrame(event: StudioEvent, seq: number): SseEnvelope | null {
-  if (!isSseEventType(event.type)) return null;
-  return {
-    v: 1,
-    type: 'sse',
-    from: 'host',
-    to: 'all',
-    payload: {
-      t: event.type,
-      flowId: event.flowId,
-      ts: event.ts,
-      data: event.payload,
-      seq,
-    },
-  };
-}

package/src/share/sse-outbound-queue.ts

@@ -1,173 +0,0 @@
-/**
- * US-072 — Per-peer outbound SSE queue with drop-on-slow-consumer.
- *
- * A bounded async queue, one instance per connected peer, that decouples the
- * host's SSE bridge (synchronous EventBus -> tap -> per-peer enqueue) from the
- * relay WebSocket's send path. If a peer's drain is slow, frames accumulate up
- * to `maxFrames` (default 256). On overflow:
- *
- *   - Non-terminal new frame: evict the OLDEST non-terminal entry. If no
- *     non-terminal entries exist (queue full of terminals), drop the new one.
- *   - Terminal new frame (`node:done` / `node:error`): evict the OLDEST entry
- *     regardless of type so the terminal is always queued.
- *
- * Per-peer metrics (`queueDepth`, `droppedFrames`, `lastSendMs`) are surfaced
- * to the LiveShareDialog via the local `/api/share/state` SSE stream. When the
- * rolling 60s drop count exceeds 100, the queue fires `onResyncTriggered` so
- * the host can emit an `sse-snapshot` to recover the peer's canvas state.
- *
- * Enqueue is synchronous and non-blocking; the producer (the SSE tap) never
- * awaits the WebSocket send. The drain runs as a single concurrent async loop
- * — at most one in-flight send per peer keeps frame ordering stable while
- * still letting different peers' queues drain in parallel.
- */
-
-import type { SsePayload } from './sse-frame.ts';
-
-const TERMINAL_TYPES = new Set<SsePayload['t']>(['node:done', 'node:error']);
-
-export const DEFAULT_MAX_FRAMES = 256;
-export const DEFAULT_DROP_RESYNC_THRESHOLD = 100;
-export const DEFAULT_DROP_RESYNC_WINDOW_MS = 60_000;
-
-const isTerminalPayload = (p: SsePayload): boolean => TERMINAL_TYPES.has(p.t);
-
-export interface PeerSseQueueMetrics {
-  /** Frames currently waiting to be sent (excludes the in-flight frame). */
-  queueDepth: number;
-  /** Lifetime count of frames evicted due to overflow. */
-  droppedFrames: number;
-  /** Duration in ms of the last awaited `send` call (null until first send). */
-  lastSendMs: number | null;
-}
-
-export interface PeerSseQueueOpts {
-  peerConnId: string;
-  /**
-   * Underlying send for the queue. Awaited per-frame so slow consumers create
-   * backpressure here rather than in the producer. Resolves on success; any
-   * error is swallowed (logged) so a single bad frame doesn't stall the drain.
-   */
-  send: (payload: SsePayload, peerConnId: string) => Promise<void> | void;
-  /** Defaults to 256. */
-  maxFrames?: number;
-  /**
-   * Called when `droppedFrames` within `dropResyncWindowMs` exceeds
-   * `dropResyncThreshold`. The window counter is reset after firing so the
-   * next trigger requires another full window of drops.
-   */
-  onResyncTriggered?: () => void;
-  /** Defaults to 100. */
-  dropResyncThreshold?: number;
-  /** Defaults to 60_000. */
-  dropResyncWindowMs?: number;
-  /** Defaults to `Date.now`. */
-  now?: () => number;
-}
-
-export interface PeerSseQueue {
-  /** Synchronously enqueue. Returns void; never awaits the underlying send. */
-  enqueue(payload: SsePayload): void;
-  metrics(): PeerSseQueueMetrics;
-  /** Stops the drain loop and discards pending frames. Idempotent. */
-  dispose(): void;
-}
-
-interface QueuedFrame {
-  payload: SsePayload;
-  terminal: boolean;
-}
-
-export function createPeerSseQueue(opts: PeerSseQueueOpts): PeerSseQueue {
-  const maxFrames = opts.maxFrames ?? DEFAULT_MAX_FRAMES;
-  const dropThreshold = opts.dropResyncThreshold ?? DEFAULT_DROP_RESYNC_THRESHOLD;
-  const dropWindowMs = opts.dropResyncWindowMs ?? DEFAULT_DROP_RESYNC_WINDOW_MS;
-  const now = opts.now ?? Date.now;
-
-  const queue: QueuedFrame[] = [];
-  const dropTimestamps: number[] = [];
-  let droppedFrames = 0;
-  let lastSendMs: number | null = null;
-  let disposed = false;
-  let draining = false;
-
-  const recordDrop = (): void => {
-    droppedFrames += 1;
-    const ts = now();
-    dropTimestamps.push(ts);
-    const cutoff = ts - dropWindowMs;
-    while (dropTimestamps.length > 0 && (dropTimestamps[0] ?? 0) < cutoff) {
-      dropTimestamps.shift();
-    }
-    if (dropTimestamps.length > dropThreshold) {
-      dropTimestamps.length = 0;
-      try {
-        opts.onResyncTriggered?.();
-      } catch (err) {
-        console.warn('[share] sse-outbound onResyncTriggered threw:', err);
-      }
-    }
-  };
-
-  const drain = async (): Promise<void> => {
-    if (draining || disposed) return;
-    draining = true;
-    try {
-      while (queue.length > 0 && !disposed) {
-        const frame = queue.shift();
-        if (!frame) break;
-        const start = now();
-        try {
-          await opts.send(frame.payload, opts.peerConnId);
-        } catch (err) {
-          console.warn('[share] sse-outbound send failed:', err);
-        }
-        lastSendMs = now() - start;
-      }
-    } finally {
-      draining = false;
-    }
-  };
-
-  const enqueue = (payload: SsePayload): void => {
-    if (disposed) return;
-    const terminal = isTerminalPayload(payload);
-
-    if (queue.length >= maxFrames) {
-      if (terminal) {
-        // Drop the oldest entry regardless of type so the terminal frame
-        // always finds a slot — terminal-wins semantics drive the peer's
-        // visual reconciliation back to a settled state.
-        queue.shift();
-        recordDrop();
-      } else {
-        const idx = queue.findIndex((f) => !f.terminal);
-        if (idx === -1) {
-          // Queue is full of terminals — drop the incoming non-terminal so
-          // we don't displace a settled state with a stale running tick.
-          recordDrop();
-          return;
-        }
-        queue.splice(idx, 1);
-        recordDrop();
-      }
-    }
-
-    queue.push({ payload, terminal });
-    void drain();
-  };
-
-  return {
-    enqueue,
-    metrics: (): PeerSseQueueMetrics => ({
-      queueDepth: queue.length,
-      droppedFrames,
-      lastSendMs,
-    }),
-    dispose: (): void => {
-      disposed = true;
-      queue.length = 0;
-      dropTimestamps.length = 0;
-    },
-  };
-}

package/src/share/sse-rate-limit.ts

@@ -1,205 +0,0 @@
-/**
- * Token-bucket rate limiter + per-(flowId, nodeId) coalescer for SSE bridge
- * frames. Sits between the SSE tap's event source and the relay broadcast so
- * a noisy `node:status` storm cannot saturate the relay or peer browsers.
- *
- * Semantics:
- * - Sustained rate `tokensPerSecond` (default 60) with bucket capacity
- *   `burst` (default 120). Each non-terminal frame consumes one token.
- * - Non-terminal frames that arrive with no tokens are queued. When a
- *   `node:status` frame for the same `(flowId, nodeId)` is already pending,
- *   the latest payload replaces the queued one (last-wins coalescing) and
- *   `droppedFrames` is incremented for the displaced payload.
- * - Terminal events (`node:done`, `node:error`) are NEVER coalesced or
- *   dropped — they bypass the bucket and emit immediately.
- * - When the queue exceeds `maxQueueDepth` (default = burst), the oldest
- *   pending non-terminal frame is dropped and `droppedFrames` is incremented.
- */
-
-import type { SsePayload } from './sse-frame.ts';
-
-const TERMINAL_TYPES: ReadonlySet<SsePayload['t']> = new Set(['node:done', 'node:error']);
-
-export interface RateLimitOptions {
-  /** Tokens added per second. Default 60. */
-  tokensPerSecond?: number;
-  /** Bucket capacity (burst size). Default 120. */
-  burst?: number;
-  /**
-   * Max pending non-terminal frames in the queue. Default = `burst`.
-   * Overflow drops the oldest pending frame.
-   */
-  maxQueueDepth?: number;
-  /** Outbound emit callback (post-rate-limit). */
-  onEmit: (frame: SsePayload) => void;
-  /** Monotonic time source in milliseconds. Defaults to `performance.now()`. */
-  now?: () => number;
-  /**
-   * Schedule `fn` to run after `ms` milliseconds, returning a cancel function.
-   * Defaults to `setTimeout`. Injected in tests for deterministic draining.
-   */
-  schedule?: (ms: number, fn: () => void) => () => void;
-}
-
-export interface RateLimitMetrics {
-  droppedFrames: number;
-  queueDepth: number;
-}
-
-export interface RateLimiter {
-  submit(frame: SsePayload): void;
-  metrics(): RateLimitMetrics;
-  /** Drain all queued frames immediately, ignoring tokens. */
-  flush(): void;
-  dispose(): void;
-}
-
-function defaultNow(): number {
-  return typeof performance !== 'undefined' ? performance.now() : Date.now();
-}
-
-function defaultSchedule(ms: number, fn: () => void): () => void {
-  const handle = setTimeout(fn, ms);
-  return () => clearTimeout(handle);
-}
-
-function coalesceKey(frame: SsePayload): string | null {
-  if (frame.t !== 'node:status') return null;
-  const data = frame.data;
-  const nodeId =
-    data && typeof data === 'object' ? (data as { nodeId?: unknown }).nodeId : undefined;
-  if (typeof nodeId !== 'string' || nodeId.length === 0) return null;
-  return `${frame.flowId}\x00${nodeId}`;
-}
-
-export function createRateLimiter(opts: RateLimitOptions): RateLimiter {
-  const tokensPerSecond = Math.max(0.0001, opts.tokensPerSecond ?? 60);
-  const burst = Math.max(1, opts.burst ?? 120);
-  const maxQueueDepth = Math.max(1, opts.maxQueueDepth ?? burst);
-  const now = opts.now ?? defaultNow;
-  const schedule = opts.schedule ?? defaultSchedule;
-
-  let tokens = burst;
-  let lastRefill = now();
-  let droppedFrames = 0;
-  let drainCancel: (() => void) | null = null;
-  let disposed = false;
-
-  const queue: SsePayload[] = [];
-  /** coalesceKey -> queue index */
-  const queueIndex = new Map<string, number>();
-
-  function safeEmit(frame: SsePayload): void {
-    try {
-      opts.onEmit(frame);
-    } catch (err) {
-      console.error('[sse-rate-limit] onEmit listener threw:', err);
-    }
-  }
-
-  function refill(): void {
-    const t = now();
-    const dt = (t - lastRefill) / 1000;
-    if (dt <= 0) return;
-    tokens = Math.min(burst, tokens + dt * tokensPerSecond);
-    lastRefill = t;
-  }
-
-  function rebuildIndex(): void {
-    queueIndex.clear();
-    for (let i = 0; i < queue.length; i++) {
-      const frame = queue[i];
-      if (!frame) continue;
-      const k = coalesceKey(frame);
-      if (k !== null) queueIndex.set(k, i);
-    }
-  }
-
-  function clearDrainTimer(): void {
-    if (drainCancel) {
-      drainCancel();
-      drainCancel = null;
-    }
-  }
-
-  function scheduleDrain(): void {
-    if (disposed || queue.length === 0 || drainCancel) return;
-    refill();
-    const needed = Math.max(0, 1 - tokens);
-    const waitMs = Math.ceil((needed / tokensPerSecond) * 1000);
-    drainCancel = schedule(Math.max(1, waitMs), () => {
-      drainCancel = null;
-      drainQueue();
-    });
-  }
-
-  function drainQueue(): void {
-    refill();
-    while (queue.length > 0 && tokens >= 1) {
-      const frame = queue.shift();
-      if (!frame) break;
-      tokens -= 1;
-      safeEmit(frame);
-    }
-    rebuildIndex();
-    scheduleDrain();
-  }
-
-  function enqueueNonTerminal(frame: SsePayload): void {
-    const key = coalesceKey(frame);
-    if (key !== null) {
-      const idx = queueIndex.get(key);
-      if (idx !== undefined && idx < queue.length && queue[idx] !== undefined) {
-        // Last-wins: replace the queued payload; older payload is "dropped".
-        queue[idx] = frame;
-        droppedFrames += 1;
-        return;
-      }
-    }
-    if (queue.length >= maxQueueDepth) {
-      queue.shift();
-      droppedFrames += 1;
-      rebuildIndex();
-    }
-    const newIdx = queue.length;
-    queue.push(frame);
-    if (key !== null) queueIndex.set(key, newIdx);
-  }
-
-  return {
-    submit(frame) {
-      if (disposed) return;
-
-      if (TERMINAL_TYPES.has(frame.t)) {
-        safeEmit(frame);
-        return;
-      }
-
-      refill();
-      if (queue.length === 0 && tokens >= 1) {
-        tokens -= 1;
-        safeEmit(frame);
-        return;
-      }
-
-      enqueueNonTerminal(frame);
-      scheduleDrain();
-    },
-    metrics() {
-      return { droppedFrames, queueDepth: queue.length };
-    },
-    flush() {
-      for (const frame of queue) safeEmit(frame);
-      queue.length = 0;
-      queueIndex.clear();
-      clearDrainTimer();
-    },
-    dispose() {
-      if (disposed) return;
-      disposed = true;
-      clearDrainTimer();
-      queue.length = 0;
-      queueIndex.clear();
-    },
-  };
-}

package/src/share/sse-tap.ts

@@ -1,183 +0,0 @@
-/**
- * SSE tap: subscribes to the local EventBus for every flowId in the shared
- * project, mirrors each bridged event into a per-flow ring buffer, and feeds
- * the relay bridge via `onEvent`. A process-wide monotonic `seq` counter is
- * stamped on every payload so peers can detect drops and out-of-order frames.
- *
- * Used by `apps/studio/src/share.ts` (US-067) to forward live runtime events
- * to connected peers, and exposes a `snapshot()` of last-seen status per node
- * so newly joined peers can be primed without replaying the entire buffer
- * (US-069 / US-070).
- */
-
-import type { EventBus, StudioEvent } from '../events.ts';
-import { type SsePayload, isSseEventType } from './sse-frame.ts';
-import {
-  type RateLimitMetrics,
-  type RateLimitOptions,
-  type RateLimiter,
-  createRateLimiter,
-} from './sse-rate-limit.ts';
-
-export interface SseTapOptions {
-  /** Called on every refresh to compute the desired subscription set. */
-  flowIds: () => string[];
-  /** Invoked synchronously with each bridged event's payload (post-rate-limit). */
-  onEvent: (frame: SsePayload) => void;
-  /** Per-flow ring-buffer cap; defaults to 50. */
-  bufferSize?: number;
-  /**
-   * Token-bucket rate limit + coalescing applied between the EventBus and
-   * `onEvent`. Pass `false` to disable (frames forwarded synchronously).
-   * Defaults to PRD-spec values: 60 frames/sec sustained, burst 120.
-   */
-  rateLimit?: false | Omit<RateLimitOptions, 'onEmit'>;
-}
-
-export interface SseTap {
-  start(): void;
-  stop(): void;
-  /** Re-syncs the subscription set against `opts.flowIds()`. Idempotent. */
-  refreshFlows(): void;
-  /**
-   * Latest per-node status payload, grouped by flow. Only carries node-level
-   * event types (`node:running`/`node:done`/`node:error`/`node:status`).
-   */
-  snapshot(): Record<string, Record<string, SsePayload>>;
-  /** Rate-limit metrics; zeros when rate limiting is disabled. */
-  metrics(): RateLimitMetrics;
-}
-
-const DEFAULT_BUFFER_SIZE = 50;
-
-const NODE_STATUS_TYPES: ReadonlySet<SsePayload['t']> = new Set([
-  'node:running',
-  'node:done',
-  'node:error',
-  'node:status',
-]);
-
-function extractNodeId(payload: unknown): string | null {
-  if (!payload || typeof payload !== 'object') return null;
-  const candidate = (payload as { nodeId?: unknown }).nodeId;
-  return typeof candidate === 'string' && candidate.length > 0 ? candidate : null;
-}
-
-export function createSseTap(events: EventBus, opts: SseTapOptions): SseTap {
-  const bufferSize = Math.max(1, opts.bufferSize ?? DEFAULT_BUFFER_SIZE);
-  let seqCounter = 0;
-  let started = false;
-
-  const unsubs = new Map<string, () => void>();
-  const buffers = new Map<string, SsePayload[]>();
-  const latestByNode = new Map<string, Map<string, SsePayload>>();
-
-  const limiter: RateLimiter | null =
-    opts.rateLimit === false
-      ? null
-      : createRateLimiter({ ...(opts.rateLimit ?? {}), onEmit: opts.onEvent });
-
-  function pushToBuffer(flowId: string, payload: SsePayload): void {
-    let buf = buffers.get(flowId);
-    if (!buf) {
-      buf = [];
-      buffers.set(flowId, buf);
-    }
-    buf.push(payload);
-    if (buf.length > bufferSize) buf.shift();
-  }
-
-  function recordLatestStatus(flowId: string, payload: SsePayload): void {
-    if (!NODE_STATUS_TYPES.has(payload.t)) return;
-    const nodeId = extractNodeId(payload.data);
-    if (!nodeId) return;
-    let nodeMap = latestByNode.get(flowId);
-    if (!nodeMap) {
-      nodeMap = new Map();
-      latestByNode.set(flowId, nodeMap);
-    }
-    nodeMap.set(nodeId, payload);
-  }
-
-  function makeSubscriber(flowId: string) {
-    return (event: StudioEvent): void => {
-      if (!isSseEventType(event.type)) return;
-      const payload: SsePayload = {
-        t: event.type,
-        flowId: event.flowId,
-        ts: event.ts,
-        data: event.payload,
-        seq: seqCounter++,
-      };
-      pushToBuffer(flowId, payload);
-      recordLatestStatus(flowId, payload);
-      if (limiter) {
-        limiter.submit(payload);
-      } else {
-        try {
-          opts.onEvent(payload);
-        } catch (err) {
-          console.error('[sse-tap] onEvent listener threw:', err);
-        }
-      }
-    };
-  }
-
-  function subscribeFlow(flowId: string): void {
-    if (unsubs.has(flowId)) return;
-    const off = events.subscribe(flowId, makeSubscriber(flowId));
-    unsubs.set(flowId, off);
-  }
-
-  function unsubscribeFlow(flowId: string): void {
-    const off = unsubs.get(flowId);
-    if (!off) return;
-    off();
-    unsubs.delete(flowId);
-    buffers.delete(flowId);
-    latestByNode.delete(flowId);
-  }
-
-  function syncSubscriptions(): void {
-    const desired = new Set(opts.flowIds());
-    for (const existing of [...unsubs.keys()]) {
-      if (!desired.has(existing)) unsubscribeFlow(existing);
-    }
-    for (const id of desired) subscribeFlow(id);
-  }
-
-  return {
-    start(): void {
-      if (started) return;
-      started = true;
-      syncSubscriptions();
-    },
-    stop(): void {
-      if (!started) return;
-      started = false;
-      for (const off of unsubs.values()) off();
-      unsubs.clear();
-      buffers.clear();
-      latestByNode.clear();
-      limiter?.dispose();
-    },
-    refreshFlows(): void {
-      if (!started) return;
-      syncSubscriptions();
-    },
-    snapshot(): Record<string, Record<string, SsePayload>> {
-      const out: Record<string, Record<string, SsePayload>> = {};
-      for (const [flowId, nodeMap] of latestByNode) {
-        const nodes: Record<string, SsePayload> = {};
-        for (const [nodeId, payload] of nodeMap) {
-          nodes[nodeId] = payload;
-        }
-        out[flowId] = nodes;
-      }
-      return out;
-    },
-    metrics(): RateLimitMetrics {
-      return limiter ? limiter.metrics() : { droppedFrames: 0, queueDepth: 0 };
-    },
-  };
-}