@appshoteditor/shot-dsl 0.4.0 → 0.5.0

package/README.md

@@ -25,6 +25,9 @@ composer — so a layout composed by the skill renders identically in the editor
 - **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';
@@ -95,19 +98,30 @@ Plan additions (all optional; a 0.3.0 plan composes and validates unchanged):
 | `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.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:
 
-- **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.
+- **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,
@@ -137,6 +151,58 @@ Output shapes:
 - **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;
@@ -147,31 +213,41 @@ Output shapes:
 - 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.
+- 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 concepts, intended as Product Page Optimization test
-candidates. Each is named `<name> — A Framed` / `— B Frameless` / `— C Panorama`:
+`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:** 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.
+- **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`;
+- `background`, `deviceId`, `screenshot`, `focus`, `crop`, `callout`, `mascot`, `art`;
 - canvas size;
-- `style.palette`, `style.font` and `style.bleed` (default `auto`).
+- 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`: screens only share one device scale and baseline when they
-  share a layout;
+- every `layout` becomes `text-top` (the hero and rhythm accents differ on purpose);
 - per-screen `presentation` and `tilt` are dropped;
-- A and B are straight, with no panorama.
+- palette mode → `tonal` with the concept's tone; hero, rhythm, callouts, panorama per concept.
 
 ## Layer order
 
@@ -236,7 +312,10 @@ and the editor converts it on import.
 > 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.
+> 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.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.).",
+  "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",
@@ -23,7 +23,10 @@
     "src/device-frames.ts",
     "src/layout-system.ts",
     "src/color.ts",
-    "src/variants.ts"
+    "src/variants.ts",
+    "src/typography.ts",
+    "src/palette.ts",
+    "src/decor.ts"
   ],
   "sideEffects": false,
   "keywords": [