@field/cascade 0.11.0 → 0.13.0

package/dist/runtime/builtins/image/simplex.js

@@ -0,0 +1,92 @@
+/**
+ * 2D simplex noise: `createNoise2D` and `buildPermutationTable` from
+ * simplex-noise 4.0.3 by Jonas Wagner (MIT), copied rather than depended on.
+ *
+ * The class `Noise` node loaded simplex-noise@latest from esm.sh at cook time,
+ * so it needed a network and could not run headless. The runtime depends on
+ * contracts alone, so the two functions it used live here, unchanged, and a
+ * seeded noise image is the same pixels it always was.
+ *
+ * Copyright (c) 2024 Jonas Wagner. Permission is hereby granted, free of
+ * charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without
+ * restriction, including without limitation the rights to use, copy, modify,
+ * merge, publish, distribute, sublicense, and/or sell copies of the Software,
+ * and to permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions: The above copyright notice and this permission
+ * notice shall be included in all copies or substantial portions of the
+ * Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.
+ */
+const SQRT3 = Math.sqrt(3.0);
+const F2 = 0.5 * (SQRT3 - 1.0);
+const G2 = (3.0 - SQRT3) / 6.0;
+const fastFloor = (x) => Math.floor(x) | 0;
+const grad2 = new Float64Array([1, 1, -1, 1, 1, -1, -1, -1, 1, 0, -1, 0, 1, 0, -1, 0, 0, 1, 0, -1, 0, 1, 0, -1]);
+function buildPermutationTable(random) {
+    const tableSize = 512;
+    const p = new Uint8Array(tableSize);
+    for (let i = 0; i < tableSize / 2; i++)
+        p[i] = i;
+    for (let i = 0; i < tableSize / 2 - 1; i++) {
+        const r = i + ~~(random() * (256 - i));
+        const aux = p[i];
+        p[i] = p[r];
+        p[r] = aux;
+    }
+    for (let i = 256; i < tableSize; i++)
+        p[i] = p[i - 256];
+    return p;
+}
+export function createNoise2D(random) {
+    const perm = buildPermutationTable(random);
+    const permGrad2x = new Float64Array(perm).map((v) => grad2[(v % 12) * 2]);
+    const permGrad2y = new Float64Array(perm).map((v) => grad2[(v % 12) * 2 + 1]);
+    return function noise2D(x, y) {
+        let n0 = 0;
+        let n1 = 0;
+        let n2 = 0;
+        const s = (x + y) * F2;
+        const i = fastFloor(x + s);
+        const j = fastFloor(y + s);
+        const t = (i + j) * G2;
+        const X0 = i - t;
+        const Y0 = j - t;
+        const x0 = x - X0;
+        const y0 = y - Y0;
+        let i1, j1;
+        if (x0 > y0) {
+            i1 = 1;
+            j1 = 0;
+        }
+        else {
+            i1 = 0;
+            j1 = 1;
+        }
+        const x1 = x0 - i1 + G2;
+        const y1 = y0 - j1 + G2;
+        const x2 = x0 - 1.0 + 2.0 * G2;
+        const y2 = y0 - 1.0 + 2.0 * G2;
+        const ii = i & 255;
+        const jj = j & 255;
+        let t0 = 0.5 - x0 * x0 - y0 * y0;
+        if (t0 >= 0) {
+            const gi0 = ii + perm[jj];
+            t0 *= t0;
+            n0 = t0 * t0 * (permGrad2x[gi0] * x0 + permGrad2y[gi0] * y0);
+        }
+        let t1 = 0.5 - x1 * x1 - y1 * y1;
+        if (t1 >= 0) {
+            const gi1 = ii + i1 + perm[jj + j1];
+            t1 *= t1;
+            n1 = t1 * t1 * (permGrad2x[gi1] * x1 + permGrad2y[gi1] * y1);
+        }
+        let t2 = 0.5 - x2 * x2 - y2 * y2;
+        if (t2 >= 0) {
+            const gi2 = ii + 1 + perm[jj + 1];
+            t2 *= t2;
+            n2 = t2 * t2 * (permGrad2x[gi2] * x2 + permGrad2y[gi2] * y2);
+        }
+        return 70.0 * (n0 + n1 + n2);
+    };
+}
+//# sourceMappingURL=simplex.js.map

package/dist/runtime/builtins/image/text.d.ts

@@ -0,0 +1,4 @@
+import type { NodeExecutionContext } from "@field/cascade/contracts";
+import type { textDefinition } from "./definitions.js";
+export declare function executeText(context: NodeExecutionContext<typeof textDefinition>): Promise<void>;
+//# sourceMappingURL=text.d.ts.map

package/dist/runtime/builtins/image/text.js

@@ -0,0 +1,141 @@
+import { colorToCss, normalizeColor, readPixelsFromCanvas, surface, writePixels } from "./io.js";
+/**
+ * `cascade.image.Text`: lines of text on a canvas, aligned to an anchor, with
+ * tracking, rotation and opacity.
+ *
+ * Fonts follow `cascade/image`'s rules. `font` is a CSS family list and draws
+ * with whatever faces the realm has (the page's or worker's in a browser,
+ * Skia's system fonts headless), so the same family only matches across hosts
+ * when both have the same face. A project font file (`.otf`, `.ttf`, `.woff`,
+ * `.woff2`) is read through `assets` and registered with the realm, which
+ * makes it match everywhere; a file that is not there falls back to
+ * `sans-serif` rather than failing, since a licensed face an export does not
+ * ship should still draw.
+ */
+const FONT_FILE = /\.(otf|ttf|woff2?)$/i;
+const HOST_KEY = "__cascadeImageHost";
+// One registration per realm and font file contents; see `registerFont` in
+// cascade/image, which this mirrors for a runtime that cannot import it.
+const registered = new Set();
+function fingerprint(bytes) {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < bytes.length; index += 1) {
+        hash ^= bytes[index];
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return `${bytes.length}-${(hash >>> 0).toString(16)}`;
+}
+/** The family to draw with: `font` itself, or a registered face for a font file. */
+async function fontFamily(context, font) {
+    const path = font.trim();
+    if (!FONT_FILE.test(path))
+        return font;
+    let bytes;
+    try {
+        const assets = context.capabilities.assets;
+        if (!assets)
+            throw new Error("no assets");
+        bytes = await assets.read({ path }, { signal: context.signal });
+    }
+    catch {
+        return "sans-serif";
+    }
+    const family = `cascade-font-${fingerprint(bytes)}`;
+    const globals = globalThis;
+    const host = globals[HOST_KEY];
+    const fonts = host ? null : globals.fonts ?? globals.document?.fonts;
+    const key = `${host ? `headless:${host.renderer}` : "browser"}:${family}`;
+    if (registered.has(key))
+        return family;
+    if (host && typeof host.registerFont === "function") {
+        await host.registerFont(family, bytes, {});
+    }
+    else if (typeof globals.FontFace === "function" && fonts) {
+        const face = new globals.FontFace(family, bytes.slice().buffer);
+        fonts.add(await face.load());
+    }
+    else {
+        return "sans-serif";
+    }
+    registered.add(key);
+    return family;
+}
+export async function executeText(context) {
+    const { props } = context;
+    const [width, height] = [props.resolution[0], props.resolution[1]];
+    const color = normalizeColor(props.color);
+    const background = normalizeColor(props.backgroundColor);
+    const [offsetX, offsetY] = props.offset;
+    const { fontSize, alignH, alignV, rotation, letterSpacing } = props;
+    const family = await fontFamily(context, props.font);
+    const { canvas, context: ctx } = surface(width, height);
+    if (background.a > 0) {
+        ctx.fillStyle = colorToCss(background);
+        ctx.fillRect(0, 0, width, height);
+    }
+    else {
+        ctx.clearRect(0, 0, width, height);
+    }
+    ctx.save();
+    ctx.globalAlpha = props.opacity;
+    ctx.font = `${props.fontStyle} ${props.fontWeight} ${fontSize}px ${family}`;
+    ctx.fillStyle = colorToCss(color);
+    const lines = props.text.split("\n");
+    const lineHeightPx = fontSize * props.lineHeight;
+    const totalTextHeight = lines.length * lineHeightPx;
+    let anchorX;
+    let anchorY;
+    switch (alignH) {
+        case "left":
+            ctx.textAlign = "left";
+            anchorX = 0;
+            break;
+        case "right":
+            ctx.textAlign = "right";
+            anchorX = width;
+            break;
+        default:
+            ctx.textAlign = "center";
+            anchorX = width / 2;
+    }
+    switch (alignV) {
+        case "top":
+            anchorY = fontSize;
+            break;
+        case "bottom":
+            anchorY = height - totalTextHeight + fontSize;
+            break;
+        default:
+            anchorY = (height - totalTextHeight) / 2 + fontSize;
+    }
+    anchorX += offsetX;
+    anchorY += offsetY;
+    if (rotation !== 0) {
+        const pivotY = anchorY - fontSize / 2 + totalTextHeight / 2;
+        ctx.translate(anchorX, pivotY);
+        ctx.rotate((rotation * Math.PI) / 180);
+        ctx.translate(-anchorX, -pivotY);
+    }
+    if (letterSpacing !== 0) {
+        // Tracking: one glyph at a time.
+        ctx.textAlign = "left";
+        lines.forEach((line, index) => {
+            const y = anchorY + index * lineHeightPx;
+            let lineWidth = 0;
+            for (const char of line)
+                lineWidth += ctx.measureText(char).width + letterSpacing;
+            lineWidth -= letterSpacing;
+            let x = alignH === "left" ? anchorX : alignH === "right" ? anchorX - lineWidth : anchorX - lineWidth / 2;
+            for (const char of line) {
+                ctx.fillText(char, x, y);
+                x += ctx.measureText(char).width + letterSpacing;
+            }
+        });
+    }
+    else {
+        lines.forEach((line, index) => ctx.fillText(line, anchorX, anchorY + index * lineHeightPx));
+    }
+    ctx.restore();
+    context.outputs.image.set(await writePixels(context, readPixelsFromCanvas(canvas)));
+}
+//# sourceMappingURL=text.js.map

package/dist/runtime/builtins/index.d.ts

@@ -6,6 +6,9 @@ import type { DefinitionNodeRegistration } from "../types.js";
  * set — which speaks the same `geometry` type as `geo`, so any of its outputs
  * fits any geometry node's input. `cascade.scene.*` is the assembly: geometry
  * plus a viewpoint plus lights, which is what the Viewer's 3D mode renders.
+ * `cascade.image.*` makes and filters images, and `cascade.assert.*` fails a
+ * run whose result is wrong. Those two load their bodies lazily: this list is
+ * in Studio's first-paint bundle.
  */
 export declare const builtinNodeRegistrations: readonly DefinitionNodeRegistration[];
 export declare function builtinNodeRegistration(moduleId: string): DefinitionNodeRegistration | undefined;

package/dist/runtime/builtins/index.js

@@ -1,5 +1,7 @@
+import { assertNodeRegistrations } from "./assert/index.js";
 import { coreNodeRegistrations } from "./core/index.js";
 import { geoNodeRegistrations } from "./geo/index.js";
+import { imageNodeRegistrations } from "./image/index.js";
 import { mathNodeRegistrations } from "./math/index.js";
 import { popNodeRegistrations } from "./pop/index.js";
 import { sceneNodeRegistrations } from "./scene/index.js";
@@ -10,6 +12,9 @@ import { sceneNodeRegistrations } from "./scene/index.js";
  * set — which speaks the same `geometry` type as `geo`, so any of its outputs
  * fits any geometry node's input. `cascade.scene.*` is the assembly: geometry
  * plus a viewpoint plus lights, which is what the Viewer's 3D mode renders.
+ * `cascade.image.*` makes and filters images, and `cascade.assert.*` fails a
+ * run whose result is wrong. Those two load their bodies lazily: this list is
+ * in Studio's first-paint bundle.
  */
 export const builtinNodeRegistrations = Object.freeze([
     ...coreNodeRegistrations,
@@ -17,6 +22,8 @@ export const builtinNodeRegistrations = Object.freeze([
     ...mathNodeRegistrations,
     ...popNodeRegistrations,
     ...sceneNodeRegistrations,
+    ...imageNodeRegistrations,
+    ...assertNodeRegistrations,
 ]);
 const registrationsById = new Map(builtinNodeRegistrations.map((registration) => [
     registration.moduleId,

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/dist/runtime/gpu.d.ts

@@ -28,6 +28,31 @@ export interface GpuHost extends GpuCapability {
 }
 export declare function isGpuHost(value: unknown): value is GpuHost;
 export declare function createGpuHost(options: GpuHostOptions): GpuHost;
+interface LimitedAdapter {
+    readonly limits: unknown;
+    requestDevice(descriptor?: {
+        requiredLimits?: Record<string, number>;
+    }): Promise<GpuCapability["device"]>;
+}
+/**
+ * The host's one device, asked for with everything the adapter allows.
+ *
+ * A bare `requestDevice()` gets WebGPU's defaults (128 MiB per storage binding,
+ * 256 invocations, 16 KiB workgroup storage, 8 storage buffers per stage)
+ * whatever the hardware is, and the device is shared, so a node cannot ask for
+ * more later. Brand + Design chunked a ribbon into four accumulator buffers on
+ * an M3 Max for that reason (3 Nov 2026). Should an adapter refuse its own
+ * ceiling, the defaults are better than no device; a node that needs more
+ * says so with `gpuLimits` and gets {@link gpuLimitShortfall}'s message.
+ */
+export declare function requestDeviceWithAdapterLimits(adapter: LimitedAdapter): Promise<GpuCapability["device"]>;
+/**
+ * What a node's declared `gpuLimits` asks for that this device does not give,
+ * as one sentence, or null when it all fits. `max*` limits must reach the
+ * value; `min*Alignment` limits must be at most it (smaller is better there).
+ */
+export declare function gpuLimitShortfall(label: string, required: Readonly<Record<string, number>> | undefined, gpu: Pick<GpuCapability, "limits" | "adapterInfo">): string | null;
 /** Getter-backed supported-limits objects cannot be normalized with spread. */
 export declare function readGpuLimits(source: unknown): Record<string, number>;
+export {};
 //# sourceMappingURL=gpu.d.ts.map

package/dist/runtime/gpu.js

@@ -196,6 +196,46 @@ export function createGpuHost(options) {
     }
     return host;
 }
+/**
+ * The host's one device, asked for with everything the adapter allows.
+ *
+ * A bare `requestDevice()` gets WebGPU's defaults (128 MiB per storage binding,
+ * 256 invocations, 16 KiB workgroup storage, 8 storage buffers per stage)
+ * whatever the hardware is, and the device is shared, so a node cannot ask for
+ * more later. Brand + Design chunked a ribbon into four accumulator buffers on
+ * an M3 Max for that reason (3 Nov 2026). Should an adapter refuse its own
+ * ceiling, the defaults are better than no device; a node that needs more
+ * says so with `gpuLimits` and gets {@link gpuLimitShortfall}'s message.
+ */
+export async function requestDeviceWithAdapterLimits(adapter) {
+    const requiredLimits = readGpuLimits(adapter.limits);
+    try {
+        return await adapter.requestDevice({ requiredLimits });
+    }
+    catch {
+        return adapter.requestDevice();
+    }
+}
+/**
+ * What a node's declared `gpuLimits` asks for that this device does not give,
+ * as one sentence, or null when it all fits. `max*` limits must reach the
+ * value; `min*Alignment` limits must be at most it (smaller is better there).
+ */
+export function gpuLimitShortfall(label, required, gpu) {
+    if (!required)
+        return null;
+    const short = [];
+    for (const [name, wanted] of Object.entries(required)) {
+        const have = gpu.limits[name];
+        const fits = have !== undefined && (name.startsWith("min") ? have <= wanted : have >= wanted);
+        if (!fits)
+            short.push(`${name} ${wanted} (this GPU: ${have ?? "not reported"})`);
+    }
+    if (!short.length)
+        return null;
+    const adapter = gpu.adapterInfo.description || gpu.adapterInfo.device || gpu.adapterInfo.vendor || "this adapter";
+    return `${label} needs GPU limits ${adapter} does not allow: ${short.join(", ")}.`;
+}
 /** Getter-backed supported-limits objects cannot be normalized with spread. */
 export function readGpuLimits(source) {
     if (!source || typeof source !== "object")

package/dist/runtime/runtime.d.ts

@@ -42,4 +42,6 @@ import type { CascadeRuntime, CreateRuntimeOptions } from "./types.js";
  */
 export declare const PREFLIGHT_WARNING_CODES: ReadonlySet<string>;
 export declare function createRuntime(options: CreateRuntimeOptions): CascadeRuntime;
+/** How many plain arrays/objects the runtime has copied in this process. */
+export declare function runtimeValueCopies(): number;
 //# sourceMappingURL=runtime.d.ts.map