@appshoteditor/shot-dsl 0.3.0 → 0.5.0

package/src/decor.ts

@@ -0,0 +1,137 @@
+/**
+ * Decoration geometry for the composer (shot-dsl 0.5.0): panorama motifs (one Fabric `Path` that
+ * runs across a whole span, offset per screen like the span background) and the rectangle tests the
+ * callout / mascot placement uses. Pure math + plain JSON; no DSL layers are validated here.
+ */
+
+export interface Rect {
+	left: number;
+	top: number;
+	right: number;
+	bottom: number;
+}
+
+export const rectOf = (cx: number, cy: number, w: number, h: number): Rect => ({ left: cx - w / 2, top: cy - h / 2, right: cx + w / 2, bottom: cy + h / 2 });
+
+export const overlaps = (a: Rect, b: Rect, pad = 0): boolean =>
+	a.left < b.right + pad && b.left < a.right + pad && a.top < b.bottom + pad && b.top < a.bottom + pad;
+
+export const insideRect = (inner: Rect, outer: Rect, eps = 1e-6): boolean =>
+	inner.left >= outer.left - eps && inner.right <= outer.right + eps && inner.top >= outer.top - eps && inner.bottom <= outer.bottom + eps;
+
+const area = (r: Rect) => Math.max(0, r.right - r.left) * Math.max(0, r.bottom - r.top);
+const intersect = (a: Rect, b: Rect): Rect => ({ left: Math.max(a.left, b.left), top: Math.max(a.top, b.top), right: Math.min(a.right, b.right), bottom: Math.min(a.bottom, b.bottom) });
+
+/**
+ * Share (0–1) of the focus band `focus` that `card` hides, NOT counting the part of the band the card
+ * magnifies itself (`source`): (card ∩ focus − card ∩ focus ∩ source) ÷ (focus − focus ∩ source).
+ */
+export function focusCoverage(card: Rect, focus: Rect, source: Rect): number {
+	const fs = intersect(focus, source);
+	const rest = area(focus) - area(fs);
+	if (rest <= 1e-9) return 0;
+	const cf = intersect(card, focus);
+	return Math.max(0, area(cf) - area(intersect(cf, source))) / rest;
+}
+
+export type PathCommand = [string, ...number[]];
+
+export type Motif = 'orbs' | 'none' | 'honeycomb' | 'wave';
+export const MOTIFS: readonly Motif[] = ['orbs', 'none', 'honeycomb', 'wave'];
+
+/**
+ * A motif across a span `spanWidth` × H, as SUBPATHS (each a list of path commands) in SPAN
+ * coordinates, deterministic.
+ * - `honeycomb`: hexagon outlines along a gentle sine band that crosses every seam.
+ * - `wave`: three flowing parallel curves across the whole span.
+ */
+export function motifSubpaths(motif: Motif, spanWidth: number, W: number, H: number): PathCommand[][] {
+	const subpaths: PathCommand[][] = [];
+	if (motif === 'honeycomb') {
+		const r = 0.085 * W; // hexagon circumradius
+		const dx = Math.sqrt(3) * r;
+		const dy = 1.5 * r;
+		const centre = (x: number) => H * 0.62 + H * 0.12 * Math.sin((2 * Math.PI * x) / (1.6 * W) + 0.6);
+		for (let row = -6; row <= 6; row++) {
+			const y = H * 0.62 + row * dy;
+			for (let col = -1; col * dx <= spanWidth + dx; col++) {
+				const x = col * dx + (row % 2 ? dx / 2 : 0);
+				// Keep a band ~2.6 cells tall around the sine centre line, thinning at its edges.
+				const d = Math.abs(y - centre(x)) / dy;
+				if (d > 1.3) continue;
+				const rr = d > 0.8 ? r * 0.62 : r * 0.9;
+				const hex: PathCommand[] = [];
+				for (let k = 0; k < 6; k++) {
+					const a = (Math.PI / 3) * k + Math.PI / 6;
+					hex.push([k === 0 ? 'M' : 'L', x + rr * Math.cos(a), y + rr * Math.sin(a)]);
+				}
+				hex.push(['Z']);
+				subpaths.push(hex);
+			}
+		}
+	} else if (motif === 'wave') {
+		const steps = Math.max(24, Math.ceil(spanWidth / (0.04 * W)));
+		for (const [k, base] of [0.5, 0.58, 0.66].entries()) {
+			const line: PathCommand[] = [];
+			for (let i = 0; i <= steps; i++) {
+				const x = (i / steps) * spanWidth;
+				const y = H * base + H * 0.06 * Math.sin((2 * Math.PI * x) / (1.4 * W) + k * 0.7);
+				line.push([i === 0 ? 'M' : 'L', x, y]);
+			}
+			subpaths.push(line);
+		}
+	}
+	return subpaths;
+}
+
+/** Path coordinate precision (canvas units): 0.1 keeps seams exact to well under a device pixel. */
+const MOTIF_PRECISION = 10;
+const round1 = (v: number) => Math.round(v * MOTIF_PRECISION) / MOTIF_PRECISION;
+
+/**
+ * The part of a span-wide motif that span screen `k` shows, in THAT screen's coordinates: only the
+ * subpaths (hexagons) touching [−pad, W + pad], and for open polylines only the segments that do
+ * (plus the segment crossing each window edge, so strokes run continuously over the seam).
+ * Coordinates are rounded to 0.1 unit. Both neighbours emit the geometry around their shared seam
+ * from the same span-space points (rounded after the same −k·W shift of an integer-width offset),
+ * so the halves meet exactly. Returns the commands and their bounding box (Fabric positions a Path
+ * by its bbox centre), or null when nothing is visible.
+ */
+export function motifPathForScreen(subpaths: PathCommand[][], k: number, W: number, pad: number): { path: PathCommand[]; bbox: Rect } | null {
+	const lo = k * W - pad;
+	const hi = (k + 1) * W + pad;
+	const out: PathCommand[] = [];
+	for (const sub of subpaths) {
+		const pts = sub.filter((c) => c.length >= 3) as Array<[string, number, number]>;
+		if (!pts.length) continue;
+		const closed = sub.some((c) => c[0] === 'Z');
+		if (closed) {
+			const xs = pts.map((c) => c[1]);
+			if (Math.max(...xs) < lo || Math.min(...xs) > hi) continue;
+			sub.forEach((c) => out.push(c.length >= 3 ? [c[0], round1((c[1] as number) - k * W), round1(c[2] as number)] : [c[0]]));
+			continue;
+		}
+		// Open polyline: keep point i when it or a neighbour lies inside the window.
+		const inside = pts.map((c) => c[1] >= lo && c[1] <= hi);
+		let pen = false;
+		pts.forEach((c, i) => {
+			const keep = inside[i] || (i > 0 && inside[i - 1]) || (i < pts.length - 1 && inside[i + 1]);
+			if (!keep) {
+				pen = false;
+				return;
+			}
+			out.push([pen ? 'L' : 'M', round1(c[1] - k * W), round1(c[2])]);
+			pen = true;
+		});
+	}
+	const xs: number[] = [];
+	const ys: number[] = [];
+	for (const c of out) {
+		if (c.length >= 3) {
+			xs.push(c[1] as number);
+			ys.push(c[2] as number);
+		}
+	}
+	if (!xs.length) return null;
+	return { path: out, bbox: { left: Math.min(...xs), top: Math.min(...ys), right: Math.max(...xs), bottom: Math.max(...ys) } };
+}

package/src/frames.ts

@@ -45,6 +45,8 @@ export function makeDeviceFrameLayer(opts: {
 	centerY?: number;
 	scale?: number;
 	screenshotRotation?: number;
+	/** Clockwise tilt of the whole mockup in degrees (the editor rotates the screenshot with it). */
+	angle?: number;
 	name?: string;
 }): LayerJSON {
 	const device = getDeviceFrame(opts.deviceId);
@@ -75,6 +77,7 @@ export function makeDeviceFrameLayer(opts: {
 		deviceId: opts.deviceId,
 		deviceScale: scale
 	};
+	if (opts.angle) fabricData.angle = opts.angle;
 
 	if (opts.screenshotUrl) {
 		const { screenshotWidth: width, screenshotHeight: height } = opts;

package/src/index.ts

@@ -6,3 +6,9 @@ export * from './builders';
 export * from './device-frames';
 export * from './frames';
 export * from './compose';
+export * from './layout-system';
+export * from './color';
+export * from './variants';
+export * from './typography';
+export * from './palette';
+export * from './decor';

package/src/layout-system.ts

@@ -0,0 +1,302 @@
+/**
+ * Set-wide layout geometry for the composer (shot-dsl 0.4.0): the no-tangent rule, focus-aware
+ * bleed, rotated bounding boxes and seam checks. Pure math — no DSL objects are built here, so every
+ * branch is unit-testable in isolation (see layout-system.test.ts).
+ *
+ * Vocabulary (all canvas units unless noted):
+ * - SUBJECT: what sits under the text — a device frame PNG, or the bare screenshot (frameless).
+ *   `width/height` are its natural (unscaled) pixel size; `screen` is the screenshot's area inside it.
+ * - NEAR edge: the subject's edge facing the text block (top for `text-top`, bottom for `text-bottom`).
+ *   FAR edge: the opposite one, which may bleed off the canvas.
+ * - OVERSHOOT: how far the FAR edge passes the canvas edge (> 0 = bleeds off, < 0 = gap).
+ */
+
+/** The "pro rules" thresholds. */
+export const NO_TANGENT = {
+	/** A subject that stays on-canvas must clear the edge by at least this × H. */
+	clearGap: 0.04,
+	/** A subject that bleeds must lose at least this × its own (rotated) height. */
+	minBleed: 0.12,
+	/** `bleed: "deep"` target, × the subject's height. */
+	deepBleed: 0.25,
+	/** The focus band must end at least this × H inside the canvas edge. */
+	focusSafe: 0.02,
+	/** Upper bound on the subject's (unrotated) width — targets are clamped to it too, × W. */
+	maxWidth: 0.9,
+	/**
+	 * Horizontal no-tangent rule: the subject's VISIBLE extent keeps at least this × W from each side
+	 * edge (a side bleed is only allowed as a deliberate panorama straddle across a seam).
+	 */
+	sideMargin: 0.05,
+	/** The focus band's (rotated) corners stay at least this × W inside the side edges / seams. */
+	focusSideSafe: 0.02,
+	/** A clear-with-margin option that shrinks the subject below this × its natural scale is rejected. */
+	minClearScale: 0.6,
+	/** Below this × the layout's target scale the copy leaves no usable room (composeSet throws). */
+	minScale: 0.5
+} as const;
+
+const EPS = 1e-6;
+
+export type BleedPreference = 'auto' | 'none' | 'deep';
+
+/** Fractions of the screenshot height (0 = top, 1 = bottom) that must stay visible. */
+export interface FocusBand {
+	top: number;
+	bottom: number;
+}
+
+export interface Subject {
+	width: number;
+	height: number;
+	/** Where the screenshot sits inside the subject (natural px). Frameless: the whole image. */
+	screen: { x: number; y: number; width: number; height: number };
+}
+
+export interface Point {
+	x: number;
+	y: number;
+}
+
+/** Axis-aligned bounding box of a w×h rectangle rotated by `angle` degrees. */
+export function rotatedBox(width: number, height: number, angle = 0): { width: number; height: number } {
+	const r = (angle * Math.PI) / 180;
+	const c = Math.abs(Math.cos(r));
+	const s = Math.abs(Math.sin(r));
+	return { width: width * c + height * s, height: width * s + height * c };
+}
+
+/**
+ * Canvas position of a point given in the subject's natural px (from its top-left), for a subject
+ * drawn centre-origin at (cx, cy), scaled by `scale` and rotated clockwise by `angle` (Fabric).
+ */
+export function subjectPointToCanvas(
+	subject: Subject,
+	p: Point,
+	pose: { cx: number; cy: number; scale: number; angle?: number }
+): Point {
+	const r = ((pose.angle ?? 0) * Math.PI) / 180;
+	const lx = (p.x - subject.width / 2) * pose.scale;
+	const ly = (p.y - subject.height / 2) * pose.scale;
+	return {
+		x: pose.cx + lx * Math.cos(r) - ly * Math.sin(r),
+		y: pose.cy + lx * Math.sin(r) + ly * Math.cos(r)
+	};
+}
+
+/** The focus band's four corners in the subject's natural px (full screen width, band height). */
+export function focusCorners(subject: Subject, focus: FocusBand): Point[] {
+	const { x, y, width, height } = subject.screen;
+	const top = y + focus.top * height;
+	const bottom = y + focus.bottom * height;
+	return [
+		{ x, y: top },
+		{ x: x + width, y: top },
+		{ x: x + width, y: bottom },
+		{ x, y: bottom }
+	];
+}
+
+/**
+ * How far (natural px, i.e. at scale 1) the focus band reaches from the subject's rotated-AABB NEAR
+ * edge toward its FAR edge. The subject keeps its focus visible iff
+ * `near + scale · focusReach ≤ H · (1 − focusSafe)`.
+ */
+export function focusReach(subject: Subject, focus: FocusBand, angle: number, farEdge: 'bottom' | 'top'): number {
+	const box = rotatedBox(subject.width, subject.height, angle);
+	// Rotate about the centre at scale 1, measure y from the AABB centre.
+	const ys = focusCorners(subject, focus).map((p) => subjectPointToCanvas(subject, p, { cx: 0, cy: 0, scale: 1, angle }).y);
+	return farEdge === 'bottom' ? Math.max(...ys) + box.height / 2 : box.height / 2 - Math.min(...ys);
+}
+
+/** The subject's four corners (tl, tr, br, bl) on the canvas for a pose. */
+export function subjectCorners(subject: Subject, pose: { cx: number; cy: number; scale: number; angle?: number }): Point[] {
+	return [
+		{ x: 0, y: 0 },
+		{ x: subject.width, y: 0 },
+		{ x: subject.width, y: subject.height },
+		{ x: 0, y: subject.height }
+	].map((p) => subjectPointToCanvas(subject, p, pose));
+}
+
+/** Clip a convex polygon to the horizontal band y0 ≤ y ≤ y1 (Sutherland–Hodgman, two edges). */
+export function clipPolygonToBand(points: Point[], y0: number, y1: number): Point[] {
+	const clip = (pts: Point[], inside: (p: Point) => boolean, cut: (a: Point, b: Point) => Point) => {
+		const out: Point[] = [];
+		pts.forEach((cur, i) => {
+			const prev = pts[(i + pts.length - 1) % pts.length];
+			if (inside(cur)) {
+				if (!inside(prev)) out.push(cut(prev, cur));
+				out.push(cur);
+			} else if (inside(prev)) out.push(cut(prev, cur));
+		});
+		return out;
+	};
+	const atY = (y: number) => (a: Point, b: Point): Point => ({ x: a.x + ((b.x - a.x) * (y - a.y)) / (b.y - a.y), y });
+	const top = clip(points, (p) => p.y >= y0, atY(y0));
+	return top.length ? clip(top, (p) => p.y <= y1, atY(y1)) : [];
+}
+
+/** Horizontal extent of the part of the subject that is actually on the canvas (null if none). */
+export function visibleXExtent(
+	subject: Subject,
+	pose: { cx: number; cy: number; scale: number; angle?: number },
+	canvasHeight: number
+): { min: number; max: number } | null {
+	const poly = clipPolygonToBand(subjectCorners(subject, pose), 0, canvasHeight);
+	if (poly.length === 0) return null;
+	const xs = poly.map((p) => p.x);
+	return { min: Math.min(...xs), max: Math.max(...xs) };
+}
+
+/** Horizontal extent of the focus band's rotated corners. */
+export function focusXExtent(
+	subject: Subject,
+	focus: FocusBand,
+	pose: { cx: number; cy: number; scale: number; angle?: number }
+): { min: number; max: number } {
+	const xs = focusCorners(subject, focus).map((p) => subjectPointToCanvas(subject, p, pose).x);
+	return { min: Math.min(...xs), max: Math.max(...xs) };
+}
+
+/** True when a far edge overshoot is in the forbidden "just touching" band. */
+export function inTangentZone(overshoot: number, subjectHeight: number, canvasHeight: number): boolean {
+	return overshoot > -NO_TANGENT.clearGap * canvasHeight + EPS && overshoot < NO_TANGENT.minBleed * subjectHeight - EPS;
+}
+
+export interface VerticalInput {
+	canvasWidth: number;
+	canvasHeight: number;
+	/** Distance from the text-side canvas edge to where the subject's near edge may start. */
+	near: number;
+	/** The subject's near edge can't start closer than this (hero layouts push the device lower). */
+	minNear?: number;
+	/** Unrotated natural width (width targets are expressed on it, so a tilt doesn't shrink the device). */
+	baseWidth: number;
+	/** Rotated-AABB natural height (vertical extent). */
+	boxHeight: number;
+	/** Target rendered width, × W. */
+	targetWidth: number;
+	/** The natural scale is capped so no more than this fraction of the subject is off-canvas. */
+	maxBleed: number;
+	/** See `focusReach`; null = no focus band marked (unconstrained). */
+	focusReach: number | null;
+	bleed: BleedPreference;
+	/** Tilted subjects: prefer a decisive bleed whenever one is possible (tilt is paired with a bleed). */
+	preferBleed?: boolean;
+	/** Hard upper bound on the scale (e.g. from the horizontal rules); applied to every option. */
+	scaleCap?: number;
+}
+
+export interface VerticalResult {
+	scale: number;
+	/** Distance from the text-side edge to the subject's near edge. */
+	near: number;
+	/** Far edge overshoot (> 0 bleeds off the canvas). */
+	overshoot: number;
+	mode: 'clear' | 'bleed';
+	/** overshoot ÷ rendered subject height (negative when clear). */
+	bleedFraction: number;
+	/** Why this option was picked (debug/report aid). */
+	reason: string;
+}
+
+/**
+ * THE no-tangent solver. Given where the subject may start (below the set's reserved text area) and
+ * how big it wants to be, return a placement whose far edge either clears the canvas edge by
+ * ≥ `clearGap`·H or bleeds by ≥ `minBleed` of the subject's height — never in between — and never
+ * pushes the focus band off-canvas. Options:
+ * - CLEAR: keep the near edge, shrink until the far edge clears with the margin.
+ * - BLEED: grow (up to `maxWidth`·W), then shift toward the far edge, until the overshoot reaches
+ *   the target; if that hides the focus band, the largest focus-safe bleed ≥ `minBleed` is used,
+ *   else the bleed option is unavailable.
+ * `none` → always clear. `deep` → bleed ≥ `deepBleed` (or the most the focus allows), else clear.
+ * `auto` → keep the natural placement when it already clears by the margin or is a focus-safe
+ * decisive bleed; otherwise (the tangent zone) PREFER the bleed option, and fall back to clear only
+ * when every ≥ `minBleed` bleed would crop the focus band. `preferBleed` (tilt) also turns a natural
+ * clear into a bleed.
+ */
+export function solveVertical(inp: VerticalInput): VerticalResult {
+	const W = inp.canvasWidth;
+	const H = inp.canvasHeight;
+	const eh = inp.boxHeight;
+	const near0 = Math.max(inp.near, inp.minNear ?? 0);
+	const cap = inp.scaleCap ?? Infinity;
+	const sCap = Math.min((NO_TANGENT.maxWidth * W) / inp.baseWidth, cap);
+	const target = Math.min(inp.targetWidth, NO_TANGENT.maxWidth);
+	const s0 = Math.max(0, Math.min((target * W) / inp.baseWidth, (H - near0) / (1 - inp.maxBleed) / eh, cap));
+	const focusLimit = H * (1 - NO_TANGENT.focusSafe);
+
+	const overshoot = (s: number, a: number) => a + s * eh - H;
+	const focusOk = (s: number, a: number) => inp.focusReach == null || a + s * inp.focusReach <= focusLimit + EPS;
+	const make = (s: number, a: number, reason: string): VerticalResult => {
+		const o = overshoot(s, a);
+		return { scale: s, near: a, overshoot: o, mode: o > 0 ? 'bleed' : 'clear', bleedFraction: o / (s * eh), reason };
+	};
+
+	const clearOption = (): VerticalResult | null => {
+		const s = Math.min(s0, (H * (1 - NO_TANGENT.clearGap) - near0) / eh);
+		if (!(s > 0) || s < NO_TANGENT.minClearScale * s0 - EPS) return null;
+		return make(s, near0, s < s0 - EPS ? 'shrunk to clear the edge with a margin' : 'clears the edge');
+	};
+
+	/** Smallest move reaching overshoot ≥ t·height, then made focus-safe (null if impossible). */
+	const bleedOption = (t: number): VerticalResult | null => {
+		let s = s0;
+		let a = near0;
+		if (overshoot(s, a) < t * s * eh - EPS) {
+			const need = (H - a) / ((1 - t) * eh);
+			s = Math.max(s0, Math.min(need, Math.max(sCap, s0)));
+			if (overshoot(s, a) < t * s * eh - EPS) a = H - s * eh * (1 - t);
+		}
+		if (focusOk(s, a)) return make(s, a, `bleeds ${Math.round(t * 100)}%+`);
+		// Focus-constrained: keep the scale (≤ what the focus allows at near0) and bleed only as deep
+		// as the focus band allows — accepted if that is still a decisive (≥ minBleed) bleed.
+		if (inp.focusReach == null) return null;
+		const fr = inp.focusReach;
+		const sF = Math.min(s, Math.max(sCap, s0), (focusLimit - near0) / fr);
+		const denom = eh * (1 - NO_TANGENT.minBleed) - fr;
+		if (!(sF > 0) || denom <= 0 || sF < (H - focusLimit) / denom - EPS) return null;
+		const aF = Math.max(near0, Math.min(focusLimit - sF * fr, H - sF * eh * (1 - t)));
+		if (overshoot(sF, aF) < NO_TANGENT.minBleed * sF * eh - EPS || !focusOk(sF, aF)) return null;
+		return make(sF, aF, 'bleed reduced to keep the focus band visible');
+	};
+
+	/** Last resort (never a tangent): clear with the margin however small that makes the subject. */
+	const forcedClear = () => make(Math.max(0, Math.min(s0, (H * (1 - NO_TANGENT.clearGap) - near0) / eh)), near0, 'forced clear');
+
+	if (inp.bleed === 'none') return clearOption() ?? forcedClear();
+
+	const naturalOver = overshoot(s0, near0);
+	const naturalClear = naturalOver <= -NO_TANGENT.clearGap * H + EPS;
+	const naturalBleed = naturalOver >= NO_TANGENT.minBleed * s0 * eh - EPS;
+
+	if (inp.bleed === 'deep') {
+		const t = Math.max(NO_TANGENT.deepBleed, naturalBleed ? naturalOver / (s0 * eh) : 0);
+		return bleedOption(t) ?? clearOption() ?? forcedClear();
+	}
+
+	// auto
+	if (naturalClear && !inp.preferBleed) return make(s0, near0, 'natural placement clears the edge');
+	if (naturalBleed && focusOk(s0, near0)) return make(s0, near0, 'natural placement bleeds decisively');
+	// In the tangent zone (or a tilted subject): resolve by bleeding decisively. Clear-with-margin
+	// only when no ≥ minBleed bleed keeps the focus band visible.
+	const bleed = bleedOption(NO_TANGENT.minBleed);
+	if (bleed) return inp.preferBleed ? { ...bleed, reason: `${bleed.reason} (tilt pairs with a bleed)` } : bleed;
+	if (naturalClear) return make(s0, near0, 'natural placement clears the edge');
+	return clearOption() ?? forcedClear();
+}
+
+/** Does the vertical line x = `seamX` pass through the polygon spanned by `points`? */
+export function crossesVertical(points: Point[], seamX: number, margin = 0): boolean {
+	const xs = points.map((p) => p.x);
+	return Math.min(...xs) < seamX + margin && Math.max(...xs) > seamX - margin;
+}
+
+/** Do two axis-aligned rects overlap? */
+export function rectsOverlap(
+	a: { left: number; top: number; right: number; bottom: number },
+	b: { left: number; top: number; right: number; bottom: number }
+): boolean {
+	return a.left < b.right && b.left < a.right && a.top < b.bottom && b.top < a.bottom;
+}

package/src/palette.ts

@@ -0,0 +1,186 @@
+/**
+ * Brand palette system (shot-dsl 0.5.0): tonal backgrounds from the app's brand colours and ONE
+ * set-wide text colour that passes WCAG AA (≥ 4.5:1) on every style-derived background.
+ *
+ * - `tonal` (new): `colors: [base, accent?]`, `tone: light | vivid | deep`. Each screen gets a
+ *   light↔deep step of the base hue as a subtle vertical gradient (`light`: pale tints; `vivid`:
+ *   around the brand colour; `deep`: richer, darker, warmer steps — still a colour, not a
+ *   near-black); the text colour is a deep (or pale) tint of the same hue, never a grey.
+ * - `family` / `sequence` (0.4.0): unchanged colours, but now also ONE text colour per set.
+ *
+ * Contrast is enforced by generation: `harmonize` evaluates both text candidates (dark / light),
+ * picks the one that needs the smaller tone adjustment, and moves every style-derived background
+ * stop away from the text colour (lighter under dark text, deeper under light text) in small
+ * steps until the WORST sampled point of every background passes.
+ */
+import type { BackgroundJSON, ColorStop } from './types';
+import { contrastRatio, isHexColor, mixHex, parseHex, toHex, DARK_TEXT, LIGHT_TEXT } from './color';
+
+export const MIN_CONTRAST = 4.5;
+/** Generation aims a little above AA so rounding never lands a sample at 4.49. */
+const TARGET_CONTRAST = 4.6;
+
+export type PaletteTone = 'light' | 'vivid' | 'deep';
+
+export interface HSL {
+	h: number;
+	s: number;
+	l: number;
+}
+
+export function hexToHsl(hex: string): HSL {
+	const c = parseHex(hex) ?? { r: 31, g: 41, b: 55 };
+	const r = c.r / 255;
+	const g = c.g / 255;
+	const b = c.b / 255;
+	const max = Math.max(r, g, b);
+	const min = Math.min(r, g, b);
+	const l = (max + min) / 2;
+	if (max === min) return { h: 0, s: 0, l };
+	const d = max - min;
+	const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+	let h: number;
+	if (max === r) h = (g - b) / d + (g < b ? 6 : 0);
+	else if (max === g) h = (b - r) / d + 2;
+	else h = (r - g) / d + 4;
+	return { h: h * 60, s, l };
+}
+
+export function hslToHex({ h, s, l }: HSL): string {
+	const hh = (((h % 360) + 360) % 360) / 360;
+	const ss = Math.min(1, Math.max(0, s));
+	const ll = Math.min(1, Math.max(0, l));
+	if (ss === 0) return toHex({ r: ll * 255, g: ll * 255, b: ll * 255 });
+	const q = ll < 0.5 ? ll * (1 + ss) : ll + ss - ll * ss;
+	const p = 2 * ll - q;
+	const hue = (t: number) => {
+		let x = t;
+		if (x < 0) x += 1;
+		if (x > 1) x -= 1;
+		if (x < 1 / 6) return p + (q - p) * 6 * x;
+		if (x < 1 / 2) return q;
+		if (x < 2 / 3) return p + (q - p) * (2 / 3 - x) * 6;
+		return p;
+	};
+	return toHex({ r: hue(hh + 1 / 3) * 255, g: hue(hh) * 255, b: hue(hh - 1 / 3) * 255 });
+}
+
+/** Lightness steps (and per-step hue drift) of each tone; screen i uses step i % 4, the hero step 0. */
+const TONE_STEPS: Record<PaletteTone, { l: number[]; sat: number; spread: number }> = {
+	light: { l: [0.9, 0.93, 0.87, 0.95], sat: 0.85, spread: 0.035 },
+	vivid: { l: [0, 0.09, -0.06, 0.15], sat: 1, spread: 0.07 },
+	// Deep = richer, darker and warmer than the brand colour, still a colour (not a near-black).
+	deep: { l: [0.46, 0.52, 0.42, 0.49], sat: 1, spread: 0.08 }
+};
+const HUE_DRIFT: Record<PaletteTone, number[]> = { light: [0, -5, 4, -8], vivid: [0, -5, 4, -8], deep: [-8, -3, -12, -6] };
+
+/**
+ * The tonal background of step `step` for `base` (before any contrast shift): a vertical gradient
+ * (editor angle 180°: offset 0 = BOTTOM) from a slightly deeper tone at the bottom to a lighter
+ * one at the top.
+ */
+export function tonalBackground(base: string, tone: PaletteTone, step: number): BackgroundJSON {
+	const hsl = hexToHsl(base);
+	const spec = TONE_STEPS[tone];
+	const k = ((step % 4) + 4) % 4;
+	const l = tone === 'vivid' ? Math.min(0.72, Math.max(0.34, hsl.l + spec.l[k])) : spec.l[k];
+	const s = Math.min(1, hsl.s * spec.sat);
+	const h = hsl.h + HUE_DRIFT[tone][k];
+	const stops: ColorStop[] = [
+		{ offset: 0, color: hslToHex({ h: h + 3, s, l: l - spec.spread }) },
+		{ offset: 1, color: hslToHex({ h: h - 3, s: s * 0.96, l: l + spec.spread }) }
+	];
+	return { type: 'gradient', gradient: { type: 'linear', colorStops: stops, angle: 180 } };
+}
+
+/** Text candidates for a palette: a deep tint of the base hue and a pale one (tonal), else neutral. */
+export function textCandidates(base: string | null): { dark: string; light: string } {
+	if (!base) return { dark: DARK_TEXT, light: LIGHT_TEXT };
+	const { h, s } = hexToHsl(base);
+	return {
+		dark: hslToHex({ h, s: Math.min(0.75, s * 0.8 + 0.1), l: 0.11 }),
+		light: hslToHex({ h, s: Math.min(1, s), l: 0.975 })
+	};
+}
+
+/** Move a background's stops `t` (0–1) of the way toward `target` (white or black). */
+export function shiftBackground(bg: BackgroundJSON, target: string, t: number): BackgroundJSON {
+	if (t <= 0) return bg;
+	if (bg.type !== 'gradient' || !bg.gradient) {
+		return { ...bg, color: isHexColor(bg.color) ? mixHex(bg.color, target, t) : bg.color };
+	}
+	const move = (c: string) => (isHexColor(c) ? mixHex(c, target, t) : c);
+	return {
+		...bg,
+		gradient: {
+			...bg.gradient,
+			colorStops: (bg.gradient.colorStops ?? []).map((s) => ({ ...s, color: move(s.color) })),
+			...(bg.gradient.colors ? { colors: bg.gradient.colors.map(move) } : {})
+		}
+	};
+}
+
+/** Worst WCAG contrast of `text` over sampled colours. */
+export function worstContrast(text: string, samples: string[]): number {
+	return samples.length ? Math.min(...samples.map((c) => contrastRatio(text, c))) : 21;
+}
+
+export interface Harmonized {
+	text: string;
+	/** Fraction the style-derived backgrounds were moved away from the text colour (0 = untouched). */
+	shift: number;
+	/** Worst contrast over every shiftable sample after the shift. */
+	worst: number;
+	/** Worst contrast over the FIXED samples (explicit backgrounds, never recoloured); 21 when none. */
+	worstFixed: number;
+}
+
+/**
+ * Choose the set's text colour and the tone shift that makes it pass everywhere.
+ * - `samplesAt(target, shift)`: every sampled colour of the style-derived backgrounds (palette
+ *   screens, panorama spans), moved toward `target` by `shift`.
+ * - `fixed`: sampled colours of explicit backgrounds — they count toward the choice but are never
+ *   recoloured.
+ * Preference: the candidate that reaches AA on the shiftable samples with the least re-toning; the
+ * other one instead only if IT also passes on the fixed samples and costs ≤ 0.15 more shift. Failing
+ * explicit screens then get their own colour from the caller. `preferLight` breaks exact ties (the
+ * 0.4.0 white default for explicit-only sets).
+ */
+export function harmonize(
+	candidates: { dark: string; light: string },
+	samplesAt: (target: string, shift: number) => string[],
+	fixed: string[] = [],
+	preferLight = false
+): Harmonized {
+	const solve = (text: string, target: string): Harmonized => {
+		let shift = 0;
+		let worst = worstContrast(text, samplesAt(target, 0));
+		for (let i = 0; i < 40 && worst < TARGET_CONTRAST; i++) {
+			shift = Math.min(1, shift + 0.025);
+			worst = worstContrast(text, samplesAt(target, shift));
+			if (shift >= 1) break;
+		}
+		return { text, shift, worst, worstFixed: worstContrast(text, fixed) };
+	};
+	const dark = solve(candidates.dark, '#FFFFFF');
+	const light = solve(candidates.light, '#000000');
+	const passes = (h: Harmonized) => h.worst >= MIN_CONTRAST;
+	const passesAll = (h: Harmonized) => passes(h) && h.worstFixed >= MIN_CONTRAST;
+	const pick = (a: Harmonized, b: Harmonized) => {
+		if (a.shift !== b.shift) return a.shift < b.shift ? a : b;
+		if (preferLight) return b;
+		return Math.min(a.worst, a.worstFixed) >= Math.min(b.worst, b.worstFixed) ? a : b;
+	};
+	// Primary: the candidate that makes the palette pass with the least re-toning.
+	const primary = passes(dark) && passes(light) ? pick(dark, light) : passes(dark) ? dark : passes(light) ? light : dark.worst >= light.worst ? dark : light;
+	if (passesAll(primary)) return primary;
+	// The other candidate may also pass on the explicit backgrounds — worth it only if that costs
+	// little extra re-toning (a light palette is never turned dark to suit one dark screen; that
+	// screen gets its own colour instead).
+	const other = primary === dark ? light : dark;
+	if (passesAll(other) && other.shift <= primary.shift + MAX_EXTRA_SHIFT_FOR_FIXED) return other;
+	return primary;
+}
+
+/** How much more palette re-toning is acceptable to get ONE colour that also passes on explicit backgrounds. */
+const MAX_EXTRA_SHIFT_FOR_FIXED = 0.15;