@mulmoclaude/shapescript-plugin 1.0.0 → 1.0.1

package/README.md

@@ -51,6 +51,92 @@ for i in 1 to count {
 
 A function call takes **no space** before its parenthesis: `sin(x)` is a call, `sin (x)` is not.
 
+## Validation and errors
+
+`executePresentShapeScript` checks arguments, parses the source, evaluates expressions,
+and builds geometry headlessly before returning success. Temporary geometry is disposed.
+Failures are returned as values, with **no `data` field**, so the host does not open a
+broken visualization. The same diagnostic is available as `error` and `jsonData.error`
+(the latter is included in the calling agent's tool response):
+
+```ts
+const result = await executePresentShapeScript(context, {
+  title: "Example", script: "cube { size missing }",
+});
+if ("error" in result) {
+  console.log(result.error.code, result.error.message);
+  // EVALUATION_ERROR, "Undefined variable: missing"
+}
+```
+
+Codes: `INVALID_ARGUMENT`, `PARSE_ERROR`, `EVALUATION_ERROR`, `LIMIT_EXCEEDED`.
+Parse diagnostics include `line` and `column` when available. Invalid input does not
+throw from the tool handler. Successful results retain their existing `{ title, data: { script } }`
+contract. Validation executes the script, including geometry construction; the browser
+constructs it again for display. The source editor also validates geometry before saving.
+
+## Builders and additional expressions
+
+```text
+// Loft joins sections and caps the ends; hull forms a convex envelope.
+loft {
+    square
+    translate 0 0 2
+    circle
+}
+hull {
+    cube { position -1 0 0 }
+    cube { position 1 0 0 }
+}
+extrude { polygon { sides 5 } }
+fill { square }
+lathe path { point 1 0 curve 0 2 1 -1 }
+
+// Stencil changes surface material without cutting away the first shape.
+stencil {
+    cube { color 1 0 0 }
+    cube { position 0.5 0 0 color 0 1 0 }
+}
+
+define offsets ((1 2 3), (4 5 6))
+cube { position offsets[0].x offsets[1].y offsets.count }
+```
+
+Also supported: `pi`, `tau`, `true`, `false`, scientific notation, unary `+`,
+short-circuit `and`/`or`, string literals, `join`/`trim`, tuple arguments to `min`/`max`,
+zero-based tuple/string subscripts, `.count`, vector `.x/.y/.z/.w`, color
+`.red/.green/.blue/.alpha` (or `.r/.g/.b/.a`), custom shape definitions with options,
+and `polygon { sides N }` (integer 3–256). Lathe samples curved profiles, and inline
+builder paths use the same parser as nested paths, including loops and definitions.
+
+## Compatibility and limits
+
+This is the plugin's documented modeling subset, **not complete compatibility with
+[upstream ShapeScript](https://shapescript.info/mac/)**. It preserves existing plugin
+conventions: primitive sphere/circle sizes specify radii; rotation/orientation properties
+and trig functions use radians; relative rotate/orientation commands and path rotation
+use turns (`1 = 360°`). Path point/curve coordinates are relative steps, and curve
+control coordinates are offsets from the endpoint. Upstream uses different conventions.
+
+Loft accepts ordered, closed planar sections with one perimeter each, resamples differing
+vertex counts, interpolates linearly, and triangulates the end caps. Sections must enclose
+a volume. Hull accepts geometry from child meshes and filled paths. Primitive profiles
+for fill/extrude must lie in XY; holes, swept/twisted extrusion, and arbitrary 3D path
+commands are not implemented. Imports, textures, text/fonts, lights/camera declarations,
+arbitrary objects, and general user-defined functions remain outside this subset.
+Unsupported commands and failed CSG operations return errors instead of silently
+substituting different geometry. As with other polygonal CSG engines, degenerate or
+self-intersecting inputs may fail.
+
+`rnd` and `rand()` draw from a seeded generator (`randomSeed`, default
+`DEFAULT_RANDOM_SEED`) rather than `Math.random()`: one script is evaluated twice — once
+on the server, which validates it, and again in the browser, which renders it — and an
+unseeded generator lets those two runs take different branches.
+
+Conversion limits cover nodes, loop/path work, detail, aggregate vertices (including CSG
+intermediates), and a coarse wall-clock budget checked between nodes — it refuses to start
+the next node once the budget is spent, but cannot interrupt one long boolean.
+
 ## Scripts
 
 ```bash

package/dist/core/definition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../../src/core/definition.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,SAAS,uBAAuB,CAAC;AAE9C,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;CA4I3B,CAAC"}
+{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../../src/core/definition.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,SAAS,uBAAuB,CAAC;AAE9C,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;CAsK3B,CAAC"}

package/dist/core/index.d.ts

@@ -1,4 +1,4 @@
-export type { PresentShapeScriptData, PresentShapeScriptArgs, PresentShapeScriptResult, PresentShapeScriptRenderedResult } from "./types";
+export type { PresentShapeScriptData, PresentShapeScriptArgs, PresentShapeScriptResult, PresentShapeScriptRenderedResult, PresentShapeScriptErrorResult, PresentShapeScriptExecutionResult, ShapeScriptDiagnostic, } from "./types";
 export { TOOL_NAME, TOOL_DEFINITION } from "./definition";
 export { pluginCore, presentShapeScript, executePresentShapeScript } from "./plugin";
 export { samples } from "./samples";

package/dist/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,gCAAgC,EAAE,MAAM,SAAS,CAAC;AAC1I,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,MAAM,UAAU,CAAC;AACrF,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,YAAY,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,sBAAsB,EACtB,sBAAsB,EACtB,wBAAwB,EACxB,gCAAgC,EAChC,6BAA6B,EAC7B,iCAAiC,EACjC,qBAAqB,GACtB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,MAAM,UAAU,CAAC;AACrF,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,YAAY,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/core/plugin.d.ts

@@ -1,8 +1,8 @@
 import type { ToolContext, ToolPluginCore } from "gui-chat-protocol";
-import type { PresentShapeScriptArgs, PresentShapeScriptData, PresentShapeScriptRenderedResult } from "./types";
+import type { PresentShapeScriptArgs, PresentShapeScriptData, PresentShapeScriptExecutionResult } from "./types";
 import { TOOL_NAME, TOOL_DEFINITION } from "./definition";
-export declare const presentShapeScript: (_context: ToolContext, args: PresentShapeScriptArgs) => Promise<PresentShapeScriptRenderedResult>;
+export declare const presentShapeScript: (_context: ToolContext, args: PresentShapeScriptArgs) => Promise<PresentShapeScriptExecutionResult>;
 export declare const pluginCore: ToolPluginCore<PresentShapeScriptData, unknown, PresentShapeScriptArgs>;
 export { TOOL_NAME, TOOL_DEFINITION };
-export declare const executePresentShapeScript: (_context: ToolContext, args: PresentShapeScriptArgs) => Promise<PresentShapeScriptRenderedResult>;
+export declare const executePresentShapeScript: (_context: ToolContext, args: PresentShapeScriptArgs) => Promise<PresentShapeScriptExecutionResult>;
 //# sourceMappingURL=plugin.d.ts.map

package/dist/core/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/core/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,KAAK,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,gCAAgC,EAAE,MAAM,SAAS,CAAC;AAChH,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAK1D,eAAO,MAAM,kBAAkB,GAAU,UAAU,WAAW,EAAE,MAAM,sBAAsB,KAAG,OAAO,CAAC,gCAAgC,CAkBtI,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,cAAc,CAAC,sBAAsB,EAAE,OAAO,EAAE,sBAAsB,CAM9F,CAAC;AAEF,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,CAAC;AACtC,eAAO,MAAM,yBAAyB,aA7Ba,WAAW,QAAQ,sBAAsB,KAAG,OAAO,CAAC,gCAAgC,CA6B5E,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/core/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,KAAK,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,iCAAiC,EAAyB,MAAM,SAAS,CAAC;AACxI,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAO1D,eAAO,MAAM,kBAAkB,GAAU,UAAU,WAAW,EAAE,MAAM,sBAAsB,KAAG,OAAO,CAAC,iCAAiC,CAkCvI,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,cAAc,CAAC,sBAAsB,EAAE,OAAO,EAAE,sBAAsB,CAM9F,CAAC;AAEF,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,CAAC;AACtC,eAAO,MAAM,yBAAyB,aA7Ca,WAAW,QAAQ,sBAAsB,KAAG,OAAO,CAAC,iCAAiC,CA6C7E,CAAC"}

package/dist/core/types.d.ts

@@ -19,4 +19,18 @@ export type PresentShapeScriptResult = ToolResult<PresentShapeScriptData>;
 export type PresentShapeScriptRenderedResult = PresentShapeScriptResult & {
     data: PresentShapeScriptData;
 };
+export interface ShapeScriptDiagnostic {
+    code: "INVALID_ARGUMENT" | "PARSE_ERROR" | "EVALUATION_ERROR" | "LIMIT_EXCEEDED";
+    message: string;
+    line?: number;
+    column?: number;
+}
+/** Errors carry no renderable data; jsonData is returned to the calling agent. */
+export type PresentShapeScriptErrorResult = ToolResult<never, {
+    error: ShapeScriptDiagnostic;
+}> & {
+    data?: never;
+    error: ShapeScriptDiagnostic;
+};
+export type PresentShapeScriptExecutionResult = PresentShapeScriptRenderedResult | PresentShapeScriptErrorResult;
 //# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,wBAAwB,GAAG,UAAU,CAAC,sBAAsB,CAAC,CAAC;AAE1E;;;;;;;;GAQG;AACH,MAAM,MAAM,gCAAgC,GAAG,wBAAwB,GAAG;IACxE,IAAI,EAAE,sBAAsB,CAAC;CAC9B,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,wBAAwB,GAAG,UAAU,CAAC,sBAAsB,CAAC,CAAC;AAE1E;;;;;;;;GAQG;AACH,MAAM,MAAM,gCAAgC,GAAG,wBAAwB,GAAG;IACxE,IAAI,EAAE,sBAAsB,CAAC;CAC9B,CAAC;AAEF,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,kBAAkB,GAAG,aAAa,GAAG,kBAAkB,GAAG,gBAAgB,CAAC;IACjF,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,kFAAkF;AAClF,MAAM,MAAM,6BAA6B,GAAG,UAAU,CAAC,KAAK,EAAE;IAAE,KAAK,EAAE,qBAAqB,CAAA;CAAE,CAAC,GAAG;IAChG,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,KAAK,EAAE,qBAAqB,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,iCAAiC,GAAG,gCAAgC,GAAG,6BAA6B,CAAC"}

package/dist/core.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./toThreeJS-CtWReTrz.cjs");exports.TOOL_DEFINITION=e.Ln,exports.TOOL_NAME=e.Rn,exports.astToThreeJS=e.t,exports.executePresentShapeScript=e.Pn,exports.parseShapeScript=e.Mn,exports.pluginCore=e.Fn,exports.presentShapeScript=e.In,exports.samples=e.Nn;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./samples-D6hOBqbS.cjs");exports.TOOL_DEFINITION=e.Rn,exports.TOOL_NAME=e.zn,exports.astToThreeJS=e.a,exports.executePresentShapeScript=e.n,exports.parseShapeScript=e.Ln,exports.pluginCore=e.r,exports.presentShapeScript=e.i,exports.samples=e.t;

package/dist/core.js

@@ -1,2 +1,2 @@
-import { Fn as e, In as t, Ln as n, Mn as r, Nn as i, Pn as a, Rn as o, t as s } from "./toThreeJS-DjFysw4f.js";
-export { n as TOOL_DEFINITION, o as TOOL_NAME, s as astToThreeJS, a as executePresentShapeScript, r as parseShapeScript, e as pluginCore, t as presentShapeScript, i as samples };
+import { Ln as e, Rn as t, a as n, i as r, n as i, r as a, t as o, zn as s } from "./samples-BwRpwZSm.js";
+export { t as TOOL_DEFINITION, s as TOOL_NAME, n as astToThreeJS, i as executePresentShapeScript, e as parseShapeScript, a as pluginCore, r as presentShapeScript, o as samples };

package/dist/index.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./toThreeJS-CtWReTrz.cjs");require("./core.cjs"),exports.TOOL_DEFINITION=e.Ln,exports.TOOL_NAME=e.Rn,exports.astToThreeJS=e.t,exports.executePresentShapeScript=e.Pn,exports.parseShapeScript=e.Mn,exports.pluginCore=e.Fn,exports.presentShapeScript=e.In,exports.samples=e.Nn;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./samples-D6hOBqbS.cjs");require("./core.cjs"),exports.TOOL_DEFINITION=e.Rn,exports.TOOL_NAME=e.zn,exports.astToThreeJS=e.a,exports.executePresentShapeScript=e.n,exports.parseShapeScript=e.Ln,exports.pluginCore=e.r,exports.presentShapeScript=e.i,exports.samples=e.t;

package/dist/index.js

@@ -1,3 +1,3 @@
-import { Fn as e, In as t, Ln as n, Mn as r, Nn as i, Pn as a, Rn as o, t as s } from "./toThreeJS-DjFysw4f.js";
+import { Ln as e, Rn as t, a as n, i as r, n as i, r as a, t as o, zn as s } from "./samples-BwRpwZSm.js";
 import "./core.js";
-export { n as TOOL_DEFINITION, o as TOOL_NAME, s as astToThreeJS, a as executePresentShapeScript, r as parseShapeScript, e as pluginCore, t as presentShapeScript, i as samples };
+export { t as TOOL_DEFINITION, s as TOOL_NAME, n as astToThreeJS, i as executePresentShapeScript, e as parseShapeScript, a as pluginCore, r as presentShapeScript, o as samples };