@appshoteditor/shot-dsl 0.3.0 → 0.4.0

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,6 @@ export * from './builders';
 export * from './device-frames';
 export * from './frames';
 export * from './compose';
+export * from './layout-system';
+export * from './color';
+export * from './variants';

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

@@ -0,0 +1,125 @@
+import { canvasDimsForDevice, type ComposePlan, type ComposeScreenPlan, type ComposeStyle } from './compose';
+
+/**
+ * Three DISTINCT concepts from one plan — Product Page Optimization test candidates, not tweaks:
+ * - **A Framed**: device mockups, straight, one shared layout.
+ * - **B Frameless**: bare rounded screenshots; screens with a `crop` (or a tight `focus` band) become
+ *   magnified zoom cards of that UI.
+ * - **C Panorama**: adjacent pairs share one continuous background + seam orbs; only the tilted hero
+ *   (screen 1) straddles its seam — one crossing per set, rotation stays an accent.
+ *
+ * KEPT from the input (every concept): name (+ suffix), canvas size, copy (headline / subheadline /
+ * badge), colours (headlineColor / subheadlineColor), `background`, `deviceId`, `screenshot`,
+ * `focus`, `crop`, and the style's `palette`, `font` and `bleed` preference (default `auto`).
+ *
+ * OVERRIDDEN (the concept decides these):
+ * - every screen's `layout` → `text-top`: screens only share one device scale + baseline when they
+ *   share a layout, and that shared system is what makes a set look designed;
+ * - per-screen `presentation` / `tilt` are dropped; `style.presentation` is `device` (A, C) or
+ *   `frameless` (B, with `zoom` on screens that have a `crop` or a focus band ≤ 45% tall);
+ * - A and B are straight and without panorama (`tilt`, `tiltScreens`, `panorama` removed);
+ * - C tilts screen 1 only (`tiltScreens: [0]`, the input's non-zero `style.tilt` or 8°) and uses the
+ *   input's `panorama.spans` if it has them (else adjacent pairs of the same canvas size); its
+ *   `straddle` is the input's if set, else the hero only; `decoration` defaults to `orbs`.
+ */
+export type VariantKey = 'A' | 'B' | 'C';
+
+export interface ComposeVariant {
+	key: VariantKey;
+	label: string;
+	plan: ComposePlan;
+}
+
+export const VARIANT_LABELS: Record<VariantKey, string> = { A: 'Framed', B: 'Frameless', C: 'Panorama' };
+
+/** Tilt (degrees) the panorama concept gives its hero screen. */
+export const VARIANT_HERO_TILT = 8;
+/** A focus band at most this tall (fraction of the screenshot) is worth a zoom card in concept B. */
+export const VARIANT_ZOOM_MAX_FOCUS = 0.45;
+
+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' };
+}
+
+function baseStyle(style: ComposeStyle | undefined): ComposeStyle {
+	const out: ComposeStyle = { bleed: style?.bleed ?? 'auto' };
+	if (style?.palette) out.palette = JSON.parse(JSON.stringify(style.palette));
+	if (style?.font) out.font = style.font;
+	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[][] {
+	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[][] = [];
+	for (let i = 0; i + 1 < plan.screens.length; ) {
+		if (key(plan.screens[i]) === key(plan.screens[i + 1])) {
+			spans.push([i, i + 1]);
+			i += 2;
+		} else {
+			i += 1;
+		}
+	}
+	return spans;
+}
+
+export function makeVariants(plan: ComposePlan): ComposeVariant[] {
+	const common = { canvasWidth: plan.canvasWidth, canvasHeight: plan.canvasHeight };
+	const strip = <T extends object>(o: T): T => JSON.parse(JSON.stringify(o)); // drops undefined keys
+
+	const a: ComposePlan = strip({
+		...common,
+		name: suffix(plan.name, 'A'),
+		style: { ...baseStyle(plan.style), presentation: 'device' },
+		screens: plan.screens.map(baseScreen)
+	});
+
+	const b: ComposePlan = strip({
+		...common,
+		name: suffix(plan.name, 'B'),
+		style: { ...baseStyle(plan.style), presentation: 'frameless' },
+		screens: plan.screens.map((screen) => {
+			const s = baseScreen(screen);
+			const f = screen.focus;
+			const tight = !!f && Math.abs(f.bottom - f.top) <= VARIANT_ZOOM_MAX_FOCUS;
+			if (screen.crop || tight) s.presentation = 'zoom';
+			return s;
+		})
+	});
+
+	const pano = plan.style?.panorama;
+	const spans = pano?.spans?.length ? JSON.parse(JSON.stringify(pano.spans)) : panoramaPairs(plan);
+	const heroStraddle = spans.some((span: number[]) => span[0] === 0) ? [0] : [];
+	const c: ComposePlan = strip({
+		...common,
+		name: suffix(plan.name, 'C'),
+		style: {
+			...baseStyle(plan.style),
+			presentation: 'device',
+			tilt: plan.style?.tilt ? plan.style.tilt : VARIANT_HERO_TILT,
+			tiltScreens: [0],
+			// Only the hero straddles by default (≤ 1 seam crossing per set); other spans keep the
+			// continuous background + orbs with centred, straight devices.
+			panorama: { spans, straddle: pano?.straddle ?? heroStraddle, decoration: pano?.decoration ?? 'orbs' }
+		},
+		screens: plan.screens.map(baseScreen)
+	});
+
+	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 }
+	];
+}