@appshoteditor/shot-dsl 0.5.1 → 0.5.2

package/README.md

@@ -64,7 +64,9 @@ validateTemplate(template); // { valid: true, errors: [] }
      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%.
+   - `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.
 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.

package/package.json

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

@@ -295,6 +295,12 @@ export interface ComposeScreenMetrics {
 	headlineSize: number;
 	/** Headline box top ÷ H (identical across a set by construction). */
 	headlineTop: number;
+	/**
+	 * Bottom of the reserved text block (headline + subheadline + badge row) ÷ H. For `text-bottom`
+	 * layouts the text block sits near the canvas bottom (not the top), so `top − textBottom` (the
+	 * subject's top minus this) isn't a meaningful "gap under the text" for that layout.
+	 */
+	textBottom: number;
 	tilt: number;
 	/** Horizontal centre ÷ W (≠ 0.5 for a straddling panorama device). */
 	centerX: number;
@@ -2023,6 +2029,7 @@ export function composeSet(plan: ComposePlan): { template: Template; report: Com
 			tangent: inTangentZone(overshoot, p.boxHeight, H),
 			headlineSize: typo.headlineSize / W,
 			headlineTop: g.headlineTop / H,
+			textBottom: (g.areaTop + typo.textArea) / H,
 			tilt: p.angle,
 			centerX: cx / W,
 			role: r.role,

package/src/layout-system.ts

@@ -17,7 +17,11 @@ export const NO_TANGENT = {
 	clearGap: 0.04,
 	/** A subject that bleeds must lose at least this × its own (rotated) height. */
 	minBleed: 0.12,
-	/** `bleed: "deep"` target, × the subject's height. */
+	/**
+	 * `bleed: "deep"` target, × the subject's height. Reached by growing the subject (up to
+	 * `maxWidth`·W) — never by shifting it down past a decisive (`minBleed`) overshoot, since a
+	 * further down-shift would just be empty space between the text and the subject.
+	 */
 	deepBleed: 0.25,
 	/** The focus band must end at least this × H inside the canvas edge. */
 	focusSafe: 0.02,
@@ -207,10 +211,15 @@ export interface VerticalResult {
  * ≥ `clearGap`·H or bleeds by ≥ `minBleed` of the subject's height — never in between — and never
  * 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 `maxWidth`·W), then shift toward the far edge, until the overshoot reaches
- *   the target; if that hides the focus band, the largest focus-safe bleed ≥ `minBleed` is used,
- *   else the bleed option is unavailable.
- * `none` → always clear. `deep` → bleed ≥ `deepBleed` (or the most the focus allows), else clear.
+ * - 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.
+ * `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.
  * `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
@@ -240,24 +249,36 @@ export function solveVertical(inp: VerticalInput): VerticalResult {
 		return make(s, near0, s < s0 - EPS ? 'shrunk to clear the edge with a margin' : 'clears the edge');
 	};
 
-	/** Smallest move reaching overshoot ≥ t·height, then made focus-safe (null if impossible). */
+	/**
+	 * 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.
+	 */
 	const bleedOption = (t: number): VerticalResult | null => {
 		let s = s0;
 		let a = near0;
 		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) < t * s * eh - EPS) a = H - s * eh * (1 - t);
+			if (overshoot(s, a) < NO_TANGENT.minBleed * s * eh - EPS) a = H - s * eh * (1 - NO_TANGENT.minBleed);
 		}
-		if (focusOk(s, a)) return make(s, a, `bleeds ${Math.round(t * 100)}%+`);
+		const reason =
+			overshoot(s, a) >= t * s * eh - EPS
+				? `bleeds ${Math.round(t * 100)}%+`
+				: `grows to its size cap (no gap forced to reach ${Math.round(t * 100)}%+)`;
+		if (focusOk(s, a)) return make(s, a, reason);
 		// Focus-constrained: keep the scale (≤ what the focus allows at near0) and bleed only as deep
-		// as the focus band allows — accepted if that is still a decisive (≥ minBleed) bleed.
+		// as the focus band allows — accepted if that is still a decisive (≥ minBleed) bleed. The shift
+		// itself only ever targets minBleed (never t), for the same no-gap reason as above.
 		if (inp.focusReach == null) return null;
 		const fr = inp.focusReach;
 		const sF = Math.min(s, Math.max(sCap, s0), (focusLimit - near0) / fr);
 		const denom = eh * (1 - NO_TANGENT.minBleed) - fr;
 		if (!(sF > 0) || denom <= 0 || sF < (H - focusLimit) / denom - EPS) return null;
-		const aF = Math.max(near0, Math.min(focusLimit - sF * fr, H - sF * eh * (1 - t)));
+		const aF = Math.max(near0, Math.min(focusLimit - sF * fr, H - sF * eh * (1 - NO_TANGENT.minBleed)));
 		if (overshoot(sF, aF) < NO_TANGENT.minBleed * sF * eh - EPS || !focusOk(sF, aF)) return null;
 		return make(sF, aF, 'bleed reduced to keep the focus band visible');
 	};