@logomarks/core 0.1.11 → 0.2.1

package/CHANGELOG.md

@@ -5,6 +5,39 @@ All notable changes to `@logomarks/core` 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.2.1] — 2026-11-15
+
+### Added
+
+The Lookbook's mark measures, moved here from `@logomarks/lookbook/marks` (the code unchanged, documented and typed), so the cards and anything else that sizes a mark share one copy. Browser-safe, like the rest of `/analyse` and `/edit`.
+
+- **The optical size in `/analyse`:** `markBox(paths)` (the real box round a mark's outlines, the 448 fit's box when there is nothing to read), `inkShare(paths)` (how much of that box is ink, by scanline coverage 16 cells across), `opticalScale(box, ink)` (how much bigger to draw a wide, slim or light mark: 1 for a square solid, 448 × 200 about 1.22, never above 1.3) and `OPTICAL`, its limits.
+- **Cells by count in `/edit`:** `cellsAcross(n, box)` beside `pixelGrid` (a grid `n` cells across the box's longest side, any `n`, where `pixelGrid` takes an amount and stops at 14 across), and `markCells(paths, n)` (shapes → rings → coverage → filled cells and their path in one call).
+
+Proved on `@logomarks/lookbook` 0.1.0: its own functions give the same values as these on the golden cases, and its equivalence tests pass unchanged on them. The golden tests gain the five cases (`optical.*`, `cells.*`), on six live marks.
+
+## [0.2.0] — 2026-11-15
+
+### Added
+
+Every generic parts module the Logomarks generators still kept locally, moved here (the code unchanged, each part documented and typed), so the site keeps only its marks. Six new subpaths, none re-exported from the root:
+
+- **`/iso`:** iso objects on `/parts`' `scene()` (cylinders, frustums, lathes, poles, roofs, shops and `shopMark()`, openings cut on the fitted faces with `isoCut()`, cut-outs square to the viewer drawn by `isoFlat()`, tipped slabs), flat planes hinged and folded into one mark (`planeScene()`, `planeMark()`, `planeGlyph()`, iso or oblique `ISO`/`OBL`), and voxels (`voxRight`, `voxPlan`, `pixDepth`, `slabs`, corner monograms `cornerMark()`). From the tools' isoparts, planeparts and blockparts.
+- **`/letters`:** letters built from geometry: a Didone capital alphabet with its frames, interlace and one-move builds (`face`, `SERIF_GLYPHS`, `serifLetter`, `pairOf`, `split`, `ruled`, `framed`…), blackletter from one 30° nib (`nib`, `parted`, `BLACKLETTERS`, `blackLetter`), condensed pairs on one stem (`pillar`, `stack`), the monogram letters, and the Echo, Dot Stroke, Ink Trap and Stair faces, the last two on one 448 frame `T`, `B`, `H`.
+- **`/font`:** a capital from a font file as a shape (`glyphShape`, `fontSource`, grown mitred to a fitted hairline), its measures (`weights`, `hairline`, `structuralHairline`, `thinnestStroke`, `runsH`…) and the moves placed on it (`underCrossbar`, `armLozenge`, `stemSplit`, `inlineOpen`…). `loadFont()` takes a path or the font's bytes and names no folder: the fonts stay with whoever draws with them.
+- **`/pixels`:** dither tapers (cells, ramps, ordered-dither `taper()`, `sprite()`, free squares) and typed pixel emotes (`emote`).
+- **`/objects`:** devices and code glyphs, blades, dishes, the boxing glove and pixel sprites, cells, faces and mascot features, animals (the gecko build, two-track animals, bold outlines) and rosettes.
+- **`/forms`:** the Bold, Line and Track constructions: needle gaps and knobs, split discs, hooked capsules, jogs and chamfer checkers, tech sparkles and ribbons, split emblems, shatter, turning slats, flow grids, fold seams, swashes, rotation, stripes, guilloche and speed letters, the Track editions' kit, and soft blobs, Rail lines and interlocking locks.
+- **`/sdf`** gains the Y2K parts built from its fields: `pinch`, `ballArm`, `node`, `blob`, `stadium`.
+
+Renamed where two modules' names met in one subpath (`blackLetter`, `serifLetter`, `monoBowl`, `DOT_S`, `TRAP_S`, `PILLAR_LEFT`, `waveArm`, `geoDisc`, `discAt`, `hookAt`, `discSide`, `techChevron`, `foldQuad`, `swashQuad`, `evenBands`, `evenRing`, `shardStrip`, `GEO_X0`, `EMBLEM_W`, `HOOK_W`, `DISC_R`, `planeMark`, `planeGlyph`…). Copies of what core already had were dropped for core's own (`GAP`, `rad`, `openRing`, `mitreOffset`, `mitreBand`, `joinPts`, `chain`, `filletClosed`), and the vector helpers the families repeated are written once.
+
+### Dependencies
+
+- `/font` loads three optional peers on first use: **opentype.js** (reading the font), **clipper-lib** (already a peer for `/edit`: `mitreGrow()` keeps Clipper's integer offset, which the exact `mitreOffset`/`offsetPolygon` can't match byte for byte) and **@resvg/resvg-js** (`thinnestStroke()`'s mask: core's own scanline fill was tried and differs on the edge pixels of 172 of 176 glyphs, so it would change the measured hairlines). Nothing else needs them.
+
+Proved on the Logomarks generators: all 206 that import these parts redraw byte-identical with core in place of the local modules. The golden tests cover every new export the behaviour tests don't reach.
+
 ## [0.1.11] — 2026-11-15
 
 ### Added

package/README.md

@@ -7,6 +7,7 @@ Geometry, SVG reading, fitting, analysis and similarity for logomarks on a 512 g
 ```bash
 npm install @logomarks/core
 npm install clipper-lib   # only for the shape edits (reshape)
+npm install opentype.js clipper-lib @resvg/resvg-js   # only for /font
 ```
 
 ## Quick start
@@ -26,13 +27,19 @@ checkFit(mark).problems;              // []
 - `/geometry`: shapes and real booleans, strokes, tracks, iso solids, badges and letter skeletons
 - `/svg`: one SVG path parser, filled shapes, bounds and rings
 - `/fit`: the 448 fit and its check (refitting a fitted mark gives the same file)
-- `/analyse`: specks, slivers and pin-holes, gap and stroke widths, shape tags
+- `/analyse`: specks, slivers and pin-holes, gap and stroke widths, shape tags, the optical size (a mark's box, its ink, how much bigger to draw it)
 - `/similar`: outline and letter signatures, IoU and nearest marks
 - `/raster`: scanline fill, components, distance transform
-- `/edit`: the studio's shape edits (weight, soften, gap, detail) and pixelate
+- `/edit`: the studio's shape edits (weight, soften, gap, detail) and pixelate, by amount or by a count of cells
 - `/sdf`: shapes as signed distance fields, smooth unions and exact gap cuts, traced to kit shapes
 - `/stitch`: a mark planned as machine embroidery (fill, satin and border stitches), for a renderer to draw as thread
 - `/parts`: the parts the industry symbols are built from (Node)
+- `/iso`: iso objects (lathes, roofs, shops, cut-outs square to the viewer, tipped slabs), folded planes and voxels
+- `/letters`: letters built from geometry: a Didone serif, a blackletter nib, monogram, pillar and stem pairs, and the echo, dot-stroke, ink-trap and stair faces
+- `/font`: a capital from a font file (a path or its bytes) as a shape, its hairline measured and grown, and the house moves placed on it (Node)
+- `/pixels`: dither tapers that break a pixel mark up, and typed pixel emotes
+- `/objects`: devices and code glyphs, blades, dishes, sport, cells, faces, animals and rosettes
+- `/forms`: the Bold, Line and Track forms: discs, hooks, jogs, emblems, shatter, slats, flow grids, folds, swashes, stripes, rails, locks and track editions
 - `/batch`: a generator's runner: seeded marks, the sidecars, the command line, `slug` (Node)
 - `logomarks-skill <dir>`: writes the design skill's `kit.mjs` and `fit.mjs`
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@logomarks/core",
-  "version": "0.1.11",
-  "description": "Geometry, SVG reading, fitting, analysis and similarity for logomarks on a 512 grid: the kit the Logomarks set is drawn with (shapes, real booleans, strokes, tracks, iso solids, badges, letter skeletons), one SVG path parser, the 448 fit, speck and shape-tag analysis, outline signatures, signed distance fields traced to shapes, stitch plans for embroidery, the industry-symbol parts and the batch runner generators use.",
+  "version": "0.2.1",
+  "description": "Geometry, SVG reading, fitting, analysis and similarity for logomarks on a 512 grid: the kit the Logomarks set is drawn with (shapes, real booleans, strokes, tracks, iso solids, badges, letter skeletons), one SVG path parser, the 448 fit, speck and shape-tag analysis, outline signatures, signed distance fields traced to shapes, stitch plans for embroidery, and the parts the generators draw with: iso objects, letters and type, font glyphs, pixel dither, objects and the Bold, Line and Track forms, plus the batch runner.",
   "type": "module",
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -22,6 +22,36 @@
       "import": "./src/parts/index.js",
       "default": "./src/parts/index.js"
     },
+    "./iso": {
+      "types": "./src/iso/index.d.ts",
+      "import": "./src/iso/index.js",
+      "default": "./src/iso/index.js"
+    },
+    "./letters": {
+      "types": "./src/letters/index.d.ts",
+      "import": "./src/letters/index.js",
+      "default": "./src/letters/index.js"
+    },
+    "./font": {
+      "types": "./src/font/index.d.ts",
+      "import": "./src/font/index.js",
+      "default": "./src/font/index.js"
+    },
+    "./pixels": {
+      "types": "./src/pixels/index.d.ts",
+      "import": "./src/pixels/index.js",
+      "default": "./src/pixels/index.js"
+    },
+    "./objects": {
+      "types": "./src/objects/index.d.ts",
+      "import": "./src/objects/index.js",
+      "default": "./src/objects/index.js"
+    },
+    "./forms": {
+      "types": "./src/forms/index.d.ts",
+      "import": "./src/forms/index.js",
+      "default": "./src/forms/index.js"
+    },
     "./batch": {
       "types": "./src/batch/index.d.ts",
       "import": "./src/batch/index.js",
@@ -103,7 +133,10 @@
     "embroidery",
     "satin-stitch",
     "signed-distance-field",
-    "sdf"
+    "sdf",
+    "letters",
+    "font",
+    "pixel-art"
   ],
   "author": "David Sherlock",
   "license": "MIT",
@@ -124,16 +157,26 @@
     "polygon-clipping": "^0.15.7"
   },
   "peerDependencies": {
-    "clipper-lib": "^6.4.2"
+    "@resvg/resvg-js": "^2.6.2",
+    "clipper-lib": "^6.4.2",
+    "opentype.js": "^2.0.0"
   },
   "peerDependenciesMeta": {
+    "@resvg/resvg-js": {
+      "optional": true
+    },
     "clipper-lib": {
       "optional": true
+    },
+    "opentype.js": {
+      "optional": true
     }
   },
   "devDependencies": {
+    "@resvg/resvg-js": "^2.6.2",
     "@types/node": "^26.6.6",
     "clipper-lib": "^6.4.2",
+    "opentype.js": "^2.0.0",
     "typescript": "^6.0.3"
   }
 }

package/src/analyse/index.d.ts

@@ -6,3 +6,4 @@ export { SPECKS, vectorParts, rasterParts, markParts, smallParts } from './speck
 export { SHAPE, shapeTags, tagsOf } from './tags.js';
 export { MEASURE, shapeMeasures } from './shape/measures.js';
 export { WIDTHS, groupRuns, widths } from './widths.js';
+export { OPTICAL, markBox, inkShare, opticalScale } from './optical.js';

package/src/analyse/index.js

@@ -1,8 +1,9 @@
 /**
- * Analysis of a mark: its pieces and holes (specks, slivers, pin-holes), its stroke and gap widths, and its shape tags
- * (with the measures they are decided on).
+ * Analysis of a mark: its pieces and holes (specks, slivers, pin-holes), its stroke and gap widths, its shape tags
+ * (with the measures they are decided on), and its optical size (its real box and how much of it is ink).
  */
 export { SPECKS, vectorParts, rasterParts, markParts, smallParts } from './specks.js';
 export { SHAPE, shapeTags, tagsOf } from './tags.js';
 export { MEASURE, shapeMeasures } from './shape/measures.js';
 export { WIDTHS, groupRuns, widths } from './widths.js';
+export { OPTICAL, markBox, inkShare, opticalScale } from './optical.js';

package/src/analyse/optical.d.ts

@@ -0,0 +1,20 @@
+import type { Bounds } from '../svg/outline.js';
+
+/** The optical size's limits: the most a mark grows, and how much its box and its ink count. */
+export const OPTICAL: {
+	/** The most a mark grows (× its 448 fit). */
+	readonly max: 1.3;
+	/** The box's term: (448² / its area) to this power, so a square is 1, 448 × 200 about 1.22. */
+	readonly power: 0.25;
+	/** The ink's term: up to this much more for a light mark … */
+	readonly light: 0.1;
+	/** … in full at or below this share of its box inked, none at or above `solid`. */
+	readonly thin: 0.2;
+	readonly solid: 0.45;
+};
+/** The real box round a mark's outlines (its paths, or the whole file), on the 512 canvas; the 448 fit's box when there is nothing to read. */
+export function markBox(paths: string): Bounds;
+/** How much of a mark's own box is ink, 0–1 (scanline coverage, 16 cells across its longest side); 1 when there is nothing to read. */
+export function inkShare(paths: string): number;
+/** The mark's optical size: how much bigger to draw a wide, slim or light mark, 1 to `OPTICAL.max`; `ink` 1 leaves the ink out of it. */
+export function opticalScale(box: Pick<Bounds, 'w' | 'h'>, ink?: number): number;

package/src/analyse/optical.js

@@ -0,0 +1,76 @@
+/**
+ * @module @logomarks/core/analyse/optical
+ *
+ * A mark's optical size: its real box, how much of that box is ink, and how much bigger to draw it so a wide, slim or
+ * light mark holds as much of the eye as a square, solid one at the 448 fit. Browser-safe (core's SVG reader and
+ * scanline coverage, no renderer). From the Lookbook's mark measures (`@logomarks/lookbook/marks`).
+ */
+
+import { shapes } from '../svg/shapes.js';
+import { bounds } from '../svg/outline.js';
+import { rings } from '../svg/rings.js';
+import { cellsAcross, pixelCoverage } from '../edit/pixelate.js';
+import { CANVAS, FIT } from '../fit/index.js';
+
+/** The 448 fit's box on the 512 canvas: what `markBox` gives when there is nothing to read. */
+const FITTED = { x: (CANVAS - FIT) / 2, y: (CANVAS - FIT) / 2, w: FIT, h: FIT };
+
+/** The optical size's limits: the most a mark grows, and how much its box and its ink count. */
+export const OPTICAL = {
+	/** The most a mark grows (× its 448 fit). */
+	max: 1.3,
+	/** The box's term: (448² / its area) to this power, so a square is 1, 448 × 200 about 1.22. */
+	power: 0.25,
+	/** The ink's term: up to this much more for a light mark … */
+	light: 0.1,
+	/** … in full at or below this share of its box inked, none at or above `solid`. */
+	thin: 0.2,
+	solid: 0.45,
+};
+
+/**
+ * The real box round a mark's outlines, on the 512 canvas (curves and arcs sampled, as the fit measures them); the
+ * 448 fit's box when there is nothing to read.
+ *
+ * @param {string} paths The mark's markup: its paths, or the whole file.
+ * @returns {import('../svg/outline.js').Bounds} The box.
+ */
+export function markBox(paths) {
+	const list = shapes(paths);
+	if (!list.length) return { ...FITTED };
+	const b = bounds(list);
+	return Number.isFinite(b.w) && b.w > 0 ? b : { ...FITTED };
+}
+
+/**
+ * How much of a mark's own box is ink, 0–1: the scanline coverage on a grid 16 cells across its longest side.
+ *
+ * @param {string} paths The mark's markup: its paths, or the whole file.
+ * @returns {number} The share inked; 1 when there is nothing to read.
+ */
+export function inkShare(paths) {
+	const list = shapes(paths);
+	if (!list.length) return 1;
+	const grid = cellsAcross(16, markBox(paths));
+	const cov = pixelCoverage(list.map((s) => ({ rings: rings(s.segs, 3), evenodd: s.evenodd })), grid);
+	let sum = 0;
+	for (const v of cov) sum += v;
+	return cov.length ? sum / cov.length : 1;
+}
+
+/**
+ * The mark's optical size: how much bigger to draw it so it holds as much of the eye as a square, solid mark at the
+ * 448 fit. Every mark is fitted to 448 on its longest side, so a wide, short one (448 × 200) or a slim one (266 × 448)
+ * carries far less area, and a light, line-drawn one less weight. 1 for a square solid; 448 × 200 about 1.22; never
+ * below 1, never above `OPTICAL.max`.
+ *
+ * @param {{ w: number, h: number }} box The mark's box (`markBox`).
+ * @param {number} [ink=1] The share of its box inked (`inkShare`); 1 leaves the ink out of it.
+ * @returns {number} The scale, 1 to `OPTICAL.max`.
+ */
+export function opticalScale(box, ink = 1) {
+	const { max, power, light, thin, solid } = OPTICAL;
+	const area = (FIT * FIT) / Math.max(1, box.w * box.h);
+	const weight = 1 + light * Math.min(1, Math.max(0, (solid - ink) / (solid - thin)));
+	return Math.min(max, Math.max(1, area ** power * weight));
+}

package/src/edit/cells.d.ts

@@ -0,0 +1,13 @@
+import type { PixelGrid } from './pixelate.js';
+
+/** A mark as square cells: the grid, which cells are filled (row by row), and the filled cells as one path. */
+export interface MarkCells {
+	grid: PixelGrid;
+	/** 1 per filled cell, row by row. */
+	on: Uint8Array;
+	/** The filled cells merged into rectangles, as one path's d; empty when none is filled. */
+	d: string;
+}
+
+/** The mark (its paths, or the whole file) as square cells, `n` across its longest side, by scanline coverage. */
+export function markCells(paths: string, n: number): MarkCells;

package/src/edit/cells.js

@@ -0,0 +1,26 @@
+/**
+ * @module @logomarks/core/edit/cells
+ *
+ * A mark as square cells by count: shapes → rings → scanline coverage → filled cells in one call, on a grid `n` cells
+ * across the mark's real box (`cellsAcross`). Browser-safe. From the Lookbook's mark measures (its pixel and LED looks).
+ */
+
+import { shapes } from '../svg/shapes.js';
+import { rings } from '../svg/rings.js';
+import { markBox } from '../analyse/optical.js';
+import { cellsAcross, pixelCoverage, pixelCells, pixelPath } from './pixelate.js';
+
+/**
+ * The mark as square cells, `n` across its longest side, measured by scanline coverage (half a cell covered, or a
+ * fifth where a cell would otherwise break a thin line: `pixelCells`).
+ *
+ * @param {string} paths The mark's markup: its paths, or the whole file.
+ * @param {number} n Cells across the longest side.
+ * @returns {import('./cells.js').MarkCells} The grid, the filled cells and the filled cells as one path (empty when none).
+ */
+export function markCells(paths, n) {
+	const list = shapes(paths);
+	const grid = cellsAcross(n, markBox(paths));
+	const cov = pixelCoverage(list.map((s) => ({ rings: rings(s.segs), evenodd: s.evenodd })), grid);
+	return { grid, on: pixelCells(cov, grid), d: pixelPath(cov, grid) ?? '' };
+}

package/src/edit/index.d.ts

@@ -1,6 +1,8 @@
 export type { ShapeInfo, SmallSizeInfo } from './reshape.js';
 export type { Adjust, Frame, Similarity, AdjustEnv } from './adjust.js';
 export type { PixelGrid } from './pixelate.js';
+export type { MarkCells } from './cells.js';
 export { loadShaper, shaperReady, hasCorners, reshape, pieceCount, shapeInfo, smallSizeInfo } from './reshape.js';
 export { NO_ADJUST, isAdjusted, adjustSuffix, transformPath, adjustPaths } from './adjust.js';
-export { SS, pixelGrid, pixelPath, pixelCells, pixelCoverage } from './pixelate.js';
+export { SS, pixelGrid, cellsAcross, pixelPath, pixelCells, pixelCoverage } from './pixelate.js';
+export { markCells } from './cells.js';

package/src/edit/index.js

@@ -1,7 +1,9 @@
 /**
  * Shape edits for a studio: weight, soften, gap and detail (Clipper, loaded on first use), turns, tilts, flips and
- * frames, and pixel-art redraws. Browser-safe: what needs a renderer (exact bounds, a canvas) is passed in.
+ * frames, and pixel-art redraws (by amount, or by a count of cells across). Browser-safe: what needs a renderer (exact
+ * bounds, a canvas) is passed in.
  */
 export { loadShaper, shaperReady, hasCorners, reshape, pieceCount, shapeInfo, smallSizeInfo } from './reshape.js';
 export { NO_ADJUST, isAdjusted, adjustSuffix, transformPath, adjustPaths } from './adjust.js';
-export { SS, pixelGrid, pixelPath, pixelCells, pixelCoverage } from './pixelate.js';
+export { SS, pixelGrid, cellsAcross, pixelPath, pixelCells, pixelCoverage } from './pixelate.js';
+export { markCells } from './cells.js';

package/src/edit/pixelate.d.ts

@@ -13,6 +13,8 @@ export interface PixelGrid {
 export const SS: 6;
 /** The grid for a box: 48 cells across its longest side at amount 0, 14 at amount 1, centred. */
 export function pixelGrid(amount: number, box: { x: number; y: number; width: number; height: number }): PixelGrid;
+/** The grid for a box by count: `n` cells across its longest side (any `n`), centred. */
+export function cellsAcross(n: number, box: { x: number; y: number; w: number; h: number }): PixelGrid;
 /** How much of each cell the mark's rings cover (0–1, row by row), by scanline at SS × SS samples a cell. */
 export function pixelCoverage(paths: readonly FillPath[], grid: PixelGrid): Float32Array;
 /** The filled cells (1 each, row by row): half covered, or a fifth where a cell stands alone or bridges two. */

package/src/edit/pixelate.js

@@ -36,6 +36,21 @@ export function pixelGrid(amount, box) {
 	return { cols, rows, cell, x0, y0 };
 }
 
+/**
+ * A pixel grid of `n` cells across a box's longest side, centred on it: `pixelGrid` sized by a count, any count
+ * (`pixelGrid` takes an amount and stops at 14 across).
+ *
+ * @param {number} n Cells across the longest side.
+ * @param {{ x: number, y: number, w: number, h: number }} box The mark's box (`markBox` in `/analyse`, or `bounds`).
+ * @returns {import('./index.js').PixelGrid} The grid: columns, rows, cell size and top-left corner.
+ */
+export function cellsAcross(n, box) {
+	const cell = Math.max(box.w, box.h) / n;
+	const cols = Math.max(1, Math.round(box.w / cell)), rows = Math.max(1, Math.round(box.h / cell));
+	const x0 = box.x + box.w / 2 - (cols * cell) / 2, y0 = box.y + box.h / 2 - (rows * cell) / 2;
+	return { cols, rows, cell, x0, y0 };
+}
+
 /**
  * How much of each cell the mark covers, measured from its rings by scanline at `SS` × `SS` samples a cell: what a
  * canvas would measure, without one.

package/src/font/glyphs.d.ts

@@ -0,0 +1,31 @@
+import type { Shape } from '../geometry/types.js';
+import type { GlyphSource } from '../letters/serif.js';
+
+/** A font: its file's path, or its bytes. */
+export type FontSource = string | Uint8Array | ArrayBuffer;
+/** A parsed font (opentype.js's Font): what /font reads of it. */
+export interface Font {
+	charToGlyph(char: string): { path: { commands: { type: string; x?: number; y?: number; x1?: number; y1?: number; x2?: number; y2?: number }[] } };
+	[key: string]: unknown;
+}
+
+/** A font, parsed and cached (needs opentype.js). */
+export function loadFont(source: FontSource): Font;
+/** A font's cap height in font units: the top of its H. */
+export function capUnits(font: Font): number;
+/** Path data filled non-zero, as a shape. */
+export function nonzeroShape(d: string, step?: number): Shape;
+/** A font's character at cap height `cap`, its ink from x 0. */
+export function glyphShape(font: FontSource, char: string, o?: { cap?: number; step?: number }): { s: Shape; w: number };
+/** The shape grown by d, its corners mitred (needs clipper-lib). */
+export function mitreGrow(shape: Shape, d: number, limit?: number): Shape;
+/** A font's stem and hairline, from its H, as fractions of the cap. */
+export function weights(font: FontSource): { S: number; h: number };
+/** A font's hairline: a quantile of its letters' stroke depths, as a fraction of the cap. */
+export function hairline(font: FontSource, chars?: string, q?: number): number;
+/** A font's structural hairline, by erosion, as a fraction of the cap (needs @resvg/resvg-js). */
+export function structuralHairline(font: FontSource, chars?: string): number;
+/** A font's character as a glyph source, grown so its hairline fits to `hair`. */
+export function fontSource(font: FontSource, char: string, o?: { hair?: number; h?: number; onGrow?: (t: number) => void }): GlyphSource;
+/** A glyph source with its ink below the baseline trimmed off. */
+export function onBase(src: GlyphSource): GlyphSource;

package/src/font/glyphs.js

@@ -0,0 +1,228 @@
+/**
+ * A capital from a font file as a kit shape, drawn on the frame the serif and blackletter faces draw on (cap line at y 0,
+ * baseline at y H, y down, ink starting at x 0), so the house moves (/letters' rule, split, dot, plinth, frame, inline;
+ * the blackletter's parted lozenge and split stem) apply to a font's letter unchanged. From the Logomarks tools
+ * (fontparts.mjs, batches 242 and 243). Node only.
+ *
+ * Every function takes a font as a file path or as its bytes (a Buffer, Uint8Array or ArrayBuffer): core holds no fonts
+ * and no font folder. A font is parsed on first use and cached (by path, or by the bytes' object). It reads fonts with
+ * opentype.js and grows them with clipper-lib, both optional peers loaded on first use.
+ *
+ * Two traps the Logomarks font A/B found:
+ * - opentype.js getPath() writes NaN for Bodoni Moda's static instances and drops DM Serif Display's closepaths (which
+ *   merges its rings), so paths are built here from glyph.path.commands;
+ * - font contours overlap (Bodoni, DM Serif, Unifraktur), so glyphs are filled non-zero (`nonzeroShape()`).
+ */
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import { U, D, I, move, bbox, rect } from '../geometry/index.js';
+import { pathRings } from '../svg/index.js';
+import { shoelace as sArea } from '../util/vec.js';
+import { wind, runsH, runsV, strokeDepths, thinnestStroke } from './measure.js';
+
+const require = createRequire(import.meta.url);
+
+/**
+ * A cache for values of a font (and a sub-key): a Map for paths, keyed `path` or `path|sub` as strings, and a WeakMap of
+ * Maps for fonts passed as bytes.
+ *
+ * @template T
+ * @returns {(font: import('./glyphs.js').FontSource, sub: string | undefined, make: () => T) => T} The cached lookup.
+ */
+const fontCache = () => {
+	const paths = new Map(), bytes = new WeakMap();
+	return (font, sub, make) => {
+		if (typeof font === 'string') { const k = sub === undefined ? font : `${font}|${sub}`; if (!paths.has(k)) paths.set(k, make()); return paths.get(k); }
+		let m = bytes.get(font); if (!m) bytes.set(font, (m = new Map()));
+		const k = sub ?? ''; if (!m.has(k)) m.set(k, make()); return m.get(k);
+	};
+};
+
+const fonts = fontCache();
+
+/**
+ * A font, parsed (cached): from its file's path, or from its bytes.
+ *
+ * @param {import('./glyphs.js').FontSource} source The font file's path, or its contents.
+ * @returns {import('./glyphs.js').Font} The parsed font (opentype.js's Font).
+ */
+export const loadFont = (source) => fonts(source, undefined, () => {
+	const opentype = require('opentype.js');
+	if (source instanceof ArrayBuffer) return opentype.parse(source);
+	const b = typeof source === 'string' ? fs.readFileSync(source) : source;
+	return opentype.parse(b.buffer.slice(b.byteOffset, b.byteOffset + b.byteLength));
+});
+
+/**
+ * A font's cap height in font units: the top of its H (OS/2 sCapHeight is far off in Unifraktur).
+ *
+ * @param {import('./glyphs.js').Font} font The parsed font.
+ * @returns {number} The cap height.
+ */
+export const capUnits = (font) => Math.max(...font.charToGlyph('H').path.commands.filter((c) => c.y !== undefined).map((c) => c.y));
+
+/**
+ * A glyph's outline as SVG path data, scaled by k, its baseline at y H and y down; one subpath per contour.
+ *
+ * @param {{ path: { commands: Record<string, any>[] } }} glyph The glyph.
+ * @param {number} k The scale.
+ * @param {number} H The baseline.
+ * @returns {string} The path data.
+ */
+const glyphD = (glyph, k, H) => {
+	const X = (v) => (v * k).toFixed(3), Y = (v) => (H - v * k).toFixed(3); let d = '';
+	for (const c of glyph.path.commands) {
+		if (c.type === 'M') d += (d ? 'Z' : '') + `M${X(c.x)} ${Y(c.y)}`;
+		else if (c.type === 'L') d += `L${X(c.x)} ${Y(c.y)}`;
+		else if (c.type === 'Q') d += `Q${X(c.x1)} ${Y(c.y1)} ${X(c.x)} ${Y(c.y)}`;
+		else if (c.type === 'C') d += `C${X(c.x1)} ${Y(c.y1)} ${X(c.x2)} ${Y(c.y2)} ${X(c.x)} ${Y(c.y)}`;
+	}
+	return d + 'Z';
+};
+
+/**
+ * Rings wound non-zero (outers one way, counters the other) as a shape: each counter cut from the smallest outer
+ * holding it, then the outers united.
+ *
+ * @param {readonly (readonly number[])[][]} rings The rings.
+ * @returns {import('../geometry/types.js').Shape} The shape.
+ */
+const ringsShape = (rings) => {
+	const rs = rings.filter((r) => Math.abs(sArea(r)) > 0.5); if (!rs.length) return [];
+	const big = rs.reduce((a, r) => (Math.abs(sArea(r)) > Math.abs(sArea(a)) ? r : a)), sign = Math.sign(sArea(big));
+	const outers = rs.filter((r) => Math.sign(sArea(r)) === sign), holes = rs.filter((r) => Math.sign(sArea(r)) !== sign), own = outers.map(() => []);
+	for (const h of holes) {
+		let best = -1;
+		outers.forEach((o, i) => { if (wind(o, h[0]) !== 0 && (best < 0 || Math.abs(sArea(o)) < Math.abs(sArea(outers[best])))) best = i; });
+		if (best >= 0) own[best].push(h);
+	}
+	return U(...outers.map((o, i) => D([o], ...own[i].map((h) => [h]))));
+};
+
+/**
+ * Path data filled non-zero, as a shape, for contours that may overlap: each counter (a ring wound against the outers)
+ * is cut from the smallest outer that holds it, then the outers are united.
+ *
+ * @param {string} d The path data.
+ * @param {number} [step=1] The curves' sampling step.
+ * @returns {import('../geometry/types.js').Shape} The shape.
+ */
+export const nonzeroShape = (d, step = 1) => ringsShape(pathRings(d, step));
+
+/**
+ * A font's character as a shape, scaled so the font's cap height (its H) is `cap`: the cap line at y 0, the baseline at
+ * y cap, the ink starting at x 0. Overshoots and descenders fall outside 0…cap as the font draws them.
+ *
+ * @param {import('./glyphs.js').FontSource} font The font (a path or its bytes).
+ * @param {string} char The character.
+ * @param {{ cap?: number, step?: number }} [o] The cap height (380) and the curves' sampling step (1).
+ * @returns {{ s: import('../geometry/types.js').Shape, w: number }} The letter and its ink's width.
+ */
+export const glyphShape = (font, char, { cap = 380, step = 1 } = {}) => {
+	const f = loadFont(font), k = cap / capUnits(f);
+	const s = nonzeroShape(glyphD(f.charToGlyph(char), k, cap), step), [x0, , x1] = bbox(s);
+	return { s: move(s, -x0, 0), w: x1 - x0 };
+};
+
+/**
+ * A mitred grow: the shape grown by d with its corners kept sharp (mitred up to `limit` times d, squared off past it),
+ * where the kit's grow() rounds every corner by d. Thickening a font's hairlines with a round grow softens every serif
+ * corner; this keeps the font's cut. Clipper's offset (clipper-lib, an optional peer), in thousandths: an exact polygon
+ * offset (/geometry's offsetPolygon) can't stand in for it, since Clipper's integer grid sets every point.
+ *
+ * @param {import('../geometry/types.js').Shape} shape The shape.
+ * @param {number} d How far (0: the shape as it is).
+ * @param {number} [limit=2] The mitre limit, in multiples of d.
+ * @returns {import('../geometry/types.js').Shape} The grown shape.
+ */
+export const mitreGrow = (shape, d, limit = 2) => {
+	if (!d) return shape;
+	const CL = require('clipper-lib');
+	const P = (r) => r.map(([x, y]) => ({ X: Math.round(x * 1000), Y: Math.round(y * 1000) })), c = new CL.Clipper(), u = new CL.Paths();
+	c.AddPaths(shape.flatMap((pg) => pg.map(P)), CL.PolyType.ptSubject, true);
+	c.Execute(CL.ClipType.ctUnion, u, CL.PolyFillType.pftEvenOdd, CL.PolyFillType.pftEvenOdd); // a clean shape: outers come back positive, holes negative
+	const co = new CL.ClipperOffset(limit, 250), out = new CL.Paths(); co.AddPaths(u, CL.JoinType.jtMiter, CL.EndType.etClosedPolygon); co.Execute(out, d * 1000);
+	return ringsShape(out.map((r) => r.map(({ X, Y }) => [X / 1000, Y / 1000])));
+};
+
+/**
+ * A font's weights, read off its H at cap 1000: the stem S (the left stem across at mid-height) and the hairline h (the
+ * bar, down through the middle), as fractions of the cap.
+ *
+ * @param {import('./glyphs.js').FontSource} font The font.
+ * @returns {{ S: number, h: number }} The stem and the hairline.
+ */
+export const weights = (font) => {
+	const H = glyphShape(font, 'H', { cap: 1000 }), st = runsH(H.s, 300)[0];
+	const bar = runsV(H.s, H.w / 2).find(([a, b]) => b - a < 300); return { S: (st[1] - st[0]) / 1000, h: bar ? (bar[1] - bar[0]) / 1000 : (st[1] - st[0]) / 1000 };
+};
+
+const wcache = fontCache();
+
+/**
+ * weights(), cached.
+ *
+ * @param {import('./glyphs.js').FontSource} font The font.
+ * @returns {{ S: number, h: number }} The stem and the hairline.
+ */
+const fontWeights = (font) => wcache(font, undefined, () => weights(font));
+
+const hcache = fontCache();
+
+/**
+ * A font's hairline as a fraction of its cap: the `q` quantile of the stroke depths of `chars` (a font whose H has no
+ * hairline bar, such as a Fraktur, is measured this way; the serif faces use their H's bar, `weights()`). Cached.
+ *
+ * @param {import('./glyphs.js').FontSource} font The font.
+ * @param {string} [chars='ABCDEGHMNRST'] The letters measured.
+ * @param {number} [q=0.1] The quantile.
+ * @returns {number} The hairline, as a fraction of the cap.
+ */
+export const hairline = (font, chars = 'ABCDEGHMNRST', q = 0.1) => hcache(font, `${chars}|${q}`, () => {
+	const d = [...chars].flatMap((c) => strokeDepths(glyphShape(font, c, { cap: 1000, step: 4 }).s, 6)).sort((a, b) => a - b);
+	return d[Math.floor(d.length * q)] / 1000;
+});
+
+const scache = fontCache();
+
+/**
+ * A font's structural hairline as a fraction of its cap: the thinnest structural stroke (thinnestStroke()) over `chars`
+ * at a 448 cap, so tips and spikes don't count (Abril Fatface 0.026, New Rocker 0.085, Germania One 0.131): pass it to
+ * fontSource() as `h`. Cached; needs @resvg/resvg-js.
+ *
+ * @param {import('./glyphs.js').FontSource} font The font.
+ * @param {string} [chars='ABEFGHMNORS'] The letters measured.
+ * @returns {number} The hairline, as a fraction of the cap.
+ */
+export const structuralHairline = (font, chars = 'ABEFGHMNORS') => scache(font, chars, () => Math.min(...[...chars].map((c) => thinnestStroke(glyphShape(font, c, { cap: 448 }).s))) / 448);
+
+/**
+ * A glyph source for /letters' moves (and any build that takes a letter): `(H, { g }) => { s, w, m }`, the font's `char`
+ * at cap H on the glyph frame, with m = { H, S, h, t, dy }: its stem and hairline (after the grow), the grow t and the
+ * lift dy. Given the gap g the mark is drawn with (exact() picks g so it lands on 22 once fitted, so the fit's scale is
+ * 22 ÷ g), the glyph is grown uniformly (mitred, so its corners stay sharp) just enough that its hairline is `hair` once
+ * fitted. The hairline is the font's H bar (`weights()`), or `h` (a fraction of the cap; hairline() and
+ * structuralHairline() measure one for a face without a bar). The grow, in fitted units, is reported through `onGrow`.
+ * Without g nothing is grown. Grown, the ink is moved back so it still starts at x 0 and its baseline stays at y H (its
+ * cap line rises 2t), so base serifs, rules and plinths line up; m.dy re-centres it in a frame.
+ *
+ * @param {import('./glyphs.js').FontSource} font The font.
+ * @param {string} char The character.
+ * @param {{ hair?: number, h?: number, onGrow?: (t: number) => void }} [o] The fitted hairline wanted (29), the font's
+ *   hairline as a fraction of the cap (its H bar's by default), and a callback for the grow.
+ * @returns {import('../letters/serif.js').GlyphSource} The glyph source.
+ */
+export const fontSource = (font, char, { hair = 29, h, onGrow } = {}) => (H, o = {}) => {
+	const wt = fontWeights(font), h0 = (h ?? wt.h) * H;
+	const k = o.g ? 22 / o.g : 1, t = o.g ? Math.max(0, (hair / k - h0) / 2) : 0; if (onGrow) onGrow(+(t * k).toFixed(2));
+	const L = glyphShape(font, char, { cap: H }), s = t ? move(mitreGrow(L.s, t), t, -t) : L.s;
+	return { s, w: L.w + 2 * t, m: { H, S: wt.S * H + 2 * t, h: h0 + 2 * t, t, dy: t } };
+};
+
+/**
+ * A glyph source with its ink below the baseline trimmed off (a vertex dipping through a plinth).
+ *
+ * @param {import('../letters/serif.js').GlyphSource} src The glyph source.
+ * @returns {import('../letters/serif.js').GlyphSource} The trimmed source.
+ */
+export const onBase = (src) => (H, o) => { const L = src(H, o); return { ...L, s: I(L.s, rect(-50, -200, L.w + 100, H + 200)) }; };