knobkit 0.0.1

package/dist/lib/widgets/value.d.ts

@@ -0,0 +1,9 @@
+import type { EventCtor, Widget } from "../types.js";
+export interface ValueWidget<S> extends Widget<{
+    value: S;
+}> {
+    changed: EventCtor<S>;
+    value(): Promise<S>;
+    set(value: S): void;
+}
+export declare function value<S>(type: string, initial: S, props?: Record<string, unknown>): ValueWidget<S>;

package/dist/lib/widgets/value.js

@@ -0,0 +1,20 @@
+import { event } from "../event.js";
+import { bound } from "../bound.js";
+import { controls } from "../controls.js";
+// 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(type, initial, props = {}) {
+    return {
+        type,
+        state: { value: initial },
+        changed: event(`${type}.changed`),
+        ...controls,
+        value() {
+            return bound(this).read(this, ["value"]);
+        },
+        set(v) {
+            bound(this).edit(this, "set", ["value"], v);
+        },
+        ...props,
+    };
+}

package/dist/lib/widgets/video.d.ts

@@ -0,0 +1,12 @@
+import type { Widget } from "../types.js";
+export interface VideoWidget extends Widget<{
+    src: string;
+}> {
+    autoplay: boolean;
+    loop: boolean;
+    set(value: string): void;
+}
+export declare function video(opts?: {
+    autoplay?: boolean;
+    loop?: boolean;
+}): VideoWidget;

package/dist/lib/widgets/video.js

@@ -0,0 +1,14 @@
+import { bound } from "../bound.js";
+import { controls } from "../controls.js";
+export function video(opts = {}) {
+    return {
+        type: "video",
+        state: { src: "" },
+        autoplay: opts.autoplay ?? false,
+        loop: opts.loop ?? false,
+        ...controls,
+        set(value) {
+            bound(this).edit(this, "set", ["src"], value);
+        },
+    };
+}

package/dist/lib/widgets/webcam.d.ts

@@ -0,0 +1,21 @@
+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 declare function webcam(opts?: {
+    every?: number;
+    control?: boolean;
+    preview?: boolean;
+    facing?: "user" | "environment";
+}): WebcamWidget;

package/dist/lib/widgets/webcam.js

@@ -0,0 +1,29 @@
+import { event } from "../event.js";
+import { bound } from "../bound.js";
+import { controls } from "../controls.js";
+export function webcam(opts = {}) {
+    return {
+        type: "webcam",
+        state: { live: false },
+        frame: event("webcam.frame"),
+        toggled: event("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() {
+            bound(this).edit(this, "set", ["live"], true);
+        },
+        stop() {
+            bound(this).edit(this, "set", ["live"], false);
+        },
+        async toggle() {
+            const live = await bound(this).read(this, ["live"]);
+            bound(this).edit(this, "set", ["live"], !live);
+        },
+        live() {
+            return bound(this).read(this, ["live"]);
+        },
+    };
+}

package/dist/server/context.d.ts

@@ -0,0 +1,2 @@
+import { type Bound } from "../lib/bound.js";
+export declare function run<T>(bound: Bound, fn: () => T): T;

package/dist/server/context.js

@@ -0,0 +1,10 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { setBoundResolver } 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();
+setBoundResolver(() => store.getStore());
+export function run(bound, fn) {
+    return store.run(bound, fn);
+}

package/dist/server/serve.d.ts

@@ -0,0 +1,5 @@
+import type { KnobkitServer } from "../lib/types.js";
+import type { Knobkit } from "../lib/knobkit.js";
+export declare function serve(knobkit: Knobkit, opts?: {
+    port?: number;
+}): Promise<KnobkitServer>;

package/dist/server/serve.js

@@ -0,0 +1,131 @@
+import { createServer } from "node:http";
+import { fileURLToPath } from "node:url";
+import { resolve, sep } from "node:path";
+import { readFile } from "node:fs/promises";
+import { Server } from "socket.io";
+import { declare } from "../lib/declare.js";
+import { makeBound } from "../lib/ctx.js";
+import { run } from "./context.js";
+const CLIENT_JS = fileURLToPath(new URL("../../dist/client.js", import.meta.url));
+const CLIENT_CSS = fileURLToPath(new URL("../../dist/client.css", import.meta.url));
+const ASSETS = fileURLToPath(new URL("../../dist/assets", import.meta.url));
+const isEvent = (x) => x != null && typeof x.type === "string" && "payload" in x;
+function html(decl, loading) {
+    return `<!doctype html><html lang="en"><head><meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${decl.title ?? "knobkit"}</title><link rel="stylesheet" href="/client.css" /></head>
+<body><div id="root">${loading}</div><script type="module" src="/client.js"></script></body></html>`;
+}
+// node-only. The browser owns state and renders; the server is stateless. It serves the decl + client
+// bundle, then for each `request` (just `{type, payload}` — no state shipped) resolves the event's
+// `on(...)` handlers. Their context reads state by pulling one attribute from the client on demand
+// (`read` ack), applies state with `edit`/`enable`, and re-emits produced events with `emit`.
+export async function serve(knobkit, opts) {
+    const decl = declare(knobkit.config, knobkit.serverEvents());
+    let js = "";
+    let css = "";
+    try {
+        [js, css] = await Promise.all([readFile(CLIENT_JS, "utf8"), readFile(CLIENT_CSS, "utf8")]);
+    }
+    catch {
+        js = `document.getElementById("root").textContent="knobkit: build the browser client (pnpm -F knobkit build:client).";`;
+    }
+    const server = createServer(async (req, res) => {
+        if (req.url === "/api/decl") {
+            res.setHeader("content-type", "application/json");
+            res.end(JSON.stringify(decl));
+        }
+        else if (req.url === "/client.js") {
+            res.setHeader("content-type", "text/javascript; charset=utf-8");
+            res.end(js);
+        }
+        else if (req.url === "/client.css") {
+            res.setHeader("content-type", "text/css; charset=utf-8");
+            res.end(css);
+        }
+        else if (req.url?.startsWith("/assets/") && req.url.endsWith(".js")) {
+            // code-split chunks (e.g. lazy-loaded CodeMirror grammars). Resolve under dist/assets and
+            // confirm the result stays inside it before serving — never trust the request path.
+            const file = resolve(ASSETS, req.url.slice("/assets/".length).split("?")[0]);
+            if (!file.startsWith(ASSETS + sep)) {
+                res.writeHead(403, { "content-type": "text/plain" });
+                res.end("Forbidden");
+                return;
+            }
+            try {
+                const body = await readFile(file);
+                res.setHeader("content-type", "text/javascript; charset=utf-8");
+                res.setHeader("cache-control", "public, max-age=31536000, immutable"); // hashed name
+                res.end(body);
+            }
+            catch {
+                res.writeHead(404, { "content-type": "text/plain" });
+                res.end("Not found");
+            }
+        }
+        else if (req.url === "/" || req.url === "/index.html") {
+            res.setHeader("content-type", "text/html; charset=utf-8");
+            res.end(html(decl, knobkit.config.loading ?? ""));
+        }
+        else {
+            res.writeHead(404, { "content-type": "text/plain" });
+            res.end("Not found");
+        }
+    });
+    // A `read` ack can carry a large attribute (e.g. an uploaded image data URL), so lift socket.io's
+    // 1MB default clear of legitimate reads.
+    const io = new Server(server, { path: "/socket.io/", maxHttpBufferSize: 1e8 });
+    io.on("connection", (socket) => {
+        const bound = makeBound({
+            read: (key, path) => socket.timeout(15000).emitWithAck("read", { key, path }),
+            edit: (key, op, path, value) => void socket.emit("edit", { key, op, path, value }),
+            enable: (key, value) => void socket.emit("enable", { key, value }),
+            busy: (key, value) => void socket.emit("busy", { key, value }),
+            keyFor: (w) => knobkit.keyFor(w),
+        });
+        void (async () => {
+            for (const fn of knobkit.setups) {
+                try {
+                    await run(bound, fn);
+                }
+                catch (err) {
+                    console.error(err);
+                }
+            }
+        })();
+        socket.on("request", async (msg) => {
+            const { type } = msg ?? {};
+            if (typeof type !== "string")
+                return;
+            let { payload } = msg;
+            // socket.io delivers a typed-array payload (mic PCM samples) as a Buffer; restore the
+            // Float32Array the handler expects.
+            if (Buffer.isBuffer(payload)) {
+                const bytes = Uint8Array.from(payload);
+                payload = new Float32Array(bytes.buffer, 0, Math.floor(bytes.byteLength / 4));
+            }
+            try {
+                await run(bound, async () => {
+                    for (const handler of knobkit.handlers.get(type) ?? []) {
+                        const r = await handler(payload);
+                        if (isEvent(r))
+                            socket.emit("emit", r);
+                    }
+                });
+            }
+            catch (err) {
+                console.error(err);
+            }
+        });
+    });
+    const port = opts?.port ?? 3000;
+    await new Promise((r) => server.listen(port, r));
+    const addr = server.address();
+    const boundPort = addr && typeof addr === "object" && addr ? addr.port : port;
+    const url = `http://localhost:${boundPort}/`;
+    console.log(`\n  knobkit  →  ${url}\n`);
+    return {
+        url,
+        stop: () => new Promise((r) => io.close(() => r())),
+    };
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "knobkit",
+  "version": "0.0.1",
+  "description": "Rapid web app development — describe inputs and a function, get a web app.",
+  "license": "MIT",
+  "author": "Alain Brown",
+  "type": "module",
+  "types": "./dist/lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/lib/index.d.ts",
+      "default": "./dist/lib/index.js"
+    },
+    "./browser": {
+      "types": "./dist/lib/index.d.ts",
+      "default": "./dist/knobkit.browser.js"
+    },
+    "./browser.css": "./dist/knobkit.browser.css",
+    "./tsconfig.base.json": "./tsconfig.base.json",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "knobkit": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "tsconfig.base.json"
+  ],
+  "dependencies": {
+    "@codemirror/commands": "^6.10.3",
+    "@codemirror/lang-cpp": "^6.0.3",
+    "@codemirror/lang-css": "^6.3.1",
+    "@codemirror/lang-html": "^6.4.11",
+    "@codemirror/lang-javascript": "^6.2.5",
+    "@codemirror/lang-json": "^6.0.2",
+    "@codemirror/lang-markdown": "^6.5.0",
+    "@codemirror/lang-python": "^6.2.1",
+    "@codemirror/lang-rust": "^6.0.2",
+    "@codemirror/lang-sql": "^6.10.0",
+    "@codemirror/lang-xml": "^6.1.0",
+    "@codemirror/language": "^6.12.3",
+    "@codemirror/state": "^6.6.0",
+    "@codemirror/view": "^6.43.0",
+    "@revolist/react-datagrid": "^4.23.13",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "react-markdown": "^10.1.0",
+    "recharts": "^3.8.1",
+    "remark-gfm": "^4.0.1",
+    "socket.io": "^4.8.3",
+    "socket.io-client": "^4.8.3",
+    "tsx": "^4.19.0",
+    "vite": "^8.0.16"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.2.16",
+    "@types/react-dom": "^19.2.3",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  },
+  "scripts": {
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "pnpm run clean && pnpm run build:lib && pnpm run build:client && pnpm run typecheck",
+    "build:lib": "tsc -p tsconfig.build.json",
+    "build:client": "vite build && vite build --config vite.browser.config.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/cli/config.ts

@@ -0,0 +1,83 @@
+import { existsSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, relative, resolve } from "node:path";
+import { searchForWorkspaceRoot, type InlineConfig, type Plugin } from "vite";
+
+export function ensureTsconfig(root: string): void {
+  const path = resolve(root, "tsconfig.json");
+  if (existsSync(path)) return;
+  const body = { extends: "knobkit/tsconfig.base.json", include: ["**/*.ts", "**/*.tsx"] };
+  writeFileSync(path, JSON.stringify(body, null, 2) + "\n");
+  console.log("knobkit: created tsconfig.json");
+}
+
+export function knobkitSource(root: string): string | null {
+  try {
+    const require = createRequire(resolve(root, "_.js"));
+    const src = resolve(dirname(require.resolve("knobkit/package.json")), "src/lib/index.ts");
+    return existsSync(src) ? src : null;
+  } catch {
+    return null;
+  }
+}
+
+const tsSource: Plugin = {
+  name: "knobkit:ts-source",
+  enforce: "pre",
+  resolveId(source, importer) {
+    if (!importer || !source.startsWith(".") || !source.endsWith(".js")) return null;
+    const base = resolve(dirname(importer), source);
+    for (const cand of [base.replace(/\.js$/, ".tsx"), base.replace(/\.js$/, ".ts")]) {
+      if (existsSync(cand)) return cand;
+    }
+    return null;
+  },
+};
+
+export function indexHtml(entry: string): string {
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>knobkit</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/${entry}"></script>
+  </body>
+</html>
+`;
+}
+
+function virtualIndex(entry: string): Plugin {
+  return {
+    name: "knobkit:index",
+    configureServer(server) {
+      server.middlewares.use(async (req, res, next) => {
+        const url = req.url?.split("?")[0];
+        if (url !== "/" && url !== "/index.html") return next();
+        res.statusCode = 200;
+        res.setHeader("content-type", "text/html");
+        res.end(await server.transformIndexHtml(req.originalUrl ?? "/", indexHtml(entry)));
+      });
+    },
+  };
+}
+
+export function mountConfig(root: string, entry: string, ownHtml: boolean): InlineConfig {
+  const src = knobkitSource(root);
+  const entryRel = relative(root, entry);
+  return {
+    configFile: false,
+    root,
+    plugins: [tsSource, ...(ownHtml ? [] : [virtualIndex(entryRel)])],
+    esbuild: { jsx: "automatic" },
+    resolve: {
+      dedupe: ["react", "react-dom"],
+      ...(src ? { alias: [{ find: /^knobkit$/, replacement: src }] } : {}),
+    },
+    ...(ownHtml ? {} : { optimizeDeps: { entries: [entryRel] } }),
+    server: { fs: { allow: [searchForWorkspaceRoot(root)] } },
+  };
+}

package/src/cli/index.ts

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { ensureTsconfig } from "./config.js";
+import { buildMount, devMount } from "./mount.js";
+import { runServe } from "./serve.js";
+
+const HELP = `knobkit — build a web app from widgets and event handlers
+
+Usage:
+  knobkit dev [file]     Start a dev server (auto-detects mount vs serve)
+  knobkit build [file]   Build a browser (mount) app to dist/
+  knobkit serve [file]   Run a server (serve) app    (same as: knobkit dev --serve)
+
+  file defaults to demo.tsx
+
+Flags:
+  --mount      Force browser (mount) mode
+  --serve      Force server (serve) mode
+  --port <n>   Dev server port (mount)
+`;
+
+interface Args {
+  file: string;
+  mount: boolean;
+  serve: boolean;
+  port?: number;
+}
+
+function parse(argv: string[]): Args {
+  const out: Args = { file: "demo.tsx", mount: false, serve: false };
+  let sawFile = false;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--mount") out.mount = true;
+    else if (a === "--serve") out.serve = true;
+    else if (a === "--port") out.port = Number(argv[++i]);
+    else if (a.startsWith("--port=")) out.port = Number(a.slice("--port=".length));
+    else if (!a.startsWith("-") && !sawFile) {
+      out.file = a;
+      sawFile = true;
+    }
+  }
+  return out;
+}
+
+function mode(file: string, args: Args): "mount" | "serve" {
+  if (args.serve) return "serve";
+  if (args.mount) return "mount";
+  return /\.serve\s*\(/.test(readFileSync(file, "utf8")) ? "serve" : "mount";
+}
+
+async function main(): Promise<void> {
+  const [cmd, ...rest] = process.argv.slice(2);
+  if (!cmd || cmd === "help" || cmd === "-h" || cmd === "--help") {
+    process.stdout.write(HELP);
+    return;
+  }
+  if (cmd !== "dev" && cmd !== "build" && cmd !== "serve") {
+    process.stderr.write(`knobkit: unknown command "${cmd}"\n\n${HELP}`);
+    process.exit(1);
+  }
+
+  const args = parse(rest);
+  const root = process.cwd();
+  const file = resolve(root, args.file);
+  if (!existsSync(file)) {
+    process.stderr.write(`knobkit: no such file: ${args.file}\n`);
+    process.exit(1);
+  }
+  ensureTsconfig(root);
+
+  if (cmd === "build") return buildMount(root, file);
+  if (cmd === "serve") return runServe(file);
+  if (mode(file, args) === "serve") return runServe(file);
+  return devMount(root, file, args.port);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/src/cli/mount.ts

@@ -0,0 +1,25 @@
+import { existsSync, rmSync, writeFileSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import { build as viteBuild, createServer } from "vite";
+import { indexHtml, mountConfig } from "./config.js";
+
+export async function devMount(root: string, entry: string, port?: number): Promise<void> {
+  const ownHtml = existsSync(resolve(root, "index.html"));
+  const server = await createServer({ ...mountConfig(root, entry, ownHtml), server: { port } });
+  await server.listen();
+  server.printUrls();
+}
+
+export async function buildMount(root: string, entry: string): Promise<void> {
+  const htmlPath = resolve(root, "index.html");
+  const created = !existsSync(htmlPath);
+  if (created) writeFileSync(htmlPath, indexHtml(relative(root, entry)));
+  try {
+    await viteBuild({
+      ...mountConfig(root, entry, true),
+      build: { outDir: "dist", emptyOutDir: true },
+    });
+  } finally {
+    if (created) rmSync(htmlPath, { force: true });
+  }
+}

package/src/cli/serve.ts

@@ -0,0 +1,22 @@
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, resolve } from "node:path";
+
+function tsxBin(): string {
+  const require = createRequire(import.meta.url);
+  const pkgPath = require.resolve("tsx/package.json");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as { bin: string | Record<string, string> };
+  const bin = typeof pkg.bin === "string" ? pkg.bin : pkg.bin.tsx;
+  return resolve(dirname(pkgPath), bin);
+}
+
+export function runServe(file: string): Promise<void> {
+  const child = spawn(process.execPath, [tsxBin(), "watch", file], { stdio: "inherit" });
+  return new Promise((res) => {
+    child.on("exit", (code) => {
+      if (code) process.exitCode = code;
+      res();
+    });
+  });
+}

package/src/client/app.test.tsx

@@ -0,0 +1,70 @@
+// @vitest-environment jsdom
+import { test, expect } from "vitest";
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { knobkit } from "../lib/knobkit.js";
+import { declare } from "../lib/declare.js";
+import { mic, log, chat, text, button, output, row, col } from "../lib/widgets/index.js";
+import { App } from "./app.js";
+import { createStore } from "./runtime.js";
+
+test("App renders a live-like app (mic + log + chat) and reacts to edits", async () => {
+  const audio = mic();
+  const transcript = log();
+  const convo = chat();
+  const app = knobkit({ title: "Live", widgets: [audio, transcript, convo] });
+  const decl = declare(app.config, app.serverEvents());
+  const store = createStore(decl, () => {});
+
+  document.body.innerHTML = '<div id="root"></div>';
+  const root = createRoot(document.getElementById("root")!);
+
+  await act(async () => {
+    root.render(<App decl={decl} store={store} />);
+  });
+  expect(document.body.textContent).toContain("Live");
+  expect(document.querySelectorAll("button").length).toBeGreaterThan(0); // mic control
+  expect(document.querySelector("input")).not.toBeNull(); // chat composer
+
+  await act(async () => {
+    store.applyEdit(app.keyFor(transcript), "append", ["lines"], "hello");
+    store.applyEdit(app.keyFor(transcript), "append", ["lines"], "world");
+  });
+  expect(document.querySelector("pre")!.textContent).toMatch(/hello\s+world/);
+});
+
+test("nested layout renders: a row inside a col, children placed via slots", async () => {
+  const field = text();
+  const go = button({ label: "Go" });
+  const result = output();
+  const app = knobkit({ widgets: col(row(field, go), result) });
+  const decl = declare(app.config, app.serverEvents());
+  const store = createStore(decl, () => {});
+
+  document.body.innerHTML = '<div id="root"></div>';
+  const root = createRoot(document.getElementById("root")!);
+  await act(async () => {
+    root.render(<App decl={decl} store={store} />);
+  });
+
+  const rowEl = document.querySelector(".pu-layout-row");
+  expect(rowEl).not.toBeNull();
+  expect(rowEl!.querySelector("input")).not.toBeNull();
+  expect(rowEl!.querySelector("button")!.textContent).toContain("Go");
+  expect(document.querySelector(".pu-layout-col")).not.toBeNull();
+  expect(rowEl!.querySelector(".pu-output")).toBeNull();
+});
+
+test("mic({ control: false }) renders headless — no built-in button", async () => {
+  const audio = mic({ control: false });
+  const app = knobkit({ widgets: [audio] });
+  const decl = declare(app.config, app.serverEvents());
+  const store = createStore(decl, () => {});
+
+  document.body.innerHTML = '<div id="root"></div>';
+  const root = createRoot(document.getElementById("root")!);
+  await act(async () => {
+    root.render(<App decl={decl} store={store} />);
+  });
+  expect(document.querySelectorAll("button").length).toBe(0);
+});