@appshoteditor/shot-dsl 0.3.0 → 0.5.0

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));
 			});
 		});
 	}

package/src/variants.ts

@@ -0,0 +1,222 @@
+import {
+	canvasDimsForDevice,
+	type ComposeHero,
+	type ComposeMascot,
+	type ComposePalette,
+	type ComposePlan,
+	type ComposeScreenPlan,
+	type ComposeStyle
+} from './compose';
+import { isHexColor } from './color';
+import type { Motif } from './decor';
+
+/**
+ * Three DISTINCT art directions from one plan — Product Page Optimization test candidates, not tweaks
+ * (shot-dsl 0.5.0):
+ * - **A Brand Classic**: device frames on the vivid tonal brand palette; hero with the mascot + badge;
+ *   callouts on the selling screens (explicit, else from a tight `focus`); an accent rhythm (every 4th screen text-bottom); shadows.
+ * - **B Clean Frameless**: pale tonal backgrounds with dark text; big full-width frameless
+ *   screenshots bleeding deep off the bottom (a zoom card only where the plan marks an explicit
+ *   `crop`); magnified callouts (explicit, else derived from a tight `focus`); hero with large type
+ *   + the mascot.
+ * - **C Story Panorama**: the deep tonal palette as ONE continuous scene across triples/pairs of
+ *   screens with a flowing motif (`style.panorama.decoration`, default `wave`), the mascot
+ *   travelling across the seams, a tilted hero and deeper bleeds.
+ *
+ * KEPT from the input (every concept): name (+ suffix), canvas size, copy (headline / subheadline /
+ * badge), colours (headlineColor / subheadlineColor), `background`, `deviceId`, `screenshot`,
+ * `focus`, `crop`, `callout`, per-screen `mascot`, `art`, and the style's `font` and `bleed`
+ * preference (default `auto`; B and C use `deep` unless the input says `none`).
+ *
+ * BRAND COLOURS: `style.palette.colors` (the first is the base, a tonal palette's second is the
+ * accent); without a palette, the first screen's background colour. Concepts then use
+ * `mode: "tonal"` with their own tone. Without any brand colour, the input palette/backgrounds stay.
+ *
+ * OVERRIDDEN (the concept decides these):
+ * - every screen's `layout` → `text-top` (one shared system; the hero and rhythm accents differ);
+ * - per-screen `presentation` / `tilt` are dropped;
+ * - `hero`, `rhythm`, `callouts`, `tilt`/`tiltScreens` and `panorama` are set per concept (C keeps the
+ *   input's `panorama.spans` / `decoration` when given).
+ */
+export type VariantKey = 'A' | 'B' | 'C';
+
+export interface ComposeVariant {
+	key: VariantKey;
+	label: string;
+	plan: ComposePlan;
+}
+
+export const VARIANT_LABELS: Record<VariantKey, string> = { A: 'Brand Classic', B: 'Clean Frameless', C: 'Story Panorama' };
+
+/** Tilt (degrees) the panorama concept gives its hero screen. */
+export const VARIANT_HERO_TILT = 8;
+/** Rhythm period of concept A (every 4th screen is an accent). */
+export const VARIANT_RHYTHM_EVERY = 4;
+
+const suffix = (name: string, key: VariantKey) => `${name} — ${key} ${VARIANT_LABELS[key]}`;
+
+/** Copy a screen without the per-screen style knobs a concept decides (layout/presentation/tilt). */
+function baseScreen(screen: ComposeScreenPlan): ComposeScreenPlan {
+	const copy: ComposeScreenPlan = JSON.parse(JSON.stringify(screen));
+	delete copy.layout;
+	delete copy.presentation;
+	delete copy.tilt;
+	return { ...copy, layout: 'text-top' };
+}
+
+/** The plan's brand colours: [base, accent?] (see module doc), or null. */
+export function brandColors(plan: ComposePlan): { base: string; accent?: string } | null {
+	const pal = plan.style?.palette;
+	const colors = (pal?.colors ?? []).filter(isHexColor);
+	if (colors.length) return { base: colors[0], accent: pal?.mode === 'tonal' ? colors[1] : undefined };
+	const bg = plan.screens[0]?.background;
+	const first = bg?.type === 'gradient' ? (bg.gradient?.colorStops?.[0]?.color ?? bg.gradient?.colors?.[0]) : bg?.color;
+	return isHexColor(first) ? { base: first } : null;
+}
+
+function tonal(plan: ComposePlan, tone: 'light' | 'vivid' | 'deep'): ComposePalette | undefined {
+	const brand = brandColors(plan);
+	if (!brand) return plan.style?.palette ? JSON.parse(JSON.stringify(plan.style.palette)) : undefined;
+	return { mode: 'tonal', colors: brand.accent ? [brand.base, brand.accent] : [brand.base], tone };
+}
+
+function baseStyle(plan: ComposePlan): ComposeStyle {
+	const style = plan.style;
+	const out: ComposeStyle = { bleed: style?.bleed ?? 'auto' };
+	if (style?.font) out.font = style.font;
+	return out;
+}
+
+/** The hero mascot: the input hero's, else the first art, anchored by the headline. */
+function heroMascot(plan: ComposePlan, size?: number): ComposeMascot | undefined {
+	const given = plan.style?.hero && typeof plan.style.hero === 'object' ? plan.style.hero.mascot : undefined;
+	if (given) return { ...given };
+	const art = plan.art?.[0];
+	return art ? { art: art.id, anchor: 'headline', ...(size ? { size } : {}) } : undefined;
+}
+
+/** The input's hero screen index (-1 when the input turns the hero off). */
+function heroIndexOf(plan: ComposePlan): number {
+	const h = plan.style?.hero;
+	if (h === false) return -1;
+	const i = h && typeof h === 'object' && Number.isFinite(h.screen) ? Math.floor(h.screen!) : 0;
+	return Math.min(Math.max(0, i), Math.max(0, plan.screens.length - 1));
+}
+
+/** The concept's hero: the input's (incl. `screen`) + the concept's overrides; `false` stays off. */
+function hero(plan: ComposePlan, extra: ComposeHero, mascotSize?: number): ComposeHero | false {
+	if (plan.style?.hero === false) return false;
+	const input = plan.style?.hero && typeof plan.style.hero === 'object' ? plan.style.hero : {};
+	const out: ComposeHero = { ...JSON.parse(JSON.stringify(input)), ...extra };
+	const mascot = heroMascot(plan, mascotSize);
+	if (mascot) out.mascot = mascot;
+	return out;
+}
+
+/** Adjacent pairs [0,1], [2,3], … of screens that share a canvas size (a lone last screen stays single). */
+export function panoramaPairs(plan: ComposePlan): number[][] {
+	return panoramaRuns(plan, [2]);
+}
+
+/**
+ * Runs of adjacent same-canvas screens with lengths cycling through `sizes` (e.g. [3, 2] → triples
+ * and pairs), never leaving a lone screen when a shorter run fits.
+ */
+export function panoramaRuns(plan: ComposePlan, sizes: number[] = [3, 2]): number[][] {
+	const explicit = plan.canvasWidth != null || plan.canvasHeight != null;
+	const key = (s: ComposeScreenPlan) => {
+		if (explicit) return 'explicit';
+		const d = canvasDimsForDevice(s.deviceId);
+		return `${d.width}x${d.height}`;
+	};
+	const spans: number[][] = [];
+	let cycle = 0;
+	for (let i = 0; i < plan.screens.length; ) {
+		let len = 1;
+		while (i + len < plan.screens.length && key(plan.screens[i + len]) === key(plan.screens[i])) len++;
+		// `len` = same-canvas run from i; take the cycle's size, or the largest that fits.
+		let take = Math.min(sizes[cycle % sizes.length], len);
+		// Don't strand a single screen after this span when a smaller span would pair it up.
+		if (len - take === 1 && take > 2) take = 2;
+		if (take >= 2) {
+			spans.push(Array.from({ length: take }, (_, k) => i + k));
+			cycle++;
+			i += take;
+		} else i += 1;
+	}
+	return spans;
+}
+
+export function makeVariants(plan: ComposePlan): ComposeVariant[] {
+	const common = { canvasWidth: plan.canvasWidth, canvasHeight: plan.canvasHeight, art: plan.art };
+	const strip = <T extends object>(o: T): T => JSON.parse(JSON.stringify(o)); // drops undefined keys
+	const badge = (plan.style?.hero && typeof plan.style.hero === 'object' ? plan.style.hero.badge : undefined) ?? undefined;
+
+	const a: ComposePlan = strip({
+		...common,
+		name: suffix(plan.name, 'A'),
+		style: {
+			...baseStyle(plan),
+			presentation: 'device',
+			palette: tonal(plan, 'vivid'),
+			hero: hero(plan, { badge }),
+			rhythm: { every: VARIANT_RHYTHM_EVERY, treatment: 'text-bottom' },
+			callouts: 'auto'
+		},
+		screens: plan.screens.map(baseScreen)
+	});
+
+	const b: ComposePlan = strip({
+		...common,
+		name: suffix(plan.name, 'B'),
+		style: {
+			...baseStyle(plan),
+			// Big screenshots bleeding decisively off the bottom: the editorial "clean" look.
+			bleed: plan.style?.bleed === 'none' ? 'none' : 'deep',
+			presentation: 'frameless',
+			palette: tonal(plan, 'light'),
+			hero: hero(plan, { badge, scale: 1.3 }),
+			callouts: 'auto'
+		},
+		screens: plan.screens.map((screen) => {
+			const s = baseScreen(screen);
+			// B1: only an explicit `crop` becomes a zoom card; everything else shows the full screen.
+			if (screen.crop) s.presentation = 'zoom';
+			return s;
+		})
+	});
+
+	const pano = plan.style?.panorama;
+	const spans: number[][] = pano?.spans?.length ? JSON.parse(JSON.stringify(pano.spans)) : panoramaRuns(plan);
+	const decoration: Motif = pano?.decoration && pano.decoration !== 'orbs' ? pano.decoration : 'wave';
+	const art = plan.art?.[0];
+	const heroIndex = heroIndexOf(plan);
+	const c: ComposePlan = strip({
+		...common,
+		name: suffix(plan.name, 'C'),
+		style: {
+			...baseStyle(plan),
+			bleed: plan.style?.bleed === 'none' ? 'none' : 'deep',
+			presentation: 'device',
+			palette: tonal(plan, 'deep'),
+			hero: hero(plan, { badge, tilt: plan.style?.tilt ? plan.style.tilt : VARIANT_HERO_TILT }, 0.26),
+			callouts: 'none',
+			// The continuous scene carries the story; a straddle only when the input asks for one
+			// (a straddle needs ≥ 18% of the device on the next screen, which a focus band rarely allows).
+			panorama: { spans, ...(pano?.straddle !== undefined ? { straddle: pano.straddle } : {}), decoration }
+		},
+		screens: plan.screens.map((screen, i) => {
+			const s = baseScreen(screen);
+			// The mascot travels: it crosses the first seam of every span except the hero's.
+			const span = spans.find((sp) => sp[0] === i);
+			if (art && span && !span.includes(heroIndex) && !s.mascot) s.mascot = { art: art.id, anchor: 'seam', size: 0.2 };
+			return s;
+		})
+	});
+
+	return [
+		{ key: 'A', label: VARIANT_LABELS.A, plan: a },
+		{ key: 'B', label: VARIANT_LABELS.B, plan: b },
+		{ key: 'C', label: VARIANT_LABELS.C, plan: c }
+	];
+}