npm - @jseeio/jsee - Versions diffs - 0.4.2 → 0.8.1 - Mend

@jseeio/jsee 0.4.2 → 0.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (66) hide show

package/CHANGELOG.md +96 -0
package/LICENSE +21 -0
package/README.md +583 -55
package/dist/2b3e1faf89f94a483539.png +0 -0
package/dist/416d91365b44e4b4f477.png +0 -0
package/dist/8f2c4d11474275fbc161.png +0 -0
package/dist/jsee.core.js +1 -0
package/dist/jsee.full.js +1 -0
package/dist/jsee.runtime.js +2 -1
package/package.json +84 -18
package/src/app.js +127 -32
package/src/browser-bundle-node.js +9 -0
package/src/cli.js +479 -67
package/src/extended-imports.js +11 -0
package/src/main.js +232 -44
package/src/overlay.js +26 -1
package/src/utils.js +386 -16
package/templates/common-inputs.js +88 -0
package/templates/common-outputs.js +340 -4
package/templates/minimal-app.vue +367 -0
package/templates/minimal-input.vue +573 -0
package/templates/minimal-output.vue +426 -0
package/templates/virtual-table.vue +194 -0
package/.claude/settings.local.json +0 -15
package/.eslintrc.js +0 -38
package/AGENTS.md +0 -65
package/CLAUDE.md +0 -5
package/CNAME +0 -1
package/_config.yml +0 -26
package/dist/jsee.js +0 -1
package/dump.sh +0 -23
package/jest-puppeteer.config.js +0 -14
package/jest.config.js +0 -8
package/jest.unit.config.js +0 -8
package/jsee.dump.txt +0 -5459
package/load/index.html +0 -52
package/templates/bulma-app.vue +0 -242
package/templates/bulma-input.vue +0 -125
package/templates/bulma-output.vue +0 -101
package/test/arrow-main.html +0 -18
package/test/arrow-worker.html +0 -18
package/test/class.html +0 -22
package/test/code.html +0 -25
package/test/codew.html +0 -25
package/test/example-class.js +0 -8
package/test/example-sum.js +0 -3
package/test/fixtures/lodash-like.js +0 -15
package/test/fixtures/upload-sample.csv +0 -3
package/test/importw.html +0 -28
package/test/minimal.html +0 -14
package/test/minimal1.html +0 -13
package/test/minimal2.html +0 -15
package/test/minimal3.html +0 -10
package/test/minimal4.html +0 -22
package/test/pipeline.html +0 -52
package/test/python.html +0 -41
package/test/runtime-arrow.html +0 -18
package/test/string.html +0 -26
package/test/stringw.html +0 -29
package/test/sum.schema.json +0 -17
package/test/sumw.schema.json +0 -15
package/test/test-basic.test.js +0 -630
package/test/test-python.test.js +0 -23
package/test/unit/cli-fetch.test.js +0 -229
package/test/unit/utils.test.js +0 -908
package/webpack.config.js +0 -101

package/README.md CHANGED Viewed

@@ -1,45 +1,128 @@
-# JSEE. Computational Documents for the Web
+# JSEE
-Turn code into a shareable, offline-capable web app. Describe inputs/outputs once (JSON), run JS/Python in a Worker or via API, and ship as a single HTML file.
+Portable, schema-driven web apps for local computation.
+JSEE turns a model function plus a small JSON schema into a reactive browser app, CLI-served tool, offline HTML bundle and API surface. It is meant for computations that should be easy to share, inspect, rerun and keep on the user's machine.
+Use JSEE when you want:
+- a self-contained UI around a JavaScript, Python, API, or WASM computation
+- typed inputs, output rendering, file/folder handling, progress, and cancellation without writing app plumbing
+- browser-first execution with optional Worker isolation and offline bundling
+- the same computation exposed to humans through a UI and to tools through HTTP/API routes
+Smallest browser example:
-Minimal example:
 ```html
-<html>
-  <div id="jsee-container">
-  <script src="https://cdn.jsdelivr.net/npm/@jseeio/jsee@latest/dist/jsee.runtime.js"></script>
-  <script>
-    function mul (a, b) {
-      return a * b
-    }
-    new JSEE(mul, '#jsee-container')
-  </script>
-</html>
+<div id="jsee-container"></div>
+<script src="https://cdn.jsdelivr.net/npm/@jseeio/jsee@latest/dist/jsee.core.js"></script>
+<script>
+  function multiply (a, b) {
+    return a * b
+  }
+  new JSEE(multiply, '#jsee-container')
+</script>
 ```
 ↳ [Result](https://jsee.org/test/minimal1.html)
 ## Installation
-**Browser (CDN):**
+**Browser CDN:**
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@jseeio/jsee@latest/dist/jsee.runtime.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@jseeio/jsee@latest/dist/jsee.core.js"></script>
 ```
-**npm (for CLI or Node.js projects):**
+Pin a version for production, for example `@jseeio/jsee@0.8.1`.
+**npm CLI/dev server:**
 ```bash
 npm install @jseeio/jsee
 ```
-**CLI (generate standalone apps):**
+Run from npm without installing globally:
 ```bash
 npx @jseeio/jsee schema.json -o app.html
 ```
-Run `jsee --help` for all CLI options.
+Run `npx @jseeio/jsee --help` for all CLI options.
+## Runtime Bundles
+| Bundle | Use when | Includes |
+|---|---|---|
+| `dist/jsee.core.js` | Most apps, direct `<script>` tags, generated HTML | runtime, inputs, core outputs, native PDF viewer |
+| `dist/jsee.full.js` | Apps that need `chart`, `3d`, or `map` without extra imports | core + Observable Plot + Three.js + Leaflet |
+| `@jseeio/jsee` package entry | CLI/server-side tooling | Node CLI module |
+Full bundle CDN:
+```html
+<script src="https://cdn.jsdelivr.net/npm/@jseeio/jsee@latest/dist/jsee.full.js"></script>
+```
+The core bundle can still render `chart`, `3d`, and `map` if the app loads the required library through schema `imports`. The `pdf` output uses the browser's native PDF viewer and is available in the core bundle. The CLI and Python server choose the required runtime bundle from the schema output types.
+## Quick start
+Scaffold a project:
+```bash
+npx @jseeio/jsee init            # minimal: schema.json + model.js + README.md
+npx @jseeio/jsee init chat       # chat template
+npx @jseeio/jsee init --html     # single index.html with CDN script
+```
+Python:
+```bash
+jsee init                         # schema.json + model.py + README.md
+jsee init chat                    # chat template
+```
+Or create the two files yourself:
+```json
+{
+  "model": { "url": "model.js", "worker": true },
+  "inputs": [
+    { "name": "n", "type": "slider", "min": 10, "max": 1000, "default": 100 }
+  ],
+  "outputs": [
+    { "name": "summary", "type": "number", "label": "Rows" },
+    { "name": "rows", "type": "table" }
+  ]
+}
+```
+```javascript
+function model ({ n }, ctx) {
+  ctx.progress(10)
+  const rows = Array.from({ length: n }, (_, i) => ({ i, y: Math.sin(i / 10) }))
+  ctx.progress(100)
+  return { summary: n, rows }
+}
+```
+Start the dev server:
-## Inputs and outputs
+```bash
+npx @jseeio/jsee schema.json     # Node (auto server-side execution)
+jsee schema.json                  # Python
+```
+Generate a standalone HTML file:
+```bash
+npx @jseeio/jsee schema.json -o app.html
+npx @jseeio/jsee schema.json -o app.html --fetch   # inline runtime + imports for offline use
+```
+## When JSEE Fits
-JSEE works best with functional tasks and one-way flow from inputs to outputs (i.e., inputs → processing → outputs). You can also extend it to more complex scenarios, like inputs → preprocessing → updated inputs → processing → outputs or inputs → processing → outputs → custom renderer. Even though many computational tasks have a functional form, some problems require more complex interactions between a user interface and code. For such cases, JSEE is probably too constrained. That makes it not as universal as R's [shiny](https://shiny.rstudio.com/) or Python's [streamlit](https://streamlit.io/).
+JSEE works best for computations with a clear flow from inputs to processing to outputs. Pipelines, input updates, streaming files, custom renderers, and chat-style interfaces are supported, but JSEE is intentionally not a general application framework. If the UI needs deep bidirectional state, many custom screens, routing, or complex collaborative editing, use a normal frontend app and call JSEE-style computation modules from it.
 ## How it works
@@ -78,8 +161,8 @@ JSEE turns a JSON schema into a working web app. Instead of writing HTML, event
 - **Run**: user clicks Run (or autorun/reactive triggers it). Inputs are collected and sent to the model
 - **Pipeline**: when `model` is an array, models execute sequentially — each receives the merged output of the previous one. Return `{ stop: true }` to halt early
-- **Worker context**: worker models receive a runtime context (`ctx`) with `ctx.log()`, `ctx.progress(value)` (0–100 or `null` for indeterminate), and `ctx.isCancelled()` for cooperative cancellation
-- **Cancellation**: `jsee.cancelCurrentRun()` or the Stop button sets a flag that workers and stream readers check
+- **Runtime context**: object-container models receive a second argument (`ctx`) with `ctx.log()`, `ctx.progress(value)` (0–100 or `null` for indeterminate), and `ctx.isCancelled()` for cooperative cancellation
+- **Cancellation**: `jsee.cancelCurrentRun()` or the Stop button rejects the active run, signals workers, and marks stale results so they are ignored. Worker-backed models can be terminated. Main-thread models should check `ctx.isCancelled()` inside long async loops because JavaScript cannot preempt synchronous CPU-bound code on the main thread
 - **Output**: results flow to the output cards — JSON trees, HTML, SVG, code blocks, or custom render functions
 ### Offline & bundling
@@ -121,6 +204,92 @@ Extra blocks can be provided for further customization:
 - [Codepen](https://codepen.io/jseeio/pen/NWayjJe)
+## Examples
+### Full schema
+A complete schema with multiple inputs, outputs, theming, and a worker model:
+```json
+{
+  "model": { "url": "model.js", "worker": true },
+  "design": { "primary": "#2a7ae2", "grid": [4, 8] },
+  "inputs": [
+    { "name": "count", "type": "slider", "min": 10, "max": 1000, "default": 100 },
+    { "name": "method", "type": "select", "options": ["linear", "quadratic"], "default": "linear" }
+  ],
+  "outputs": [
+    { "name": "summary", "type": "number", "prefix": "n = " },
+    { "name": "data", "type": "chart", "mark": "dot", "x": "x", "y": "y" },
+    { "name": "raw", "type": "table" }
+  ],
+  "autorun": true
+}
+```
+### Chart output
+Model returns array of objects or column-oriented data:
+```javascript
+function model ({ count }) {
+  const data = Array.from({ length: count }, (_, i) => ({
+    x: i, y: Math.sin(i / 10) + Math.random() * 0.2
+  }))
+  return { chart: data }
+}
+```
+Schema: `{ "name": "chart", "type": "chart", "mark": "line", "x": "x", "y": "y" }`
+### Map output
+Model returns markers array:
+```javascript
+function model () {
+  return {
+    map: [
+      { lat: 51.505, lng: -0.09, popup: 'London' },
+      { lat: 48.857, lng: 2.352, popup: 'Paris' },
+      { lat: 52.52, lng: 13.405, popup: 'Berlin' }
+    ]
+  }
+}
+```
+### Pipeline
+Sequential models pass merged results forward:
+```json
+{
+  "model": [
+    { "url": "preprocess.js", "worker": true },
+    { "url": "analyze.js", "worker": false }
+  ]
+}
+```
+First model returns `{ cleaned: [...] }`, second receives `{ cleaned: [...], ...originalInputs }`. Return `{ stop: true }` from any model to halt early.
+### Multi-column layout
+Use `columns` on inputs/outputs for dashboard-style layouts:
+```json
+{
+  "inputs": [
+    { "name": "a", "type": "slider", "min": 0, "max": 100, "columns": 6 },
+    { "name": "b", "type": "slider", "min": 0, "max": 100, "columns": 6 }
+  ],
+  "outputs": [
+    { "name": "total", "type": "number", "columns": 4 },
+    { "name": "chart", "type": "chart", "columns": 8 }
+  ]
+}
+```
 ## Schema
 - `model` — Contains main parameters of the model/script
@@ -139,8 +308,8 @@ Extra blocks can be provided for further customization:
   - `container` (string) — How input values are passed to the function/method:
     - `object` (default) — Pass inputs wrapped in an object, i.e. `{'x': 1, 'y': 2}`
     - `args` — Pass inputs as separate arguments
+    - In `object` mode, JavaScript models receive the runtime context as a second argument: `function model(inputs, ctx) { ... }`
   - `worker` (boolean) — If `true`, JSEE initializes a Web Worker to run the script
-    - For `container: 'object'`, model functions receive a second runtime context argument (`ctx`)
     - `ctx.log(...args)` — Write runtime logs
     - `ctx.progress(value)` — Report progress (`0..100` or `null` for indeterminate)
     - `ctx.isCancelled()` — Check cooperative cancellation state (useful in long loops/streams)
@@ -149,39 +318,127 @@ Extra blocks can be provided for further customization:
   - `model` can also be an **array of model objects** to create a pipeline. Models execute sequentially — each receives the merged output of the previous one. First model defaults to `worker: true`, others to `worker: false`. Return `{ stop: true }` from any model to halt the pipeline early
 - `render` — Custom rendering script. Instead of relying on JSEE for output visualization, you can provide a custom script that visualizes the results. That can be useful if you rely on custom libs for plotting
 - `design` — Design parameters
-  - `layout` — Layout for the model/input/output blocks. If it's empty and the JSEE container is not, JSEE uses inner HTML as a template. If the container is empty too, it uses the default `blocks` template
-  - `framework` — Design framework to use. If a JavaScript object with the same name is present in a global context, JSEE loads it too (using Vue's `use` method)
+  - `layout` — Layout for the model/input/output blocks. If it's empty and the JSEE container is not, JSEE uses inner HTML as a template. If the container is empty too, it uses the default `blocks` template. Set `'sidebar'` for a fixed-width (280px) sticky input panel — inputs stay visible while scrolling outputs. Collapses to single column on mobile
+  - `framework` — Design framework to use (`'minimal'` by default). If a JavaScript object with the same name is present in a global context, JSEE loads it too (using Vue's `use` method)
+  - `theme` — Color theme. Set `'dark'` for dark mode
+  - `primary` — Accent color (buttons, toggles, gradient). Hex string, e.g. `'#e74c3c'`
+  - `secondary` — Second gradient color. Defaults to a darker shade of `primary`
+  - `bg` — Background color. Derives card, input, and border colors automatically
+  - `fg` — Text color. Derives secondary text color automatically
+  - `font` — Font family string, e.g. `'Georgia, serif'`
+  - `radius` — Border radius in pixels (number) or CSS value (string)
+  - `grid` (array) — 12-column grid split for input/output sections. E.g. `[4, 8]` (default), `[6, 6]` (equal), `[3, 9]`. Values are `fr` units
+  - All components use CSS custom properties that can be overridden via CSS: `--jsee-primary`, `--jsee-bg`, `--jsee-text`, `--jsee-text-secondary`, `--jsee-border`, `--jsee-input-bg`, `--jsee-input-border`, `--jsee-focus-border`, `--jsee-focus-ring`, `--jsee-card-bg`, `--jsee-bg-secondary`, `--jsee-label-bg`, `--jsee-error`, `--jsee-radius`
 - `inputs` — Inputs definition
   - `name`* — Name of the input
   - `type`* — Type. Possible types:
     - `int`, `float` or `number` — Number
-    - `string` — String
-    - `text` — Textarea
+    - `string` — String (text input)
+    - `color` — Color picker (HTML5 `<input type="color">`)
+    - `text` — Textarea (auto-resizes to fit content, up to 400px)
     - `checkbox` or `bool` — Checkbox
     - `select` or `categorical` — Select (one of many `options`)
+    - `slider` — Range slider (`min`, `max`, `step`)
+    - `range` — Dual-handle range slider, returns `[min, max]` array
+    - `radio` — Radio button group (one of many `options`)
+    - `toggle` — Toggle switch (boolean)
+    - `date` — Date picker
+    - `multi-select` — Checkbox group, returns array of selected `options`
+    - `group` — Group of inputs. Use `elements` array for child inputs. Supports three display styles via `style` property:
+      - `blocks` (default) — flat list of child inputs
+      - `accordion` — collapsible section (also triggered by `collapsed` or `label` props)
+      - `tabs` — tabbed view where each child element becomes a tab (child groups use their `name`/`label` as tab label)
     - `file` — File Input
+    - `folder` — Directory input. Shows a file listing with optional selection. In the browser, uses `<input webkitdirectory>` or drag-drop. On the server, reads from a directory path. Returns array of `{name, path, size, type, selected}` objects. Props:
+      - `select` (boolean) — Show checkboxes for file selection (default: all files passed)
+      - `reactive` (boolean) — Trigger model run on selection change
     - `action` or `button` — Button (its `name` will be passed as a `caller` to the model)
   - `default` — Default value
   - `alias` (string or array of strings) — Alternative names for URL parameter matching. E.g. `"alias": ["f", "file"]` allows `?f=value` or `?file=value` to set this input
   - `display` (string) — Filtrex expression to conditionally show/hide this input. Evaluated against current input values. E.g. `"display": "mode == 'advanced'"` shows the input only when `mode` is `"advanced"`. Supports `len()` for string length
+  - `reactive` (boolean) — Trigger a model run when this input changes (see **Execution triggers** below)
   - `disabled` (boolean) — Disables the input in the UI. When combined with `reactive: true`, triggers an initial model run on page load (useful for server-populated values)
+  - `enter` (boolean) — If `true` on a `string` input, pressing Enter triggers a model run (useful for chat or search inputs)
   - `raw` (boolean, file input only) — If `true`, pass the raw source to the model instead of reading text in the UI (`File` object for disk files or `{ kind: 'url', url: '...' }` for URL input)
   - `stream` (boolean, file input only) — If `true`, pass an async iterable `ChunkedReader` to the model instead of raw source handles. Supports `for await (const chunk of reader)`, `await reader.text()`, `await reader.bytes()`, and `for await (const line of reader.lines())`. Works in both main-thread and worker execution. Reader metadata (`reader.name`, `reader.size`, `reader.type`) is preserved and remains available in downstream pipeline models
+  - `validate` (string) — Filtrex expression for input validation. The variable `value` holds the current input value. Expression must return truthy for valid input. E.g. `"validate": "value >= 0 and value <= 150"`. Runs on every input change (debounced). Invalid inputs show an error message and block model execution
+  - `required` (boolean) — Shorthand validation: rejects empty strings, null, undefined, and empty arrays
+  - `error` (string) — Custom error message for `validate` or `required` failures (default: `"Invalid value"` / `"Required"`)
+  - `columns` (number, 1-12) — Grid column span for this input. When any input has `columns`, the inputs section switches to a 12-column CSS grid. E.g. `"columns": 6` makes the input take half width
   - URL params for file inputs (e.g. `?file=https://...`) auto-load on init, so bookmarkable links run without an extra Load click
-- `outputs` — Outputs definition. Outputs also support `alias` (string) for matching model result keys by alternative names
+- `outputs` — Outputs definition. Outputs also support `alias` (string) for matching model result keys by alternative names. Per-output `columns` (number, 1-12) sets grid column span, same as inputs
   - `name`* — Name of the output
   - `type`* — Type. Possible types:
     - `file` — File output (not displayer, but downloaded)
     - `object` — JavaScript Object
     - `html` or `svg` — SVG element
     - `code` — Code block
+    - `markdown` — Rendered Markdown (supports tables, headings, lists, etc.)
+    - `image` — Image (`<img>` tag from data URL or URL)
+    - `audio` — Audio player (`<audio>` from URL or data URL)
+    - `video` — Video player (`<video>` from URL or data URL)
+    - `table` — Virtualized table with scrolling
+    - `chat` — Chat message list. Accumulates `{role, content}` messages across runs instead of replacing. Renders user/assistant bubbles with Markdown support, auto-scrolls to latest message. See **Chat mode** below
+    - `group` — Group of outputs. Use `elements` array for child outputs. Supports `style: 'tabs'` for tabbed display or default blocks (stacked). Child outputs are matched by name against model results
+    - `chart` — SVG chart via [Observable Plot](https://observablehq.com/plot/). Model returns array of objects, column-oriented data, or a full Plot config. Schema props: `mark` (line/dot/bar/area/etc.), `x`, `y`, `color`, `width`, `height`. Included in full bundle or load Plot via `imports`
+    - `3d` — 3D model viewer via [Three.js](https://threejs.org/). Model returns a URL (GLTF/GLB), data URL, or geometry object `{vertices, faces}`. Schema props: `width`, `height`. Included in full bundle or load Three.js via `imports`
+    - `map` — Interactive map via [Leaflet](https://leafletjs.com/). Model returns markers `[{lat, lng, popup}]`, `{center, markers, zoom}`, or GeoJSON. Schema props: `height`, `zoom`, `center`, `tiles`. Included in full bundle or load Leaflet via `imports`
+    - `pdf` — Browser-native PDF viewer. Model returns a URL, data URL, Blob, ArrayBuffer, or Uint8Array. Schema prop: `height`. Included in the core bundle
+    - `gallery` — CSS grid of images. Model returns array of URLs/data URLs. Click to expand lightbox. Schema props: `columns` (default 3), `gap` (default 8px). Zero-cost, included in core bundle
+    - `highlight` — Highlighted text with labels. Model returns `[{text, label, color}]` segments. Unlabeled segments render as plain text. Zero-cost, included in core bundle
+    - `gauge` — Semicircle gauge. Model returns a number or `{value, label}`. Schema props: `min` (default 0), `max` (default 100), `label`, `color`. Zero-cost, included in core bundle
+    - `number` — Large KPI number display. Model returns a number or `{value, delta, label}`. Delta shown with colored up/down arrow. Schema props: `label`, `prefix` (e.g. `"$"`), `suffix` (e.g. `"%"`), `precision`
+    - `alert` — Colored status banner with left accent border. Model returns a string or `{message, type}`. Four variants: `info` (blue, default), `success` (green), `warning` (amber), `error` (red). Schema prop: `alertType` (default type when value is a string)
+    - `viewer` — Intelligent media viewer. Model returns a URL string. Auto-detects content type from extension: images (png, jpg, gif, svg, webp), audio (mp3, wav, ogg, flac), video (mp4, webm, mov), or iframe (fallback). Useful with `folder` input for file preview
     - `function` — Render function. Rather than returning a value, a model returns a function that JSEE will call passing the container element
-    - `blank` — Blank block (can be alternative to `function` and useful for custom renderers)
+    - `blank` — Empty container for custom rendering via `function` output or external code
 - `examples` — List of examples
-- `autorun` (boolean, default: `false`) — Run the model automatically on first load
-- `reactive` (boolean, default: `false`) — Re-run the model on any input change (debounced). For per-input reactivity, set `reactive: true` on individual inputs instead
-- `interval` (number, default: `0`) — Defines the interval between script evaluations (in milliseconds). If set to `0`, the script is evaluated only once
-- Runtime cancellation: call `jsee.cancelCurrentRun()` on the JSEE instance to request stop of the active run. Long-running models should check `ctx.isCancelled()` and return early
+- **Execution triggers** — by default the model only runs when the user clicks Run. Three schema-level options change this:
+  - `autorun` (boolean, default: `false`) — run the model once on first load, then wait for manual Run clicks
+  - `reactive` (boolean, default: `false`) — re-run the model on **any** input change (debounced 300ms). Useful for lightweight models where instant feedback is desired
+  - `interval` (number, default: `0`) — repeat execution every N milliseconds. `0` means no repetition
+  - Per-input `reactive` — set `reactive: true` on an **individual input** to trigger a model run only when that specific input changes (fires immediately, not debounced). Other inputs still require a manual Run click. Useful when one input is interactive (e.g. a slider) but others are expensive to recompute
+  | Option | Scope | When it runs | Debounced |
+  |--------|-------|-------------|-----------|
+  | `autorun: true` | schema | once on load | no |
+  | `reactive: true` | schema | every input change | yes (300ms) |
+  | `reactive: true` | input | that input changes | no |
+  | `interval: N` | schema | every N ms | no |
+- **Chat mode** — declare an output with `"type": "chat"` to enable conversational UI. The runtime manages state:
+  1. User types a message in a text input and presses Run (or Enter if the input has `"enter": true`)
+  2. The runtime injects `history` (array of `{role, content}` dicts) into the model payload alongside the user's `message`
+  3. The model returns `{chat: "response string"}` (or `{chat: {role, content}}`)
+  4. The runtime appends both the user message and assistant response to the chat output's internal `_messages` array, clears the input, and auto-scrolls
+  5. Messages render with Markdown support (code blocks, bold, links, tables)
+  Works with both Workers (postMessage) and server POST — no special execution mode needed. Python shorthand: `jsee.serve(fn, chat=True)` auto-generates the schema from `fn(message, history) -> str`
+- **Input persistence** — by default, JSEE saves input values to `localStorage` and restores them on page refresh. Priority: URL params > localStorage > schema defaults. Set `persist: false` in the schema to disable. Clicking Reset clears saved values
+- **Notifications** — set `notify: true` in the schema to show a browser notification when a run completes while the tab is hidden. JSEE requests permission on first load and fires `new Notification()` after successful runs only
+- **Streaming outputs (SSE)** — set `model.stream: true` to enable Server-Sent Events streaming. The POST handler reads `text/event-stream` responses and calls `output()` on each `data:` line for progressive results. Python generators are auto-detected:
+  ```python
+  def stream_count(n: int = 5):
+      for i in range(n):
+          yield {'count': i}
+  jsee.serve(stream_count, stream=True)
+  ```
+- **Efficient binary outputs** — large base64 image data URLs (>50KB) in `image` outputs are automatically converted to `URL.createObjectURL()` blob URLs, reducing memory usage by ~33%. Previous blob URLs are revoked on each update
+- **Typed array passing** — declare `arrayBuffer: true` on an input to convert JS arrays to typed arrays before passing to workers/WASM. Set `dtype` to control the type (`float32`, `float64`, `uint8`, `int32`, etc., default: `float64`). Typed arrays are transferred with zero-copy semantics via `postMessage` transferables
+  ```json
+  "inputs": [{ "name": "data", "type": "string", "arrayBuffer": true, "dtype": "float32" }]
+  ```
+- Runtime cancellation: call `jsee.cancelCurrentRun()` on the JSEE instance to request stop of the active run. Long-running models should check `ctx.isCancelled()` and return early:
+  ```javascript
+  async function model (inputs, ctx) {
+    for (let i = 0; i < inputs.steps; i++) {
+      if (ctx.isCancelled()) throw new Error('Cancelled')
+      await doStep(i)
+      ctx.progress(Math.round(100 * (i + 1) / inputs.steps))
+    }
+    return { done: true }
+  }
+  ```
 - Schema validation — JSEE validates schema structure during initialization and logs warnings for non-critical issues (e.g. unknown input types, malformed aliases)
 - `jsee.download(title)` — Downloads a self-contained HTML file that works offline. All external scripts are inlined and the schema/model/imports are cached. `title` defaults to `'output'`
 - `page` (CLI only) — Page metadata for generated HTML:
@@ -191,35 +448,306 @@ Extra blocks can be provided for further customization:
   - `social` (object) — Social media links: `twitter`, `github`, `facebook`, `linkedin`, `instagram`, `youtube` (values are usernames/handles)
   - `org` (object) — Organization footer: `name`, `url`, `description`
-JSEE is a reactive branch of [StatSim](https://statsim.com)'s [Port](https://github.com/statsim/port). It's still work in progress. Expect API changes.
+## Smart output auto-detection
+When outputs are not explicitly defined in the schema, or when a model returns keys that don't match any named output, JSEE infers the output type from the value:
+| Value | Inferred type |
+|---|---|
+| Array of objects | `table` |
+| Array of image URL strings (`.png`, `.jpg`, `.gif`, `.svg`, `.webp`) | `gallery` |
+| Other arrays | `object` |
+| `data:image/*` string | `image` |
+| `data:audio/*` string | `audio` |
+| `data:video/*` string | `video` |
+| `data:application/pdf` string | `pdf` |
+| String ending in `.png`, `.jpg`, `.gif`, `.svg`, `.webp` | `image` |
+| String ending in `.mp3`, `.wav`, `.ogg`, `.flac` | `audio` |
+| String ending in `.mp4`, `.webm`, `.mov` | `video` |
+| String ending in `.pdf` | `pdf` |
+| String ending in `.md` | `markdown` |
+| String with newlines and > 200 characters | `code` |
+| Other strings | `string` |
+| Numbers, booleans | `string` |
+| Objects | `object` |
+## JSEE instance API
+After creating an instance with `new JSEE({schema, container})`, these methods are available:
+| Method | Description |
+|---|---|
+| `jsee.run(caller)` | Execute the model pipeline. `caller` can be `'run'`, `'autorun'`, `'reactive'`, or a custom button name |
+| `jsee.output(result)` | Process and render results to output cards |
+| `jsee.cancelCurrentRun()` | Stop the active run. Rejects the current run promise, sets cancellation state, and signals/terminates workers |
+| `jsee.isCancelled()` | Returns `true` if cancellation was requested |
+| `jsee.progress(value)` | Set progress bar: `0`-`100` for determinate, `null` for indeterminate |
+| `jsee.download(title)` | Export current app as a self-contained offline HTML file |
+| `jsee.destroy()` | Cleanup: cancel runs, terminate workers, unmount Vue app, revoke blob URLs |
+| `jsee.notify(text)` | Show a success toast notification |
+| `jsee.log(...args)` | Log to browser console and optional `#log` DOM element |
+JSEE is part of the [StatSim](https://statsim.com) ecosystem. The schema/runtime contract is the public surface; lower-level packaging and renderer internals may continue to evolve.
+## CLI — Node.js
-# CLI
+```
+jsee [schema.json] [data...] [options]
+jsee init [template] [--html]
+```
-- `--inputs`, `-i` — Input schema JSON file (default: `schema.json`)
-- `--outputs`, `-o` — Output file path(s), comma-separated (HTML, JSON, or both)
-- `--description`, `-d` — Markdown file to include as app description
-- `--port`, `-p` — Dev server port (default: `3000`)
-- `--version`, `-v` — JSEE runtime version (`latest`, `dev`, or semver)
-- `--fetch`, `-f` — Bundle everything into a single offline HTML: fetches the JSEE runtime, reads `model`/`view`/`render` code from disk, and resolves imports. Local files are detected by checking the filesystem (so bare paths like `dist/core.js` work alongside `./relative.js`); anything not found locally is fetched from CDN. All code is stored in hidden `<script data-src="...">` elements
-- `--runtime`, `-r` — Select runtime source for generated HTML:
-  - `auto` (default): `inline` when `--fetch` is used, otherwise `cdn` for file output and `local` for dev server mode
-  - `local`: use `http://localhost:<port>/dist/...`
-  - `cdn`: use jsdelivr runtime URL
-  - `inline`: embed runtime code directly in HTML
-  - Any other value is used as a custom `<script src="...">` path/URL (e.g. `./node_modules/@jseeio/jsee/dist/jsee.js`)
-- `--cdn`, `-c` — Rewrite model URLs for CDN deployment (can be a base URL string or boolean to infer from `package.json`)
-- `--execute`, `-e` — Run models server-side (see below)
-- `--verbose` — Enable verbose logging
-- `--help`, `-h` — Show usage info
+### Commands
-# Server-side execution
+#### `jsee init [template]`
-With `--execute` (`-e`), JSEE loads each model's JS file on the server (via `require()`), rewrites the schema to point at a POST endpoint, and starts an Express server. The browser GUI sends inputs to the server, which runs the model and returns results as JSON. This is useful for models that need Node.js APIs or heavy computation that shouldn't run in the browser.
+Scaffold a new project. Templates: `minimal` (default), `chat`.
 ```bash
-jsee schema.json -e -p 3000
+jsee init                   # schema.json + model.js + README.md
+jsee init chat              # chat template
+jsee init --html            # single index.html with CDN script
 ```
-# Changelog
+#### `jsee <schema> [data...]`
+Start a dev server or generate a static HTML file from a schema.
+```bash
+jsee schema.json                    # dev server on port 3000
+jsee schema.json -o app.html        # generate static HTML
+jsee schema.json -o app.html -f     # self-contained HTML with bundled runtime
+```
+### Options
+| Flag | Description |
+|---|---|
+| `-i, --inputs <file>` | Input schema JSON file (default: `schema.json`) |
+| `-o, --outputs <file>` | Output file path(s), comma-separated (HTML, JSON) |
+| `-d, --description <file>` | Markdown file to include as app description |
+| `-p, --port <number>` | Dev server port (default: `3000`) |
+| `-v, --version <version>` | JSEE runtime version (`latest`, `dev`, or semver) |
+| `-f, --fetch` | Bundle runtime + all deps into a single offline HTML |
+| `-e, --execute` | Run models server-side (auto-enabled when serving local .js models) |
+| `--client` | Force client-side execution (disable auto server-side) |
+| `-c, --cdn <url\|bool>` | Rewrite model URLs for CDN deployment |
+| `-r, --runtime <mode>` | Runtime source: `auto\|local\|cdn\|inline` or a custom URL/path |
+| `--verbose` | Enable verbose logging |
+| `--help, -h` | Show usage info |
+#### `--fetch`
+Bundles everything into a single offline HTML: the JSEE runtime, model/view/render code, and all imports are stored in hidden `<script data-src="...">` elements. Local files are detected by checking the filesystem (so bare paths like `dist/core.js` work alongside `./relative.js`); anything not found locally is fetched from CDN.
+#### `--runtime`
+Select the runtime source for generated HTML:
+- `auto` (default): `inline` when `--fetch`, otherwise `cdn` for file output and `local` for dev server
+- `local`: `http://localhost:<port>/dist/...`
+- `cdn`: jsdelivr CDN URL
+- `inline`: embed runtime code directly in HTML
+- Any other value is used as a custom `<script src="...">` path/URL
+### Data inputs
+Positional arguments after the schema file and named `--key=value` arguments are mapped to schema inputs. Values are auto-detected:
+| Value | Detected as |
+|---|---|
+| `42`, `3.14` | Number |
+| `'[1,2,3]'`, `'{"a":1}'` | JSON (array or object) |
+| `data.csv` (existing file) | File path |
+| `hello` | String |
+Inputs set from the CLI are locked (non-editable) in the GUI and used as defaults for server-side execution.
+```bash
+# Positional — mapped to inputs in schema order
+jsee schema.json 42 hello
+# Named — matched by input name
+jsee schema.json --a=100 --b=200
+# File path
+jsee schema.json data.csv
+# Mixed
+jsee schema.json data.csv --format=json
+```
+### Server-side execution
+When serving (no `-o` flag), JSEE automatically enables server-side execution if all models point to local `.js` files. Use `--client` to force browser execution.
+```bash
+jsee schema.json              # auto server-side (local .js models)
+jsee schema.json --client     # force browser execution
+jsee schema.json -e -p 3000   # explicit server-side on port 3000
+```
+### File and folder serving
+JSEE can serve individual files or entire folders without a schema or model:
+```bash
+jsee report.pdf                   # serve PDF with viewer
+jsee photo.png                    # serve image
+jsee data.csv                     # serve CSV as table
+jsee data/                        # serve folder with file browser
+```
+For single files, JSEE auto-detects the output type from the file extension (image, pdf, audio, video, table, markdown, code). For folders, JSEE creates a file browser with selection checkboxes, stats summary, and a preview of the selected file.
+Output type auto-detection also works for model results — if a model returns a string ending in `.png`, it renders as an image automatically.
+### Serve bar
+When serving, a top bar appears with the server address, a Save HTML button, and (when server-side execution is active) a Browser/Server toggle to switch execution mode. Input values are preserved across the switch via localStorage. The serve bar is not included in generated output files or saved bundles.
+## CLI — Python
+```
+jsee <target> [function] [data...] [options]
+jsee init [template]
+```
+### Commands
+#### `jsee init [template]`
+Scaffold a new project. Templates: `minimal` (default), `chat`. Generates `schema.json` + `model.py` + `README.md`.
+```bash
+jsee init                   # minimal template
+jsee init chat              # chat template
+```
+#### `jsee <file.py> <function> [data...]`
+Serve a Python function as a web app with auto-generated GUI and REST API.
+```bash
+jsee example.py greet                  # serve function
+jsee example.py greet --port=8080      # custom port
+```
+#### `jsee <schema.json>`
+Serve from a pre-built schema file.
+```bash
+jsee schema.json
+```
+### Options
+| Flag | Description |
+|---|---|
+| `--host <addr>` | Host to bind to (default: `0.0.0.0`) |
+| `--port <number>` | Port to listen on (default: `5050`) |
+### Data inputs
+Same as Node.js — positional args after the function name and `--key=value` args are mapped to function parameters. Values are auto-detected (numbers, JSON, file paths, strings). Inputs set from the CLI are locked in the GUI.
+```bash
+jsee example.py greet Alice 5          # positional data
+jsee example.py greet --name=Alice     # named data
+jsee schema.json 42 hello              # positional data with schema
+```
+### API endpoints
+Every server (both Node.js with `--execute` and Python) exposes these endpoints:
+| Route | Method | Description |
+|---|---|---|
+| `/` | GET | Interactive GUI |
+| `/api` | GET | Schema and endpoint discovery |
+| `/api/openapi.json` | GET | Auto-generated OpenAPI 3.1 spec |
+| `/{modelName}` | POST | Execute model with JSON or multipart input |
+Both servers support `application/json` and `multipart/form-data` POST bodies, CORS (`Access-Control-Allow-Origin: *`), and return consistent JSON errors for 404/400/500.
+```bash
+# Run the model via API (JSON)
+curl -X POST http://localhost:3000/modelName \
+  -H 'Content-Type: application/json' \
+  -d '{"x": 3, "y": 4}'
+# Run with file upload (multipart)
+curl -X POST http://localhost:3000/modelName \
+  -F 'text=hello' \
+  -F 'file=@image.png'
+# Get OpenAPI spec
+curl http://localhost:3000/api/openapi.json
+```
+#### Return value serialization
+Both servers normalize model return values consistently:
+| Return type | JSON response |
+|---|---|
+| Object/dict | returned as-is |
+| Primitive (number, string, bool) | `{"result": value}` |
+| Tuple/list (Python) | `{"result": [a, b]}` |
+| Buffer/bytes | `{"result": "data:image/png;base64,..."}` |
+| PIL Image (Python) | `{"result": "data:image/png;base64,..."}` |
+| list[dict] (Python) | `{"result": {"columns": [...], "rows": [...]}}` |
+## Python
+JSEE also ships a Python package (`py/`) that turns Python functions into web apps with the same GUI and API. Zero dependencies beyond Python stdlib.
+```bash
+cd py && pip install -e .
+jsee example.py sum
+```
+Or programmatically:
+```python
+from typing import Annotated, Literal
+import jsee
+def calculator(
+    num1: float,
+    op: Literal['add', 'subtract', 'multiply', 'divide'],
+    num2: float,
+    precision: Annotated[int, jsee.Slider(0, 10)] = 2
+) -> dict:
+    """A simple calculator"""
+    ops = {'add': num1 + num2, 'subtract': num1 - num2,
+           'multiply': num1 * num2, 'divide': num1 / num2 if num2 else 0}
+    return {'result': round(ops[op], precision)}
+jsee.serve(calculator, port=5050)
+```
+Python type hints are auto-mapped to GUI widgets: `Literal` → dropdown, `Annotated[float, jsee.Slider()]` → slider, `bool` → checkbox, `Enum` → dropdown. See [`py/README.md`](py/README.md) for full Python documentation.
+### WSGI deployment
+For production deployment, use `create_app()` to get a standard WSGI application:
+```python
+# app.py
+import jsee
+def multiply(x: float = 5) -> dict:
+    return {'result': x * 2}
+app = jsee.create_app(multiply)
+```
+Deploy with gunicorn, uWSGI, or any WSGI server:
+```bash
+gunicorn app:app
+```
+`create_app()` accepts the same arguments as `serve()` — functions, dicts, or schema.json paths. Note: SSE streaming is not supported in basic WSGI.
+## Changelog
 See `CHANGELOG.md`.