knobkit 0.0.1 → 0.0.3

package/README.md

@@ -0,0 +1,153 @@
+# <img src="https://raw.githubusercontent.com/knobkit/knobkit/main/design/logo.svg" height="28" alt="" /> knobkit
+
+[![npm version](https://img.shields.io/npm/v/knobkit.svg)](https://www.npmjs.com/package/knobkit) [![license](https://img.shields.io/npm/l/knobkit.svg)](https://github.com/knobkit/knobkit/blob/main/LICENSE)
+
+**Your AI app, live as you type.** Declare widgets, write event handlers — done. The same file runs
+entirely in the browser — no server at all — or with handlers on a stateless Node server. Swap one line.
+
+```ts
+import { knobkit, chat } from "knobkit";
+
+const convo = chat({ placeholder: "Say something…" });
+
+const app = knobkit({
+  title: "Echo bot",
+  description: "Whatever you send comes back reversed.",
+  widgets: [convo],
+});
+
+app.on(convo.sent, async ({ text }) => {
+  convo.say({ role: "user", content: text });
+  convo.say({ role: "assistant", content: [...text].reverse().join("") });
+});
+
+app.serve();
+```
+
+That's a complete app. `app.serve()` runs the handler on Node; change that one line to
+`app.mount("#root")` and the identical file runs fully client-side. For a real model-backed chatbot
+(streaming, history), see [`examples/`](https://github.com/knobkit/knobkit/tree/main/examples).
+
+## Why not Gradio or Streamlit?
+
+Same authoring feel — declare inputs, write a function, get an app — different architecture:
+
+- **The browser owns all state.** A knobkit server keeps nothing. A handler pulls only the
+  attributes it actually reads and writes back structured edits. No sessions, no sticky state —
+  restart, redeploy, or scale the server and no one's app breaks.
+- **One file, two tiers.** Prototype entirely in the browser (`mount` apps build to static files —
+  host them anywhere, run WebGPU models client-side), then move handlers to a server when you need
+  secrets, large models, or native deps — by changing the last line.
+- **Events, not reruns.** Handlers are plain `on(event, async fn)` functions. No full-script
+  re-execution on every interaction, no reactive graph to fight, no widget-key gymnastics.
+- **Data stays where it lives.** A request crossing the wire is just `{ type, payload }` — never a
+  copy of state. An attribute a handler never reads (say, generated audio) never leaves the browser.
+
+## Quick start
+
+```bash
+npm create knobkit@latest my-app   # choose mount (browser) or serve (node)
+cd my-app
+npm install
+npm run dev
+```
+
+Skip the prompts with `npm create knobkit@latest my-app -- --mount` (or `--serve`). Already have a
+project? `npm install knobkit`. Requires Node ≥ 22.
+
+## CLI
+
+The `knobkit` package installs a `knobkit` command:
+
+```bash
+knobkit dev      # dev server — auto-detects mount vs serve
+knobkit build    # build a browser (mount) app to dist/
+knobkit serve    # run a server (serve) app
+```
+
+The entry file is the `"main"` field of your package.json — like `vite`, the manifest names the
+entry. Pass a file to run something else: `knobkit dev other.tsx`. Flags: `--mount` / `--serve`
+force a mode, `--port <n>` sets the dev-server port. Otherwise `knobkit dev` detects the tier from
+whether your entry file ends in `mount()` or `serve()`.
+
+## Concepts
+
+- **Widgets** hold structured state and render themselves. Handlers interact through widget methods:
+  - **read** with async getters — `await convo.history()`, `await box.value()` — pulled from the browser.
+  - **write** with structured edits — `convo.say(m)`, `convo.append(token)`, `out.set(v)`, `log.push(line)`.
+  - **produce** by `return`ing an event from a handler (it's re-emitted, like a user action).
+- **Events** are plain serializable `{ type, payload }`. `widget.sent("hi")` builds one.
+- **`on(event, handler)`** registers a handler against a widget's event (`convo.sent`, `go.clicked`).
+- **`setup(fn)`** runs once per session — in the browser on `mount`, per connection on `serve` — with a
+  live context, so async startup (load model weights, fetch a user's data) happens here. The page
+  renders first; setup is non-blocking.
+- **`busy`** marks a transient working span on a widget — `widget.busy(handler)` wraps an async handler,
+  or `widget.busyStart()`/`busyEnd()` bracket one by hand (e.g. a `setup()` load). The widget shows a
+  thin indeterminate bar and drops its input events while busy. `disable()`/`enable()` is the persistent
+  version (dimmed).
+- **`mount` vs `serve`** is the only thing that changes between in-browser and client/server — the
+  widgets, handlers, and methods are identical.
+
+## The two runtimes
+
+| | `mount("#root")` | `serve()` |
+|---|---|---|
+| State | in the browser | in the browser |
+| `on(...)` handlers | run in the browser | run on a stateless Node server |
+| Transport | local function call | socket.io |
+| Use when | everything fits client-side (incl. WebGPU models) | the handler needs the server (large models, secrets, native deps) |
+
+## Widgets
+
+Inputs: `text`, `number`, `slider`, `dropdown`, `checkbox`, `checkboxGroup`, `radio`, `upload`, `mic`,
+`webcam`, `chat`, `button`.
+Outputs: `output` (plain text or `format: "markdown"`), `json`, `log`, `label`, `html`, `image`,
+`gallery`, `annotatedImage` (boxes/labels over an image), `highlightedText` (spans over text), `audio`,
+`video`, `file` (download), `progress`, `chart` (bar/line/area), `frame` (embed a URL or a sandboxed
+HTML document in an isolated iframe).
+Both (editable or read-only): `code` (syntax-highlighted editor/viewer), `table` (data grid).
+Custom: `widget({ state, … })`.
+
+## Layout
+
+`widgets` is the widget tree. An array is a vertical stack; `row`, `col`, and `grid` are containers
+that nest other widgets — composed with the widget objects themselves, no keys or strings:
+
+```ts
+import { knobkit, upload, dropdown, button, output, row, col } from "knobkit";
+
+knobkit({ widgets: col(photo, row(size, go), caption) });
+knobkit({ widgets: grid([a, b, c, d], { cols: 2 }) });
+```
+
+`tabs` and `accordion` are containers too — `tabs([{ label, content }, …])`,
+`accordion({ label, open }, …children)`. Containers are themselves widgets whose state is their
+arrangement, so a handler can restructure the UI at runtime — `panel.add(chart)`, `panel.remove(sidebar)`.
+
+## Examples
+
+In [`examples/`](https://github.com/knobkit/knobkit/tree/main/examples) — each is a single
+`demo.tsx`. Run one with `pnpm -F knobkit-example-<name> dev`.
+
+[`examples/playground`](https://github.com/knobkit/knobkit/tree/main/examples/playground) is an
+in-browser playground: a `code` editor on the right runs live as a mounted knobkit app on the left,
+with a `dropdown` of built-in examples — itself a knobkit app built from `code`/`dropdown`/layout.
+Run it with `pnpm -F knobkit-example-playground dev`.
+
+## Develop
+
+Requires Node ≥ 22 and pnpm.
+
+```bash
+pnpm install
+pnpm -F knobkit build     # build the library + browser client bundle
+pnpm -F knobkit test      # vitest
+pnpm typecheck            # all packages
+```
+
+See [CLAUDE.md](https://github.com/knobkit/knobkit/blob/main/CLAUDE.md) for the architecture and how
+to add a widget.
+
+## License
+
+[MIT](https://github.com/knobkit/knobkit/blob/main/LICENSE)

package/dist/cli/config.js

@@ -2,6 +2,7 @@ import { existsSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, relative, resolve } from "node:path";
 import { searchForWorkspaceRoot } from "vite";
+import { FAVICON_TAG } from "../lib/favicon.js";
 export function ensureTsconfig(root) {
     const path = resolve(root, "tsconfig.json");
     if (existsSync(path))
@@ -41,6 +42,7 @@ export function indexHtml(entry) {
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>knobkit</title>
+    ${FAVICON_TAG}
   </head>
   <body>
     <div id="root"></div>

package/dist/cli/index.js

@@ -7,11 +7,11 @@ 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)
+  knobkit dev      Start a dev server (auto-detects mount vs serve)
+  knobkit build    Build a browser (mount) app to dist/
+  knobkit serve    Run a server (serve) app    (same as: knobkit dev --serve)
 
-  file defaults to demo.tsx
+  The entry file is "main" in package.json; pass a file to override (knobkit dev other.tsx)
 
 Flags:
   --mount      Force browser (mount) mode
@@ -19,8 +19,7 @@ Flags:
   --port <n>   Dev server port (mount)
 `;
 function parse(argv) {
-    const out = { file: "demo.tsx", mount: false, serve: false };
-    let sawFile = false;
+    const out = { mount: false, serve: false };
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a === "--mount")
@@ -31,13 +30,35 @@ function parse(argv) {
             out.port = Number(argv[++i]);
         else if (a.startsWith("--port="))
             out.port = Number(a.slice("--port=".length));
-        else if (!a.startsWith("-") && !sawFile) {
+        else if (!a.startsWith("-") && out.file === undefined)
             out.file = a;
-            sawFile = true;
-        }
     }
     return out;
 }
+function entry(root, args) {
+    if (args.file) {
+        const file = resolve(root, args.file);
+        if (!existsSync(file)) {
+            process.stderr.write(`knobkit: no such file: ${args.file}\n`);
+            process.exit(1);
+        }
+        return file;
+    }
+    const pkgPath = resolve(root, "package.json");
+    const main = existsSync(pkgPath)
+        ? JSON.parse(readFileSync(pkgPath, "utf8")).main
+        : undefined;
+    if (!main) {
+        process.stderr.write(`knobkit: no entry file — pass one (knobkit dev app.tsx) or set "main" in package.json\n`);
+        process.exit(1);
+    }
+    const file = resolve(root, main);
+    if (!existsSync(file)) {
+        process.stderr.write(`knobkit: package.json "main" points to a missing file: ${main}\n`);
+        process.exit(1);
+    }
+    return file;
+}
 function mode(file, args) {
     if (args.serve)
         return "serve";
@@ -57,11 +78,7 @@ async function main() {
     }
     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);
-    }
+    const file = entry(root, args);
     ensureTsconfig(root);
     if (cmd === "build")
         return buildMount(root, file);

package/dist/lib/favicon.d.ts

@@ -0,0 +1 @@
+export declare const FAVICON_TAG: string;

package/dist/lib/favicon.js

@@ -0,0 +1,15 @@
+// The K-Tile logo (design/logo.svg) as a data URI, so served and mounted apps get a favicon
+// without serving an extra file.
+const SVG = [
+    "%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E",
+    "%3Crect x='4' y='4' width='56' height='56' rx='14' fill='%232563eb'/%3E",
+    "%3Cg stroke='%23fff' stroke-width='7' stroke-linecap='round'%3E",
+    "%3Cline x1='23' y1='16' x2='23' y2='48'/%3E",
+    "%3Cline x1='23' y1='33' x2='42' y2='18'/%3E",
+    "%3Cline x1='23' y1='33' x2='42' y2='46'/%3E",
+    "%3C/g%3E",
+    "%3Ccircle cx='23' cy='33' r='6.5' fill='%23fff'/%3E",
+    "%3Ccircle cx='23' cy='33' r='2.8' fill='%231d4ed8'/%3E",
+    "%3C/svg%3E",
+].join("");
+export const FAVICON_TAG = `<link rel="icon" href="data:image/svg+xml,${SVG}" />`;

package/dist/server/serve.js

@@ -5,6 +5,7 @@ import { readFile } from "node:fs/promises";
 import { Server } from "socket.io";
 import { declare } from "../lib/declare.js";
 import { makeBound } from "../lib/ctx.js";
+import { FAVICON_TAG } from "../lib/favicon.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));
@@ -13,7 +14,7 @@ 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>
+<title>${decl.title ?? "knobkit"}</title>${FAVICON_TAG}<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

package/package.json

@@ -1,9 +1,32 @@
 {
   "name": "knobkit",
-  "version": "0.0.1",
-  "description": "Rapid web app development — describe inputs and a function, get a web app.",
+  "version": "0.0.3",
+  "description": "Your AI app, live as you type — declare widgets, write event handlers, done. The same file runs in the browser or on a stateless Node server.",
+  "keywords": [
+    "widgets",
+    "ui",
+    "framework",
+    "declarative",
+    "web-app",
+    "react",
+    "events",
+    "isomorphic",
+    "rapid-prototyping"
+  ],
   "license": "MIT",
   "author": "Alain Brown",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/knobkit/knobkit.git",
+    "directory": "packages/knobkit"
+  },
+  "homepage": "https://github.com/knobkit/knobkit#readme",
+  "bugs": {
+    "url": "https://github.com/knobkit/knobkit/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
   "type": "module",
   "types": "./dist/lib/index.d.ts",
   "exports": {

package/src/cli/config.ts

@@ -2,6 +2,7 @@ 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";
+import { FAVICON_TAG } from "../lib/favicon.js";
 
 export function ensureTsconfig(root: string): void {
   const path = resolve(root, "tsconfig.json");
@@ -41,6 +42,7 @@ export function indexHtml(entry: string): string {
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>knobkit</title>
+    ${FAVICON_TAG}
   </head>
   <body>
     <div id="root"></div>

package/src/cli/index.ts

@@ -8,11 +8,11 @@ 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)
+  knobkit dev      Start a dev server (auto-detects mount vs serve)
+  knobkit build    Build a browser (mount) app to dist/
+  knobkit serve    Run a server (serve) app    (same as: knobkit dev --serve)
 
-  file defaults to demo.tsx
+  The entry file is "main" in package.json; pass a file to override (knobkit dev other.tsx)
 
 Flags:
   --mount      Force browser (mount) mode
@@ -21,29 +21,52 @@ Flags:
 `;
 
 interface Args {
-  file: string;
+  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;
+  const out: Args = { mount: false, serve: 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;
-    }
+    else if (!a.startsWith("-") && out.file === undefined) out.file = a;
   }
   return out;
 }
 
+function entry(root: string, args: Args): string {
+  if (args.file) {
+    const file = resolve(root, args.file);
+    if (!existsSync(file)) {
+      process.stderr.write(`knobkit: no such file: ${args.file}\n`);
+      process.exit(1);
+    }
+    return file;
+  }
+  const pkgPath = resolve(root, "package.json");
+  const main = existsSync(pkgPath)
+    ? (JSON.parse(readFileSync(pkgPath, "utf8")) as { main?: string }).main
+    : undefined;
+  if (!main) {
+    process.stderr.write(
+      `knobkit: no entry file — pass one (knobkit dev app.tsx) or set "main" in package.json\n`,
+    );
+    process.exit(1);
+  }
+  const file = resolve(root, main);
+  if (!existsSync(file)) {
+    process.stderr.write(`knobkit: package.json "main" points to a missing file: ${main}\n`);
+    process.exit(1);
+  }
+  return file;
+}
+
 function mode(file: string, args: Args): "mount" | "serve" {
   if (args.serve) return "serve";
   if (args.mount) return "mount";
@@ -63,11 +86,7 @@ async function main(): Promise<void> {
 
   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);
-  }
+  const file = entry(root, args);
   ensureTsconfig(root);
 
   if (cmd === "build") return buildMount(root, file);

package/src/lib/favicon.ts

@@ -0,0 +1,16 @@
+// The K-Tile logo (design/logo.svg) as a data URI, so served and mounted apps get a favicon
+// without serving an extra file.
+const SVG = [
+  "%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E",
+  "%3Crect x='4' y='4' width='56' height='56' rx='14' fill='%232563eb'/%3E",
+  "%3Cg stroke='%23fff' stroke-width='7' stroke-linecap='round'%3E",
+  "%3Cline x1='23' y1='16' x2='23' y2='48'/%3E",
+  "%3Cline x1='23' y1='33' x2='42' y2='18'/%3E",
+  "%3Cline x1='23' y1='33' x2='42' y2='46'/%3E",
+  "%3C/g%3E",
+  "%3Ccircle cx='23' cy='33' r='6.5' fill='%23fff'/%3E",
+  "%3Ccircle cx='23' cy='33' r='2.8' fill='%231d4ed8'/%3E",
+  "%3C/svg%3E",
+].join("");
+
+export const FAVICON_TAG = `<link rel="icon" href="data:image/svg+xml,${SVG}" />`;

package/src/server/serve.ts

@@ -7,6 +7,7 @@ import type { KnobkitServer, Event } from "../lib/types.js";
 import type { Knobkit } from "../lib/knobkit.js";
 import { declare, type AppDecl } from "../lib/declare.js";
 import { makeBound } from "../lib/ctx.js";
+import { FAVICON_TAG } from "../lib/favicon.js";
 import { run } from "./context.js";
 
 const CLIENT_JS = fileURLToPath(new URL("../../dist/client.js", import.meta.url));
@@ -18,7 +19,7 @@ const isEvent = (x: any): x is Event => x != null && typeof x.type === "string"
 function html(decl: AppDecl, loading: string): string {
   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>
+<title>${decl.title ?? "knobkit"}</title>${FAVICON_TAG}<link rel="stylesheet" href="/client.css" /></head>
 <body><div id="root">${loading}</div><script type="module" src="/client.js"></script></body></html>`;
 }