@appshoteditor/shot-dsl 0.1.0

package/README.md

@@ -0,0 +1,39 @@
+# @appshoteditor/shot-dsl
+
+The layout DSL behind [appshoteditor.com](https://appshoteditor.com) — framework-free building blocks
+for composing **editable App Store / Play Store screenshot layouts**, plus device-frame geometry.
+
+It is the single source of truth shared by the web editor, the Cloudflare Worker (handoff validation),
+and the [App Store Screenshots agent skill](https://github.com/AppShotEditor/app-store-screenshots-skill)'s
+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`.
+- **Builders** — `makeTextLayer`, `makeImageLayer`, `makeShapeLayer`, `makeSolid/GradientBackground`,
+  `makeScreen`, `makeTemplate`.
+- **Device geometry** — `deviceFrames`, `getDeviceFrame`, `makeDeviceFrameLayers`, `calculateDeviceScale`.
+- **Composer** — `composeTemplate(plan)`: a benefit/screenshot plan → a validated, device-framed `Template`.
+
+```ts
+import { composeTemplate, validateTemplate } from '@appshoteditor/shot-dsl';
+
+const template = composeTemplate({
+  name: 'My App',
+  screens: [
+    {
+      headline: 'Track every workout',
+      background: { type: 'gradient', gradient: { type: 'linear', colorStops: [/* … */] } },
+      deviceId: 'iphone_16_pro',
+      screenshot: { url: '…', width: 1179, height: 2556 }
+    }
+  ]
+});
+validateTemplate(template); // { valid: true, errors: [] }
+```
+
+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
+> editor serves; this package ships only the geometry, not the frame images.

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@appshoteditor/shot-dsl",
+  "version": "0.1.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",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src/index.ts",
+    "src/types.ts",
+    "src/validate.ts",
+    "src/builders.ts",
+    "src/compose.ts",
+    "src/frames.ts",
+    "src/device-frames.ts"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "app-store-screenshots",
+    "appshoteditor",
+    "agent-skill",
+    "device-frames",
+    "layout-dsl"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AppShotEditor/app-shot-editor.git",
+    "directory": "packages/shot-dsl"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/builders.ts

@@ -0,0 +1,210 @@
+import type { BackgroundJSON, ColorStop, LayerJSON, ScreenLayersJSON, Template, TemplateRole } from './types';
+import { CURRENT_SCHEMA_VERSION } from './types';
+import { generateLayerId } from './validate';
+
+/** Common per-layer metadata accepted by every builder. */
+interface LayerMeta {
+	id?: string;
+	name?: string;
+	visible?: boolean;
+	locked?: boolean;
+	templateRole?: TemplateRole;
+	templateKey?: string;
+}
+
+const DEFAULT_CANVAS_WIDTH = 280;
+const DEFAULT_CANVAS_HEIGHT = 600;
+
+// ---- Backgrounds ----
+
+export function makeSolidBackground(color: string): BackgroundJSON {
+	return { type: 'solid', color };
+}
+
+export function makeGradientBackground(opts: {
+	colorStops: ColorStop[];
+	type?: 'linear' | 'radial';
+	coords?: { x1: number; y1: number; x2: number; y2: number };
+}): BackgroundJSON {
+	return {
+		type: 'gradient',
+		gradient: { type: opts.type ?? 'linear', colorStops: opts.colorStops, coords: opts.coords }
+	};
+}
+
+// ---- Layers ----
+
+export function makeTextLayer(
+	opts: {
+		text: string;
+		left: number;
+		top: number;
+		width: number;
+		fontSize?: number;
+		fontFamily?: string;
+		fontWeight?: string;
+		fill?: string;
+		textAlign?: 'left' | 'center' | 'right';
+		lineHeight?: number;
+		originX?: 'left' | 'center' | 'right';
+		originY?: 'top' | 'center' | 'bottom';
+	} & LayerMeta
+): LayerJSON {
+	const id = opts.id ?? generateLayerId();
+	return {
+		id,
+		name: opts.name ?? 'Text',
+		type: 'text',
+		visible: opts.visible ?? true,
+		locked: opts.locked ?? false,
+		templateRole: opts.templateRole,
+		templateKey: opts.templateKey,
+		fabricData: {
+			type: 'Textbox',
+			left: opts.left,
+			top: opts.top,
+			width: opts.width,
+			text: opts.text,
+			fill: opts.fill ?? '#ffffff',
+			fontSize: opts.fontSize ?? 28,
+			fontFamily: opts.fontFamily ?? 'Inter',
+			fontWeight: opts.fontWeight ?? '700',
+			textAlign: opts.textAlign ?? 'center',
+			lineHeight: opts.lineHeight ?? 1.1,
+			// Match the editor convention (addText, makeImageLayer, makeShapeLayer all
+			// use center origin) so `left`/`top` are the box center, not its corner.
+			originX: opts.originX ?? 'center',
+			originY: opts.originY ?? 'center',
+			layerId: id,
+			layerType: 'text'
+		}
+	};
+}
+
+export function makeImageLayer(
+	opts: {
+		src: string;
+		left: number;
+		top: number;
+		width: number;
+		height: number;
+		scaleX?: number;
+		scaleY?: number;
+		originX?: 'left' | 'center' | 'right';
+		originY?: 'top' | 'center' | 'bottom';
+		imageCornerRadius?: number;
+	} & LayerMeta
+): LayerJSON {
+	const id = opts.id ?? generateLayerId();
+	return {
+		id,
+		name: opts.name ?? 'Image',
+		type: 'image',
+		visible: opts.visible ?? true,
+		locked: opts.locked ?? false,
+		templateRole: opts.templateRole,
+		templateKey: opts.templateKey,
+		fabricData: {
+			type: 'image',
+			left: opts.left,
+			top: opts.top,
+			width: opts.width,
+			height: opts.height,
+			scaleX: opts.scaleX ?? 1,
+			scaleY: opts.scaleY ?? 1,
+			src: opts.src,
+			originX: opts.originX ?? 'center',
+			originY: opts.originY ?? 'center',
+			...(opts.imageCornerRadius ? { imageCornerRadius: opts.imageCornerRadius } : {}),
+			layerId: id,
+			layerType: 'image'
+		}
+	};
+}
+
+export function makeShapeLayer(
+	opts: {
+		shape: 'rectangle' | 'circle';
+		left: number;
+		top: number;
+		width?: number;
+		height?: number;
+		radius?: number;
+		fill?: string;
+		rx?: number;
+		ry?: number;
+	} & LayerMeta
+): LayerJSON {
+	const id = opts.id ?? generateLayerId();
+	const common = {
+		left: opts.left,
+		top: opts.top,
+		fill: opts.fill ?? '#0ea5e9',
+		originX: 'center',
+		originY: 'center',
+		layerId: id,
+		layerType: 'shape'
+	};
+	const fabricData =
+		opts.shape === 'circle'
+			? { type: 'circle', radius: opts.radius ?? 50, ...common, shapeType: 'circle' }
+			: {
+					type: 'Rect',
+					width: opts.width ?? 100,
+					height: opts.height ?? 100,
+					rx: opts.rx ?? 0,
+					ry: opts.ry ?? 0,
+					...common,
+					shapeType: 'rectangle'
+				};
+	return {
+		id,
+		name: opts.name ?? 'Shape',
+		type: 'shape',
+		visible: opts.visible ?? true,
+		locked: opts.locked ?? false,
+		templateRole: opts.templateRole,
+		templateKey: opts.templateKey,
+		fabricData
+	};
+}
+
+// ---- Assembly ----
+
+export function makeScreen(opts: {
+	layers: LayerJSON[];
+	background?: BackgroundJSON;
+	canvasWidth?: number;
+	canvasHeight?: number;
+}): ScreenLayersJSON {
+	return {
+		schemaVersion: CURRENT_SCHEMA_VERSION,
+		canvasWidth: opts.canvasWidth ?? DEFAULT_CANVAS_WIDTH,
+		canvasHeight: opts.canvasHeight ?? DEFAULT_CANVAS_HEIGHT,
+		layers: opts.layers,
+		background: opts.background
+	};
+}
+
+export function makeTemplate(opts: {
+	id?: string;
+	name: string;
+	screens: ScreenLayersJSON[];
+	description?: string;
+	thumbnail?: string;
+	tags?: string[];
+	version?: string;
+	author?: string;
+}): Template {
+	return {
+		id: opts.id ?? generateLayerId(),
+		name: opts.name,
+		description: opts.description,
+		thumbnail: opts.thumbnail ?? '',
+		tags: opts.tags ?? [],
+		version: opts.version ?? '1.0.0',
+		screens: opts.screens,
+		createdAt: new Date().toISOString(),
+		author: opts.author
+	};
+}

package/src/compose.ts

@@ -0,0 +1,68 @@
+import type { BackgroundJSON, Template } from './types';
+import { makeTextLayer, makeScreen, makeTemplate } from './builders';
+import { makeDeviceFrameLayers } from './frames';
+
+/** One screen's worth of plan input (the skill decides these per benefit). */
+export interface ComposeScreenPlan {
+	headline: string;
+	headlineColor?: string;
+	background: BackgroundJSON;
+	screenshot: { url: string; width: number; height: number };
+	deviceId: string;
+}
+
+export interface ComposePlan {
+	name: string;
+	screens: ComposeScreenPlan[];
+	canvasWidth?: number;
+	canvasHeight?: number;
+}
+
+/**
+ * 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.
+ */
+export function composeTemplate(plan: ComposePlan): Template {
+	const canvasWidth = plan.canvasWidth ?? 280;
+	const canvasHeight = plan.canvasHeight ?? 600;
+
+	const screens = plan.screens.map((screen) => {
+		const { screenshot, frame } = makeDeviceFrameLayers({
+			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
+		});
+
+		// 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.
+		const headline = makeTextLayer({
+			text: screen.headline,
+			left: canvasWidth / 2,
+			top: canvasHeight * 0.12,
+			width: canvasWidth * 0.84,
+			fontSize: 26,
+			fontWeight: '800',
+			fill: screen.headlineColor ?? '#ffffff',
+			textAlign: 'center',
+			name: 'Headline',
+			templateRole: 'editable',
+			templateKey: 'headline'
+		});
+
+		// z-order: screenshot (bottom) -> frame -> headline (top)
+		return makeScreen({
+			background: screen.background,
+			canvasWidth,
+			canvasHeight,
+			layers: [screenshot, frame, headline]
+		});
+	});
+
+	return makeTemplate({ name: plan.name, screens, tags: ['generated'] });
+}

package/src/device-frames.ts

@@ -0,0 +1,318 @@
+// =============================================================================
+// DEVICE FRAME DEFINITIONS
+// =============================================================================
+//
+// HOW TO ADD/EDIT A DEVICE:
+//
+// 1. Open the device PNG in Affinity Designer (or similar)
+// 2. Get the document size → imageDimensions: { width, height }
+// 3. Draw a rectangle over the transparent screen area
+// 4. From Transform panel, copy X, Y, W, H → screenBounds: { x, y, width, height }
+// 5. Add entry below
+//
+// =============================================================================
+
+export interface DeviceFrame {
+	id: string;
+	name: string;
+	platform: 'ios' | 'android' | 'macos' | 'windows';
+	category: 'phone' | 'tablet' | 'desktop' | 'laptop';
+	frameAsset: string; // Path to PNG with transparent screen
+	imageDimensions: { width: number; height: number }; // Size of the PNG
+	screenBounds: { x: number; y: number; width: number; height: number }; // Screen area within PNG
+	cornerRadius: number; // Corner radius of the screen in pixels (unscaled)
+}
+
+// =============================================================================
+// DEVICE LIST - Edit this array to add/modify devices
+// =============================================================================
+
+export const deviceFrames: DeviceFrame[] = [
+	// -------------------------------------------------------------------------
+	// iOS PHONES
+	// -------------------------------------------------------------------------
+	{
+		id: 'iphone_16_pro',
+		name: 'iPhone 16 Pro',
+		platform: 'ios',
+		category: 'phone',
+		frameAsset: '/devices/iphone-16-pro.png',
+		imageDimensions: { width: 1406, height: 2822 },
+		// Screen centered within frame: (1406-1212)/2=97, (2822-2618)/2=102
+		screenBounds: { x: 97, y: 100, width: 1212, height: 2624 },
+		cornerRadius: 120 // Adjust to match device screen corners
+	},
+	{
+		id: 'iphone_16_pro_max',
+		name: 'iPhone 16 Pro Max',
+		platform: 'ios',
+		category: 'phone',
+		frameAsset: '/devices/iphone-16-pro-max.png',
+		imageDimensions: { width: 1520, height: 3068 },
+		// Screen centered within frame: (1520-1310)/2=105, (3068-2846)/2=111
+		screenBounds: { x: 100, y: 100, width: 1320, height: 2870 },
+		cornerRadius: 140 // Slightly larger than 16 Pro
+	},
+	{
+		id: 'iphone_16',
+		name: 'iPhone 16',
+		platform: 'ios',
+		category: 'phone',
+		frameAsset: '/devices/iphone-16.png',
+		imageDimensions: { width: 1379, height: 2756 },
+		screenBounds: { x: 95, y: 98, width: 1189, height: 2563 },
+		cornerRadius: 118
+	},
+	{
+		id: 'iphone_16_plus',
+		name: 'iPhone 16 Plus',
+		platform: 'ios',
+		category: 'phone',
+		frameAsset: '/devices/iphone-16-plus.png',
+		imageDimensions: { width: 1490, height: 2996 },
+		screenBounds: { x: 103, y: 106, width: 1284, height: 2786 },
+		cornerRadius: 128
+	},
+	{
+		id: 'iphone_17_pro',
+		name: 'iPhone 17 Pro',
+		platform: 'ios',
+		category: 'phone',
+		frameAsset: '/devices/iphone-17-pro.png',
+		imageDimensions: { width: 1406, height: 2822 },
+		screenBounds: { x: 97, y: 100, width: 1212, height: 2624 },
+		cornerRadius: 120
+	},
+	{
+		id: 'iphone_17_pro_max',
+		name: 'iPhone 17 Pro Max',
+		platform: 'ios',
+		category: 'phone',
+		frameAsset: '/devices/iphone-17-pro-max.png',
+		imageDimensions: { width: 1520, height: 3068 },
+		screenBounds: { x: 100, y: 100, width: 1320, height: 2870 },
+		cornerRadius: 140
+	},
+	{
+		id: 'iphone_air',
+		name: 'iPhone Air',
+		platform: 'ios',
+		category: 'phone',
+		frameAsset: '/devices/iphone-air.png',
+		imageDimensions: { width: 1490, height: 2996 },
+		screenBounds: { x: 103, y: 106, width: 1284, height: 2786 },
+		cornerRadius: 128
+	},
+
+	// -------------------------------------------------------------------------
+	// ANDROID PHONES
+	// -------------------------------------------------------------------------
+	{
+		id: 'pixel_9_pro',
+		name: 'Google Pixel 9 Pro',
+		platform: 'android',
+		category: 'phone',
+		frameAsset: '/devices/pixel-9-pro.png',
+		imageDimensions: { width: 1620, height: 3136 },
+		screenBounds: { x: 112, y: 111, width: 1396, height: 2916 },
+		cornerRadius: 135
+	},
+	{
+		id: 'pixel_9_pro_xl',
+		name: 'Google Pixel 9 Pro XL',
+		platform: 'android',
+		category: 'phone',
+		frameAsset: '/devices/pixel-9-pro-xl.png',
+		imageDimensions: { width: 1684, height: 3272 },
+		screenBounds: { x: 116, y: 116, width: 1452, height: 3043 },
+		cornerRadius: 140
+	},
+
+	// -------------------------------------------------------------------------
+	// iPadOS TABLETS
+	// -------------------------------------------------------------------------
+	{
+		id: 'ipad_pro_13_m4',
+		name: 'iPad Pro 13" (M4)',
+		platform: 'ios',
+		category: 'tablet',
+		frameAsset: '/devices/ipad-pro-13-m4.png',
+		imageDimensions: { width: 2264, height: 2952 },
+		screenBounds: { x: 100, y: 100, width: 2064, height: 2752 },
+		cornerRadius: 40
+	},
+	{
+		id: 'ipad_pro_11_m4',
+		name: 'iPad Pro 11" (M4)',
+		platform: 'ios',
+		category: 'tablet',
+		frameAsset: '/devices/ipad-pro-11-m4.png',
+		imageDimensions: { width: 1868, height: 2620 },
+		screenBounds: { x: 100, y: 116, width: 1668, height: 2388 },
+		cornerRadius: 40
+	},
+	{
+		id: 'ipad_air_13',
+		name: 'iPad Air 13"',
+		platform: 'ios',
+		category: 'tablet',
+		frameAsset: '/devices/ipad-air-13.png',
+		imageDimensions: { width: 2248, height: 2932 },
+		screenBounds: { x: 100, y: 100, width: 2048, height: 2732 },
+		cornerRadius: 40
+	},
+	{
+		id: 'ipad_air_11',
+		name: 'iPad Air 11"',
+		platform: 'ios',
+		category: 'tablet',
+		frameAsset: '/devices/ipad-air-11.png',
+		imageDimensions: { width: 1880, height: 2600 },
+		screenBounds: { x: 120, y: 120, width: 1640, height: 2360 },
+		cornerRadius: 40
+	},
+	{
+		id: 'ipad_mini_7',
+		name: 'iPad mini 7',
+		platform: 'ios',
+		category: 'tablet',
+		frameAsset: '/devices/ipad-mini-7.png',
+		imageDimensions: { width: 1888, height: 2666 },
+		screenBounds: { x: 200, y: 200, width: 1488, height: 2266 },
+		cornerRadius: 40
+	},
+
+	// -------------------------------------------------------------------------
+	// macOS LAPTOPS
+	// -------------------------------------------------------------------------
+	{
+		id: 'macbook_air_13',
+		name: 'MacBook Air 13"',
+		platform: 'macos',
+		category: 'laptop',
+		frameAsset: '/devices/macbook-air-13.png',
+		imageDimensions: { width: 3260, height: 2164 },
+		screenBounds: { x: 350, y: 306, width: 2560, height: 1608 },
+		cornerRadius: 20
+	},
+	{
+		id: 'macbook_air_13_menu_bar',
+		name: 'MacBook Air 13" (Menu Bar)',
+		platform: 'macos',
+		category: 'laptop',
+		frameAsset: '/devices/macbook-air-13-menu-bar.png',
+		imageDimensions: { width: 3260, height: 2164 },
+		screenBounds: { x: 350, y: 312, width: 2560, height: 1602 },
+		cornerRadius: 20
+	},
+	{
+		id: 'macbook_air_15',
+		name: 'MacBook Air 15"',
+		platform: 'macos',
+		category: 'laptop',
+		frameAsset: '/devices/macbook-air-15.png',
+		imageDimensions: { width: 3580, height: 2364 },
+		screenBounds: { x: 350, y: 306, width: 2880, height: 1808 },
+		cornerRadius: 20
+	},
+	{
+		id: 'macbook_air_15_menu_bar',
+		name: 'MacBook Air 15" (Menu Bar)',
+		platform: 'macos',
+		category: 'laptop',
+		frameAsset: '/devices/macbook-air-15-menu-bar.png',
+		imageDimensions: { width: 3580, height: 2364 },
+		screenBounds: { x: 350, y: 308, width: 2880, height: 1806 },
+		cornerRadius: 20
+	},
+	{
+		id: 'macbook_pro_14',
+		name: 'MacBook Pro 14"',
+		platform: 'macos',
+		category: 'laptop',
+		frameAsset: '/devices/macbook-pro-14.png',
+		imageDimensions: { width: 3944, height: 2564 },
+		screenBounds: { x: 461, y: 364, width: 3022, height: 1900 },
+		cornerRadius: 20
+	},
+	{
+		id: 'macbook_pro_14_menu_bar',
+		name: 'MacBook Pro 14" (Menu Bar)',
+		platform: 'macos',
+		category: 'laptop',
+		frameAsset: '/devices/macbook-pro-14-menu-bar.png',
+		imageDimensions: { width: 3824, height: 2564 },
+		screenBounds: { x: 401, y: 374, width: 3022, height: 1890 },
+		cornerRadius: 20
+	},
+	{
+		id: 'macbook_pro_16',
+		name: 'MacBook Pro 16"',
+		platform: 'macos',
+		category: 'laptop',
+		frameAsset: '/devices/macbook-pro-16.png',
+		imageDimensions: { width: 4340, height: 2860 },
+		screenBounds: { x: 442, y: 377, width: 3456, height: 2170 },
+		cornerRadius: 20
+	},
+	{
+		id: 'macbook_pro_16_menu_bar',
+		name: 'MacBook Pro 16" (Menu Bar)',
+		platform: 'macos',
+		category: 'laptop',
+		frameAsset: '/devices/macbook-pro-16-menu-bar.png',
+		imageDimensions: { width: 4340, height: 2860 },
+		screenBounds: { x: 442, y: 389, width: 3456, height: 2158 },
+		cornerRadius: 20
+	},
+
+	// -------------------------------------------------------------------------
+	// macOS DESKTOPS
+	// -------------------------------------------------------------------------
+	{
+		id: 'imac_24',
+		name: 'iMac 24"',
+		platform: 'macos',
+		category: 'desktop',
+		frameAsset: '/devices/imac-24.png',
+		imageDimensions: { width: 4880, height: 5720 },
+		screenBounds: { x: 200, y: 1600, width: 4480, height: 2520 },
+		cornerRadius: 0
+	},
+	{
+		id: 'studio_display',
+		name: 'Studio Display',
+		platform: 'macos',
+		category: 'desktop',
+		frameAsset: '/devices/studio-display.png',
+		imageDimensions: { width: 5520, height: 4316 },
+		screenBounds: { x: 200, y: 200, width: 5120, height: 2880 },
+		cornerRadius: 0
+	},
+	{
+		id: 'pro_display_xdr',
+		name: 'Pro Display XDR',
+		platform: 'macos',
+		category: 'desktop',
+		frameAsset: '/devices/pro-display-xdr.png',
+		imageDimensions: { width: 6416, height: 4865 },
+		screenBounds: { x: 200, y: 200, width: 6016, height: 3384 },
+		cornerRadius: 0
+	}
+];
+
+// =============================================================================
+// HELPER FUNCTIONS
+// =============================================================================
+
+export function getDeviceFrame(id: string): DeviceFrame | undefined {
+	return deviceFrames.find((d) => d.id === id);
+}
+
+export function getDeviceFramesByPlatform(platform: DeviceFrame['platform']): DeviceFrame[] {
+	return deviceFrames.filter((d) => d.platform === platform);
+}
+
+export function getDeviceFramesByCategory(category: DeviceFrame['category']): DeviceFrame[] {
+	return deviceFrames.filter((d) => d.category === category);
+}

package/src/frames.ts

@@ -0,0 +1,149 @@
+import { getDeviceFrame, type DeviceFrame } from './device-frames';
+import type { LayerJSON } from './types';
+import { generateLayerId } from './validate';
+
+const DEFAULT_CANVAS_WIDTH = 280;
+const DEFAULT_CANVAS_HEIGHT = 600;
+
+/**
+ * Mirror of FabricCanvas.calculateDeviceScale(): fit the device PNG within 85% of
+ * the canvas, capped at 0.15. Kept identical so composed frames size like the editor's.
+ */
+export function calculateDeviceScale(
+	device: DeviceFrame,
+	canvasWidth = DEFAULT_CANVAS_WIDTH,
+	canvasHeight = DEFAULT_CANVAS_HEIGHT
+): number {
+	const maxWidth = canvasWidth * 0.85;
+	const maxHeight = canvasHeight * 0.85;
+	return Math.min(
+		maxWidth / device.imageDimensions.width,
+		maxHeight / device.imageDimensions.height,
+		0.15
+	);
+}
+
+/**
+ * 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).
+ *
+ * `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.
+ */
+export function makeDeviceFrameLayers(opts: {
+	deviceId: string;
+	screenshotUrl: string;
+	screenshotWidth: number;
+	screenshotHeight: number;
+	canvasWidth?: number;
+	canvasHeight?: number;
+	centerX?: number;
+	centerY?: number;
+	scale?: number;
+	screenshotRotation?: number;
+	name?: string;
+}): { screenshot: LayerJSON; frame: LayerJSON } {
+	const device = getDeviceFrame(opts.deviceId);
+	if (!device) throw new Error(`Unknown device: ${opts.deviceId}`);
+
+	const canvasWidth = opts.canvasWidth ?? DEFAULT_CANVAS_WIDTH;
+	const canvasHeight = opts.canvasHeight ?? DEFAULT_CANVAS_HEIGHT;
+	const scale = opts.scale ?? calculateDeviceScale(device, canvasWidth, canvasHeight);
+
+	const frameId = `device-frame-${generateLayerId()}`;
+	const screenshotId = generateLayerId();
+
+	const scaledImageWidth = device.imageDimensions.width * scale;
+	const scaledImageHeight = device.imageDimensions.height * scale;
+	const screenWidth = device.screenBounds.width * scale;
+	const screenHeight = device.screenBounds.height * scale;
+	const screenOffsetX = device.screenBounds.x * scale;
+	const screenOffsetY = device.screenBounds.y * scale;
+	const cornerRadius = device.cornerRadius * scale;
+
+	const frameCenterX = opts.centerX ?? canvasWidth / 2;
+	const frameCenterY = opts.centerY ?? canvasHeight / 2;
+
+	// 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;
+
+	// Scale the screenshot to exactly fill the screen bounds.
+	const imgScaleX = screenWidth / opts.screenshotWidth;
+	const imgScaleY = screenHeight / opts.screenshotHeight;
+
+	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 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
+		}
+	};
+
+	return { screenshot, frame };
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+// App Shot Editor layout DSL — single source of truth shared by the editor,
+// the Cloudflare Worker (handoff validation), and the skill's composer.
+export * from './types';
+export * from './validate';
+export * from './builders';
+export * from './device-frames';
+export * from './frames';
+export * from './compose';

package/src/types.ts

@@ -0,0 +1,71 @@
+/**
+ * App Shot Editor layout DSL — pure data types shared by the editor, the
+ * Cloudflare Worker (handoff validation), and the skill's composer.
+ *
+ * No Fabric.js / runtime dependencies live here: `fabricData` is an opaque JSON
+ * object that the editor enlivens into a Fabric object at load time. Keeping this
+ * module dependency-free is what lets the Worker and the standalone skill bundle
+ * import + validate the same DSL without pulling in the editor.
+ */
+
+export type LayerType = 'background' | 'text' | 'image' | 'device' | 'shape';
+
+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. */
+export interface LayerJSON {
+	id: string;
+	name: string;
+	type: LayerType;
+	visible: boolean;
+	locked: boolean;
+	/** Template-related metadata (optional). */
+	templateRole?: TemplateRole;
+	templateKey?: string;
+	/** Serialized Fabric.js object data (null for the background layer). */
+	fabricData: object | null;
+}
+
+export interface ColorStop {
+	offset: number;
+	color: string;
+}
+
+/** Background is stored separately from layers (it isn't a Fabric object). */
+export interface BackgroundJSON {
+	type: 'solid' | 'gradient';
+	color?: string;
+	gradient?: {
+		type: 'linear' | 'radial';
+		colorStops: ColorStop[];
+		/** @deprecated v1 only — use colorStops. Kept for backward compatibility. */
+		colors?: string[];
+		angle?: number;
+		coords?: { x1: number; y1: number; x2: number; y2: number };
+	};
+}
+
+/** One screen (canvas) of a design. */
+export interface ScreenLayersJSON {
+	schemaVersion: number;
+	canvasWidth?: number;
+	canvasHeight?: number;
+	layers: LayerJSON[];
+	background?: BackgroundJSON;
+}
+
+/** A reusable, multi-screen design — the unit the skill produces + hands off. */
+export interface Template {
+	id: string;
+	name: string;
+	description?: string;
+	thumbnail: string;
+	tags: string[];
+	version: string;
+	screens: ScreenLayersJSON[];
+	createdAt?: string;
+	author?: string;
+}

package/src/validate.ts

@@ -0,0 +1,125 @@
+import type { LayerJSON, ScreenLayersJSON, Template } from './types';
+import { CURRENT_SCHEMA_VERSION } from './types';
+
+const LAYER_TYPES = ['background', 'text', 'image', 'device', 'shape'];
+
+/** Check if a value is a valid LayerJSON. */
+export function isValidLayerJSON(data: unknown): data is LayerJSON {
+	if (!data || typeof data !== 'object') return false;
+	const obj = data as Record<string, unknown>;
+	return (
+		typeof obj.id === 'string' &&
+		typeof obj.name === 'string' &&
+		typeof obj.type === 'string' &&
+		LAYER_TYPES.includes(obj.type as string) &&
+		typeof obj.visible === 'boolean' &&
+		typeof obj.locked === 'boolean'
+	);
+}
+
+/** Check if a value is a valid ScreenLayersJSON. */
+export function isValidScreenLayersJSON(data: unknown): data is ScreenLayersJSON {
+	if (!data || typeof data !== 'object') return false;
+	const obj = data as Record<string, unknown>;
+	return (
+		typeof obj.schemaVersion === 'number' &&
+		Array.isArray(obj.layers) &&
+		obj.layers.every(isValidLayerJSON)
+	);
+}
+
+/** Check if a value is a valid Template. */
+export function isValidTemplate(data: unknown): data is Template {
+	if (!data || typeof data !== 'object') return false;
+	const obj = data as Record<string, unknown>;
+	return (
+		typeof obj.id === 'string' &&
+		typeof obj.name === 'string' &&
+		typeof obj.thumbnail === 'string' &&
+		Array.isArray(obj.tags) &&
+		typeof obj.version === 'string' &&
+		Array.isArray(obj.screens) &&
+		obj.screens.every(isValidScreenLayersJSON)
+	);
+}
+
+/** Migrate a ScreenLayersJSON from older schema versions to the current one. */
+export function migrateScreenLayersJSON(json: ScreenLayersJSON): ScreenLayersJSON {
+	let migrated = { ...json };
+
+	// v1 -> v2: convert gradient `colors` array to `colorStops` with offsets.
+	if (migrated.schemaVersion < 2) {
+		const gradient = migrated.background?.gradient;
+		const hasColors = gradient?.colors && gradient.colors.length > 0;
+		const hasColorStops = gradient?.colorStops && gradient.colorStops.length > 0;
+
+		if (hasColors && !hasColorStops) {
+			const colors = gradient!.colors!;
+			migrated = {
+				...migrated,
+				schemaVersion: 2,
+				background: {
+					...migrated.background!,
+					gradient: {
+						...gradient!,
+						colorStops: colors.map((color, index) => ({
+							offset: colors.length > 1 ? index / (colors.length - 1) : 0,
+							color
+						}))
+					}
+				}
+			};
+			delete migrated.background!.gradient!.colors;
+		} else {
+			migrated.schemaVersion = 2;
+		}
+	}
+
+	return migrated;
+}
+
+/** Generate a unique layer id. */
+export function generateLayerId(): string {
+	return `layer-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+}
+
+export interface ValidationResult {
+	valid: boolean;
+	errors: string[];
+}
+
+/**
+ * Strict, error-reporting validation for a Template (used by the Worker on
+ * handoff upload and by the skill's composer before sending). Unlike the boolean
+ * `isValidTemplate`, this returns a list of human-readable problems.
+ */
+export function validateTemplate(data: unknown): ValidationResult {
+	const errors: string[] = [];
+	if (!data || typeof data !== 'object') {
+		return { valid: false, errors: ['Template must be an object'] };
+	}
+	const t = data as Record<string, unknown>;
+
+	if (typeof t.id !== 'string' || !t.id) errors.push('id must be a non-empty string');
+	if (typeof t.name !== 'string' || !t.name) errors.push('name must be a non-empty string');
+
+	if (!Array.isArray(t.screens) || t.screens.length === 0) {
+		errors.push('screens must be a non-empty array');
+	} else {
+		t.screens.forEach((screen, i) => {
+			if (!isValidScreenLayersJSON(screen)) {
+				errors.push(`screens[${i}] is not a valid screen`);
+				return;
+			}
+			const s = screen as ScreenLayersJSON;
+			if (s.schemaVersion > CURRENT_SCHEMA_VERSION) {
+				errors.push(`screens[${i}] has unsupported schemaVersion ${s.schemaVersion}`);
+			}
+			s.layers.forEach((layer, j) => {
+				if (!isValidLayerJSON(layer)) errors.push(`screens[${i}].layers[${j}] is invalid`);
+			});
+		});
+	}
+
+	return { valid: errors.length === 0, errors };
+}