@field/cascade 0.12.0 → 0.13.0

package/dist/runtime/definition/architecture.js

@@ -18,6 +18,15 @@ export function validateNodeModuleArchitecture(source, fileName, ts) {
     const diagnostics = [];
     const exportsDefinition = file.statements.some((statement) => ts.isVariableStatement(statement) && isDefinition(statement));
     for (const statement of file.statements) {
+        if (ts.isVariableStatement(statement) &&
+            !isDefinition(statement) &&
+            !supersededByDefinition(statement) &&
+            isPureConstant(statement)) {
+            // A helper: `const TAU = Math.PI * 2`, `const PALETTE = [...] as const`,
+            // `const lerp = (a, b, t) => a + (b - a) * t`. Immutable, so it cannot
+            // carry anything from one cook to the next.
+            continue;
+        }
         if (ts.isVariableStatement(statement) && !isDefinition(statement)) {
             // `icon` and `runsOn` get their own sentence, because the general
             // message sends you looking for the wrong thing. A dynamic node declares
@@ -97,6 +106,86 @@ export function validateNodeModuleArchitecture(source, fileName, ts) {
             ? declaration.name.text
             : null;
     }
+    /**
+     * Whether a module-level declaration is an immutable helper rather than
+     * state: `const` only, and every initializer pure (see `isPure`).
+     */
+    function isPureConstant(statement) {
+        if (!(statement.declarationList.flags & ts.NodeFlags.Const))
+            return false;
+        return statement.declarationList.declarations.every((declaration) => ts.isIdentifier(declaration.name) &&
+            declaration.initializer !== undefined &&
+            isPure(declaration.initializer, false));
+    }
+    /**
+     * An expression that creates no mutable value: literals, arithmetic and
+     * logic over them, references and property reads (`Math.PI`), functions
+     * (they close over nothing mutable, since nothing at module level is), and
+     * array/object literals only when frozen — `as const` or `Object.freeze(…)`.
+     * Calls, `new`, regular expressions (`lastIndex` is state) and a bare
+     * array or object are not.
+     */
+    function isPure(node, frozen) {
+        if (ts.isNumericLiteral(node) || ts.isStringLiteral(node) || ts.isBigIntLiteral(node) ||
+            ts.isNoSubstitutionTemplateLiteral(node) ||
+            node.kind === ts.SyntaxKind.TrueKeyword || node.kind === ts.SyntaxKind.FalseKeyword ||
+            node.kind === ts.SyntaxKind.NullKeyword)
+            return true;
+        if (ts.isIdentifier(node))
+            return true;
+        if (ts.isArrowFunction(node) || ts.isFunctionExpression(node))
+            return true;
+        if (ts.isParenthesizedExpression(node))
+            return isPure(node.expression, frozen);
+        if (ts.isAsExpression(node))
+            return isPure(node.expression, frozen || isConstAssertion(node.type));
+        if (ts.isSatisfiesExpression(node) || ts.isNonNullExpression(node) || ts.isTypeAssertionExpression(node))
+            return isPure(node.expression, frozen);
+        if (ts.isPrefixUnaryExpression(node))
+            return node.operator !== ts.SyntaxKind.PlusPlusToken &&
+                node.operator !== ts.SyntaxKind.MinusMinusToken &&
+                isPure(node.operand, false);
+        if (ts.isBinaryExpression(node))
+            return !isAssignment(node.operatorToken.kind) &&
+                isPure(node.left, false) && isPure(node.right, false);
+        if (ts.isConditionalExpression(node))
+            return isPure(node.condition, false) && isPure(node.whenTrue, frozen) && isPure(node.whenFalse, frozen);
+        if (ts.isTemplateExpression(node))
+            return node.templateSpans.every((span) => isPure(span.expression, false));
+        if (ts.isPropertyAccessExpression(node))
+            return isPure(node.expression, false);
+        if (ts.isElementAccessExpression(node))
+            return isPure(node.expression, false) && isPure(node.argumentExpression, false);
+        if (ts.isArrayLiteralExpression(node))
+            return frozen && node.elements.every((element) => !ts.isSpreadElement(element) && isPure(element, true));
+        if (ts.isObjectLiteralExpression(node))
+            return frozen && node.properties.every((property) => ts.isPropertyAssignment(property)
+                ? !ts.isComputedPropertyName(property.name) && isPure(property.initializer, true)
+                : ts.isShorthandPropertyAssignment(property));
+        if (ts.isCallExpression(node) &&
+            ts.isPropertyAccessExpression(node.expression) &&
+            ts.isIdentifier(node.expression.expression) &&
+            node.expression.expression.text === "Object" &&
+            node.expression.name.text === "freeze" &&
+            node.arguments.length === 1) {
+            const [argument] = node.arguments;
+            // Object.freeze is shallow: a nested array or object needs its own freeze.
+            return ts.isArrayLiteralExpression(argument)
+                ? argument.elements.every((element) => !ts.isSpreadElement(element) && isPure(element, false))
+                : ts.isObjectLiteralExpression(argument)
+                    ? argument.properties.every((property) => ts.isPropertyAssignment(property) &&
+                        !ts.isComputedPropertyName(property.name) &&
+                        isPure(property.initializer, false))
+                    : false;
+        }
+        return false;
+    }
+    function isConstAssertion(type) {
+        return ts.isTypeReferenceNode(type) && ts.isIdentifier(type.typeName) && type.typeName.text === "const";
+    }
+    function isAssignment(kind) {
+        return kind >= ts.SyntaxKind.FirstAssignment && kind <= ts.SyntaxKind.LastAssignment;
+    }
     function isDefinition(statement) {
         return Boolean(statement.declarationList.flags & ts.NodeFlags.Const) &&
             Boolean(statement.modifiers?.some((item) => item.kind === ts.SyntaxKind.ExportKeyword)) &&

package/doc/PROJECT_AUTHORING.md

@@ -196,6 +196,65 @@ The initiating node ID is captured as `api.sourceNodeId`; `setParam` uses the sa
 }
 ```
 
+### Reading another project's data
+
+File reads stay inside the project: a `..` path or a symlink out of it is
+refused. To read another folder, declare it as a read-only root:
+
+```json
+{
+  "reads": ["../other-sketch/data"]
+}
+```
+
+Each entry is a folder relative to the project (absolute and `~` paths are
+refused). The `files` capability's `read`, `list` and `stat`, `cascade/io`'s
+loaders and Studio's media route may then resolve into it, whether the path
+reaches it with `..` (`../other-sketch/data/points.csv`) or through a symlink in
+the project (`data -> ../other-sketch/data`). What counts is where the file
+really is, so a symlink inside the read root that points elsewhere is still
+refused. Writes into a read root are always refused. The declaration is the
+project's, in `cascade.json`, never the graph's; Studio's Project Settings
+cannot change it.
+
+### Named exports and a keyed cache
+
+A node with the `files` capability (`runsOn: 'server'`) writes under the name
+it gives, never renamed by a content hash, but only into `.cascade-cache/`. To
+write a stably named export, such as a ladder's chosen variant, declare the
+folder:
+
+```json
+{
+  "writes": ["renders"]
+}
+```
+
+```ts
+await context.capabilities.files.write('renders/cloud-final.png', bytes, { signal: context.signal });
+```
+
+Each entry is a folder inside the project; `..`, absolute paths, the project
+root, `nodes`, `.git` and `.cascade` are refused, and a symlink out of a write
+folder is refused like any other. `cascade/io`'s `write` and `saveImage` keep
+content-hashed names in `.cascade-cache/`: they are intermediates between
+nodes, and the hash is what stops a fixed name handing on the wrong pixels.
+
+For a cache a node must find again on the next run, by a key it derives from
+everything the bytes depend on, use `files.cache`:
+
+```ts
+const { files } = context.capabilities;
+const key = `stage/${hashOf(inputs, props)}`;
+const hit = await files.cache.get(key, { signal: context.signal });   // Uint8Array | null
+if (!hit) await files.cache.put(key, computed, { signal: context.signal });
+```
+
+Entries live in `.cascade-cache/keyed/<key>`; keys are letters, digits, `.`,
+`_` and `-` in `/`-separated parts, each starting with a letter or digit.
+Writes are atomic, so parallel render workers can share one cache. The cache
+rule above still holds: it may only memoize work from wired inputs and props.
+
 Read settings without giving nodes write access:
 
 ```ts
@@ -241,7 +300,7 @@ Clean graph design is clean code design:
 - **One responsibility per node**, named for what it does (`layout_rings`, not `main`).
 - **Data flows through typed ports**, never through module-level state or files one node writes and another reads behind the graph's back.
 - **What varies is a parameter**; seeds, counts and colours are on the node, not constants in the code.
-- **Shared helpers go in `lib/` or the kit** (`KIT.md`); the node is the unit you compose and reuse.
+- **Shared helpers go in `lib/` or the kit** (`KIT.md`); the node is the unit you compose and reuse. A helper only this node uses may stay in its file: function declarations and immutable `const`s (`const TAU = Math.PI * 2`, `const PALETTE = [...] as const`, `const lerp = (a, b, t) => …`) pass `cascade check`. Anything that can change between cooks (`let`, `new Map()`, a bare array or object, a regex, a call) is module state and is refused (`architecture/module-state`).
 
 Split a node when it does two of load, generate, style, render and export, or when its `execute` grows past about 150 lines. `cascade check` warns on both (`shape/long-execute`, `shape/mixed-jobs`); the warnings are advice and never fail the check. Drawing with noise and colour is one job's worth of calls, so it only flags a module doing four of the five, or loading and exporting in the same node.
 

package/doc/WEB_PLAYER.md

@@ -54,6 +54,12 @@ player.play();
 await player.dispose();
 ```
 
+For a neutral preview page, `chrome: false` hides the player's dark frame, Play
+button and frame field, leaving the output alone on a transparent page; the
+controller still plays, seeks and reports errors. The plain-iframe form is
+`player.html?chrome=0`. The other options have URL forms too: `frame`, `fps`,
+`autoplay=1`, `outputNode` with `outputPort`.
+
 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.
@@ -70,7 +76,9 @@ serialized and playback coalesces requests instead of building a catch-up queue.
 
 - `play()`, `pause()`, `seek(frame)`.
 - `setInput(nodeId, name, value)` and `setProp(nodeId, name, value)`, which await
-  the resulting cook.
+  the resulting cook. Every cook re-runs only the nodes whose inputs or props
+  changed and everything downstream of them; an unchanged upstream node keeps
+  its outputs (`run({ reuse: "strict" })`).
 - `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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@field/cascade",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Visual programming for generative art",
   "license": "MIT",
   "author": "FIELD.IO <marcus@field.io>",