@appshoteditor/shot-dsl 0.3.0 → 0.5.0

package/README.md

@@ -16,11 +16,18 @@ composer — so a layout composed by the skill renders identically in the editor
   `makeScreen`, `makeTemplate`.
 - **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.
+- **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`).
+- **Art direction (0.5.0)** — `breakLines` (balanced line breaks, `typography.ts`), tonal palettes +
+  `harmonize` (one WCAG-AA text colour per set, `palette.ts`), panorama motifs (`decor.ts`), and in
+  `composeSet`: the hero, accent rhythm, callouts, mascots and shadows (see "Art direction" below).
 
 ```ts
 import { composeTemplate, validateTemplate } from '@appshoteditor/shot-dsl';
@@ -41,6 +48,207 @@ 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: "tonal" \| "family" \| "sequence", colors: [hex…], tone? }`. Background for screens that omit one; ONE text colour per set (see Art direction). |
+| `style.panorama` | plan | `{ spans?: [[0,1], …], straddle?: true \| [screen…], decoration?: "orbs" \| "honeycomb" \| "wave" \| "none" }`. Adjacent screens share one continuous background; `straddle` picks the span-start screens whose device crosses the seam (only by ≥ 18% of it). |
+| `style.hero`, `style.rhythm`, `style.callouts`, `style.shadows` | plan | 0.5.0 — see Art direction. |
+| `art` | plan | 0.5.0 `[{ id, url, width, height, faces? }]` brand art (uploaded-asset URLs only). |
+| `callout`, `mascot` | screen | 0.5.0 — a magnified crop of the selling element · brand art placement. |
+| `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:
+
+- **Text colour (0.5.0: ONE per set).** An explicit `headlineColor` / `subheadlineColor` always
+  wins. Otherwise EVERY screen takes part in choosing one set colour: `harmonize` tries a dark and a
+  light candidate (a deep / pale tint of the brand hue for tonal palettes, else `#111827` / white),
+  sampling every screen on a 5×7 grid. Palette / span backgrounds may be re-toned (moved away from
+  the text in small steps until the worst sample passes WCAG 4.5); explicit backgrounds are sampled
+  as they are and never recoloured. The candidate needing the least re-toning wins (the other only
+  if it also passes on the explicit backgrounds for ≤ 0.15 more). If the set colour still can't reach
+  4.5 on an explicit background, ONLY that screen gets its own best colour (a panorama span whose
+  fill is explicit counts as ONE unit: one colour for the whole span, so the scene stays consistent) —
+  `report.screens[i].textColorSource === "screen"` (else `"set"`, or `"plan"` for an explicit
+  `headlineColor`). An explicit-only set keeps white whenever white passes (0.4.0). The headline and
+  subheadline are also checked densely right behind their boxes; a screen that no colour can bring to
+  4.5 warns `contrast-low` — never silent. The subheadline's brand tint is used only when it clears
+  4.6 (a margin, so it never lands at 4.49).
+- **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.
+
+### Art direction (0.5.0)
+
+- **Line breaks.** Headlines and subheadlines are set in `breakLines` lines. An explicit `\n` is ALWAYS
+  a break — lines the author broke are never merged, on any device or role. Only a line (explicit or
+  not) wider than the box is broken further: into the greedy line count, re-balanced (no single word
+  on the last line, breaks after punctuation preferred, never after "the"/"to"/…; past 40 tokens it
+  breaks greedily, so absurd copy fails fast). CJK / kana / Hangul count ~1 em per glyph and may
+  break between glyphs. The breaks are emitted as `\n` in the Textbox. A single word wider than the
+  box throws (Fabric can't wrap inside a word — it would widen the box past the margins).
+  Subheadline: 0.5× the headline, weight 600, full opacity, tinted 18% toward the brand hue when
+  that still passes AA. Text box 0.88 W.
+- **Tonal palette.** `{ mode: "tonal", colors: [base, accent?], tone: "light" | "vivid" | "deep" }`:
+  screen i gets tonal step i % 4 of the base hue as a vertical gradient (the hero step 0). The accent
+  fills badge pills. Tonal panorama spans run one ramp through their members' tones.
+- **Hero** (`style.hero`, default ON for screen 1; `false` = off): headline 1.25× (stepped down in
+  0.05s — to 1× if needed — so it never has more lines than at the set size; `scale` 1–1.4), its own group with bleed `deep`, optional `layout`, `tilt`,
+  `badge`, `mascot`. `report.screens[i].role` is `hero`.
+- **Rhythm** (`style.rhythm: { every, treatment }`): screens where `i % every === every − 1` are
+  `accent`s — `text-bottom` layout, or `callout` (a forced callout + deep bleed). All `set`-role
+  screens still share one group, type size, text area, scale and baseline.
+- **Callouts** (`screen.callout` crop, or `style.callouts: "auto"` from a focus band ≤ 50% tall): an
+  image layer with the SAME uploaded `src` + `cropX`/`cropY`, rounded, shadowed, magnified 1.6–2.2×
+  (down to 1.25× to fit), inside 3.5% side margins, between the text block and a 4% far-edge margin.
+  It may cover its own source slice (the pop-out), but it hides at most `CALLOUT_MAX_FOCUS_COVER`
+  (35%) of the REST of the focus band: it is centred on its source when that allows, else moved
+  up/down or out to a side edge (breaking out of the device), else made smaller; if nothing works it
+  is skipped (`callout-skipped`). `report.screens[i].callout.focusCover` is the share hidden. Never on
+  zoom cards or a straddling device.
+- **Mascots** (`plan.art` + `screen.mascot` / `style.hero.mascot`): an image layer (uploaded src,
+  `flipX` to face into the canvas when `faces` is given, shadow). Anchors `headline` / `device-top` /
+  `device-side` / `seam` are tried in order with fallbacks at 100/85/70% size; a placement must clear
+  every text line, the badge, the subheadline, the callout, every other mascot on the screen
+  (including a neighbour's seam half) and the focus band's core (its outer 10% W may be overlapped).
+  `seam` puts one mascot across a panorama seam, emitted on both screens (±W). Otherwise
+  `mascot-skipped`.
+- **Badges** keep their label at WCAG ≥ 4.5 on the pill: a solid (tonal accent) pill is toned
+  toward black or white until it does; a translucent one gets fainter.
+- **Shadows** (`style.shadows`, default true), tinted with the brand hue: device layers get
+  `fabricData.deviceShadow = { color, blur, offsetX, offsetY }` in CANVAS units — the editor casts it
+  from the frame's screenshot (a Fabric shadow on the frame PNG would fall into its transparent screen
+  hole); frameless / zoom / callouts / mascots get a Fabric `shadow` in object units.
+  `validateTemplate` checks `deviceShadow` (device layers only; colour ≤ 64 chars; blur 0…canvasWidth;
+  offsets ±canvasWidth).
+- **Panorama motif** (`decoration: "honeycomb" | "wave"`): the motif is laid out across the whole span,
+  but each screen emits only ITS part (the hexagons / wave segments touching it plus a 2-stroke
+  overdraw) as one locked `Path` in its own coordinates, rounded to 0.1 unit; both neighbours emit
+  the same points around a seam, so it runs on continuously. (0.5.0-pre emitted the whole N·W path on
+  every screen — O(N²) bytes.)
+- **Handoff size.** `MAX_HANDOFF_BYTES` (256 KiB, the server's cap) and `handoffBytes(template)` (UTF-8
+  size of the `{ template }` request body). The skill's `lint` / `compose` / `publish` / `variants`
+  error over the cap and warn over 80%. A 30-screen phone + iPad + Mac honeycomb panorama is ≈ 166 KB.
+
+`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;
+- 0.5.0: a stranded last headline word (`headline-orphan`), a screen no colour can bring to AA
+  (`contrast-low`), a callout that can't be magnified or placed without hiding the focus band
+  (`callout-skipped`), no room for a mascot (`mascot-skipped`).
+
+Backward compatibility (0.5.0): a 0.4.0 plan still composes, but screen 1 is now the hero (1.25×
+headline, `deep` bleed, its own device pose) and devices get shadows — `style.hero: false` /
+`style.shadows: false` restore the 0.4.0 look. Balanced line breaks can change where a headline
+wraps, and the new warnings can make `--strict` fail for a plan that passed before.
+
+Warnings never block composing.
+
+`makeVariants(plan)` returns three distinct ART DIRECTIONS, intended as Product Page Optimization
+test candidates. Each is named `<name> — A Brand Classic` / `— B Clean Frameless` / `— C Story Panorama`:
+
+- **A Brand Classic:** device frames on the `vivid` tonal palette, hero with the mascot (first `art`)
+  + badge, `callouts: "auto"` (plus explicit ones), rhythm every 4 (`text-bottom`).
+- **B Clean Frameless:** `light` tonal palette, full-width frameless screenshots with a `deep` bleed
+  (a zoom card only for an explicit `crop` — B1), callouts, hero at 1.3× with the mascot.
+- **C Story Panorama:** `deep` tonal palette; spans = the input's `panorama.spans`, else triples and
+  pairs (`panoramaRuns`); `decoration` = the input's (not `orbs`), else `wave`; a mascot crossing the
+  first seam of every span but the hero's; the hero tilted (the input's `style.tilt`, or 8°); bleed
+  `deep`; a straddle only if the input asks.
+
+**Kept from the input** in every concept:
+- copy (headline / subheadline / badge) and `headlineColor` / `subheadlineColor`;
+- `background`, `deviceId`, `screenshot`, `focus`, `crop`, `callout`, `mascot`, `art`;
+- canvas size;
+- the brand colours (`style.palette.colors`; else the first screen's background colour), `style.font`,
+  and `style.bleed: none`.
+
+**Overridden:**
+- every `layout` becomes `text-top` (the hero and rhythm accents differ on purpose);
+- per-screen `presentation` and `tilt` are dropped;
+- palette mode → `tonal` with the concept's tone; hero, rhythm, callouts, panorama per concept.
+
 ## Layer order
 
 A screen's `layers` array is **bottom → top**: index 0 is painted first (canvas add order), the last
@@ -102,7 +310,12 @@ and the editor converts it on import.
 `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).
+> (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. 0.5.0 likewise: callouts and mascots are image layers with
+> uploaded-asset srcs, motifs are `Path` shape layers — all accepted by the 0.4.0 validator (and by
+> 0.5.0's, which additionally checks the shape of `deviceShadow`). Only the device shadow needs a
+> 0.5.0-aware editor to render; older editors ignore it.
 
 Zero runtime dependencies. The `schemaVersion` is the compatibility contract between producers and the editor.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@appshoteditor/shot-dsl",
-  "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.).",
+  "version": "0.5.0",
+  "description": "App Shot Editor layout DSL + device-frame geometry \u2014 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",
@@ -20,7 +20,13 @@
     "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",
+    "src/typography.ts",
+    "src/palette.ts",
+    "src/decor.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]);
+}