tsdraft 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stephen Frederick
+
+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.

package/README.md

@@ -1,3 +1,73 @@
-# Temporary Holding Version
+# tsdraft
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Write 2D CAD drawings in TypeScript and export them as DXF for AutoCAD or
+BricsCAD, or as SVG for a quick preview. A drawing is a program, so dimensions
+can come from variables, sheets can share code, and changes show up as diffs.
+[tscircuit](https://github.com/tscircuit/tscircuit) takes the same approach to
+circuit boards.
+
+This is an early release. It has layers, lines, polylines, rectangles, circles,
+arcs and single-line text. It does not yet have dimensions, hatches, blocks,
+paper space or a JSX syntax.
+
+## Install
+
+```sh
+npm install tsdraft
+```
+
+tsdraft is an ES module and needs Node 22 or later.
+
+## Example
+
+```ts
+import { createDrawing, toDXF, toSVG } from "tsdraft";
+
+const d = createDrawing({ units: "ft" });
+
+d.layer("C-PROP", { color: 3 }, () => {
+  d.rect([0, 0], 75, 120);
+});
+d.layer("A-BLDG", { color: 1 }, () => {
+  d.rect([17.5, 30], 40, 50);
+  d.text([19.5, 55], "PROPOSED RESIDENCE", { height: 2 });
+});
+
+const drawing = d.build();
+const dxf = toDXF(drawing);
+const svg = toSVG(drawing);
+```
+
+Coordinates are in drawing units with Y pointing up, as in CAD. Angles are in
+degrees, counterclockwise from +X. Layer colors are AutoCAD Color Index numbers.
+Entities go on layer `0` unless they are drawn inside a `layer()` callback.
+
+`toDXF` writes ASCII DXF R12, because nearly every CAD program can open that
+version. R12 has no field for drawing units, so the file holds plain numbers.
+Set the units in CAD after opening it, for example with `UNITS` in AutoCAD or
+BricsCAD.
+
+## Development
+
+Contributors need Node 24 or later and pnpm. Node runs the TypeScript source
+directly, so tests and examples need no build step.
+
+```sh
+pnpm install
+pnpm verify    # format check, lint, type check, tests, package smoke test
+pnpm example   # writes examples/out/site-plan.dxf and .svg
+```
+
+`pnpm test:package` packs the package, installs the tarball into a throwaway
+project and checks that it type-checks and runs there. `pnpm build` compiles
+`src/` to `dist/`, and `npm pack` and `npm publish` run it automatically.
+
+The official TypeScript 7 compiler checks and builds the package.
+[tsrs](https://github.com/oxc-project/tsrs), the Rust port of TypeScript, runs
+as `pnpm check:tsrs` and as an informational CI step. It tracks TypeScript 7.1
+beta, so it does not gate releases yet. Its WebAssembly build is the planned
+route for type-checking drawings in a browser playground.
+
+## License
+
+[MIT](LICENSE)

package/dist/drawing.d.ts

@@ -0,0 +1,86 @@
+/** A model-space point, in drawing units. Y points up, as in CAD. */
+export type Point = readonly [x: number, y: number];
+/**
+ * The unit one drawing unit stands for. It is kept on the drawing for callers;
+ * the DXF R12 writer has no field for it, so set units in CAD after opening.
+ */
+export type Units = "in" | "ft" | "mm" | "cm" | "m";
+export interface Layer {
+    readonly name: string;
+    /** AutoCAD Color Index, 1 to 255. 7 is white on dark backgrounds, black on light. */
+    readonly color: number;
+}
+interface EntityBase {
+    readonly layer: string;
+}
+export interface Line extends EntityBase {
+    readonly kind: "line";
+    readonly from: Point;
+    readonly to: Point;
+}
+export interface Polyline extends EntityBase {
+    readonly kind: "polyline";
+    readonly points: readonly Point[];
+    readonly closed: boolean;
+}
+export interface Circle extends EntityBase {
+    readonly kind: "circle";
+    readonly center: Point;
+    readonly radius: number;
+}
+/** Angles are in degrees, counterclockwise from +X, as in DXF. */
+export interface Arc extends EntityBase {
+    readonly kind: "arc";
+    readonly center: Point;
+    readonly radius: number;
+    readonly startAngle: number;
+    readonly endAngle: number;
+}
+export interface Text extends EntityBase {
+    readonly kind: "text";
+    /** Left end of the text baseline. */
+    readonly at: Point;
+    readonly height: number;
+    readonly value: string;
+    /** Degrees counterclockwise. */
+    readonly rotation: number;
+}
+export type Entity = Line | Polyline | Circle | Arc | Text;
+export interface Drawing {
+    readonly units: Units;
+    readonly layers: readonly Layer[];
+    readonly entities: readonly Entity[];
+}
+export interface DrawingOptions {
+    readonly units?: Units;
+}
+export interface LayerOptions {
+    readonly color?: number;
+}
+export interface TextOptions {
+    readonly height?: number;
+    readonly rotation?: number;
+}
+/**
+ * Builds a drawing. Entities go on the current layer, which starts as "0".
+ * `layer(name, opts, draw)` scopes everything drawn inside `draw` to that layer.
+ */
+export declare class DrawingBuilder {
+    #private;
+    readonly units: Units;
+    constructor(options?: DrawingOptions);
+    /** Defines or updates a layer. With `draw`, entities drawn inside it go on this layer. */
+    layer(name: string, options?: LayerOptions, draw?: () => void): this;
+    line(from: Point, to: Point): this;
+    polyline(points: readonly Point[], closed?: boolean): this;
+    /** Closed rectangle from its lower-left corner. */
+    rect(corner: Point, width: number, height: number): this;
+    circle(center: Point, radius: number): this;
+    arc(center: Point, radius: number, startAngle: number, endAngle: number): this;
+    text(at: Point, value: string, options?: TextOptions): this;
+    build(): Drawing;
+}
+export declare function createDrawing(options?: DrawingOptions): DrawingBuilder;
+/** Counterclockwise sweep from start to end, in degrees, within [0, 360). */
+export declare function sweep(startAngle: number, endAngle: number): number;
+export {};

package/dist/drawing.js

@@ -0,0 +1,116 @@
+/**
+ * Builds a drawing. Entities go on the current layer, which starts as "0".
+ * `layer(name, opts, draw)` scopes everything drawn inside `draw` to that layer.
+ */
+export class DrawingBuilder {
+    units;
+    #layers = new Map([["0", { name: "0", color: 7 }]]);
+    #entities = [];
+    #current = "0";
+    constructor(options = {}) {
+        this.units = options.units ?? "in";
+    }
+    /** Defines or updates a layer. With `draw`, entities drawn inside it go on this layer. */
+    layer(name, options = {}, draw) {
+        if (!/^[^<>/\\":;?*|=`]{1,255}$/.test(name)) {
+            throw new Error(`Invalid layer name: ${JSON.stringify(name)}`);
+        }
+        const color = options.color ?? this.#layers.get(name)?.color ?? 7;
+        if (!Number.isInteger(color) || color < 1 || color > 255) {
+            throw new Error(`Layer ${name}: color must be an ACI integer from 1 to 255`);
+        }
+        this.#layers.set(name, { name, color });
+        if (draw) {
+            const previous = this.#current;
+            this.#current = name;
+            try {
+                draw();
+            }
+            finally {
+                this.#current = previous;
+            }
+        }
+        return this;
+    }
+    line(from, to) {
+        return this.#add({ kind: "line", layer: this.#current, from: pt(from), to: pt(to) });
+    }
+    polyline(points, closed = false) {
+        if (points.length < 2)
+            throw new Error("A polyline needs at least 2 points");
+        return this.#add({ kind: "polyline", layer: this.#current, points: points.map(pt), closed });
+    }
+    /** Closed rectangle from its lower-left corner. */
+    rect(corner, width, height) {
+        const [x, y] = pt(corner);
+        num(width, "width");
+        num(height, "height");
+        return this.polyline([
+            [x, y],
+            [x + width, y],
+            [x + width, y + height],
+            [x, y + height],
+        ], true);
+    }
+    circle(center, radius) {
+        return this.#add({
+            kind: "circle",
+            layer: this.#current,
+            center: pt(center),
+            radius: positive(radius, "radius"),
+        });
+    }
+    arc(center, radius, startAngle, endAngle) {
+        num(startAngle, "startAngle");
+        num(endAngle, "endAngle");
+        if (sweep(startAngle, endAngle) === 0)
+            throw new Error("An arc's start and end angles must differ");
+        return this.#add({
+            kind: "arc",
+            layer: this.#current,
+            center: pt(center),
+            radius: positive(radius, "radius"),
+            startAngle,
+            endAngle,
+        });
+    }
+    text(at, value, options = {}) {
+        if (/[\r\n]/.test(value))
+            throw new Error("Text must be a single line");
+        return this.#add({
+            kind: "text",
+            layer: this.#current,
+            at: pt(at),
+            value,
+            height: positive(options.height ?? 0.125, "height"),
+            rotation: num(options.rotation ?? 0, "rotation"),
+        });
+    }
+    build() {
+        return { units: this.units, layers: [...this.#layers.values()], entities: [...this.#entities] };
+    }
+    #add(entity) {
+        this.#entities.push(entity);
+        return this;
+    }
+}
+export function createDrawing(options) {
+    return new DrawingBuilder(options);
+}
+/** Counterclockwise sweep from start to end, in degrees, within [0, 360). */
+export function sweep(startAngle, endAngle) {
+    return (((endAngle - startAngle) % 360) + 360) % 360;
+}
+function num(value, label) {
+    if (!Number.isFinite(value))
+        throw new Error(`${label} must be a finite number`);
+    return value;
+}
+function positive(value, label) {
+    if (num(value, label) <= 0)
+        throw new Error(`${label} must be greater than 0`);
+    return value;
+}
+function pt(point) {
+    return [num(point[0], "x"), num(point[1], "y")];
+}

package/dist/dxf.d.ts

@@ -0,0 +1,9 @@
+import type { Drawing } from "./drawing.ts";
+/**
+ * Writes an ASCII DXF (AC1009, R12). R12 is the most widely readable DXF:
+ * AutoCAD, BricsCAD, LibreCAD, QCAD and most converters open it.
+ *
+ * R12 has no header variable for drawing units, so coordinates are written as
+ * plain numbers in the drawing's units and `drawing.units` is not written.
+ */
+export declare function toDXF(drawing: Drawing): string;

package/dist/dxf.js

@@ -0,0 +1,112 @@
+import { fmt } from "./format.js";
+/**
+ * Writes an ASCII DXF (AC1009, R12). R12 is the most widely readable DXF:
+ * AutoCAD, BricsCAD, LibreCAD, QCAD and most converters open it.
+ *
+ * R12 has no header variable for drawing units, so coordinates are written as
+ * plain numbers in the drawing's units and `drawing.units` is not written.
+ */
+export function toDXF(drawing) {
+    const out = [];
+    const g = (code, value) => {
+        out.push(String(code), typeof value === "number" ? fmt(value) : value);
+    };
+    g(0, "SECTION");
+    g(2, "HEADER");
+    g(9, "$ACADVER");
+    g(1, "AC1009");
+    g(0, "ENDSEC");
+    g(0, "SECTION");
+    g(2, "TABLES");
+    g(0, "TABLE");
+    g(2, "LTYPE");
+    g(70, "1");
+    g(0, "LTYPE");
+    g(2, "CONTINUOUS");
+    g(70, "0");
+    g(3, "Solid line");
+    g(72, "65");
+    g(73, "0");
+    g(40, "0.0");
+    g(0, "ENDTAB");
+    g(0, "TABLE");
+    g(2, "LAYER");
+    g(70, String(drawing.layers.length));
+    for (const layer of drawing.layers) {
+        g(0, "LAYER");
+        g(2, layer.name);
+        g(70, "0");
+        g(62, String(layer.color));
+        g(6, "CONTINUOUS");
+    }
+    g(0, "ENDTAB");
+    g(0, "ENDSEC");
+    g(0, "SECTION");
+    g(2, "ENTITIES");
+    for (const entity of drawing.entities)
+        writeEntity(entity, g);
+    g(0, "ENDSEC");
+    g(0, "EOF");
+    return out.join("\r\n") + "\r\n";
+}
+function writeEntity(e, g) {
+    switch (e.kind) {
+        case "line":
+            g(0, "LINE");
+            g(8, e.layer);
+            g(10, e.from[0]);
+            g(20, e.from[1]);
+            g(30, 0);
+            g(11, e.to[0]);
+            g(21, e.to[1]);
+            g(31, 0);
+            return;
+        case "polyline":
+            g(0, "POLYLINE");
+            g(8, e.layer);
+            g(66, "1");
+            g(10, 0);
+            g(20, 0);
+            g(30, 0);
+            g(70, e.closed ? "1" : "0");
+            for (const [x, y] of e.points) {
+                g(0, "VERTEX");
+                g(8, e.layer);
+                g(10, x);
+                g(20, y);
+                g(30, 0);
+            }
+            g(0, "SEQEND");
+            g(8, e.layer);
+            return;
+        case "circle":
+            g(0, "CIRCLE");
+            g(8, e.layer);
+            g(10, e.center[0]);
+            g(20, e.center[1]);
+            g(30, 0);
+            g(40, e.radius);
+            return;
+        case "arc":
+            g(0, "ARC");
+            g(8, e.layer);
+            g(10, e.center[0]);
+            g(20, e.center[1]);
+            g(30, 0);
+            g(40, e.radius);
+            g(50, e.startAngle);
+            g(51, e.endAngle);
+            return;
+        case "text":
+            g(0, "TEXT");
+            g(8, e.layer);
+            g(10, e.at[0]);
+            g(20, e.at[1]);
+            g(30, 0);
+            g(40, e.height);
+            g(1, e.value);
+            if (e.rotation !== 0)
+                g(50, e.rotation);
+            return;
+    }
+}

package/dist/format.d.ts

@@ -0,0 +1,2 @@
+/** Formats a coordinate with at most 6 decimals, no float noise, and no "-0". */
+export declare function fmt(value: number): string;

package/dist/format.js

@@ -0,0 +1,5 @@
+/** Formats a coordinate with at most 6 decimals, no float noise, and no "-0". */
+export function fmt(value) {
+    const rounded = Number(value.toFixed(6));
+    return Object.is(rounded, -0) ? "0" : String(rounded);
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createDrawing, DrawingBuilder, sweep, type Arc, type Circle, type Drawing, type DrawingOptions, type Entity, type Layer, type LayerOptions, type Line, type Point, type Polyline, type Text, type TextOptions, type Units, } from "./drawing.ts";
+export { toDXF } from "./dxf.ts";
+export { toSVG, type SvgOptions } from "./svg.ts";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createDrawing, DrawingBuilder, sweep, } from "./drawing.js";
+export { toDXF } from "./dxf.js";
+export { toSVG } from "./svg.js";

package/dist/svg.d.ts

@@ -0,0 +1,9 @@
+import { type Drawing } from "./drawing.ts";
+export interface SvgOptions {
+    /** Margin around the drawing's extents, in drawing units. Defaults to 2% of the larger side. */
+    readonly margin?: number;
+    /** Stroke width in screen pixels; it stays constant when the SVG scales. */
+    readonly strokeWidth?: number;
+}
+/** Renders a preview SVG. Model Y points up, so the drawing group flips Y. */
+export declare function toSVG(drawing: Drawing, options?: SvgOptions): string;

package/dist/svg.js

@@ -0,0 +1,108 @@
+import { sweep } from "./drawing.js";
+import { fmt } from "./format.js";
+/** Screen colors for the standard ACI colors 1 to 7. Other indexes draw in currentColor. */
+const ACI = {
+    1: "#ff0000",
+    2: "#ffff00",
+    3: "#00ff00",
+    4: "#00ffff",
+    5: "#0000ff",
+    6: "#ff00ff",
+    7: "currentColor",
+};
+/** Renders a preview SVG. Model Y points up, so the drawing group flips Y. */
+export function toSVG(drawing, options = {}) {
+    const [minX, minY, maxX, maxY] = extents(drawing.entities);
+    const margin = options.margin ?? Math.max(maxX - minX, maxY - minY, 1) * 0.02;
+    const x = minX - margin;
+    const y = -(maxY + margin);
+    const w = maxX - minX + margin * 2;
+    const h = maxY - minY + margin * 2;
+    const colors = new Map(drawing.layers.map((l) => [l.name, ACI[l.color] ?? "currentColor"]));
+    const stroke = options.strokeWidth ?? 1;
+    const body = drawing.entities
+        .map((e) => entityToSvg(e, colors.get(e.layer) ?? "currentColor"))
+        .join("\n    ");
+    return [
+        `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${fmt(x)} ${fmt(y)} ${fmt(w)} ${fmt(h)}">`,
+        `  <g transform="scale(1 -1)" fill="none" stroke-width="${fmt(stroke)}" vector-effect="non-scaling-stroke">`,
+        `    ${body}`,
+        `  </g>`,
+        `</svg>`,
+        ``,
+    ].join("\n");
+}
+function entityToSvg(e, color) {
+    const s = `stroke="${color}" vector-effect="non-scaling-stroke" data-layer="${esc(e.layer)}"`;
+    switch (e.kind) {
+        case "line":
+            return `<line x1="${fmt(e.from[0])}" y1="${fmt(e.from[1])}" x2="${fmt(e.to[0])}" y2="${fmt(e.to[1])}" ${s}/>`;
+        case "polyline": {
+            const tag = e.closed ? "polygon" : "polyline";
+            const points = e.points.map(([px, py]) => `${fmt(px)},${fmt(py)}`).join(" ");
+            return `<${tag} points="${points}" ${s}/>`;
+        }
+        case "circle":
+            return `<circle cx="${fmt(e.center[0])}" cy="${fmt(e.center[1])}" r="${fmt(e.radius)}" ${s}/>`;
+        case "arc": {
+            const [cx, cy] = e.center;
+            const a0 = rad(e.startAngle);
+            const a1 = rad(e.endAngle);
+            const large = sweep(e.startAngle, e.endAngle) > 180 ? 1 : 0;
+            const start = `${fmt(cx + e.radius * Math.cos(a0))} ${fmt(cy + e.radius * Math.sin(a0))}`;
+            const end = `${fmt(cx + e.radius * Math.cos(a1))} ${fmt(cy + e.radius * Math.sin(a1))}`;
+            // sweep-flag 1 is the positive-angle direction in local (Y-up) coordinates: counterclockwise.
+            return `<path d="M ${start} A ${fmt(e.radius)} ${fmt(e.radius)} 0 ${large} 1 ${end}" ${s}/>`;
+        }
+        case "text": {
+            // Undo the group's Y flip so the text reads upright, then apply CAD rotation.
+            const t = `translate(${fmt(e.at[0])} ${fmt(e.at[1])}) scale(1 -1)${e.rotation ? ` rotate(${fmt(-e.rotation)})` : ""}`;
+            return `<text transform="${t}" font-size="${fmt(e.height)}" font-family="monospace" fill="${color}" stroke="none" data-layer="${esc(e.layer)}">${esc(e.value)}</text>`;
+        }
+    }
+}
+/** Approximate extents. Arcs use their full circle; text assumes 0.6 × height per character. */
+function extents(entities) {
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    const add = (x, y) => {
+        minX = Math.min(minX, x);
+        minY = Math.min(minY, y);
+        maxX = Math.max(maxX, x);
+        maxY = Math.max(maxY, y);
+    };
+    for (const e of entities) {
+        switch (e.kind) {
+            case "line":
+                add(...e.from);
+                add(...e.to);
+                break;
+            case "polyline":
+                for (const p of e.points)
+                    add(...p);
+                break;
+            case "circle":
+            case "arc":
+                add(e.center[0] - e.radius, e.center[1] - e.radius);
+                add(e.center[0] + e.radius, e.center[1] + e.radius);
+                break;
+            case "text": {
+                const len = e.value.length * e.height * 0.6;
+                const r = rad(e.rotation);
+                add(...e.at);
+                add(e.at[0] + len * Math.cos(r), e.at[1] + len * Math.sin(r));
+                add(e.at[0] - e.height * Math.sin(r), e.at[1] + e.height * Math.cos(r));
+                break;
+            }
+        }
+    }
+    return minX === Infinity ? [0, 0, 1, 1] : [minX, minY, maxX, maxY];
+}
+function rad(degrees) {
+    return (degrees * Math.PI) / 180;
+}
+function esc(value) {
+    return value.replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c] ?? c);
+}

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "tsdraft",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "2D CAD drawings as TypeScript: write the drawing in code, export DXF and SVG.",
+  "keywords": [
+    "2d",
+    "autocad",
+    "bricscad",
+    "cad",
+    "drafting",
+    "drawing",
+    "dxf"
+  ],
+  "homepage": "https://github.com/Surfside-Software/tsdraft#readme",
+  "bugs": {
+    "url": "https://github.com/Surfside-Software/tsdraft/issues"
+  },
+  "license": "MIT",
+  "author": "Stephen Frederick",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Surfside-Software/tsdraft.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "pnpm clean && tsc -p tsconfig.build.json",
+    "prepack": "pnpm build",
+    "check": "tsc --noEmit",
+    "check:tsrs": "tsrs --noEmit",
+    "lint": "oxlint",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "test": "node --test test/*.test.ts",
+    "test:package": "node scripts/package-smoke.ts",
+    "example": "node examples/site-plan.ts",
+    "verify": "pnpm fmt:check && pnpm lint && pnpm check && pnpm test && pnpm test:package"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "oxfmt": "0.77.0",
+    "oxlint": "1.92.0",
+    "tsrs": "0.23.0-ts7.1.0-beta",
+    "typescript": "7.0.2"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@12.11.2"
+}