@jseeio/jsee 0.3.7 → 0.3.9

package/.claude/settings.local.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm run test:basic:*)",
+      "Bash(npm run build-dev:*)",
+      "Bash(npm run test:unit:*)",
+      "Bash(find:*)",
+      "Bash(npx eslint:*)",
+      "Bash(npm run test:python:*)"
+    ]
+  }
+}

package/.eslintrc.js

@@ -0,0 +1,38 @@
+module.exports = {
+  env: {
+    browser: true,
+    node: true,
+    es2020: true,
+    jest: true,
+  },
+  parserOptions: {
+    ecmaVersion: 2020,
+    sourceType: 'module',
+  },
+  rules: {
+    // Match existing style: no semicolons, single quotes, 2-space indent
+    semi: ['warn', 'never'],
+    quotes: ['warn', 'single', { avoidEscape: true, allowTemplateLiterals: true }],
+    indent: ['warn', 2, { SwitchCase: 1, ignoredNodes: ['TemplateLiteral *'] }],
+    'no-unused-vars': ['warn', { args: 'none', varsIgnorePattern: '^_' }],
+    'no-undef': 'error',
+    eqeqeq: ['warn', 'smart'],
+    'no-eval': 'off', // intentional eval usage in main.js
+  },
+  globals: {
+    VERSION: 'readonly',
+    importScripts: 'readonly',
+    JSEE: 'readonly',
+    loadPyodide: 'readonly',
+  },
+  overrides: [
+    {
+      // Puppeteer tests use global `page` from jest-puppeteer
+      files: ['test/**/*.test.js'],
+      globals: {
+        page: 'readonly',
+      },
+    },
+  ],
+  ignorePatterns: ['dist/', 'node_modules/', 'apps/', 'tmp/', 'load/'],
+}

package/AGENTS.md

@@ -0,0 +1,38 @@
+# Project briefing for awesome agents
+
+You are the most talented and experienced agent in the world, and you have been tasked with leading the development of JSEE, a powerful tool for automating the creation of interactive web applications.
+
+## Philosophy
+
+JSEE abstracts away the complexities of web development, allowing users to focus on their core logic and data. It provides a simple interface for defining inputs, outputs, and processing logic, and takes care of the rest. By leveraging modern web technologies like Vue.js and Web Workers, JSEE ensures that applications are responsive and efficient.
+
+
+## Style
+
+Use **2-space indentation** and **semicolon-free** syntax. Use **single quotes** for strings. Preserve the existing style in the codebase, and avoid introducing new formatting styles or conventions.
+
+## Quick start
+
+
+## Repo map
+
+
+## Definition of done
+- Run: `npm run build` (or `npm run build-dev` during iteration)
+- Run unit tests: `npm run test:unit` (fast, no browser needed)
+- Run E2E tests: `npm run test:basic` (requires `http-server -p 8080` running)
+- Add/adjust unit tests for core logic in `test/unit/`
+
+## Constraints
+- Don’t add new production dependencies without asking.
+- Update the `README.md`, `CHANGELOG.md` and `index.html` with any user-facing changes or new features.
+- Commit messages should be clear and descriptive, following the format: `feature|fix|test|docs: short description` (e.g., `feature: add new column type classification`). No multiline and EOF!
+- Each change: for non-trivial changes, add comments, update docs (new features that can be used by users should be represented in `README.md` and `CHANGELOG.md`), run tests, commit with a clear message. For trivial changes (e.g., fixing typos), you can skip some steps but still ensure the change is well-documented in the commit message.
+- A lot of apps depend on JSEE, so be mindful of backward compatibility. If a change is breaking, stop and ask for help. If you need to make a breaking change, update the version in `package.json` and clearly document the change in `CHANGELOG.md`.
+- Ask for confirmation before each commit
+- Commit changes one at a time, with clear messages. Avoid large commits that combine multiple changes.
+
+## Conventions
+- Formatting: no formatter is configured; preserve existing style (2-space indentation, semicolon-free, single quotes)
+- Types: plain JavaScript with runtime type checks (`typeof`, `isNaN`) and counters
+- Error handling: prefer tolerant stream processing (skip malformed lines, classify invalid/empty values as `missing`, degrade expensive stats for unsuitable columns instead of hard-failing)

package/CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog
+
+## Unreleased
+### Bug fixes:
+- Gate worker initialization with an `initialized` flag: only the first `{url|code}` payload initializes the worker, all later payloads are treated as execution input
+- Fix model type inference for URL-loaded JS: when `code` is present, infer `function` instead of treating `url` as API `post`
+- Improve worker payload fallback diagnostics: if `postMessage` fails with File/Blob/binary payloads, throw a descriptive error instead of silently dropping data via JSON fallback
+- Move `showdown-katex` and `katex` to runtime `dependencies` so `npx jsee` works without dev installs
+- Fix `--fetch` bundling to include `schema.view` and `schema.render` blocks in addition to `schema.model`
+- Fix `--fetch` import resolution for local relative JS imports and support object import entries (`{ url, ... }`)
+- Fix CLI output path handling for absolute/relative `--outputs` values and remove duplicate final HTML write
+- Fix `download()` method referencing undeclared `env` variable — now correctly uses `this`
+- Fix `outputAsync()` referencing undeclared `delay` — now correctly uses `utils.delay`
+- Fix CLI social links default case referencing undeclared `s` variable
+- Remove dead `title` assignment in CLI `gen` function (already handled in `genHead`)
+### Features:
+- Allow `progress(null)` to render an indeterminate top progress bar for stream-like tasks where total size is unknown
+- Add `cancelCurrentRun()` runtime entrypoint and wire overlay Stop button with proper `click` handling for any active run
+- Add worker cooperative cancel signal: `_cmd: 'cancel'` updates worker state and JS model context now exposes `ctx.isCancelled()`
+- Add end-to-end `raw` file input mode: schema `inputs[].raw` now passes `File` objects / URL handles instead of loading full text into memory
+- Add file input stream mode (`inputs[].stream: true`) that wraps raw file/URL sources into async iterable `ChunkedReader` objects (zero-dep, supports `for await`, `.text()`, `.bytes()`, `.lines()`) in both worker and main-thread execution
+- Preserve stream reader metadata (`name`, `size`, `type`) for file/URL sources and keep it available across downstream pipeline stages
+- Auto-load file input URL query params on init (no extra Load click required)
+- Add CLI `--runtime <auto|local|cdn|inline>` to control runtime source in generated HTML
+- Add CLI `--help` flag with usage information and examples
+- Add ESLint config matching project style (no semicolons, single quotes, 2-space indent)
+
+## 0.3.8 (2026-02-08)
+### Bug fixes:
+- Fix `run()` error handling: wrap in try/catch/finally so overlay and running state always reset on failure
+- Add `.catch()` to fire-and-forget `run()` callers to prevent unhandled rejections
+- Add worker execution timeout (default 30s, configurable via `model.timeout`) to prevent permanently frozen UI
+- Fix `indexOf('json')` bug in `initSchema` — condition was inverted, `.json` was never appended
+- Fix array type detection in auto-created outputs (`typeof` returns `'object'` for arrays)
+- Fix `getName` for `async function` strings and guard against arrow functions crashing
+- Fix broken string interpolation and remove leftover `console.log('1')` in utils.js
+### Features:
+- Add `schema.reactive` option: re-run model on any input change (debounced 300ms). Distinct from `autorun` (first load only) and per-input `reactive` (individual input change)
+- Add run-concurrency guard: overlapping reactive/autorun calls are dropped, manual clicks are queued
+- Move `getName` to utils.js for testability and reuse
+- Add runtime `validateSchema()` checks and fail-fast on critical schema issues (`model`/`view` presence, input shape)
+- Replace deprecated `node-sass` with `sass`, update `express`, `csv-parse`, and remove unused `element-plus`
+### Testing:
+- Add separate Jest config for unit tests (`jest.unit.config.js`, no browser needed)
+- Add unit tests for utils.js: `isObject`, `sanitizeName`, `getUrl`, `delay`, `debounce`, `getName`, `getModelFuncJS`, `getModelFuncAPI`, `validateSchema`
+- Add `npm run test:unit` script
+
+## 0.3.4 (2024-11-19)
+### JSEE:
+- [x] Add `columns` parameter to the `inputs`, `outputs` blocks (making it possible to create multi-column layouts, like simple dashboards)
+- [x] Add `function` output type (for custom renderers which take a container element as an argument)
+- [x] Add `dom-to-image` library for exporting dynamic output blocks to PNG
+- [x] Support for inputs to be set with url parameters (e.g. `?input1=1&input2=2`)
+### HTML Generator:
+- [x] Add `latex` and table output in the markdown renderer
+- [x] Cache `import` scripts to avoid multiple loads when `--fetch` is used
+- [x] Infer `description` from the markdown and update html `<head>` with it
+- [x] Update `social`, `org`, `ga` blocks
+- [x] Small layout fixes
+
+## 0.3.1 (2024-04-10)
+- [x] Add `download` method to jsee object
+- [x] Add `bin` folder with `cmd.js` for easier project building
+
+## 0.2.9 (2023-12-11)
+- [x] Add examples
+- [x] Add imports
+- [x] Add `caller` field to the model input (can be: `run`, `autorun` or a button name)
+- [x] Add `title` field (for buttons rn)
+- [x] If `display` field is `false` the input is not shown
+- [x] If `autorun` is true, then actually autorun the model initially
+
+## 0.2.8 (2021-12-29)
+- [x] Fix no input case
+
+## 0.2.7 (2021-12-29)
+- [x] Show output when result is `0`
+- [x] Updated style for buttons and inputs
+
+## 0.2.6 (2021-12-27)
+- [x] Tests
+- [x] Load schema from query (loader)
+- [x] Reset button appears only after data change
+- [x] Default input type (`string`)
+- [x] Directly load code when running in a window (not code to text)
+- [x] Passing code directly

package/CLAUDE.md

@@ -0,0 +1,5 @@
+See @AGENTS.md for the canonical project briefing.
+
+Claude workflow:
+- Explore in Plan Mode, then implement, then run tests.
+- Prefer adding stable rules to AGENTS.md via PR.

package/README.md

@@ -1,4 +1,4 @@
-# Focus on code, not UI
+# JSEE
 
 Minimal example:
 ```html
@@ -16,6 +16,25 @@ Minimal example:
 
 ↳ [Result](https://jsee.org/test/minimal1.html)
 
+## Installation
+
+**Browser (CDN):**
+```html
+<script src="https://cdn.jsdelivr.net/npm/@jseeio/jsee@latest/dist/jsee.runtime.js"></script>
+```
+
+**npm (for CLI or Node.js projects):**
+```bash
+npm install @jseeio/jsee
+```
+
+**CLI (generate standalone apps):**
+```bash
+npx @jseeio/jsee schema.json -o app.html
+```
+
+Run `jsee --help` for all CLI options.
+
 ## JavaScript Execution Environment
 
 JSEE is a browser-based environment for processing tasks. It creates a graphical interface, executes code in a web worker or via API, bridges all pieces together into a user-friendly web app. In some cases, JSEE does all of that automatically, without any configuration. And when the configuration is required, it's just one JSON file with an [intuitive structure](#schema).
@@ -88,11 +107,19 @@ Extra blocks can be provided for further customization
     - `async-init`
     - `py`
     - `tf`
+    - Inference note: when `code` is present (including code loaded from a `.js` URL), JSEE treats the model as `function` unless `type` is explicitly set
   - `method` (string) - If `type` is `class`, `method` defines the name of the class method to call during evaluation
   - `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
   - `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)
+  - `timeout` (number, default: `30000`) - Worker execution timeout in milliseconds. Only applies when `worker: true`. Does not apply during model initialization (loading can be slow). If exceeded, the worker is terminated with an error
+  - `imports` (array) - Per-model imports loaded before this model's code executes. Accepts URLs as strings or objects `{ url: "..." }`. Top-level `imports` are moved to the first model internally
+  - `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.
@@ -108,57 +135,48 @@ Extra blocks can be provided for further customization
     - `file` - File Input
     - `action` or `button` - Button (its `name` will be passed as a `caller` to the model)
   - `default` - Default value
-- `outputs` - Outputs definition
+  - `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
+  - `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)
+  - `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.
+  - 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
   - `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
     - `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)
 - `examples` - List of examples
-- `autorun` (boolean, default: `false`) - Defines if the script should be evaluated on each input change event
+- `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.
+- 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:
+  - `title` (string) - Page title
+  - `url` (string) - Page URL
+  - `ga` (string) - Google Analytics measurement ID (e.g. `"G-XXXXXXXXXX"`)
+  - `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.
 
+# CLI
+- `--fetch` - Fetches JSEE runtime and bundles `model`/`view`/`render` blocks plus their imports into generated HTML
+- `--runtime <auto|local|cdn|inline>` - 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
+- `--cdn` - Use CDN for models (can be string with a base URL or boolean to infer from package.json). Model urls will be prefixed with the CDN URL. This helps with deployment to static hosts (e.g. GitHub Pages).
+- `--execute` - Executes the model code on the server-side. 
+# Server-side execution
+
 # Changelog
 
-## 0.3.4
-### JSEE:
-- [x] Add `columns` parameter to the `inputs`, `outputs` blocks (making it possible to create multi-column layouts, like simple dashboards)
-- [x] Add `function` output type (for custom renderers which take a container element as an argument)
-- [x] Add `dom-to-image` library for exporting dynamic output blocks to PNG
-- [x] Support for inputs to be set with url parameters (e.g. `?input1=1&input2=2`)
-### HTML Generator:
-- [x] Add `latex` and table output in the markdown renderer
-- [x] Cache `import` scripts to avoid multiple loads when `--fetch` is used
-- [x] Infer `description` from the markdown and update html `<head>` with it
-- [x] Update `social`, `org`, `ga` blocks
-- [x] Small layout fixes
-
-## 0.3.1
-- [x] Add `download` method to jsee object
-- [x] Add `bin` folder with `cmd.js` for easier project building
-
-## 0.2.9
-- [x] Add examples
-- [x] Add imports
-- [x] Add `caller` field to the model input (can be: `run`, `autorun` or a button name)
-- [x] Add `title` field (for buttons rn)
-- [x] If `display` field is `false` the input is not shown
-- [x] If `autorun` is true, then actually autorun the model initially
-
-## 0.2.8
-- [x] Fix no input case
-
-## 0.2.7
-- [x] Show output when result is `0`
-- [x] Updated style for buttons and inputs
-
-## 0.2.6
-- [x] Tests
-- [x] Load schema from query (loader)
-- [x] Reset button appears only after data change
-- [x] Default input type (`string`)
-- [x] Directly load code when running in a window (not code to text)
-- [x] Passing code directly
+See `CHANGELOG.md`.

package/bin/jsee

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
 const gen = require('../src/cli.js')
-gen(process.argv)
+gen(process.argv.slice(2))