@jseeio/jsee 0.3.7 → 0.3.8

package/.claude/settings.local.json

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

package/AGENTS.md

@@ -0,0 +1,37 @@
+# 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
+
+## 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,71 @@
+# 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
+### 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
+
+## 0.3.8
+### 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
+### 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

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
@@ -93,6 +93,10 @@ Extra blocks can be provided for further customization
     - `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)
 - `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 +112,32 @@ 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
+  - `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.
 - `outputs` - Outputs definition
   - `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 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 code, models and their imports and generates a bundled HTML file
+- `--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))