@appshoteditor/shot-dsl 0.5.0 → 0.5.1

package/README.md

@@ -174,11 +174,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.1",
+  "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

@@ -397,7 +397,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 +420,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 +1051,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 +1071,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 +1601,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 };
 	}
@@ -2101,21 +2124,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 +2216,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 +2229,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,