@appshoteditor/shot-dsl 0.2.0 → 0.4.0

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));
 			});
 		});
 	}

package/src/variants.ts

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