@field/cascade 0.4.0 → 0.5.2

package/doc/NODE_REFERENCE.md

@@ -53,6 +53,32 @@ Runs on `portable`.
 | --- | --- | --- | --- |
 | `camera` | `camera` |  |  |
 
+### `cascade.core.Feedback`
+
+Feedback — Runs its contents once per step, carrying the previous result forward.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `initial` | `any` | `null` |  |
+| `steps` | `int` | `1` |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `history` | `int` | `0` | 0…100000 |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `result` | `any` |  |  |
+| `history` | `array` |  |  |
+
 ### `cascade.core.Input`
 
 Input — Defines a public graph or subnet input
@@ -147,6 +173,25 @@ Runs on `portable`.
 | --- | --- | --- | --- |
 | `output` | `any` |  |  |
 
+### `cascade.core.Previous`
+
+Previous — The previous step's state, inside a Feedback container. The first step gets the container's initial value.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `initial` | `any` | `null` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `value` | `any` |  |  |
+| `step` | `int` |  |  |
+
 ### `cascade.core.Random`
 
 Random — Generate a deterministic unit value from an explicit seed.
@@ -250,6 +295,28 @@ Runs on `portable`.
 | --- | --- | --- | --- |
 | `output` | `any` |  |  |
 
+### `cascade.core.Time`
+
+Time — The current frame and time, as values the graph can read.
+
+Runs on `portable`.
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `frame` | `int` | `1` |  |
+| `fframe` | `float` | `1` |  |
+| `time` | `float` | `0` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `frame` | `int` |  |  |
+| `fframe` | `float` |  |  |
+| `time` | `float` |  |  |
+
 ### `cascade.geo.Circle`
 
 Circle — A closed circle, as one cubic Bezier chain or as a polygon of divisions segments.
@@ -339,6 +406,39 @@ Runs on `portable`.
 | --- | --- | --- | --- |
 | `geometry` | `geometry` |  |  |
 
+### `cascade.geo.Render`
+
+Render — Draw a scene through a camera, as a raster.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `scene` | `scene` |  |  |
+| `camera` | `camera` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `size` | `vec2i` | `[1280,720]` | 16…8192 |
+| `filename` | `string` | `"render.png"` |  |
+| `background` | `color` | `[0,0,0,0]` |  |
+| `stroke` | `color` | `[0,0,0,1]` |  |
+| `strokeWidth` | `float` | `1` | 0…200 |
+| `opacity` | `float` | `1` | 0…1 |
+| `drawPoints` | `bool` | `false` |  |
+| `pointRadius` | `float` | `1.5` | 0…50 |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `image` | `image` |  |  |
+| `asset` | `asset` |  |  |
+
 ### `cascade.geo.SvgExport`
 
 SVG Export — Write geometry as an SVG document, one group element per group.
@@ -359,6 +459,8 @@ Runs on `portable`.
 | `width` | `float` | `0` |  |
 | `height` | `float` | `0` |  |
 | `margin` | `float` | `0` |  |
+| `bounds` | `vec4` | `[0,0,0,0]` |  |
+| `background` | `color` | `[0,0,0,0]` |  |
 | `stroke` | `color` | `[0,0,0,1]` |  |
 | `strokeWidth` | `float` | `1` |  |
 | `opacity` | `float` | `1` | 0…1 |
@@ -396,6 +498,275 @@ Runs on `portable`.
 | --- | --- | --- | --- |
 | `geometry` | `geometry` |  |  |
 
+### `cascade.pop.FieldForce`
+
+POP Field Force — Pull particles along a field's gradient and around its contours. The calligraphy force.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `particles` | `geometry` |  |  |
+| `field` | `geometry` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `normal` | `float` | `0` | -100000…100000 |
+| `tangential` | `float` | `2600` | -100000…100000 |
+| `radius` | `float` | `20` | 0…10000 |
+| `level` | `float` | `0.28` | 0…1 |
+| `hold` | `float` | `5200` | 0…100000 |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `geometry` | `geometry` |  |  |
+
+### `cascade.pop.NoiseForce`
+
+POP Noise Force — Push particles along a heading read from a noise field.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `particles` | `geometry` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `amplitude` | `float` | `6` | 0…500 |
+| `frequency` | `float` | `0.3` | 0.001…10 |
+| `evolve` | `float` | `0` | -1000…1000 |
+| `timestep` | `float` | `0.041666666666666664` | 0.004166666666666667…1 |
+| `seed` | `int` | `7` | 0…999999 |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `geometry` | `geometry` |  |  |
+
+### `cascade.pop.Separate`
+
+POP Separate — Push neighbours apart within a radius.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `particles` | `geometry` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `radius` | `float` | `0.5` | 0…100 |
+| `strength` | `float` | `4` | 0…500 |
+| `timestep` | `float` | `0.041666666666666664` | 0.004166666666666667…1 |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `geometry` | `geometry` |  |  |
+
+### `cascade.pop.Simulate`
+
+POP Simulate — Re-simulate a particle system from frame zero to this frame.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `geometry` | `geometry` |  |  |
+| `frame` | `float` | `1` |  |
+| `attract` | `geometry` |  |  |
+| `field` | `geometry` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `trail_length` | `int` | `14` | 1…500 |
+| `trail_increment` | `int` | `1` | 1…32 |
+| `substeps` | `int` | `1` | 1…32 |
+| `timestep` | `float` | `0.041666666666666664` | 0.004166666666666667…1 |
+| `impulse` | `int` | `6` | 0…100000 |
+| `life` | `float` | `4` | 0…3600 |
+| `lifevar` | `float` | `0.4` | 0…1 |
+| `force` | `vec2` | `[0,0]` |  |
+| `airresist` | `float` | `0.4` | 0…20 |
+| `noise_amplitude` | `float` | `14` | 0…500 |
+| `noise_frequency` | `float` | `0.02` | 0.001…10 |
+| `noise_evolve` | `float` | `0.08` | -10…10 |
+| `field_normal` | `float` | `0` | -20000…20000 |
+| `field_tangential` | `float` | `0` | -20000…20000 |
+| `field_radius` | `float` | `24` | 0.5…2000 |
+| `field_level` | `float` | `0.35` | 0…1 |
+| `field_hold` | `float` | `0` | 0…40000 |
+| `birth_area` | `vec4` | `[0,0,0,0]` |  |
+| `birth_hue` | `vec2` | `[0,0]` | 0…1 |
+| `birth_saturation` | `float` | `0.6` | 0…1 |
+| `birth_value` | `float` | `1` | 0…1 |
+| `attract_amplitude` | `float` | `0` | 0…20000 |
+| `attract_radius` | `float` | `60` | 0…5000 |
+| `separate_radius` | `float` | `0` | 0…500 |
+| `separate_strength` | `float` | `12` | 0…500 |
+| `maxspeed` | `float` | `60` | 0…10000 |
+| `wrap` | `vec4` | `[0,0,0,0]` |  |
+| `seed` | `int` | `7` | 0…999999 |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `geometry` | `geometry` |  |  |
+| `trails` | `geometry` |  |  |
+
+### `cascade.pop.Solver`
+
+POP Solver — Advance a particle system by one timestep.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `particles` | `geometry` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `timestep_mode` | `string` | `"fixed"` |  |
+| `timestep` | `float` | `0.041666666666666664` | 0.004166666666666667…1 |
+| `maxspeed` | `float` | `0` | 0…10000 |
+| `force` | `vec2` | `[0,0]` |  |
+| `airresist` | `float` | `0` | 0…20 |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `geometry` | `geometry` |  |  |
+
+### `cascade.pop.Source`
+
+POP Source — Birth particles from a geometry's points.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `geometry` | `geometry` |  |  |
+| `particles` | `geometry` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `impulse` | `int` | `8` | 0…100000 |
+| `life` | `float` | `3` | 0…3600 |
+| `lifevar` | `float` | `0.3` | 0…1 |
+| `velocity` | `vec2` | `[0,0]` |  |
+| `seed` | `int` | `7` | 0…999999 |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `geometry` | `geometry` |  |  |
+
+### `cascade.pop.Trail`
+
+POP Trail — Build trails from a Feedback container's history.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `history` | `array` |  |  |
+| `particles` | `geometry` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `result` | `string` | `"polylines"` |  |
+| `length` | `int` | `12` | 1…100000 |
+| `increment` | `int` | `1` | 1…1000 |
+| `velocityscale` | `float` | `1` | 0…100 |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `geometry` | `geometry` |  |  |
+
+### `cascade.scene.Light`
+
+Light — A light, following Houdini's /obj/hlight. Nothing shades with lights yet — the viewport draws wireframe and points.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `translate` | `vec3` | `[0,0,5]` |  |
+| `direction` | `vec3` | `[0,0,-1]` |  |
+| `color` | `color` | `[1,1,1,1]` |  |
+| `intensity` | `float` | `1` |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `type` | `string` | `"point"` |  |
+| `coneangle` | `float` | `45` | 0…180 |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `light` | `light` |  |  |
+
+### `cascade.scene.Scene`
+
+Scene — Geometry, a camera and lights, assembled into a scene. Attach anything to the input.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `inputs` | `any` |  |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `scene` | `scene` |  |  |
+
 ## Studio node libraries
 
 Class-based nodes, available in Studio. Their parameters are declared in the
@@ -413,7 +784,7 @@ under `src/nodes/<library>/nodes/`.
 
 ### Geometry — `cascade.geo.*`
 
-**Geometry.** `cascade.geo.Rectangle` (A closed four-point polygon, counter-clockwise from bottom-left.), `cascade.geo.Circle` (A closed circle, as one cubic Bezier chain or as a polygon of divisions segments.), `cascade.geo.Transform` (Translate, rotate and scale geometry about a pivot.), `cascade.geo.Merge` (Concatenate geometries, taking the union of their attributes.), `cascade.geo.CopyToPoints` (Instance one geometry onto every point of another.), `cascade.geo.SvgExport` (Write geometry as an SVG document, one group element per group.)
+**Geometry.** `cascade.geo.Rectangle` (A closed four-point polygon, counter-clockwise from bottom-left.), `cascade.geo.Circle` (A closed circle, as one cubic Bezier chain or as a polygon of divisions segments.), `cascade.geo.Transform` (Translate, rotate and scale geometry about a pivot.), `cascade.geo.Merge` (Concatenate geometries, taking the union of their attributes.), `cascade.geo.CopyToPoints` (Instance one geometry onto every point of another.), `cascade.geo.SvgExport` (Write geometry as an SVG document, one group element per group.), `cascade.geo.Render` (Draw a scene through a camera, as a raster.)
 
 ### Image — `cascade.image.*`
 

package/doc/PROJECT_AUTHORING.md

@@ -564,12 +564,24 @@ Applications can use `createRuntime()` from `cascade/runtime` directly. Register
 
 Server and browser hosts are deliberately explicit. A graph that uses Python or shell stages belongs on the server or behind an application-defined bridge; the runtime does not silently move computation between environments.
 
-The Studio single-HTML/folder exporter is not this embedding API. It currently
+For a browser-only deployment, build a static player:
+
+```bash
+cascade build index.cascade --out web-player --asset assets/source.svg
+```
+
+The output directory must be new. Serve it over HTTP(S), open `index.html`, or
+embed `player.html` in an iframe. `embed.js` supplies same-origin playback,
+parameter and output controls. Only explicitly included files and literal typed
+asset/image references are copied; server capabilities are rejected, not proxied.
+See [Web player](WEB_PLAYER.md) for the full deployment and asset contract.
+
+The Studio single-HTML/folder exporter is separate from this player. It currently
 serializes a compatibility graph into its own small browser runtime, so it does
 not preserve every node, capability, or runtime behavior. Use it only after
-testing the exported artifact for the particular graph. For a dependable
-custom experience today, embed `cascade/runtime` in an application and provide
-the graph's declared modules and capabilities explicitly.
+testing the exported artifact for the particular graph. Prefer `cascade build`
+for definition-v1 browser graphs, or embed `cascade/runtime` directly when an
+application needs custom capabilities and presentation.
 
 ## Verify a project
 

package/doc/WEB_PLAYER.md

@@ -0,0 +1,131 @@
+# Browser player
+
+The player runs a compatible graph in a browser without Studio or a Cascade
+server. Available in Cascade 0.5+. Install `@field/cascade@latest`, or build the
+checkout when developing Cascade itself.
+
+## Build and launch
+
+From a project containing `index.cascade`:
+
+```sh
+cascade build index.cascade --out web-player
+```
+
+The output directory must not already exist. It contains `index.html`,
+`player.html`, `app.js`, `embed.js`, and any included assets. Serve that directory
+with an ordinary static HTTP server or hosting service, then open `index.html`.
+Do not open it through `file://`: browser module and asset loading requires HTTP.
+No application backend is required. WebGPU needs a supported browser/device and
+a secure context such as HTTPS or localhost.
+
+Graph definitions are inspected and compiled at build time, not executed.
+The build rejects unsupported server capabilities, server transport imports,
+Node dependencies and dynamic node modules. It does not publish or upload files.
+
+## Embed
+
+For a simple embed, including across origins:
+
+```html
+<iframe src="/artwork/player.html" title="Generative artwork"
+  style="width:100%;height:600px;border:0"></iframe>
+```
+
+For programmatic controls on the **same origin**:
+
+Give the host container an explicit height, for example
+`<div id="artwork" style="height:600px"></div>`. The iframe fills that container.
+
+```js
+import { mount } from './web-player/embed.js';
+
+const player = await mount(document.querySelector('#artwork'), {
+  frame: 1,
+  fps: 30,
+  autoplay: false,
+  output: { nodeId: 'render', port: 'image' },
+});
+
+await player.setProp('render', 'strokeWidth', 2);
+await player.seek(48);
+player.play();
+// Later, when the host view is removed:
+await player.dispose();
+```
+
+The generic `mountPlayer` export from `cascade/player` accepts the same options
+plus `url`, pointing to a built `player.html`. Each mount creates an iframe, so
+two sketches can use the same node IDs and cache filenames without sharing data.
+Programmatic cross-origin control is not provided; use the iframe directly.
+
+Mount resolves after the first successful cook and display. A failed startup
+rejects and removes the failed embed. Playback starts paused unless requested;
+runtime failures pause playback and expose their diagnostic. Frame work is
+serialized and playback coalesces requests instead of building a catch-up queue.
+
+## Controls and output
+
+`PlayerController` provides:
+
+- `play()`, `pause()`, `seek(frame)`.
+- `setInput(nodeId, name, value)` and `setProp(nodeId, name, value)`, which await
+  the resulting cook.
+- `selectOutput(nodeId, port)` and `getOutput(nodeId, port)`.
+- `downloadOutput()`, returning the selected output as a `Blob`.
+- `resize(width, height)` for the display, without changing authored resolution.
+- `subscribe(listener)` for `frame`, `playing` and `error` events; returns an
+  unsubscribe function.
+- `dispose()`, which stops work and releases runtime, GPU, image and iframe resources.
+
+Output selection defaults to the last renderable output in the run result;
+select a node and port explicitly when a graph has several deliverables. Images/SVG and
+geometry/scenes are displayable; scene rendering currently uses the shared CPU
+wireframe/point renderer, not a shaded GPU renderer. Camera conventions match
+Studio and offline rendering. For durable image retention, obtain a Blob:
+image references returned by `getOutput` are current-frame references, not an
+archive of every rendered frame.
+
+## Assets and resource limits
+
+Literal typed image/asset references in graph inputs or props are included
+automatically. Files whose paths are computed in node code must be listed:
+
+```sh
+cascade build index.cascade --out web-player --asset assets/photo.png
+```
+
+Repeat `--asset` for additional files. Only those files are copied, preserving
+project-relative paths below the output's `assets/` directory. Directories,
+hidden files, path traversal and symlinks escaping the project are rejected.
+The builder never copies the entire project, credentials, Python environments
+or cache directories. Review authored graph values and custom code before
+publishing: project modules are trusted code, not a sandbox.
+
+The player supplies one asset store for declared `assets` capabilities and
+existing `cascade/io` imports. Reads resolve packaged files; writes stay in
+memory and create immutable references. `mediaUrl` resolves through that store,
+not Studio's `/api/media`. Server-only preview transformations are unsupported
+and fail explicitly rather than returning different pixels silently.
+
+Generated encoded assets are limited to 256 MiB and 4,096 entries per iframe.
+After a cook, assets no longer reachable from graph outputs, authored/controller
+values or active display leases are released. Feedback history keeps referenced
+images alive. Exceeding the live budget fails with a diagnostic; live images
+are not silently replaced or evicted. Disposal revokes all generated URLs.
+
+## Host limits
+
+| Graph requirement | Static player |
+| --- | --- |
+| Definition-v1 CPU nodes, core/geometry/POP/scene built-ins | Supported |
+| Canvas drawing and compatible `cascade/io` helpers | Supported |
+| Declared `assets` | Packaged inputs and in-memory generated outputs |
+| Declared `gpu` | Browser WebGPU, if available; no Dawn in the browser |
+| Python, shell, filesystem, Studio/server transport | Rejected |
+| Dynamic modules or mixed execution styles | Rejected |
+| Project Studio panels | Not included |
+
+Separate heavy preprocessing from the live graph when possible: export its
+result as an explicit asset, then build the browser-compatible graph around
+that input. The player does not emulate server operations or carry credentials.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@field/cascade",
-  "version": "0.4.0",
+  "version": "0.5.2",
   "description": "Visual programming for generative art",
   "license": "MIT",
   "author": "FIELD.IO <marcus@field.io>",
@@ -8,7 +8,7 @@
     "type": "git",
     "url": "git+https://github.com/marcuswendt/cascade.git"
   },
-  "homepage": "https://github.com/marcuswendt/cascade#readme",
+  "homepage": "https://cascade.field.io",
   "keywords": [
     "node-graph",
     "visual-programming",
@@ -34,6 +34,7 @@
     "doc/NODE_REFERENCE.md",
     "doc/PROJECT_AUTHORING.md",
     "doc/HEADLESS_GPU.md",
+    "doc/WEB_PLAYER.md",
     "README.md",
     "LICENSE"
   ],
@@ -77,6 +78,14 @@
       "types": "./dist/runtime/camera/index.d.ts",
       "default": "./dist/runtime/camera/index.js"
     },
+    "./runtime/render": {
+      "types": "./dist/runtime/geometry/render.d.ts",
+      "default": "./dist/runtime/geometry/render.js"
+    },
+    "./runtime/scene": {
+      "types": "./dist/runtime/scene/index.d.ts",
+      "default": "./dist/runtime/scene/index.js"
+    },
     "./runtime/definition/extract": {
       "types": "./dist/runtime/definition/extract.d.ts",
       "default": "./dist/runtime/definition/extract.js"
@@ -103,6 +112,10 @@
     },
     "./studio/panel": {
       "types": "./dist/studio/panel.d.ts"
+    },
+    "./player": {
+      "types": "./dist/player/embed.d.ts",
+      "default": "./dist/player/embed.js"
     }
   },
   "scripts": {
@@ -122,6 +135,7 @@
     "test:run": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:package": "node scripts/smoke-package.mjs",
+    "test:player": "node scripts/smoke-player.mjs",
     "build:node-reference": "tsx scripts/build-node-reference.mjs"
   },
   "dependencies": {

package/dist/assets/geo-DhyFdBXX.js

@@ -1 +0,0 @@
-import{b as e,f as t,s as n,x as r}from"./index-CC6YQw2n.js";r(n,{assets:e});export{t as geoLibrary};