tsdraft 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,111 @@
+# Changelog
+
+## 0.2.1
+
+Every fix below was found by opening tsdraft's output in AutoCAD 2025.
+
+- Fixed: text holding `\U+XXXX` or `\M+NXXXX` came out in AutoCAD as the
+  character those escapes stand for, so `\U+00B0` became a degree sign and
+  `\U+000A` put a line feed inside a single-line text. Both DXF versions now
+  write such a backslash so that AutoCAD holds the text as the drawing has it
+  when it opens the file. AutoCAD decodes the text after all once it has saved
+  the drawing itself and opened it again: `\M+NXXXX` after a save as DWG, and
+  `\U+XXXX` too after a save as DXF.
+- Fixed: a size too small for the 6 decimals tsdraft writes was written as 0.
+  AutoCAD gave such a text its default height, and held such a circle or arc
+  with radius 0. A radius, text height or rectangle size that would be written
+  as 0 is now an error, in the compiler for a literal and when the code runs.
+  `rect()` also throws when a side is lost because two corners round together.
+- Fixed: AutoCAD reads only two exponent digits from DXF, so it took a number
+  written as `1e+100` for `1e+10`, with no `AUDIT` error. A coordinate, size or
+  text rotation of 1e100 or more is now an error, in the compiler for a size
+  written as a literal and when the code runs. The R2018 writer also caps the
+  extents and the view height it works out, which could pass 1e100 for a
+  drawing whose own numbers are all smaller.
+- Fixed: an arc within 0.000001 degrees of a full turn was written with equal
+  angles, which AutoCAD holds as an arc of no length. It is now an error. An arc
+  angle that rounds up to 360 is written as 0.
+- Fixed: `toDXF` wrote layer `0` wherever the drawing listed it, and `AUDIT`
+  reported "Layer zero name found at incorrect index" when another layer came
+  first. Layer `0` is now written first.
+- Fixed: `lint` matched layer names with JavaScript's `toLowerCase()`, which
+  AutoCAD does not use. It accepted an entity on `οδος` for a layer `ΟΔΟΣ`,
+  where AutoCAD makes a second layer. `lint` and the builder now compare names
+  as AutoCAD does. The README lists the pairs that differ.
+- Fixed: two layers such as `ΟΔΟΣ` and `οδος`, which AutoCAD keeps apart but
+  its `AUDIT` reports as a duplicate name, are now an error.
+- Fixed: AutoCAD discarded a drawing whose layer name had a zero-width space,
+  another invisible formatting character, a letterlike symbol such as the ohm
+  sign U+2126, or a Glagolitic, Coptic, Tifinagh, Georgian Supplement, Latin
+  Extended-C or Ethiopic Extended letter. Those names are now errors, in the
+  compiler for a literal and when the code runs. The README lists them.
+- Fixed: `lint` threw a `RangeError` on a polyline of about 100,000 points or
+  more.
+- Fixed: a layer name that starts or ends with a no-break space, or another
+  space outside ASCII, threw when the code ran, though the compiler accepted
+  the literal and AutoCAD accepts the name. Only an ASCII space is refused now.
+- Fixed: AutoCAD replaced the private-use characters U+E800 to U+E8FF in text
+  and layer names. They are now errors.
+- Fixed: `toSVG` drew nothing for an arc so close to a full turn that its ends
+  rounded to one point, and ignored a layer's color when an entity spelled the
+  layer's name in another case.
+- Changed: a `DrawingError` message starts "The drawing has 3 problems:" and no
+  longer names DXF, because code other than `toDXF` uses it to refuse a drawing.
+- Changed: `lint` messages for a bad radius or height read "radius: This value
+  must be greater than 0", the wording the compiler uses for a literal.
+- `lint` warns about a polyline or an arc with no length, as it does for a line,
+  and about a line, polyline or arc that loses its length to rounding.
+- `lint` warns about text that contains `%%`, which AutoCAD stores as written
+  but draws as a control code: `%%d` is drawn as a degree sign.
+- `pnpm test:cad` covers each fix above, and checks every character `lint`
+  accepts in text and in layer names, and each form of number the writers
+  print, against AutoCAD.
+
+## 0.2.0
+
+0.1.1 was never published, so its changes ship here too.
+
+Every fix below comes from opening tsdraft's output in AutoCAD 2025.
+
+- `createDrawing({ dxf: "R2018" })` targets AC1032, the DXF version AutoCAD has
+  used since 2018. It writes handles, owner links, the standard tables, model
+  and paper space blocks, plot styles and `$INSUNITS`. R12 stays the default.
+  `toDXF(drawing)` writes the drawing's version, and
+  `toDXF(drawing, { version })` writes another.
+- Layer names, layer colors, radii, text heights and rectangle sizes written as
+  literals are checked by the compiler. The same checks run when the code runs.
+- `lint(drawing, { version })` returns every problem in a drawing. `toDXF`
+  throws a `DrawingError` listing the errors instead of writing a file AutoCAD
+  would reject.
+- Fixed: AutoCAD discarded R12 drawings whose layer names had spaces, dots or
+  other punctuation, or more than 31 characters. Those names are now errors in
+  an R12 drawing and allowed in an R2018 drawing.
+- Fixed: a layer name containing a line break wrote extra records into the
+  file. Commas, carets and leading or trailing spaces are rejected too.
+- Fixed: AutoCAD discarded any drawing with a `^` in its text. A caret is now
+  escaped.
+- Fixed: R12 text outside ASCII came out garbled. It is now written as
+  `\U+XXXX` escapes.
+- Fixed: arc angles outside 0 to 360 failed `AUDIT`. Angles are now stored from
+  0 up to 360.
+- Fixed: `wall` and `WALL` were two layers, and AutoCAD kept only the first.
+  They are now one layer.
+- Text with control characters, or with emoji and other characters above
+  U+FFFF, is rejected, because AutoCAD cannot read it.
+- Unknown units, and rectangle sizes of 0 or less, are rejected.
+- Breaking: a `Drawing` now has a required `dxf` field, and R12 layer names
+  AutoCAD rejects now throw (see above).
+- `pnpm test:cad` runs the output through AutoCAD over ssh.
+- Published from GitHub Actions through npm trusted publishing, with a
+  provenance attestation linking the package to its source commit.
+- `tsdraft/package.json` can be imported or resolved.
+- The package now includes this changelog.
+
+## 0.1.0
+
+First release.
+
+- `createDrawing()` builds a drawing with layers (AutoCAD Color Index colors),
+  lines, polylines, rectangles, circles, arcs and single-line text.
+- `toDXF()` writes ASCII DXF R12 (AC1009) with layer and linetype tables.
+- `toSVG()` writes an SVG preview with model Y pointing up.

package/README.md

@@ -1,14 +1,18 @@
 # tsdraft
 
-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.
+Write 2D CAD drawings in TypeScript and export them as DXF, the exchange format
+that AutoCAD, BricsCAD and most other CAD programs open, or as SVG for a quick
+preview. A drawing is a program, so dimensions can come from variables, drawings
+can share code, and changes show up as diffs.
 
-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.
+## Status
+
+tsdraft is at an early stage. It draws layers, lines, polylines, rectangles,
+circles, arcs and single-line text. It does not yet have dimensions, hatches,
+blocks, linetypes, lineweights or paper space layouts. It writes DXF, not DWG.
+
+The DXF output is tested by opening it in AutoCAD 2025 and running `AUDIT`. It
+has not been tested in BricsCAD or any other CAD program yet.
 
 ## Install
 
@@ -42,10 +46,159 @@ 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.
+Numbers are written with 6 decimals, in DXF and in SVG. The checks below judge
+a drawing as it will be written, so a size too small to survive the rounding is
+an error and a line that rounds down to a point is a warning. Every number must
+also be under 1e100 in size. AutoCAD reads only two exponent digits from DXF, so
+it would take `1e+100` for `1e+10` and report nothing.
+
+## DXF versions
+
+A drawing is written for one DXF version. `createDrawing()` targets R12, the
+oldest version still in common use, which nearly every CAD program can open.
+`createDrawing({ dxf: "R2018" })` targets the version AutoCAD has used since
+2018, which is the newest one Autodesk has published. `toDXF(drawing)` writes
+the drawing's version, and `toDXF(drawing, { version })` writes another one.
+
+|               | `"R12"`, the default                               | `"R2018"`                                              |
+| ------------- | -------------------------------------------------- | ------------------------------------------------------ |
+| Format code   | AC1009                                             | AC1032                                                 |
+| Drawing units | Not stored. Set them in CAD with `UNITS`.          | Stored in `$INSUNITS`.                                 |
+| Polylines     | `POLYLINE` with `VERTEX` records                   | `LWPOLYLINE`                                           |
+| Text          | ASCII, with `\U+XXXX` escapes for other characters | UTF-8                                                  |
+| Layer names   | Up to 31 letters, digits, `$`, `-` and `_`         | Up to 255 characters, with the exceptions listed below |
+
+Choose R2018 when the drawing will be inserted into another drawing, because CAD
+needs the stored units to scale it correctly. AutoCAD shows layer names from an
+R12 file in upper case.
+
+## Checks
+
+AutoCAD discards a whole drawing over one bad layer name, and it reports no
+line of your code when it does. tsdraft checks the rules AutoCAD enforces at
+three points, so the mistake shows up where you made it.
+
+1. **In the editor.** Layer names, colors and sizes written as literals are
+   checked by the TypeScript compiler, and the error message says what is wrong.
+2. **When the code runs.** The builder throws at the call that breaks a rule.
+   This covers values the compiler cannot see, such as a name read from a file.
+3. **Before export.** `lint(drawing)` returns every problem in a drawing, and
+   `toDXF` throws a `DrawingError` that lists them instead of writing a file
+   AutoCAD would reject.
+
+```ts
+const d = createDrawing({ units: "ft" });
+
+d.layer("A WALL");
+// error TS2345: Argument of type '"A WALL"' is not assignable to parameter of
+// type '"R12 layer names can only use letters, digits, $, - and _. Use DXF
+// version \"R2018\" for other characters"'.
+
+createDrawing({ dxf: "R2018" }).layer("A WALL"); // fine
+
+lint(drawing, { version: "R12" }); // check a drawing against another version
+```
+
+The rules:
+
+- Layer names cannot be empty, start or end with a space, or contain a line
+  break or any of ``< > / \ " : ; ? * | = ` ^ ,``. R12 names have the tighter
+  limits in the table above.
+- Layer names cannot contain the other characters AutoCAD refuses in a name. It
+  discards the drawing over any of them, and they are listed under
+  [Layer name characters](#layer-name-characters).
+- `wall` and `WALL` are the same layer, as in CAD. The first spelling is kept.
+  tsdraft compares names the way AutoCAD does, which is not the way JavaScript
+  does: see [Layer names and case](#layer-names-and-case).
+- Layer colors are whole numbers from 1 to 255.
+- Radii, text heights and rectangle sizes are greater than 0, and large enough
+  not to be written as 0. Anything from 0.000001 up is safe. AutoCAD gives text
+  of height 0 its default height.
+- Text is a single line. It cannot contain emoji or other characters above
+  U+FFFF, because AutoCAD cannot read them from DXF, or the private-use
+  characters U+E800 to U+E8FF, which AutoCAD replaces.
+- Coordinates, sizes and text rotations are under 1e100 in size, because
+  AutoCAD reads only two exponent digits from DXF.
+- Arc angles are stored from 0 up to 360, so -90 becomes 270. An arc cannot come
+  within 0.000001 degrees of a full turn, because its two angles would be
+  written the same and AutoCAD holds such an arc as having no length. Draw a
+  circle instead.
+
+`lint` also returns warnings. Warnings do not stop an export. They are:
+
+- A line, a polyline or an arc that has no length, or has none once its numbers
+  are rounded.
+- Text that contains `%%`. AutoCAD stores the text as written but reads `%%` as
+  the start of a control code when it draws it: `%%d` is drawn as a degree sign
+  and `%%%` as one percent sign.
+
+`toDXF` throws a `DrawingError` for errors only. Its `diagnostics` property holds
+them, and other code may throw one to refuse a drawing for its own reasons.
+
+### Text
+
+When AutoCAD opens tsdraft's DXF, it holds each text exactly as the drawing has
+it. tsdraft escapes what DXF would otherwise read as something else: a caret,
+and a backslash that starts `\U+XXXX` or `\M+NXXXX`, which AutoCAD decodes into
+a character. A text `\U+00B0` reaches AutoCAD as those seven characters and not
+as a degree sign. Write the character itself, `°`, to get the character.
+
+That lasts until AutoCAD saves the drawing, because AutoCAD does not escape these
+sequences in what it writes. After it saves as DWG and opens the file again, a
+text `\M+18140` holds the character U+3000. After it saves as DXF and opens
+that, `\U+00B0` holds a degree sign as well. tsdraft cannot change this.
+
+### Layer names and case
+
+AutoCAD lower-cases a layer name one character at a time, from a table of its
+own that is older and smaller than Unicode's. An entity on `mixedcase`, `café`,
+`αβγ` or `СЛОЙ` goes on a layer declared as `MixedCase`, `CAFÉ`, `ΑΒΓ` or `Слой`,
+and `lint` accepts it. AutoCAD does not pair these, and `lint` reports the
+entity's layer as undefined:
+
+- `ΟΔΟΣ` and `οδος`, because of the final sigma `ς`. `οδοσ` does match.
+- `STRASSE` and `straße`, and `TITLE` and `tıtle` with a dotless `ı`.
+- `Ÿ` and `ÿ`, `İ` and `i`, and the title-case digraphs such as `Dž`.
+- Georgian, Cherokee and most other letters that gained a case after Unicode
+  5.1.
+
+Declaring both spellings as layers is an error too for some of these pairs,
+among them `ΟΔΟΣ` and `οδος`, `Ÿ` and `ÿ`, and `ß` and `ẞ`. AutoCAD keeps two
+layers, and its `AUDIT` then reports a duplicate name.
+
+`AUDIT` compares names more loosely than `lint` can follow in full. It reports
+each of these pairs as a duplicate name while AutoCAD keeps both layers, and
+`lint` does not catch them:
+
+- A letter and the two letters it stands for: `ß` and `ss`, `æ` and `ae`, `œ`
+  and `oe`, `ij` and `ij`, `fi` and `fi`, `dž` and `dž`, `þ` and `th`.
+- A composed letter such as `é` and its decomposed form.
+- Names that differ only by a soft hyphen.
+
+### Layer name characters
+
+AutoCAD refuses these characters in a layer name, so `lint` does too. Over any
+of them but the last row's, AutoCAD discards the whole drawing. All are outside
+ASCII, so they only concern R2018 drawings.
+
+| Characters                                                                 | What they are                                              |
+| -------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| U+0080 to U+009F                                                           | C1 control characters                                      |
+| U+0600 to U+0603, U+06DD, U+070F, U+17B4, U+17B5                           | Arabic, Syriac and Khmer formatting characters             |
+| U+200B to U+200F, U+202A to U+202E, U+2060 to U+2064, U+206A to U+206F     | Zero-width spaces and joiners, and text direction controls |
+| U+FEFF, U+FFF9 to U+FFFB                                                   | The byte order mark and annotation characters              |
+| U+2071, U+207F, U+2090 to U+2094                                           | Superscript and subscript letters                          |
+| Letters in U+2102 to U+214E, such as `ℓ`, `ℕ`, the ohm sign and the kelvin | Letterlike symbols. Use the Greek `Ω`, U+03A9, for ohms.   |
+| U+2180 to U+2188                                                           | Roman numeral characters                                   |
+| U+2C00 to U+2C5E, except U+2C2F                                            | Glagolitic                                                 |
+| U+2C60 to U+2C7D, except U+2C70                                            | Latin Extended-C                                           |
+| U+2C80 to U+2CE4                                                           | Coptic                                                     |
+| U+2D00 to U+2D25                                                           | Georgian Supplement                                        |
+| U+2D30 to U+2D65, U+2D6F                                                   | Tifinagh                                                   |
+| Letters in U+2D80 to U+2DDE                                                | Ethiopic Extended                                          |
+| U+E800 to U+E8FF                                                           | Private use. AutoCAD replaces these and keeps the drawing. |
+
+`src/layers.ts` has the exact list.
 
 ## Development
 
@@ -55,9 +208,17 @@ 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 example   # writes a site plan to examples/out/ as DXF and SVG
 ```
 
+`pnpm test:cad` opens the output in AutoCAD. It needs
+`TSDRAFT_CAD_SSH=user@host`, an ssh login to a WSL shell on a Windows machine
+that has AutoCAD. Each test drawing runs in AutoCAD's headless console, which
+runs `AUDIT` and saves the drawing back as DXF. The script then compares that
+file with what was drawn. Run it after any change to a DXF writer, because
+AutoCAD rejects files that DXF parsing libraries accept. Some of its cases write
+a file `toDXF` would refuse, to show that AutoCAD does what the rule says.
+
 `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.
@@ -68,6 +229,16 @@ 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.
 
+## Releasing
+
+Bump `version` in `package.json` and add a CHANGELOG entry in a pull request.
+After it merges, publish a GitHub release tagged `v<version>` on the merge
+commit. The Release workflow checks that the tag matches the version, runs
+`pnpm verify` and publishes to npm through
+[trusted publishing](https://docs.npmjs.com/trusted-publishers), so no npm token
+is stored anywhere. npm adds a provenance attestation that links each version to
+the commit it was built from.
+
 ## License
 
 [MIT](LICENSE)

package/dist/drawing.d.ts

@@ -1,3 +1,4 @@
+import { type LayerColor, type LayerName, type Positive } from "./rules.ts";
 /** A model-space point, in drawing units. Y points up, as in CAD. */
 export type Point = readonly [x: number, y: number];
 /**
@@ -5,6 +6,15 @@ export type Point = readonly [x: number, y: number];
  * the DXF R12 writer has no field for it, so set units in CAD after opening.
  */
 export type Units = "in" | "ft" | "mm" | "cm" | "m";
+/**
+ * DXF versions tsdraft writes.
+ *
+ * - `"R12"` (AC1009) opens in nearly every CAD program, but stores no units and
+ *   limits layer names to 31 letters, digits, `$`, `-` and `_`.
+ * - `"R2018"` (AC1032) is the newest published version and the one AutoCAD has
+ *   used since 2018. It records the drawing's units.
+ */
+export type DxfVersion = "R12" | "R2018";
 export interface Layer {
     readonly name: string;
     /** AutoCAD Color Index, 1 to 255. 7 is white on dark backgrounds, black on light. */
@@ -28,7 +38,7 @@ export interface Circle extends EntityBase {
     readonly center: Point;
     readonly radius: number;
 }
-/** Angles are in degrees, counterclockwise from +X, as in DXF. */
+/** Angles are in degrees from 0 up to 360, counterclockwise from +X, as in DXF. */
 export interface Arc extends EntityBase {
     readonly kind: "arc";
     readonly center: Point;
@@ -48,39 +58,63 @@ export interface Text extends EntityBase {
 export type Entity = Line | Polyline | Circle | Arc | Text;
 export interface Drawing {
     readonly units: Units;
+    /** The DXF version the drawing is written for. `toDXF` uses it unless told otherwise. */
+    readonly dxf: DxfVersion;
     readonly layers: readonly Layer[];
     readonly entities: readonly Entity[];
 }
-export interface DrawingOptions {
+export interface DrawingOptions<V extends DxfVersion = DxfVersion> {
+    /** Defaults to `"in"`. */
     readonly units?: Units;
+    /** The DXF version to check the drawing against and export. Defaults to `"R12"`. */
+    readonly dxf?: V;
 }
-export interface LayerOptions {
-    readonly color?: number;
+export interface LayerOptions<C extends number = number> {
+    /** AutoCAD Color Index, 1 to 255. */
+    readonly color?: LayerColor<C>;
 }
-export interface TextOptions {
-    readonly height?: number;
+export interface TextOptions<H extends number = number> {
+    readonly height?: Positive<H>;
+    /** Degrees counterclockwise. */
     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.
+ *
+ * Mistakes written as literals, such as a layer name the DXF version does not
+ * allow or a negative radius, are compile errors. The same checks run again
+ * when the code runs, for values the compiler cannot see.
  */
-export declare class DrawingBuilder {
+export declare class DrawingBuilder<V extends DxfVersion = "R12"> {
     #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;
+    readonly dxf: V;
+    constructor(options?: DrawingOptions<V>);
+    /**
+     * Defines or updates a layer. With `draw`, entities drawn inside it go on this layer.
+     * `wall` and `WALL` are the same layer, as in CAD, and keep the first spelling.
+     */
+    layer<N extends string, C extends number = number>(name: LayerName<N, V>, options?: LayerOptions<C>, 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;
+    rect<W extends number, H extends number>(corner: Point, width: Positive<W>, height: Positive<H>): this;
+    circle<R extends number>(center: Point, radius: Positive<R>): this;
+    /**
+     * Arc from `startAngle` counterclockwise to `endAngle`. Angles are stored
+     * from 0 up to 360, so -90 becomes 270, because AutoCAD's AUDIT rejects
+     * angles outside that range.
+     *
+     * Angles are written with 6 decimals. An arc within 0.000001 degrees of a
+     * full turn would be written with equal angles, which AutoCAD holds as an
+     * arc of no length, so it throws: draw a circle instead.
+     */
+    arc<R extends number>(center: Point, radius: Positive<R>, startAngle: number, endAngle: number): this;
+    text<H extends number = number>(at: Point, value: string, options?: TextOptions<H>): this;
     build(): Drawing;
 }
-export declare function createDrawing(options?: DrawingOptions): DrawingBuilder;
+export declare function createDrawing<V extends DxfVersion = "R12">(options?: DrawingOptions<V>): DrawingBuilder<V>;
 /** 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

@@ -1,28 +1,63 @@
+import { fmt, written } from "./format.js";
+import { layerAuditKey, layerKey } from "./layers.js";
+import { arcProblem, layerColorProblem, magnitudeProblem, layerNameProblem, layerTwinProblem, sizeProblem, textProblem, } from "./rules.js";
+const UNITS = ["in", "ft", "mm", "cm", "m"];
+const DXF_VERSIONS = ["R12", "R2018"];
 /**
  * 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.
+ *
+ * Mistakes written as literals, such as a layer name the DXF version does not
+ * allow or a negative radius, are compile errors. The same checks run again
+ * when the code runs, for values the compiler cannot see.
  */
 export class DrawingBuilder {
     units;
+    dxf;
+    /** Keyed by `layerKey`, because AutoCAD ignores case in layer names. */
     #layers = new Map([["0", { name: "0", color: 7 }]]);
+    /** The first layer name for each `layerAuditKey`, to find names AUDIT would call duplicates. */
+    #audited = new Map([["0", "0"]]);
     #entities = [];
     #current = "0";
     constructor(options = {}) {
-        this.units = options.units ?? "in";
+        const units = options.units ?? "in";
+        if (!UNITS.includes(units))
+            throw new Error(`Unknown units: ${JSON.stringify(units)}`);
+        const dxf = options.dxf ?? "R12";
+        if (!DXF_VERSIONS.includes(dxf)) {
+            throw new Error(`Unsupported DXF version: ${JSON.stringify(dxf)}`);
+        }
+        this.units = units;
+        this.dxf = dxf;
     }
-    /** Defines or updates a layer. With `draw`, entities drawn inside it go on this layer. */
+    /**
+     * Defines or updates a layer. With `draw`, entities drawn inside it go on this layer.
+     * `wall` and `WALL` are the same layer, as in CAD, and keep the first spelling.
+     */
     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 });
+        // The parameter type is the error message when a literal name is wrong, so read it as a string.
+        const requested = name;
+        const nameProblem = layerNameProblem(requested, this.dxf);
+        if (nameProblem)
+            throw new Error(`Layer ${JSON.stringify(requested)}: ${nameProblem}`);
+        const key = layerKey(requested);
+        const existing = this.#layers.get(key);
+        const auditKey = layerAuditKey(requested);
+        const twinProblem = layerTwinProblem(requested, this.#audited.get(auditKey) ?? requested);
+        if (twinProblem)
+            throw new Error(`Layer ${JSON.stringify(requested)}: ${twinProblem}`);
+        const color = options.color ?? existing?.color ?? 7;
+        const colorProblem = layerColorProblem(color);
+        if (colorProblem)
+            throw new Error(`Layer ${JSON.stringify(requested)}: ${colorProblem}`);
+        const layer = { name: existing?.name ?? requested, color };
+        this.#layers.set(key, layer);
+        if (!this.#audited.has(auditKey))
+            this.#audited.set(auditKey, layer.name);
         if (draw) {
             const previous = this.#current;
-            this.#current = name;
+            this.#current = layer.name;
             try {
                 draw();
             }
@@ -43,13 +78,18 @@ export class DrawingBuilder {
     /** Closed rectangle from its lower-left corner. */
     rect(corner, width, height) {
         const [x, y] = pt(corner);
-        num(width, "width");
-        num(height, "height");
+        const w = positive(width, "width");
+        const h = positive(height, "height");
+        // A side can still vanish in the file: a corner and the one across from it may round together.
+        if (written(x + w) === written(x))
+            throw new Error(lostSide("width", "x", x));
+        if (written(y + h) === written(y))
+            throw new Error(lostSide("height", "y", y));
         return this.polyline([
             [x, y],
-            [x + width, y],
-            [x + width, y + height],
-            [x, y + height],
+            [x + w, y],
+            [x + w, y + h],
+            [x, y + h],
         ], true);
     }
     circle(center, radius) {
@@ -60,34 +100,52 @@ export class DrawingBuilder {
             radius: positive(radius, "radius"),
         });
     }
+    /**
+     * Arc from `startAngle` counterclockwise to `endAngle`. Angles are stored
+     * from 0 up to 360, so -90 becomes 270, because AutoCAD's AUDIT rejects
+     * angles outside that range.
+     *
+     * Angles are written with 6 decimals. An arc within 0.000001 degrees of a
+     * full turn would be written with equal angles, which AutoCAD holds as an
+     * arc of no length, so it throws: draw a circle instead.
+     */
     arc(center, radius, startAngle, endAngle) {
-        num(startAngle, "startAngle");
-        num(endAngle, "endAngle");
-        if (sweep(startAngle, endAngle) === 0)
+        const start = turn(num(startAngle, "startAngle"));
+        const end = turn(num(endAngle, "endAngle"));
+        if (start === end)
             throw new Error("An arc's start and end angles must differ");
+        const problem = arcProblem(start, end);
+        if (problem)
+            throw new Error(problem);
         return this.#add({
             kind: "arc",
             layer: this.#current,
             center: pt(center),
             radius: positive(radius, "radius"),
-            startAngle,
-            endAngle,
+            startAngle: start,
+            endAngle: end,
         });
     }
     text(at, value, options = {}) {
-        if (/[\r\n]/.test(value))
-            throw new Error("Text must be a single line");
+        const problem = textProblem(value);
+        if (problem)
+            throw new Error(problem);
         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"),
+            rotation: kept(options.rotation ?? 0, "rotation"),
         });
     }
     build() {
-        return { units: this.units, layers: [...this.#layers.values()], entities: [...this.#entities] };
+        return {
+            units: this.units,
+            dxf: this.dxf,
+            layers: [...this.#layers.values()],
+            entities: [...this.#entities],
+        };
     }
     #add(entity) {
         this.#entities.push(entity);
@@ -99,18 +157,39 @@ export function createDrawing(options) {
 }
 /** Counterclockwise sweep from start to end, in degrees, within [0, 360). */
 export function sweep(startAngle, endAngle) {
-    return (((endAngle - startAngle) % 360) + 360) % 360;
+    return turn(endAngle - startAngle);
+}
+/** Brings an angle in degrees into [0, 360). */
+function turn(degrees) {
+    const wrapped = ((degrees % 360) + 360) % 360;
+    // A tiny negative angle rounds up to exactly 360.
+    return wrapped === 360 ? 0 : wrapped;
 }
 function num(value, label) {
     if (!Number.isFinite(value))
         throw new Error(`${label} must be a finite number`);
     return value;
 }
+/** Takes `unknown` because a `Positive<N>` parameter is a message string when the literal is wrong. */
 function positive(value, label) {
-    if (num(value, label) <= 0)
-        throw new Error(`${label} must be greater than 0`);
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`${label} must be a finite number`);
+    }
+    const problem = sizeProblem(value);
+    if (problem)
+        throw new Error(`${label}: ${problem}`);
+    return value;
+}
+function lostSide(size, axis, at) {
+    return `${size}: This value is too small at ${axis} = ${at}. Both sides of the rectangle are written as ${axis} = ${fmt(at)}, because tsdraft writes 6 decimals`;
+}
+/** A number the drawing keeps and the writers print, which AutoCAD must be able to read. */
+function kept(value, label) {
+    const problem = magnitudeProblem(num(value, label));
+    if (problem)
+        throw new Error(`${label}: ${problem}`);
     return value;
 }
 function pt(point) {
-    return [num(point[0], "x"), num(point[1], "y")];
+    return [kept(point[0], "x"), kept(point[1], "y")];
 }

package/dist/dxf-r12.d.ts

@@ -0,0 +1,11 @@
+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.
+ * R12 predates Unicode DXF, so text outside ASCII is written as `\U+XXXX`.
+ * Layer `0` is written first, wherever it is in `drawing.layers`.
+ */
+export declare function toDXFR12(drawing: Drawing): string;