@appshoteditor/shot-dsl 0.1.2 → 0.3.0

package/README.md

@@ -10,11 +10,17 @@ composer — so a layout composed by the skill renders identically in the editor
 ## What's inside
 
 - **Types** — `Template`, `ScreenLayersJSON`, `LayerJSON`, `BackgroundJSON`, `CURRENT_SCHEMA_VERSION`.
-- **Validators** — `validateTemplate()` (strict, error-reporting), `isValidTemplate`, `migrateScreenLayersJSON`.
+- **Validators** — `validateTemplate()` (strict, error-reporting), `isValidTemplate`, `migrateScreenLayersJSON`,
+  `validateDeviceScreenshot`, `isUploadedScreenshotSrc`.
 - **Builders** — `makeTextLayer`, `makeImageLayer`, `makeShapeLayer`, `makeSolid/GradientBackground`,
   `makeScreen`, `makeTemplate`.
-- **Device geometry** — `deviceFrames`, `getDeviceFrame`, `makeDeviceFrameLayers`, `calculateDeviceScale`.
+- **Device geometry** — `deviceFrames`, `getDeviceFrame`, `makeDeviceFrameLayer`, `calculateDeviceScale`,
+  `computeScreenshotPlacement` (the screenshot-in-frame fit/clip math the editor uses).
 - **Composer** — `composeTemplate(plan)`: a benefit/screenshot plan → a validated, device-framed `Template`.
+  Per screen: `headline`, optional `subheadline` / `headlineColor` / `subheadlineColor`, and `layout`
+  (`text-top` default, `text-bottom`, `device-bleed` — see `COMPOSE_LAYOUTS`). All geometry (device
+  scale/position, font sizes, padding) is derived from the canvas size, so a plan composes to the
+  same proportions at 280×608 editor units or 1320×2868 native pixels.
 
 ```ts
 import { composeTemplate, validateTemplate } from '@appshoteditor/shot-dsl';
@@ -24,6 +30,8 @@ const template = composeTemplate({
   screens: [
     {
       headline: 'Track every workout',
+      subheadline: 'Sets, reps and rest — logged for you',
+      layout: 'text-top',
       background: { type: 'gradient', gradient: { type: 'linear', colorStops: [/* … */] } },
       deviceId: 'iphone_16_pro',
       screenshot: { url: '…', width: 1179, height: 2556 }
@@ -33,6 +41,69 @@ const template = composeTemplate({
 validateTemplate(template); // { valid: true, errors: [] }
 ```
 
+## Layer order
+
+A screen's `layers` array is **bottom → top**: index 0 is painted first (canvas add order), the last
+entry is frontmost. A composed screen is `[device, headline, subheadline?]`; the editor's built-in
+templates list background shapes, then the device, then text. (The editor's layers *panel* shows the
+reverse — top first.)
+
+## Device screenshots (0.3.0)
+
+A device mockup is **one** layer. Its screenshot is a property of the device layer, at
+`fabricData.screenshot`:
+
+```json
+{
+  "id": "device-frame-layer-1790080000000-abc123def",
+  "name": "iPhone 17 Pro Max",
+  "type": "device",
+  "visible": true,
+  "locked": false,
+  "fabricData": {
+    "type": "image",
+    "src": "/devices/iphone-17-pro-max.webp",
+    "left": 140, "top": 438.69, "width": 1520, "height": 3068,
+    "scaleX": 0.175, "scaleY": 0.175, "originX": "center", "originY": "center",
+    "layerId": "device-frame-layer-1790080000000-abc123def",
+    "layerType": "deviceFrame",
+    "layerRole": "frame",
+    "deviceFrameId": "device-frame-layer-1790080000000-abc123def",
+    "deviceId": "iphone_17_pro_max",
+    "deviceScale": 0.175,
+    "screenshot": { "src": "/api/screenshots/<asset-id>/raw", "width": 1320, "height": 2868 }
+  }
+}
+```
+
+`screenshot` is `{ src, width, height, rotation? }` (`DeviceScreenshotJSON`; `rotation` ∈ 0/90/180/270).
+Producers emit **no** screenshot geometry or clip path: the editor places the image under the frame
+and clips it to the screen with the same code path it uses when a user drops a screenshot onto a
+frame (`computeScreenshotPlacement`), so the screenshot belongs to the frame (it is not a separate
+layer). `validateTemplate` requires `src` to be an uploaded-asset URL (`/api/screenshots/<id>/raw`) —
+external, protocol-relative and `data:` URLs are rejected. It also requires every device layer to have a
+known `deviceId` and a frame-asset `src` (`/devices/<name>.webp|png`), and rejects duplicate layer ids
+or `deviceFrameId`s within a screen. Every other image reference in a handoff (image layers, pattern
+`fill.source`, nested objects) must be an uploaded screenshot or a `/devices/` asset. Frame metadata
+(`layerRole: 'frame'`, `deviceFrameId`, `deviceId`, `deviceScale`) is only allowed on device layers,
+`layerRole: 'screenshot'` only on legacy image layers, and editor-internal props
+(`EDITOR_INTERNAL_PROPS`, e.g. `pendingScreenshot`) are rejected everywhere, as are `__proto__` /
+`constructor` / `prototype` keys at any depth (`FORBIDDEN_KEYS`).
+
+`computeScreenshotPlacement` centres the screenshot on the frame's screen bounds; the screen-centre
+offset scales with the frame's scale *relative to* `deviceScale` (0.2.x editors multiplied by the
+absolute frame scale, misplacing off-centre screens such as MacBooks by a few canvas units).
+
+**Legacy (≤ 0.2.0):** screenshots were a separate `type: 'image'` layer with
+`fabricData.layerRole: 'screenshot'` and a `deviceFrameId` matching its frame, placed directly below
+the frame. `validateTemplate` still accepts that shape (its `src` must also be an uploaded-asset URL)
+and the editor converts it on import.
+`makeDeviceFrameLayers()` (which returned `{ screenshot, frame }`) was replaced by
+`makeDeviceFrameLayer()` (returns the single device layer).
+
+> Consumers: a template in the 0.3.0 shape needs an editor that understands `fabricData.screenshot`
+> (appshoteditor.com with the matching importer).
+
 Zero runtime dependencies. The `schemaVersion` is the compatibility contract between producers and the editor.
 
 > Intended for use via a bundler (Vite, esbuild, etc.). Device `frameAsset` values are URL paths the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appshoteditor/shot-dsl",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "App Shot Editor layout DSL + device-frame geometry — framework-free building blocks for composing editable App Store screenshot layouts. Intended for use via a bundler (Vite, esbuild, etc.).",
   "license": "MIT",
   "type": "module",

package/src/compose.ts

@@ -1,6 +1,6 @@
-import type { BackgroundJSON, Template } from './types';
+import type { BackgroundJSON, LayerJSON, Template } from './types';
 import { makeTextLayer, makeScreen, makeTemplate } from './builders';
-import { makeDeviceFrameLayers } from './frames';
+import { makeDeviceFrameLayer } from './frames';
 import { getDeviceFrame, deviceClassForDeviceId } from './device-frames';
 
 /**
@@ -22,10 +22,27 @@ function canvasDimsForDevice(deviceId: string): { width: number; height: number
 	}
 }
 
+/**
+ * Screen layout variants:
+ * - `text-top` (default): headline (+ subheadline) at the top, device below, bleeding off the bottom.
+ * - `text-bottom`: device at the top bleeding off the TOP edge, text block anchored to the bottom.
+ * - `device-bleed`: text at the top, an oversized device (~95% of the width) bleeding heavily off
+ *   the bottom — the "hero" look.
+ */
+export type ComposeLayout = 'text-top' | 'text-bottom' | 'device-bleed';
+
+export const COMPOSE_LAYOUTS: readonly ComposeLayout[] = ['text-top', 'text-bottom', 'device-bleed'];
+
 /** One screen's worth of plan input (the skill decides these per benefit). */
 export interface ComposeScreenPlan {
 	headline: string;
 	headlineColor?: string;
+	/** Optional short supporting line under the headline (smaller, slightly muted). */
+	subheadline?: string;
+	/** Defaults to `headlineColor` (rendered at reduced opacity). */
+	subheadlineColor?: string;
+	/** Defaults to `text-top`. */
+	layout?: ComposeLayout;
 	background: BackgroundJSON;
 	screenshot: { url: string; width: number; height: number };
 	deviceId: string;
@@ -38,11 +55,103 @@ export interface ComposePlan {
 	canvasHeight?: number;
 }
 
+// ---------------------------------------------------------------------------
+// Layout proportions. EVERYTHING below is a fraction of the canvas — there are no absolute pixel
+// constants, so the same plan composes to a proportionally identical layout at 280×608 (editor
+// units) or 1320×2868 (native iPhone 6.9" pixels).
+// ---------------------------------------------------------------------------
+
 /**
- * Deterministically assemble a Template from a plan. Each screen gets a background,
- * a device-framed screenshot sitting in the lower ~60%, and a headline across the
- * top (marked editable so the user can tweak it in the editor). Claude decides the
- * plan (which benefit, copy, device, palette); this turns it into valid DSL.
+ * Typographic unit. On portrait phone canvases this is the canvas width; on squatter canvases
+ * (tablet, laptop) it's capped by the height so text doesn't swallow a landscape canvas.
+ */
+const TYPE_UNIT_HEIGHT_CAP = 0.55; // unit = min(W, 0.55·H)
+const HEADLINE_SIZE = 0.085; // × unit — for headlines that fit in ≤ 2 lines
+const HEADLINE_SIZE_LONG = 0.072; // × unit — fallback when the headline would wrap to 3+ lines
+const HEADLINE_LINE_HEIGHT = 1.1;
+const SUBHEADLINE_RATIO = 0.55; // subheadline size ÷ headline size
+const SUBHEADLINE_LINE_HEIGHT = 1.25;
+const SUBHEADLINE_OPACITY = 0.85;
+const TEXT_WIDTH = 0.84; // × W → 8% side padding each side
+/** Rough average glyph advance for Inter at heavy weights, as a fraction of the font size. */
+const AVG_CHAR_WIDTH = 0.58;
+
+const EDGE_MARGIN = 0.055; // × H — gap between the text block and the canvas edge
+const TEXT_GAP = 0.3; // × headline font size — headline ↔ subheadline gap
+const DEVICE_GAP = 0.04; // × unit — text block ↔ device gap
+
+interface LayoutSpec {
+	/** Target rendered device width as a fraction of the canvas width. */
+	deviceWidth: number;
+	/** Max fraction of the device's height allowed off-canvas (bounds the scale on squat canvases). */
+	maxBleed: number;
+	/** Device can't start above this fraction of H (text-top variants) — pushes the hero lower. */
+	minDeviceTop: number;
+}
+
+const LAYOUTS: Record<ComposeLayout, LayoutSpec> = {
+	'text-top': { deviceWidth: 0.86, maxBleed: 0.2, minDeviceTop: 0 },
+	'text-bottom': { deviceWidth: 0.9, maxBleed: 0.2, minDeviceTop: 0 },
+	'device-bleed': { deviceWidth: 0.95, maxBleed: 0.4, minDeviceTop: 0.28 }
+};
+
+/** Greedy word-wrap estimate of how many lines `text` takes at `fontSize` in a box `width` wide. */
+function estimateLines(text: string, fontSize: number, width: number): number {
+	const maxChars = Math.max(1, Math.floor(width / (fontSize * AVG_CHAR_WIDTH)));
+	let lines = 0;
+	for (const paragraph of text.split('\n')) {
+		let current = 0;
+		lines++;
+		for (const word of paragraph.split(/\s+/).filter(Boolean)) {
+			const len = word.length;
+			if (current === 0) {
+				current = len;
+			} else if (current + 1 + len <= maxChars) {
+				current += 1 + len;
+			} else {
+				lines++;
+				current = len;
+			}
+			// A single word longer than a line wraps mid-word in Fabric's Textbox.
+			while (current > maxChars) {
+				lines++;
+				current -= maxChars;
+			}
+		}
+	}
+	return Math.max(1, lines);
+}
+
+interface TextBlock {
+	headlineSize: number;
+	headlineHeight: number;
+	subSize: number;
+	subHeight: number;
+	gap: number;
+	height: number;
+}
+
+function measureTextBlock(screen: ComposeScreenPlan, unit: number, textWidth: number): TextBlock {
+	let headlineSize = unit * HEADLINE_SIZE;
+	if (estimateLines(screen.headline, headlineSize, textWidth) > 2) headlineSize = unit * HEADLINE_SIZE_LONG;
+	const headlineHeight =
+		estimateLines(screen.headline, headlineSize, textWidth) * headlineSize * HEADLINE_LINE_HEIGHT;
+
+	const hasSub = !!screen.subheadline?.trim();
+	const subSize = headlineSize * SUBHEADLINE_RATIO;
+	const subHeight = hasSub
+		? estimateLines(screen.subheadline!, subSize, textWidth) * subSize * SUBHEADLINE_LINE_HEIGHT
+		: 0;
+	const gap = hasSub ? headlineSize * TEXT_GAP : 0;
+	return { headlineSize, headlineHeight, subSize, subHeight, gap, height: headlineHeight + gap + subHeight };
+}
+
+/**
+ * Deterministically assemble a Template from a plan. Each screen gets a background, a large
+ * device frame carrying its screenshot and a bold headline (+ optional subheadline), arranged per the screen's
+ * `layout`. All geometry is derived from the canvas size. Text layers are marked editable so the
+ * user can tweak them in the editor. Claude decides the plan (benefit, copy, device, palette,
+ * layout); this turns it into valid DSL.
  */
 export function composeTemplate(plan: ComposePlan): Template {
 	const screens = plan.screens.map((screen) => {
@@ -50,45 +159,101 @@ export function composeTemplate(plan: ComposePlan): Template {
 		// old single-size behavior), else derive from the screen's device class so a mixed-device
 		// plan gets the correct aspect per screen.
 		const explicit = plan.canvasWidth != null || plan.canvasHeight != null;
-		const { width: canvasWidth, height: canvasHeight } = explicit
+		const { width: W, height: H } = explicit
 			? { width: plan.canvasWidth ?? 280, height: plan.canvasHeight ?? 600 }
 			: canvasDimsForDevice(screen.deviceId);
 
-		const { screenshot, frame } = makeDeviceFrameLayers({
+		const layout: ComposeLayout = screen.layout ?? 'text-top';
+		const spec = LAYOUTS[layout] ?? LAYOUTS['text-top'];
+		const unit = Math.min(W, H * TYPE_UNIT_HEIGHT_CAP);
+		const textWidth = W * TEXT_WIDTH;
+		const margin = H * EDGE_MARGIN;
+		const deviceGap = unit * DEVICE_GAP;
+		const block = measureTextBlock(screen, unit, textWidth);
+
+		// Text block vertical extent.
+		const blockTop = layout === 'text-bottom' ? H - margin - block.height : margin;
+
+		// Device size: target a fraction of the canvas width, but never let more than `maxBleed` of
+		// the device fall off-canvas (keeps squat tablet/laptop canvases sane).
+		const device = getDeviceFrame(screen.deviceId);
+		if (!device) throw new Error(`Unknown device: ${screen.deviceId}`);
+		const { width: fw, height: fh } = device.imageDimensions;
+		let scale: number;
+		let centerY: number;
+		if (layout === 'text-bottom') {
+			const deviceBottom = blockTop - deviceGap;
+			scale = Math.min((W * spec.deviceWidth) / fw, deviceBottom / (1 - spec.maxBleed) / fh);
+			centerY = deviceBottom - (fh * scale) / 2; // top edge bleeds off the top when tall
+		} else {
+			const deviceTop = Math.max(margin + block.height + deviceGap, H * spec.minDeviceTop);
+			scale = Math.min((W * spec.deviceWidth) / fw, (H - deviceTop) / (1 - spec.maxBleed) / fh);
+			centerY = deviceTop + (fh * scale) / 2; // bottom edge bleeds off the bottom when tall
+		}
+
+		// One device layer; the screenshot rides on it as `fabricData.screenshot` and the editor
+		// places + clips it under the frame on import (see DeviceScreenshotJSON).
+		const frame = makeDeviceFrameLayer({
 			deviceId: screen.deviceId,
 			screenshotUrl: screen.screenshot.url,
 			screenshotWidth: screen.screenshot.width,
 			screenshotHeight: screen.screenshot.height,
-			canvasWidth,
-			canvasHeight,
-			centerY: canvasHeight * 0.6 // sit the device lower, leaving room for the headline
+			canvasWidth: W,
+			canvasHeight: H,
+			centerX: W / 2,
+			centerY,
+			scale
 		});
 
-		// Center origin (editor convention): left/top are the box CENTER. Center the
-		// headline horizontally and sit it near the top, leaving room for the device.
+		// Center origin (editor convention): left/top are the box CENTER.
+		const headlineColor = screen.headlineColor ?? '#ffffff';
 		const headline = makeTextLayer({
 			text: screen.headline,
-			left: canvasWidth / 2,
-			top: canvasHeight * 0.12,
-			width: canvasWidth * 0.84,
-			fontSize: 26,
+			left: W / 2,
+			top: blockTop + block.headlineHeight / 2,
+			width: textWidth,
+			fontSize: block.headlineSize,
 			fontWeight: '800',
-			fill: screen.headlineColor ?? '#ffffff',
+			lineHeight: HEADLINE_LINE_HEIGHT,
+			fill: headlineColor,
 			textAlign: 'center',
 			name: 'Headline',
 			templateRole: 'editable',
 			templateKey: 'headline'
 		});
 
-		// z-order: screenshot (bottom) -> frame -> headline (top)
+		// BOTTOM → TOP (canvas add order): device -> headline -> subheadline.
+		const layers: LayerJSON[] = [frame, headline];
+
+		if (screen.subheadline?.trim()) {
+			const sub = makeTextLayer({
+				text: screen.subheadline,
+				left: W / 2,
+				top: blockTop + block.headlineHeight + block.gap + block.subHeight / 2,
+				width: textWidth,
+				fontSize: block.subSize,
+				fontWeight: '500',
+				lineHeight: SUBHEADLINE_LINE_HEIGHT,
+				fill: screen.subheadlineColor ?? headlineColor,
+				textAlign: 'center',
+				name: 'Subheadline',
+				templateRole: 'editable',
+				templateKey: 'subheadline'
+			});
+			// When it inherits the headline color, mute it slightly (standard Fabric `opacity`, editable
+			// in the editor). An explicit subheadlineColor is used as-is.
+			if (!screen.subheadlineColor) (sub.fabricData as Record<string, unknown>).opacity = SUBHEADLINE_OPACITY;
+			layers.push(sub);
+		}
+
 		return makeScreen({
 			background: screen.background,
-			canvasWidth,
-			canvasHeight,
+			canvasWidth: W,
+			canvasHeight: H,
 			// Tag the device GROUP (multi-device) so a mixed plan lands as separate sidebar groups in
 			// the editor instead of relying on frame inference. Absent ⇒ editor infers it.
 			deviceClass: deviceClassForDeviceId(screen.deviceId) ?? undefined,
-			layers: [screenshot, frame, headline]
+			layers
 		});
 	});
 

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,22 +24,21 @@ 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;
@@ -47,7 +46,7 @@ export function makeDeviceFrameLayers(opts: {
 	scale?: number;
 	screenshotRotation?: number;
 	name?: string;
-}): { screenshot: LayerJSON; frame: LayerJSON } {
+}): LayerJSON {
 	const device = getDeviceFrame(opts.deviceId);
 	if (!device) throw new Error(`Unknown device: ${opts.deviceId}`);
 
@@ -56,8 +55,82 @@ 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.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 +139,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/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;
 }

package/src/validate.ts

@@ -1,5 +1,6 @@
 import type { LayerJSON, ScreenLayersJSON, Template } from './types';
 import { CURRENT_SCHEMA_VERSION } from './types';
+import { getDeviceFrame } from './device-frames';
 
 const LAYER_TYPES = ['background', 'text', 'image', 'device', 'shape'];
 
@@ -83,6 +84,194 @@ export function generateLayerId(): string {
 	return `layer-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
 }
 
+/**
+ * The only screenshot URL form a device layer's `fabricData.screenshot.src` may carry: a
+ * same-origin, root-relative reference to the user's uploaded asset (`/api/screenshots/<id>/raw`,
+ * which the Worker serves owner-only from private R2). Rejects external, protocol-relative,
+ * `data:`/`javascript:` and path-traversal URLs, so a handoff can't make the editor fetch
+ * arbitrary third-party images.
+ */
+export const UPLOADED_SCREENSHOT_SRC = /^\/api\/screenshots\/[A-Za-z0-9_-]{1,128}\/raw$/;
+
+export function isUploadedScreenshotSrc(src: unknown): src is string {
+	return typeof src === 'string' && UPLOADED_SCREENSHOT_SRC.test(src);
+}
+
+/**
+ * A device layer's own `fabricData.src` — the frame PNG/WebP the editor serves from `static/devices/`
+ * (see `DeviceFrame.frameAsset`; the built-in templates still reference legacy `.png` names).
+ * Single path segment, no dots besides the extension, so no traversal.
+ */
+export const DEVICE_FRAME_SRC = /^\/devices\/[a-z0-9][a-z0-9-]*\.(?:webp|png)$/;
+
+export function isDeviceFrameSrc(src: unknown): src is string {
+	return typeof src === 'string' && DEVICE_FRAME_SRC.test(src);
+}
+
+const SCREENSHOT_ROTATIONS = [0, 90, 180, 270];
+const SCREENSHOT_KEYS = new Set(['src', 'width', 'height', 'rotation']);
+
+/** Problems with a device layer's `fabricData.screenshot` (see `DeviceScreenshotJSON`); empty ⇒ valid. */
+export function validateDeviceScreenshot(value: unknown, at = 'screenshot'): string[] {
+	if (!value || typeof value !== 'object' || Array.isArray(value)) return [`${at} must be an object`];
+	const errors: string[] = [];
+	const shot = value as Record<string, unknown>;
+	for (const key of Object.keys(shot)) {
+		if (!SCREENSHOT_KEYS.has(key)) errors.push(`${at}.${key} is not allowed`);
+	}
+	if (!isUploadedScreenshotSrc(shot.src)) {
+		errors.push(`${at}.src must be an uploaded screenshot URL (/api/screenshots/<id>/raw)`);
+	}
+	for (const dim of ['width', 'height'] as const) {
+		const n = shot[dim];
+		if (typeof n !== 'number' || !Number.isFinite(n) || n <= 0) {
+			errors.push(`${at}.${dim} must be a positive number`);
+		}
+	}
+	if (shot.rotation !== undefined && !SCREENSHOT_ROTATIONS.includes(shot.rotation as number)) {
+		errors.push(`${at}.rotation must be one of 0, 90, 180, 270`);
+	}
+	return errors;
+}
+
+/**
+ * Editor-internal Fabric properties that drive loading/placement at runtime. Never legitimate in a
+ * handoff: e.g. `pendingScreenshot` makes the editor (re)load an image URL as a frame's screenshot,
+ * which would bypass the `screenshot.src` rules below.
+ */
+export const EDITOR_INTERNAL_PROPS = [
+	'pendingScreenshot',
+	'_lastFrameScaleX',
+	'_lastFrameScaleY',
+	'_userScale',
+	'_userOffsetX',
+	'_userOffsetY'
+] as const;
+
+/**
+ * Keys that JSON.parse keeps as OWN properties but that change meaning once copied/enlivened
+ * (`__proto__` smuggles properties past `in`/dot checks; `constructor` breaks Fabric's enliven).
+ */
+export const FORBIDDEN_KEYS = ['__proto__', 'constructor', 'prototype'] as const;
+
+/** Problems for every forbidden key anywhere inside `value` (own keys only, depth-capped). */
+export function findForbiddenKeys(value: unknown, at: string, depth = 0): string[] {
+	if (depth > 32 || !value || typeof value !== 'object') return [];
+	const errors: string[] = [];
+	const entries = Array.isArray(value)
+		? value.map((v, k) => [`[${k}]`, v] as const)
+		: Object.keys(value).map((k) => [`.${k}`, (value as Record<string, unknown>)[k]] as const);
+	for (const [suffix, v] of entries) {
+		const key = suffix.startsWith('.') ? suffix.slice(1) : null;
+		if (key !== null && (FORBIDDEN_KEYS as readonly string[]).includes(key)) {
+			errors.push(`${at}${suffix} is not allowed`);
+			continue;
+		}
+		errors.push(...findForbiddenKeys(v, `${at}${suffix}`, depth + 1));
+	}
+	return errors;
+}
+
+/** Any `src` / `source` (image layers, pattern fills, group children, clip paths…) must be one of these. */
+function isAllowedImageRef(value: unknown): boolean {
+	return isUploadedScreenshotSrc(value) || isDeviceFrameSrc(value);
+}
+
+/** Collect problems with every `src`/`source` value anywhere inside `value`. */
+function checkImageRefs(value: unknown, at: string, errors: string[], depth = 0): void {
+	if (depth > 32) {
+		errors.push(`${at} is nested too deeply`);
+		return;
+	}
+	if (Array.isArray(value)) {
+		value.forEach((v, k) => checkImageRefs(v, `${at}[${k}]`, errors, depth + 1));
+		return;
+	}
+	if (!value || typeof value !== 'object') return;
+	for (const [key, v] of Object.entries(value as Record<string, unknown>)) {
+		if ((key === 'src' || key === 'source') && !isAllowedImageRef(v)) {
+			errors.push(
+				`${at}.${key} must be an uploaded screenshot (/api/screenshots/<id>/raw) or a device frame asset (/devices/<name>.webp|png)`
+			);
+		} else if (v && typeof v === 'object') {
+			checkImageRefs(v, `${at}.${key}`, errors, depth + 1);
+		}
+	}
+}
+
+/** Per-layer fabricData rules for handoffs (see validateTemplate). */
+function validateLayerFabricData(
+	layer: LayerJSON,
+	fd: Record<string, unknown>,
+	at: string,
+	frameIds: Set<string>
+): string[] {
+	const errors: string[] = [];
+	const fdAt = `${at}.fabricData`;
+
+	for (const prop of EDITOR_INTERNAL_PROPS) {
+		if (prop in fd) errors.push(`${fdAt}.${prop} is editor-internal and not allowed`);
+	}
+
+	// Frame role/metadata only on device layers; screenshot role only on a legacy image layer.
+	const isLegacyScreenshot = fd.layerRole === 'screenshot';
+	if (layer.type === 'device') {
+		if (fd.layerRole !== undefined && fd.layerRole !== 'frame') {
+			errors.push(`${fdAt}.layerRole must be "frame" on a device layer`);
+		}
+		if (typeof fd.deviceId !== 'string' || !getDeviceFrame(fd.deviceId)) {
+			errors.push(`${fdAt}.deviceId must be a known device id`);
+		}
+		if (!isDeviceFrameSrc(fd.src)) {
+			errors.push(`${fdAt}.src must be a device frame asset (/devices/<name>.webp|png)`);
+		}
+		if (typeof fd.deviceFrameId === 'string' && fd.deviceFrameId) {
+			if (frameIds.has(fd.deviceFrameId)) {
+				errors.push(`${fdAt}.deviceFrameId "${fd.deviceFrameId}" is duplicated in this screen`);
+			}
+			frameIds.add(fd.deviceFrameId);
+		}
+	} else if (isLegacyScreenshot) {
+		// Legacy (≤0.2.0) separate screenshot layer: still accepted, but only in its real shape and
+		// held to the same uploaded-asset src rule as the 0.3.0 property.
+		if (layer.type !== 'image' || typeof fd.type !== 'string' || fd.type.toLowerCase() !== 'image') {
+			errors.push(`${fdAt}.layerRole "screenshot" is only allowed on image layers`);
+		}
+		if (!isUploadedScreenshotSrc(fd.src)) {
+			errors.push(`${fdAt}.src must be an uploaded screenshot URL (/api/screenshots/<id>/raw)`);
+		}
+		if (fd.deviceId !== undefined && (typeof fd.deviceId !== 'string' || !getDeviceFrame(fd.deviceId))) {
+			errors.push(`${fdAt}.deviceId must be a known device id`);
+		}
+	} else {
+		if (fd.layerRole !== undefined) errors.push(`${fdAt}.layerRole is only allowed on device / legacy screenshot layers`);
+		for (const key of ['deviceFrameId', 'deviceId', 'deviceScale']) {
+			if (fd[key] !== undefined) errors.push(`${fdAt}.${key} is only allowed on device / legacy screenshot layers`);
+		}
+		if (fd.layerType === 'deviceFrame') errors.push(`${fdAt}.layerType "deviceFrame" is only allowed on device layers`);
+	}
+
+	// Device-owned screenshot (0.3.0+).
+	if (fd.screenshot !== undefined) {
+		if (layer.type !== 'device') errors.push(`${fdAt}.screenshot is only allowed on device layers`);
+		errors.push(...validateDeviceScreenshot(fd.screenshot, `${fdAt}.screenshot`));
+	}
+
+	// Every other image reference (image layers, pattern fills, nested objects): same-origin
+	// uploaded screenshots or device frame assets only. (Top-level device/screenshot srcs were
+	// checked above with their stricter rule; skip them here to avoid duplicate messages.)
+	const { src: _src, screenshot: _screenshot, ...rest } = fd;
+	void _screenshot;
+	if (layer.type !== 'device' && !isLegacyScreenshot && _src !== undefined && !isAllowedImageRef(_src)) {
+		errors.push(
+			`${fdAt}.src must be an uploaded screenshot (/api/screenshots/<id>/raw) or a device frame asset (/devices/<name>.webp|png)`
+		);
+	}
+	checkImageRefs(rest, fdAt, errors);
+
+	return errors;
+}
+
 export interface ValidationResult {
 	valid: boolean;
 	errors: string[];
@@ -115,8 +304,18 @@ export function validateTemplate(data: unknown): ValidationResult {
 			if (s.schemaVersion > CURRENT_SCHEMA_VERSION) {
 				errors.push(`screens[${i}] has unsupported schemaVersion ${s.schemaVersion}`);
 			}
+			const layerIds = new Set<string>();
+			const frameIds = new Set<string>();
 			s.layers.forEach((layer, j) => {
-				if (!isValidLayerJSON(layer)) errors.push(`screens[${i}].layers[${j}] is invalid`);
+				const at = `screens[${i}].layers[${j}]`;
+				if (!isValidLayerJSON(layer)) errors.push(`${at} is invalid`);
+				errors.push(...findForbiddenKeys(layer, at));
+				if (layerIds.has(layer.id)) errors.push(`${at}.id "${layer.id}" is duplicated in this screen`);
+				layerIds.add(layer.id);
+
+				const fd = layer.fabricData as Record<string, unknown> | null;
+				if (!fd || typeof fd !== 'object') return;
+				errors.push(...validateLayerFabricData(layer, fd, at, frameIds));
 			});
 		});
 	}