@appshoteditor/shot-dsl 0.2.0 → 0.4.0

package/README.md

@@ -10,15 +10,21 @@ 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`.
-- **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.
+- **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`
+  (`composeSet(plan)` returns the same template plus a `report` with lint warnings and per-screen
+  geometry). 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.
+- **Set layout system (0.4.0)** — `solveVertical` / `NO_TANGENT` (the no-tangent rule), `focusReach`,
+  `rotatedBox` (`layout-system.ts`); `makeVariants(plan)` (three concept plans, `variants.ts`); small
+  colour helpers (`color.ts`).
 
 ```ts
 import { composeTemplate, validateTemplate } from '@appshoteditor/shot-dsl';
@@ -39,6 +45,199 @@ const template = composeTemplate({
 validateTemplate(template); // { valid: true, errors: [] }
 ```
 
+## Set layout system (0.4.0)
+
+`composeSet` lays a plan out as ONE system, the way a screenshot designer would:
+
+1. **One system per set.** It measures every screen's text block first and reserves a text area
+   for the TALLEST one (per canvas size). The headline size is fixed for the whole set
+   (`HEADLINE_SIZE` × the type unit). Long copy is never shrunk: it gets a lint warning instead.
+   Screens that share a canvas size, presentation, device, layout and tilt (`report.screens[i].group`)
+   get the same subject scale and baseline, so copy length never moves or resizes anything.
+2. **No tangents.** A device (or frameless screenshot) either clears the far edge by ≥ 4% of H or
+   bleeds off it by ≥ 12% of its own height. The band in between is the "just touching" look, and
+   `solveVertical` never emits it. `style.bleed` picks how a tangent is resolved:
+   - `auto` (default): a device that already clears by the margin stays as it is. Otherwise it
+     bleeds decisively: it grows toward the 90%-of-W cap, then shifts down. It clears with the
+     margin only when every ≥ 12% bleed would crop its focus band.
+   - `none`: always fully visible.
+   - `deep`: bleed ≥ 25%.
+3. **No side tangents.** No subject is wider than 90% of W (`NO_TANGENT.maxWidth`). The part that is
+   actually on the canvas keeps ≥ 5% of W from both side edges. The only side bleed is a deliberate
+   panorama straddle across a seam.
+4. **Focus-aware, on all four edges.** Marked `focus` band corners (`{ top, bottom }`, fractions of
+   the screenshot height) always stay:
+   - ≥ 2% of H inside the top and bottom edges;
+   - ≥ 2% of W inside the side edges and any seam. This includes tilted subjects: their rotated
+     corners are checked.
+
+   A bleed that would crop the band is reduced, or turned into the clear-with-margin option. When a
+   tilt doesn't fit the side rules, the composer first shrinks the device, or the zoom card (keeping
+   its aspect), by at most 20%. After
+   that it reduces the tilt in quarter steps, down to straight if needed, and warns `tilt-reduced`.
+   In a group, the most restrictive focus decides for every screen. A zoom card that can't show a
+   whole band warns `zoom-focus-cropped`.
+5. **Room for the device.** The device must keep at least half the size it would get on this canvas
+   with NO copy. That size is height-limited for tall devices on landscape canvases, such as an iMac
+   on 608×380. If the text leaves less room, `composeSet` throws "copy too long for this canvas … cut
+   the subheadline or headline". If even the no-copy fit is under 30% of the target width, it throws
+   "device … doesn't fit a W×H canvas … use the device's own canvas", because the canvas, not the
+   copy, is the problem.
+
+Text metrics are per font (`FONT_CHAR_WIDTH`, plus character classes: capitals and m/w count
+wider, i/l and punctuation narrower). They are calibrated to be conservative for every
+`COMPOSE_FONTS` entry, so an estimated 2-line headline never renders as 3.
+
+Plan additions (all optional; a 0.3.0 plan composes and validates unchanged):
+
+| Field | Where | Meaning |
+| --- | --- | --- |
+| `style.presentation` | plan | `device` (default) · `frameless` (rounded screenshot + shadow) · `zoom` (magnified crop of `crop`, else the centre of the `focus` band) |
+| `style.tilt`, `style.tiltScreens` | plan | Degrees (clockwise) applied only to the listed screen indices. A tilted subject prefers a bleed under `auto`/`deep`; the tilt is reduced (`tilt-reduced`) if it can't keep the side margins. |
+| `style.bleed` | plan | `auto` · `none` · `deep` (see above) |
+| `style.palette` | plan | `{ mode: "family" \| "sequence", colors: [hex…] }`. Background for screens that omit one. |
+| `style.panorama` | plan | `{ spans: [[0,1], …], straddle?: true \| [screen…], decoration?: "orbs" \| "none" }`. Adjacent screens share one continuous background; `straddle` picks the span-start screens whose device crosses the seam. |
+| `style.font` | plan | One of `COMPOSE_FONTS` (the editor's font list). |
+| `focus`, `crop`, `presentation`, `tilt`, `badge` | screen | Focus band · zoom crop `{x,y,w,h}` · per-screen overrides · a social-proof pill above the headline |
+
+Output shapes:
+
+- **Headline colour.** An explicit `headlineColor` / `subheadlineColor` always wins. Otherwise, on a
+  palette background or in a panorama span, it is white or `#111827`, whichever has the better
+  worst-case WCAG contrast. The contrast is checked against the background actually behind the text
+  block, sampled over it. For a span, that is the span's N·W gradient, which uses the FIRST
+  screen's background, at this screen's offset. A screen with its own explicit background outside a
+  span keeps the white default.
+- **Frameless / zoom** is a plain `type: 'image'` layer:
+  - Its `src` is the uploaded screenshot, with `crossOrigin: 'anonymous'`.
+  - It has a rounded `clipPath` Rect in the image's local space, `imageCornerRadius` (canvas units,
+    the editor's corner-radius control) and a Fabric `shadow` (blur/offset in the object's own units,
+    like the editor's shadow control).
+  - Zoom adds Fabric `cropX`/`cropY` with `width`/`height` set to the crop size.
+  - Every screen of a zoom group uses the same card box.
+- **Tilt** is the device layer's `angle`. The editor rotates the screenshot with the frame on attach, on
+  move/scale/rotate, and in the offscreen export.
+- **Panorama** is pure DSL:
+  - Each screen of a span gets a locked `Rect` of size N·W × H at `left = N·W/2 − k·W`, painted with
+    the span-start screen's background.
+    - A solid colour stays solid.
+    - A linear gradient keeps its stops and `angle`, applied across N·W; without an `angle` it runs
+      corner to corner.
+    - Radial gradients and explicit `coords` throw a clear error.
+  - Optional seam orbs are moved or shrunk so they never overlap either neighbour's text block, and
+    dropped when there's no room.
+  - With `straddle` (`true` = every span, or a list of span-start screen indices), that span's first
+    device is shifted right so it crosses the seam. More than one crossing per set is lint-warned
+    (`panorama-straddle-count`). A copy of it,
+    named "… (continued)", is emitted on the next screen at `left − W`, below that screen's own device.
+  - The straddle is only ever a rightward shift. It must keep the left side margin, and when a
+    `focus` band is marked, the band stays ≥ 2% of W inside the seam. Otherwise the straddle is
+    skipped (`straddle-skipped`) and the device is placed like any other screen.
+  - In the editor, the halves are independent layers: moving one does not move the other.
+- **Badge** is a rounded `Rect` pill plus a `Textbox` (`templateKey: 'badge'`). They sit in a badge row
+  above the headline, reserved set-wide, so they never collide with the text or the device.
+
+`report.warnings` (`ComposeWarning`) flags:
+
+- a headline over 5 words, or estimated at more than 2 lines at the set size;
+- a subheadline estimated at more than 1 line;
+- more than 2 tilted screens;
+- a seam crossing a headline or focus band, or a straddle that can't be checked because no focus
+  band is marked;
+- skipped straddles, and more than one straddle per set;
+- tilts reduced to keep the side margins;
+- zoom crops that can't show their whole focus band;
+- long badges.
+
+Warnings never block composing.
+
+`makeVariants(plan)` returns three distinct concepts, intended as Product Page Optimization test
+candidates. Each is named `<name> — A Framed` / `— B Frameless` / `— C Panorama`:
+
+- **A:** device frames, straight, all `text-top`.
+- **B:** frameless. Screens with a `crop`, or a `focus` band ≤ 45% tall, become zoom cards.
+- **C:** panorama spans: the input's `panorama.spans`, or adjacent pairs, with a continuous
+  background and seam orbs. Only screen 1 (the hero) is tilted (the input's `style.tilt`, or 8°)
+  and straddles its seam, unless the input sets `straddle`. Every other device stays centred and
+  straight.
+
+**Kept from the input** in every concept:
+- copy (headline / subheadline / badge) and `headlineColor` / `subheadlineColor`;
+- `background`, `deviceId`, `screenshot`, `focus`, `crop`;
+- canvas size;
+- `style.palette`, `style.font` and `style.bleed` (default `auto`).
+
+**Overridden:**
+- every `layout` becomes `text-top`: screens only share one device scale and baseline when they
+  share a layout;
+- per-screen `presentation` and `tilt` are dropped;
+- A and B are straight, with no panorama.
+
+## 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). 0.4.0 adds no new layer shapes that the 0.3.0 validator
+> or importer would reject: frameless/zoom are ordinary image layers, and panorama and badges are
+> ordinary shape and text layers.
+
 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.2.0",
+  "version": "0.4.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",
@@ -20,7 +20,10 @@
     "src/builders.ts",
     "src/compose.ts",
     "src/frames.ts",
-    "src/device-frames.ts"
+    "src/device-frames.ts",
+    "src/layout-system.ts",
+    "src/color.ts",
+    "src/variants.ts"
   ],
   "sideEffects": false,
   "keywords": [

package/src/color.ts

@@ -0,0 +1,76 @@
+/**
+ * Tiny, dependency-free colour helpers for the composer's palette / panorama / badge styling.
+ * Only `#rgb` / `#rrggbb` hex input is understood; anything else is passed through untouched
+ * (callers fall back to sensible defaults).
+ */
+
+export type RGB = { r: number; g: number; b: number };
+
+const HEX = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+
+export function isHexColor(value: unknown): value is string {
+	return typeof value === 'string' && HEX.test(value);
+}
+
+export function parseHex(hex: string): RGB | null {
+	if (!isHexColor(hex)) return null;
+	let h = hex.slice(1);
+	if (h.length === 3) h = h.replace(/./g, (c) => c + c);
+	return { r: parseInt(h.slice(0, 2), 16), g: parseInt(h.slice(2, 4), 16), b: parseInt(h.slice(4, 6), 16) };
+}
+
+export function toHex({ r, g, b }: RGB): string {
+	const c = (n: number) => Math.round(Math.max(0, Math.min(255, n))).toString(16).padStart(2, '0');
+	return `#${c(r)}${c(g)}${c(b)}`.toUpperCase();
+}
+
+/** Linear mix of `a` toward `b` by `t` (0 → a, 1 → b). Non-hex input returns `a`. */
+export function mixHex(a: string, b: string, t: number): string {
+	const x = parseHex(a);
+	const y = parseHex(b);
+	if (!x || !y) return a;
+	return toHex({ r: x.r + (y.r - x.r) * t, g: x.g + (y.g - x.g) * t, b: x.b + (y.b - x.b) * t });
+}
+
+export const lighten = (hex: string, t: number): string => mixHex(hex, '#ffffff', t);
+export const darken = (hex: string, t: number): string => mixHex(hex, '#000000', t);
+
+/** WCAG relative luminance (0 = black, 1 = white); 0 for non-hex input. */
+export function luminance(hex: string): number {
+	const c = parseHex(hex);
+	if (!c) return 0;
+	const lin = (v: number) => {
+		const s = v / 255;
+		return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+	};
+	return 0.2126 * lin(c.r) + 0.7152 * lin(c.g) + 0.0722 * lin(c.b);
+}
+
+/** `rgba(r,g,b,a)` from a hex colour (white for non-hex input). */
+export function rgba(hex: string, alpha: number): string {
+	const c = parseHex(hex) ?? { r: 255, g: 255, b: 255 };
+	return `rgba(${c.r},${c.g},${c.b},${alpha})`;
+}
+
+/** WCAG contrast ratio between two hex colours (1 … 21). */
+export function contrastRatio(a: string, b: string): number {
+	const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+	return (hi + 0.05) / (lo + 0.05);
+}
+
+export const DARK_TEXT = '#111827';
+export const LIGHT_TEXT = '#FFFFFF';
+
+/**
+ * The text colour (white or near-black) with the best WORST-case contrast against every sampled
+ * background colour (e.g. several points of a gradient behind a headline).
+ */
+export function readableTextOn(backgrounds: string[]): string {
+	const worst = (text: string) => Math.min(...backgrounds.map((bg) => contrastRatio(text, bg)));
+	return worst(DARK_TEXT) > worst(LIGHT_TEXT) ? DARK_TEXT : LIGHT_TEXT;
+}
+
+/** Readable text colour on a background of `hex` (see readableTextOn). */
+export function contrastText(hex: string): string {
+	return readableTextOn([hex]);
+}