@appshoteditor/shot-dsl 0.5.2 → 0.5.3

package/README.md

@@ -60,13 +60,18 @@ validateTemplate(template); // { valid: true, errors: [] }
 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.
+   - `auto` (default): a device that already clears by the margin, or already bleeds decisively
+     (≥ 12%, without cropping its focus band), stays as it is. Otherwise it grows toward the
+     90%-of-W cap; if that's still short of a 12% bleed, "minimum disturbance" decides between
+     clearing and shifting down: it clears at the near edge (no shift) when that clear scale is
+     ≥ 88% of the grown/capped scale (`NO_TANGENT.clearOverShift`); otherwise it shifts down only
+     as far as exactly a 12% bleed.
    - `none`: always fully visible.
    - `deep`: grows the subject toward a 25% bleed (still capped at 90% W). When growth alone can't
-     reach 25% (the size cap bites first), it shifts down too — but never further than a 12% bleed
-     needs, even though the target is 25%: it never shifts deeper just to force that target.
+     reach 25% and a down-shift would be the only way to reach even 12%, the same minimum-disturbance
+     rule applies: it clears at the near edge when that costs ≤ 12% of the grown/capped scale;
+     otherwise it shifts down only as far as exactly a 12% bleed needs — never deeper, even though
+     the target is 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.
@@ -98,7 +103,7 @@ 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.tilt`, `style.tiltScreens` | plan | Degrees (clockwise) applied only to the listed screen indices. A tilted subject prefers a deeper bleed under `auto`/`deep`, but clears instead when its scale cap (from keeping the side margins) stops it reaching a decisive bleed without a big down-shift (minimum disturbance, see above); the tilt itself is reduced (`tilt-reduced`) if it can't keep the side margins at all. |
 | `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). |
@@ -234,9 +239,9 @@ Warnings never block composing.
 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`).
+  + badge, callouts (the input's explicit `style.callouts`, else `auto`), 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.
+  (a zoom card only for an explicit `crop` — B1), callouts (same default as A), 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
@@ -252,7 +257,9 @@ test candidates. Each is named `<name> — A Brand Classic` / `— B Clean Frame
 **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.
+- palette mode → `tonal` with the concept's tone; hero, rhythm, panorama per concept;
+- `callouts` per concept too, but only C's is fixed (`none`) — A and B keep the input's explicit
+  `style.callouts`, defaulting to `auto` only when the input leaves it unset.
 
 ## Layer order
 

package/package.json

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

@@ -157,7 +157,10 @@ export interface ComposeMascot {
 	flip?: boolean;
 }
 
-/** The hero (screen 1 by default): larger type, optional mascot + badge, deeper bleed and/or tilt. */
+/**
+ * The hero (screen 1 by default): larger type, optional mascot + badge, and/or tilt. Prefers a deeper
+ * bleed, but clears rather than leave a gap under the text.
+ */
 export interface ComposeHero {
 	/** Hero screen index. Default 0. */
 	screen?: number;

package/src/layout-system.ts

@@ -36,6 +36,14 @@ export const NO_TANGENT = {
 	focusSideSafe: 0.02,
 	/** A clear-with-margin option that shrinks the subject below this × its natural scale is rejected. */
 	minClearScale: 0.6,
+	/**
+	 * "Minimum disturbance": when growing toward a decisive bleed is capped short and the only way to
+	 * reach `minBleed` is to shift the subject down (away from the text), shrinking it to clear the
+	 * edge instead is preferred whenever that clear scale is still at least this × the (grown/capped)
+	 * bleed scale — shrinking by ≤ 12% to clear beats pushing the subject down and leaving a gap under
+	 * the text.
+	 */
+	clearOverShift: 0.88,
 	/** Below this × the layout's target scale the copy leaves no usable room (composeSet throws). */
 	minScale: 0.5
 } as const;
@@ -186,7 +194,7 @@ export interface VerticalInput {
 	/** See `focusReach`; null = no focus band marked (unconstrained). */
 	focusReach: number | null;
 	bleed: BleedPreference;
-	/** Tilted subjects: prefer a decisive bleed whenever one is possible (tilt is paired with a bleed). */
+	/** Tilted subjects: prefers a deeper bleed, but clears rather than leave a gap under the text. */
 	preferBleed?: boolean;
 	/** Hard upper bound on the scale (e.g. from the horizontal rules); applied to every option. */
 	scaleCap?: number;
@@ -212,18 +220,27 @@ export interface VerticalResult {
  * pushes the focus band off-canvas. Options:
  * - CLEAR: keep the near edge, shrink until the far edge clears with the margin.
  * - BLEED: grow (up to its size cap) toward the target overshoot; only when growth alone can't get
- *   there (the size cap bites first) does the subject shift toward the far edge, and then only far
- *   enough for a decisive (`minBleed`) overshoot — never further just to reach a deeper target, which
- *   would otherwise leave empty space between the text and the subject. If the result hides the focus
- *   band, the placement instead targets the smallest decisive bleed (`minBleed`) that stays focus-safe
- *   — or near0 itself, when near0 already sits further down than that — else the bleed option is
- *   unavailable.
+ *   there (the size cap bites first) does the subject need to shift toward the far edge to reach a
+ *   decisive (`minBleed`) overshoot. When that shift would itself stay focus-safe, "minimum
+ *   disturbance" is tried first: if shrinking the (grown/capped) subject back down clears the edge
+ *   with the margin and loses at most `1 − clearOverShift` of that scale, that clear placement
+ *   (sitting at near0, undisturbed) is used INSTEAD of shifting it down — see
+ *   `NO_TANGENT.clearOverShift`. Only when clearing would shrink it more than that (or the shift
+ *   wouldn't be focus-safe in the first place, so there's no real shift to prefer clearing over) does
+ *   it fall back to shifting down, and even then never further than `minBleed` needs — never all the
+ *   way to a deeper target, which would otherwise leave empty space between the text and the subject.
+ *   If the (shifted) result hides the focus band, the placement instead targets the smallest decisive
+ *   bleed (`minBleed`) that stays focus-safe — or near0 itself, when near0 already sits further down
+ *   than that — else the bleed option is unavailable.
  * `none` → always clear. `deep` → grow toward `deepBleed` (≥ `minBleed` at the width cap, ≥ `deepBleed`
- * whenever growth alone reaches it), or the most the focus allows, else clear.
+ * whenever growth alone reaches it, else the minimum-disturbance clear above), or the most the focus
+ * allows, else clear.
  * `auto` → keep the natural placement when it already clears by the margin or is a focus-safe
- * decisive bleed; otherwise (the tangent zone) PREFER the bleed option, and fall back to clear only
- * when every ≥ `minBleed` bleed would crop the focus band. `preferBleed` (tilt) also turns a natural
- * clear into a bleed.
+ * decisive bleed; otherwise (the tangent zone) PREFER the bleed option — or its minimum-disturbance
+ * clear, when a shallow shrink beats the shift a decisive bleed would need — and fall back to clear
+ * when no ≥ `minBleed` bleed keeps the focus band visible.
+ * `preferBleed` (tilt) also turns a natural clear into a bleed — or its minimum-disturbance clear, when
+ * the tilt's scale cap stops it from reaching a decisive bleed without a shift.
  */
 export function solveVertical(inp: VerticalInput): VerticalResult {
 	const W = inp.canvasWidth;
@@ -252,10 +269,17 @@ export function solveVertical(inp: VerticalInput): VerticalResult {
 	/**
 	 * Smallest move reaching overshoot ≥ t·height, then made focus-safe (null if impossible). Growing
 	 * the subject (up to its size cap — the width cap, or a tighter `scaleCap` when one binds) is
-	 * always tried first. Only when that growth is capped short of t does the subject shift toward the
-	 * far edge — and even then, only far enough for a decisive (`minBleed`) overshoot, never all the
-	 * way to t: a deeper target like `deepBleed` is something to grow toward, not something worth
-	 * shifting the subject away from the text to force.
+	 * always tried first. Only when that growth is capped short of t does the subject need to shift
+	 * toward the far edge to reach a decisive (`minBleed`) overshoot — and even then, only when that
+	 * shift would actually stay focus-safe, "minimum disturbance" is tried first: shrinking the grown
+	 * subject back down to clear the edge, if that only costs ≤ `1 − clearOverShift` of its scale,
+	 * beats shifting it away from the text. (When the shift itself wouldn't be focus-safe, there's no
+	 * real shift to prefer clearing over, so this is skipped — the focus-constrained fallback below
+	 * decides instead, exactly as it did before minimum disturbance existed.) Otherwise — clearing
+	 * would shrink it more than that, or no shift is possible to compare against — it shifts down, and
+	 * even then never further than `minBleed` needs, never all the way to t: a deeper target like
+	 * `deepBleed` is something to grow toward, not something worth shifting the subject away from the
+	 * text to force.
 	 */
 	const bleedOption = (t: number): VerticalResult | null => {
 		let s = s0;
@@ -263,7 +287,27 @@ export function solveVertical(inp: VerticalInput): VerticalResult {
 		if (overshoot(s, a) < t * s * eh - EPS) {
 			const need = (H - a) / ((1 - t) * eh);
 			s = Math.max(s0, Math.min(need, Math.max(sCap, s0)));
-			if (overshoot(s, a) < NO_TANGENT.minBleed * s * eh - EPS) a = H - s * eh * (1 - NO_TANGENT.minBleed);
+			if (overshoot(s, a) < NO_TANGENT.minBleed * s * eh - EPS) {
+				const shifted = H - s * eh * (1 - NO_TANGENT.minBleed);
+				// Minimum disturbance only competes with a shift that would actually work: if shifting
+				// down to `shifted` wouldn't even keep the focus band visible, there's no real shift
+				// alternative to prefer clearing over — let the focus-constrained path below (and its
+				// own reasons) decide instead, same as before minimum disturbance existed.
+				if (focusOk(s, shifted)) {
+					// Prefer shrinking to clear (undisturbed, at near0) over shifting the subject down,
+					// as long as that shrink is shallow (≤ 1 − clearOverShift of the bleed's own
+					// grown/capped scale) — a small shrink beats a gap-forcing down-shift.
+					const clear = clearOption();
+					if (clear && clear.scale >= NO_TANGENT.clearOverShift * s - EPS) {
+						const reason =
+							clear.scale < s0 - EPS
+								? `shrunk ${Math.round((1 - clear.scale / s0) * 100)}% to clear instead of shifting down for a bleed`
+								: 'clears the edge (preferred over shifting down for a bleed)';
+						return { ...clear, reason };
+					}
+				}
+				a = shifted;
+			}
 		}
 		const reason =
 			overshoot(s, a) >= t * s * eh - EPS
@@ -300,10 +344,12 @@ export function solveVertical(inp: VerticalInput): VerticalResult {
 	// auto
 	if (naturalClear && !inp.preferBleed) return make(s0, near0, 'natural placement clears the edge');
 	if (naturalBleed && focusOk(s0, near0)) return make(s0, near0, 'natural placement bleeds decisively');
-	// In the tangent zone (or a tilted subject): resolve by bleeding decisively. Clear-with-margin
-	// only when no ≥ minBleed bleed keeps the focus band visible.
+	// In the tangent zone (or a tilted subject): resolve by bleeding decisively — or its
+	// minimum-disturbance clear, when the size cap stops a decisive bleed without a shift.
+	// Clear-with-margin (the naturalClear fallback below) only when no ≥ minBleed bleed keeps the
+	// focus band visible.
 	const bleed = bleedOption(NO_TANGENT.minBleed);
-	if (bleed) return inp.preferBleed ? { ...bleed, reason: `${bleed.reason} (tilt pairs with a bleed)` } : bleed;
+	if (bleed) return inp.preferBleed && bleed.mode === 'bleed' ? { ...bleed, reason: `${bleed.reason} (tilt pairs with a bleed)` } : bleed;
 	if (naturalClear) return make(s0, near0, 'natural placement clears the edge');
 	return clearOption() ?? forcedClear();
 }

package/src/variants.ts

@@ -14,19 +14,22 @@ import type { Motif } from './decor';
  * Three DISTINCT art directions from one plan — Product Page Optimization test candidates, not tweaks
  * (shot-dsl 0.5.0):
  * - **A Brand Classic**: device frames on the vivid tonal brand palette; hero with the mascot + badge;
- *   callouts on the selling screens (explicit, else from a tight `focus`); an accent rhythm (every 4th screen text-bottom); shadows.
+ *   callouts on the selling screens by default (explicit, else from a tight `focus`; the input can
+ *   turn this off with `style.callouts: 'none'`); an accent rhythm (every 4th screen text-bottom); shadows.
  * - **B Clean Frameless**: pale tonal backgrounds with dark text; big full-width frameless
  *   screenshots bleeding deep off the bottom (a zoom card only where the plan marks an explicit
- *   `crop`); magnified callouts (explicit, else derived from a tight `focus`); hero with large type
- *   + the mascot.
+ *   `crop`); magnified callouts by default (explicit, else derived from a tight `focus`; same
+ *   `style.callouts: 'none'` opt-out as A); hero with large type + the mascot.
  * - **C Story Panorama**: the deep tonal palette as ONE continuous scene across triples/pairs of
  *   screens with a flowing motif (`style.panorama.decoration`, default `wave`), the mascot
- *   travelling across the seams, a tilted hero and deeper bleeds.
+ *   travelling across the seams, a tilted hero that prefers a deeper bleed (but clears rather than
+ *   leave a gap under the text).
  *
  * KEPT from the input (every concept): name (+ suffix), canvas size, copy (headline / subheadline /
  * badge), colours (headlineColor / subheadlineColor), `background`, `deviceId`, `screenshot`,
- * `focus`, `crop`, `callout`, per-screen `mascot`, `art`, and the style's `font` and `bleed`
- * preference (default `auto`; B and C use `deep` unless the input says `none`).
+ * `focus`, `crop`, `callout`, per-screen `mascot`, `art`, the style's `font`, its `bleed` preference
+ * (default `auto`; B and C use `deep` unless the input says `none`), and its `callouts` preference
+ * (default `auto` for A and B if the input doesn't set one explicitly; C is always `none`).
  *
  * BRAND COLOURS: `style.palette.colors` (the first is the base, a tonal palette's second is the
  * accent); without a palette, the first screen's background colour. Concepts then use
@@ -35,8 +38,10 @@ import type { Motif } from './decor';
  * OVERRIDDEN (the concept decides these):
  * - every screen's `layout` → `text-top` (one shared system; the hero and rhythm accents differ);
  * - per-screen `presentation` / `tilt` are dropped;
- * - `hero`, `rhythm`, `callouts`, `tilt`/`tiltScreens` and `panorama` are set per concept (C keeps the
- *   input's `panorama.spans` / `decoration` when given).
+ * - `hero`, `rhythm`, `tilt`/`tiltScreens` and `panorama` are set per concept (C keeps the input's
+ *   `panorama.spans` / `decoration` when given);
+ * - `callouts` is set per concept too, but only C's is fixed (`none`) regardless of the input — A and
+ *   B fall back to `auto` only when the input leaves `callouts` unset (see `baseStyle`).
  */
 export type VariantKey = 'A' | 'B' | 'C';
 
@@ -80,9 +85,14 @@ function tonal(plan: ComposePlan, tone: 'light' | 'vivid' | 'deep'): ComposePale
 	return { mode: 'tonal', colors: brand.accent ? [brand.base, brand.accent] : [brand.base], tone };
 }
 
+/**
+ * Style knobs every concept inherits from the input, defaulted the same way for all three: `bleed`
+ * (default `auto`), `font` (kept only if set), and `callouts` (default `auto`) — concepts that want a
+ * different `callouts` (currently only C, always `none`) set it explicitly afterwards, which wins.
+ */
 function baseStyle(plan: ComposePlan): ComposeStyle {
 	const style = plan.style;
-	const out: ComposeStyle = { bleed: style?.bleed ?? 'auto' };
+	const out: ComposeStyle = { bleed: style?.bleed ?? 'auto', callouts: style?.callouts ?? 'auto' };
 	if (style?.font) out.font = style.font;
 	return out;
 }
@@ -160,8 +170,7 @@ export function makeVariants(plan: ComposePlan): ComposeVariant[] {
 			presentation: 'device',
 			palette: tonal(plan, 'vivid'),
 			hero: hero(plan, { badge }),
-			rhythm: { every: VARIANT_RHYTHM_EVERY, treatment: 'text-bottom' },
-			callouts: 'auto'
+			rhythm: { every: VARIANT_RHYTHM_EVERY, treatment: 'text-bottom' }
 		},
 		screens: plan.screens.map(baseScreen)
 	});
@@ -175,8 +184,7 @@ export function makeVariants(plan: ComposePlan): ComposeVariant[] {
 			bleed: plan.style?.bleed === 'none' ? 'none' : 'deep',
 			presentation: 'frameless',
 			palette: tonal(plan, 'light'),
-			hero: hero(plan, { badge, scale: 1.3 }),
-			callouts: 'auto'
+			hero: hero(plan, { badge, scale: 1.3 })
 		},
 		screens: plan.screens.map((screen) => {
 			const s = baseScreen(screen);