linework 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to this project are documented here. Format follows
+[Keep a Changelog](https://keepachangelog.com/); versions follow [SemVer](https://semver.org/).
+
+## [0.3.0] — 2026-07-24
+
+### Added
+- **More import formats** (`linework/import`): `parseSTL` (binary or ASCII — the
+  3D-printing format), `fromBufferGeometry` (adapt a three.js `BufferGeometry`
+  with no three.js dependency), and `fromOcct` (map [occt-import-js] STEP/IGES
+  results in — the CAD kernel stays an optional ~6 MB peer, not a dependency).
+- Live demo importer now accepts `.stl` alongside `.glb` / `.obj`.
+- 6 more tests (binary + ASCII STL round-trips, size-based binary detection,
+  three.js adapter indexed/non-indexed, occt result mapping). 25 total.
+
+[occt-import-js]: https://github.com/kovacsv/occt-import-js
+
+## [0.2.0] — 2026-07-24
+
+### Added
+- **Model import** (`linework/import`): turn a **glTF/GLB or OBJ mesh** into
+  linework strokes via feature-edge extraction — boundary edges plus sharp
+  creases (configurable `angle`), with vertices welded by position so shared
+  edges aren't mistaken for boundaries. `parseGLB` / `parseOBJ` / `featureEdges`
+  / `meshToShapes`, all zero-dependency; no Draco, geometry-only.
+- Live "drop a .glb / .obj" importer on the demo page, running entirely in the
+  browser, defaulting to a CC0 street lantern (5,394 tris → feature edges).
+- 6 new tests (cube edge count, crease threshold, boundary detection, vertex
+  welding, OBJ parsing, fitted emit). 19 total.
+
+[0.2.0]: https://github.com/isaacrowntree/linework/releases/tag/v0.2.0
+
+## [0.1.0] — 2026-07-18
+
+First public release.
+
+### Added
+- **Core renderer** (`linework`): the classic pipeline — 3D points → yaw/pitch
+  rotation → perspective projection → painter's-algorithm depth sorting → SVG
+  strings. Multi-stroke paths, plane-correct disc ellipses, backface-culled
+  quads, per-object sorting for animated part groups, depth cueing.
+- **Sketch layer** (`linework/sketch`): fluent authoring API with scoped context
+  blocks (`part` / `tag` / `bias`), chainable paths, a view-aware `cyl`, paper-space
+  notes, and the `scene()` replay idiom for animation frames.
+- **Orbit helper** (`linework/orbit`): drag-to-orbit boilerplate as a one-liner —
+  pointer capture, yaw/pitch clamping, rAF batching, double-click reset, and
+  reduced-motion-aware idle sway.
+- **Helpers** (`linework/helpers`): the primitive-builder middle layer.
+- 13 invariant tests, GitHub Actions CI, ESM build with type declarations.
+- Blueprint demo site rendered entirely by the library; server-side hero image
+  via `npm run hero`.
+
+[0.1.0]: https://github.com/isaacrowntree/linework/releases/tag/v0.1.0

package/LICENSE

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

@@ -0,0 +1,134 @@
+# linework
+
+[![ci](https://github.com/isaacrowntree/linework/actions/workflows/ci.yml/badge.svg)](https://github.com/isaacrowntree/linework/actions)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](package.json)
+[![live demo](https://img.shields.io/badge/demo-live-FFC24B.svg)](https://isaacrowntree.com/linework/)
+
+A tiny **true-3D renderer for annotated technical drawings**, output as plain SVG strings. Rotate → project → depth-sort → paint. Zero dependencies, ~180-line core, fully tested.
+
+### ▶ [Try the live demo — drop a 3D model, watch it become a drawing](https://isaacrowntree.com/linework/)
+
+[![A street lantern imported from a glTF mesh and rendered by linework as feature-edge linework](docs/import-lantern.svg)](https://isaacrowntree.com/linework/)
+
+*The lantern above was **imported from a glTF mesh** and rendered by the library itself, in Node, with zero client JavaScript. On the [live demo](https://isaacrowntree.com/linework/) it orbits under your pointer — and you can drop your own model.*
+
+## Why
+
+The category is empty. WebGL libraries (three.js) make *shaded surfaces* easy and annotated linework painful — thin strokes, dash patterns, line-weight hierarchy, text callouts are all fights. Pseudo-3D toys (Zdog — last release 2019) can't do text or fine-grained depth sorting. Nothing ships "parametric technical illustration": exploded diagrams, dimension lines, balloons, title blocks. This does exactly that, and nothing else.
+
+- **The classic pipeline, honestly implemented** — 3D points → yaw/pitch rotation → perspective projection → painter's-algorithm depth sorting *per frame* → SVG string. Paint order is computed, never authored.
+- **Shapes built for drawings, not games** — multi-stroke paths (hollow-tube outlines as one shape), discs that project to correct ellipses, backface-culled boxes, per-object sorting for animated parts.
+- **SVG strings are the point** — themeable with CSS variables, crawlable, printable, accessible, and **renderable server-side at build time**.
+- **Styling is yours** — the library emits class names you define; it never dictates a look.
+
+## The sketch layer — DX is a feature
+
+Authoring should read like drafting, not like assembling tuples. Context blocks scope parts, tags and layering over everything drawn inside them:
+
+```ts
+import { sketch, scene } from "linework/sketch";
+
+const s = sketch({ yaw: 0.5, pitch: 0.16, f: 1500, cx: 460, cy: 320 });
+
+s.box(300, 380, 320, 42, 40, 80);                    // base plate
+
+s.part("housing", 'class="prt"', () => {             // one <g>, one sort unit
+  s.cyl([460, 218], 70, 34, -34, "ink");             // bearing body
+  s.bias(0.6, () => s.cap([460, 218], 34, 32, "ink")); // bore, layered above
+});
+
+s.tube(9).M([180, 400]).Q([300, 420], 20, [420, 340], 10); // hollow frame tube
+
+s.note("320 mm", [460, 452]);                        // paper-space annotation
+el.innerHTML = s.render();                           // depth-sorted SVG
+```
+
+For animation, `scene()` gives you the frame-loop idiom — define once, replay with a new view per frame:
+
+```ts
+const draw = scene((s, { explode }) => { /* build with s.* */ });
+el.innerHTML = draw({ yaw, pitch, f: 1500, cx: 460, cy: 320 }, { explode });
+// ~1 ms for a few hundred shapes — drag-to-orbit rebuilds are free
+```
+
+Prefer bare metal? `linework` exports the raw `Shape` types + `render()`/`xform()`, and `linework/helpers` sits in between.
+
+## Import a 3D model → a technical drawing
+
+`linework/import` turns a **3D mesh — glTF/GLB, OBJ, STL, or a three.js `BufferGeometry` — into linework strokes**. A shaded model carries no lines — its form lives in where the surface bends — so it recovers exactly the lines a draftsperson would draw: the outline and the hard creases, nothing from the smooth interior of a face. The result drops straight into `render()` and rotates like any other scene.
+
+*(That lantern in the header is exactly this: a CC0 glTF — 5,394 triangles of shaded mesh → 2,479 feature edges → rotatable line drawing, in one `meshToShapes()` call. [Drop your own .glb on the demo](https://isaacrowntree.com/linework/).)*
+
+```ts
+import { parseGLB, meshToShapes } from "linework/import";
+import { render } from "linework";
+
+const meshes = parseGLB(await file.arrayBuffer());          // parseOBJ · parseSTL · fromBufferGeometry
+const shapes = meshToShapes(meshes, {
+  angle: 25,                                                // crease threshold°
+  fit: { cx: 400, cy: 300, size: 440 },                     // fit into a screen box
+});
+el.innerHTML = render(shapes, { yaw: 0.6, pitch: 0.35, f: 1400, cx: 400, cy: 300 });
+```
+
+`featureEdges(mesh)` is exposed on its own if you want the raw edge list. Vertices are welded by position first, so meshes that split a shared edge across primitives still sort as one surface. **No Draco**, and geometry-only — textures and materials are ignored.
+
+**Formats:**
+
+| Input | Function | Notes |
+|---|---|---|
+| glTF / GLB | `parseGLB(buffer)` | embedded buffers, node transforms; no Draco |
+| OBJ | `parseOBJ(text)` | fan-triangulated |
+| STL | `parseSTL(buffer \| text)` | binary or ASCII; the 3D-printing format |
+| three.js | `fromBufferGeometry(geo)` | reads the typed arrays; no three.js dependency |
+| **STEP / IGES** | `fromOcct(result)` | via [occt-import-js](https://github.com/kovacsv/occt-import-js) (OpenCASCADE WASM) — you bring the kernel; linework stays tiny |
+
+STEP is a trimmed-NURBS B-rep, not a mesh — tessellating it is a job for a real CAD kernel, so linework doesn't embed one. `occt-import-js` returns meshes that `fromOcct()` maps straight in, keeping the ~6 MB kernel an optional peer rather than a dependency.
+
+## Coordinates (read this once)
+
+| Field | Meaning |
+|---|---|
+| `x` | right, in your SVG's user units |
+| `y` | **down** — screen convention, not math convention |
+| `z` | toward the viewer; negative recedes and depth-dims |
+| `view.yaw` | rotation about the vertical axis through `cx` (radians) |
+| `view.pitch` | rotation about the horizontal axis through `cy`; positive looks down |
+| `view.f` | perspective focal distance — `k = f/(f−z)`; larger = flatter |
+| `bias` | per-shape depth nudge for deliberate coplanar layering |
+
+**Paper space:** annotations (dimensions, balloons, title blocks) are strings appended *after* the sorted scene — they never rotate, exactly like a real drawing's notes. `sketch.pt(p, z)` projects model points so leaders can pin paper to model.
+
+**Known limitation** (shared by every painter's-algorithm renderer): cyclic overlaps can't sort correctly — split long members into segments if you construct one.
+
+## Server-side rendering
+
+`render()` is a pure string function. Static site generators can emit finished 3D-looking diagrams with **zero client JS**:
+
+```js
+import { writeFileSync } from "node:fs";
+writeFileSync("diagram.svg", wrapInSvgTag(render(shapes, view)));
+```
+
+The hero image above and this repo's [demo page](https://isaacrowntree.com/linework/) are both drawn this way — see [`scripts/render-hero.mjs`](scripts/render-hero.mjs) and [`docs/scene.js`](docs/scene.js).
+
+## Install & test
+
+```bash
+npm i linework        # ESM, types included
+npm test              # 19 tests: projection, parallax, paint order, culling,
+                      # sketch scoping, and feature-edge extraction
+```
+
+## Contributing
+
+Small, dependency-free, and test-driven on purpose — see [CONTRIBUTING.md](CONTRIBUTING.md). Changes are tracked in [CHANGELOG.md](CHANGELOG.md). Issues and PRs welcome.
+
+## Provenance
+
+Extracted from **Fitment** — a "will that part fit your bike?" planner whose exploded service-manual drawings are rendered entirely by this engine, live-orbitable, with dimension callouts in paper space over the rotating model.
+
+## License
+
+[MIT](LICENSE) © Isaac Rowntree

package/dist/helpers.d.ts

@@ -0,0 +1,44 @@
+/**
+ * helpers — the ergonomic layer over raw Shapes, extracted from real use
+ * (the Fitment bike planner drew its entire scene through these).
+ *
+ * Everything returns Shape[] fragments you concat into one scene, or
+ * pushes into the array you hand it. Class names are yours: the library
+ * never dictates styling.
+ */
+import type { Shape, Stroke, V3, Cmd } from "./linework.js";
+export type P2 = [number, number];
+export declare const v3: (p: P2, z?: number) => V3;
+export declare const lerp2: (a: P2, b: P2, t: number) => P2;
+export interface Opt {
+    bias?: number;
+    tag?: string;
+    part?: string;
+    fill?: string;
+}
+/** straight segment between two 3D points */
+export declare const line3: (a: P2, za: number, b: P2, zb: number, cls: string, opt?: Opt) => Shape;
+/** arbitrary path from Cmd list */
+export declare const path3: (d: Cmd[], strokes: Stroke[], opt?: Opt) => Shape;
+/** hollow-tube outline: fat outer stroke + panel-colored core, one shape */
+export declare const tube: (d: Cmd[], w: number, outerCls?: string, innerCls?: string, opt?: Opt) => Shape;
+/** circle lying in a constant-z plane (wheels, rings) — projects to a correct ellipse */
+export declare const disc: (p: P2, z: number, r: number, strokes: Stroke[], opt?: Opt) => Shape;
+/** circle facing along z (cylinder caps) — stylized: stays round and readable */
+export declare const faceCap: (p: P2, z: number, r: number, strokes: Stroke[], opt?: Opt) => Shape;
+/**
+ * A six-faced box: face plate at z, body extruded away from the viewer
+ * (z − dz). Outward windings + backface culling keep it contiguous at
+ * any yaw/pitch. Classes: face plate `faceCls`, top/bottom `topCls`,
+ * left/right `sideCls`.
+ */
+export declare function box3(x: number, y: number, w: number, h: number, z: number, dz: number, faceCls?: string, topCls?: string, sideCls?: string, opt?: Opt): Shape[];
+/**
+ * A stylized cylinder along the z axis: back cap, silhouette rails that
+ * hug the PROJECTED axis (correct at any view), front cap. Needs the
+ * current view's transform to place the rails; pass `xform(view)`.
+ */
+export declare function cyl3(X: (p: V3) => {
+    x: number;
+    y: number;
+}, p: P2, r: number, zNear: number, zFar: number, capCls?: string, opt?: Opt): Shape[];

package/dist/helpers.js

@@ -0,0 +1,59 @@
+export const v3 = (p, z = 0) => [p[0], p[1], z];
+export const lerp2 = (a, b, t) => [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t];
+/** straight segment between two 3D points */
+export const line3 = (a, za, b, zb, cls, opt = {}) => ({
+    t: "path", d: [["M", v3(a, za)], ["L", v3(b, zb)]], strokes: [{ cls }], ...opt,
+});
+/** arbitrary path from Cmd list */
+export const path3 = (d, strokes, opt = {}) => ({
+    t: "path", d, strokes, ...opt,
+});
+/** hollow-tube outline: fat outer stroke + panel-colored core, one shape */
+export const tube = (d, w, outerCls = "tube", innerCls = "tube-in", opt = {}) => ({
+    t: "path", d, strokes: [{ cls: outerCls, w }, { cls: innerCls, w: Math.max(1.5, w - 5) }], ...opt,
+});
+/** circle lying in a constant-z plane (wheels, rings) — projects to a correct ellipse */
+export const disc = (p, z, r, strokes, opt = {}) => ({
+    t: "disc", c: v3(p, z), r, strokes, ...opt,
+});
+/** circle facing along z (cylinder caps) — stylized: stays round and readable */
+export const faceCap = (p, z, r, strokes, opt = {}) => ({
+    t: "face", c: v3(p, z), r, strokes, ...opt,
+});
+/**
+ * A six-faced box: face plate at z, body extruded away from the viewer
+ * (z − dz). Outward windings + backface culling keep it contiguous at
+ * any yaw/pitch. Classes: face plate `faceCls`, top/bottom `topCls`,
+ * left/right `sideCls`.
+ */
+export function box3(x, y, w, h, z, dz, faceCls = "face3", topCls = "top3", sideCls = "side3", opt = {}) {
+    const zB = z - dz;
+    const A = [x, y, z], B = [x + w, y, z], C = [x + w, y + h, z], D = [x, y + h, z];
+    const A2 = [x, y, zB], B2 = [x + w, y, zB], C2 = [x + w, y + h, zB], D2 = [x, y + h, zB];
+    const b0 = opt.bias ?? 0;
+    const q = (qq, cls, bias) => ({ t: "quad", q: qq, cls, cull: true, ...opt, bias });
+    return [
+        q([A, A2, B2, B], topCls, b0),
+        q([D, C, C2, D2], topCls, b0),
+        q([A, A2, D2, D], sideCls, b0),
+        q([B, C, C2, B2], sideCls, b0),
+        q([A2, D2, C2, B2], faceCls, b0 + 0.1),
+        q([A, B, C, D], faceCls, b0 + 0.2),
+    ];
+}
+/**
+ * A stylized cylinder along the z axis: back cap, silhouette rails that
+ * hug the PROJECTED axis (correct at any view), front cap. Needs the
+ * current view's transform to place the rails; pass `xform(view)`.
+ */
+export function cyl3(X, p, r, zNear, zFar, capCls = "cap3", opt = {}) {
+    const n = X(v3(p, zNear)), f = X(v3(p, zFar));
+    const dx = n.x - f.x, dy = n.y - f.y, m = Math.hypot(dx, dy) || 1;
+    const ox = (-dy / m) * r, oy = (dx / m) * r;
+    return [
+        { t: "face", c: v3(p, zFar), r, strokes: [{ cls: capCls }], ...opt },
+        line3([p[0] + ox, p[1] + oy], zFar, [p[0] + ox, p[1] + oy], zNear, capCls, opt),
+        line3([p[0] - ox, p[1] - oy], zFar, [p[0] - ox, p[1] - oy], zNear, capCls, opt),
+        { t: "face", c: v3(p, zNear), r, strokes: [{ cls: capCls }], ...opt, bias: (opt.bias ?? 0) + 0.5 },
+    ];
+}

package/dist/import.d.ts

@@ -0,0 +1,103 @@
+/**
+ * linework/import — turn a 3D mesh (glTF/GLB, OBJ, STL, or a three.js
+ * BufferGeometry) into linework strokes.
+ *
+ * The pipeline:
+ *   parse mesh triangles (+ node transforms)
+ *   → weld vertices by position
+ *   → keep only FEATURE edges (boundary + sharp creases)
+ *   → emit linework `path` Shapes at their 3D coordinates.
+ *
+ * A shaded 3D model carries no lines — its form lives in where the
+ * surface bends. Feature-edge extraction recovers exactly the lines a
+ * draftsperson would draw: the outline and the hard creases, nothing
+ * from the smooth interior of a face. The result drops straight into
+ * render()/sketch and rotates like any other linework scene.
+ *
+ * Zero dependencies. GLB, OBJ and STL are parsed by hand; no Draco.
+ */
+import type { Shape, V3 } from "./linework.js";
+export interface Mesh {
+    /** flat [x,y,z, x,y,z, …] in world space (node transforms applied) */
+    positions: Float32Array;
+    /** triangle vertex indices */
+    indices: Uint32Array;
+    name?: string;
+}
+/** Parse a .glb ArrayBuffer into world-space meshes. */
+export declare function parseGLB(buffer: ArrayBuffer): Mesh[];
+/** Parse a Wavefront .obj string into a single mesh (triangulated). */
+export declare function parseOBJ(text: string): Mesh[];
+/**
+ * Parse a binary or ASCII `.stl` into a single mesh. Binary is detected by
+ * the exact-size invariant (84 + 50·count bytes) rather than the unreliable
+ * "solid" prefix, since some binary exporters write "solid" in the header.
+ */
+export declare function parseSTL(data: ArrayBuffer | string): Mesh[];
+/**
+ * Adapt a three.js `BufferGeometry` (or anything with the same shape) into a
+ * linework `Mesh` — no three.js dependency, it just reads the typed arrays.
+ * Bring an existing three scene's geometry straight into a technical drawing.
+ */
+export declare function fromBufferGeometry(geometry: {
+    attributes: {
+        position: {
+            array: ArrayLike<number>;
+        };
+    };
+    index?: {
+        array: ArrayLike<number>;
+    } | null;
+}): Mesh;
+/**
+ * Adapt the result of [occt-import-js](https://github.com/kovacsv/occt-import-js)
+ * — OpenCASCADE compiled to WASM — which is the practical way to get geometry
+ * out of a **STEP / IGES / BREP** CAD file. You bring the kernel (it's ~6 MB,
+ * so it stays an optional peer, not a linework dependency); each mesh it
+ * returns already matches a BufferGeometry, so this just maps and merges them.
+ *
+ *   const occt = await occtimportjs();
+ *   const result = occt.ReadStepFile(new Uint8Array(buf), null);
+ *   const shapes = meshToShapes(fromOcct(result), { fit });
+ */
+export declare function fromOcct(result: {
+    meshes: Array<{
+        attributes: {
+            position: {
+                array: ArrayLike<number>;
+            };
+        };
+        index?: {
+            array: ArrayLike<number>;
+        } | null;
+    }>;
+}): Mesh[];
+export interface EdgeOptions {
+    /** crease threshold in degrees; edges sharper than this are kept. Default 25. */
+    angle?: number;
+    /** position weld tolerance as a fraction of the model's bounding-box diagonal. Default 1e-4. */
+    weld?: number;
+}
+/**
+ * Feature edges of a mesh: every edge that is a boundary (belongs to one
+ * triangle) or a sharp crease (the two triangles sharing it meet at an
+ * angle greater than `angle`). Returns pairs of world-space points.
+ */
+export declare function featureEdges(mesh: Mesh, opts?: EdgeOptions): [V3, V3][];
+export interface ImportOptions extends EdgeOptions {
+    /** stroke class for the emitted edges. Default "ink". */
+    cls?: string;
+    /** fit the model into this screen box; returns shapes already centered/scaled. */
+    fit?: {
+        cx: number;
+        cy: number;
+        size: number;
+    };
+    /** flip Y (glTF is Y-up; screen space is Y-down). Default true. */
+    flipY?: boolean;
+}
+/**
+ * One-call convenience: meshes → feature edges → linework Shapes, fitted
+ * to a screen box. Feed the result straight to render()/sketch.
+ */
+export declare function meshToShapes(meshes: Mesh[], opts?: ImportOptions): Shape[];

package/dist/import.js

@@ -0,0 +1,296 @@
+const IDENT = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+function matMul(a, b) {
+    const o = new Array(16).fill(0);
+    for (let c = 0; c < 4; c++)
+        for (let r = 0; r < 4; r++)
+            for (let k = 0; k < 4; k++)
+                o[c * 4 + r] += a[k * 4 + r] * b[c * 4 + k];
+    return o;
+}
+function fromTRS(t, r, s) {
+    const [tx, ty, tz] = t ?? [0, 0, 0];
+    const [x, y, z, w] = r ?? [0, 0, 0, 1];
+    const [sx, sy, sz] = s ?? [1, 1, 1];
+    const x2 = x + x, y2 = y + y, z2 = z + z;
+    const xx = x * x2, xy = x * y2, xz = x * z2;
+    const yy = y * y2, yz = y * z2, zz = z * z2;
+    const wx = w * x2, wy = w * y2, wz = w * z2;
+    return [
+        (1 - (yy + zz)) * sx, (xy + wz) * sx, (xz - wy) * sx, 0,
+        (xy - wz) * sy, (1 - (xx + zz)) * sy, (yz + wx) * sy, 0,
+        (xz + wy) * sz, (yz - wx) * sz, (1 - (xx + yy)) * sz, 0,
+        tx, ty, tz, 1,
+    ];
+}
+function applyMat(m, x, y, z) {
+    return [
+        m[0] * x + m[4] * y + m[8] * z + m[12],
+        m[1] * x + m[5] * y + m[9] * z + m[13],
+        m[2] * x + m[6] * y + m[10] * z + m[14],
+    ];
+}
+const COMPONENT = {
+    5120: { array: Int8Array, size: 1 },
+    5121: { array: Uint8Array, size: 1 },
+    5122: { array: Int16Array, size: 2 },
+    5123: { array: Uint16Array, size: 2 },
+    5125: { array: Uint32Array, size: 4 },
+    5126: { array: Float32Array, size: 4 },
+};
+const NUM_COMPONENTS = { SCALAR: 1, VEC2: 2, VEC3: 3, VEC4: 4, MAT4: 16 };
+/** Parse a .glb ArrayBuffer into world-space meshes. */
+export function parseGLB(buffer) {
+    const dv = new DataView(buffer);
+    if (dv.getUint32(0, true) !== 0x46546c67)
+        throw new Error("[import] not a GLB (bad magic)");
+    const jsonLen = dv.getUint32(12, true);
+    const json = JSON.parse(new TextDecoder().decode(new Uint8Array(buffer, 20, jsonLen)));
+    // BIN chunk follows the JSON chunk
+    let bin = null;
+    let off = 20 + jsonLen;
+    while (off < dv.byteLength) {
+        const len = dv.getUint32(off, true), type = dv.getUint32(off + 4, true);
+        if (type === 0x004e4942)
+            bin = new Uint8Array(buffer, off + 8, len); // "BIN\0"
+        off += 8 + len + ((4 - (len % 4)) % 4);
+    }
+    return extractMeshes(json, bin, buffer);
+}
+function readAccessor(json, bin, buffer, index) {
+    const acc = json.accessors[index];
+    const bv = json.bufferViews[acc.bufferView];
+    const comp = COMPONENT[acc.componentType];
+    const n = NUM_COMPONENTS[acc.type];
+    const base = (bv.byteOffset ?? 0) + (acc.byteOffset ?? 0);
+    if (!bin)
+        throw new Error("[import] external buffers not supported — use a .glb");
+    const src = new comp.array(bin.buffer, bin.byteOffset + base, acc.count * n);
+    return Float64Array.from(src);
+}
+function extractMeshes(json, bin, buffer) {
+    const out = [];
+    const scene = json.scenes?.[json.scene ?? 0];
+    const roots = scene?.nodes ?? json.nodes?.map((_, i) => i) ?? [];
+    const walk = (nodeIdx, parent) => {
+        const node = json.nodes[nodeIdx];
+        const local = node.matrix ? node.matrix : fromTRS(node.translation, node.rotation, node.scale);
+        const world = matMul(parent, local);
+        if (node.mesh != null) {
+            for (const prim of json.meshes[node.mesh].primitives) {
+                if (prim.attributes.POSITION == null)
+                    continue;
+                const pos = readAccessor(json, bin, buffer, prim.attributes.POSITION);
+                const world3 = new Float32Array(pos.length);
+                for (let i = 0; i < pos.length; i += 3) {
+                    const [x, y, z] = applyMat(world, pos[i], pos[i + 1], pos[i + 2]);
+                    world3[i] = x;
+                    world3[i + 1] = y;
+                    world3[i + 2] = z;
+                }
+                let indices;
+                if (prim.indices != null) {
+                    indices = Uint32Array.from(readAccessor(json, bin, buffer, prim.indices));
+                }
+                else {
+                    indices = new Uint32Array(pos.length / 3);
+                    for (let i = 0; i < indices.length; i++)
+                        indices[i] = i;
+                }
+                out.push({ positions: world3, indices, name: json.meshes[node.mesh].name });
+            }
+        }
+        for (const child of node.children ?? [])
+            walk(child, world);
+    };
+    for (const r of roots)
+        walk(r, IDENT);
+    return out;
+}
+/* ============================ OBJ ============================ */
+/** Parse a Wavefront .obj string into a single mesh (triangulated). */
+export function parseOBJ(text) {
+    const verts = [];
+    const idx = [];
+    for (const line of text.split("\n")) {
+        const t = line.trim();
+        if (t.startsWith("v ")) {
+            const p = t.slice(2).trim().split(/\s+/).map(Number);
+            verts.push(p[0], p[1], p[2]);
+        }
+        else if (t.startsWith("f ")) {
+            const f = t.slice(2).trim().split(/\s+/).map((tok) => parseInt(tok.split("/")[0], 10) - 1);
+            for (let i = 1; i < f.length - 1; i++)
+                idx.push(f[0], f[i], f[i + 1]); // fan-triangulate
+        }
+    }
+    return [{ positions: Float32Array.from(verts), indices: Uint32Array.from(idx) }];
+}
+/* ============================ STL ============================ */
+/** Build an unindexed mesh from flat triangle-soup positions (STL has no
+ *  shared indices; featureEdges welds by position to recover topology). */
+function meshFromSoup(positions) {
+    const indices = new Uint32Array(positions.length / 3);
+    for (let i = 0; i < indices.length; i++)
+        indices[i] = i;
+    return { positions, indices };
+}
+function parseAsciiSTL(text) {
+    const verts = [];
+    const re = /vertex\s+(-?[\d.eE+-]+)\s+(-?[\d.eE+-]+)\s+(-?[\d.eE+-]+)/g;
+    let m;
+    while ((m = re.exec(text)))
+        verts.push(+m[1], +m[2], +m[3]);
+    return [meshFromSoup(Float32Array.from(verts))];
+}
+/**
+ * Parse a binary or ASCII `.stl` into a single mesh. Binary is detected by
+ * the exact-size invariant (84 + 50·count bytes) rather than the unreliable
+ * "solid" prefix, since some binary exporters write "solid" in the header.
+ */
+export function parseSTL(data) {
+    if (typeof data === "string")
+        return parseAsciiSTL(data);
+    const dv = new DataView(data);
+    const count = dv.byteLength >= 84 ? dv.getUint32(80, true) : 0;
+    const isBinary = dv.byteLength === 84 + count * 50;
+    if (!isBinary) {
+        const text = new TextDecoder().decode(new Uint8Array(data));
+        if (/^\s*solid/.test(text) && text.includes("vertex"))
+            return parseAsciiSTL(text);
+        throw new Error("[import] not a recognisable STL (bad size and no ASCII facets)");
+    }
+    const positions = new Float32Array(count * 9);
+    for (let i = 0; i < count; i++) {
+        const o = 84 + i * 50 + 12; // skip the 12-byte per-face normal
+        for (let v = 0; v < 9; v++)
+            positions[i * 9 + v] = dv.getFloat32(o + v * 4, true);
+    }
+    return [meshFromSoup(positions)];
+}
+/* ==================== three.js adapter ==================== */
+/**
+ * Adapt a three.js `BufferGeometry` (or anything with the same shape) into a
+ * linework `Mesh` — no three.js dependency, it just reads the typed arrays.
+ * Bring an existing three scene's geometry straight into a technical drawing.
+ */
+export function fromBufferGeometry(geometry) {
+    const src = geometry.attributes.position.array;
+    const positions = src instanceof Float32Array ? src : Float32Array.from(src);
+    const indices = geometry.index
+        ? Uint32Array.from(geometry.index.array)
+        : meshFromSoup(positions).indices;
+    return { positions, indices };
+}
+/**
+ * Adapt the result of [occt-import-js](https://github.com/kovacsv/occt-import-js)
+ * — OpenCASCADE compiled to WASM — which is the practical way to get geometry
+ * out of a **STEP / IGES / BREP** CAD file. You bring the kernel (it's ~6 MB,
+ * so it stays an optional peer, not a linework dependency); each mesh it
+ * returns already matches a BufferGeometry, so this just maps and merges them.
+ *
+ *   const occt = await occtimportjs();
+ *   const result = occt.ReadStepFile(new Uint8Array(buf), null);
+ *   const shapes = meshToShapes(fromOcct(result), { fit });
+ */
+export function fromOcct(result) {
+    return result.meshes.map(fromBufferGeometry);
+}
+function faceNormal(p, a, b, c) {
+    const ux = p[b * 3] - p[a * 3], uy = p[b * 3 + 1] - p[a * 3 + 1], uz = p[b * 3 + 2] - p[a * 3 + 2];
+    const vx = p[c * 3] - p[a * 3], vy = p[c * 3 + 1] - p[a * 3 + 1], vz = p[c * 3 + 2] - p[a * 3 + 2];
+    const nx = uy * vz - uz * vy, ny = uz * vx - ux * vz, nz = ux * vy - uy * vx;
+    const m = Math.hypot(nx, ny, nz) || 1;
+    return [nx / m, ny / m, nz / m];
+}
+/**
+ * Feature edges of a mesh: every edge that is a boundary (belongs to one
+ * triangle) or a sharp crease (the two triangles sharing it meet at an
+ * angle greater than `angle`). Returns pairs of world-space points.
+ */
+export function featureEdges(mesh, opts = {}) {
+    const angle = opts.angle ?? 25;
+    const p = mesh.positions, idx = mesh.indices;
+    // weld vertices by quantized position so shared edges are detected
+    let min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];
+    for (let i = 0; i < p.length; i += 3)
+        for (let k = 0; k < 3; k++) {
+            min[k] = Math.min(min[k], p[i + k]);
+            max[k] = Math.max(max[k], p[i + k]);
+        }
+    const diag = Math.hypot(max[0] - min[0], max[1] - min[1], max[2] - min[2]) || 1;
+    const q = diag * (opts.weld ?? 1e-4);
+    const keyOf = (v) => `${Math.round(p[v * 3] / q)},${Math.round(p[v * 3 + 1] / q)},${Math.round(p[v * 3 + 2] / q)}`;
+    const weld = new Map();
+    const rep = new Uint32Array(p.length / 3);
+    for (let v = 0; v < p.length / 3; v++) {
+        const k = keyOf(v);
+        let r = weld.get(k);
+        if (r == null) {
+            r = v;
+            weld.set(k, v);
+        }
+        rep[v] = r;
+    }
+    // accumulate the (up to two) face normals per undirected welded edge
+    const cos = Math.cos((angle * Math.PI) / 180);
+    const edges = new Map();
+    for (let t = 0; t < idx.length; t += 3) {
+        const A = rep[idx[t]], B = rep[idx[t + 1]], C = rep[idx[t + 2]];
+        const n = faceNormal(p, A, B, C);
+        for (const [u, v] of [[A, B], [B, C], [C, A]]) {
+            if (u === v)
+                continue;
+            const lo = Math.min(u, v), hi = Math.max(u, v);
+            const key = lo + "_" + hi;
+            const e = edges.get(key);
+            if (e)
+                e.n.push(n);
+            else
+                edges.set(key, { a: lo, b: hi, n: [n] });
+        }
+    }
+    const pt = (v) => [p[v * 3], p[v * 3 + 1], p[v * 3 + 2]];
+    const out = [];
+    for (const e of edges.values()) {
+        const keep = e.n.length === 1 || // boundary
+            e.n.some((n1, i) => e.n.slice(i + 1).some((n2) => n1[0] * n2[0] + n1[1] * n2[1] + n1[2] * n2[2] < cos));
+        if (keep)
+            out.push([pt(e.a), pt(e.b)]);
+    }
+    return out;
+}
+/**
+ * One-call convenience: meshes → feature edges → linework Shapes, fitted
+ * to a screen box. Feed the result straight to render()/sketch.
+ */
+export function meshToShapes(meshes, opts = {}) {
+    const cls = opts.cls ?? "ink";
+    const flipY = opts.flipY ?? true;
+    const allEdges = [];
+    for (const m of meshes)
+        allEdges.push(...featureEdges(m, opts));
+    // fit transform (uniform scale about the model center → screen box)
+    let map = (v) => v;
+    if (opts.fit) {
+        let min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];
+        for (const [a, b] of allEdges)
+            for (const v of [a, b])
+                for (let k = 0; k < 3; k++) {
+                    min[k] = Math.min(min[k], v[k]);
+                    max[k] = Math.max(max[k], v[k]);
+                }
+        const span = Math.max(max[0] - min[0], max[1] - min[1], max[2] - min[2]) || 1;
+        const s = opts.fit.size / span;
+        const c = [(min[0] + max[0]) / 2, (min[1] + max[1]) / 2, (min[2] + max[2]) / 2];
+        const sy = flipY ? -s : s;
+        map = (v) => [opts.fit.cx + (v[0] - c[0]) * s, opts.fit.cy + (v[1] - c[1]) * sy, (v[2] - c[2]) * s];
+    }
+    else if (flipY) {
+        map = (v) => [v[0], -v[1], v[2]];
+    }
+    return allEdges.map(([a, b]) => ({
+        t: "path",
+        d: [["M", map(a)], ["L", map(b)]],
+        strokes: [{ cls }],
+    }));
+}

package/dist/linework.d.ts

@@ -0,0 +1,89 @@
+/**
+ * linework — a tiny true-3D renderer for annotated technical drawings.
+ *
+ * The classic pipeline, properly this time:
+ *   model (V3 points) → rotate (yaw, pitch) → perspective project
+ *   → depth-sort (painter's algorithm) → emit SVG strings.
+ *
+ * Why not a library: nothing ships "parametric technical illustration"
+ * (multi-weight strokes, dashed line styles, hollow tubes, CSS theming,
+ * crawlable text). This is ~180 lines and does exactly that.
+ *
+ * Deliberate stylizations (schematic license, documented):
+ *  - "face" discs (cylinder end-caps) stay round instead of thinning to
+ *    lenses edge-on — they must stay readable as parts.
+ *  - Depth cueing dims far strokes instead of hidden-line removal.
+ */
+export type V3 = [number, number, number];
+export interface View {
+    yaw: number;
+    pitch: number;
+    f: number;
+    cx: number;
+    cy: number;
+}
+export interface Pt {
+    x: number;
+    y: number;
+    z: number;
+    k: number;
+}
+/** Build the world→screen transform for a view. */
+export declare function xform(v: View): (p: V3) => Pt;
+export interface Stroke {
+    cls: string;
+    w?: number;
+}
+export type Cmd = ["M", V3] | ["L", V3] | ["Q", V3, V3] | ["Z"];
+export type Shape = 
+/** polyline/curve; multi-stroke renders the same d repeatedly (hollow tubes) */
+{
+    t: "path";
+    d: Cmd[];
+    strokes: Stroke[];
+    fill?: string;
+    bias?: number;
+    tag?: string;
+    part?: string;
+}
+/** circle lying in a constant-z model plane (wheels, rings) → ellipse */
+ | {
+    t: "disc";
+    c: V3;
+    r: number;
+    strokes: Stroke[];
+    fill?: string;
+    bias?: number;
+    tag?: string;
+    part?: string;
+}
+/** circle facing along z (cylinder caps) — stylized: stays round */
+ | {
+    t: "face";
+    c: V3;
+    r: number;
+    strokes: Stroke[];
+    fill?: string;
+    bias?: number;
+    tag?: string;
+    part?: string;
+}
+/** flat filled quad (box faces); cull=true drops backfaces */
+ | {
+    t: "quad";
+    q: [V3, V3, V3, V3];
+    cls: string;
+    cull?: boolean;
+    bias?: number;
+    tag?: string;
+    part?: string;
+};
+export interface PartDef {
+    attrs: string;
+}
+/**
+ * Render shapes with painter's-algorithm depth sorting.
+ * Shapes sharing a `part` key sort as one object (per-object sorting keeps
+ * animated <g part> wrappers intact) and are wrapped with that part's attrs.
+ */
+export declare function render(shapes: Shape[], view: View, parts?: Record<string, PartDef>): string;

package/dist/linework.js

@@ -0,0 +1,133 @@
+/**
+ * linework — a tiny true-3D renderer for annotated technical drawings.
+ *
+ * The classic pipeline, properly this time:
+ *   model (V3 points) → rotate (yaw, pitch) → perspective project
+ *   → depth-sort (painter's algorithm) → emit SVG strings.
+ *
+ * Why not a library: nothing ships "parametric technical illustration"
+ * (multi-weight strokes, dashed line styles, hollow tubes, CSS theming,
+ * crawlable text). This is ~180 lines and does exactly that.
+ *
+ * Deliberate stylizations (schematic license, documented):
+ *  - "face" discs (cylinder end-caps) stay round instead of thinning to
+ *    lenses edge-on — they must stay readable as parts.
+ *  - Depth cueing dims far strokes instead of hidden-line removal.
+ */
+/** Build the world→screen transform for a view. */
+export function xform(v) {
+    const cy = Math.cos(v.yaw), sy = Math.sin(v.yaw);
+    const cp = Math.cos(v.pitch), sp = Math.sin(v.pitch);
+    return (p) => {
+        const dx = p[0] - v.cx, dy = p[1] - v.cy;
+        // yaw about vertical
+        const x1 = cy * dx - sy * p[2];
+        const z1 = sy * dx + cy * p[2];
+        // pitch about horizontal (screen y grows downward; +pitch = camera above)
+        const y2 = cp * dy + sp * z1;
+        const z2 = -sp * dy + cp * z1;
+        const k = v.f / (v.f - z2);
+        return { x: v.cx + x1 * k, y: v.cy + y2 * k, z: z2, k };
+    };
+}
+const f1 = (n) => n.toFixed(1);
+function pathD(d, X) {
+    const zs = [];
+    const str = d
+        .map((c) => {
+        if (c[0] === "Z")
+            return "Z";
+        if (c[0] === "Q") {
+            const a = X(c[1]), b = X(c[2]);
+            zs.push(a.z, b.z);
+            return `Q ${f1(a.x)} ${f1(a.y)} ${f1(b.x)} ${f1(b.y)}`;
+        }
+        const p = X(c[1]);
+        zs.push(p.z);
+        return `${c[0]} ${f1(p.x)} ${f1(p.y)}`;
+    })
+        .join(" ");
+    return { str, zs };
+}
+/** depth-cue opacity: far → gently dimmer. Tuned so the far side of the
+ *  bike reads as "behind", never as "ghosted". */
+const dim = (z) => (z < -12 ? Math.max(0.55, 1 + (z + 12) / 420).toFixed(2) : "");
+function emit(sh, X) {
+    if (sh.t === "path") {
+        const { str, zs } = pathD(sh.d, X);
+        const depth = zs.reduce((a, b) => a + b, 0) / (zs.length || 1);
+        const op = dim(depth);
+        const fill = sh.fill ?? "none";
+        const svg = sh.strokes
+            .map((s, i) => `<path d="${str}" class="${s.cls}${sh.tag ? " " + sh.tag : ""}"${s.w ? ` stroke-width="${f1(s.w)}"` : ""} fill="${i === 0 ? fill : "none"}"${op && i === 0 ? ` opacity="${op}"` : op ? ` opacity="${op}"` : ""}/>`)
+            .join("");
+        return { svg, depth: depth + (sh.bias ?? 0) };
+    }
+    if (sh.t === "disc" || sh.t === "face") {
+        const c = X(sh.c);
+        const op = dim(c.z);
+        let core;
+        if (sh.t === "disc") {
+            // project the disc's plane basis to get the ellipse
+            const u = X([sh.c[0] + 1, sh.c[1], sh.c[2]]);
+            const v = X([sh.c[0], sh.c[1] + 1, sh.c[2]]);
+            const rx = Math.hypot(u.x - c.x, u.y - c.y) * sh.r;
+            const ry = Math.hypot(v.x - c.x, v.y - c.y) * sh.r;
+            const rot = (Math.atan2(u.y - c.y, u.x - c.x) * 180) / Math.PI;
+            core = `<ellipse cx="${f1(c.x)}" cy="${f1(c.y)}" rx="${f1(rx)}" ry="${f1(ry)}" transform="rotate(${f1(rot)} ${f1(c.x)} ${f1(c.y)})"`;
+        }
+        else {
+            core = `<circle cx="${f1(c.x)}" cy="${f1(c.y)}" r="${f1(sh.r * c.k)}"`;
+        }
+        const fill = sh.fill ?? "none";
+        const svg = sh.strokes
+            .map((s, i) => core +
+            ` class="${s.cls}${sh.tag ? " " + sh.tag : ""}"${s.w ? ` stroke-width="${f1(s.w)}"` : ""} fill="${i === 0 ? fill : "none"}"${op ? ` opacity="${op}"` : ""}/>`)
+            .join("");
+        return { svg, depth: c.z + (sh.bias ?? 0) };
+    }
+    // quad
+    const q = sh.q.map(X);
+    // backface cull via signed screen area
+    const area = (q[1].x - q[0].x) * (q[2].y - q[0].y) - (q[2].x - q[0].x) * (q[1].y - q[0].y);
+    if (sh.cull && area <= 0)
+        return { svg: "", depth: -Infinity };
+    const depth = (q[0].z + q[1].z + q[2].z + q[3].z) / 4 + (sh.bias ?? 0);
+    const d = `M ${f1(q[0].x)} ${f1(q[0].y)} L ${f1(q[1].x)} ${f1(q[1].y)} L ${f1(q[2].x)} ${f1(q[2].y)} L ${f1(q[3].x)} ${f1(q[3].y)} Z`;
+    return { svg: `<path d="${d}" class="${sh.cls}${sh.tag ? " " + sh.tag : ""}"/>`, depth };
+}
+/**
+ * Render shapes with painter's-algorithm depth sorting.
+ * Shapes sharing a `part` key sort as one object (per-object sorting keeps
+ * animated <g part> wrappers intact) and are wrapped with that part's attrs.
+ */
+export function render(shapes, view, parts = {}) {
+    const X = xform(view);
+    const slots = [];
+    const byPart = new Map();
+    for (const sh of shapes) {
+        const e = emit(sh, X);
+        if (!e.svg)
+            continue;
+        if (sh.part) {
+            const b = byPart.get(sh.part) ?? { svgs: [], depths: [] };
+            b.svgs.push(e.svg);
+            b.depths.push(e.depth);
+            byPart.set(sh.part, b);
+        }
+        else {
+            slots.push(e);
+        }
+    }
+    for (const [key, b] of byPart) {
+        const depth = b.depths.reduce((a, c) => a + c, 0) / b.depths.length;
+        const def = parts[key];
+        slots.push({
+            svg: `<g ${def ? def.attrs : ""}>${b.svgs.join("")}</g>`,
+            depth,
+            part: key,
+        });
+    }
+    slots.sort((a, b) => a.depth - b.depth); // far → near
+    return slots.map((s) => s.svg).join("");
+}

package/dist/orbit.d.ts

@@ -0,0 +1,21 @@
+/**
+ * orbit — the drag-to-orbit boilerplate every consumer would otherwise
+ * copy-paste: pointer capture, yaw/pitch clamping, rAF batching,
+ * double-click reset, and a gentle idle sway until first touch
+ * (disabled under prefers-reduced-motion).
+ */
+import type { View } from "./linework.js";
+export interface OrbitOptions {
+    view: View;
+    onFrame: (view: View) => void;
+    yawRange?: [number, number];
+    pitchRange?: [number, number];
+    /** idle sway amplitude in radians (0 disables). Default 0.12. */
+    idle?: number;
+}
+export interface OrbitHandle {
+    view: View;
+    redraw: () => void;
+    stop: () => void;
+}
+export declare function orbit(el: Element, o: OrbitOptions): OrbitHandle;

package/dist/orbit.js

@@ -0,0 +1,53 @@
+export function orbit(el, o) {
+    const v = { ...o.view };
+    const [ylo, yhi] = o.yawRange ?? [-1.1, 1.1];
+    const [plo, phi] = o.pitchRange ?? [-0.3, 0.6];
+    const idleAmp = o.idle ?? 0.12;
+    const clamp = (x, a, b) => Math.max(a, Math.min(b, x));
+    let dragging = false, x0 = 0, y0 = 0, yaw0 = 0, p0 = 0, raf = 0, stopped = false;
+    let idleOn = idleAmp > 0 &&
+        (typeof matchMedia === "undefined" || !matchMedia("(prefers-reduced-motion: reduce)").matches);
+    const frame = () => { raf = 0; o.onFrame({ ...v }); };
+    const req = () => { if (!raf)
+        raf = requestAnimationFrame(frame); };
+    el.addEventListener("pointerdown", (e) => {
+        const ev = e;
+        if (ev.target?.closest?.("[data-no-orbit]"))
+            return;
+        idleOn = false;
+        dragging = true;
+        x0 = ev.clientX;
+        y0 = ev.clientY;
+        yaw0 = v.yaw;
+        p0 = v.pitch;
+        el.setPointerCapture?.(ev.pointerId);
+    });
+    el.addEventListener("pointermove", (e) => {
+        if (!dragging)
+            return;
+        const ev = e;
+        v.yaw = clamp(yaw0 + (ev.clientX - x0) / 260, ylo, yhi);
+        v.pitch = clamp(p0 + (ev.clientY - y0) / 340, plo, phi);
+        req();
+    });
+    const end = () => { dragging = false; };
+    el.addEventListener("pointerup", end);
+    el.addEventListener("pointercancel", end);
+    el.addEventListener("dblclick", () => { v.yaw = o.view.yaw; v.pitch = o.view.pitch; req(); });
+    // gentle sway so the page is alive before anyone touches it
+    const t0 = performance.now();
+    const sway = (t) => {
+        if (stopped)
+            return;
+        if (idleOn) {
+            v.yaw = clamp(o.view.yaw + Math.sin((t - t0) / 1700) * idleAmp, ylo, yhi);
+            v.pitch = clamp(o.view.pitch + Math.sin((t - t0) / 2500) * idleAmp * 0.35, plo, phi);
+            o.onFrame({ ...v });
+        }
+        requestAnimationFrame(sway);
+    };
+    o.onFrame({ ...v }); // first paint
+    if (idleOn)
+        requestAnimationFrame(sway);
+    return { view: v, redraw: () => o.onFrame({ ...v }), stop: () => { stopped = true; idleOn = false; } };
+}

package/dist/sketch.d.ts

@@ -0,0 +1,78 @@
+/**
+ * sketch — the expressive authoring layer. Designing a drawing should be
+ * as pleasant as looking at one.
+ *
+ * Three ideas:
+ *  1. A Sketch holds the view, so nothing needs `xform` passed around.
+ *  2. Context blocks — `s.part()`, `s.tag()`, `s.bias()` — scope metadata
+ *     over everything drawn inside them, killing per-call option noise.
+ *  3. `scene(build)` returns a replayable frame function: define once,
+ *     call with a new view every frame for orbit/explode animation.
+ *
+ *     const draw = scene((s, { e }) => {
+ *       s.box(300, 380, 320, 42, 40, 80);
+ *       s.part("shaft", () => s.cyl([460, 310], 19, 168, 24, "ink"));
+ *     });
+ *     el.innerHTML = draw({ yaw, pitch, f: 1500, cx: 460, cy: 320 }, { e });
+ */
+import { type Shape, type Stroke, type View, type V3, type Pt } from "./linework.js";
+export type P2 = [number, number];
+/** fluent path under construction — every verb returns itself */
+export declare class Path {
+    private shape;
+    constructor(shape: Shape & {
+        t: "path";
+    });
+    M(p: P2, z?: number): this;
+    L(p: P2, z?: number): this;
+    Q(c: P2, cz: number, p: P2, z?: number): this;
+    close(): this;
+    /** additional stroke over the same geometry (hollow tubes, glows) */
+    stroke(cls: string, w?: number): this;
+    fill(paint: string): this;
+}
+export declare class Sketch {
+    readonly view: View;
+    readonly X: (p: V3) => Pt;
+    private shapes;
+    private parts;
+    private paperStrs;
+    private ctx;
+    constructor(view: View);
+    private scoped;
+    /** everything drawn inside belongs to one animated part (one <g>, one sort unit) */
+    part(name: string, attrs: string, fn: () => void): this;
+    /** everything inside carries an extra class — visibility groups, themes */
+    tag(cls: string, fn: () => void): this;
+    /** deliberate layering for coplanar geometry */
+    bias(n: number, fn: () => void): this;
+    private opt;
+    /** begin a fluent path: s.path("ink").M(a).Q(c, 10, b, 20) */
+    path(cls: string, w?: number): Path;
+    /** hollow-tube outline in one call: fat outer + core stroke */
+    tube(w: number, outer?: string, inner?: string): Path;
+    line(a: P2, za: number, b: P2, zb: number, cls: string, w?: number): this;
+    /** circle in a constant-z plane — projects to a correct ellipse */
+    disc(c: P2, z: number, r: number, cls: string | Stroke[], fill?: string): this;
+    /** cylinder end-cap facing the viewer — stylized, stays readable */
+    cap(c: P2, z: number, r: number, cls: string, fill?: string): this;
+    /** six-faced box: face plate at z, body extruded away (z − dz) */
+    box(x: number, y: number, w: number, h: number, z: number, dz: number, cls?: {
+        face?: string;
+        top?: string;
+        side?: string;
+    }): this;
+    /** cylinder along z with silhouette rails computed from THIS sketch's view */
+    cyl(c: P2, r: number, zNear: number, zFar: number, cls?: string, fill?: string): this;
+    /** project a model point to screen — for hand-placed annotations */
+    pt(p: P2, z?: number): P2;
+    /** raw SVG painted above the sorted scene */
+    paper(svg: string): this;
+    /** paper-space text at a projected anchor */
+    note(text: string, p: P2, z?: number, cls?: string, dx?: number, dy?: number): this;
+    count(): number;
+    render(): string;
+}
+export declare const sketch: (view: View) => Sketch;
+/** define once, replay per frame with a fresh view — the orbit-loop idiom */
+export declare function scene<P = void>(build: (s: Sketch, props: P) => void): (view: View, props: P) => string;

package/dist/sketch.js

@@ -0,0 +1,150 @@
+/**
+ * sketch — the expressive authoring layer. Designing a drawing should be
+ * as pleasant as looking at one.
+ *
+ * Three ideas:
+ *  1. A Sketch holds the view, so nothing needs `xform` passed around.
+ *  2. Context blocks — `s.part()`, `s.tag()`, `s.bias()` — scope metadata
+ *     over everything drawn inside them, killing per-call option noise.
+ *  3. `scene(build)` returns a replayable frame function: define once,
+ *     call with a new view every frame for orbit/explode animation.
+ *
+ *     const draw = scene((s, { e }) => {
+ *       s.box(300, 380, 320, 42, 40, 80);
+ *       s.part("shaft", () => s.cyl([460, 310], 19, 168, 24, "ink"));
+ *     });
+ *     el.innerHTML = draw({ yaw, pitch, f: 1500, cx: 460, cy: 320 }, { e });
+ */
+import { render, xform } from "./linework.js";
+/** fluent path under construction — every verb returns itself */
+export class Path {
+    shape;
+    constructor(shape) { this.shape = shape; }
+    M(p, z = 0) { this.shape.d.push(["M", [p[0], p[1], z]]); return this; }
+    L(p, z = 0) { this.shape.d.push(["L", [p[0], p[1], z]]); return this; }
+    Q(c, cz, p, z = 0) { this.shape.d.push(["Q", [c[0], c[1], cz], [p[0], p[1], z]]); return this; }
+    close() { this.shape.d.push(["Z"]); return this; }
+    /** additional stroke over the same geometry (hollow tubes, glows) */
+    stroke(cls, w) { this.shape.strokes.push({ cls, w }); return this; }
+    fill(paint) { this.shape.fill = paint; return this; }
+}
+export class Sketch {
+    view;
+    X;
+    shapes = [];
+    parts = {};
+    paperStrs = [];
+    ctx = { bias: 0 };
+    constructor(view) {
+        this.view = view;
+        this.X = xform(view);
+    }
+    /* ---------- context blocks ---------- */
+    scoped(patch, fn) {
+        const prev = this.ctx;
+        this.ctx = { ...prev, ...patch, bias: prev.bias + (patch.bias ?? 0) };
+        try {
+            fn();
+        }
+        finally {
+            this.ctx = prev;
+        }
+        return this;
+    }
+    /** everything drawn inside belongs to one animated part (one <g>, one sort unit) */
+    part(name, attrs, fn) {
+        this.parts[name] = { attrs };
+        return this.scoped({ part: name }, fn);
+    }
+    /** everything inside carries an extra class — visibility groups, themes */
+    tag(cls, fn) {
+        return this.scoped({ tag: this.ctx.tag ? `${this.ctx.tag} ${cls}` : cls }, fn);
+    }
+    /** deliberate layering for coplanar geometry */
+    bias(n, fn) { return this.scoped({ bias: n }, fn); }
+    opt() {
+        const o = {};
+        if (this.ctx.part)
+            o.part = this.ctx.part;
+        if (this.ctx.tag)
+            o.tag = this.ctx.tag;
+        if (this.ctx.bias)
+            o.bias = this.ctx.bias;
+        return o;
+    }
+    /* ---------- primitives ---------- */
+    /** begin a fluent path: s.path("ink").M(a).Q(c, 10, b, 20) */
+    path(cls, w) {
+        const shape = { t: "path", d: [], strokes: [{ cls, w }], ...this.opt() };
+        this.shapes.push(shape);
+        return new Path(shape);
+    }
+    /** hollow-tube outline in one call: fat outer + core stroke */
+    tube(w, outer = "tube", inner = "tube-in") {
+        return this.path(outer, w).stroke(inner, Math.max(1.5, w - 5));
+    }
+    line(a, za, b, zb, cls, w) {
+        this.path(cls, w).M(a, za).L(b, zb);
+        return this;
+    }
+    /** circle in a constant-z plane — projects to a correct ellipse */
+    disc(c, z, r, cls, fill) {
+        const strokes = typeof cls === "string" ? [{ cls }] : cls;
+        this.shapes.push({ t: "disc", c: [c[0], c[1], z], r, strokes, fill, ...this.opt() });
+        return this;
+    }
+    /** cylinder end-cap facing the viewer — stylized, stays readable */
+    cap(c, z, r, cls, fill) {
+        this.shapes.push({ t: "face", c: [c[0], c[1], z], r, strokes: [{ cls }], fill, ...this.opt() });
+        return this;
+    }
+    /** six-faced box: face plate at z, body extruded away (z − dz) */
+    box(x, y, w, h, z, dz, cls = {}) {
+        const { face = "face3", top = "top3", side = "side3" } = cls;
+        const zB = z - dz, o = this.opt(), b0 = o.bias ?? 0;
+        const A = [x, y, z], B = [x + w, y, z], C = [x + w, y + h, z], D = [x, y + h, z];
+        const A2 = [x, y, zB], B2 = [x + w, y, zB], C2 = [x + w, y + h, zB], D2 = [x, y + h, zB];
+        const q = (qq, c2, bias) => this.shapes.push({ t: "quad", q: qq, cls: c2, cull: true, ...o, bias });
+        q([A, A2, B2, B], top, b0);
+        q([D, C, C2, D2], top, b0);
+        q([A, A2, D2, D], side, b0);
+        q([B, C, C2, B2], side, b0);
+        q([A2, D2, C2, B2], face, b0 + 0.1);
+        q([A, B, C, D], face, b0 + 0.2);
+        return this;
+    }
+    /** cylinder along z with silhouette rails computed from THIS sketch's view */
+    cyl(c, r, zNear, zFar, cls = "ink", fill) {
+        const n = this.X([c[0], c[1], zNear]), f = this.X([c[0], c[1], zFar]);
+        const dx = n.x - f.x, dy = n.y - f.y, m = Math.hypot(dx, dy) || 1;
+        const ox = (-dy / m) * r, oy = (dx / m) * r;
+        this.cap(c, zFar, r, cls);
+        this.line([c[0] + ox, c[1] + oy], zFar, [c[0] + ox, c[1] + oy], zNear, cls);
+        this.line([c[0] - ox, c[1] - oy], zFar, [c[0] - ox, c[1] - oy], zNear, cls);
+        const o = this.opt();
+        this.shapes.push({ t: "face", c: [c[0], c[1], zNear], r, strokes: [{ cls }], fill, ...o, bias: (o.bias ?? 0) + 0.5 });
+        return this;
+    }
+    /* ---------- paper space (annotations that never rotate) ---------- */
+    /** project a model point to screen — for hand-placed annotations */
+    pt(p, z = 0) { const q = this.X([p[0], p[1], z]); return [q.x, q.y]; }
+    /** raw SVG painted above the sorted scene */
+    paper(svg) { this.paperStrs.push(svg); return this; }
+    /** paper-space text at a projected anchor */
+    note(text, p, z = 0, cls = "an", dx = 6, dy = 4) {
+        const q = this.pt(p, z);
+        return this.paper(`<text x="${(q[0] + dx).toFixed(1)}" y="${(q[1] + dy).toFixed(1)}" class="${cls}">${text}</text>`);
+    }
+    /* ---------- output ---------- */
+    count() { return this.shapes.length; }
+    render() { return render(this.shapes, this.view, this.parts) + this.paperStrs.join(""); }
+}
+export const sketch = (view) => new Sketch(view);
+/** define once, replay per frame with a fresh view — the orbit-loop idiom */
+export function scene(build) {
+    return (view, props) => {
+        const s = sketch(view);
+        build(s, props);
+        return s.render();
+    };
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "linework",
+  "version": "0.3.0",
+  "description": "Tiny true-3D renderer for annotated technical drawings in SVG — rotate, project, depth-sort, emit strings. Zero dependencies.",
+  "type": "module",
+  "main": "./dist/linework.js",
+  "types": "./dist/linework.d.ts",
+  "exports": {
+    ".": { "types": "./dist/linework.d.ts", "import": "./dist/linework.js" },
+    "./helpers": { "types": "./dist/helpers.d.ts", "import": "./dist/helpers.js" },
+    "./sketch": { "types": "./dist/sketch.d.ts", "import": "./dist/sketch.js" },
+    "./orbit": { "types": "./dist/orbit.d.ts", "import": "./dist/orbit.js" },
+    "./import": { "types": "./dist/import.d.ts", "import": "./dist/import.js" }
+  },
+  "files": ["dist", "README.md", "LICENSE", "CHANGELOG.md"],
+  "license": "MIT",
+  "repository": "github:isaacrowntree/linework",
+  "homepage": "https://isaacrowntree.com/linework/",
+  "keywords": ["svg", "3d", "pseudo-3d", "isometric", "technical-illustration", "exploded-diagram", "painters-algorithm", "blueprint"],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && cp dist/linework.js dist/helpers.js dist/sketch.js dist/orbit.js dist/import.js docs/",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "hero": "npm run build && node scripts/render-hero.mjs",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10"
+  }
+}