@appshoteditor/shot-dsl 0.5.0 → 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.
@@ -174,11 +176,14 @@ Output shapes:
 - **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.
+  The requested crop is automatically padded, on whichever sides have room inside the screenshot,
+  before it's magnified, so the rounded corners of the card don't clip content sitting at the
+  requested crop's own corners (e.g. a selection handle); a side with no room (flush against the
+  screenshot edge) can still clip there. 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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@appshoteditor/shot-dsl",
-  "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.).",
+  "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",
   "main": "./src/index.ts",

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;
@@ -397,7 +403,8 @@ const BADGE_MAX_CHARS = 28;
 
 // Frameless / zoom styling.
 const FRAMELESS_WIDTH = 0.9; // × the layout's device width target (no bezel → a touch narrower)
-const FRAMELESS_RADIUS = 0.1; // × rendered width
+const FRAMELESS_RADIUS = 0.1; // × rendered width — fallback, and the cap for `frameCornerRadiusRatio`
+const FRAMELESS_RADIUS_MIN = 0.03; // × rendered width — floor for a device with squarer screen corners (e.g. iPad)
 const ZOOM_WIDTH = 0.88; // × W
 const ZOOM_RADIUS = 0.05; // × W
 const ZOOM_MIN_ASPECT = 0.5; // card height ≥ half its width
@@ -419,6 +426,15 @@ export const CALLOUT_MAG = { min: 1.6, max: 2.2, floor: 1.25 } as const;
  */
 export const CALLOUT_MAX_FOCUS_COVER = 0.35;
 const CALLOUT_RADIUS = 0.035; // × W
+/**
+ * Padding added around the requested callout crop (screenshot px), as a multiple of the rounded
+ * mask's LOCAL corner radius (`CALLOUT_RADIUS * W`, converted to the crop's own pixel space — see
+ * `calloutGeometry`), so the rounded corners of the clip mask (`makeCalloutLayer`) don't cut into
+ * content at the requested crop's own corners (e.g. selection handles). The geometric minimum to
+ * keep a corner point inside a rounded corner of radius `rx` is `1 - 1/√2 ≈ 0.293`; the extra margin
+ * covers the fact that padding the crop shrinks the eventual magnification a little further.
+ */
+const CALLOUT_CORNER_PAD = 0.35;
 // Auto crop: fractions of the screenshot width (left-aligned — UI rows start at the left, so a cut
 // at the right loses a chevron, not the first letters of a label); card h ÷ w.
 const CALLOUT_AUTO = { x: 0.02, w: 0.64, aspect: 0.4 };
@@ -1041,6 +1057,19 @@ function shadowFor(W: number, scale: number, look: Look, spec: { blur: number; o
 	return { color: look.shadowColor, blur: (spec.blur * W) / scale, offsetX: 0, offsetY: (spec.offsetY * W) / scale };
 }
 
+/**
+ * Non-zoom frameless corner radius, as a ratio of the rendered width: the device's own screen corner
+ * radius (relative to its screen width), clamped to [FRAMELESS_RADIUS_MIN, FRAMELESS_RADIUS]. A flat
+ * FRAMELESS_RADIUS reads fine on an iPhone (its screen corners are nearly that round) but is far too
+ * round on an iPad (squarer corners, wide screen) — round enough to eat into the status bar. Falls
+ * back to FRAMELESS_RADIUS when the device is unknown.
+ */
+function frameCornerRadiusRatio(deviceId: string): number {
+	const device = getDeviceFrame(deviceId);
+	if (!device) return FRAMELESS_RADIUS;
+	return Math.min(FRAMELESS_RADIUS, Math.max(FRAMELESS_RADIUS_MIN, device.cornerRadius / device.screenBounds.width));
+}
+
 /** Frameless / zoom subject: the uploaded screenshot as a plain image layer, rounded + shadowed. */
 function makeScreenshotImageLayer(r: ResolvedScreen, p: Placement, look: Look): LayerJSON {
 	const id = generateLayerId();
@@ -1048,7 +1077,7 @@ function makeScreenshotImageLayer(r: ResolvedScreen, p: Placement, look: Look):
 	const zoom = p.zoom;
 	const width = zoom ? zoom.cropW : shot.width;
 	const height = zoom ? zoom.cropH : shot.height;
-	const radius = zoom ? ZOOM_RADIUS * r.W : FRAMELESS_RADIUS * width * p.scale;
+	const radius = zoom ? ZOOM_RADIUS * r.W : frameCornerRadiusRatio(r.plan.deviceId) * width * p.scale;
 	const fabricData: Record<string, unknown> = {
 		type: 'image',
 		src: shot.url,
@@ -1578,7 +1607,7 @@ export function composeSet(plan: ComposePlan): { template: Template; report: Com
 		rects: TextRects;
 		text: string;
 		subText?: string;
-		callout?: { rect: Rect; mag: number; crop: { x: number; y: number; w: number; h: number }; scale: number; focusCover: number };
+		callout?: { rect: Rect; mag: number; crop: { x: number; y: number; w: number; h: number }; requested: { x: number; y: number; w: number; h: number }; scale: number; focusCover: number };
 		focusCore?: Rect;
 		mascot?: { rect: Rect; scale: number; flip: boolean; art: ComposeArt; seamPartner?: number; dx?: number };
 	}
@@ -2000,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,
@@ -2101,21 +2131,49 @@ function calloutGeometry(r: ResolvedScreen, p: Placement, cx: number, rects: Tex
 	const req = r.calloutReq!;
 	const { W, H } = r;
 	const shot = r.plan.screenshot;
-	const crop = { x: req.x * shot.width, y: req.y * shot.height, w: req.w * shot.width, h: req.h * shot.height };
+	const requested = { x: req.x * shot.width, y: req.y * shot.height, w: req.w * shot.width, h: req.h * shot.height };
 	const scr = p.subject.screen;
 	// Canvas px per screenshot px as the editor fits it into the screen bounds (frameless: the image).
 	const screenScale = (p.scale * scr.width) / shot.width;
-	const centre = subjectPointToCanvas(
-		p.subject,
-		{ x: scr.x + ((crop.x + crop.w / 2) / shot.width) * scr.width, y: scr.y + ((crop.y + crop.h / 2) / shot.height) * scr.height },
-		{ cx, cy: p.cy, scale: p.scale, angle: p.angle }
-	);
+	// Vertical band the card must fit in — computed before padding since it only depends on the text
+	// layout, not the crop, and the padding estimate below needs it too (the same vertical fit cap
+	// applies to both).
 	const texts = textRectList(rects);
 	const gap = CALLOUT_TEXT_GAP * H;
 	const [lo, hi] =
 		r.layout === 'text-bottom'
 			? [CALLOUT_EDGE * H, Math.min(...texts.map((t) => t.top)) - gap]
 			: [Math.max(...texts.map((t) => t.bottom)) + gap, H * (1 - CALLOUT_EDGE)];
+	// Pad the requested crop on sides that have room inside the screenshot, so its own corners land
+	// inside the rounded clip mask (`makeCalloutLayer`) instead of being cut off there. `pad` is sized
+	// from a PRELIMINARY magnification: the same formula AND the same fit caps (side margins, vertical
+	// room) used below, run on the unpadded crop — since the final mag depends on the padded crop's own
+	// size, this is a deterministic chicken-and-egg break, not the exact final mag. The placement
+	// search below can still shrink the final mag further (retrying smaller sizes when every position
+	// hides too much of the focus band), so `makeCalloutLayer` also hard-caps the mask's own corner
+	// radius as a backstop — the padding here just keeps that cap from binding in the common case.
+	const baseWReq = requested.w * screenScale;
+	const baseHReq = requested.h * screenScale;
+	let prelimMag = Math.min(CALLOUT_MAG.max, Math.max(CALLOUT_MAG.min, (CALLOUT_TARGET_WIDTH * W) / baseWReq));
+	prelimMag = Math.min(prelimMag, ((1 - 2 * CALLOUT_MARGIN) * W) / baseWReq, (hi - lo) / baseHReq);
+	// Guard against a degenerate (non-positive) estimate — e.g. no vertical room at all — blowing up
+	// `pad`; the real computation below bails out (`callout-skipped`) in that same case anyway, so the
+	// crop's exact shape no longer matters once that happens.
+	prelimMag = Math.max(prelimMag, 1e-6);
+	const pad = (CALLOUT_CORNER_PAD * CALLOUT_RADIUS * W) / (screenScale * prelimMag);
+	const padX0 = Math.max(0, requested.x - pad);
+	const padY0 = Math.max(0, requested.y - pad);
+	const crop = {
+		x: padX0,
+		y: padY0,
+		w: Math.min(shot.width, requested.x + requested.w + pad) - padX0,
+		h: Math.min(shot.height, requested.y + requested.h + pad) - padY0
+	};
+	const centre = subjectPointToCanvas(
+		p.subject,
+		{ x: scr.x + ((crop.x + crop.w / 2) / shot.width) * scr.width, y: scr.y + ((crop.y + crop.h / 2) / shot.height) * scr.height },
+		{ cx, cy: p.cy, scale: p.scale, angle: p.angle }
+	);
 	const baseW = crop.w * screenScale;
 	const baseH = crop.h * screenScale;
 	let mag = Math.min(CALLOUT_MAG.max, Math.max(CALLOUT_MAG.min, (CALLOUT_TARGET_WIDTH * W) / baseW));
@@ -2165,7 +2223,7 @@ function calloutGeometry(r: ResolvedScreen, p: Placement, cx: number, rects: Tex
 				}
 			}
 		}
-		if (bestRect) return { rect: bestRect, mag: k, crop, scale: screenScale * k, focusCover: cover(bestRect) };
+		if (bestRect) return { rect: bestRect, mag: k, crop, requested, scale: screenScale * k, focusCover: cover(bestRect) };
 		if (k <= CALLOUT_MAG.floor) break;
 	}
 	warnings.push({
@@ -2178,7 +2236,24 @@ function calloutGeometry(r: ResolvedScreen, p: Placement, cx: number, rects: Tex
 
 function makeCalloutLayer(r: ResolvedScreen, c: NonNullable<ReturnType<typeof calloutGeometry>>, look: Look): LayerJSON {
 	const id = generateLayerId();
-	const radius = CALLOUT_RADIUS * r.W;
+	// Hard guarantee, independent of how `calloutGeometry`'s padding estimate turned out (it's only a
+	// preliminary-magnification guess — the placement search can shrink the final mag further): the
+	// mask's corner radius can never clip the REQUESTED crop's own corners. On each side that had room
+	// to pad (not clamped flush to the screenshot edge — a clamped side had no padding and was always
+	// going to clip there, mask or no mask), the actual padding applied is the gap between `crop` and
+	// `requested`. The geometric minimum margin to keep a corner inside a rounded corner of local
+	// radius `rx` is `(1 − 1/√2) · rx`, so `rx` is capped at the smallest such padding ÷ (1 − 1/√2) —
+	// converted back to a canvas-unit radius via `c.scale`. If every side is clamped (the crop already
+	// spans the screenshot), there's no padding to guarantee anything from, so the normal radius stands.
+	const shot = r.plan.screenshot;
+	const EPS = 1e-6;
+	const pads: number[] = [];
+	if (c.crop.x > EPS) pads.push(c.requested.x - c.crop.x);
+	if (c.crop.y > EPS) pads.push(c.requested.y - c.crop.y);
+	if (c.crop.x + c.crop.w < shot.width - EPS) pads.push(c.crop.x + c.crop.w - (c.requested.x + c.requested.w));
+	if (c.crop.y + c.crop.h < shot.height - EPS) pads.push(c.crop.y + c.crop.h - (c.requested.y + c.requested.h));
+	const CORNER_INSET = 1 - 1 / Math.SQRT2; // ≈0.293 — geometric minimum margin to keep a corner inside a rounded corner of radius rx
+	const radius = pads.length ? Math.min(CALLOUT_RADIUS * r.W, (Math.min(...pads) / CORNER_INSET) * c.scale) : CALLOUT_RADIUS * r.W;
 	const fabricData: Record<string, unknown> = {
 		type: 'image',
 		src: r.plan.screenshot.url,

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');
 	};