@johnmorrisdotca/dougu-sports 0.8.0 → 0.10.0

package/dist/emblems/ball/ball.baseball.js

@@ -1,5 +1,5 @@
 // Baseball: a white leather ball with 108 red double stitches in V's along the figure-eight seam.
-import { seamedBall } from "./ball.family.seamed.js";
+import { SEAMED_HOME, seamedBall } from "./ball.family.seamed.js";
 export const BALL_BASEBALL = /* @__PURE__ */ seamedBall({
     id: "ball:baseball",
     en: "Baseball",
@@ -9,6 +9,7 @@ export const BALL_BASEBALL = /* @__PURE__ */ seamedBall({
     b: 0.4,
     view: { yaw: 18, pitch: 28, roll: -10 },
     mat: { gloss: 0.3, shade: "#4a3a2a", grain: { f: 1.4, a: 0.12 } },
+    home: SEAMED_HOME("baseball"),
     groove: "#8a7a62",
     stitch: { colour: "#c4262e", count: 108, half: 0.075, width: 0.85, lean: 0.032 },
 });

package/dist/emblems/ball/ball.contrast.d.ts

@@ -0,0 +1,4 @@
+/** The contrast of two colours, 1 to 21. */
+export declare function contrast(a: string, b: string): number;
+/** The stitch colour for a ball: the wanted one if it is a colour, else the ball's own thread, cream, navy or near-black, whichever shows on every colour the ball is. */
+export declare function stitchFor(grounds: readonly string[], wanted: string | undefined, fallback: string): string;

package/dist/emblems/ball/ball.contrast.js

@@ -0,0 +1,22 @@
+// Contrast of colours, for choosing a thread or an ink that shows on the ball. Imports only the core's colour reader.
+import { hexOf, readColour } from "./ball.core.js";
+const luminance = (hex) => {
+    const rgb = readColour(hex) ?? [128, 128, 128];
+    const f = (c) => {
+        const v = c / 255;
+        return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+    };
+    return 0.2126 * f(rgb[0]) + 0.7152 * f(rgb[1]) + 0.0722 * f(rgb[2]);
+};
+/** The contrast of two colours, 1 to 21. */
+export function contrast(a, b) {
+    const x = luminance(a), y = luminance(b);
+    return (Math.max(x, y) + 0.05) / (Math.min(x, y) + 0.05);
+}
+/** The stitch colour for a ball: the wanted one if it is a colour, else the ball's own thread, cream, navy or near-black, whichever shows on every colour the ball is. */
+export function stitchFor(grounds, wanted, fallback) {
+    const w = wanted === undefined ? undefined : readColour(wanted);
+    if (w !== undefined)
+        return hexOf(w);
+    return [fallback, "#f4f0e6", "#1b2a5c", "#101418"].find((c) => grounds.every((g) => contrast(c, g) >= 2.2)) ?? fallback;
+}

package/dist/emblems/ball/ball.core.d.ts

@@ -1,4 +1,6 @@
 import type { FlagRenderer, PuckFace } from "./ball.face.ts";
+import type { Surface } from "./ball.engine.ts";
+import type { BallDecal, BallMark, BallPaint, BallScript, BallSpots, BallStamp } from "./ball.print.ts";
 /** `metal` (also written `colour`): full colour, with shading. `line`: one outline in `currentColor`. */
 export type PieceStyle = "metal" | "colour" | "color" | "line";
 /** `inherit` (the default): the page's text colour. `auto`: dark ink on a light device and pale ink on a dark one. `light` and `dark` force one. */
@@ -27,7 +29,23 @@ export interface PieceOptions {
     flags?: FlagRenderer;
     /** A judogi seen from behind: the back number on it (see `Backnumber`). The back views of the judogi (`gear:judogi-back`, `gear:judogi-blue-back`) take it; anything else ignores it. */
     backnumber?: Backnumber;
+    /** A baseball, a softball and the classic soccer balls: the colour of the ball, as one colour or two (see `BallPaint`). Any other ball takes the body colour as a tint. */
+    paint?: string | BallPaint;
+    /** A baseball, a softball and the classic soccer balls: a logo printed on the side of the ball, wrapped to the sphere (see `BallDecal`). An SVG string, a `data:` image URI or an object. */
+    decal?: string | BallDecal;
+    /** The same balls: stamped text like a ball's stamp, `true` for the default (see `BallStamp`). */
+    stamp?: boolean | string | readonly string[] | BallStamp;
+    /** The same balls: a cursive script word where a maker's mark sits, `true` for the ball's own word, or your text (see `BallScript`). */
+    script?: boolean | string | BallScript;
+    /** The same balls: a small mark under the script, `true` for the circled letter, an SVG string of your own, or an object (see `BallMark`). */
+    mark?: boolean | string | BallMark;
+    /** The same balls: where on the ball the logo and the lettering go (see `BallSpots`). */
+    spots?: BallSpots;
+    /** @internal The function that draws the print of a ball (`printLayers`). `renderEmblem`, the registry and `printed()` set it; a ball taken from its own module has none and ignores `decal`, `stamp`, `script` and `mark`. */
+    printer?: PrintRenderer;
 }
+/** What draws the print of a ball on its surface: the options, the ball's own word, and the colours the print lies on. */
+export type PrintRenderer = (s: Surface, p: PrintOptions | undefined, word: string, grounds: readonly string[]) => string;
 /**
  * The back number sewn on the back of a judogi (IJF Sport and Organisation Rules, C1.8): the competitor's family name and the three letters of the National Olympic Committee, on a white patch under a coloured band.
  * Only `gear:judogi-back` and `gear:judogi-blue-back` take it; anything else ignores it.
@@ -112,7 +130,31 @@ export interface ResolvedOptions {
     flags: FlagRenderer | undefined;
     /** A string that tells two faces apart, for the ids of a drawing. */
     faceKey: string;
+    /** The colours of a printed or painted ball, read and made safe; undefined when none was asked for. */
+    paint: ResolvedPaint | undefined;
+    /** What a ball is printed with, as the caller gave it (made safe where it is drawn, by `resolvePrint`); undefined when nothing was asked for. */
+    print: PrintOptions | undefined;
+    /** What draws the print, when the caller has it (see `PieceOptions.printer`). */
+    printer: PrintRenderer | undefined;
 }
+/** The colours of a painted ball, as hex colours. */
+export interface ResolvedPaint {
+    body: string | undefined;
+    second: string | undefined;
+    split: "seam" | "half";
+    angle: number;
+    stitch: string | undefined;
+}
+/** The printing options of a ball, as given. */
+export interface PrintOptions {
+    decal?: PieceOptions["decal"];
+    stamp?: PieceOptions["stamp"];
+    script?: PieceOptions["script"];
+    mark?: PieceOptions["mark"];
+    spots?: PieceOptions["spots"];
+}
+/** True when a ball is asked to carry a logo, lettering or a mark. */
+export declare const hasPrint: (p: PrintOptions | undefined) => boolean;
 export declare function resolveOptions(o: PieceOptions | undefined): ResolvedOptions;
 /** The ink of a drawing when a theme sets it, and the page it is made to read on. */
 export declare const PIECE_INK: {

package/dist/emblems/ball/ball.core.js

@@ -42,6 +42,39 @@ export function hashOf(text) {
         h = Math.imul(h ^ text.charCodeAt(i), 16777619);
     return (h >>> 0).toString(36);
 }
+/** True when a ball is asked to carry a logo, lettering or a mark. */
+export const hasPrint = (p) => p !== undefined && ((p.decal !== undefined && p.decal !== false) || [p.stamp, p.script, p.mark].some((v) => v !== undefined && v !== false));
+function paintOf(value) {
+    const o = typeof value === "string" ? { body: value } : typeof value === "object" && value !== null ? value : undefined;
+    if (o === undefined)
+        return undefined;
+    const pick = (v) => {
+        const rgb = typeof v === "string" ? readColour(v) : undefined;
+        return rgb === undefined ? undefined : hexOf(rgb);
+    };
+    const body = pick(o.body), second = pick(o.second), stitch = pick(o.stitch);
+    if (body === undefined && second === undefined && stitch === undefined)
+        return undefined;
+    const angle = typeof o.angle === "number" && Number.isFinite(o.angle) ? Math.max(-360, Math.min(360, o.angle)) : 0;
+    return { body, second, split: o.split === "half" ? "half" : "seam", angle, stitch };
+}
+/** The printing options that were given, copied (a hostile object is never held), or undefined when there are none. */
+function printOf(o) {
+    if (o === undefined)
+        return undefined;
+    const p = {};
+    if (o.decal !== undefined)
+        p.decal = o.decal;
+    if (o.stamp !== undefined)
+        p.stamp = o.stamp;
+    if (o.script !== undefined)
+        p.script = o.script;
+    if (o.mark !== undefined)
+        p.mark = o.mark;
+    if (o.spots !== undefined)
+        p.spots = o.spots;
+    return Object.keys(p).length === 0 ? undefined : p;
+}
 /** What tells one face from another: its plain data (a renderer is a function, and only its name goes in). */
 function faceKeyOf(face) {
     if (typeof face !== "object" || face === null)
@@ -68,7 +101,7 @@ export function resolveOptions(o) {
     const theme = o?.theme === "auto" || o?.theme === "light" || o?.theme === "dark" ? o.theme : "inherit";
     const tint = readColour(o?.tint);
     const accent = readColour(o?.accent);
-    return { style: o?.style === "line" ? "line" : "colour", size, theme, tint: tint === undefined ? undefined : hexOf(tint), accent: accent === undefined ? undefined : hexOf(accent), colors: coloursOf(o?.colors), grain: typeof o?.grain === "boolean" ? o.grain : undefined, face: typeof o?.face === "object" && o.face !== null ? o.face : undefined, flags: typeof o?.flags === "function" ? o.flags : undefined, faceKey: faceKeyOf(o?.face) + (typeof o?.flags === "function" ? `|fn:${o.flags.name}` : "") };
+    return { style: o?.style === "line" ? "line" : "colour", size, theme, tint: tint === undefined ? undefined : hexOf(tint), accent: accent === undefined ? undefined : hexOf(accent), colors: coloursOf(o?.colors), grain: typeof o?.grain === "boolean" ? o.grain : undefined, face: typeof o?.face === "object" && o.face !== null ? o.face : undefined, flags: typeof o?.flags === "function" ? o.flags : undefined, faceKey: faceKeyOf(o?.face) + (typeof o?.flags === "function" ? `|fn:${o.flags.name}` : ""), paint: paintOf(o?.paint), print: printOf(o), printer: typeof o?.printer === "function" ? o.printer : undefined };
 }
 /** The ink of a drawing when a theme sets it, and the page it is made to read on. */
 export const PIECE_INK = { light: "#20262d", dark: "#eef1f3" };

package/dist/emblems/ball/ball.engine.d.ts

@@ -1,5 +1,5 @@
-import { type Piece, type PieceSize, type ResolvedOptions } from "./ball.core.ts";
-import { type V3 } from "./ball.math.ts";
+import { type Piece, type PieceSize, type PrintOptions, type PrintRenderer, type ResolvedOptions, type ResolvedPaint } from "./ball.core.ts";
+import { type M3, type V3 } from "./ball.math.ts";
 /** How a ball takes the light. */
 export interface Material {
     /** The colour of the shadowed side; by default the base colour made darker. */
@@ -32,12 +32,14 @@ export interface Surface {
         ink?: boolean;
         opacity?: number;
         n?: number;
+        rule?: "evenodd";
     }): string;
     /** Several closed polygons of one fill, drawn as one path (a smaller document than a path for each). */
     panels(rings: ReadonlyArray<readonly V3[]>, fill: string, o?: {
         ink?: boolean;
         opacity?: number;
         n?: number;
+        rule?: "evenodd";
     }): string;
     /** A curve on the surface: only what faces you. `closed` joins its ends; `deco` marks a line that is not part of the ball's form (a highlight), which the line style leaves out. */
     stroke(pts: readonly V3[], colour: string, width: number, o?: StrokeOptions): string;
@@ -59,8 +61,16 @@ export interface Surface {
     facing(u: V3): number;
     /** A point of space, in units of the ball's radius from its centre (not on the surface): its screen position and depth (positive is toward you). */
     space(p: V3): [number, number, number];
+    /** The whole disc of the ball filled with a colour (a sphere's silhouette). */
+    fill(colour: string): string;
+    /** The ball's view, for a module that draws what the engine does not (`ball.region.ts`). Opaque to everything else. */
+    readonly view: Geometry;
+    /** Where a ball's printing sits: the middle of its label area in the ball's own frame, and the right-hand and upward directions there. Only a ball that is printed has one. */
+    readonly home: HomeFrame | undefined;
 }
 export interface StrokeOptions {
+    /** Digits kept after the point in the path (1 by default; lettering asks for 2). */
+    digits?: number;
     closed?: boolean;
     ink?: boolean;
     deco?: boolean;
@@ -88,8 +98,23 @@ export interface BallSpec {
     /** The colour the whole ball is filled with before its panels are laid on, where it is not `base` (a soccer ball is white, its pentagons are `base`). */
     ground?: string;
     mat: Material;
-    /** Lays the panels and seams. `base` is the main colour, or the tint; `accent` is the second colour or undefined. */
-    draw: (s: Surface, base: string, accent: string | undefined, colors?: readonly [string, string, string]) => string;
+    /** Lays the panels and seams. `base` is the main colour, or the tint; `accent` is the second colour or undefined. `custom` is what a caller asked to paint and print (a ball that takes it reads it; the rest ignore it). */
+    draw: (s: Surface, base: string, accent: string | undefined, colors?: readonly [string, string, string], custom?: Custom) => string;
+    /**
+     * Where a ball carries a logo and lettering: the middle of the label area (`c`) and the way up there (`up`), as directions in the ball's own frame, how far it reaches from the middle (`reach`, radians),
+     * the view that shows it (`view`, used instead of `view` when the caller prints something) and the ball's own word for the script and the stamp (`word`).
+     */
+    home?: {
+        c: V3;
+        up: V3;
+        reach: number;
+        view: {
+            yaw: number;
+            pitch: number;
+            roll: number;
+        };
+        word: string;
+    };
     /** Where the ball's centre is in the 100 by 100 box (50, 50 by default): a hammer's head sits in a corner to leave room for the wire. */
     centre?: readonly [number, number];
     /** Where the ball is in space, in units of its radius from the middle of the whole (0, 0, 0 by default), turned with it: a hammer's head is at one end of the hammer, which turns about its middle. */
@@ -102,6 +127,47 @@ export interface BallSpec {
         front: string;
     };
 }
+/** The label area of a printed ball: its middle, and the right-hand and upward directions there, and how far it reaches. */
+export interface HomeFrame {
+    c: V3;
+    ex: V3;
+    up: V3;
+    reach: number;
+}
+/** What a caller asked a ball to be painted and printed with. */
+export interface Custom {
+    paint: ResolvedPaint | undefined;
+    print: PrintOptions | undefined;
+    /** Draws the print, when the caller has it; without it a ball draws no print. */
+    printer: PrintRenderer | undefined;
+}
+export declare const EPS = 0.000001;
+export interface Geometry {
+    /** The centre of the ball on the screen, and the middle of the whole (where a point of `space` is measured from). */
+    cx: number;
+    cy: number;
+    ox: number;
+    oy: number;
+    axes: V3;
+    rot: M3;
+    k: number;
+    /** The unit sphere's point is visible when its dot with `w` is above 0. */
+    w: V3;
+    wl: number;
+    /** The third row of the rotation: the direction of the eye in the ball's own frame. */
+    rz: V3;
+    /** The exponent of a pointed ball's profile, or undefined for an ellipsoid. */
+    point: number | undefined;
+}
+/** How squarely a point of the sphere faces the eye, before it is scaled: above 0 is the side you see. For an ellipsoid it is the dot of the point with `w`; for a pointed ball the surface's normal is worked out. */
+export declare const visOf: (g: Geometry, u: V3) => number;
+export declare const project: (g: Geometry, u: V3) => [number, number];
+export interface Run {
+    pts: Array<[number, number, number]>;
+}
+/** The parts of a curve that face you, each as screen points with their facing. The curve is cut exactly at the limb. */
+export declare function visibleRuns(g: Geometry, pts: readonly V3[], closed: boolean): Run[];
+export declare const pathOf: (pts: Array<[number, number, number]>, digits?: number) => string;
 /** Draws a ball: the document for a spec, the options and a turn in radians. */
 export declare function drawBall(title: string, key: string, spec: BallSpec, opts: ResolvedOptions, turn: {
     yaw: number;

package/dist/emblems/ball/ball.engine.js

@@ -1,9 +1,9 @@
 // The ball renderer: one procedural engine for every sphere and every prolate ball. A ball is drawn in true 3D: a rotation, an orthographic projection, back faces dropped, panels cut at the limb
 // along the limb itself, then radial-gradient shading and a grain that stays where it is while the ball turns. A ball is a `BallSpec`: its shape (the semi-axes of an ellipsoid), its
 // view, its material and a `draw` function that lays panels, seams and dots on the unit sphere; the engine does the rest.
-import { grainDef, escape, hashOf, labelled, mix, num, radians, resolveOptions, wrapPiece } from "./ball.core.js";
+import { grainDef, hasPrint, blend, escape, hashOf, labelled, mix, num, radians, resolveOptions, wrapPiece } from "./ball.core.js";
 import { add, apply, basis, cross, dot, ellipseOf, len, mul, norm, rotation, sampleRing, sub } from "./ball.math.js";
-const EPS = 1e-6;
+export const EPS = 1e-6;
 const STEP = Math.PI / 18;
 /** How a point of the unit sphere is carried to the ball's surface: an ellipsoid's scaling, and for a pointed ball a narrowing of the cross-section toward the ends. */
 const shapeOf = (g, u) => {
@@ -11,7 +11,7 @@ const shapeOf = (g, u) => {
     return [u[0] * g.axes[0], u[1] * g.axes[1] * f, u[2] * g.axes[2] * f];
 };
 /** How squarely a point of the sphere faces the eye, before it is scaled: above 0 is the side you see. For an ellipsoid it is the dot of the point with `w`; for a pointed ball the surface's normal is worked out. */
-const visOf = (g, u) => {
+export const visOf = (g, u) => {
     if (g.point === undefined)
         return dot(u, g.w);
     const rest = Math.max(0, 1 - u[0] * u[0]);
@@ -20,7 +20,7 @@ const visOf = (g, u) => {
     const nx = 2 * b * g.point * u[0] * rest ** (g.point - 0.5);
     return (g.rz[0] * nx + g.rz[1] * a * u[1] + g.rz[2] * a * u[2]) / (a * b);
 };
-const project = (g, u) => {
+export const project = (g, u) => {
     const q = apply(g.rot, shapeOf(g, u));
     return [g.cx + g.k * q[0], g.cy - g.k * q[1]];
 };
@@ -82,7 +82,7 @@ function limbArc(g, from, to) {
     return out;
 }
 /** The parts of a curve that face you, each as screen points with their facing. The curve is cut exactly at the limb. */
-function visibleRuns(g, pts, closed) {
+export function visibleRuns(g, pts, closed) {
     const n = pts.length;
     const vis = pts.map((p) => visOf(g, p) / g.wl);
     const at = (u, f) => {
@@ -130,9 +130,34 @@ function visibleRuns(g, pts, closed) {
     }
     return runs;
 }
-const pathOf = (pts) => pts.map((p, i) => `${i === 0 ? "M" : "L"}${num(p[0])} ${num(p[1])}`).join("");
+export const pathOf = (pts, digits = 1) => pts.map((p, i) => `${i === 0 ? "M" : "L"}${num(p[0], digits)} ${num(p[1], digits)}`).join("");
+/** A number written as short as SVG allows: no leading zero, and the space left out where the next number's own sign or point shows where it starts. */
+const tight = (text, after) => {
+    const t = text.replace(/^(-?)0\./, "$1.");
+    return after === "" || t.startsWith("-") || (t.startsWith(".") && after.includes(".")) ? t : ` ${t}`;
+};
+/** A run as a path of relative moves in `digits` decimals, written tight: about half the bytes of `pathOf`. Each step is the difference of the rounded points, so the line does not drift. */
+function relativePath(pts, digits) {
+    const r = (v) => Math.round(v * 10 ** digits) / 10 ** digits;
+    const first = pts[0];
+    let x = r(first[0]), y = r(first[1]);
+    let out = `M${num(x, digits)} ${num(y, digits)}l`;
+    let last = "";
+    for (let i = 1; i < pts.length; i++) {
+        const p = pts[i];
+        const nx = r(p[0]), ny = r(p[1]);
+        for (const v of [nx - x, ny - y]) {
+            const t = tight(num(v, digits), last);
+            out += t;
+            last = t.trim();
+        }
+        x = nx;
+        y = ny;
+    }
+    return out;
+}
 /** A curve's visible parts as paths: a stroke is thinner where it turns toward the limb (three steps), so it does not sit on the ball like a wire. */
-function runPaths(runs, colour, width, extra) {
+function runPaths(runs, colour, width, extra, digits = 1) {
     const tiers = [[], [], []];
     const factor = [1, 0.74, 0.5];
     const tierOf = (f) => (f > 0.55 ? 0 : f > 0.25 ? 1 : 2);
@@ -141,7 +166,7 @@ function runPaths(runs, colour, width, extra) {
         let piece = [];
         const flush = () => {
             if (piece.length > 1)
-                tiers[kind].push(pathOf(piece));
+                tiers[kind].push(digits > 1 ? relativePath(piece, digits) : pathOf(piece, digits));
             piece = [];
         };
         for (const p of run.pts) {
@@ -159,7 +184,7 @@ function runPaths(runs, colour, width, extra) {
     const make = (d, w) => (d.length === 0 ? "" : `<path d="${d.join("")}" fill="none" stroke="${colour}" stroke-width="${num(w, 2)}" stroke-linecap="round" stroke-linejoin="round"${extra}/>`);
     return make(tiers[2], width * factor[2]) + make(tiers[1], width * factor[1]) + make(tiers[0], width);
 }
-function surfaceOf(g, line, minWidth) {
+function surfaceOf(g, line, minWidth, home) {
     const INK = "currentColor";
     const facing = (u) => visOf(g, u) / g.wl;
     const s = {
@@ -181,7 +206,7 @@ function surfaceOf(g, line, minWidth) {
             const d = ringPath(g, sampleRing(ring, o?.n ?? 4));
             if (d === "")
                 return "";
-            return `<path d="${d}" fill="${line ? INK : fill}"${o?.opacity === undefined ? "" : ` opacity="${o.opacity}"`}/>`;
+            return `<path d="${d}" fill="${line ? INK : fill}"${o?.rule === undefined ? "" : ` fill-rule="${o.rule}"`}${o?.opacity === undefined ? "" : ` opacity="${o.opacity}"`}/>`;
         },
         panels(rings, fill, o) {
             if (line && o?.ink !== true)
@@ -189,8 +214,16 @@ function surfaceOf(g, line, minWidth) {
             const d = rings.map((ring) => ringPath(g, sampleRing(ring, o?.n ?? 4))).join("");
             if (d === "")
                 return "";
-            return `<path d="${d}" fill="${line ? INK : fill}"${o?.opacity === undefined ? "" : ` opacity="${o.opacity}"`}/>`;
+            return `<path d="${d}" fill="${line ? INK : fill}"${o?.rule === undefined ? "" : ` fill-rule="${o.rule}"`}${o?.opacity === undefined ? "" : ` opacity="${o.opacity}"`}/>`;
         },
+        fill(colour) {
+            if (line)
+                return "";
+            const sil = silhouette(g);
+            return sil.d === "" ? `<circle ${sil.tag} fill="${colour}"/>` : `<path d="${sil.d}" fill="${colour}"/>`;
+        },
+        view: g,
+        home,
         stroke: (pts, colour, width, o) => s.strokes([pts], colour, width, o),
         strokes(curves, colour, width, o) {
             if (line && (o?.deco === true || o?.ink === false))
@@ -199,7 +232,7 @@ function surfaceOf(g, line, minWidth) {
             if (runs.length === 0)
                 return "";
             const extra = `${o?.opacity === undefined || line ? "" : ` opacity="${o.opacity}"`}${o?.dash === undefined ? "" : ` stroke-dasharray="${o.dash}"`}${o?.dx === undefined && o?.dy === undefined ? "" : ` transform="translate(${o.dx ?? 0} ${o.dy ?? 0})"`}`;
-            return runPaths(runs, line ? INK : colour, Math.max(width, minWidth), extra);
+            return runPaths(runs, line ? INK : colour, Math.max(width, minWidth), extra, o?.digits);
         },
         seam(pts, colour, width, o) {
             if (line)
@@ -297,11 +330,15 @@ export function drawBall(title, key, spec, opts, turn, turning) {
     const g = { ox, oy, cx: ox + kk * away[0], cy: oy - kk * away[1], axes, rot, k: (46 * (spec.fit ?? 1)) / Math.max(...axes), w, wl: len(w), rz, point: spec.point };
     const line = opts.style === "line";
     const minWidth = 80 / opts.size;
-    const base = opts.tint ?? spec.base;
-    const surface = surfaceOf(g, line, minWidth);
-    const layers = spec.draw(surface, base, opts.accent, opts.colors);
+    // A ball with a second colour of its own (a soccer ball's panels on a white ground) paints the body as the ground and the second colour as the panels; one with a single colour takes the body as its main colour.
+    const paint = opts.paint;
+    const two = spec.ground !== undefined;
+    const base = opts.tint ?? (two ? paint?.second : paint?.body) ?? spec.base;
+    const ground = two ? paint?.body ?? spec.ground : undefined;
+    const surface = surfaceOf(g, line, minWidth, homeOf(spec));
+    const layers = spec.draw(surface, base, opts.accent, opts.colors, { paint: opts.paint, print: opts.print, printer: opts.printer });
     const sil = silhouette(g);
-    const id = `k${hashOf(`${key}|${opts.style}|${opts.tint ?? ""}|${opts.accent ?? ""}${opts.colors === undefined ? "" : `|${opts.colors.join("")}`}|${sil.tag}${sil.d}`)}`;
+    const id = `k${hashOf(`${key}|${opts.style}|${opts.tint ?? ""}|${opts.accent ?? ""}${opts.colors === undefined ? "" : `|${opts.colors.join("")}`}|${sil.tag}${sil.d}${paint === undefined && (opts.print === undefined || opts.printer === undefined) ? "" : `|${JSON.stringify([paint, opts.printer === undefined ? undefined : opts.print])}`}`)}`;
     // A long outline (the hull of a pointed ball) is written once, in the definitions, and used wherever the silhouette is.
     const long = sil.d.length > 400;
     const outline = long ? `<path id="${id}s" d="${sil.d}"/>` : "";
@@ -312,7 +349,8 @@ export function drawBall(title, key, spec, opts, turn, turning) {
         return wrapPiece({ title, size: opts.size, theme: opts.theme, defs: outline, body: `<g fill="none" stroke-linecap="round" stroke-linejoin="round">${body}</g>` });
     }
     const m = spec.mat;
-    const shade = m.shade ?? mix(base, -0.62);
+    const painted = paint?.body !== undefined || paint?.second !== undefined;
+    const shade = painted && !two ? mix(paint?.second === undefined || paint.body === undefined ? base : blend(paint.body, paint.second, 0.5), -0.6) : m.shade ?? mix(base, -0.62);
     const grain = opts.grain ?? (opts.size >= 48 && !turning);
     const gr = grain && m.grain !== undefined ? m.grain : undefined;
     const rim = m.rim ?? 1;
@@ -325,17 +363,29 @@ export function drawBall(title, key, spec, opts, turn, turning) {
         (gr === undefined
             ? ""
             : grainDef(id, gr.f, gr.a, gr.seed));
-    const inner = `<g clip-path="url(#${id}c)"${gr === undefined ? "" : ` filter="url(#${id}n)"`}>${shape(`fill="${spec.ground ?? base}"`)}${layers}</g>`;
+    const inner = `<g clip-path="url(#${id}c)"${gr === undefined ? "" : ` filter="url(#${id}n)"`}>${shape(`fill="${ground ?? spec.ground ?? base}"`)}${layers}</g>`;
     const metal = m.metal === true ? shape(`fill="url(#${id}m)"`) : "";
     const overlays = shape(`fill="url(#${id}d)"`) + metal + shape(`fill="url(#${id}b)"`) + shape(`fill="url(#${id}h)"`);
     const at = spec.attach?.(surface, base);
     return wrapPiece({ title, size: opts.size, theme: opts.theme, defs: defs + metalDef(id, m.metal === true), body: `${at?.behind ?? ""}${inner}${overlays}${at?.front ?? ""}` });
 }
+/** A ball's label area as a surface sees it: the middle, the right-hand and the upward direction, orthogonal, and how far it reaches. */
+function homeOf(spec) {
+    const h = spec.home;
+    if (h === undefined)
+        return undefined;
+    const c = norm(h.c);
+    const ex = norm(cross(h.up, c));
+    return { c, ex, up: cross(c, ex), reach: h.reach };
+}
 const finite = (v) => (typeof v === "number" && Number.isFinite(v) ? v : 0);
 /** A ball from its definition: the `Piece` the registry and the gallery take. */
 export function defineBall(def) {
-    const view = def.spec.view;
-    const render = (o, turning) => drawBall(escape(def.en), def.id, def.spec, resolveOptions(o), { yaw: radians(view.yaw + finite(o?.yaw), 0), pitch: radians(view.pitch + finite(o?.pitch), 0), roll: radians(view.roll + finite(o?.roll), 0) }, turning);
+    const render = (o, turning) => {
+        const opts = resolveOptions(o);
+        const view = hasPrint(opts.print) && opts.printer !== undefined && opts.style !== "line" && def.spec.home !== undefined ? def.spec.home.view : def.spec.view;
+        return drawBall(escape(def.en), def.id, def.spec, opts, { yaw: radians(view.yaw + finite(o?.yaw), 0), pitch: radians(view.pitch + finite(o?.pitch), 0), roll: radians(view.roll + finite(o?.roll), 0) }, turning);
+    };
     return {
         id: def.id,
         en: def.en,

package/dist/emblems/ball/ball.family.seamed.d.ts

@@ -34,5 +34,9 @@ export interface SeamedOptions {
     };
     /** A thin groove along the seam. */
     groove?: string;
+    /** Where the ball takes its logo and lettering (see `BallSpec.home`): a baseball and a softball do. */
+    home?: BallSpec["home"];
 }
+/** The label area of a baseball's or a softball's seam (b = 0.4): the middle of one of its two leather pieces, the way up there, and the view that shows it. The point opposite is in the same leather piece, 0.6 radians clear of the seam, so lettering can go on the far side of the ball. */
+export declare const SEAMED_HOME: (word: string) => NonNullable<BallSpec["home"]>;
 export declare function seamedBall(o: SeamedOptions): Piece<BallSpec>;

package/dist/emblems/ball/ball.family.seamed.js

@@ -2,17 +2,44 @@
 // A baseball and a softball have red stitches that cross it in Vs; a tennis or padel ball has a white rubber strip along it; a sliotar a raised rib.
 import { defineBall } from "./ball.engine.js";
 import { mix } from "./ball.core.js";
+import { stitchFor } from "./ball.contrast.js";
+import { region } from "./ball.region.js";
 import { scuffs } from "./ball.decal.js";
-import { seamCurve } from "./ball.math.js";
+import { add, cross, greatCircle, mul, norm, seamCurve } from "./ball.math.js";
 import { stitches } from "./ball.stitch.js";
+/** The label area of a baseball's or a softball's seam (b = 0.4): the middle of one of its two leather pieces, the way up there, and the view that shows it. The point opposite is in the same leather piece, 0.6 radians clear of the seam, so lettering can go on the far side of the ball. */
+export const SEAMED_HOME = (word) => ({
+    c: [0.668, -0.669, -0.326],
+    up: [0.601, 0.743, -0.293],
+    reach: 0.82,
+    view: { yaw: -127.8, pitch: -47.4, roll: -7.9 },
+    word,
+});
 export function seamedBall(o) {
     const spec = {
         view: o.view ?? { yaw: 0, pitch: 0, roll: 0 },
         base: o.base,
         mat: o.mat,
-        draw: (s, base) => {
+        home: o.home,
+        draw: (s, base, _accent, _colors, custom) => {
             const seam = seamCurve(o.b, 160);
+            const paint = custom?.paint;
+            const second = paint?.second;
             let out = "";
+            // A two-tone ball: the second colour fills the region on the right of the seam (or a half of the ball), the body colour the rest.
+            if (second !== undefined && !s.line) {
+                if (paint?.split === "half" && o.home !== undefined) {
+                    const c = norm(o.home.c), ex = norm(cross(o.home.up, c));
+                    const turn = ((paint.angle ?? 0) * Math.PI) / 180;
+                    const n = add(mul(ex, Math.cos(turn)), mul(cross(c, ex), Math.sin(turn)));
+                    out += region(s, greatCircle(n, 120), second);
+                }
+                else
+                    out += region(s, [...seam].reverse(), second);
+            }
+            const grounds = second === undefined ? [base] : [base, second];
+            if (custom?.print !== undefined && o.home !== undefined)
+                out += custom.printer?.(s, custom.print, o.home.word, [base]) ?? "";
             if (o.groove !== undefined)
                 out += s.stroke(seam, o.groove, 0.8, { closed: true, opacity: 0.55 });
             if (o.strip !== undefined)
@@ -21,11 +48,19 @@ export function seamedBall(o) {
                 out += scuffs(s, mix(base, -0.55), mix(base, 0.6), { dark: o.wear.dark, pale: o.wear.pale, seed: o.wear.seed });
             if (o.stitch !== undefined) {
                 const marks = stitches(seam, true, o.stitch.count, o.stitch.half, { v: true, lean: o.stitch.lean });
-                const second = o.stitch.colour2;
-                if (second === undefined)
-                    out += s.strokes(marks, o.stitch.colour, o.stitch.width, { ink: false });
-                else
-                    out += s.strokes(marks.filter((_, i) => i % 2 === 0), o.stitch.colour, o.stitch.width, { ink: false }) + s.strokes(marks.filter((_, i) => i % 2 === 1), second, o.stitch.width, { ink: false });
+                const colour2 = o.stitch.colour2;
+                if (second !== undefined && paint?.split !== "half") {
+                    // On a ball split along its seam each stitch's two legs lie on their own colour, and take the thread that shows on it.
+                    const legs = (pick) => marks.map((m) => (pick === 0 ? [m[0], m[1]] : [m[1], m[2]]));
+                    out += s.strokes(legs(0), stitchFor([base], paint?.stitch, o.stitch.colour), o.stitch.width, { ink: false }) + s.strokes(legs(1), stitchFor([second], paint?.stitch, o.stitch.colour), o.stitch.width, { ink: false });
+                }
+                else {
+                    const colour = stitchFor(grounds, paint?.stitch, o.stitch.colour);
+                    if (colour2 === undefined || colour !== o.stitch.colour)
+                        out += s.strokes(marks, colour, o.stitch.width, { ink: false });
+                    else
+                        out += s.strokes(marks.filter((_, i) => i % 2 === 0), colour, o.stitch.width, { ink: false }) + s.strokes(marks.filter((_, i) => i % 2 === 1), colour2, o.stitch.width, { ink: false });
+                }
             }
             if (o.strip === undefined && o.stitch === undefined)
                 out += s.stroke(seam, "currentColor", 1.6, { closed: true });

package/dist/emblems/ball/ball.image.d.ts

@@ -3,6 +3,14 @@ export interface SafeImage {
     /** x, y, width and height of the drawing's own coordinates (its viewBox). */
     box: readonly [number, number, number, number];
     markup: string;
+    /** The same drawing as a list of elements in order, with the attributes that survived (ids already renamed), for a caller that draws it its own way (`ball.warp.ts` wraps it onto a sphere). */
+    nodes: readonly SafeNode[];
+}
+/** One element of a safe drawing: opened (`open`), closed (`close`) or both at once (`self`), with its safe attributes. */
+export interface SafeNode {
+    kind: "open" | "close" | "self";
+    name: string;
+    attrs: Readonly<Record<string, string>>;
 }
 /** The markup of an SVG made safe, or `undefined` when there is none to be had: not text, too long, no `<svg>` root, nothing drawable left. `prefix` is put in front of every id and every reference to one. */
 export declare function safeImage(source: unknown, prefix: string): SafeImage | undefined;

package/dist/emblems/ball/ball.image.js

@@ -54,6 +54,7 @@ export function safeImage(source, prefix) {
     const cleaned = source.replace(/<!--[\s\S]*?-->/g, "").replace(/<!\[CDATA\[[\s\S]*?\]\]>/g, "").replace(/<\?[\s\S]*?\?>/g, "").replace(/<![^>]*>/g, "");
     const tag = /<(\/?)([A-Za-z][\w:-]*)((?:[^>"']|"[^"]*"|'[^']*')*?)(\/?)>/g;
     let out = "";
+    const list = [];
     let nodes = 0;
     let root;
     // The depth inside an element being dropped (0 when none is).
@@ -73,8 +74,10 @@ export function safeImage(source, prefix) {
         }
         if (closing) {
             const top = open.pop();
-            if (top !== undefined && top !== "#root")
+            if (top !== undefined && top !== "#root") {
                 out += `</${top}>`;
+                list.push({ kind: "close", name: top, attrs: {} });
+            }
             continue;
         }
         const attrs = {};
@@ -98,6 +101,7 @@ export function safeImage(source, prefix) {
         if (attrs["style"] !== undefined)
             pairs.push(...styleAttrs(attrs["style"]));
         let written = "";
+        const kept = {};
         const seen = new Set();
         for (const [key, raw] of pairs) {
             if (!ATTRS.has(key) || seen.has(key))
@@ -106,8 +110,10 @@ export function safeImage(source, prefix) {
             if (v === undefined)
                 continue;
             seen.add(key);
+            kept[key] = v;
             written += ` ${key}="${escape(v)}"`;
         }
+        list.push({ kind: selfClosed ? "self" : "open", name, attrs: kept });
         out += `<${name}${written}${selfClosed ? "/>" : ">"}`;
         if (!selfClosed)
             open.push(name);
@@ -115,8 +121,11 @@ export function safeImage(source, prefix) {
     if (root === undefined || !/<(path|circle|ellipse|rect|line|polyline|polygon)\b/.test(out))
         return undefined;
     // Close what the text left open, so the markup is always balanced.
-    for (let top = open.pop(); top !== undefined; top = open.pop())
-        if (top !== "#root")
-            out += `</${top}>`;
-    return { box: boxOf(root), markup: out };
+    for (let top = open.pop(); top !== undefined; top = open.pop()) {
+        if (top === "#root")
+            continue;
+        out += `</${top}>`;
+        list.push({ kind: "close", name: top, attrs: {} });
+    }
+    return { box: boxOf(root), markup: out, nodes: list };
 }