@appshoteditor/shot-dsl 0.4.0 → 0.5.1

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/index.ts

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

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;

package/src/typography.ts

@@ -0,0 +1,200 @@
+/**
+ * Line breaking by meaning (shot-dsl 0.5.0). The composer never lets Fabric's greedy wrap decide a
+ * headline's shape:
+ * - an explicit `\n` in the copy is ALWAYS a line break — lines the author broke are never merged;
+ * - a line (explicit or not) that doesn't fit the box is broken into the SAME number of lines the
+ *   greedy wrap would use, but balanced — minimal raggedness, no single short word stranded on the
+ *   last line, breaks preferred after punctuation and never right after a short function word.
+ * The chosen breaks are emitted as `\n` in the Textbox text, so the editor shows exactly these lines
+ * (each fits the box by the conservative width model, so Fabric never re-wraps them).
+ *
+ * CJK (and other scripts written without spaces) may break between any two of their characters:
+ * such characters are tokens of their own, joined without a space.
+ */
+
+/** Width of one line (canvas units) for the font model in use. */
+export type LineWidth = (line: string) => number;
+
+/** Words that read badly at the END of a line ("Hear the / word"). */
+const WEAK_ENDINGS = new Set([
+	'a',
+	'an',
+	'the',
+	'to',
+	'of',
+	'and',
+	'or',
+	'for',
+	'in',
+	'on',
+	'at',
+	'by',
+	'with',
+	'your',
+	'my',
+	'our',
+	'their',
+	'is',
+	'it’s',
+	"it's",
+	'&'
+]);
+
+const PUNCT_END = /[.,:;!?—–)。，、！？]$/;
+
+/**
+ * Beyond this many tokens a line is broken greedily (linear) instead of balanced (the balancing DP is
+ * O(tokens² · lines)). Real headlines are ≤ ~12 words; this only keeps absurd copy fast — it fails
+ * the copy-length rules anyway.
+ */
+export const MAX_BALANCED_TOKENS = 40;
+
+/** Ideographs, kana, Hangul, fullwidth forms: break anywhere between them; about 1 em wide. */
+export function isWideChar(ch: string): boolean {
+	const c = ch.codePointAt(0) ?? 0;
+	return (
+		(c >= 0x1100 && c <= 0x115f) || // Hangul Jamo
+		(c >= 0x2e80 && c <= 0x303e) || // CJK radicals, punctuation
+		(c >= 0x3041 && c <= 0x33ff) || // kana, CJK symbols
+		(c >= 0x3400 && c <= 0x4dbf) || // CJK ext A
+		(c >= 0x4e00 && c <= 0x9fff) || // CJK unified
+		(c >= 0xa960 && c <= 0xa97f) ||
+		(c >= 0xac00 && c <= 0xd7a3) || // Hangul syllables
+		(c >= 0xf900 && c <= 0xfaff) ||
+		(c >= 0xfe30 && c <= 0xfe4f) ||
+		(c >= 0xff00 && c <= 0xff60) || // fullwidth forms
+		(c >= 0xffe0 && c <= 0xffe6) ||
+		(c >= 0x20000 && c <= 0x3fffd)
+	);
+}
+
+interface Token {
+	text: string;
+	/** A space precedes this token when it follows another on the same line. */
+	space: boolean;
+}
+
+/** Words split at spaces; runs of wide characters split per character (no space between them). */
+function tokenize(line: string): Token[] {
+	const tokens: Token[] = [];
+	for (const word of line.split(/\s+/).filter(Boolean)) {
+		let buf = '';
+		let first = true;
+		const flush = () => {
+			if (!buf) return;
+			tokens.push({ text: buf, space: first });
+			first = false;
+			buf = '';
+		};
+		for (const ch of word) {
+			if (isWideChar(ch)) {
+				flush();
+				tokens.push({ text: ch, space: first });
+				first = false;
+			} else buf += ch;
+		}
+		flush();
+	}
+	return tokens;
+}
+
+const join = (tokens: Token[], i: number, j: number) => tokens.slice(i, j).reduce((s, t, k) => s + (k > 0 && t.space ? ' ' : '') + t.text, '');
+
+/** Greedy wrap at token boundaries — the line COUNT to balance to (and the fallback breaking). */
+function greedy(tokens: Token[], maxWidth: number, width: LineWidth): Array<[number, number]> {
+	const lines: Array<[number, number]> = [];
+	let start = 0;
+	for (let j = 1; j < tokens.length; j++) {
+		if (width(join(tokens, start, j + 1)) > maxWidth) {
+			lines.push([start, j]);
+			start = j;
+		}
+	}
+	if (tokens.length) lines.push([start, tokens.length]);
+	return lines;
+}
+
+/**
+ * Balanced break of one line into its greedy line count (greedy past MAX_BALANCED_TOKENS). A single
+ * token wider than the box stays on its own line (the caller reports it — see `overlongWords`).
+ */
+function balanceLine(line: string, maxWidth: number, width: LineWidth): string[] {
+	const tokens = tokenize(line);
+	if (tokens.length === 0) return [''];
+	if (width(join(tokens, 0, tokens.length)) <= maxWidth) return [join(tokens, 0, tokens.length)];
+	const g = greedy(tokens, maxWidth, width);
+	const n = g.length;
+	const T = tokens.length;
+	if (n === 1 || T > MAX_BALANCED_TOKENS || tokens.some((t) => width(t.text) > maxWidth)) return g.map(([i, j]) => join(tokens, i, j));
+
+	const cost = (i: number, j: number, last: boolean): number => {
+		const w = width(join(tokens, i, j));
+		if (w > maxWidth) return Infinity;
+		const slack = (maxWidth - w) / maxWidth;
+		let c = slack * slack;
+		const lastWord = tokens[j - 1].text;
+		const words = j - i;
+		if (!last) {
+			if (PUNCT_END.test(lastWord)) c -= 0.12;
+			if (WEAK_ENDINGS.has(lastWord.toLowerCase())) c += 0.35;
+			// A lone word on an inner line ("See / their progress") reads as stranded too.
+			if (words === 1 && T > 2) c += 0.6;
+		} else if (words === 1 && T > 1) {
+			// A single word alone on the last line (an orphan) — heavily penalised.
+			c += 1.2;
+		}
+		return c;
+	};
+	// DP over break positions: best[k][j] = min cost of tokens[0..j) in k lines.
+	const best: number[][] = Array.from({ length: n + 1 }, () => new Array(T + 1).fill(Infinity));
+	const from: number[][] = Array.from({ length: n + 1 }, () => new Array(T + 1).fill(-1));
+	best[0][0] = 0;
+	for (let k = 1; k <= n; k++) {
+		for (let j = k; j <= T; j++) {
+			for (let i = k - 1; i < j; i++) {
+				if (best[k - 1][i] === Infinity) continue;
+				const c = best[k - 1][i] + cost(i, j, k === n && j === T);
+				if (c < best[k][j]) {
+					best[k][j] = c;
+					from[k][j] = i;
+				}
+			}
+		}
+	}
+	if (best[n][T] === Infinity) return g.map(([i, j]) => join(tokens, i, j));
+	const lines: string[] = [];
+	for (let k = n, j = T; k > 0; k--) {
+		const i = from[k][j];
+		lines.unshift(join(tokens, i, j));
+		j = i;
+	}
+	return lines;
+}
+
+/**
+ * The lines `text` is set in: every explicit `\n` line is kept as written, and only a line that
+ * doesn't fit the box is broken (balanced) — never merged with its neighbours.
+ */
+export function breakLines(text: string, maxWidth: number, width: LineWidth): string[] {
+	return text
+		.replace(/\r/g, '')
+		.split('\n')
+		.flatMap((line) => balanceLine(line.trim().replace(/\s+/g, ' '), maxWidth, width));
+}
+
+/**
+ * Tokens (words, or single wide characters) wider than the box. Fabric's Textbox never breaks inside
+ * a word — it widens the box to the longest word, which would overflow the side margin — so the
+ * composer rejects such copy with a clear error.
+ */
+export function overlongWords(text: string, maxWidth: number, width: LineWidth): string[] {
+	return tokenize(text.replace(/\n/g, ' ')).filter((t) => width(t.text) > maxWidth).map((t) => t.text);
+}
+
+/** True when the LAST line of `lines` is one short word while the block has more than one line. */
+export function hasOrphan(lines: string[]): boolean {
+	if (lines.length < 2) return false;
+	const last = lines[lines.length - 1].trim().split(/\s+/).filter(Boolean);
+	const prev = lines[lines.length - 2].trim().split(/\s+/).filter(Boolean);
+	return last.length === 1 && [...last[0]].length > 0 && !isWideChar([...last[0]][0]) && prev.length > 1;
+}

package/src/validate.ts

@@ -199,12 +199,38 @@ function checkImageRefs(value: unknown, at: string, errors: string[], depth = 0)
 	}
 }
 
+const DEVICE_SHADOW_KEYS = new Set(['color', 'blur', 'offsetX', 'offsetY']);
+
+/**
+ * Problems with a device layer's `fabricData.deviceShadow` (shot-dsl 0.5.0): `{ color, blur, offsetX,
+ * offsetY }` in canvas units — a colour string (≤ 64 chars) and finite numbers, blur in
+ * [0, canvasWidth] and offsets within ±canvasWidth (the composer emits ~7.5% / 3% of W).
+ */
+export function validateDeviceShadow(value: unknown, canvasWidth: number, at = 'deviceShadow'): string[] {
+	if (!value || typeof value !== 'object' || Array.isArray(value)) return [`${at} must be an object`];
+	const errors: string[] = [];
+	const v = value as Record<string, unknown>;
+	for (const key of Object.keys(v)) if (!DEVICE_SHADOW_KEYS.has(key)) errors.push(`${at}.${key} is not allowed`);
+	if (typeof v.color !== 'string' || !v.color || v.color.length > 64) errors.push(`${at}.color must be a colour string (≤ 64 chars)`);
+	const limit = canvasWidth > 0 && Number.isFinite(canvasWidth) ? canvasWidth : 4096;
+	const num = (key: string, min: number) => {
+		const n = v[key];
+		if (n === undefined && key !== 'blur') return;
+		if (typeof n !== 'number' || !Number.isFinite(n) || n < min || n > limit) errors.push(`${at}.${key} must be a number from ${min} to ${limit}`);
+	};
+	num('blur', 0);
+	num('offsetX', -limit);
+	num('offsetY', -limit);
+	return errors;
+}
+
 /** Per-layer fabricData rules for handoffs (see validateTemplate). */
 function validateLayerFabricData(
 	layer: LayerJSON,
 	fd: Record<string, unknown>,
 	at: string,
-	frameIds: Set<string>
+	frameIds: Set<string>,
+	canvasWidth = 0
 ): string[] {
 	const errors: string[] = [];
 	const fdAt = `${at}.fabricData`;
@@ -251,6 +277,12 @@ function validateLayerFabricData(
 		if (fd.layerType === 'deviceFrame') errors.push(`${fdAt}.layerType "deviceFrame" is only allowed on device layers`);
 	}
 
+	// Device drop shadow (0.5.0).
+	if (fd.deviceShadow !== undefined) {
+		if (layer.type !== 'device') errors.push(`${fdAt}.deviceShadow is only allowed on device layers`);
+		errors.push(...validateDeviceShadow(fd.deviceShadow, canvasWidth, `${fdAt}.deviceShadow`));
+	}
+
 	// Device-owned screenshot (0.3.0+).
 	if (fd.screenshot !== undefined) {
 		if (layer.type !== 'device') errors.push(`${fdAt}.screenshot is only allowed on device layers`);
@@ -272,6 +304,18 @@ function validateLayerFabricData(
 	return errors;
 }
 
+/**
+ * The handoff API's size cap: `POST /api/handoffs` rejects a body over this many bytes (413). The
+ * body is `JSON.stringify({ template })`. Producers (the skill's `lint` / `publish`) check
+ * `handoffBytes` against it before any network call.
+ */
+export const MAX_HANDOFF_BYTES = 256 * 1024;
+
+/** UTF-8 size of the handoff request body for `template` (what the server measures). */
+export function handoffBytes(template: unknown): number {
+	return new TextEncoder().encode(JSON.stringify({ template })).length;
+}
+
 export interface ValidationResult {
 	valid: boolean;
 	errors: string[];
@@ -315,7 +359,7 @@ export function validateTemplate(data: unknown): ValidationResult {
 
 				const fd = layer.fabricData as Record<string, unknown> | null;
 				if (!fd || typeof fd !== 'object') return;
-				errors.push(...validateLayerFabricData(layer, fd, at, frameIds));
+				errors.push(...validateLayerFabricData(layer, fd, at, frameIds, s.canvasWidth ?? 0));
 			});
 		});
 	}