@frockbot/applet-sdk 0.7.150 → 0.7.151

package/src/client/transport.ts

@@ -1,504 +0,0 @@
-/**
- * The one socket an open Applet holds, and everything that hangs off it:
- * the v1 handshake, snapshot and catch-up, mutate/ack/reject, reconnection.
- *
- * TanStack DB never sees a frame. It sees a sink per table (`begin`/`write`/
- * `commit`/`markReady`/`truncate`) and a promise per client transaction, which
- * is the entire seam between this module and `collections.ts`.
- */
-
-import {
-  APPLET_CONTRACT_VERSION,
-  APPLET_PROTOCOL_VERSION,
-  decodeServerFrame,
-  encodeFrame,
-  type AppletChangeV1,
-  type AppletMutationV1,
-  type AppletSnapshotTablesV1,
-  type AppletViewerV1,
-} from "../protocol/index.js";
-
-export interface AppletInitV1 {
-  /** Absolute ws(s):// URL of the Applet's socket, minted by the kernel. */
-  socketUrl: string;
-  /** Short-lived viewer token; appended as `?token=`. */
-  token: string;
-  generationId: string;
-  tokenTransport?: "subprotocol-v1";
-  /**
-   * Report each hop of the open path — socket open, hello, ready — to the
-   * host, for the timing log it keeps behind its own flag. Off by default.
-   */
-  timing?: boolean;
-}
-
-/** The hops a page reports when the host asked for timing. */
-export type AppletTimingHop = "socket-open" | "hello" | "ready";
-
-export type AppletStatus =
-  "idle" | "connecting" | "ready" | "reconnecting" | "closed";
-
-export interface AppletState {
-  status: AppletStatus;
-  viewer: AppletViewerV1 | null;
-  generationId: string | null;
-}
-
-/** Minimal socket shape, so tests and the dev runner can supply their own. */
-export interface AppletSocket {
-  send(data: string): void;
-  close(code?: number, reason?: string): void;
-  onopen: ((event: unknown) => void) | null;
-  onmessage: ((event: { data: unknown }) => void) | null;
-  onclose: ((event: unknown) => void) | null;
-  onerror: ((event: unknown) => void) | null;
-}
-
-export type AppletSocketFactory = (
-  url: string,
-  protocols?: string[],
-) => AppletSocket;
-
-/** What a TanStack DB collection hands the transport for one table. */
-export interface AppletTableSink {
-  begin(): void;
-  write(message: {
-    type: "insert" | "update" | "delete";
-    key?: string;
-    value?: Record<string, unknown>;
-  }): void;
-  commit(): void;
-  markReady(): void;
-  truncate(): void;
-}
-
-export interface AppletTransportOptions {
-  socketFactory?: AppletSocketFactory;
-  /** Reconnection backoff bounds, in milliseconds. */
-  minimumBackoffMs?: number;
-  maximumBackoffMs?: number;
-  /** Scheduler seam so tests do not wait in real time. */
-  schedule?: (closure: () => void, delayMs: number) => unknown;
-  /** Where a timing hop goes when `init.timing` is set; the page posts to its host. */
-  onTiming?: (hop: AppletTimingHop) => void;
-}
-
-class RejectedMutation extends Error {}
-
-function defaultSocketFactory(url: string, protocols?: string[]): AppletSocket {
-  return new WebSocket(url, protocols) as unknown as AppletSocket;
-}
-
-export class AppletTransport {
-  #options: Required<
-    Omit<AppletTransportOptions, "socketFactory" | "onTiming">
-  > & {
-    socketFactory: AppletSocketFactory;
-    onTiming: ((hop: AppletTimingHop) => void) | undefined;
-  };
-  #socket?: AppletSocket;
-  #init?: AppletInitV1;
-  #state: AppletState = { status: "idle", viewer: null, generationId: null };
-  #listeners = new Set<() => void>();
-  #sinks = new Map<string, AppletTableSink>();
-  #pending = new Map<
-    string,
-    {
-      resolve: (changes: AppletChangeV1[]) => void;
-      reject: (error: Error) => void;
-    }
-  >();
-  #lastChangeId = 0;
-  #synced = false;
-  #buffer: AppletChangeV1[] = [];
-  #attempt = 0;
-  #closed = false;
-  #resyncQueued = false;
-  #txnSeq = 0;
-  /**
-   * Every socket this transport has opened gets a number, and only the newest
-   * one owns the shared connection state. `error` and `close` both fire for a
-   * single failure, and a socket the transport has already given up on can
-   * still call back later, so a callback carrying a superseded identity is
-   * dropped instead of reconnecting or clearing state a live socket owns.
-   */
-  #socketSeq = 0;
-  #currentSocketId = 0;
-  /**
-   * At most one reconnect is outstanding. The scheduler seam cannot cancel a
-   * timer, so a retry carries an identity too: `#pendingRetryId` is cleared or
-   * replaced whenever the retry is superseded, and a closure that fires with a
-   * stale identity does nothing.
-   */
-  #retrySeq = 0;
-  #pendingRetryId = 0;
-  /**
-   * Whether this socket has sent its own `hello`. A v2 socket that opened with
-   * no cursor sends none: the server's `hello` carries the snapshot, and only
-   * a hello that arrives without one — a server that could not fit it, or one
-   * that speaks v1 — is answered.
-   */
-  #helloSent = false;
-
-  constructor(options: AppletTransportOptions = {}) {
-    this.#options = {
-      socketFactory: options.socketFactory ?? defaultSocketFactory,
-      minimumBackoffMs: options.minimumBackoffMs ?? 250,
-      maximumBackoffMs: options.maximumBackoffMs ?? 8_000,
-      schedule:
-        options.schedule ?? ((closure, delay) => setTimeout(closure, delay)),
-      onTiming: options.onTiming,
-    };
-  }
-
-  get state(): AppletState {
-    return this.#state;
-  }
-
-  subscribe(listener: () => void): () => void {
-    this.#listeners.add(listener);
-    return () => this.#listeners.delete(listener);
-  }
-
-  /**
-   * Open the socket. Called by the dev runner, the tests, and the `init`
-   * bridge. Calling it again — a fresh viewer token after the old one expired,
-   * say — supersedes whatever socket or pending reconnect is outstanding, so a
-   * reconnect never races the connection the caller just asked for.
-   */
-  connect(init: AppletInitV1): void {
-    this.#init = init;
-    this.#closed = false;
-    this.#reset();
-    this.#attempt = 0;
-    this.#open();
-  }
-
-  /**
-   * A fresh viewer credential for the page that is already running: the
-   * host's `refresh` message. The document stays; the transport reconnects
-   * in place with the new token, and since it carries its cursor the server
-   * answers with `changes` rather than a snapshot. The same credential
-   * offered twice — a host re-sending what the page already holds — is not
-   * a reason to drop a live socket.
-   */
-  refresh(init: AppletInitV1): void {
-    const held = this.#init;
-    if (
-      held &&
-      this.#socket &&
-      !this.#closed &&
-      held.token === init.token &&
-      held.socketUrl === init.socketUrl &&
-      held.generationId === init.generationId
-    ) {
-      this.#init = init;
-      return;
-    }
-    this.connect(init);
-  }
-
-  close(): void {
-    this.#closed = true;
-    this.#reset(1000, "closed");
-    this.#failPending(new Error("The Applet connection was closed"));
-    this.#setState({ status: "closed" });
-  }
-
-  /**
-   * Give up the current socket and any pending reconnect. The socket is closed
-   * rather than merely forgotten, so a superseded connection cannot keep
-   * receiving frames, and its late `close` arrives with a stale identity.
-   */
-  #reset(code = 1000, reason = "superseded"): void {
-    this.#pendingRetryId = 0;
-    const socket = this.#socket;
-    this.#socket = undefined;
-    this.#currentSocketId = 0;
-    this.#synced = false;
-    if (socket) {
-      try {
-        socket.close(code, reason);
-      } catch {
-        // A socket that is already gone needs no closing.
-      }
-    }
-  }
-
-  #open(): void {
-    if (!this.#init || this.#closed) return;
-    // Never open while another attempt is current.
-    if (this.#socket) return;
-    this.#pendingRetryId = 0;
-    const id = ++this.#socketSeq;
-    this.#currentSocketId = id;
-    this.#setState({
-      status: this.#attempt === 0 ? "connecting" : "reconnecting",
-    });
-    const url = new URL(this.#init.socketUrl);
-    // The version this page speaks and, on a reconnect, the cursor it will
-    // resume from, both settled before the first frame so the server's hello
-    // can carry the snapshot exactly when one is needed.
-    url.searchParams.set("v", String(APPLET_PROTOCOL_VERSION));
-    const since = this.#lastChangeId === 0 ? undefined : this.#lastChangeId;
-    if (since !== undefined) url.searchParams.set("since", String(since));
-    const protocols =
-      this.#init.tokenTransport === "subprotocol-v1"
-        ? ["frockbot.applet.v1", `frockbot.viewer.${this.#init.token}`]
-        : undefined;
-    if (!protocols) url.searchParams.set("token", this.#init.token);
-    const socket = this.#options.socketFactory(url.toString(), protocols);
-    this.#socket = socket;
-    this.#helloSent = false;
-    socket.onopen = () => {
-      if (this.#currentSocketId !== id) return;
-      this.#timing("socket-open");
-      // A resume asks for its catch-up at once, crossing the server's hello
-      // on the wire as it always has. A first connection waits: the hello on
-      // its way carries the snapshot.
-      if (since !== undefined) this.#handshake();
-    };
-    socket.onmessage = (event) => {
-      if (this.#currentSocketId === id) this.#receive(event.data);
-    };
-    socket.onclose = () => this.#dropped(id);
-    socket.onerror = () => this.#dropped(id);
-  }
-
-  #handshake(): void {
-    const since = this.#lastChangeId === 0 ? undefined : this.#lastChangeId;
-    this.#helloSent = true;
-    this.#write({
-      v: APPLET_PROTOCOL_VERSION,
-      type: "hello",
-      contract: APPLET_CONTRACT_VERSION,
-      ...(since === undefined ? {} : { since }),
-    });
-  }
-
-  #timing(hop: AppletTimingHop): void {
-    if (this.#init?.timing) this.#options.onTiming?.(hop);
-  }
-
-  /**
-   * One failure reaches here twice — `error` then `close` — and a socket the
-   * transport already replaced can reach here at any time. Only the socket that
-   * still owns the connection schedules a replacement.
-   */
-  #dropped(id: number): void {
-    if (id !== this.#currentSocketId) return;
-    if (this.#closed) return;
-    this.#reset(1000, "dropped");
-    this.#failPending(new Error("The Applet connection dropped"));
-    const retryId = ++this.#retrySeq;
-    this.#pendingRetryId = retryId;
-    const delay = Math.min(
-      this.#options.maximumBackoffMs,
-      this.#options.minimumBackoffMs * 2 ** this.#attempt,
-    );
-    this.#attempt += 1;
-    this.#setState({ status: "reconnecting" });
-    this.#options.schedule(
-      () => {
-        if (this.#pendingRetryId !== retryId) return;
-        this.#pendingRetryId = 0;
-        this.#open();
-      },
-      delay * (0.5 + Math.random() / 2),
-    );
-  }
-
-  #receive(data: unknown): void {
-    let frame;
-    try {
-      frame = decodeServerFrame(data);
-    } catch {
-      // A frame this client cannot understand is a protocol break, not a blip:
-      // drop the socket so the reconnect path takes a clean snapshot.
-      this.#socket?.close(1008, "Unreadable frame");
-      return;
-    }
-
-    if (frame.type === "hello") {
-      this.#timing("hello");
-      const changedGeneration =
-        this.#state.generationId !== null &&
-        this.#state.generationId !== frame.generationId;
-      this.#setState({
-        viewer: frame.viewer,
-        generationId: frame.generationId,
-      });
-      if (changedGeneration) {
-        // New code over the same storage: never replay across the boundary.
-        this.#lastChangeId = 0;
-        this.#synced = false;
-        this.#buffer = [];
-      }
-      if (frame.snapshot) {
-        // The whole state came with the greeting: render on it, and send
-        // nothing back. A hello for a new generation carries that
-        // generation's rows, so the reset above is what it needs.
-        this.#snapshot(frame.lastChangeId, frame.snapshot);
-        return;
-      }
-      if (changedGeneration || !this.#helloSent) {
-        // Nothing came with the greeting: a server that could not fit the
-        // snapshot, one that speaks v1, or new code over the same storage.
-        // Ask, as v1 always did.
-        this.#helloSent = true;
-        this.#write({
-          v: APPLET_PROTOCOL_VERSION,
-          type: "hello",
-          contract: APPLET_CONTRACT_VERSION,
-        });
-      }
-      return;
-    }
-
-    if (frame.type === "snapshot") {
-      this.#snapshot(frame.lastChangeId, frame.tables);
-      return;
-    }
-
-    if (frame.type === "changes") {
-      this.#lastChangeId = frame.lastChangeId;
-      if (!this.#synced) {
-        // Catch-up after a reconnect arrives without a snapshot; the sinks are
-        // already populated from the previous session, so apply it directly.
-        this.#synced = true;
-        this.#attempt = 0;
-        this.#setState({ status: "ready" });
-        for (const sink of this.#sinks.values()) sink.markReady();
-        this.#timing("ready");
-      }
-      this.#apply(frame.changes);
-      return;
-    }
-
-    if (frame.type === "ack") {
-      this.#lastChangeId = frame.lastChangeId;
-      // The authoritative rows must reach the sync layer before the optimistic
-      // transaction is discarded, or the row would vanish on resolve.
-      this.#apply(frame.changes);
-      this.#pending.get(frame.txnId)?.resolve(frame.changes);
-      this.#pending.delete(frame.txnId);
-      return;
-    }
-
-    this.#pending.get(frame.txnId)?.reject(new RejectedMutation(frame.reason));
-    this.#pending.delete(frame.txnId);
-  }
-
-  /** The whole state, from a `snapshot` frame or a v2 hello: replace and mark ready. */
-  #snapshot(lastChangeId: number, tables: AppletSnapshotTablesV1): void {
-    this.#lastChangeId = lastChangeId;
-    for (const [name, sink] of this.#sinks) {
-      // `truncate` only has meaning inside an open sync transaction.
-      sink.begin();
-      sink.truncate();
-      for (const row of tables[name] ?? [])
-        sink.write({ type: "insert", value: row });
-      sink.commit();
-      sink.markReady();
-    }
-    this.#synced = true;
-    this.#attempt = 0;
-    this.#setState({ status: "ready" });
-    this.#timing("ready");
-    const buffered = this.#buffer;
-    this.#buffer = [];
-    if (buffered.length > 0) this.#apply(buffered);
-  }
-
-  #apply(changes: AppletChangeV1[]): void {
-    if (!this.#synced) {
-      this.#buffer.push(...changes);
-      return;
-    }
-    const byTable = new Map<string, AppletChangeV1[]>();
-    for (const change of changes) {
-      const list = byTable.get(change.table);
-      if (list) list.push(change);
-      else byTable.set(change.table, [change]);
-    }
-    for (const [name, list] of byTable) {
-      const sink = this.#sinks.get(name);
-      if (!sink) continue;
-      sink.begin();
-      for (const change of list) {
-        if (change.op === "delete")
-          sink.write({ type: "delete", key: change.key });
-        else sink.write({ type: change.op, value: change.row });
-      }
-      sink.commit();
-    }
-  }
-
-  /** Register a table's sink; returns the cleanup TanStack DB expects. */
-  registerTable(name: string, sink: AppletTableSink): () => void {
-    this.#sinks.set(name, sink);
-    if (this.#synced) this.#queueResync();
-    return () => {
-      if (this.#sinks.get(name) === sink) this.#sinks.delete(name);
-    };
-  }
-
-  /**
-   * A table that mounts after the first snapshot has no rows of its own, so ask
-   * for a fresh snapshot. Coalesced, because a first render registers them all
-   * in the same tick.
-   */
-  #queueResync(): void {
-    if (this.#resyncQueued) return;
-    this.#resyncQueued = true;
-    queueMicrotask(() => {
-      this.#resyncQueued = false;
-      if (!this.#socket) return;
-      this.#synced = false;
-      this.#helloSent = true;
-      this.#write({
-        v: APPLET_PROTOCOL_VERSION,
-        type: "hello",
-        contract: APPLET_CONTRACT_VERSION,
-      });
-    });
-  }
-
-  /** Send one client transaction; resolves on `ack`, rejects on `reject`. */
-  mutate(mutations: AppletMutationV1[]): Promise<AppletChangeV1[]> {
-    if (!this.#socket) {
-      return Promise.reject(new Error("The Applet is not connected"));
-    }
-    const txnId = `c${++this.#txnSeq}`;
-    return new Promise<AppletChangeV1[]>((resolve, reject) => {
-      this.#pending.set(txnId, { resolve, reject });
-      try {
-        this.#write({
-          v: APPLET_PROTOCOL_VERSION,
-          type: "mutate",
-          txnId,
-          mutations,
-        });
-      } catch (error) {
-        this.#pending.delete(txnId);
-        reject(error instanceof Error ? error : new Error(String(error)));
-      }
-    });
-  }
-
-  #write(frame: Parameters<typeof encodeFrame>[0]): void {
-    const socket = this.#socket;
-    if (!socket) throw new Error("The Applet is not connected");
-    socket.send(encodeFrame(frame));
-  }
-
-  #failPending(error: Error): void {
-    for (const entry of this.#pending.values()) entry.reject(error);
-    this.#pending.clear();
-  }
-
-  #setState(patch: Partial<AppletState>): void {
-    this.#state = { ...this.#state, ...patch };
-    for (const listener of this.#listeners) listener();
-  }
-}

package/src/kit/README.md

@@ -1,130 +0,0 @@
-# The Applet component kit
-
-`import { … } from "@frockbot/applet-sdk/kit"`
-
-Fourteen components. They are the whole visual vocabulary of an Applet: there
-is no CSS file to write and no colour to choose. Every surface, edge, and
-accent resolves through the nine semantic tokens the host injects, so an Applet
-follows the User's theme — light, dark, or anything FrockBot ships later —
-without knowing which one is on.
-
-**Do not** write `#hex`, `rgb(...)`, `hsl(...)`, or a colour name anywhere. The
-linter rejects them in `.ts`, `.tsx`, and `.css` alike. If a component cannot
-express what you want, the kit is missing something — say so rather than
-styling around it.
-
-## Layout
-
-### `Stack`
-
-The only layout primitive. Rows and columns, nothing else.
-
-| Prop        | Type                                          | Default    |
-| ----------- | --------------------------------------------- | ---------- |
-| `direction` | `"row" \| "column"`                           | `"column"` |
-| `gap`       | `"none" \| "small" \| "medium" \| "large"`    | `"medium"` |
-| `align`     | `"start" \| "center" \| "end" \| "stretch"`   | —          |
-| `justify`   | `"start" \| "center" \| "end" \| "between"`   | —          |
-| `wrap`      | `boolean`                                     | `false`    |
-| `root`      | `boolean` — put exactly one at the page's top | `false`    |
-
-```tsx
-<Stack root gap="large">
-  <Stack direction="row" gap="small" align="end">
-    …
-  </Stack>
-</Stack>
-```
-
-### `Text`
-
-| Prop   | Type                                             | Default     |
-| ------ | ------------------------------------------------ | ----------- |
-| `size` | `"title" \| "heading" \| "body" \| "small"`      | `"body"`    |
-| `tone` | `"default" \| "muted"`                           | `"default"` |
-| `as`   | `"p" \| "span" \| "div" \| "h1" \| "h2" \| "h3"` | `"p"`       |
-
-## Controls
-
-### `Button`
-
-| Prop       | Type                                | Default     |
-| ---------- | ----------------------------------- | ----------- |
-| `variant`  | `"default" \| "primary" \| "ghost"` | `"default"` |
-| `onClick`  | `() => void`                        | —           |
-| `disabled` | `boolean`                           | `false`     |
-
-Also accepts the ordinary `<button>` attributes except `className` and `style`.
-`type` defaults to `"button"`, so it never submits a form by accident.
-
-### `Input`, `Textarea`
-
-| Prop            | Type                      | Notes                                |
-| --------------- | ------------------------- | ------------------------------------ |
-| `label`         | `string`                  | rendered above the control           |
-| `error`         | `string`                  | rendered below, in the accent colour |
-| `value`         | `string`                  | controlled                           |
-| `onValueChange` | `(value: string) => void` | receives the value, not the event    |
-| `placeholder`   | `string`                  |                                      |
-
-`onKeyDown`, `disabled`, and the rest of the native attributes pass through.
-
-### `Select`
-
-Adds `options: Array<{ value: string; label: string }>`; otherwise identical to
-`Input`.
-
-### `Checkbox`
-
-| Prop        | Type                         | Notes                             |
-| ----------- | ---------------------------- | --------------------------------- |
-| `checked`   | `boolean`                    | required                          |
-| `onChange`  | `(checked: boolean) => void` | required                          |
-| `label`     | `ReactNode`                  | optional visible label            |
-| `ariaLabel` | `string`                     | required when there is no `label` |
-| `disabled`  | `boolean`                    |                                   |
-
-## Surfaces
-
-### `Card`
-
-`title?: ReactNode`, plus children. A bordered panel.
-
-### `Toolbar`
-
-`children` sit at the leading edge; `end?: ReactNode` is pushed to the trailing
-edge. Use it for the Applet's title and its status or primary action.
-
-### `List` and `ListItem`
-
-`List` takes `bordered?: boolean` (default `true`) and `ListItem` children.
-
-`ListItem`: `start?: ReactNode` (a checkbox, a badge), `end?: ReactNode`
-(actions), `onClick?: () => void` (makes the row interactive), and children as
-the body.
-
-### `Badge`
-
-`tone?: "default" | "accent"`, plus children.
-
-### `EmptyState`
-
-`title: string`, `description?: string`, `action?: ReactNode`. Show it whenever
-a live query comes back empty — an Applet should never render a blank page.
-
-### `Dialog`
-
-| Prop      | Type         | Notes                                     |
-| --------- | ------------ | ----------------------------------------- |
-| `open`    | `boolean`    | renders nothing when false                |
-| `onClose` | `() => void` | fires on Escape and on a backdrop click   |
-| `title`   | `ReactNode`  | also becomes the dialog's accessible name |
-| `actions` | `ReactNode`  | a trailing row, usually two `Button`s     |
-
-## The nine tokens
-
-The host re-emits these into the page on `init`; the kit reads them and so may
-you, always through `var(--frockbot-<name>)`:
-
-`surface`, `surface-raised`, `surface-subtle`, `text`, `text-muted`, `border`,
-`accent-surface`, `accent-text`, `radius-card`.