Implicit Cad

interface:
  display_name: "Implicit CAD"
  short_description: "Write shader-native implicit CAD files."
  default_prompt: "Use $implicit-cad to create browser-rendered implicit CAD `.implicit.js` files with GLSL SDF primitives and snapshots."

MIT License

Copyright (c) 2026 earthtojake and Gradient Control Laboratories

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, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

#!/usr/bin/env node
import { spawnSync } from "node:child_process";
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";

const scriptsDir = path.dirname(fileURLToPath(import.meta.url));
const packageCli = path.join(scriptsDir, "packages", "implicitjs", "scripts", "export.mjs");

if (!fs.existsSync(packageCli)) {
  process.stderr.write(
    `Missing implicitjs export CLI at ${packageCli}. Restore the development symlink layout or rebuild the production skill bundle.\n`
  );
  process.exit(1);
}

const completed = spawnSync(process.execPath, [packageCli, ...process.argv.slice(2)], {
  cwd: process.cwd(),
  stdio: "inherit",
});

process.exitCode = completed.status ?? 1;

import { IMPLICIT_CAD_SCHEMA } from "../packages/implicitjs/src/lib/implicitCad/schema.js";

export const SCHEMA = IMPLICIT_CAD_SCHEMA;
export const PI = Math.PI;
export const TWO_PI = Math.PI * 2;
export const SQRT2 = Math.sqrt(2);
export const SQRT3 = Math.sqrt(3);

function numberLiteral(value) {
  const numeric = Number(value);
  if (!Number.isFinite(numeric)) {
    throw new Error(`Expected finite number, got ${value}`);
  }
  if (Object.is(numeric, -0)) {
    return "0.0";
  }
  return Number.isInteger(numeric) ? `${numeric}.0` : String(numeric);
}

function componentList(value, dimension) {
  if (typeof value === "number") {
    return Array.from({ length: dimension }, () => numberLiteral(value));
  }
  if (!Array.isArray(value) && !ArrayBuffer.isView(value)) {
    throw new Error(`Expected vec${dimension} array or scalar`);
  }
  return Array.from({ length: dimension }, (_, index) => numberLiteral(value[index] ?? 0));
}

export function vec2(value, y = null) {
  const components = y === null ? componentList(value, 2) : [numberLiteral(value), numberLiteral(y)];
  return `vec2(${components.join(", ")})`;
}

export function vec3(value, y = null, z = null) {
  const components = y === null && z === null
    ? componentList(value, 3)
    : [numberLiteral(value), numberLiteral(y), numberLiteral(z)];
  return `vec3(${components.join(", ")})`;
}

export function expr(value) {
  if (value && typeof value === "object" && typeof value.expr === "string") {
    return value.expr;
  }
  if (typeof value === "number") {
    return numberLiteral(value);
  }
  return String(value);
}

export function glsl(strings, ...values) {
  return strings.reduce((result, part, index) => (
    `${result}${part}${index < values.length ? expr(values[index]) : ""}`
  ), "");
}

function reduceCall(values, callName, radius = null) {
  const parts = values.map(expr);
  if (parts.length === 0) {
    throw new Error(`${callName} requires at least one field`);
  }
  if (parts.length === 1) {
    return parts[0];
  }
  return parts.slice(1).reduce((acc, value) => (
    radius === null
      ? `${callName}(${acc}, ${value})`
      : `${callName}(${acc}, ${value}, ${numberLiteral(radius)})`
  ), parts[0]);
}

function reduceCallWithArgs(values, callName, args = []) {
  const parts = values.map(expr);
  if (parts.length === 0) {
    throw new Error(`${callName} requires at least one field`);
  }
  if (parts.length === 1) {
    return parts[0];
  }
  const suffix = args.length > 0 ? `, ${args.map(expr).join(", ")}` : "";
  return parts.slice(1).reduce((acc, value) => `${callName}(${acc}, ${value}${suffix})`, parts[0]);
}

export function linearMap(value, inMin, inMax, outMin, outMax) {
  return `implicit_linear_map(${expr(value)}, ${numberLiteral(inMin)}, ${numberLiteral(inMax)}, ${numberLiteral(outMin)}, ${numberLiteral(outMax)})`;
}

export function ramp(value, inMin, inMax, outMin, outMax) {
  return `implicit_ramp(${expr(value)}, ${numberLiteral(inMin)}, ${numberLiteral(inMax)}, ${numberLiteral(outMin)}, ${numberLiteral(outMax)})`;
}

export function twoBodyField(a, b) {
  return `implicit_two_body_field(${expr(a)}, ${expr(b)})`;
}

export function twoBodyPolar(a, b, angle) {
  return `implicit_two_body_polar(${expr(a)}, ${expr(b)}, ${numberLiteral(angle)})`;
}

export function triangleWaveEven(value, period) {
  return `implicit_triangle_wave_even(${expr(value)}, ${expr(period)})`;
}

export function triangleWaveEvenPositive(value, period) {
  return `implicit_triangle_wave_even_positive(${expr(value)}, ${expr(period)})`;
}

export function triangleWaveOdd(value, period) {
  return `implicit_triangle_wave_odd(${expr(value)}, ${expr(period)})`;
}

export function triangleWaveOddPositive(value, period) {
  return `implicit_triangle_wave_odd_positive(${expr(value)}, ${expr(period)})`;
}

export function unionSharp(values) {
  return reduceCall(values, "implicit_union_sharp");
}

export function intersectSharp(values) {
  return reduceCall(values, "implicit_intersect_sharp");
}

export function unionRound(values, radius = 0) {
  return reduceCall(values, "implicit_union_round", radius);
}

export function intersectRound(values, radius = 0) {
  return reduceCall(values, "implicit_intersect_round", radius);
}

export function unionChamfer(values, radius = 0) {
  return reduceCall(values, "implicit_union_chamfer", radius);
}

export function intersectChamfer(values, radius = 0) {
  return reduceCall(values, "implicit_intersect_chamfer", radius);
}

export function unionExp(values, radius = 0) {
  return reduceCall(values, "implicit_union_exp", radius);
}

export function intersectExp(values, radius = 0) {
  return reduceCall(values, "implicit_intersect_exp", radius);
}

export function unionLpNorm(values, radius = 0, normPower = 2) {
  return reduceCallWithArgs(values, "implicit_union_lp_norm", [numberLiteral(radius), numberLiteral(normPower)]);
}

export function intersectLpNorm(values, radius = 0, normPower = 2) {
  return reduceCallWithArgs(values, "implicit_intersect_lp_norm", [numberLiteral(radius), numberLiteral(normPower)]);
}

export function unionRvachev(values, radius = 0) {
  return reduceCall(values, "implicit_union_rvachev", radius);
}

export function intersectRvachev(values, radius = 0) {
  return reduceCall(values, "implicit_intersect_rvachev", radius);
}

export function booleanSharp() {
  return { union: unionSharp, intersect: intersectSharp };
}

export function booleanRound(radius = 0) {
  return {
    radius,
    union: (values) => unionRound(values, radius),
    intersect: (values) => intersectRound(values, radius),
  };
}

export function booleanExp(radius = 0) {
  return {
    radius,
    union: (values) => unionExp(values, radius),
    intersect: (values) => intersectExp(values, radius),
  };
}

export function booleanLp(normPower, radius = 0) {
  return {
    radius,
    normPower,
    union: (values) => unionLpNorm(values, radius, normPower),
    intersect: (values) => intersectLpNorm(values, radius, normPower),
  };
}

export function booleanRvachev(radius = 0) {
  return {
    radius,
    union: (values) => unionRvachev(values, radius),
    intersect: (values) => intersectRvachev(values, radius),
  };
}

export function booleanChamfer(radius = 0) {
  return {
    radius,
    union: (values) => unionChamfer(values, radius),
    intersect: (values) => intersectChamfer(values, radius),
  };
}

export function difference(target, tools, {
  union = unionSharp,
  intersect = intersectSharp
} = {}) {
  const toolList = Array.isArray(tools) ? tools : [tools];
  const toolUnion = union(toolList);
  return intersect([target, `-(${toolUnion})`]);
}

export function sphere(p, center, radius) {
  return `implicit_sphere(${expr(p)}, ${vec3(center)}, ${numberLiteral(radius)})`;
}

export function circle(p, center, radius) {
  return sphere(p, center, radius);
}

export function boxCentered(p, size, { center = [0, 0, 0] } = {}) {
  return `implicit_box_centered(${expr(p)}, ${vec3(size)}, ${vec3(center)})`;
}

export function plane(p, origin, normal) {
  return `implicit_plane(${expr(p)}, ${vec3(origin)}, ${vec3(normal)})`;
}

export function lineSegment(p, endpointA, endpointB) {
  return `implicit_line_segment(${expr(p)}, ${vec3(endpointA)}, ${vec3(endpointB)})`;
}

export function torus(p, majorRadius, minorRadius) {
  return `implicit_torus(${expr(p)}, ${numberLiteral(majorRadius)}, ${numberLiteral(minorRadius)})`;
}

export function axis(p, origin, direction) {
  return `implicit_axis(${expr(p)}, ${vec3(origin)}, ${vec3(direction)})`;
}

export function cylinder(p, origin, direction, radius) {
  return `implicit_cylinder(${expr(p)}, ${vec3(origin)}, ${vec3(direction)}, ${numberLiteral(radius)})`;
}

export function cylinderCapped(p, endpointA, endpointB, radius) {
  return `implicit_cylinder_capped(${expr(p)}, ${vec3(endpointA)}, ${vec3(endpointB)}, ${numberLiteral(radius)})`;
}

export function capsule(p, endpointA, endpointB, radius) {
  return `implicit_capsule(${expr(p)}, ${vec3(endpointA)}, ${vec3(endpointB)}, ${numberLiteral(radius)})`;
}

export function coneCapsule(p, endpointA, endpointB, radiusA, radiusB) {
  return `implicit_cone_capsule(${expr(p)}, ${vec3(endpointA)}, ${vec3(endpointB)}, ${numberLiteral(radiusA)}, ${numberLiteral(radiusB)})`;
}

export function cone(p, apex, direction, halfAngle) {
  return `implicit_cone(${expr(p)}, ${vec3(apex)}, ${vec3(direction)}, ${numberLiteral(halfAngle)})`;
}

export function coneCapped(p, endpointA, endpointB, radiusA, radiusB) {
  return `implicit_cone_capped(${expr(p)}, ${vec3(endpointA)}, ${vec3(endpointB)}, ${numberLiteral(radiusA)}, ${numberLiteral(radiusB)})`;
}

export function shell(distance, thickness, bias = 0) {
  return `implicit_shell(${expr(distance)}, ${numberLiteral(thickness)}, ${numberLiteral(bias)})`;
}

export function rotateAxis(p, origin, direction, angle) {
  return `implicit_rotate_axis(${expr(p)}, ${vec3(origin)}, ${vec3(direction)}, ${numberLiteral(angle)})`;
}

export function repeatCentered(p, period) {
  return `implicit_repeat_centered(${expr(p)}, ${vec3(period)})`;
}

export function remapCylindrical(p, circumference) {
  return `implicit_remap_cylindrical(${expr(p)}, ${numberLiteral(circumference)})`;
}

export function cubicGrid(p, size) {
  return `implicit_cubic_grid(${expr(p)}, ${vec3(size)})`;
}

export function squareHoneycomb(p, size) {
  return `implicit_square_honeycomb(${expr(p)}, ${vec2(size)})`;
}

export function squareHoneycombReinforced(p, size, { rotation = 0.25, rotation2 = null } = {}) {
  return `implicit_square_honeycomb_reinforced(${expr(p)}, ${vec2(size)}, ${numberLiteral(rotation)}, ${numberLiteral(rotation2 ?? 0)}, ${numberLiteral(rotation2 === null ? 0 : 1)})`;
}

export function squareDiagonalHoneycomb(p, size) {
  return `implicit_square_diagonal_honeycomb(${expr(p)}, ${vec2(size)})`;
}

export function octetHoneycomb(p, size) {
  return `implicit_octet_honeycomb(${expr(p)}, ${vec2(size)})`;
}

export function hexagonalHoneycomb(p, size, { setback = 1 / 3 } = {}) {
  const resolvedSize = typeof size === "number" ? [size, size * SQRT3] : size;
  return `implicit_hexagonal_honeycomb(${expr(p)}, ${vec2(resolvedSize)}, ${numberLiteral(setback)})`;
}

export function triangularHoneycomb(p, size) {
  const resolvedSize = typeof size === "number" ? [size, size * SQRT3] : size;
  return `implicit_triangular_honeycomb(${expr(p)}, ${vec2(resolvedSize)})`;
}

export function tpmsGyroid(p, period, drop = [1, 1, 1]) {
  return `implicit_tpms_gyroid(${expr(p)}, ${vec3(period)}, ${vec3(drop)})`;
}

export function tpmsSchwarz(p, period, { drop = [1, 1, 1], gyroidBlend = 0 } = {}) {
  return `implicit_tpms_schwarz(${expr(p)}, ${vec3(period)}, ${vec3(drop)}, ${numberLiteral(gyroidBlend)})`;
}

export function tpmsDiamond(p, period, { drop = [1, 1, 1], gyroidBlend = 0 } = {}) {
  return `implicit_tpms_diamond(${expr(p)}, ${vec3(period)}, ${vec3(drop)}, ${numberLiteral(gyroidBlend)})`;
}

export function tpmsLidinoid(p, period, { drop = [1, 1, 1], gyroidBlend = 0 } = {}) {
  return `implicit_tpms_lidinoid(${expr(p)}, ${vec3(period)}, ${vec3(drop)}, ${numberLiteral(gyroidBlend)})`;
}

export function tpmsNeovius(p, period, { drop = [1, 1, 1], schwarzBlend = 0 } = {}) {
  return `implicit_tpms_neovius(${expr(p)}, ${vec3(period)}, ${vec3(drop)}, ${numberLiteral(schwarzBlend)})`;
}

export function tpmsSplitP(p, period, { lidinoidBlend = 1, gyroidOctave = 1, schwarzOctave = 1 } = {}) {
  return `implicit_tpms_split_p(${expr(p)}, ${vec3(period)}, ${numberLiteral(lidinoidBlend)}, ${numberLiteral(gyroidOctave)}, ${numberLiteral(schwarzOctave)})`;
}

export function tpmsIwp(p, period, drop = [1, 1, 1]) {
  return `implicit_tpms_iwp(${expr(p)}, ${vec3(period)}, ${vec3(drop)})`;
}

export function distanceFunction(distanceExpression, { point = "p" } = {}) {
  return `float sdf(vec3 ${point}) {\n  return ${expr(distanceExpression)};\n}`;
}

export function colorFunction(colorExpression, { point = "p", normal = "normal" } = {}) {
  return `vec3 color(vec3 ${point}, vec3 ${normal}) {\n  return clamp(${expr(colorExpression)}, vec3(0.0), vec3(1.0));\n}`;
}

function distanceSource(value) {
  return typeof value === "function" || /\bsdf\s*\(/.test(expr(value))
    ? value
    : distanceFunction(value);
}

function colorSource(value) {
  return typeof value === "function" || /\bcolor\s*\(/.test(expr(value))
    ? value
    : colorFunction(value);
}

export function createImplicitModel({
  name = "Implicit CAD",
  description = "",
  units = "mm",
  bounds,
  params = {},
  values = {},
  animations = {},
  render = {},
  glsl = "",
  distance,
  color = "",
} = {}) {
  const glslSource = glsl || [
    distance !== undefined ? distanceSource(distance) : "",
    color ? colorSource(color) : "",
  ].filter(Boolean).join("\n\n");
  return {
    schema: SCHEMA,
    name,
    description,
    units,
    ...(bounds !== undefined ? { bounds } : {}),
    ...(params && Object.keys(params).length ? { params } : {}),
    ...(values && Object.keys(values).length ? { values } : {}),
    ...(animations && Object.keys(animations).length ? { animations } : {}),
    ...(render && Object.keys(render).length ? { render } : {}),
    glsl: glslSource,
  };
}

{
  "name": "implicitjs",
  "version": "0.1.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "implicitjs",
      "version": "0.1.0",
      "dependencies": {
        "gifenc": "^1.0.3",
        "playwright": "^1.52.0",
        "three": "0.160.0"
      }
    },
    "node_modules/fsevents": {
      "version": "2.3.2",
      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz",
      "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==",
      "hasInstallScript": true,
      "license": "MIT",
      "optional": true,
      "os": [
        "darwin"
      ],
      "engines": {
        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
      }
    },
    "node_modules/gifenc": {
      "version": "1.0.3",
      "resolved": "https://registry.npmjs.org/gifenc/-/gifenc-1.0.3.tgz",
      "integrity": "sha512-xdr6AdrfGBcfzncONUOlXMBuc5wJDtOueE3c5rdG0oNgtINLD+f2iFZltrBRZYzACRbKr+mSVU/x98zv2u3jmw==",
      "license": "MIT"
    },
    "node_modules/playwright": {
      "version": "1.60.0",
      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.60.0.tgz",
      "integrity": "sha512-hheHdokM8cdqCb0lcE3s+zT4t4W+vvjpGxsZlDnikarzx8tSzMebh3UiFtgqwFwnTnjYQcsyMF8ei2mCO/tpeA==",
      "license": "Apache-2.0",
      "dependencies": {
        "playwright-core": "1.60.0"
      },
      "bin": {
        "playwright": "cli.js"
      },
      "engines": {
        "node": ">=18"
      },
      "optionalDependencies": {
        "fsevents": "2.3.2"
      }
    },
    "node_modules/playwright-core": {
      "version": "1.60.0",
      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.60.0.tgz",
      "integrity": "sha512-9bW6zvX/m0lEbgTKJ6YppOKx8H3VOPBMOCFh2irXFOT4BbHgrx5hPjwJYLT40Lu+4qtD36qKc/Hn56StUW57IA==",
      "license": "Apache-2.0",
      "bin": {
        "playwright-core": "cli.js"
      },
      "engines": {
        "node": ">=18"
      }
    },
    "node_modules/three": {
      "version": "0.160.0",
      "resolved": "https://registry.npmjs.org/three/-/three-0.160.0.tgz",
      "integrity": "sha512-DLU8lc0zNIPkM7rH5/e1Ks1Z8tWCGRq6g8mPowdDJpw1CFBJMU7UoJjC6PefXW7z//SSl0b2+GCw14LB+uDhng==",
      "license": "MIT"
    }
  }
}

{
  "name": "implicitjs",
  "version": "0.1.0",
  "type": "module",
  "description": "Standalone browser-native implicit CAD runtime, renderer, mesh sampler, and exporters.",
  "exports": {
    ".": {
      "browser": "./src/browser.js",
      "default": "./src/index.js"
    },
    "./browser": "./src/browser.js",
    "./schema": "./src/lib/implicitCad/schema.js",
    "./animation": "./src/lib/implicitCad/animation.js",
    "./model": "./src/lib/implicitCad/model.js",
    "./implicit": "./src/browser.js",
    "./loader": "./src/lib/implicitCad/loader.js",
    "./render": "./src/lib/implicitCad/render.js",
    "./snapshot": "./src/lib/implicitCad/snapshot.js",
    "./graphicsSettings": "./src/lib/implicitCad/graphicsSettings.js",
    "./mesh": "./src/lib/implicitCad/mesh.js",
    "./meshQuality": "./src/lib/implicitCad/meshQuality.js",
    "./exportModel": "./src/lib/implicitCad/exportModel.js",
    "./export": "./src/lib/implicitCad/export.js",
    "./exporters": "./src/lib/implicitCad/exporters.js",
    "./sdfEvaluator": "./src/lib/implicitCad/sdfEvaluator.js",
    "./headlessRenderEntry": "./src/common/implicitHeadlessRenderEntry.js",
    "./common/*": "./src/common/*",
    "./lib/implicitCad/*": "./src/lib/implicitCad/*"
  },
  "scripts": {
    "export": "node scripts/export.mjs",
    "snapshot": "node scripts/snapshot.mjs",
    "test": "node scripts/run-tests.mjs",
    "verify:exports": "node scripts/verify-implicit-cad-exports.mjs"
  },
  "sideEffects": [
    "./src/common/implicitHeadlessRenderEntry.js"
  ],
  "dependencies": {
    "gifenc": "^1.0.3",
    "playwright": "^1.52.0",
    "three": "0.160.0"
  }
}

#!/usr/bin/env node
import { exportImplicitCadFile, IMPLICIT_CAD_EXPORT_FORMATS } from "../src/lib/implicitCad/export.js";

function usage() {
  return `Usage:
  node scripts/export.mjs --input <model.implicit.js> --format glb
  node scripts/export.mjs --input <model.implicit.js> --output <mesh.stl> --resolution <resolution>

Options:
  --input, -i       Input .implicit.js/.implicit.mjs file.
  --output, -o      Output file. Defaults to same folder/stem with selected format.
  --format, -f      Export format: ${IMPLICIT_CAD_EXPORT_FORMATS.join(", ")}.
  --resolution      Longest-axis sampling resolution. Default: 96.
  --max-cells       Safety cap for grid cells. Default: 2500000.
  --params          JSON object of implicit parameter values.
  --animation       JSON object of implicit animation state.
  --animated        Export a GLB morph-target animation from the selected animation.
  --frames          Animation frame count for --animated. Default: 18.
  --duration        Animation duration in seconds for --animated. Default: animation duration.
  --json            Print machine-readable result JSON.
  --help, -h        Show this help.
`;
}

function parseJsonOption(value, label) {
  const text = String(value || "").trim();
  if (!text) {
    return null;
  }
  try {
    const parsed = JSON.parse(text);
    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
      throw new Error(`${label} must be a JSON object`);
    }
    return parsed;
  } catch (error) {
    throw new Error(`Invalid ${label}: ${error instanceof Error ? error.message : String(error)}`);
  }
}

function parseArgs(argv) {
  const options = {
    input: "",
    output: "",
    format: "",
    resolution: 96,
    maxCells: undefined,
    params: null,
    animationState: null,
    animated: false,
    frames: undefined,
    duration: undefined,
    json: false,
    help: false,
  };
  for (let index = 0; index < argv.length; index += 1) {
    const arg = argv[index];
    const readValue = () => {
      index += 1;
      if (index >= argv.length) {
        throw new Error(`${arg} requires a value`);
      }
      return argv[index];
    };
    switch (arg) {
      case "--input":
      case "-i":
        options.input = readValue();
        break;
      case "--output":
      case "-o":
        options.output = readValue();
        break;
      case "--format":
      case "-f":
        options.format = readValue();
        break;
      case "--resolution":
        options.resolution = Number(readValue());
        break;
      case "--max-cells":
        options.maxCells = Number(readValue());
        break;
      case "--params":
        options.params = parseJsonOption(readValue(), "--params");
        break;
      case "--animation":
        options.animationState = parseJsonOption(readValue(), "--animation");
        break;
      case "--animated":
        options.animated = true;
        break;
      case "--frames":
        options.frames = Number(readValue());
        break;
      case "--duration":
        options.duration = Number(readValue());
        break;
      case "--json":
        options.json = true;
        break;
      case "--help":
      case "-h":
        options.help = true;
        break;
      default:
        if (!options.input && !arg.startsWith("-")) {
          options.input = arg;
        } else {
          throw new Error(`Unknown argument: ${arg}`);
        }
    }
  }
  return options;
}

async function main() {
  const options = parseArgs(process.argv.slice(2));
  if (options.help) {
    process.stdout.write(usage());
    return;
  }
  if (!options.input) {
    throw new Error("Missing --input");
  }
  const result = await exportImplicitCadFile(options);
  if (options.json) {
    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
  } else {
    process.stdout.write(`Exported ${result.format.toUpperCase()} ${result.output}\n`);
    process.stdout.write(`Triangles: ${result.triangleCount.toLocaleString()}  Bytes: ${result.bytes.toLocaleString()}\n`);
  }
}

main().catch((error) => {
  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
  process.exitCode = 1;
});

#!/usr/bin/env node
import { spawnSync } from "node:child_process";
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";

const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
const repoRoot = path.resolve(packageRoot, "..", "..");
const testRoots = [
  path.join(packageRoot, "src"),
  path.join(packageRoot, "scripts"),
];

function collectTests(dir, tests = []) {
  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
    const entryPath = path.join(dir, entry.name);
    if (entry.isDirectory()) {
      collectTests(entryPath, tests);
    } else if (/\.test\.[cm]?js$/u.test(entry.name)) {
      tests.push(entryPath);
    }
  }
  return tests;
}

const requestedTests = process.argv.slice(2).map((testPath) => path.resolve(packageRoot, testPath));
const tests = (requestedTests.length ? requestedTests : testRoots.flatMap((root) => collectTests(root))).sort();
if (!tests.length) {
  console.error("No implicitjs tests found.");
  process.exit(1);
}

const result = spawnSync(process.execPath, [
  "--test",
  "--experimental-default-type=module",
  ...tests,
], {
  cwd: packageRoot,
  env: {
    ...process.env,
    ...(fs.existsSync(path.join(repoRoot, ".venv", "bin", "python"))
      ? { CAD_PYTHON: path.join(repoRoot, ".venv", "bin", "python") }
      : {}),
    ...(fs.existsSync(path.join(repoRoot, "packages", "cadpy", "src"))
      ? { CAD_PYTHONPATH: path.join(repoRoot, "packages", "cadpy", "src") }
      : {}),
  },
  stdio: "inherit",
});

process.exit(result.status ?? 1);

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Implicit CAD snapshot render</title>
    <style>
      html,
      body {
        margin: 0;
        min-width: 100%;
        min-height: 100%;
        overflow: hidden;
        background: transparent;
      }
    </style>
  </head>
  <body>
    <script type="importmap">
      {
        "imports": {
          "gifenc": "/node_modules/gifenc/dist/gifenc.esm.js",
          "three": "/node_modules/three/build/three.module.js"
        }
      }
    </script>
    <script type="module" src="/src/common/implicitHeadlessRenderEntry.js"></script>
  </body>
</html>

#!/usr/bin/env node
import fs from "node:fs";
import path from "node:path";
import { performance } from "node:perf_hooks";
import { fileURLToPath, pathToFileURL } from "node:url";

export const SNAPSHOT_ORIGIN = "http://implicit-cad-snapshot.local";
const SNAPSHOT_RENDER_URL = `${SNAPSHOT_ORIGIN}/render.html`;
const SNAPSHOT_ROUTE_GLOB = `${SNAPSHOT_ORIGIN}/**`;
export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
export const RUNTIME_DIR = path.join(PACKAGE_ROOT, "scripts", "snapshot-runtime");
export const RENDER_HTML_PATH = path.join(RUNTIME_DIR, "render.html");
const DEFAULT_TIMEOUT_SECONDS = 180;
const RENDER_BROWSER_STARTUP_TIMEOUT_MS = 15_000;
const DEFAULT_RENDER_THEME_ID = "workbench";
const WORKBENCH_RENDER_THEME_IDS = new Set([DEFAULT_RENDER_THEME_ID]);
const SIMPLE_RENDER_WIDTH = 1200;
const SIMPLE_RENDER_HEIGHT = 900;
const SIMPLE_SQUARE_RENDER_WIDTH = 1024;
const SIMPLE_SQUARE_RENDER_HEIGHT = 1024;
const DIAGNOSTIC_RENDER_WIDTH = 1600;
const DIAGNOSTIC_RENDER_HEIGHT = 1200;
const DEFAULT_RENDER_WIDTH = DIAGNOSTIC_RENDER_WIDTH;
const DEFAULT_RENDER_HEIGHT = DIAGNOSTIC_RENDER_HEIGHT;
const COMPLEX_ASSEMBLY_RENDER_WIDTH = 1800;
const COMPLEX_ASSEMBLY_RENDER_HEIGHT = 1200;
const COMPLEX_ASSEMBLY_LARGE_RENDER_WIDTH = 1920;
const COMPLEX_ASSEMBLY_LARGE_RENDER_HEIGHT = 1440;
const PRESENTATION_RENDER_WIDTH = 2400;
const PRESENTATION_RENDER_HEIGHT = 1600;
const PRESENTATION_LARGE_RENDER_WIDTH = 2800;
const PRESENTATION_LARGE_RENDER_HEIGHT = 1800;
const ORBIT_RENDER_WIDTH = 960;
const ORBIT_RENDER_HEIGHT = 640;
const CONTACT_SHEET_RENDER_WIDTH = 2400;
const CONTACT_SHEET_RENDER_HEIGHT = 1600;

const APPEARANCE_OPTION_KEYS = new Set([
  "materials",
  "edges",
  "background",
  "floor",
  "environment",
  "lighting",
]);
const GRAPHICS_OPTION_KEYS = new Set([
  "resolutionScale",
  "interactionResolutionScale",
  "detail",
  "normalSmoothing",
  "modelColors",
  "shadows",
  "ambientOcclusion",
  "rimLight",
]);

export class SnapshotError extends Error {
  constructor(message) {
    super(message);
    this.name = "SnapshotError";
  }
}

class RouteFileError extends SnapshotError {
  constructor(message, { status = 404 } = {}) {
    super(message);
    this.status = status;
  }
}

export function helpText() {
  return `Usage:
  node scripts/snapshot.mjs --input <model.implicit.js> --output <snapshot.png>
  node scripts/snapshot.mjs --input <model.implicit.js> --output <orbit.gif> --mode orbit
  node scripts/snapshot.mjs --job <render-job.json>
  node scripts/snapshot.mjs --job - --json

Snapshot renders browser-native implicit CAD .implicit.js/.implicit.mjs modules. Supported shortcut flags are --input, --output/-o, --mode, --appearance, --camera, --size-profile, --width, --height, --params, --graphics, --job, and --json. The default appearance is the built-in light/dark-aware theme. --appearance accepts a saved theme name, an inline JSON appearance settings object, or a JSON appearance settings file path. --camera accepts a preset, azimuth:elevation pair, or JSON object with preset, position, target, up, direction, and zoom fields. JSON jobs use input, mode=view/orbit/animate, outputs, camera, width/height, appearance, graphics, implicitParameters, implicitAnimation, orbit, and optional render.transparent/render.zoom/render.frameMargin. A job can include multiple outputs, and --job can load a raw job, an array of jobs, or { "jobs": [...] }; prefer one multi-output job for review packets so the browser, source module, and runtime model are reused. Output file names are saved with a shared UTC seconds timestamp before the extension.
`;
}

function isPlainObject(value) {
  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
}

function positiveInteger(value, label) {
  const parsed = Number.parseInt(String(value || ""), 10);
  if (!Number.isFinite(parsed) || parsed <= 0) {
    throw new SnapshotError(`${label} must be a positive integer`);
  }
  return parsed;
}

function readRequiredValue(argv, index, flag) {
  const value = argv[index + 1];
  if (!value || value.startsWith("--")) {
    throw new SnapshotError(`${flag} requires a value`);
  }
  return value;
}

function optionDefaults() {
  return {
    job: "",
    input: "",
    output: "",
    mode: "",
    modeSpecified: false,
    appearance: DEFAULT_RENDER_THEME_ID,
    appearanceSpecified: false,
    camera: "iso",
    cameraSpecified: false,
    sizeProfile: "",
    graphics: null,
    graphicsSpecified: false,
    width: null,
    height: null,
    params: null,
    paramsSpecified: false,
    json: false,
    help: false,
  };
}

export function parseSnapshotArgs(argv) {
  const options = optionDefaults();
  for (let index = 0; index < argv.length; index += 1) {
    const arg = argv[index];
    if (arg === "--help" || arg === "-h") {
      options.help = true;
    } else if (arg === "--json") {
      options.json = true;
    } else if (arg === "--job") {
      options.job = readRequiredValue(argv, index, arg);
      index += 1;
    } else if (arg.startsWith("--job=")) {
      options.job = arg.slice("--job=".length);
    } else if (arg === "--input") {
      options.input = readRequiredValue(argv, index, arg);
      index += 1;
    } else if (arg.startsWith("--input=")) {
      options.input = arg.slice("--input=".length);
    } else if (arg === "--output" || arg === "-o") {
      options.output = readRequiredValue(argv, index, arg);
      index += 1;
    } else if (arg.startsWith("--output=")) {
      options.output = arg.slice("--output=".length);
    } else if (arg === "--mode") {
      options.mode = readRequiredValue(argv, index, arg);
      options.modeSpecified = true;
      index += 1;
    } else if (arg.startsWith("--mode=")) {
      options.mode = arg.slice("--mode=".length);
      options.modeSpecified = true;
    } else if (arg === "--appearance") {
      options.appearance = readRequiredValue(argv, index, arg);
      options.appearanceSpecified = true;
      index += 1;
    } else if (arg.startsWith("--appearance=")) {
      options.appearance = arg.slice("--appearance=".length);
      options.appearanceSpecified = true;
    } else if (arg === "--camera") {
      options.camera = readRequiredValue(argv, index, arg);
      options.cameraSpecified = true;
      index += 1;
    } else if (arg.startsWith("--camera=")) {
      options.camera = arg.slice("--camera=".length);
      options.cameraSpecified = true;
    } else if (arg === "--size-profile") {
      options.sizeProfile = readRequiredValue(argv, index, arg);
      index += 1;
    } else if (arg.startsWith("--size-profile=")) {
      options.sizeProfile = arg.slice("--size-profile=".length);
    } else if (arg === "--width") {
      options.width = positiveInteger(readRequiredValue(argv, index, arg), arg);
      index += 1;
    } else if (arg.startsWith("--width=")) {
      options.width = positiveInteger(arg.slice("--width=".length), "--width");
    } else if (arg === "--height") {
      options.height = positiveInteger(readRequiredValue(argv, index, arg), arg);
      index += 1;
    } else if (arg.startsWith("--height=")) {
      options.height = positiveInteger(arg.slice("--height=".length), "--height");
    } else if (arg === "--params") {
      options.params = readRequiredValue(argv, index, arg);
      options.paramsSpecified = true;
      index += 1;
    } else if (arg.startsWith("--params=")) {
      options.params = arg.slice("--params=".length);
      options.paramsSpecified = true;
    } else if (arg === "--graphics") {
      options.graphics = readRequiredValue(argv, index, arg);
      options.graphicsSpecified = true;
      index += 1;
    } else if (arg.startsWith("--graphics=")) {
      options.graphics = arg.slice("--graphics=".length);
      options.graphicsSpecified = true;
    } else {
      throw new SnapshotError(`Unknown argument: ${arg}`);
    }
  }
  return options;
}

function loadJsonText(text, sourceLabel) {
  try {
    return JSON.parse(text);
  } catch (error) {
    throw new SnapshotError(`Failed to parse JSON from ${sourceLabel}: ${error.message}`);
  }
}

function parseCameraOption(rawCamera) {
  const camera = String(rawCamera || "").trim();
  if (!camera) {
    throw new SnapshotError("--camera requires a preset, azimuth:elevation pair, or JSON camera object");
  }
  if (!camera.startsWith("{")) {
    return camera;
  }
  const parsed = loadJsonText(camera, "--camera");
  if (!isPlainObject(parsed)) {
    throw new SnapshotError("--camera must be a preset, azimuth:elevation pair, or JSON object");
  }
  return { ...parsed };
}

function parseParamsOption(rawParams) {
  const parsed = loadJsonText(String(rawParams || ""), "--params");
  if (!isPlainObject(parsed)) {
    throw new SnapshotError("--params must be an implicit parameter JSON object");
  }
  return { ...parsed };
}

function validateDirectSettingsPayload(parsed, {
  optionName,
  sourceLabel,
  allowedKeys,
  settingLabel,
}) {
  if (!isPlainObject(parsed)) {
    throw new SnapshotError(`${optionName} JSON must be a ${settingLabel} object: ${sourceLabel}`);
  }
  const unknownKeys = Object.keys(parsed).filter((key) => !allowedKeys.has(key));
  if (unknownKeys.length) {
    throw new SnapshotError(
      `${optionName} JSON must be the ${settingLabel} object directly; unsupported keys: ${unknownKeys.join(", ")}`
    );
  }
  if (!Object.keys(parsed).length) {
    throw new SnapshotError(`${optionName} JSON must include at least one ${settingLabel} field: ${sourceLabel}`);
  }
  return { ...parsed };
}

function resolveMaybeRelative(rawPath, cwd) {
  return path.isAbsolute(rawPath) ? path.resolve(rawPath) : path.resolve(cwd, rawPath);
}

function loadAppearanceOption(rawAppearance, { cwd }) {
  const appearance = String(rawAppearance || DEFAULT_RENDER_THEME_ID).trim() || DEFAULT_RENDER_THEME_ID;
  if (appearance.startsWith("{")) {
    return validateDirectSettingsPayload(loadJsonText(appearance, "--appearance"), {
      optionName: "--appearance",
      sourceLabel: "--appearance",
      allowedKeys: APPEARANCE_OPTION_KEYS,
      settingLabel: "appearance settings",
    });
  }

  const appearancePath = resolveMaybeRelative(appearance, cwd);
  const looksLikeFile = appearance.toLowerCase().endsWith(".json") || appearance.includes("/") || appearance.includes("\\");
  if (!looksLikeFile && !fs.existsSync(appearancePath)) {
    return appearance;
  }
  if (!fs.existsSync(appearancePath)) {
    throw new SnapshotError(`Appearance JSON file does not exist: ${appearance}`);
  }
  return validateDirectSettingsPayload(loadJsonText(fs.readFileSync(appearancePath, "utf8"), appearancePath), {
    optionName: "--appearance",
    sourceLabel: appearancePath,
    allowedKeys: APPEARANCE_OPTION_KEYS,
    settingLabel: "appearance settings",
  });
}

function loadGraphicsOption(rawGraphics, { cwd }) {
  const graphics = String(rawGraphics || "").trim();
  if (!graphics) {
    throw new SnapshotError("--graphics requires a JSON object or JSON file path");
  }
  if (graphics.startsWith("{")) {
    return validateDirectSettingsPayload(loadJsonText(graphics, "--graphics"), {
      optionName: "--graphics",
      sourceLabel: "--graphics",
      allowedKeys: GRAPHICS_OPTION_KEYS,
      settingLabel: "implicit graphics settings",
    });
  }

  const graphicsPath = resolveMaybeRelative(graphics, cwd);
  if (!fs.existsSync(graphicsPath)) {
    throw new SnapshotError(`Graphics JSON file does not exist: ${graphics}`);
  }
  return validateDirectSettingsPayload(loadJsonText(fs.readFileSync(graphicsPath, "utf8"), graphicsPath), {
    optionName: "--graphics",
    sourceLabel: graphicsPath,
    allowedKeys: GRAPHICS_OPTION_KEYS,
    settingLabel: "implicit graphics settings",
  });
}

function cloneJson(value) {
  return JSON.parse(JSON.stringify(value));
}

function applyOptionOverridesToJob(job, options, { cwd }) {
  if (!isPlainObject(job)) {
    return job;
  }
  if (!options.modeSpecified &&
      !options.appearanceSpecified &&
      !options.cameraSpecified &&
      !options.sizeProfile &&
      !options.width &&
      !options.height &&
      !options.paramsSpecified &&
      !options.graphicsSpecified) {
    return job;
  }
  const nextJob = cloneJson(job);
  if (options.modeSpecified) {
    nextJob.mode = options.mode;
  }
  if (options.appearanceSpecified) {
    nextJob.appearance = loadAppearanceOption(options.appearance, { cwd });
  }
  if (options.cameraSpecified) {
    nextJob.camera = parseCameraOption(options.camera);
  }
  if (options.width) {
    nextJob.width = options.width;
  }
  if (options.height) {
    nextJob.height = options.height;
  }
  if (options.sizeProfile) {
    nextJob.render = {
      ...(isPlainObject(nextJob.render) ? nextJob.render : {}),
      sizeProfile: options.sizeProfile,
    };
  }
  if (options.paramsSpecified) {
    nextJob.implicitParameters = parseParamsOption(options.params);
  }
  if (options.graphicsSpecified) {
    nextJob.graphics = loadGraphicsOption(options.graphics, { cwd });
  }
  return nextJob;
}

async function readStream(stream) {
  return new Promise((resolve, reject) => {
    let text = "";
    stream.setEncoding("utf8");
    stream.on("data", (chunk) => {
      text += chunk;
    });
    stream.on("error", reject);
    stream.on("end", () => resolve(text));
  });
}

export async function loadJobFromOptions(options, {
  stdin = process.stdin,
  cwd = process.cwd(),
} = {}) {
  const resolvedCwd = path.resolve(cwd);
  if (options.job) {
    const text = options.job === "-"
      ? await readStream(stdin)
      : fs.readFileSync(resolveMaybeRelative(options.job, resolvedCwd), "utf8");
    const sourceLabel = options.job === "-" ? "stdin" : resolveMaybeRelative(options.job, resolvedCwd);
    const payload = loadJsonText(text, sourceLabel);
    if (Array.isArray(payload)) {
      return payload.map((job) => applyOptionOverridesToJob(job, options, { cwd: resolvedCwd }));
    }
    if (isPlainObject(payload) && Array.isArray(payload.jobs)) {
      return {
        ...cloneJson(payload),
        jobs: payload.jobs.map((job) => applyOptionOverridesToJob(job, options, { cwd: resolvedCwd })),
      };
    }
    return applyOptionOverridesToJob(payload, options, { cwd: resolvedCwd });
  }

  if (!stdin.isTTY && !options.input) {
    const text = await readStream(stdin);
    if (text.trim()) {
      return loadJsonText(text, "stdin");
    }
  }

  if (!options.input) {
    throw new SnapshotError("render requires --job, stdin JSON, or --input");
  }
  if (!options.output) {
    throw new SnapshotError("render shortcut requires --output");
  }

  const output = {
    path: options.output,
    camera: parseCameraOption(options.camera),
  };
  if (options.width) {
    output.width = options.width;
  }
  if (options.height) {
    output.height = options.height;
  }
  let mode = String(options.mode || "").trim().toLowerCase();
  if (!mode) {
    mode = options.output.toLowerCase().endsWith(".gif") ? "orbit" : "view";
  }
  const job = {
    input: options.input,
    mode,
    outputs: [output],
    appearance: loadAppearanceOption(options.appearance, { cwd: resolvedCwd }),
  };
  if (options.sizeProfile) {
    job.render = { sizeProfile: options.sizeProfile };
  }
  if (options.paramsSpecified) {
    job.implicitParameters = parseParamsOption(options.params);
  }
  if (options.graphicsSpecified) {
    job.graphics = loadGraphicsOption(options.graphics, { cwd: resolvedCwd });
  }
  return job;
}

function pathIsInsideOrEqual(child, parent) {
  const resolvedChild = path.resolve(child);
  const resolvedParent = path.resolve(parent);
  const relative = path.relative(resolvedParent, resolvedChild);
  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
}

function isImplicitPath(filePath) {
  const name = path.basename(filePath).toLowerCase();
  return name.endsWith(".implicit.js") || name.endsWith(".implicit.mjs");
}

function resolveInputPath(rawInput, { cwd }) {
  const inputText = String(rawInput || "").trim();
  if (!inputText) {
    throw new SnapshotError("render job is missing input");
  }
  const selected = resolveMaybeRelative(inputText, cwd);
  if (!fs.existsSync(selected)) {
    throw new SnapshotError(`Render input does not exist: ${inputText}`);
  }
  if (!isImplicitPath(selected)) {
    throw new SnapshotError("Snapshot supports only .implicit.js and .implicit.mjs inputs");
  }
  return selected;
}

function encodePathParam(value) {
  return value.replaceAll(path.sep, "/").split("/").map(encodeURIComponent).join("/");
}

function assetUrlForPath(filePath, rootPath) {
  if (!pathIsInsideOrEqual(filePath, rootPath)) {
    throw new SnapshotError(`Render asset must be inside the snapshot render root: ${filePath}`);
  }
  const stat = fs.statSync(filePath);
  const versionSource = `${path.resolve(filePath)}:${stat.mtimeMs}:${stat.size}`;
  const version = Buffer.from(versionSource).toString("base64url");
  return `/__render_asset/${encodePathParam(path.relative(path.resolve(rootPath), path.resolve(filePath)))}?v=${version}`;
}

export function snapshotTimestamp() {
  return new Date().toISOString().replace(/[-:]/gu, "").replace(/\.\d{3}Z$/u, "Z");
}

export function timestampOutputPath(outputPath, timestamp) {
  if (!outputPath) {
    return "";
  }
  const parsed = path.parse(outputPath);
  return path.join(parsed.dir, `${parsed.name}_${timestamp}${parsed.ext}`);
}

function normalizeSnapshotJobPacket(rawPayload) {
  if (Array.isArray(rawPayload)) {
    return { single: false, jobs: rawPayload };
  }
  if (isPlainObject(rawPayload) && Array.isArray(rawPayload.jobs)) {
    return { single: false, jobs: rawPayload.jobs };
  }
  return { single: true, jobs: [rawPayload] };
}

function appearanceThemeIdForJob(job) {
  const appearance = job.appearance;
  return typeof appearance === "string"
    ? (appearance.trim().toLowerCase() || DEFAULT_RENDER_THEME_ID)
    : DEFAULT_RENDER_THEME_ID;
}

function normalizeSizeProfile(value) {
  return String(value || "").trim().toLowerCase().replaceAll("_", "-");
}

function explicitSizeProfile(job, output) {
  const render = isPlainObject(job.render) ? job.render : {};
  return normalizeSizeProfile(output.sizeProfile || render.sizeProfile || job.sizeProfile || "");
}

function defaultRenderSize(job, output) {
  const mode = String(job.mode || "view").trim().toLowerCase();
  const profile = explicitSizeProfile(job, output);
  if (profile === "simple-square" || profile === "square") {
    return [SIMPLE_SQUARE_RENDER_WIDTH, SIMPLE_SQUARE_RENDER_HEIGHT];
  }
  if (["simple", "simple-part", "unlabeled"].includes(profile)) {
    return [SIMPLE_RENDER_WIDTH, SIMPLE_RENDER_HEIGHT];
  }
  if (["presentation-large", "hero", "large-presentation"].includes(profile)) {
    return [PRESENTATION_LARGE_RENDER_WIDTH, PRESENTATION_LARGE_RENDER_HEIGHT];
  }
  if (profile === "presentation") {
    return [PRESENTATION_RENDER_WIDTH, PRESENTATION_RENDER_HEIGHT];
  }
  if (["complex-assembly-large", "assembly-large"].includes(profile)) {
    return [COMPLEX_ASSEMBLY_LARGE_RENDER_WIDTH, COMPLEX_ASSEMBLY_LARGE_RENDER_HEIGHT];
  }
  if (["complex-assembly", "assembly"].includes(profile)) {
    return [COMPLEX_ASSEMBLY_RENDER_WIDTH, COMPLEX_ASSEMBLY_RENDER_HEIGHT];
  }
  if (profile === "contact-sheet" || profile === "contactsheet") {
    return [CONTACT_SHEET_RENDER_WIDTH, CONTACT_SHEET_RENDER_HEIGHT];
  }
  if (profile === "orbit" || mode === "orbit" || mode === "animate" || isPlainObject(job.implicitAnimation)) {
    return [ORBIT_RENDER_WIDTH, ORBIT_RENDER_HEIGHT];
  }
  if (["dimensioned", "section", "labeled", "diagnostic"].includes(profile) ||
      WORKBENCH_RENDER_THEME_IDS.has(appearanceThemeIdForJob(job))) {
    return [DIAGNOSTIC_RENDER_WIDTH, DIAGNOSTIC_RENDER_HEIGHT];
  }
  return [SIMPLE_RENDER_WIDTH, SIMPLE_RENDER_HEIGHT];
}

function resolveOutputSize(job, output) {
  const [defaultWidth, defaultHeight] = defaultRenderSize(job, output);
  return [
    positiveInteger(output.width || job.width || defaultWidth, "output width"),
    positiveInteger(output.height || job.height || defaultHeight, "output height"),
  ];
}

export function resolveRenderJob(rawJob, {
  cwd = process.cwd(),
  timestamp = snapshotTimestamp(),
} = {}) {
  if (!isPlainObject(rawJob)) {
    throw new SnapshotError("render job must be an object");
  }
  const job = cloneJson(rawJob);
  if ("theme" in job) {
    throw new SnapshotError("render jobs use appearance; theme is reserved for saved appearance settings");
  }
  if ("params" in job) {
    throw new SnapshotError("render jobs use implicitParameters; params is reserved for shortcut --params parsing");
  }
  const mode = String(job.mode || "view").trim().toLowerCase();
  if (!["view", "orbit", "animate"].includes(mode)) {
    throw new SnapshotError("Implicit CAD snapshot supports only view, orbit, and animate modes");
  }
  const renderSettings = isPlainObject(job.render) ? { ...job.render } : {};
  const graphicsSettings = isPlainObject(job.graphics) ? { ...job.graphics } : {};
  const appearanceSettings = job.appearance || DEFAULT_RENDER_THEME_ID;
  const resolvedCwd = path.resolve(cwd);
  const inputPath = resolveInputPath(job.input, { cwd: resolvedCwd });
  const rootPath = path.dirname(inputPath);
  const outputs = Array.isArray(job.outputs) ? job.outputs : [];
  if (!outputs.length) {
    throw new SnapshotError("render job must include outputs");
  }
  const normalizedOutputs = outputs.map((output) => {
    const outputObject = isPlainObject(output) ? { ...output } : {};
    const [width, height] = resolveOutputSize({
      ...job,
      mode,
      appearance: appearanceSettings,
      render: renderSettings,
    }, outputObject);
    const outputPath = String(outputObject.path || "");
    const timestampedOutputPath = timestampOutputPath(outputPath, timestamp);
    return {
      ...outputObject,
      path: timestampedOutputPath ? path.resolve(resolvedCwd, timestampedOutputPath) : "",
      width,
      height,
      camera: outputObject.camera || job.camera || "iso",
    };
  });

  return {
    ...job,
    mode,
    appearance: appearanceSettings,
    graphics: graphicsSettings,
    render: renderSettings,
    outputs: normalizedOutputs,
    resolved: {
      rootPath,
      inputPath,
      inputUrl: assetUrlForPath(inputPath, rootPath),
      kind: "implicit",
    },
  };
}

export function resolveRenderJobPacket(rawPayload, {
  cwd = process.cwd(),
  timestamp = snapshotTimestamp(),
} = {}) {
  const { single, jobs } = normalizeSnapshotJobPacket(rawPayload);
  return {
    single,
    jobs: jobs.map((job) => resolveRenderJob(job, { cwd, timestamp })),
  };
}

function contentTypeForPath(filePath) {
  const suffix = path.extname(filePath).toLowerCase();
  if (suffix === ".mjs" || suffix === ".js") {
    return "text/javascript; charset=utf-8";
  }
  if (suffix === ".html") {
    return "text/html; charset=utf-8";
  }
  if (suffix === ".json") {
    return "application/json; charset=utf-8";
  }
  if (suffix === ".png") {
    return "image/png";
  }
  if (suffix === ".gif") {
    return "image/gif";
  }
  return "application/octet-stream";
}

function routeFile(pathname, prefix, root) {
  const relativePath = decodeURIComponent(pathname.slice(prefix.length));
  const filePath = path.resolve(root, relativePath.replace(/^\/+/u, ""));
  if (!pathIsInsideOrEqual(filePath, root)) {
    throw new RouteFileError(`forbidden route path: ${pathname}`, { status: 403 });
  }
  return filePath;
}

export function resolveSnapshotRouteFile(rawUrl, { activeRootPath = null } = {}) {
  const parsed = new URL(rawUrl);
  if (parsed.origin !== SNAPSHOT_ORIGIN) {
    throw new RouteFileError(`unsupported snapshot origin: ${parsed.origin}`, { status: 403 });
  }
  if (parsed.pathname === "/render.html") {
    return RENDER_HTML_PATH;
  }
  if (parsed.pathname.startsWith("/src/")) {
    return routeFile(parsed.pathname, "/src/", path.join(PACKAGE_ROOT, "src"));
  }
  if (parsed.pathname.startsWith("/node_modules/")) {
    return routeFile(parsed.pathname, "/node_modules/", path.join(PACKAGE_ROOT, "node_modules"));
  }
  if (parsed.pathname.startsWith("/__render_asset/")) {
    if (!activeRootPath) {
      throw new RouteFileError("snapshot render asset requested without an active render root");
    }
    return routeFile(parsed.pathname, "/__render_asset/", activeRootPath);
  }
  throw new RouteFileError(`snapshot route not found: ${parsed.pathname}`);
}

function maxOutputSize(job) {
  const outputs = Array.isArray(job.outputs) && job.outputs.length ? job.outputs : [];
  const widths = outputs.filter(isPlainObject).map((output) => Number(output.width || DEFAULT_RENDER_WIDTH));
  const heights = outputs.filter(isPlainObject).map((output) => Number(output.height || DEFAULT_RENDER_HEIGHT));
  return [
    Math.max(...(widths.length ? widths : [DEFAULT_RENDER_WIDTH])),
    Math.max(...(heights.length ? heights : [DEFAULT_RENDER_HEIGHT])),
  ];
}

async function withSnapshotTimeout(promise, timeoutSeconds, label = "snapshot") {
  const timeout = Math.max(1, Number(timeoutSeconds || DEFAULT_TIMEOUT_SECONDS));
  let timer = null;
  try {
    return await Promise.race([
      promise,
      new Promise((_, reject) => {
        timer = setTimeout(() => reject(new SnapshotError(`${label} timed out after ${timeoutSeconds}s`)), timeout * 1000);
      }),
    ]);
  } finally {
    if (timer) {
      clearTimeout(timer);
    }
  }
}

export function chromiumLaunchOptions() {
  return {
    headless: true,
    timeout: RENDER_BROWSER_STARTUP_TIMEOUT_MS,
    args: [],
  };
}

const PAGE_ISSUE_MAX_LENGTH = 2000;

function pageIssueText(prefix, text) {
  const message = String(text || "").trim();
  const truncated = message.length > PAGE_ISSUE_MAX_LENGTH
    ? `${message.slice(0, PAGE_ISSUE_MAX_LENGTH)}… [truncated]`
    : message;
  return `${prefix}: ${truncated}`;
}

class BatchSnapshotRenderer {
  constructor() {
    this.browser = null;
    this.context = null;
    this.page = null;
    this.activeRootPath = null;
    this.started = false;
    this.pageIssues = [];
  }

  async start() {
    if (this.started) {
      return;
    }
    try {
      const { chromium } = await import("playwright").catch((error) => {
        throw new SnapshotError(
          `Implicit CAD snapshot requires the JavaScript playwright package. Install implicitjs dependencies and run playwright install chromium if needed. ${error instanceof Error ? error.message : String(error)}`
        );
      });
      this.browser = await chromium.launch(chromiumLaunchOptions());
      this.context = await this.browser.newContext({
        viewport: { width: DEFAULT_RENDER_WIDTH, height: DEFAULT_RENDER_HEIGHT },
        deviceScaleFactor: 1,
      });
      this.page = await this.context.newPage();
      // THREE.js reports shader compile failures through console.error inside
      // the page; without these hooks a broken shader renders a blank image
      // with no diagnostic at all.
      this.page.on("console", (message) => {
        if (message.type() === "error") {
          this.pageIssues.push(pageIssueText("page console error", message.text()));
        }
      });
      this.page.on("pageerror", (error) => {
        this.pageIssues.push(pageIssueText("page error", error instanceof Error ? error.message : error));
      });
      await this.page.route(SNAPSHOT_ROUTE_GLOB, (route) => this.handleRoute(route));
      await this.page.goto(SNAPSHOT_RENDER_URL, {
        waitUntil: "load",
        timeout: DEFAULT_TIMEOUT_SECONDS * 1000,
      });
      await this.page.waitForFunction(
        "typeof window.__implicitCadSnapshotRender === 'function'",
        null,
        { timeout: DEFAULT_TIMEOUT_SECONDS * 1000 }
      );
      this.started = true;
    } catch (error) {
      await this.close();
      throw error;
    }
  }

  async handleRoute(route) {
    const request = route.request();
    if (request.method() !== "GET") {
      await route.fulfill({ status: 405, contentType: "text/plain; charset=utf-8", body: "method not allowed" });
      return;
    }
    let filePath = "";
    try {
      filePath = resolveSnapshotRouteFile(request.url(), { activeRootPath: this.activeRootPath });
    } catch (error) {
      await route.fulfill({
        status: error instanceof RouteFileError ? error.status : 500,
        contentType: "text/plain; charset=utf-8",
        body: error instanceof Error ? error.message : String(error),
      });
      return;
    }
    if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) {
      await route.fulfill({ status: 404, contentType: "text/plain; charset=utf-8", body: "not found" });
      return;
    }
    await route.fulfill({
      status: 200,
      contentType: contentTypeForPath(filePath),
      headers: { "cache-control": "no-store" },
      body: fs.readFileSync(filePath),
    });
  }

  async render(job) {
    await this.start();
    const resolved = isPlainObject(job.resolved) ? job.resolved : {};
    this.activeRootPath = path.resolve(String(resolved.rootPath || ""));
    const [width, height] = maxOutputSize(job);
    await this.page.setViewportSize({ width, height });
    const issueStart = this.pageIssues.length;
    const result = await withSnapshotTimeout(
      this.page.evaluate((renderJob) => window.__implicitCadSnapshotRender(renderJob), { ...job }),
      job.timeoutSeconds || DEFAULT_TIMEOUT_SECONDS
    );
    const issues = [...new Set(this.pageIssues.slice(issueStart))];
    if (!isPlainObject(result) || !result.ok) {
      const failure = String(isPlainObject(result) ? result.error || "" : "") || "unknown browser snapshot failure";
      throw new SnapshotError([failure, ...issues].join("\n"));
    }
    if (issues.length) {
      result.warnings = [...(Array.isArray(result.warnings) ? result.warnings : []), ...issues];
    }
    return result;
  }

  async close() {
    if (this.context) {
      try {
        await this.context.close();
      } catch {
        // Best-effort cleanup.
      }
      this.context = null;
    }
    if (this.browser) {
      try {
        await this.browser.close();
      } catch {
        // Best-effort cleanup.
      }
      this.browser = null;
    }
    this.page = null;
    this.started = false;
  }
}

export async function renderResolvedJobPacket(packet) {
  const renderer = new BatchSnapshotRenderer();
  const started = performance.now();
  const results = [];
  try {
    for (const job of packet.jobs) {
      const result = await renderer.render(job);
      results.push(packet.single ? result : { input: job.input, ...result });
    }
  } finally {
    await renderer.close();
  }
  if (packet.single) {
    return results[0];
  }
  return {
    ok: results.every((result) => result.ok !== false),
    jobs: results,
    timings: {
      jobCount: results.length,
      totalMs: performance.now() - started,
    },
  };
}

function writeOutputPayload(output) {
  const outputPath = String(output.path || "");
  if (!outputPath) {
    return;
  }
  const dataUrl = String(output.dataUrl || "");
  const match = dataUrl.match(/^data:([^;]+);base64,(.+)$/su);
  if (!match) {
    throw new SnapshotError(`Snapshot output did not include a base64 data URL: ${outputPath}`);
  }
  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
  fs.writeFileSync(outputPath, Buffer.from(match[2], "base64"));
}

export function writeRenderOutputs(result) {
  if (Array.isArray(result.jobs)) {
    for (const jobResult of result.jobs) {
      if (isPlainObject(jobResult)) {
        writeRenderOutputs(jobResult);
      }
    }
    return;
  }
  const outputs = Array.isArray(result.outputs) ? result.outputs : [];
  for (const output of outputs) {
    if (isPlainObject(output)) {
      writeOutputPayload(output);
    }
  }
}

export function printRenderResult(result, { jsonOutput = false, stdout = process.stdout } = {}) {
  if (jsonOutput) {
    stdout.write(`${JSON.stringify(result, null, 2)}\n`);
    return;
  }
  if (Array.isArray(result.jobs)) {
    for (const jobResult of result.jobs) {
      if (isPlainObject(jobResult)) {
        printRenderResult(jobResult, { jsonOutput: false, stdout });
      }
    }
    return;
  }
  const outputs = Array.isArray(result.outputs) ? result.outputs : null;
  if (!outputs) {
    stdout.write(`${JSON.stringify(result, null, 2)}\n`);
    return;
  }
  for (const output of outputs) {
    if (isPlainObject(output) && output.path) {
      stdout.write(`saved snapshot: ${output.path}\n`);
    }
  }
  const warnings = Array.isArray(result.warnings) ? result.warnings : [];
  for (const warning of warnings) {
    stdout.write(`snapshot warning: ${warning}\n`);
  }
}

export async function runRenderCli(argv, {
  cwd = process.cwd(),
  stdin = process.stdin,
  stdout = process.stdout,
  stderr = process.stderr,
} = {}) {
  try {
    const options = parseSnapshotArgs(argv);
    if (options.help) {
      stdout.write(helpText());
      return 0;
    }
    const rawPayload = await loadJobFromOptions(options, { stdin, cwd });
    const packet = resolveRenderJobPacket(rawPayload, { cwd });
    const result = await renderResolvedJobPacket(packet);
    writeRenderOutputs(result);
    printRenderResult(result, { jsonOutput: options.json, stdout });
    return 0;
  } catch (error) {
    stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
    return 1;
  }
}

if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
  runRenderCli(process.argv.slice(2)).then((status) => {
    process.exitCode = status;
  });
}

export const snapshotCliModuleUrl = pathToFileURL(fileURLToPath(import.meta.url)).href;