@jseeio/jsee 0.3.8 → 0.4.0

package/.claude/settings.local.json

@@ -3,7 +3,11 @@
     "allow": [
       "Bash(npm run test:basic:*)",
       "Bash(npm run build-dev:*)",
-      "Bash(npm run test:unit:*)"
+      "Bash(npm run test:unit:*)",
+      "Bash(find:*)",
+      "Bash(npx eslint:*)",
+      "Bash(npm run test:python:*)",
+      "Bash(npm run build:*)"
     ]
   }
 }

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

@@ -13,14 +13,41 @@ Use **2-space indentation** and **semicolon-free** syntax. Use **single quotes**
 
 ## Quick start
 
+```bash
+npm install          # install dependencies
+npm run build-dev    # fast dev build (no tests, no minification)
+npm run build        # production build + full test suite
+npm run test:unit    # unit tests only (fast, no browser)
+npm run test:basic   # E2E tests (auto-starts http-server on 8484)
+```
 
 ## Repo map
 
+```
+src/
+  main.js        # JSEE class — schema parsing, model/worker init, run loop
+  app.js         # Vue 3 app factory — creates reactive GUI from schema inputs/outputs
+  worker.js      # Web Worker entry — receives model config, runs importScripts + model code
+  utils.js       # Shared helpers — URL resolution, script loading, serialization, validation
+  cli.js         # CLI (`npx jsee`) — HTML generation, --fetch bundling, dev server
+  overlay.js     # Loading/progress overlay component
+  constants.js   # Shared defaults (container selector, timeouts, chunk sizes)
+templates/       # Vue SFC templates (bulma-app, bulma-input, bulma-output, file-picker)
+test/
+  unit/          # Jest unit tests (no browser): utils.test.js, cli-fetch.test.js
+  test-basic.test.js   # Puppeteer E2E tests against built dist/
+  test-python.test.js  # Pyodide integration test
+  fixtures/      # Test fixtures (lodash-like.js, upload-sample.csv)
+dist/            # Build output: jsee.js (dev), jsee.runtime.js (production)
+apps/            # Example apps (hashr, detect, qrcode, etc.)
+webpack.config.js  # Two build targets: full (jsee.js) and runtime (jsee.runtime.js)
+```
+
 
 ## 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)
+- Run E2E tests: `npm run test:basic` (auto-starts http-server on port 8484)
 - Add/adjust unit tests for core logic in `test/unit/`
 
 ## Constraints
@@ -30,6 +57,7 @@ Use **2-space indentation** and **semicolon-free** syntax. Use **single quotes**
 - 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)

package/CHANGELOG.md

@@ -1,16 +1,33 @@
 # Changelog
 
-## Unreleased
+## 0.4.0
 ### Bug fixes:
+- Fix relative import URLs (e.g. `dist/core.js`) resolving against CDN instead of page URL — now resolves against `window.location.href` so blob workers can load them correctly
 - 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 CSS-aware imports: `.css` entries in `imports` arrays are injected as `<link rel="stylesheet">` on the main thread and skipped in workers
+- Add CLI `--runtime` to control runtime source: supports `auto|local|cdn|inline` modes plus custom URL/path values (e.g. `./node_modules/@jseeio/jsee/dist/jsee.js`)
+- 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
+## 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
@@ -30,7 +47,7 @@
 - Add unit tests for utils.js: `isObject`, `sanitizeName`, `getUrl`, `delay`, `debounce`, `getName`, `getModelFuncJS`, `getModelFuncAPI`, `validateSchema`
 - Add `npm run test:unit` script
 
-## 0.3.4
+## 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)
@@ -43,11 +60,11 @@
 - [x] Update `social`, `org`, `ga` blocks
 - [x] Small layout fixes
 
-## 0.3.1
+## 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
+## 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)
@@ -55,14 +72,14 @@
 - [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
+## 0.2.8 (2021-12-29)
 - [x] Fix no input case
 
-## 0.2.7
+## 0.2.7 (2021-12-29)
 - [x] Show output when result is `0`
 - [x] Updated style for buttons and inputs
 
-## 0.2.6
+## 0.2.6 (2021-12-27)
 - [x] Tests
 - [x] Load schema from query (loader)
 - [x] Reset button appears only after data change

package/README.md

@@ -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).
@@ -54,12 +73,13 @@ Extra blocks can be provided for further customization
 
 - `render` - visualization part (optional). Defines custom rendering code.
 - `design` - overall appearance (optional). Defines how the app looks overwriting defaults.
-- `imports` - a list of urls (optional). Defines a list of scripts to load before the model is initialized.
+- `imports` - a list of urls (optional). Defines a list of scripts and stylesheets to load before the model is initialized. CSS files (`.css` extension) are injected as `<link rel="stylesheet">` in `<head>`, JS files are loaded as scripts. Relative paths are resolved against the page URL.
 
   ```json
   "imports": [
     "https://cdn.jsdelivr.net/npm/@tensorflow/tfjs",
-    "https://cdn.jsdelivr.net/pyodide/v0.17.0/full/pyodide.js"
+    "https://cdn.jsdelivr.net/pyodide/v0.17.0/full/pyodide.js",
+    "styles/app.css"
   ]
   ```
 
@@ -88,6 +108,7 @@ 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}`
@@ -97,6 +118,9 @@ Extra blocks can be provided for further customization
     - `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.
@@ -112,9 +136,13 @@ 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
+  - `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.
-- `outputs` - Outputs definition
+  - `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)
@@ -129,15 +157,35 @@ Extra blocks can be provided for further customization
 - `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 code, models and their imports and generates a bundled HTML file
+- `--fetch` - Fetches JSEE runtime and bundles `model`/`view`/`render` blocks plus their imports into generated HTML
+- `--runtime <mode|path|url>` - 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` - 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. 
+- `--execute` - Executes the model code on the server-side
+
 # Server-side execution
 
+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.
+
+```bash
+jsee schema.json -e -p 3000
+```
+
 # Changelog
 
 See `CHANGELOG.md`.