@react-scad/core 0.1.8 → 0.1.10

package/README.md

@@ -1,26 +1,61 @@
-# react-scad
+# [react-scad](https://github.com/react-scad/react-scad) · [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/react-scad/react-scad/blob/main/LICENSE) [![npm version](https://img.shields.io/npm/v/@react-scad/core.svg?style=flat)](https://www.npmjs.com/package/@react-scad/core) [![Publish](https://github.com/react-scad/react-scad/actions/workflows/cicd.yml/badge.svg)](https://github.com/react-scad/react-scad/actions/workflows/cicd.yml) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/react-scad/react-scad#contributing)
 
-Render JSX to **OpenSCAD** models using the [React reconciler](https://github.com/facebook/react/tree/main/packages/react-reconciler).
+Render JSX to **SCAD** models using the [React reconciler](https://github.com/facebook/react/tree/main/packages/react-reconciler).
 
-- Write declarative 3D with React components; no imperative OpenSCAD scripting
-- Compose shapes with familiar JSX; get `.scad` source for OpenSCAD or 3D printing
-- Use [@react-scad/cli](../cli) via npx to build and run
+- Describe models as a tree of components instead of imperative SCAD; avoids nested modules and parameter threading.
+- Same React/JSX mental model (components, props, composition), output is 3D.
+- Writes plain `.scad` files for [OpenSCAD](https://openscad.org/) or any slicer.
 
-![Example](https://github.com/react-scad/react-scad/raw/main/assets/example.gif)
+---
+
+## Preview
+
+![Example](./assets/example.gif)
 
 *Rocket example with animated rotation.*
 
-Install the library and React:
+---
+
+## Why react-scad?
+
+SCAD is good for parametric 3D but scripts are imperative and nesting gets heavy; composing modules and passing parameters is tedious.
+
+A lot of people already think in components and JSX from building UIs. **react-scad** aims to facilitate that same way of thinking for parametric 3D.
+
+---
+
+## Getting Started
+
+### Prerequisites
+
+- **Node.js** 18+
+- **React** 18 or later (peer dependency)
+
+### Install
 
 ```bash
 npm install react @react-scad/core
 ```
 
+<details>
+<summary>pnpm or yarn</summary>
+
+```bash
+pnpm add react @react-scad/core
+# or
+yarn add react @react-scad/core
+```
+
+</details>
+
 ### Minimal example
 
+Create a file `main.tsx` (or `main.jsx`):
+
 ```jsx
 import { createRoot, Cube, Sphere, Union } from "@react-scad/core";
 
+// Output path: the .scad file that will be created
 const root = createRoot("model.scad");
 
 root.render(
@@ -31,18 +66,68 @@ root.render(
 );
 ```
 
-Save as `main.tsx`, then run it:
+| Piece | Meaning |
+| ----- | ------- |
+| `createRoot("model.scad")` | Root that writes to `model.scad` |
+| `Union` | CSG union of all children (like `union()` in SCAD) |
+| `Cube` / `Sphere` | Props match SCAD: `size`, `center`, `r`, `$fn`, etc. |
+
+### Run and write the `.scad` file
+
+Run your entry file with [tsx](https://github.com/privatenumber/tsx) so Node can execute the `.tsx`. The `.scad` file is written to the **current working directory** when you call `root.render()`.
+
+> **Note:** Node doesn’t run `.tsx` by itself. Use **tsx** or bundle with esbuild (see [Advanced](#advanced) for alternatives).
+
+```bash
+npx tsx main.tsx
+```
+
+Watch mode (re-run on save):
 
 ```bash
-npx @react-scad/cli run main.tsx
-npx @react-scad/cli run main.tsx --watch
+npx tsx watch main.tsx
 ```
 
-## Primitives (OpenSCAD coverage)
+The path you pass to `createRoot()` is relative to the current working directory.
+
+### View the result
 
-All listed OpenSCAD primitives and operations are implemented. Prop names follow OpenSCAD where it makes sense (`r`, `h`, `size`, `center`, `$fn`, etc.).
+- Open the generated `.scad` file in [OpenSCAD](https://openscad.org/) to preview, export STL, or tweak.
+- Or import the `.scad` (or an exported STL) into your slicer for 3D printing.
 
-| OpenSCAD | react-scad | Implemented |
+---
+
+## Advanced
+
+To write to a custom path or get the SCAD string in memory instead of using `createRoot(path)`, use `createContainer()`, `render()`, and `toScad()`:
+
+```jsx
+import { createContainer, render, toScad, Cube, Sphere, Union } from "@react-scad/core";
+import { writeFileSync } from "fs";
+
+const container = createContainer();
+render(
+  <Union>
+    <Cube size={[10, 10, 10]} center />
+    <Sphere r={6} />
+  </Union>,
+  container
+);
+
+const scadCode = toScad(container);
+writeFileSync("out/model.scad", scadCode);
+// or use scadCode however you like
+```
+
+Then run with `npx tsx main.tsx` or bundle with esbuild and run with Node.
+
+---
+
+## Primitives (SCAD coverage)
+
+All listed SCAD primitives and operations are implemented. Prop names follow SCAD where it makes sense (`r`, `h`, `size`, `center`, `$fn`, etc.).
+
+| SCAD | react-scad | Implemented |
 | -------- | ---------- | :---------: |
 | **3D primitives** | | |
 | `cube()` | `Cube` | ✓ |
@@ -72,22 +157,51 @@ All listed OpenSCAD primitives and operations are implemented. Prop names follow
 | `surface()` | `Surface` | ✓ |
 | `import()` | `Import` | ✓ |
 
-## Why react-scad?
+### Missing anything?
+
+> If you need a SCAD primitive or feature that isn’t listed here, open an [issue](https://github.com/react-scad/react-scad/issues/new) or a PR.
 
-OpenSCAD is great for parametric 3D, but code is imperative and nesting gets messy. Composing modules and passing parameters can be tedious.
+---
 
-With react-scad you build a tree of SCAD primitives using React components. The reconciler runs with a custom host config that builds an internal SCAD tree (no DOM). Serialization turns that tree into OpenSCAD source.
+## Contributing
 
-**JSX → React tree → host config → SCAD tree → OpenSCAD source.**
+1. **Fork and clone** the repo, then install dependencies:
+   ```bash
+   git clone https://github.com/YOUR_USER/react-scad.git
+   cd react-scad
+   pnpm install
+   ```
 
-You get declarative composition, reuse via components, and the same `.scad` output you’d use in OpenSCAD or slicers.
+2. **Create a branch** for your change:
+   ```bash
+   git checkout -b fix/your-change
+   ```
+
+3. **Build and test** before committing:
+   ```bash
+   pnpm run build
+   pnpm run dev          # optional: smoke-test the example
+   ```
+
+4. **Format and lint** (all code in the repo):
+   ```bash
+   pnpm run format
+   pnpm run lint
+   ```
+
+5. **Open a PR** against `main` with a short description of the change. For bugs, reference the issue if one exists.
+
+6. **Publishing** is done via GitHub Actions on push to `main`; no need to publish from a PR.
+
+---
 
 ## Acknowledgements
 
 - [React](https://react.dev/) and the [React reconciler](https://github.com/facebook/react/tree/main/packages/react-reconciler) for the rendering model that makes this approach possible.
-- [OpenSCAD](https://openscad.org/) for the script-based CAD language and documentation.
+- [OpenSCAD](https://openscad.org/) for the SCAD language and documentation.
+
+---
 
 ## License
 
-React SCAD is MIT-licensed open-source software by Leon Meka and 
-contributors.
+MIT

package/dist/log.d.ts

@@ -0,0 +1,14 @@
+export declare const c: {
+    dim: (s: string) => string;
+    cyan: (s: string) => string;
+    green: (s: string) => string;
+    red: (s: string) => string;
+    yellow: (s: string) => string;
+    bold: (s: string) => string;
+};
+export declare const log: {
+    buildOk(ms: number): void;
+    wrote(path: string, ms: number): void;
+    watchCycle(ms: number, code: number | null): void;
+};
+//# sourceMappingURL=log.d.ts.map

package/dist/log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,CAAC;aACJ,MAAM;cACL,MAAM;eACL,MAAM;aACR,MAAM;gBACH,MAAM;cACR,MAAM;CAChB,CAAC;AAMF,eAAO,MAAM,GAAG;gBACH,MAAM,GAAG,IAAI;gBAGb,MAAM,MAAM,MAAM,GAAG,IAAI;mBAGtB,MAAM,QAAQ,MAAM,GAAG,IAAI,GAAG,IAAI;CAKjD,CAAC"}

package/dist/log.js

@@ -0,0 +1,25 @@
+const noColor = process.env.NO_COLOR != null || !process.stdout.isTTY;
+export const c = {
+    dim: (s) => (noColor ? s : `\x1b[2m${s}\x1b[0m`),
+    cyan: (s) => (noColor ? s : `\x1b[36m${s}\x1b[0m`),
+    green: (s) => (noColor ? s : `\x1b[32m${s}\x1b[0m`),
+    red: (s) => (noColor ? s : `\x1b[31m${s}\x1b[0m`),
+    yellow: (s) => (noColor ? s : `\x1b[33m${s}\x1b[0m`),
+    bold: (s) => (noColor ? s : `\x1b[1m${s}\x1b[0m`),
+};
+function time() {
+    return new Date().toLocaleTimeString("en-US", { hour12: false });
+}
+export const log = {
+    buildOk(ms) {
+        console.log(c.dim(`[${time()}] `) + c.green("✓ Built") + c.dim(` in ${ms}ms`));
+    },
+    wrote(path, ms) {
+        console.log(c.dim(`[${time()}] `) + c.green("✓ Wrote") + c.dim(` ${path} in ${ms}ms`));
+    },
+    watchCycle(ms, code) {
+        const ok = code === 0;
+        const status = ok ? c.green("done") : c.red(`exit ${code}`);
+        console.log(`  ${ok ? c.green("✓") : c.red("✗")}${c.dim(` ${ms}ms  `)}${status}`);
+    },
+};

package/dist/runtime/root.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"root.d.ts","sourceRoot":"","sources":["../../src/runtime/root.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAKjD,YAAY,EAAE,aAAa,EAAE,CAAC;AAE9B,MAAM,WAAW,QAAQ;IACxB,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC;IAC1C,MAAM,IAAI,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,IAAI,GAAG,MAAM,CAAC;AAE1B,wBAAgB,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,QAAQ,CAchD;AAED,wBAAgB,eAAe,IAAI,aAAa,CAE/C;AAED,wBAAgB,MAAM,CACrB,OAAO,EAAE,KAAK,CAAC,YAAY,EAC3B,SAAS,EAAE,aAAa,EACxB,QAAQ,CAAC,EAAE,MAAM,IAAI,GACnB,IAAI,CAGN;AAED,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"root.d.ts","sourceRoot":"","sources":["../../src/runtime/root.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAKjD,YAAY,EAAE,aAAa,EAAE,CAAC;AAE9B,MAAM,WAAW,QAAQ;IACxB,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC;IAC1C,MAAM,IAAI,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,IAAI,GAAG,MAAM,CAAC;AAE1B,wBAAgB,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,QAAQ,CAgBhD;AAED,wBAAgB,eAAe,IAAI,aAAa,CAE/C;AAED,wBAAgB,MAAM,CACrB,OAAO,EAAE,KAAK,CAAC,YAAY,EAC3B,SAAS,EAAE,aAAa,EACxB,QAAQ,CAAC,EAAE,MAAM,IAAI,GACnB,IAAI,CAGN;AAED,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/runtime/root.js

@@ -1,3 +1,4 @@
+import { log } from "../log.js";
 import { toScad } from "../serialize/index.js";
 import { createScadContainer } from "./node-ops.js";
 import { createFiberRoot, updateContainer } from "./reconciler.js";
@@ -9,9 +10,11 @@ export function createRoot(path) {
         registerWriteOnCommit(container, path);
     return {
         render(element) {
+            const start = Date.now();
             updateContainer(element, fiberRoot, null, null);
             if (path)
                 writeAfterCommit(container);
+            log.watchCycle(Date.now() - start, 0);
         },
         toScad() {
             return toScad(container);

package/dist/runtime/write-on-commit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write-on-commit.d.ts","sourceRoot":"","sources":["../../src/runtime/write-on-commit.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIjD,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAElF;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,aAAa,GAAG,IAAI,CAG/D"}
+{"version":3,"file":"write-on-commit.d.ts","sourceRoot":"","sources":["../../src/runtime/write-on-commit.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIjD,wBAAgB,qBAAqB,CACpC,SAAS,EAAE,aAAa,EACxB,IAAI,EAAE,MAAM,GACV,IAAI,CAEN;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,aAAa,GAAG,IAAI,CAU/D"}

package/dist/runtime/write-on-commit.js

@@ -1,4 +1,6 @@
-import { writeFileSync } from "node:fs";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { log } from "../log.js";
 import { toScad } from "../serialize/index.js";
 const writeOnCommitPaths = new WeakMap();
 export function registerWriteOnCommit(container, path) {
@@ -6,6 +8,13 @@ export function registerWriteOnCommit(container, path) {
 }
 export function writeAfterCommit(container) {
     const path = writeOnCommitPaths.get(container);
-    if (path)
+    if (path) {
+        const start = Date.now();
+        const dir = dirname(path);
+        if (dir !== ".")
+            mkdirSync(dir, { recursive: true });
         writeFileSync(path, toScad(container), "utf8");
+        const ms = Date.now() - start;
+        log.wrote(path, ms);
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-scad/core",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Render JSX to OpenSCAD models using the React reconciler",
   "keywords": [
     "react",