@field/cascade 0.6.0 → 0.7.0

package/dist/index.html

@@ -4,7 +4,7 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Cascade</title>
-  <script type="module" crossorigin src="/assets/index-DTyzl6YV.js"></script>
+  <script type="module" crossorigin src="/assets/index-C35beBgj.js"></script>
   <link rel="modulepreload" crossorigin href="/assets/legacy-CAj2_7QE.js">
   <link rel="modulepreload" crossorigin href="/assets/index-client-BoJgsN9M.js">
   <link rel="modulepreload" crossorigin href="/assets/nodeTypeUtils-BDJsc2Ks.js">

package/dist/runtime/builtins/geo/definitions.d.ts

@@ -1,3 +1,4 @@
+import type { NodeExecutionContext } from "@field/cascade/contracts";
 export declare const rectangleDefinition: {
     readonly apiVersion: 1;
     readonly label: "Rectangle";
@@ -387,6 +388,116 @@ export declare const renderDefinition: {
         };
     };
 };
+/**
+ * `cascade.geo.FromRects` — the conversion, as a node.
+ *
+ * Named for what it does rather than for Houdini, which has no equivalent:
+ * `Rects` would read as a node that *produces* them, and `Convert` would be a
+ * general node with one mode in it.
+ *
+ * The whole point is that this is the only place `rects` is understood.
+ * `SvgExport`, `Render` and the viewport keep taking `geometry` and learn
+ * nothing — which is the argument MW-OBSERVATORY-ART made as owner of the
+ * consuming code, against adding a second input to the exporter.
+ *
+ * There is deliberately **no implicit `rects` → `geometry` conversion** in the
+ * type table. It would let a rects output wire straight into a geometry input,
+ * and the flip below would then happen invisibly or not at all — a picture
+ * silently mirrored is exactly the failure this node's `origin` prop exists to
+ * make a decision.
+ */
+export declare const fromRectsDefinition: {
+    readonly apiVersion: 1;
+    readonly label: "From Rects";
+    readonly description: "Convert rects into geometry, one closed polygon each, keeping the tag.";
+    readonly icon: "Frame";
+    readonly runsOn: "portable";
+    readonly inputs: {
+        readonly rects: {
+            readonly kind: "data";
+            readonly type: "rects";
+        };
+        /** The frame the rects were measured against, for the flip. */
+        readonly height: {
+            readonly kind: "data";
+            readonly type: "float";
+            readonly default: 0;
+            readonly min: 0;
+            readonly description: "Image height, for Top Left. Zero means no flip.";
+        };
+    };
+    readonly outputs: {
+        readonly geometry: {
+            readonly kind: "data";
+            readonly type: "geometry";
+        };
+    };
+    readonly props: {
+        readonly origin: {
+            readonly type: "string";
+            readonly default: "top-left";
+            readonly control: "select";
+            readonly options: readonly [{
+                readonly value: "top-left";
+                readonly label: "Top Left - raster, needs a height";
+            }, {
+                readonly value: "bottom-left";
+                readonly label: "Bottom Left - already +Y up";
+            }];
+            readonly label: "Origin";
+            readonly description: "Where y is measured from. Raster rects need flipping or the SVG comes out mirrored.";
+        };
+    };
+};
+export declare function executeFromRects(context: NodeExecutionContext<typeof fromRectsDefinition>): void;
+export declare const fromRectsRegistration: {
+    kind: "definition-v1";
+    moduleId: string;
+    definition: {
+        readonly apiVersion: 1;
+        readonly label: "From Rects";
+        readonly description: "Convert rects into geometry, one closed polygon each, keeping the tag.";
+        readonly icon: "Frame";
+        readonly runsOn: "portable";
+        readonly inputs: {
+            readonly rects: {
+                readonly kind: "data";
+                readonly type: "rects";
+            };
+            /** The frame the rects were measured against, for the flip. */
+            readonly height: {
+                readonly kind: "data";
+                readonly type: "float";
+                readonly default: 0;
+                readonly min: 0;
+                readonly description: "Image height, for Top Left. Zero means no flip.";
+            };
+        };
+        readonly outputs: {
+            readonly geometry: {
+                readonly kind: "data";
+                readonly type: "geometry";
+            };
+        };
+        readonly props: {
+            readonly origin: {
+                readonly type: "string";
+                readonly default: "top-left";
+                readonly control: "select";
+                readonly options: readonly [{
+                    readonly value: "top-left";
+                    readonly label: "Top Left - raster, needs a height";
+                }, {
+                    readonly value: "bottom-left";
+                    readonly label: "Bottom Left - already +Y up";
+                }];
+                readonly label: "Origin";
+                readonly description: "Where y is measured from. Raster rects need flipping or the SVG comes out mirrored.";
+            };
+        };
+    };
+    loadExecute: () => Promise<typeof executeFromRects>;
+};
 export declare const geoNodeDefinitions: readonly [readonly ["cascade.geo.Rectangle", {
     readonly apiVersion: 1;
     readonly label: "Rectangle";
@@ -769,5 +880,47 @@ export declare const geoNodeDefinitions: readonly [readonly ["cascade.geo.Rectan
             readonly step: 0.1;
         };
     };
+}], readonly ["cascade.geo.FromRects", {
+    readonly apiVersion: 1;
+    readonly label: "From Rects";
+    readonly description: "Convert rects into geometry, one closed polygon each, keeping the tag.";
+    readonly icon: "Frame";
+    readonly runsOn: "portable";
+    readonly inputs: {
+        readonly rects: {
+            readonly kind: "data";
+            readonly type: "rects";
+        };
+        /** The frame the rects were measured against, for the flip. */
+        readonly height: {
+            readonly kind: "data";
+            readonly type: "float";
+            readonly default: 0;
+            readonly min: 0;
+            readonly description: "Image height, for Top Left. Zero means no flip.";
+        };
+    };
+    readonly outputs: {
+        readonly geometry: {
+            readonly kind: "data";
+            readonly type: "geometry";
+        };
+    };
+    readonly props: {
+        readonly origin: {
+            readonly type: "string";
+            readonly default: "top-left";
+            readonly control: "select";
+            readonly options: readonly [{
+                readonly value: "top-left";
+                readonly label: "Top Left - raster, needs a height";
+            }, {
+                readonly value: "bottom-left";
+                readonly label: "Bottom Left - already +Y up";
+            }];
+            readonly label: "Origin";
+            readonly description: "Where y is measured from. Raster rects need flipping or the SVG comes out mirrored.";
+        };
+    };
 }]];
 //# sourceMappingURL=definitions.d.ts.map

package/dist/runtime/builtins/geo/definitions.js

@@ -1,3 +1,4 @@
+import { rectsToGeometry } from "../../geometry/rects.js";
 export const rectangleDefinition = {
     apiVersion: 1,
     label: "Rectangle",
@@ -240,6 +241,79 @@ export const renderDefinition = {
         pointRadius: { type: "float", default: 1.5, min: 0, max: 50, step: 0.1 },
     },
 };
+/**
+ * `cascade.geo.FromRects` — the conversion, as a node.
+ *
+ * Named for what it does rather than for Houdini, which has no equivalent:
+ * `Rects` would read as a node that *produces* them, and `Convert` would be a
+ * general node with one mode in it.
+ *
+ * The whole point is that this is the only place `rects` is understood.
+ * `SvgExport`, `Render` and the viewport keep taking `geometry` and learn
+ * nothing — which is the argument MW-OBSERVATORY-ART made as owner of the
+ * consuming code, against adding a second input to the exporter.
+ *
+ * There is deliberately **no implicit `rects` → `geometry` conversion** in the
+ * type table. It would let a rects output wire straight into a geometry input,
+ * and the flip below would then happen invisibly or not at all — a picture
+ * silently mirrored is exactly the failure this node's `origin` prop exists to
+ * make a decision.
+ */
+export const fromRectsDefinition = {
+    apiVersion: 1,
+    label: "From Rects",
+    description: "Convert rects into geometry, one closed polygon each, keeping the tag.",
+    icon: "Frame",
+    runsOn: "portable",
+    inputs: {
+        rects: { kind: "data", type: "rects" },
+        /** The frame the rects were measured against, for the flip. */
+        height: {
+            kind: "data",
+            type: "float",
+            default: 0,
+            min: 0,
+            description: "Image height, for Top Left. Zero means no flip.",
+        },
+    },
+    outputs: { geometry: { kind: "data", type: "geometry" } },
+    props: {
+        origin: {
+            type: "string",
+            default: "top-left",
+            control: "select",
+            options: [
+                { value: "top-left", label: "Top Left - raster, needs a height" },
+                { value: "bottom-left", label: "Bottom Left - already +Y up" },
+            ],
+            label: "Origin",
+            description: "Where y is measured from. Raster rects need flipping or the SVG comes out mirrored.",
+        },
+    },
+};
+export function executeFromRects(context) {
+    const incoming = context.inputs.rects;
+    const origin = context.props.origin === "bottom-left" ? "bottom-left" : "top-left";
+    const height = context.inputs.height ?? 0;
+    // A raster conversion with no height is the one mistake worth refusing: it
+    // produces a mirrored picture that looks plausible, and a silently upside
+    // down poster is harder to notice than a red node.
+    if (origin === "top-left" && height <= 0 && rectCount(incoming) > 0)
+        throw new Error("cascade.geo.FromRects needs the image height to flip raster rects — wire it, or set Origin to Bottom Left if the rects are already +Y up");
+    context.outputs.geometry.set(rectsToGeometry(incoming, { origin, height }));
+}
+function rectCount(value) {
+    if (Array.isArray(value))
+        return value.length;
+    const rects = value?.rects;
+    return Array.isArray(rects) ? rects.length : 0;
+}
+export const fromRectsRegistration = {
+    kind: "definition-v1",
+    moduleId: "cascade.geo.FromRects",
+    definition: fromRectsDefinition,
+    loadExecute: async () => executeFromRects,
+};
 export const geoNodeDefinitions = Object.freeze([
     ["cascade.geo.Rectangle", rectangleDefinition],
     ["cascade.geo.Circle", circleDefinition],
@@ -248,5 +322,6 @@ export const geoNodeDefinitions = Object.freeze([
     ["cascade.geo.CopyToPoints", copyToPointsDefinition],
     ["cascade.geo.SvgExport", svgExportDefinition],
     ["cascade.geo.Render", renderDefinition],
+    ["cascade.geo.FromRects", fromRectsDefinition],
 ]);
 //# sourceMappingURL=definitions.js.map

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

@@ -1,5 +1,7 @@
 import type { DefinitionNodeRegistration } from "../../types.js";
 import { copyToPointsRegistration } from "./copyToPoints.js";
+import { fromRectsRegistration } from "./definitions.js";
+export { executeFromRects, fromRectsDefinition } from "./definitions.js";
 import { circleRegistration, rectangleRegistration } from "./generators.js";
 import { mergeRegistration } from "./merge.js";
 import { renderRegistration } from "./render.js";
@@ -17,7 +19,7 @@ import { transformRegistration } from "./transform.js";
  *
  * The namespace lives in `namespace.ts`, once.
  */
-export { circleRegistration, copyToPointsRegistration, mergeRegistration, rectangleRegistration, renderRegistration, svgExportRegistration, transformRegistration, };
+export { circleRegistration, fromRectsRegistration, copyToPointsRegistration, mergeRegistration, rectangleRegistration, renderRegistration, svgExportRegistration, transformRegistration, };
 export { GEO_NAMESPACE, geoModuleId } from "./namespace.js";
 export declare const geoNodeRegistrations: readonly DefinitionNodeRegistration[];
 export declare function geoNodeRegistration(moduleId: string): DefinitionNodeRegistration | undefined;

package/dist/runtime/builtins/geo/index.js

@@ -1,4 +1,6 @@
 import { copyToPointsRegistration } from "./copyToPoints.js";
+import { fromRectsRegistration } from "./definitions.js";
+export { executeFromRects, fromRectsDefinition } from "./definitions.js";
 import { circleRegistration, rectangleRegistration } from "./generators.js";
 import { mergeRegistration } from "./merge.js";
 import { renderRegistration } from "./render.js";
@@ -16,7 +18,7 @@ import { transformRegistration } from "./transform.js";
  *
  * The namespace lives in `namespace.ts`, once.
  */
-export { circleRegistration, copyToPointsRegistration, mergeRegistration, rectangleRegistration, renderRegistration, svgExportRegistration, transformRegistration, };
+export { circleRegistration, fromRectsRegistration, copyToPointsRegistration, mergeRegistration, rectangleRegistration, renderRegistration, svgExportRegistration, transformRegistration, };
 export { GEO_NAMESPACE, geoModuleId } from "./namespace.js";
 export const geoNodeRegistrations = Object.freeze([
     rectangleRegistration,
@@ -26,6 +28,7 @@ export const geoNodeRegistrations = Object.freeze([
     copyToPointsRegistration,
     renderRegistration,
     svgExportRegistration,
+    fromRectsRegistration,
 ]);
 const registrationsById = new Map(geoNodeRegistrations.map((registration) => [
     registration.moduleId,

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

@@ -17,6 +17,7 @@ export * from "./matrix.js";
 export * from "./merge.js";
 export * from "./primitives.js";
 export * from "./promote.js";
+export * from "./rects.js";
 export * from "./resample.js";
 export * from "./svg.js";
 export * from "./transform.js";

package/dist/runtime/geometry/index.js

@@ -17,6 +17,7 @@ export * from "./matrix.js";
 export * from "./merge.js";
 export * from "./primitives.js";
 export * from "./promote.js";
+export * from "./rects.js";
 export * from "./resample.js";
 export * from "./svg.js";
 export * from "./transform.js";

package/dist/runtime/geometry/rects.d.ts

@@ -0,0 +1,88 @@
+import type { Geometry, Rect, Rects } from "@field/cascade/contracts";
+/**
+ * `rects` into `geometry` — the conversion that gives the type consumers.
+ *
+ * `rects` has been a declared core type with **zero consumers in the runtime**:
+ * nothing converted it, `cascade.geo.SvgExport` takes only `geometry`, and
+ * `cloud-plots` rendered its rects through its own Python export instead.
+ * Marcus decided on 2026-09-12 that this lands now rather than after the
+ * cutover.
+ *
+ * ## Why a conversion and not a second input on `SvgExport`
+ *
+ * MW-OBSERVATORY-ART's argument, as the owner of the consuming code, and it is
+ * the right one: a second input would make **every** geometry consumer learn
+ * about `rects` separately — the SVG writer, then the renderer, then the
+ * viewport — which is three type vocabularies again by another route. One
+ * conversion means `rects` reaches all of them at once and none of them
+ * changes.
+ *
+ * ## Two wire shapes, because the producer and the contract disagree
+ *
+ * `packages/contracts` declares a rect as `{ x, y, width, height, tag? }`. The
+ * only thing that actually produces rects — `cloud-plots`' Python
+ * `node_cli.py` — emits `{ "rect": [x, y, w, h], "tag": "<name>" }`, measured
+ * by MW-OBSERVATORY-ART rather than remembered. Both are accepted here.
+ *
+ * Being permissive is deliberate: the declared shape has no producer and the
+ * produced shape has no declaration, so refusing either would mean the
+ * conversion works for nothing that exists or for nothing that is written
+ * down. Which of the two becomes canonical is a separate decision, and this
+ * keeps working whichever way it goes.
+ *
+ * ## The tag rides along, and that was the condition
+ *
+ * *"A conversion that keeps the four numbers and drops the tag would silently
+ * destroy the labelling, and the failure would show up as unlabelled marks in
+ * a poster rather than as an error."* So every rect's tag becomes a
+ * **primitive-level string attribute** named `tag` — geometry has string
+ * attributes, so this is lossless rather than an approximation, and `SvgExport`
+ * and the renderer already read primitive attributes for style.
+ */
+/** The shape `cloud-plots` actually emits. */
+interface TaggedBox {
+    readonly rect: readonly [number, number, number, number];
+    readonly tag?: string;
+}
+export type RectLike = Rect | TaggedBox;
+export interface RectsToGeometryOptions {
+    /**
+     * Where a rect's `y` is measured from.
+     *
+     * **`top-left` is raster space**, which is what `cloud-plots` produces —
+     * pixel coordinates against the image, clamped to its bounds by
+     * `_clamp_rects`. Cascade geometry is **+Y up**, and `geometryToSvg` flips on
+     * the way out, so a raster rect passed through unflipped comes out of the SVG
+     * writer mirrored. Converting with `top-left` and a `height` is what makes
+     * the picture come back the way the analyst saw it.
+     *
+     * `bottom-left` passes the numbers through and is right for anything already
+     * in geometry's own space.
+     */
+    readonly origin?: "top-left" | "bottom-left";
+    /**
+     * The image height, for `top-left`. Zero means no flip.
+     *
+     * Required rather than inferred, because the rects themselves do not carry
+     * the frame they were measured against — flipping about the tallest rect
+     * would be a guess that looks right on a full-height mark and wrong on every
+     * other one.
+     */
+    readonly height?: number;
+}
+/**
+ * One closed four-point polygon per rect, counter-clockwise from the corner
+ * nearest the origin — the same winding `rectangleGeometry` produces, so a
+ * converted rect and an authored rectangle behave identically downstream.
+ *
+ * A rect with a non-finite or missing number is **skipped**, and the count of
+ * what was skipped is on the geometry as a `rects_skipped` detail. Throwing
+ * would make one bad mark in a thousand lose the other nine hundred and
+ * ninety-nine; silence would lose them without saying so.
+ */
+export declare function rectsToGeometry(value: Rects | readonly RectLike[] | null | undefined, options?: RectsToGeometryOptions): Geometry;
+/** True for either accepted wire shape. Used by the node to say what arrived
+ *  when something else does. */
+export declare function isRectLike(value: unknown): value is RectLike;
+export {};
+//# sourceMappingURL=rects.d.ts.map

package/dist/runtime/geometry/rects.js

@@ -0,0 +1,68 @@
+import { GeometryBuilder } from "./builder.js";
+function coordinates(rect) {
+    if (Array.isArray(rect.rect)) {
+        const box = rect.rect;
+        if (box.length < 4 || box.some((value) => typeof value !== "number"))
+            return null;
+        return [box[0], box[1], box[2], box[3]];
+    }
+    const declared = rect;
+    if (typeof declared?.x !== "number" ||
+        typeof declared?.y !== "number" ||
+        typeof declared?.width !== "number" ||
+        typeof declared?.height !== "number")
+        return null;
+    return [declared.x, declared.y, declared.width, declared.height];
+}
+/**
+ * One closed four-point polygon per rect, counter-clockwise from the corner
+ * nearest the origin — the same winding `rectangleGeometry` produces, so a
+ * converted rect and an authored rectangle behave identically downstream.
+ *
+ * A rect with a non-finite or missing number is **skipped**, and the count of
+ * what was skipped is on the geometry as a `rects_skipped` detail. Throwing
+ * would make one bad mark in a thousand lose the other nine hundred and
+ * ninety-nine; silence would lose them without saying so.
+ */
+export function rectsToGeometry(value, options = {}) {
+    const list = Array.isArray(value)
+        ? value
+        : (value?.rects ?? []);
+    const flip = options.origin === "top-left" ? (options.height ?? 0) : 0;
+    const builder = new GeometryBuilder();
+    const tags = [];
+    let skipped = 0;
+    let tagged = false;
+    for (const rect of list) {
+        const box = coordinates(rect);
+        if (!box || box.some((component) => !Number.isFinite(component))) {
+            skipped += 1;
+            continue;
+        }
+        const [x, y, width, height] = box;
+        // In raster space `y` is the TOP edge and grows downwards, so the flip is
+        // about the frame and the box's own height comes back off it.
+        const bottom = flip > 0 ? flip - (y + height) : y;
+        const top = bottom + height;
+        builder.addPolygon([x, bottom, x + width, bottom, x + width, top, x, top], {
+            closed: true,
+        });
+        const tag = rect.tag;
+        tags.push(typeof tag === "string" ? tag : "");
+        if (typeof tag === "string" && tag.length > 0)
+            tagged = true;
+    }
+    // Only when something is actually labelled: an attribute of empty strings on
+    // every primitive is noise in the Inspector and in every exported file.
+    if (tagged)
+        builder.setStringAttribute("primitive", "tag", tags);
+    if (skipped > 0)
+        builder.setDetail("rects_skipped", skipped);
+    return builder.build();
+}
+/** True for either accepted wire shape. Used by the node to say what arrived
+ *  when something else does. */
+export function isRectLike(value) {
+    return (typeof value === "object" && value !== null && coordinates(value) !== null);
+}
+//# sourceMappingURL=rects.js.map

package/doc/NODE_REFERENCE.md

@@ -369,6 +369,31 @@ Runs on `portable`.
 | --- | --- | --- | --- |
 | `geometry` | `geometry` |  |  |
 
+### `cascade.geo.FromRects`
+
+From Rects — Convert rects into geometry, one closed polygon each, keeping the tag.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `rects` | `rects` |  |  |
+| `height` | `float` | `0` |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `origin` | `string` | `"top-left"` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `geometry` | `geometry` |  |  |
+
 ### `cascade.geo.Merge`
 
 Merge — Concatenate geometries, taking the union of their attributes.
@@ -899,7 +924,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.), `cascade.geo.Render` (Draw a scene through a camera, as a raster.)
+**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.), `cascade.geo.FromRects` (Convert rects into geometry, one closed polygon each, keeping the tag.)
 
 ### Image — `cascade.image.*`
 

package/package.json

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

package/dist/assets/definitions-Cckh442l.js

@@ -1 +0,0 @@
-import{O as e,d as t,l as n,m as r,u as i}from"./index-DTyzl6YV.js";e([r,n,i,t]);

package/dist/assets/geo-DcAVygkw.js

@@ -1 +0,0 @@
-import{D as e,O as t,c as n,y as r}from"./index-DTyzl6YV.js";t(n,{assets:e});export{r as geoLibrary};

package/dist/assets/math-BA6juJD7.js

@@ -1 +0,0 @@
-import{O as e,s as t}from"./index-DTyzl6YV.js";e(t,{});

package/dist/assets/pop-Bkzzmp57.js

@@ -1 +0,0 @@
-import{O as e,_ as t,v as n}from"./index-DTyzl6YV.js";e(n,{});export{t as popLibrary};