@appshoteditor/shot-dsl 0.2.0 → 0.4.0

package/src/frames.ts

@@ -1,5 +1,5 @@
 import { getDeviceFrame, type DeviceFrame } from './device-frames';
-import type { LayerJSON } from './types';
+import type { DeviceScreenshotJSON, LayerJSON } from './types';
 import { generateLayerId } from './validate';
 
 const DEFAULT_CANVAS_WIDTH = 280;
@@ -24,30 +24,31 @@ export function calculateDeviceScale(
 }
 
 /**
- * Build the paired { screenshot, frame } layers for a device mockup — a Fabric-free
- * reproduction of FabricCanvas.addDeviceFrame(). Place them in a screen's `layers`
- * array in this order (screenshot below the frame).
+ * Build a device-mockup layer — a Fabric-free reproduction of the frame half of
+ * FabricCanvas.addDeviceFrame(). The screenshot rides on the frame as
+ * `fabricData.screenshot` (see `DeviceScreenshotJSON`); the editor places + clips it
+ * under the frame on import (same path as dropping a screenshot onto a frame), so no
+ * screenshot geometry or clip path is emitted here.
  *
  * `screenshotWidth`/`screenshotHeight` are the screenshot's natural pixel size
- * (the composer supplies them from the uploaded asset's stored dimensions).
- *
- * NOTE: geometry matches the editor exactly; the precise Fabric serialization shape
- * (esp. clipPath) should be confirmed by round-tripping a composed device template
- * through the editor before the skill relies on it in production.
+ * (the composer supplies them from the uploaded asset's stored dimensions) and are
+ * required with `screenshotUrl` (throws otherwise). Omit `screenshotUrl` for an empty frame.
  */
-export function makeDeviceFrameLayers(opts: {
+export function makeDeviceFrameLayer(opts: {
 	deviceId: string;
-	screenshotUrl: string;
-	screenshotWidth: number;
-	screenshotHeight: number;
+	screenshotUrl?: string;
+	screenshotWidth?: number;
+	screenshotHeight?: number;
 	canvasWidth?: number;
 	canvasHeight?: number;
 	centerX?: number;
 	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;
-}): { screenshot: LayerJSON; frame: LayerJSON } {
+}): LayerJSON {
 	const device = getDeviceFrame(opts.deviceId);
 	if (!device) throw new Error(`Unknown device: ${opts.deviceId}`);
 
@@ -56,8 +57,83 @@ export function makeDeviceFrameLayers(opts: {
 	const scale = opts.scale ?? calculateDeviceScale(device, canvasWidth, canvasHeight);
 
 	const frameId = `device-frame-${generateLayerId()}`;
-	const screenshotId = generateLayerId();
 
+	const fabricData: Record<string, unknown> = {
+		type: 'image',
+		src: device.frameAsset,
+		crossOrigin: 'anonymous',
+		left: opts.centerX ?? canvasWidth / 2,
+		top: opts.centerY ?? canvasHeight / 2,
+		width: device.imageDimensions.width,
+		height: device.imageDimensions.height,
+		scaleX: scale,
+		scaleY: scale,
+		originX: 'center',
+		originY: 'center',
+		layerId: frameId,
+		layerType: 'deviceFrame',
+		deviceFrameId: frameId,
+		layerRole: 'frame',
+		deviceId: opts.deviceId,
+		deviceScale: scale
+	};
+	if (opts.angle) fabricData.angle = opts.angle;
+
+	if (opts.screenshotUrl) {
+		const { screenshotWidth: width, screenshotHeight: height } = opts;
+		if (!(typeof width === 'number' && width > 0 && typeof height === 'number' && height > 0)) {
+			throw new Error('makeDeviceFrameLayer: screenshotWidth/screenshotHeight (> 0) are required with screenshotUrl');
+		}
+		const screenshot: DeviceScreenshotJSON = { src: opts.screenshotUrl, width, height };
+		if (opts.screenshotRotation) screenshot.rotation = opts.screenshotRotation;
+		fabricData.screenshot = screenshot;
+	}
+
+	return {
+		id: frameId,
+		name: opts.name ?? device.name,
+		type: 'device',
+		visible: true,
+		locked: false,
+		fabricData
+	};
+}
+
+/** Where a frame currently sits on the canvas (a Fabric object's relevant props). */
+export interface DeviceFramePose {
+	left?: number;
+	top?: number;
+	scaleX?: number;
+	scaleY?: number;
+	angle?: number;
+	/** The frame's base scale when it was created (`fabricData.deviceScale`). */
+	deviceScale?: number;
+}
+
+/** Fabric props for a screenshot placed inside a frame; `clip` is a centered Rect in the image's local space. */
+export interface ScreenshotPlacement {
+	left: number;
+	top: number;
+	scaleX: number;
+	scaleY: number;
+	angle: number;
+	clip: { width: number; height: number; rx: number; ry: number };
+}
+
+/**
+ * THE screenshot-in-frame geometry: fit a screenshot of natural size `natural` to the
+ * device's screen bounds for a frame at `frame`, optionally rotated by `rotation`
+ * (0/90/180/270 — 90/270 swap the effective dimensions), with a rounded clip matching
+ * `device.cornerRadius`. Used by the editor (FabricCanvas.updateDeviceFrameScreenshot)
+ * and the offscreen thumbnail/export renderers so all three place screenshots identically.
+ */
+export function computeScreenshotPlacement(
+	device: DeviceFrame,
+	frame: DeviceFramePose,
+	natural: { width: number; height: number },
+	rotation = 0
+): ScreenshotPlacement {
+	const scale = frame.deviceScale || 0.15;
 	const scaledImageWidth = device.imageDimensions.width * scale;
 	const scaledImageHeight = device.imageDimensions.height * scale;
 	const screenWidth = device.screenBounds.width * scale;
@@ -66,84 +142,51 @@ export function makeDeviceFrameLayers(opts: {
 	const screenOffsetY = device.screenBounds.y * scale;
 	const cornerRadius = device.cornerRadius * scale;
 
-	const frameCenterX = opts.centerX ?? canvasWidth / 2;
-	const frameCenterY = opts.centerY ?? canvasHeight / 2;
+	const naturalWidth = natural.width || 1;
+	const naturalHeight = natural.height || 1;
 
-	// Screen center relative to the frame center (same formula as addDeviceFrame).
-	const screenCenterX = frameCenterX - scaledImageWidth / 2 + screenOffsetX + screenWidth / 2;
-	const screenCenterY = frameCenterY - scaledImageHeight / 2 + screenOffsetY + screenHeight / 2;
+	// When rotated 90 or 270, the effective dimensions are swapped.
+	const isRotated90or270 = rotation === 90 || rotation === 270;
+	const effectiveWidth = isRotated90or270 ? naturalHeight : naturalWidth;
+	const effectiveHeight = isRotated90or270 ? naturalWidth : naturalHeight;
 
-	// Scale the screenshot to exactly fill the screen bounds.
-	const imgScaleX = screenWidth / opts.screenshotWidth;
-	const imgScaleY = screenHeight / opts.screenshotHeight;
+	// Scale to fit the screen bounds using the effective dimensions.
+	const imgScaleX = screenWidth / effectiveWidth;
+	const imgScaleY = screenHeight / effectiveHeight;
 
-	const screenshot: LayerJSON = {
-		id: screenshotId,
-		name: opts.name ? `${opts.name} screenshot` : 'Screenshot',
-		type: 'image',
-		visible: true,
-		locked: false,
-		fabricData: {
-			type: 'image',
-			src: opts.screenshotUrl,
-			crossOrigin: 'anonymous',
-			left: screenCenterX,
-			top: screenCenterY,
-			width: opts.screenshotWidth,
-			height: opts.screenshotHeight,
-			scaleX: imgScaleX,
-			scaleY: imgScaleY,
-			originX: 'center',
-			originY: 'center',
-			selectable: false,
-			evented: false,
-			// clipPath is in the image's local (unscaled) coordinate space.
-			clipPath: {
-				type: 'Rect',
-				width: opts.screenshotWidth,
-				height: opts.screenshotHeight,
-				rx: cornerRadius / imgScaleX,
-				ry: cornerRadius / imgScaleY,
-				left: 0,
-				top: 0,
-				originX: 'center',
-				originY: 'center'
-			},
-			layerId: screenshotId,
-			layerType: 'image',
-			deviceFrameId: frameId,
-			layerRole: 'screenshot',
-			deviceId: opts.deviceId,
-			screenshotRotation: opts.screenshotRotation ?? 0
-		}
-	};
+	const frameLeft = frame.left || 0;
+	const frameTop = frame.top || 0;
+	const frameScaleX = frame.scaleX || 1;
+	const frameScaleY = frame.scaleY || 1;
+	const frameAngle = frame.angle || 0;
 
-	const frame: LayerJSON = {
-		id: frameId,
-		name: opts.name ?? device.name,
-		type: 'device',
-		visible: true,
-		locked: false,
-		fabricData: {
-			type: 'image',
-			src: device.frameAsset,
-			crossOrigin: 'anonymous',
-			left: frameCenterX,
-			top: frameCenterY,
-			width: device.imageDimensions.width,
-			height: device.imageDimensions.height,
-			scaleX: scale,
-			scaleY: scale,
-			originX: 'center',
-			originY: 'center',
-			layerId: frameId,
-			layerType: 'deviceFrame',
-			deviceFrameId: frameId,
-			layerRole: 'frame',
-			deviceId: opts.deviceId,
-			deviceScale: scale
+	// Screen center offset from the frame center (at the frame's base scale), rotated with the frame.
+	const offsetX = -(scaledImageWidth / 2) + screenOffsetX + screenWidth / 2;
+	const offsetY = -(scaledImageHeight / 2) + screenOffsetY + screenHeight / 2;
+	const angleRad = (frameAngle * Math.PI) / 180;
+	const rotatedOffsetX = offsetX * Math.cos(angleRad) - offsetY * Math.sin(angleRad);
+	const rotatedOffsetY = offsetX * Math.sin(angleRad) + offsetY * Math.cos(angleRad);
+
+	// The frame's current scale relative to its base deviceScale (1 unless the user resized it).
+	const frameScaleRatioX = frameScaleX / scale;
+	const frameScaleRatioY = frameScaleY / scale;
+
+	return {
+		// The offset is already in base-scale canvas units, so it scales by the RATIO, not the
+		// absolute frame scale (≤0.2 editors multiplied by frameScale, shrinking off-centre screen
+		// offsets ~7× — visible on MacBooks, whose screen sits above the frame centre).
+		left: frameLeft + rotatedOffsetX * frameScaleRatioX,
+		top: frameTop + rotatedOffsetY * frameScaleRatioY,
+		scaleX: imgScaleX * frameScaleRatioX,
+		scaleY: imgScaleY * frameScaleRatioY,
+		// The screenshot's visual angle combines the frame rotation and its own rotation.
+		angle: frameAngle + rotation,
+		// The clipPath lives in the image's local (unscaled) coordinate space.
+		clip: {
+			width: naturalWidth,
+			height: naturalHeight,
+			rx: cornerRadius / imgScaleX,
+			ry: cornerRadius / imgScaleY
 		}
 	};
-
-	return { screenshot, frame };
 }

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

@@ -15,7 +15,42 @@ export type TemplateRole = 'placeholder' | 'editable' | 'fixed';
 /** Current ScreenLayersJSON schema version. */
 export const CURRENT_SCHEMA_VERSION = 2;
 
-/** JSON representation of a single layer for persistence + handoff. */
+/**
+ * Screenshot carried BY a device-frame layer (`type: 'device'`), at `fabricData.screenshot`.
+ *
+ * Since shot-dsl 0.3.0 a device mockup is ONE layer: the frame, with its screenshot as a property —
+ * mirroring the editor, where a frame's screenshot is owned by the frame (it is not a panel layer).
+ * On import the editor places the image under the frame and clips it to the screen area with the
+ * same code path it uses when a user drops a screenshot onto a frame, so producers never compute
+ * screenshot geometry or clip paths themselves.
+ *
+ * Legacy (≤ 0.2.0) templates instead emitted a separate `type: 'image'` layer with
+ * `fabricData.layerRole === 'screenshot'` + a `deviceFrameId` matching its frame, placed directly
+ * below the frame. `validateTemplate` still accepts that shape and the editor converts it on import.
+ */
+export interface DeviceScreenshotJSON {
+	/**
+	 * Image URL. In handoffs this must be the uploaded-asset form `/api/screenshots/<id>/raw`
+	 * (see `isUploadedScreenshotSrc`) — external / `data:` / protocol-relative URLs are rejected.
+	 */
+	src: string;
+	/** Natural pixel size of the screenshot. */
+	width: number;
+	height: number;
+	/** Clockwise rotation inside the frame, in degrees (0 | 90 | 180 | 270). Default 0. */
+	rotation?: number;
+}
+
+/**
+ * JSON representation of a single layer for persistence + handoff.
+ *
+ * Order convention: in a DSL `ScreenLayersJSON.layers` array (templates, handoffs) layers are listed
+ * BOTTOM → TOP — index 0 is painted first (canvas add order), the last entry is frontmost. E.g. a
+ * composed screen is `[device, headline, subheadline]`; the built-in templates list shapes, then the
+ * device, then text. (The editor's layers PANEL is the reverse — top first — and so is the
+ * `layersJSON` the editor persists alongside a full `canvasJSON`; that pairing restores z-order from
+ * `canvasJSON`, never from this array.)
+ */
 export interface LayerJSON {
 	id: string;
 	name: string;
@@ -61,6 +96,7 @@ export interface ScreenLayersJSON {
 	canvasHeight?: number;
 	/** Device group (multi-device); optional/additive — absent ⇒ the editor infers it. */
 	deviceClass?: DeviceClass;
+	/** BOTTOM → TOP (index 0 is painted first). See `LayerJSON`. */
 	layers: LayerJSON[];
 	background?: BackgroundJSON;
 }