tsdraft 0.2.2 → 0.4.0

package/CHANGELOG.md

@@ -1,14 +1,97 @@
 # Changelog
 
-## 0.2.2
+## 0.4.0
+
+- `fromPaper(length, "in" | "mm", { ratio, units })` turns a length on paper
+  into drawing units, to size text, symbols and dashes by how large they plot:
+  `fromPaper(3 / 32, "in", { ratio: 96, units: "ft" })` is 0.75. A wrong unit,
+  and a length or ratio of 0 or less, are compile errors as literals and thrown
+  errors otherwise. A result that would be written as 0, or is 1e100 or more,
+  throws.
+- `examples/site-plan.ts` is now the example sheet: a permit-style site plan for
+  an ARCH D sheet at 1" = 10', with property lines, setbacks, a building
+  footprint, dimensions, labels, site data, notes and a legend. Every text
+  height and annotation offset comes from `fromPaper`. Its default export is the drawing.
+- Breaking: a `Drawing` has `format: 0`, its format version, which is separate
+  from `dxf`. The builder sets it. A drawing written by hand needs it, and
+  `lint` reports one without it under the new rule `format`. Format 0 carries
+  no promise of stability.
+- Breaking: `LintRule` gained `format`, `id` and `duplicate-id`. Code that
+  switches over every rule, or uses `Record<LintRule, …>`, needs the three.
+- `toJSON(drawing)` writes a drawing as canonical JSON: the same drawing gives
+  the same string, whatever order its keys were set in.
+- `fromJSON(json)` reads a drawing from a JSON string or a parsed value. It
+  refuses a format version, a field or an entity kind it does not know, naming
+  each, then runs `lint`, and throws a `DrawingError`.
+- Entities take an `id` in their options: 1 to 64 letters, digits, `.`, `-` and
+  `_`. A malformed id and a second entity with the same id are builder errors
+  and `lint` errors, under the new rules `id` and `duplicate-id`. `toSVG` writes
+  the id as `data-id`.
+- A `Diagnostic` about an entity carries its `id`, and `call`, the file, line
+  and column of the call that drew it, when the drawing was built with
+  `createDrawing({ recordCalls: true })`. Setting
+  `globalThis.TSDRAFT_RECORD_CALLS = true` before a drawing's code runs turns
+  recording on for every builder that does not set the option, which is how a
+  tool that runs drawing files asks for it.
+- The builder's `layer`, `linetype` and entity methods now throw a
+  `DrawingError` with the same message as before. Its diagnostic has the rule,
+  the `id` and the `call` that broke it.
+- [docs/format.md](docs/format.md) describes all of the above.
 
-Found by opening tsdraft's output in AutoCAD 2025.
+## 0.3.0
+
+- Breaking: `createDrawing()` now targets DXF R2018. Pass `{ dxf: "R12" }` for
+  R12, which gets no new features.
+- Linetypes. `d.linetype({ name, description, pattern })` defines one, with
+  dashes as positive lengths, gaps as negative ones and dots as 0. `DASHED`,
+  `HIDDEN`, `CENTER`, `PHANTOM`, `DASHDOT` and `DOT` are exported with the
+  patterns AutoCAD loads from its `acad.lin`. `Continuous`, `ByLayer` and
+  `ByBlock` are in every drawing. `createDrawing({ linetypeScale })` sets
+  `$LTSCALE`.
+- Lineweights in millimetres, from AutoCAD's 24.
+- Layers take a `linetype`, a `lineweight`, and `off`, `frozen`, `locked` and
+  `plot`. Entities take a `linetype` and a `lineweight` of their own, and draw
+  ByLayer otherwise, as before.
+- `toSVG` draws dashes and pen weights, and leaves out layers that are off or
+  frozen. Its `strokeWidth` is now the width of a 0.25 mm line.
+- `toSVG` marks each entity's element with `data-entity`, its index in
+  `drawing.entities`, beside `data-layer`.
+- New rules, each a builder error and a `lint` error, and a compile error where
+  the literal shows it:
+  - a lineweight outside AutoCAD's list, which makes AutoCAD discard the drawing
+    when an entity has it;
+  - a linetype the drawing does not define, which makes AutoCAD discard it;
+  - a pattern of one length, which `AUDIT` reports, or more than 12, which makes
+    AutoCAD discard the drawing;
+  - a pattern length that is not 0 but is written as 0, which would turn a dash
+    or a gap into a dot, and a pattern whose lengths add up to 1e100 or more,
+    because the total is written too;
+  - defining `Continuous`, `ByLayer` or `ByBlock`, a layer whose linetype is
+    `ByLayer` or `ByBlock`, and freezing layer `0`, which is the current layer;
+  - a linetype scale of 0 or less, or one written as 0, which AutoCAD reads as
+    1, and a description over 249 characters, where AutoCAD cuts it;
+  - linetype names follow the rules of layer names, which AutoCAD holds them to,
+    and a name that `AUDIT` would report as a duplicate of `Continuous`,
+    `ByLayer` or `ByBlock`, such as one with a soft hyphen in it;
+  - a description with a control character, an emoji or a private-use
+    character from U+E800 to U+E8FF, as for text;
+  - an R12 drawing that defines a linetype, sets a linetype scale, or gives a
+    layer a linetype other than `Continuous`, a lineweight or a state, and an R12
+    entity with a linetype or lineweight of its own. Each message says to use
+    R2018.
+- A layer or an entity can be given a definition in place of a linetype name.
+  It is checked as `linetype()` checks one, and is defined if the drawing does
+  not have the name. If the drawing has the name with another pattern or
+  description, the builder throws: change a linetype with `linetype()`.
+- `lint` has the rules `linetype`, `duplicate-linetype`, `undefined-linetype`,
+  `lineweight` and `layer-state`, and a diagnostic names its `linetype`.
+
+## 0.2.2
 
 - Fixed: AutoCAD keeps two layers such as `straße` and `STRASSE` apart, but its
   `AUDIT` reports them as a duplicate name. `lint` now reports the second layer
   as a duplicate, and the builder throws at the `layer()` call. It does so for
-  the kinds of pair measured in AutoCAD, in either letter case and inside longer
-  names:
+  these kinds of pair, in either letter case and inside longer names:
   - a letter and the letters it stands for, such as `ß` and `ss`, `æ` and `ae`,
     `œ` and `oe`, `ij` and `ij`, `fi` and `fi`, `dž` and `dž`, and `þ` and `th`;
   - a composed character and its decomposed form, such as `é`;
@@ -21,13 +104,9 @@ Found by opening tsdraft's output in AutoCAD 2025.
 - When an entity names its layer by the other spelling of such a pair, the
   undefined-layer error now says which declared layer AutoCAD does not take it
   for. AutoCAD adds a layer for the entity, and `AUDIT` reports a duplicate name.
-- `pnpm test:cad` checks each kind of pair against AutoCAD, and 600 longer names
-  beside respellings of themselves.
 
 ## 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
@@ -81,16 +160,11 @@ Every fix below was found by opening tsdraft's output in AutoCAD 2025.
   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.
@@ -119,7 +193,6 @@ Every fix below comes from opening tsdraft's output in AutoCAD 2025.
 - 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.

package/README.md

@@ -1,40 +1,66 @@
-# tsdraft
-
-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.
-
-## 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
-
-```sh
-npm install tsdraft
-```
-
-tsdraft is an ES module and needs Node 22 or later.
-
-## Example
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Surfside-Software/tsdraft/main/docs/assets/tsdraft-logo-dark.svg">
+  <img src="https://raw.githubusercontent.com/Surfside-Software/tsdraft/main/docs/assets/tsdraft-logo-light.svg" alt="tsdraft" width="292" height="64">
+</picture>
+
+Write 2D CAD drawings in TypeScript and export them as DXF for CAD programs, or
+as SVG for a quick preview.
+
+[![npm](https://img.shields.io/npm/v/tsdraft?color=1aafc8)](https://www.npmjs.com/package/tsdraft)
+[![CI](https://img.shields.io/github/actions/workflow/status/Surfside-Software/tsdraft/ci.yml?branch=main&label=CI)](https://github.com/Surfside-Software/tsdraft/actions/workflows/ci.yml)
+[![License](https://img.shields.io/npm/l/tsdraft?color=1aafc8)](LICENSE)
+
+<a href="https://github.com/Surfside-Software/tsdraft/tree/main/examples">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Surfside-Software/tsdraft/main/docs/assets/outdoor-kitchen-dark.svg">
+    <img src="https://raw.githubusercontent.com/Surfside-Software/tsdraft/main/docs/assets/outdoor-kitchen-light.svg" alt="An outdoor kitchen drawn by tsdraft at 3/8 inch to the foot. On the left, an elevation of a stucco wall with an undercounter refrigerator, a built-in gas grill under a vent hood, a sink below a window and two shelves, with dimension strings and notes. On the right, a wall section through the grill from the footing to the attic: the reinforced masonry wall on its footing, the patio slab, the cabinet, the grill, the hood and its duct, and the ceilings with insulation." width="100%">
+  </picture>
+</a>
+
+The picture is what `toSVG` writes for
+[`examples/outdoor-kitchen.ts`](examples/outdoor-kitchen.ts), restyled for this
+page with a color for each layer. Its dimensions, leaders and stipple
+are small functions in the example that draw lines and text, and every size
+comes from a few parameters at the top of the file.
+[`examples`](examples) has both drawings and how to run them.
+
+A smaller drawing, start to finish:
 
 ```ts
-import { createDrawing, toDXF, toSVG } from "tsdraft";
+import { createDrawing, DASHED, PHANTOM, toDXF, toSVG } from "tsdraft";
+
+const lot = { width: 120, depth: 80 }; // ft
+const setbacks = { front: 20, side: 10, rear: 15 };
+const house = { width: 56, depth: 32 };
+const x = (lot.width - house.width) / 2;
+const y = setbacks.front + 5;
 
-const d = createDrawing({ units: "ft" });
+// Linetype patterns are in drawing units. At a scale of 4, DASHED draws dashes of 2 ft and
+// PHANTOM long dashes of 5 ft.
+const d = createDrawing({ units: "ft", linetypeScale: 4 });
 
-d.layer("C-PROP", { color: 3 }, () => {
-  d.rect([0, 0], 75, 120);
+d.layer("C-PROP", { color: 3, linetype: PHANTOM, lineweight: 0.5 }, () => {
+  d.rect([0, 0], lot.width, lot.depth);
+  d.text([2, -6], `LOT ${lot.width}' x ${lot.depth}'`, { height: 3 });
 });
-d.layer("A-BLDG", { color: 1 }, () => {
-  d.rect([17.5, 30], 40, 50);
-  d.text([19.5, 55], "PROPOSED RESIDENCE", { height: 2 });
+d.layer("C-SETB", { color: 4, linetype: DASHED, lineweight: 0.25 }, () => {
+  const { front, side, rear } = setbacks;
+  d.rect([side, front], lot.width - side * 2, lot.depth - front - rear);
+});
+d.layer("A-BLDG", { color: 1, lineweight: 0.7 }, () => {
+  d.rect([x, y], house.width, house.depth);
+  d.text([x + 2, y + house.depth / 2], "PROPOSED RESIDENCE", { height: 3, lineweight: 0.35 });
+});
+d.layer("C-PAVE", { color: 8, lineweight: 0.25 }, () => {
+  d.line([x + 40, y], [x + 40, -12]);
+  d.line([x + 52, y], [x + 52, -12]);
+});
+d.layer("C-ROAD", { color: 2, lineweight: 0.35 }, () => {
+  d.line([-10, -12], [lot.width + 10, -12]);
+  d.text([lot.width / 2 - 10, -18], "MAIN STREET", { height: 3 });
+});
+d.layer("V-TREE", { color: 3, lineweight: 0.18 }, () => {
+  for (let i = 0; i < 6; i++) d.circle([15 + i * 18, 72], 5);
 });
 
 const drawing = d.build();
@@ -42,35 +68,76 @@ const dxf = toDXF(drawing);
 const svg = toSVG(drawing);
 ```
 
+A drawing is a program, so dimensions can come from variables, drawings can
+share code, and changes show up as diffs.
+
 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.
+Linetypes and lineweights are set on a layer, and an entity draws ByLayer unless
+it is given its own. `DASHED`, `HIDDEN`, `CENTER`, `PHANTOM`, `DASHDOT` and `DOT`
+are AutoCAD's own definitions; `d.linetype({ name, pattern })` defines another,
+with dashes as positive lengths, gaps as negative ones and dots as 0. A
+lineweight is in millimetres.
 
-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.
+Text, symbols and dashes are sized by how large they plot. `fromPaper` turns a
+length on paper into drawing units for one scale, given as a plain ratio:
+
+```ts
+import { fromPaper } from "tsdraft";
+
+const view = { ratio: 120, units: "ft" } as const; // 1" = 10'
+const note = fromPaper(3 / 32, "in", view); // 0.9375 ft
+d.text([0, 0], "PROPERTY LINE", { height: note });
+```
+
+A paper unit other than `"in"` or `"mm"`, and a length or a ratio of 0 or less,
+are compile errors as literals and thrown errors otherwise. `fromPaper` also
+throws when the result would be written as 0 or is 1e100 or more.
+[`examples/site-plan.ts`](examples/site-plan.ts) is a whole sheet sized this
+way, and the file to copy to start a drawing.
+
+## Status
+
+tsdraft is at an early stage. It draws layers, lines, polylines, rectangles,
+circles, arcs and single-line text, with linetypes and lineweights, and layers
+that are off, frozen, locked or not plotted. It does not yet have dimensions,
+hatches, blocks or paper space layouts. It writes DXF, not DWG. The drawing at
+the top builds its dimensions, leaders and stipple from lines and text, so in
+CAD they are plain lines and text, not dimension or hatch objects.
+
+The rules tsdraft checks are AutoCAD's. Other CAD programs may hold a drawing to
+other rules.
+
+## Install
+
+```sh
+npm install tsdraft
+```
+
+tsdraft is an ES module and needs Node 22 or later.
 
 ## 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
+A drawing is written for one DXF version. `createDrawing()` targets R2018, the
+version AutoCAD has used since 2018, which is the newest one Autodesk has
+published. `createDrawing({ dxf: "R12" })` targets R12, the oldest version still
+in common use, which nearly every CAD program can open. `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 |
+|                           | `"R2018"`, the default                                                  | `"R12"`                                            |
+| ------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------- |
+| Format code               | AC1032                                                                  | AC1009                                             |
+| Drawing units             | Stored in `$INSUNITS`.                                                  | Not stored. Set them in CAD with `UNITS`.          |
+| Polylines                 | `LWPOLYLINE`                                                            | `POLYLINE` with `VERTEX` records                   |
+| Text                      | UTF-8                                                                   | ASCII, with `\U+XXXX` escapes for other characters |
+| Layer names               | Up to 255 characters, except those in [the rules](docs/rules.md#errors) | Up to 31 letters, digits, `$`, `-` and `_`         |
+| Linetypes, lineweights    | Yes                                                                     | No: only `Continuous`, and no lineweights          |
+| Layer off, frozen, locked | Yes, and not plotted                                                    | No                                                 |
 
-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.
+R12 gets no new features. Choose it only for a program that cannot read R2018.
+CAD needs the stored units to scale a drawing inserted into another, and AutoCAD
+shows layer names from an R12 file in upper case.
 
 ## Checks
 
@@ -87,148 +154,28 @@ three points, so the mistake shows up where you made it.
    AutoCAD would reject.
 
 ```ts
-const d = createDrawing({ units: "ft" });
+const d = createDrawing({ units: "ft", dxf: "R12" });
 
 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
+createDrawing().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.
-
-Where `AUDIT` would take the entity's spelling for the declared layer's, as it
-does for `STRASSE` and `straße`, the message says so. AutoCAD adds a layer for
-the entity, and `AUDIT` then reports a duplicate name.
-
-### Layer names that AUDIT calls duplicates
-
-AutoCAD's `AUDIT` compares layer names another way than AutoCAD looks them up.
-It reports "Duplicate name" for some pairs of layers that AutoCAD keeps as two.
-`lint` reports the second layer of such a pair as a duplicate, which is an
-error, for these kinds of pair. Each kind holds in either letter case and
-inside a longer name, so `Hauptstraße 12` and `HAUPTSTRASSE 12` are a pair.
-
-- Single letters: `σ` and `ς`, `Ÿ` and `ÿ`, `ß` and `ẞ`, a title-case digraph
-  such as `Dž` and `dž`, and a few others.
-- A letter and the letters it stands for: `ß` and `ss`, `æ` and `ae`, `œ` and
-  `oe`, `ij` and `ij`, `þ` and `th`, `dž` and `dž`, `lj` and `lj`, `nj` and `nj`,
-  `dz` and `dz`, the ligatures `ff`, `fi`, `fl`, `ffi`, `ffl` and `st`, and `ȸ`, `ȹ`,
-  `ʪ`, `ʫ`, `ꜳ`, `ꜵ`, `ꜷ`, `ꜹ`, `ꜽ`, `ꝏ` and `ᴂ`.
-- A composed character and its decomposed form, such as `é` and an `e` with a
-  combining acute accent, with its marks in any order Unicode counts as the
-  same, such as a dot below before or after a circumflex. Hangul syllables are
-  an exception, and so are 40 Arabic, Indic, Myanmar, kana, Hebrew and CJK
-  compatibility characters: `AUDIT` keeps those apart from their decomposed
-  forms.
-- A name with a soft hyphen, U+00AD, inside it or in front of it, and the same
-  name without.
-
-This is what was measured in AutoCAD 2025. It is not AutoCAD's whole comparison,
-so a drawing that passes `lint` can still get a "Duplicate name" from `AUDIT`.
-The rule is kept narrow so that it does not go the other way: in over 20,000
-pairs tried, `lint` reported none that `AUDIT` accepts. What it leaves out:
-
-- A name that ends with a soft hyphen and the same name without it, and a soft
-  hyphen in front of a combining mark or a Hangul jamo. `AUDIT` reports some of
-  those pairs and not others. It does not report `coop` and `coop` followed by a
-  soft hyphen. Two names that both end with a soft hyphen are compared like any
-  others.
-- Compatibility characters that `AUDIT` takes for their plain forms, such as a
-  modifier letter `ʰ` and `h`, `㎏` and `kg`, and Arabic presentation forms.
-- Characters that `AUDIT` cannot tell from an unassigned one, such as `Ԥ`,
-  U+0524, and `Ꙡ`, U+A660. Two names that differ only in such characters are
-  duplicates to it.
-
-### 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.
+## Reference
+
+- [Rules](docs/rules.md) lists what `lint` refuses and what it warns about.
+- [The Drawing format](docs/format.md) covers format 0, entity ids, `toJSON`
+  and `fromJSON`, and what a diagnostic carries.
+- [Layer names](docs/layer-names.md) explains how AutoCAD compares layer and
+  linetype names, and lists the pairs `AUDIT` calls duplicates and the
+  characters it refuses.
+- [Text](docs/text.md) explains what tsdraft escapes in text, and what AutoCAD
+  does with it after a save.
 
 ## Development
 
@@ -237,37 +184,19 @@ 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 a site plan to examples/out/ as DXF and SVG
+pnpm verify          # format check, lint, type check, tests, package smoke test
+pnpm example         # writes both examples to examples/out/ as DXF and SVG
+pnpm readme:drawing  # redraws the pictures in docs/assets/ from the examples
 ```
 
-`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.
-
-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.
-
-## 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.
+[docs/development.md](docs/development.md) covers the package smoke test, the
+TypeScript compilers and releasing.
+
+## Contributing
+
+tsdraft is developed in a private repository and published here through pull
+requests from the `export` branch. Issues are welcome.
+[`CONTRIBUTING.md`](CONTRIBUTING.md) says how changes arrive.
 
 ## License
 

package/dist/callsite.d.ts

@@ -0,0 +1,47 @@
+/** A place in a source file, as the JavaScript engine names it in a stack. */
+export interface CallSite {
+    /** A `file://` URL for an ES module in Node, a path for CommonJS, and a URL in a browser. */
+    readonly file: string;
+    /** Counted from 1. */
+    readonly line: number;
+    /** Counted from 1. */
+    readonly column: number;
+}
+/**
+ * A stack that the engine has captured and formats when `stack` is first read. `whole` is true
+ * for a stack that starts inside tsdraft, and false for one cut down to the caller's frame.
+ */
+export interface HeldCall {
+    readonly stack?: unknown;
+    readonly whole: boolean;
+}
+type Method = (...args: never[]) => unknown;
+/**
+ * Captures the call of the builder method `method` that is running now, to be read later, or
+ * returns undefined where the engine gives no stack. It must be called from the builder's file.
+ *
+ * With `Error.captureStackTrace` the engine leaves out every frame down to `method`, so only the
+ * caller's frame is captured. Without it, the whole stack of a new error is kept.
+ */
+export declare function holdCall(method: Method): HeldCall | undefined;
+/** The location a held call names, or undefined when its stack has none. */
+export declare function readCall(held: HeldCall | undefined): CallSite | undefined;
+/**
+ * The caller's frame in a whole stack captured by `holdCall`: the first frame in neither of
+ * tsdraft's two files on it, which are those of the first frame, `holdCall`'s own, and of the
+ * second, the builder's. Frames are told apart by file and not counted, because an engine may
+ * leave a frame out. When the caller's code is in one file with tsdraft, as in a bundle, no
+ * frame qualifies and there is no location, which is better than a line inside tsdraft.
+ */
+export declare function callerInStack(stack: string): CallSite | undefined;
+/** Keeps the calls that drew `entities`, one for each entity in order. */
+export declare function recordCalls(entities: readonly object[], calls: readonly (HeldCall | undefined)[]): void;
+/** The call that drew the entity at `index` of `entities`, when the builder recorded it. */
+export declare function callOf(entities: readonly object[], index: number): CallSite | undefined;
+/**
+ * The location of each frame of a stack, innermost first. V8 writes a frame as
+ * `at name (file:1:2)` or `at file:1:2`, and Firefox and Safari as `name@file:1:2`. A line that
+ * is no frame, such as the error's message, is left out.
+ */
+export declare function parseStack(stack: string): CallSite[];
+export {};