@logomarks/logo3d 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to `@logomarks/logo3d` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.1] — 2026-11-15
+
+### Changed
+
+- Works with `@logomarks/core` 0.2.0 as well as 0.1 (`^0.1.9 || ^0.2.0`), so a project on the new core keeps one copy
+  of it. 0.2.0 only adds subpaths; nothing this package uses changed.
+
+## [0.1.0] — 2026-11-10
+
+The first cut.
+
+### Added
+
+- **Shape** (`readLogo`): an SVG's filled elements read without a DOM (transforms, fills and fill rules from
+  attributes, styles and classes; rounded rects, circles, ellipses, polygons, polylines), painted into colour layers
+  that never overlap, a full-viewBox background dropped, normalised (y up, centred, the longest side 1), and the
+  bevel's cap measured: the deepest inset that keeps every layer's pieces and holes. Built on @logomarks/core's SVG
+  reader, booleans, distance transform and components.
+- **Geometry** (`buildGeometry`): profiles `flat`, `chamfer`, `round` and `pillow`; every level inset point for point
+  onto the true round offset; earcut faces; banded sides with smooth or split normals; face, side and back draw
+  groups per layer; deterministic.
+- **Materials**: chrome, black chrome, gold, brushed steel (anisotropy), clear and frosted glass (transmission),
+  clay, matte, gloss, and the house flat colour (the face exactly the colour, the sides darker); separate face and
+  side materials; glTF through KHR_materials_* (unlit for the flat colour).
+- **Scene**: a studio built in code and two self-hosted CC0 Poly Haven HDRIs at 1k (Studio Small 09; Kloofendal 48d
+  Partly Cloudy, pure sky); transparent, solid and paper-sweep backgrounds (a contact shadow on the sweep); four views
+  fitted to the logo's bounding sphere; a drag to turn; frames only while moving and seen.
+- **Motion**: none, turntable, swing, float and light sweep, as pure functions of time, exactly periodic.
+- **Exports**: PNG stills off screen (multisampled, tiled above 2048 px, un-premultiplied when transparent), GLB, and
+  a frame source for a video encoder.
+- **Worker**: geometry in a same-origin module worker (no blob: URL, no WebAssembly); `createBuilder` keeps only the
+  latest request, and builds on the main thread without a worker.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ArrayPress Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# @logomarks/logo3d
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+3D logos from SVG, in the browser: a mark's exact outlines extruded with a flat, chamfered, round or pillow edge (the bevel capped by the logo's thinnest stroke), in colour layers with their own face, side and back materials, lit only by what they reflect, and exported as PNG, GLB or video frames. Geometry runs in a module worker. No WebAssembly, no server.
+
+## Install
+
+```bash
+npm install @logomarks/logo3d three
+```
+
+## Quick start
+
+```js
+import { createBuilder } from '@logomarks/logo3d';
+import { createView } from '@logomarks/logo3d/three';
+import LogoWorker from '@logomarks/logo3d/worker?worker'; // Vite; any same-origin module worker will do
+import softbox from '@logomarks/logo3d/assets/hdri/studio_small_09_1k.hdr?url';
+
+const view = createView(canvas, { hdri: { 'studio_small_09_1k.hdr': softbox } });
+const builder = createBuilder(() => new LogoWorker());
+
+const { geometry, colors } = await builder.build({ svg, options: { profile: 'round', depth: 0.14, bevel: 0.6 } });
+view.setGeometry(geometry, colors);
+await view.setLook({ material: 'chrome', environment: 'softbox', background: 'sweep', motion: 'turntable' });
+
+const png = await view.png({ width: 2048, height: 2048, transparent: true });
+const glb = await view.glb();
+```
+
+In Node (no WebGL), the pure half works on its own:
+
+```js
+import { readLogo, buildGeometry, poseAt } from '@logomarks/logo3d';
+
+const shape = readLogo(svgText);                        // colour layers, y up, longest side 1
+const geo = buildGeometry(shape, { profile: 'pillow' }); // typed arrays and draw groups
+```
+
+## What's in it
+
+- [API](docs/api.md): every export, by entry point
+- [Shape and geometry](docs/geometry.md): reading SVGs, colour layers, the profiles, the bevel's cap
+- [Materials, light and backdrops](docs/look.md): the presets, the studio and the HDRIs, the views and motions
+- [Exports](docs/exports.md): PNG stills, GLB, video frames
+- [Credits](docs/credits.md): the CC0 HDRIs
+
+## Links
+
+- [Changelog](CHANGELOG.md)
+- [Licence](LICENSE)
+- [`@logomarks/core`](https://github.com/Logomarks/core), the SVG reader, booleans and raster it builds on
+- [logomarks.ai/3d-logo-generator](https://logomarks.ai/3d-logo-generator), where it runs
+
+## Licence
+
+MIT © ArrayPress Limited; author David Sherlock. The HDRIs in `assets/hdri/` are CC0 from Poly Haven (see [credits](docs/credits.md)).

package/package.json

@@ -1,6 +1,84 @@
 {
   "name": "@logomarks/logo3d",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "3D logos from SVG: a mark's exact outlines extruded with a flat, chamfered, round or pillow edge capped by its thinnest stroke, in colour layers with separate face, side and back materials (chrome, black chrome, gold, brushed steel, clear and frosted glass, clay, matte, gloss, and a flat colour with darker sides), lit by a studio or a CC0 HDRI, on a transparent, solid or paper-sweep ground, moved by loop-exact motions, and exported as PNG, GLB or video frames. Geometry runs in a module worker; no WebAssembly.",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./three": {
+      "types": "./src/three/index.d.ts",
+      "import": "./src/three/index.js",
+      "default": "./src/three/index.js"
+    },
+    "./worker": {
+      "types": "./src/worker/worker.d.ts",
+      "import": "./src/worker/worker.js",
+      "default": "./src/worker/worker.js"
+    },
+    "./assets/*": "./assets/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "assets",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "3d",
+    "3d-logo",
+    "bevel",
+    "chrome",
+    "extrude",
+    "glb",
+    "gltf",
+    "hdri",
+    "logo",
+    "logomark",
+    "logomarks",
+    "svg",
+    "three",
+    "turntable",
+    "webgl"
+  ],
+  "author": "David Sherlock",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Logomarks/logo3d.git"
+  },
+  "homepage": "https://www.npmjs.com/package/@logomarks/logo3d",
+  "bugs": "https://github.com/Logomarks/logo3d/issues",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@logomarks/core": "^0.1.9 || ^0.2.0",
+    "earcut": "^3.0.2"
+  },
+  "peerDependencies": {
+    "three": ">=0.170.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "@types/three": "^0.186.0",
+    "three": "^0.186.0",
+    "typescript": "^6.0.3"
+  }
+}

package/src/export/glb.d.ts

@@ -0,0 +1,5 @@
+import type * as THREE from 'three';
+import type { GLTFExporter } from 'three/addons/exporters/GLTFExporter.js';
+
+/** A logo's mesh as a GLB: at rest, its materials as glTF carries them. */
+export function glbOf(three: typeof THREE, exporter: typeof GLTFExporter, mesh: THREE.Mesh, o?: { name?: string }): Promise<Blob>;

package/src/export/glb.js

@@ -0,0 +1,28 @@
+/**
+ * @module @logomarks/logo3d/export/glb
+ *
+ * The logo as a binary glTF (.glb): its mesh at rest (no motion), its longest side 1 m, y up and facing +z, in its
+ * materials. Physical materials carry their KHR_materials_* extensions (clearcoat, transmission, volume, IOR,
+ * anisotropy); the flat colour goes as unlit (KHR_materials_unlit), its sides one darker unlit colour.
+ */
+
+import { exportable } from '../materials/factory.js';
+
+/**
+ * A logo's mesh as a GLB.
+ *
+ * @param {typeof import('three')} THREE three.js.
+ * @param {typeof import('three/addons/exporters/GLTFExporter.js').GLTFExporter} GLTFExporter three's exporter.
+ * @param {import('three').Mesh} mesh The logo's mesh.
+ * @param {{ name?: string }} [o] `name`: the node's name ("Logo").
+ * @returns {Promise<Blob>} The file.
+ */
+export async function glbOf(THREE, GLTFExporter, mesh, { name = 'Logo' } = {}) {
+	const mats = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+	const copy = new THREE.Mesh(mesh.geometry, mats.map((m) => exportable(THREE, m)));
+	copy.name = name;
+	const scene = new THREE.Scene();
+	scene.add(copy);
+	const out = await new GLTFExporter().parseAsync(scene, { binary: true });
+	return new Blob([/** @type {ArrayBuffer} */ (out)], { type: 'model/gltf-binary' });
+}

package/src/export/still.d.ts

@@ -0,0 +1,23 @@
+import type * as THREE from 'three';
+import type { OutputPass } from 'three/addons/postprocessing/OutputPass.js';
+
+/** RGBA pixels, rows top to bottom. */
+export interface Pixels {
+	data: Uint8ClampedArray<ArrayBuffer>;
+	width: number;
+	height: number;
+}
+/** Turns premultiplied pixels into straight ones, in place. */
+export function unpremultiply(px: Uint8ClampedArray | Uint8Array): void;
+/** Copies a GL tile (rows bottom to top) into an image, clipped to it. */
+export function placeTile(tile: Uint8Array, tw: number, th: number, out: Uint8ClampedArray, width: number, height: number, x: number, y: number): void;
+/** Even tiles over a side: the tile's side. */
+export function tileSide(size: number, most: number): number;
+/** A still renderer: off-screen, multisampled, tone-mapped by OutputPass, tiled for large stills. */
+export function stillRenderer(
+	three: typeof THREE,
+	pass: typeof OutputPass,
+	renderer: THREE.WebGLRenderer,
+): { render(scene: THREE.Scene, camera: THREE.PerspectiveCamera, o: { width: number; height: number; transparent?: boolean; tile?: number }): Pixels; dispose(): void };
+/** Pixels as a PNG. */
+export function pngOf(px: Pixels): Promise<Blob>;

package/src/export/still.js

@@ -0,0 +1,144 @@
+/**
+ * @module @logomarks/logo3d/export/still
+ *
+ * Stills drawn off screen, never by resizing the live view: the scene rendered into a multisampled half-float
+ * target, tone-mapped and encoded by three's OutputPass into a second target, and read back. Large stills go in even
+ * tiles (the camera's view offset), so a 4096 px PNG never needs a 4096 px multisampled target. Transparent stills
+ * are un-premultiplied, so their edges have no dark fringe.
+ */
+
+/**
+ * @typedef {object} Pixels
+ * @property {Uint8ClampedArray} data RGBA, rows top to bottom.
+ * @property {number} width
+ * @property {number} height
+ */
+
+/**
+ * Turns premultiplied pixels into straight ones, in place.
+ *
+ * @param {Uint8ClampedArray | Uint8Array} px RGBA.
+ */
+export function unpremultiply(px) {
+	for (let i = 0; i < px.length; i += 4) {
+		const a = px[i + 3];
+		if (a === 0 || a === 255) continue;
+		const k = 255 / a;
+		px[i] = Math.min(255, Math.round(px[i] * k));
+		px[i + 1] = Math.min(255, Math.round(px[i + 1] * k));
+		px[i + 2] = Math.min(255, Math.round(px[i + 2] * k));
+	}
+}
+
+/**
+ * Copies a tile read from GL (rows bottom to top) into an image (rows top to bottom), clipped to the image.
+ *
+ * @param {Uint8Array} tile The tile's pixels.
+ * @param {number} tw Its width.
+ * @param {number} th Its height.
+ * @param {Uint8ClampedArray} out The image.
+ * @param {number} width The image's width.
+ * @param {number} height The image's height.
+ * @param {number} x Where the tile goes.
+ * @param {number} y
+ */
+export function placeTile(tile, tw, th, out, width, height, x, y) {
+	const w = Math.min(tw, width - x), h = Math.min(th, height - y);
+	for (let row = 0; row < h; row++) {
+		const src = (th - 1 - row) * tw * 4;
+		out.set(tile.subarray(src, src + w * 4), ((y + row) * width + x) * 4);
+	}
+}
+
+/**
+ * Even tiles over an image: as few as fit under the largest size, all the same size (the last may run past the edge).
+ *
+ * @param {number} size The image's side.
+ * @param {number} most The largest tile.
+ * @returns {number} The tile's side.
+ */
+export const tileSide = (size, most) => Math.ceil(size / Math.ceil(size / most));
+
+/**
+ * A still renderer for a WebGL renderer.
+ *
+ * @param {typeof import('three')} THREE three.js.
+ * @param {typeof import('three/addons/postprocessing/OutputPass.js').OutputPass} OutputPass three's output pass.
+ * @param {import('three').WebGLRenderer} renderer The renderer (the live view's).
+ * @returns {{ render(scene: import('three').Scene, camera: import('three').PerspectiveCamera, o: { width: number, height: number, transparent?: boolean, tile?: number }): Pixels, dispose(): void }}
+ */
+export function stillRenderer(THREE, OutputPass, renderer) {
+	/** @type {import('three').WebGLRenderTarget | null} */
+	let scene3d = null;
+	/** @type {import('three').WebGLRenderTarget | null} */
+	let encoded = null;
+	const pass = new OutputPass();
+	const targets = (/** @type {number} */ w, /** @type {number} */ h) => {
+		if (scene3d && scene3d.width === w && scene3d.height === h) return;
+		scene3d?.dispose();
+		encoded?.dispose();
+		const samples = Math.min(4, renderer.capabilities.maxSamples ?? 4);
+		scene3d = new THREE.WebGLRenderTarget(w, h, { type: THREE.HalfFloatType, samples });
+		encoded = new THREE.WebGLRenderTarget(w, h, { type: THREE.UnsignedByteType });
+	};
+	return {
+		render(scene, camera, { width, height, transparent = false, tile = 2048 }) {
+			const out = new Uint8ClampedArray(width * height * 4);
+			const tw = tileSide(width, tile), th = tileSide(height, tile);
+			targets(tw, th);
+			const rt = /** @type {import('three').WebGLRenderTarget} */ (scene3d), enc = /** @type {import('three').WebGLRenderTarget} */ (encoded);
+			const buf = new Uint8Array(tw * th * 4);
+			const before = { target: renderer.getRenderTarget(), alpha: renderer.getClearAlpha(), aspect: camera.aspect };
+			const clear = new THREE.Color();
+			renderer.getClearColor(clear);
+			renderer.setClearColor(0x000000, transparent ? 0 : 1);
+			camera.aspect = width / height;
+			camera.updateProjectionMatrix();
+			try {
+				for (let y = 0; y < height; y += th)
+					for (let x = 0; x < width; x += tw) {
+						camera.setViewOffset(width, height, x, y, tw, th);
+						renderer.setRenderTarget(rt);
+						renderer.clear();
+						renderer.render(scene, camera);
+						pass.render(renderer, enc, rt);
+						renderer.readRenderTargetPixels(enc, 0, 0, tw, th, buf);
+						placeTile(buf, tw, th, out, width, height, x, y);
+					}
+			} finally {
+				camera.clearViewOffset();
+				camera.aspect = before.aspect;
+				camera.updateProjectionMatrix();
+				renderer.setRenderTarget(before.target);
+				renderer.setClearColor(clear, before.alpha);
+			}
+			if (transparent) unpremultiply(out);
+			return { data: out, width, height };
+		},
+		dispose() {
+			scene3d?.dispose();
+			encoded?.dispose();
+			pass.dispose();
+		},
+	};
+}
+
+/**
+ * Pixels as a PNG.
+ *
+ * @param {Pixels} px The pixels.
+ * @returns {Promise<Blob>} The PNG.
+ */
+export async function pngOf(px) {
+	const img = new ImageData(px.data, px.width, px.height);
+	if (typeof OffscreenCanvas !== 'undefined') {
+		const c = new OffscreenCanvas(px.width, px.height);
+		/** @type {OffscreenCanvasRenderingContext2D} */ (c.getContext('2d')).putImageData(img, 0, 0);
+		return c.convertToBlob({ type: 'image/png' });
+	}
+	const c = document.createElement('canvas');
+	c.width = px.width;
+	c.height = px.height;
+	/** @type {CanvasRenderingContext2D} */ (c.getContext('2d')).putImageData(img, 0, 0);
+	return new Promise((ok, fail) => c.toBlob((b) => (b ? ok(b) : fail(new Error('logo3d: could not encode the PNG'))), 'image/png'));
+}

package/src/geometry/buffer.js

@@ -0,0 +1,102 @@
+/**
+ * @module @logomarks/logo3d/geometry/buffer
+ *
+ * A growing indexed mesh: positions, normals and UVs pushed vertex by vertex, triangles pushed into the current part,
+ * and the parts packed into typed arrays with one draw group each.
+ */
+
+/**
+ * @typedef {object} Group
+ * @property {number} start The group's first index.
+ * @property {number} count How many indices it draws.
+ * @property {number} layer The colour layer it belongs to.
+ * @property {'face' | 'side' | 'back'} part Which part of the logo it is.
+ * @property {number} materialIndex `layer * 3` plus 0 (face), 1 (side) or 2 (back).
+ */
+
+/** The parts, in draw order within a layer. */
+export const PARTS = Object.freeze(/** @type {const} */ (['face', 'side', 'back']));
+
+/** A mesh being built. */
+export class MeshBuffer {
+	constructor() {
+		/** @type {number[]} */
+		this.position = [];
+		/** @type {number[]} */
+		this.normal = [];
+		/** @type {number[]} */
+		this.uv = [];
+		/** @type {{ layer: number, part: 'face' | 'side' | 'back', index: number[] }[]} */
+		this.parts = [];
+	}
+
+	/**
+	 * Starts a part: the triangles pushed next belong to it.
+	 *
+	 * @param {number} layer The layer.
+	 * @param {'face' | 'side' | 'back'} part The part.
+	 */
+	begin(layer, part) {
+		this.parts.push({ layer, part, index: [] });
+	}
+
+	/**
+	 * Adds a vertex.
+	 *
+	 * @param {number} x
+	 * @param {number} y
+	 * @param {number} z
+	 * @param {number} nx The normal (unit length).
+	 * @param {number} ny
+	 * @param {number} nz
+	 * @param {number} u The texture coordinates.
+	 * @param {number} v
+	 * @returns {number} Its index.
+	 */
+	vertex(x, y, z, nx, ny, nz, u, v) {
+		this.position.push(x, y, z);
+		this.normal.push(nx, ny, nz);
+		this.uv.push(u, v);
+		return this.position.length / 3 - 1;
+	}
+
+	/**
+	 * Adds a triangle to the current part, anticlockwise seen from outside.
+	 *
+	 * @param {number} a
+	 * @param {number} b
+	 * @param {number} c
+	 */
+	triangle(a, b, c) {
+		this.parts[this.parts.length - 1].index.push(a, b, c);
+	}
+
+	/**
+	 * The mesh as typed arrays, each layer's face, side and back parts merged into one group each.
+	 *
+	 * @returns {{ position: Float32Array, normal: Float32Array, uv: Float32Array, index: Uint32Array, groups: Group[] }}
+	 */
+	pack() {
+		/** @type {Map<string, number[]>} */
+		const merged = new Map();
+		for (const p of this.parts) {
+			const key = `${p.layer}:${p.part}`;
+			const list = merged.get(key);
+			if (list) for (const i of p.index) list.push(i);
+			else merged.set(key, p.index.slice());
+		}
+		const layers = Math.max(-1, ...this.parts.map((p) => p.layer)) + 1;
+		/** @type {Group[]} */
+		const groups = [];
+		/** @type {number[]} */
+		const index = [];
+		for (let layer = 0; layer < layers; layer++)
+			PARTS.forEach((part, k) => {
+				const list = merged.get(`${layer}:${part}`);
+				if (!list?.length) return;
+				groups.push({ start: index.length, count: list.length, layer, part, materialIndex: layer * 3 + k });
+				for (const i of list) index.push(i);
+			});
+		return { position: new Float32Array(this.position), normal: new Float32Array(this.normal), uv: new Float32Array(this.uv), index: new Uint32Array(index), groups };
+	}
+}

package/src/geometry/caps.js

@@ -0,0 +1,53 @@
+/**
+ * @module @logomarks/logo3d/geometry/caps
+ *
+ * The front and back faces: each polygon's rings at the face's inset, triangulated by earcut, every triangle turned
+ * to face out (+z for the front, −z for the back). UVs map the logo's box to the unit square, mirrored on the back so
+ * a texture reads the right way round from behind.
+ */
+
+import earcut from 'earcut';
+
+/**
+ * Triangles over a polygon's rings.
+ *
+ * @param {[number, number][][]} rings The outline, then the holes (as inset).
+ * @returns {{ flat: number[], tris: number[] }} The points flattened, and the triangles as indices into them.
+ */
+export function triangulate(rings) {
+	/** @type {number[]} */
+	const flat = [];
+	/** @type {number[]} */
+	const holes = [];
+	rings.forEach((r, i) => {
+		if (i) holes.push(flat.length / 2);
+		for (const p of r) flat.push(p[0], p[1]);
+	});
+	return { flat, tris: earcut(flat, holes.length ? holes : undefined, 2) };
+}
+
+/**
+ * Adds a face.
+ *
+ * @param {import('./buffer.js').MeshBuffer} mesh The mesh.
+ * @param {[number, number][][]} rings The polygon's rings at the face's inset.
+ * @param {number} z Its height.
+ * @param {boolean} front The front (+z) or the back (−z).
+ * @param {{ x0: number, y0: number, size: number }} box The logo's box, for the UVs.
+ */
+export function addCap(mesh, rings, z, front, box) {
+	const { flat, tris } = triangulate(rings);
+	const nz = front ? 1 : -1;
+	const base = [];
+	for (let i = 0; i < flat.length; i += 2) {
+		const u = (flat[i] - box.x0) / box.size, v = (flat[i + 1] - box.y0) / box.size;
+		base.push(mesh.vertex(flat[i], flat[i + 1], z, 0, 0, nz, front ? u : 1 - u, v));
+	}
+	for (let t = 0; t < tris.length; t += 3) {
+		const [a, b, c] = [tris[t], tris[t + 1], tris[t + 2]];
+		const cross = (flat[2 * b] - flat[2 * a]) * (flat[2 * c + 1] - flat[2 * a + 1]) - (flat[2 * b + 1] - flat[2 * a + 1]) * (flat[2 * c] - flat[2 * a]);
+		if (cross === 0) continue;
+		if (cross > 0 === front) mesh.triangle(base[a], base[b], base[c]);
+		else mesh.triangle(base[a], base[c], base[b]);
+	}
+}

package/src/geometry/check.js

@@ -0,0 +1,86 @@
+/**
+ * @module @logomarks/logo3d/geometry/check
+ *
+ * Whether rings cross: every pair of edges tested through a grid, so a bevel's levels can be checked for
+ * self-intersection. Edges that share a point (neighbours, or points a bevel merged) don't count as crossing.
+ */
+
+/**
+ * Whether segments ab and cd cross properly (each strictly through the other).
+ *
+ * @param {readonly number[]} a
+ * @param {readonly number[]} b
+ * @param {readonly number[]} c
+ * @param {readonly number[]} d
+ * @returns {boolean} True when they cross.
+ */
+export function segmentsCross(a, b, c, d) {
+	const side = (/** @type {readonly number[]} */ p, /** @type {readonly number[]} */ q, /** @type {readonly number[]} */ r) => (q[0] - p[0]) * (r[1] - p[1]) - (q[1] - p[1]) * (r[0] - p[0]);
+	const d1 = side(c, d, a), d2 = side(c, d, b), d3 = side(a, b, c), d4 = side(a, b, d);
+	const eps = 1e-14;
+	return ((d1 > eps && d2 < -eps) || (d1 < -eps && d2 > eps)) && ((d3 > eps && d4 < -eps) || (d3 < -eps && d4 > eps));
+}
+
+/**
+ * Whether segments ab and cd meet at all: crossing, touching (an end on the other) or overlapping along a line.
+ *
+ * @param {readonly number[]} a
+ * @param {readonly number[]} b
+ * @param {readonly number[]} c
+ * @param {readonly number[]} d
+ * @returns {boolean} True when they share a point.
+ */
+export function segmentsMeet(a, b, c, d) {
+	const side = (/** @type {readonly number[]} */ p, /** @type {readonly number[]} */ q, /** @type {readonly number[]} */ r) => Math.sign((q[0] - p[0]) * (r[1] - p[1]) - (q[1] - p[1]) * (r[0] - p[0]));
+	const within = (/** @type {readonly number[]} */ p, /** @type {readonly number[]} */ q, /** @type {readonly number[]} */ r) =>
+		Math.min(p[0], q[0]) <= r[0] && r[0] <= Math.max(p[0], q[0]) && Math.min(p[1], q[1]) <= r[1] && r[1] <= Math.max(p[1], q[1]);
+	const d1 = side(c, d, a), d2 = side(c, d, b), d3 = side(a, b, c), d4 = side(a, b, d);
+	if (d1 * d2 < 0 && d3 * d4 < 0) return true;
+	return (d1 === 0 && within(c, d, a)) || (d2 === 0 && within(c, d, b)) || (d3 === 0 && within(a, b, c)) || (d4 === 0 && within(a, b, d));
+}
+
+/**
+ * The first pair of crossing edges among some rings, or null.
+ *
+ * @param {readonly (readonly (readonly number[])[])[]} rings The rings (open).
+ * @param {{ cells?: number }} [o] `cells`: the grid's cells across (64).
+ * @returns {{ a: [number, number], b: [number, number] } | null} The two edges (ring, edge), or null when none cross.
+ */
+export function firstCrossing(rings, { cells = 64 } = {}) {
+	/** @type {[number, number, readonly number[], readonly number[]][]} */
+	const edges = [];
+	let x0 = Infinity, y0 = Infinity, x1 = -Infinity, y1 = -Infinity;
+	rings.forEach((r, ri) =>
+		r.forEach((p, i) => {
+			const q = r[(i + 1) % r.length];
+			if (p[0] === q[0] && p[1] === q[1]) return;
+			edges.push([ri, i, p, q]);
+			x0 = Math.min(x0, p[0]);
+			y0 = Math.min(y0, p[1]);
+			x1 = Math.max(x1, p[0]);
+			y1 = Math.max(y1, p[1]);
+		}),
+	);
+	const w = (x1 - x0) / cells || 1, h = (y1 - y0) / cells || 1;
+	/** @type {Map<number, number[]>} */
+	const grid = new Map();
+	const cell = (/** @type {number} */ v, /** @type {number} */ o, /** @type {number} */ s) => Math.min(cells - 1, Math.max(0, Math.floor((v - o) / s)));
+	edges.forEach(([, , p, q], e) => {
+		for (let cx = cell(Math.min(p[0], q[0]), x0, w); cx <= cell(Math.max(p[0], q[0]), x0, w); cx++)
+			for (let cy = cell(Math.min(p[1], q[1]), y0, h); cy <= cell(Math.max(p[1], q[1]), y0, h); cy++) {
+				const k = cy * cells + cx;
+				const list = grid.get(k);
+				if (list) list.push(e);
+				else grid.set(k, [e]);
+			}
+	});
+	const shares = (/** @type {readonly number[][]} */ [a, b, c, d]) => [c, d].some((s) => (s[0] === a[0] && s[1] === a[1]) || (s[0] === b[0] && s[1] === b[1]));
+	for (const list of grid.values())
+		for (let i = 0; i < list.length; i++)
+			for (let j = i + 1; j < list.length; j++) {
+				const A = edges[list[i]], B = edges[list[j]];
+				if (shares([A[2], A[3], B[2], B[3]])) continue;
+				if (segmentsCross(A[2], A[3], B[2], B[3])) return { a: [A[0], A[1]], b: [B[0], B[1]] };
+			}
+	return null;
+}