@jseeio/jsee 0.3.8 → 0.3.9

package/.claude/settings.local.json

@@ -3,7 +3,10 @@
     "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:*)"
     ]
   }
 }

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

@@ -30,6 +30,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

@@ -3,14 +3,29 @@
 ## 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
+## 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 +45,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 +58,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 +70,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).
@@ -88,6 +107,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 +117,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 +135,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,11 +156,23 @@ 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 <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