knobkit 0.0.1

package/src/lib/widgets/file.ts

@@ -0,0 +1,23 @@
+import { bound } from "../bound.js";
+import { controls } from "../controls.js";
+import type { Widget } from "../types.js";
+
+export interface FileWidget extends Widget<{ name: string; url: string }> {
+  // Offer a file for download — the output counterpart to `upload`. Pass a URL (or data URL) and an
+  // optional display name; the name defaults to the URL's last path segment.
+  set(value: { name?: string; url: string } | string): void;
+}
+
+export function file(): FileWidget {
+  return {
+    type: "file",
+    state: { name: "", url: "" },
+    ...controls,
+    set(value: { name?: string; url: string } | string): void {
+      const v = typeof value === "string" ? { url: value } : value;
+      const b = bound(this);
+      b.edit(this, "set", ["url"], v.url);
+      b.edit(this, "set", ["name"], v.name ?? v.url.split("/").pop()?.split("?")[0] ?? "download");
+    },
+  };
+}

package/src/lib/widgets/frame.ts

@@ -0,0 +1,36 @@
+import { event } from "../event.js";
+import { bound } from "../bound.js";
+import { controls } from "../controls.js";
+import type { EventCtor, Widget } from "../types.js";
+
+export interface FrameWidget extends Widget<{ src: string; doc: string }> {
+  sandbox?: string;
+  title: string;
+  loaded: EventCtor;
+  load(url: string): void;
+  show(doc: string): void;
+  clear(): void;
+}
+
+export function frame(opts: { src?: string; doc?: string; sandbox?: string; title?: string } = {}): FrameWidget {
+  return {
+    type: "frame",
+    state: { src: opts.src ?? "", doc: opts.doc ?? "" },
+    sandbox: opts.sandbox,
+    title: opts.title ?? "frame",
+    loaded: event("frame.loaded"),
+    ...controls,
+    load(url: string): void {
+      bound(this).edit(this, "set", ["doc"], "");
+      bound(this).edit(this, "set", ["src"], url);
+    },
+    show(doc: string): void {
+      bound(this).edit(this, "set", ["src"], "");
+      bound(this).edit(this, "set", ["doc"], doc);
+    },
+    clear(): void {
+      bound(this).edit(this, "set", ["src"], "");
+      bound(this).edit(this, "set", ["doc"], "");
+    },
+  };
+}

package/src/lib/widgets/gallery.ts

@@ -0,0 +1,29 @@
+import { bound } from "../bound.js";
+import { controls } from "../controls.js";
+import type { Widget } from "../types.js";
+
+export interface GalleryItem {
+  src: string; // URL or data URL
+  caption?: string;
+}
+
+export interface GalleryWidget extends Widget<{ items: GalleryItem[] }> {
+  set(items: GalleryItem[]): void; // replace the whole grid
+  add(item: GalleryItem): void; // append one image
+}
+
+// A grid of images (the canonical output for batched image generation). Not a layout container — its
+// `items` are image records, not child widget keys.
+export function gallery(): GalleryWidget {
+  return {
+    type: "gallery",
+    state: { items: [] },
+    ...controls,
+    set(items: GalleryItem[]): void {
+      bound(this).edit(this, "set", ["items"], items);
+    },
+    add(item: GalleryItem): void {
+      bound(this).edit(this, "append", ["items"], item);
+    },
+  };
+}

package/src/lib/widgets/highlighted-text.ts

@@ -0,0 +1,29 @@
+import { bound } from "../bound.js";
+import { controls } from "../controls.js";
+import type { Widget } from "../types.js";
+
+export interface HighlightSpan {
+  text: string;
+  label?: string | null; // null/omitted => plain, unhighlighted run of text
+}
+
+export interface HighlightedTextWidget
+  extends Widget<{ value: HighlightSpan[]; colorMap: Record<string, string> }> {
+  // The canonical output for token classification / NER / diff: a sequence of text runs, each
+  // optionally tagged with a label that colors it. `colorMap` pins a color per label; unmapped
+  // labels get a stable auto color in the view.
+  set(value: HighlightSpan[], colorMap?: Record<string, string>): void;
+}
+
+export function highlightedText(): HighlightedTextWidget {
+  return {
+    type: "highlightedText",
+    state: { value: [], colorMap: {} },
+    ...controls,
+    set(value: HighlightSpan[], colorMap?: Record<string, string>): void {
+      const b = bound(this);
+      if (colorMap !== undefined) b.edit(this, "set", ["colorMap"], colorMap);
+      b.edit(this, "set", ["value"], value);
+    },
+  };
+}

package/src/lib/widgets/html.ts

@@ -0,0 +1,18 @@
+import { bound } from "../bound.js";
+import { controls } from "../controls.js";
+import type { Widget } from "../types.js";
+
+export interface HtmlWidget extends Widget<{ value: string }> {
+  set(value: string): void; // replace the rendered HTML (the escape hatch for custom markup)
+}
+
+export function html(opts: { value?: string } = {}): HtmlWidget {
+  return {
+    type: "html",
+    state: { value: opts.value ?? "" },
+    ...controls,
+    set(value: string): void {
+      bound(this).edit(this, "set", ["value"], value);
+    },
+  };
+}

package/src/lib/widgets/image.ts

@@ -0,0 +1,18 @@
+import { bound } from "../bound.js";
+import { controls } from "../controls.js";
+import type { Widget } from "../types.js";
+
+export interface ImageWidget extends Widget<{ src: string }> {
+  set(value: string): void; // set the displayed image (URL or data URL)
+}
+
+export function image(): ImageWidget {
+  return {
+    type: "image",
+    state: { src: "" },
+    ...controls,
+    set(value: string): void {
+      bound(this).edit(this, "set", ["src"], value);
+    },
+  };
+}

package/src/lib/widgets/index.ts

@@ -0,0 +1,31 @@
+export * from "./text.js";
+export * from "./number.js";
+export * from "./slider.js";
+export * from "./code.js";
+export * from "./table.js";
+export * from "./chart.js";
+export * from "./dropdown.js";
+export * from "./checkbox.js";
+export * from "./checkbox-group.js";
+export * from "./radio.js";
+export * from "./gallery.js";
+export * from "./video.js";
+export * from "./label.js";
+export * from "./highlighted-text.js";
+export * from "./annotated-image.js";
+export * from "./file.js";
+export * from "./progress.js";
+export * from "./html.js";
+export * from "./frame.js";
+export * from "./upload.js";
+export * from "./image.js";
+export * from "./button.js";
+export * from "./mic.js";
+export * from "./chat.js";
+export * from "./output.js";
+export * from "./json.js";
+export * from "./log.js";
+export * from "./audio.js";
+export * from "./webcam.js";
+export * from "./layout.js";
+export { embed } from "./embed.js";

package/src/lib/widgets/json.ts

@@ -0,0 +1,18 @@
+import { bound } from "../bound.js";
+import { controls } from "../controls.js";
+import type { Widget } from "../types.js";
+
+export interface JsonWidget extends Widget<{ value: unknown }> {
+  set(value: unknown): void; // replace the displayed value
+}
+
+export function json(): JsonWidget {
+  return {
+    type: "json",
+    state: { value: null },
+    ...controls,
+    set(value: unknown): void {
+      bound(this).edit(this, "set", ["value"], value);
+    },
+  };
+}

package/src/lib/widgets/label.ts

@@ -0,0 +1,29 @@
+import { bound } from "../bound.js";
+import { controls } from "../controls.js";
+import type { Widget } from "../types.js";
+
+export interface LabelClass {
+  label: string;
+  score: number; // 0..1
+}
+
+export interface LabelWidget extends Widget<{ label: string; confidences: LabelClass[] }> {
+  // The classifier result: either a bare label, or a label with per-class confidences (rendered as
+  // bars). When only confidences are given, the top-scoring class becomes the headline label.
+  set(value: string | { label?: string; confidences?: LabelClass[] }): void;
+}
+
+export function label(): LabelWidget {
+  return {
+    type: "label",
+    state: { label: "", confidences: [] },
+    ...controls,
+    set(value: string | { label?: string; confidences?: LabelClass[] }): void {
+      const v = typeof value === "string" ? { label: value, confidences: [] as LabelClass[] } : value;
+      const b = bound(this);
+      if (v.confidences !== undefined) b.edit(this, "set", ["confidences"], v.confidences);
+      const top = v.label ?? v.confidences?.reduce((a, c) => (c.score > a.score ? c : a), v.confidences[0])?.label;
+      if (top !== undefined) b.edit(this, "set", ["label"], top);
+    },
+  };
+}

package/src/lib/widgets/layout.ts

@@ -0,0 +1,47 @@
+import { bound } from "../bound.js";
+import { controls } from "../controls.js";
+import type { Widget } from "../types.js";
+
+export interface LayoutWidget extends Widget<{ items: string[] }> {
+  children: Widget<any>[];
+  add(child: Widget<any>): void;
+  remove(child: Widget<any>): Promise<void>;
+}
+
+function container(type: string, children: Widget<any>[], props: Record<string, unknown> = {}): LayoutWidget {
+  return {
+    type,
+    state: { items: [] },
+    children,
+    ...controls,
+    add(child: Widget<any>): void {
+      const b = bound(this);
+      b.edit(this, "append", ["items"], b.key(child));
+    },
+    async remove(child: Widget<any>): Promise<void> {
+      const b = bound(this);
+      const key = b.key(child);
+      const items = await b.read<string[]>(this, ["items"]);
+      b.edit(this, "set", ["items"], items.filter((k) => k !== key));
+    },
+    ...props,
+  };
+}
+
+export const row = (...children: Widget<any>[]): LayoutWidget => container("row", children);
+export const col = (...children: Widget<any>[]): LayoutWidget => container("col", children);
+export const grid = (children: Widget<any>[], opts: { cols?: number } = {}): LayoutWidget =>
+  container("grid", children, { cols: opts.cols ?? 2 });
+
+// Tabbed container: each panel is a labelled child. `labels` rides alongside `items` (the child keys)
+// in the same order; the active tab is view-local state, so switching tabs never round-trips.
+export const tabs = (panels: { label: string; content: Widget<any> }[]): LayoutWidget =>
+  container(
+    "tabs",
+    panels.map((p) => p.content),
+    { labels: panels.map((p) => p.label) },
+  );
+
+// A single collapsible section. `open` is the initial state; toggling it is view-local.
+export const accordion = (opts: { label: string; open?: boolean }, ...children: Widget<any>[]): LayoutWidget =>
+  container("accordion", children, { label: opts.label, open: opts.open ?? true });

package/src/lib/widgets/log.ts

@@ -0,0 +1,22 @@
+import { bound } from "../bound.js";
+import { controls } from "../controls.js";
+import type { Widget } from "../types.js";
+
+export interface LogWidget extends Widget<{ lines: string[] }> {
+  push(line: string): void;
+  all(): Promise<string[]>;
+}
+
+export function log(): LogWidget {
+  return {
+    type: "log",
+    state: { lines: [] },
+    ...controls,
+    push(line: string): void {
+      bound(this).edit(this, "append", ["lines"], line);
+    },
+    all(): Promise<string[]> {
+      return bound(this).read<string[]>(this, ["lines"]);
+    },
+  };
+}

package/src/lib/widgets/mic.ts

@@ -0,0 +1,42 @@
+import { event } from "../event.js";
+import { bound } from "../bound.js";
+import { controls } from "../controls.js";
+import type { EventCtor, Widget } from "../types.js";
+
+export interface MicWidget extends Widget<{ live: boolean }> {
+  clip: EventCtor<Float32Array>;
+  toggled: EventCtor<boolean>;
+  every: number;
+  control: boolean;
+  hold: boolean;
+  start(): void;
+  stop(): void;
+  toggle(): Promise<void>;
+  live(): Promise<boolean>;
+}
+
+export function mic(opts: { every?: number; control?: boolean; hold?: boolean } = {}): MicWidget {
+  return {
+    type: "mic",
+    state: { live: false },
+    clip: event<Float32Array>("mic.clip"),
+    toggled: event<boolean>("mic.toggled"),
+    every: opts.every ?? 0,
+    control: opts.control ?? true,
+    hold: opts.hold ?? true,
+    ...controls,
+    start(): void {
+      bound(this).edit(this, "set", ["live"], true);
+    },
+    stop(): void {
+      bound(this).edit(this, "set", ["live"], false);
+    },
+    async toggle(): Promise<void> {
+      const live = await bound(this).read<boolean>(this, ["live"]);
+      bound(this).edit(this, "set", ["live"], !live);
+    },
+    live(): Promise<boolean> {
+      return bound(this).read<boolean>(this, ["live"]);
+    },
+  };
+}

package/src/lib/widgets/number.ts

@@ -0,0 +1,5 @@
+import { value } from "./value.js";
+
+export function number(opts: { value?: number; min?: number; max?: number } = {}) {
+  return value("number", opts.value ?? 0, { min: opts.min, max: opts.max });
+}

package/src/lib/widgets/output.ts

@@ -0,0 +1,20 @@
+import { bound } from "../bound.js";
+import { controls } from "../controls.js";
+import type { Widget } from "../types.js";
+
+export interface OutputWidget extends Widget<{ value: string }> {
+  format: "text" | "markdown"; // how the view renders `value`; "text" is plain, "markdown" renders GFM
+  set(value: string): void; // replace the displayed text
+}
+
+export function output(opts: { format?: "text" | "markdown" } = {}): OutputWidget {
+  return {
+    type: "output",
+    state: { value: "" },
+    format: opts.format ?? "text",
+    ...controls,
+    set(value: string): void {
+      bound(this).edit(this, "set", ["value"], value);
+    },
+  };
+}

package/src/lib/widgets/progress.ts

@@ -0,0 +1,21 @@
+import { bound } from "../bound.js";
+import { controls } from "../controls.js";
+import type { Widget } from "../types.js";
+
+export interface ProgressWidget extends Widget<{ value: number; label: string }> {
+  // Drive a determinate bar: `value` is a 0..1 fraction, with an optional caption.
+  set(value: number, label?: string): void;
+}
+
+export function progress(opts: { label?: string } = {}): ProgressWidget {
+  return {
+    type: "progress",
+    state: { value: 0, label: opts.label ?? "" },
+    ...controls,
+    set(value: number, label?: string): void {
+      const b = bound(this);
+      b.edit(this, "set", ["value"], value);
+      if (label !== undefined) b.edit(this, "set", ["label"], label);
+    },
+  };
+}

package/src/lib/widgets/radio.ts

@@ -0,0 +1,6 @@
+import { value } from "./value.js";
+
+// Single-select from a fixed set, like dropdown but rendered as radios.
+export function radio(opts: { choices: string[]; value?: string }) {
+  return value("radio", opts.value ?? opts.choices[0]!, { choices: opts.choices });
+}

package/src/lib/widgets/slider.ts

@@ -0,0 +1,7 @@
+import { value } from "./value.js";
+
+export function slider(opts: { value?: number; min?: number; max?: number; step?: number } = {}) {
+  const min = opts.min ?? 0;
+  const max = opts.max ?? 100;
+  return value("slider", opts.value ?? min, { min, max, step: opts.step ?? 1 });
+}

package/src/lib/widgets/table.ts

@@ -0,0 +1,58 @@
+import { event } from "../event.js";
+import { bound } from "../bound.js";
+import { controls } from "../controls.js";
+import type { EventCtor, Widget } from "../types.js";
+
+export interface Column {
+  key: string; // maps a column to the per-row object key (RevoGrid `prop`)
+  label?: string; // header text; defaults to `key`
+  type?: "text" | "number"; // cell editor/parsing hint
+  width?: number;
+}
+export type Row = Record<string, unknown>;
+
+export interface TableWidget extends Widget<{ columns: Column[]; rows: Row[] }> {
+  edited: EventCtor<{ row: number; key: string; value: unknown }>; // a cell (or pasted cell) changed
+  editable: boolean;
+  maxHeight: number; // height ceiling in px; the grid fits its rows up to this, then scrolls
+  data(): Promise<Row[]>; // read all rows
+  columnsOf(): Promise<Column[]>; // read the column defs
+  setRows(rows: Row[]): void; // replace all rows
+  setColumns(columns: Column[]): void; // replace the column defs
+  addRow(row: Row): void; // append one row
+  setCell(row: number, key: string, value: unknown): void; // set one cell by row index + column key
+}
+
+// A tabular widget rendered by RevoGrid (virtualized, range-select, copy/paste, in-cell editing). State
+// is the uniform shape — `{ columns, rows }` — and every mutation is a structured edit by path, so a
+// cell edit is `set ["rows", r, key]` and a new row is `append ["rows"]`; the grid stays controlled by
+// the store on both tiers. Defaults to read-only (a display table); pass `editable: true` to let the
+// user edit cells.
+export function table(opts: { columns?: Column[]; rows?: Row[]; editable?: boolean; maxHeight?: number } = {}): TableWidget {
+  return {
+    type: "table",
+    state: { columns: opts.columns ?? [], rows: opts.rows ?? [] },
+    edited: event<{ row: number; key: string; value: unknown }>("table.edited"),
+    editable: opts.editable ?? false,
+    maxHeight: opts.maxHeight ?? 500,
+    ...controls,
+    data(): Promise<Row[]> {
+      return bound(this).read<Row[]>(this, ["rows"]);
+    },
+    columnsOf(): Promise<Column[]> {
+      return bound(this).read<Column[]>(this, ["columns"]);
+    },
+    setRows(rows: Row[]): void {
+      bound(this).edit(this, "set", ["rows"], rows);
+    },
+    setColumns(columns: Column[]): void {
+      bound(this).edit(this, "set", ["columns"], columns);
+    },
+    addRow(row: Row): void {
+      bound(this).edit(this, "append", ["rows"], row);
+    },
+    setCell(row: number, key: string, value: unknown): void {
+      bound(this).edit(this, "set", ["rows", row, key], value);
+    },
+  };
+}

package/src/lib/widgets/text.ts

@@ -0,0 +1,5 @@
+import { value } from "./value.js";
+
+export function text(opts: { placeholder?: string; lines?: number } = {}) {
+  return value("text", "", { placeholder: opts.placeholder, lines: opts.lines ?? 1 });
+}

package/src/lib/widgets/upload.ts

@@ -0,0 +1,6 @@
+import { value } from "./value.js";
+
+// state is the chosen image as a data URL
+export function upload(opts: { accept?: string } = {}) {
+  return value<string | null>("upload", null, { accept: opts.accept ?? "image/*" });
+}

package/src/lib/widgets/value.ts

@@ -0,0 +1,28 @@
+import { event } from "../event.js";
+import { bound } from "../bound.js";
+import { controls } from "../controls.js";
+import type { EventCtor, Widget } from "../types.js";
+
+export interface ValueWidget<S> extends Widget<{ value: S }> {
+  changed: EventCtor<S>;
+  value(): Promise<S>; // read the current input value
+  set(value: S): void; // set it programmatically
+}
+
+// A self-managing value input: it holds a single `value` attribute; its view (in `client`) edits that
+// value locally as the user types and emits `changed` for handlers that care.
+export function value<S>(type: string, initial: S, props: Record<string, unknown> = {}): ValueWidget<S> {
+  return {
+    type,
+    state: { value: initial },
+    changed: event<S>(`${type}.changed`),
+    ...controls,
+    value(): Promise<S> {
+      return bound(this).read<S>(this, ["value"]);
+    },
+    set(v: S): void {
+      bound(this).edit(this, "set", ["value"], v);
+    },
+    ...props,
+  };
+}

package/src/lib/widgets/video.ts

@@ -0,0 +1,22 @@
+import { bound } from "../bound.js";
+import { controls } from "../controls.js";
+import type { Widget } from "../types.js";
+
+export interface VideoWidget extends Widget<{ src: string }> {
+  autoplay: boolean;
+  loop: boolean;
+  set(value: string): void; // set the video source (URL or data URL)
+}
+
+export function video(opts: { autoplay?: boolean; loop?: boolean } = {}): VideoWidget {
+  return {
+    type: "video",
+    state: { src: "" },
+    autoplay: opts.autoplay ?? false,
+    loop: opts.loop ?? false,
+    ...controls,
+    set(value: string): void {
+      bound(this).edit(this, "set", ["src"], value);
+    },
+  };
+}

package/src/lib/widgets/webcam.ts

@@ -0,0 +1,46 @@
+import { event } from "../event.js";
+import { bound } from "../bound.js";
+import { controls } from "../controls.js";
+import type { EventCtor, Widget } from "../types.js";
+
+export interface WebcamWidget extends Widget<{ live: boolean }> {
+  frame: EventCtor<string>;
+  toggled: EventCtor<boolean>;
+  every: number;
+  control: boolean;
+  preview: boolean;
+  facing: "user" | "environment";
+  start(): void;
+  stop(): void;
+  toggle(): Promise<void>;
+  live(): Promise<boolean>;
+}
+
+export function webcam(
+  opts: { every?: number; control?: boolean; preview?: boolean; facing?: "user" | "environment" } = {},
+): WebcamWidget {
+  return {
+    type: "webcam",
+    state: { live: false },
+    frame: event<string>("webcam.frame"),
+    toggled: event<boolean>("webcam.toggled"),
+    every: opts.every ?? 0, // 0 = preview only; >0 = a frame every N ms
+    control: opts.control ?? true,
+    preview: opts.preview ?? true,
+    facing: opts.facing ?? "user",
+    ...controls,
+    start(): void {
+      bound(this).edit(this, "set", ["live"], true);
+    },
+    stop(): void {
+      bound(this).edit(this, "set", ["live"], false);
+    },
+    async toggle(): Promise<void> {
+      const live = await bound(this).read<boolean>(this, ["live"]);
+      bound(this).edit(this, "set", ["live"], !live);
+    },
+    live(): Promise<boolean> {
+      return bound(this).read<boolean>(this, ["live"]);
+    },
+  };
+}

package/src/server/context.ts

@@ -0,0 +1,12 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { setBoundResolver, type Bound } from "../lib/bound.js";
+
+// Per-request context binding for handlers. Each socket request runs inside `run(bound, …)`, so a
+// widget method's `bound(this)` resolves to that request's snapshot reader / event sender even across
+// awaits and concurrent requests.
+const store = new AsyncLocalStorage<Bound>();
+setBoundResolver(() => store.getStore());
+
+export function run<T>(bound: Bound, fn: () => T): T {
+  return store.run(bound, fn);
+}