@appshoteditor/shot-dsl 0.1.1 → 0.2.0

package/README.md

@@ -15,6 +15,10 @@ composer — so a layout composed by the skill renders identically in the editor
   `makeScreen`, `makeTemplate`.
 - **Device geometry** — `deviceFrames`, `getDeviceFrame`, `makeDeviceFrameLayers`, `calculateDeviceScale`.
 - **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 +28,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 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appshoteditor/shot-dsl",
-  "version": "0.1.1",
+  "version": "0.2.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/builders.ts

@@ -1,4 +1,4 @@
-import type { BackgroundJSON, ColorStop, LayerJSON, ScreenLayersJSON, Template, TemplateRole } from './types';
+import type { BackgroundJSON, ColorStop, DeviceClass, LayerJSON, ScreenLayersJSON, Template, TemplateRole } from './types';
 import { CURRENT_SCHEMA_VERSION } from './types';
 import { generateLayerId } from './validate';
 
@@ -176,11 +176,13 @@ export function makeScreen(opts: {
 	background?: BackgroundJSON;
 	canvasWidth?: number;
 	canvasHeight?: number;
+	deviceClass?: DeviceClass;
 }): ScreenLayersJSON {
 	return {
 		schemaVersion: CURRENT_SCHEMA_VERSION,
 		canvasWidth: opts.canvasWidth ?? DEFAULT_CANVAS_WIDTH,
 		canvasHeight: opts.canvasHeight ?? DEFAULT_CANVAS_HEIGHT,
+		deviceClass: opts.deviceClass,
 		layers: opts.layers,
 		background: opts.background
 	};

package/src/compose.ts

@@ -1,7 +1,7 @@
-import type { BackgroundJSON, Template } from './types';
+import type { BackgroundJSON, LayerJSON, Template } from './types';
 import { makeTextLayer, makeScreen, makeTemplate } from './builders';
 import { makeDeviceFrameLayers } from './frames';
-import { getDeviceFrame } from './device-frames';
+import { getDeviceFrame, deviceClassForDeviceId } from './device-frames';
 
 /**
  * Editor-unit canvas dimensions for a device, by frame class — so a plan that mixes iPhone, iPad,
@@ -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-framed 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,42 +159,99 @@ 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 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
+		}
+
 		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
+			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)
+		const layers: LayerJSON[] = [screenshot, 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);
+		}
+
+		// z-order: screenshot (bottom) -> frame -> headline -> subheadline (top)
 		return makeScreen({
 			background: screen.background,
-			canvasWidth,
-			canvasHeight,
-			layers: [screenshot, frame, headline]
+			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
 		});
 	});
 

package/src/device-frames.ts

@@ -1,3 +1,5 @@
+import type { DeviceClass } from './types';
+
 // =============================================================================
 // DEVICE FRAME DEFINITIONS
 // =============================================================================
@@ -316,3 +318,16 @@ export function getDeviceFramesByPlatform(platform: DeviceFrame['platform']): De
 export function getDeviceFramesByCategory(category: DeviceFrame['category']): DeviceFrame[] {
 	return deviceFrames.filter((d) => d.category === category);
 }
+
+/**
+ * Map a device-frame id to its device GROUP (multi-device), using the frame's platform + category.
+ * Returns null for an unknown id. Kept in sync with the app's `device-groups.ts` mapping.
+ */
+export function deviceClassForDeviceId(deviceId: string): DeviceClass | null {
+	const frame = getDeviceFrame(deviceId);
+	if (!frame) return null;
+	if (frame.platform === 'ios') return frame.category === 'tablet' ? 'ipad_13' : 'iphone_6_9';
+	if (frame.platform === 'android') return 'android_phone';
+	if (frame.platform === 'macos' || frame.platform === 'windows') return 'macbook';
+	return null;
+}

package/src/types.ts

@@ -48,11 +48,19 @@ export interface BackgroundJSON {
 	};
 }
 
+/**
+ * Device GROUP a screen belongs to (multi-device). Mirrors the app's `db.ts` union so a composed
+ * template can tag each screen and the editor buckets it into the right sidebar group on import.
+ */
+export type DeviceClass = 'iphone_6_9' | 'ipad_13' | 'android_phone' | 'macbook';
+
 /** One screen (canvas) of a design. */
 export interface ScreenLayersJSON {
 	schemaVersion: number;
 	canvasWidth?: number;
 	canvasHeight?: number;
+	/** Device group (multi-device); optional/additive — absent ⇒ the editor infers it. */
+	deviceClass?: DeviceClass;
 	layers: LayerJSON[];
 	background?: BackgroundJSON;
 }