shipseal 0.0.8 → 0.1.1

package/dist/cli.js

@@ -1,10 +1,9 @@
 #!/usr/bin/env node
 import { existsSync, readFileSync } from "node:fs";
-import { basename, dirname, extname, isAbsolute, join, relative } from "node:path";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { cac } from "cac";
-import { appendFile, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { appendFile, mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
 import { z } from "zod";
-import { createHash } from "node:crypto";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { fileURLToPath } from "node:url";
@@ -14,6 +13,8 @@ import { fromJsx } from "takumi-js/helpers/jsx";
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
 import { inflateSync } from "node:zlib";
+import { randomUUID } from "node:crypto";
+import { createServer } from "node:http";
 
 //#region src/core/errors.ts
 var ShipsealError = class extends Error {
@@ -62,7 +63,11 @@ const brandSchema = z.object({
 	}),
 	radius: z.number().nonnegative(),
 	theme: z.enum(["dark", "light"]),
-	style: z.literal("minimal"),
+	style: z.enum([
+		"minimal",
+		"editorial",
+		"terminal"
+	]),
 	tokens: z.string().nullable()
 });
 const DEFAULT_BRAND_COLORS = {
@@ -163,6 +168,12 @@ const FORMATS = {
 		safeZone: LANDSCAPE_SAFE_ZONE
 	}
 };
+const V1_FORMAT_IDS = [
+	"og",
+	"github-social",
+	"x",
+	"linkedin"
+];
 
 //#endregion
 //#region src/config/schema.ts
@@ -175,7 +186,19 @@ const configSchema = z.object({
 		templates: z.array(z.string()).optional(),
 		maxHighlights: z.number().int().positive().optional(),
 		changelogPath: z.string().optional(),
-		snippet: z.string().nullable().optional()
+		snippet: z.string().nullable().optional(),
+		announce: z.enum([
+			"major",
+			"minor",
+			"patch"
+		]).optional(),
+		headline: z.string().nullable().optional(),
+		subheadline: z.string().nullable().optional(),
+		story: z.object({
+			upgrade: z.string().max(4e3).optional(),
+			before: z.string().optional(),
+			after: z.string().optional()
+		}).refine((value) => Boolean(value.before) === Boolean(value.after), { message: "Supply both story.before and story.after screenshot paths, or neither." }).optional()
 	}).optional(),
 	milestones: z.object({
 		stars: z.array(z.number().int().positive()).optional(),
@@ -213,6 +236,7 @@ const DEFAULT_CONFIG = {
 		],
 		maxHighlights: 4,
 		changelogPath: "CHANGELOG.md",
+		announce: "patch",
 		snippet: null
 	},
 	milestones: {
@@ -301,18 +325,16 @@ const COPY_LIMITS = {
 
 //#endregion
 //#region src/copy/deterministic.ts
-function deterministicCopy(facts, maxHighlights = 4) {
+function deterministicCopy(facts, maxHighlights = 4, displayName) {
 	const name = facts.project.name.value;
 	const version = facts.release?.version.value;
 	const features = (facts.release?.features ?? []).map((item) => item.value);
 	const fixes = (facts.release?.fixes ?? []).map((item) => item.value);
 	const breaking = (facts.release?.breaking ?? []).map((item) => item.value);
-	const headline = [
-		...breaking,
-		...features,
-		...fixes
-	].map((line) => cleanLine(firstSentence(line))).find((line) => line.length <= HEADLINE_MAX_CHARS) ?? (version === void 0 ? name : `${name} ${version}`);
-	const tagline = facts.project.tagline?.value;
+	const headlineSource = [...breaking, ...features].map((line) => cleanLine(firstSentence(line))).find((line) => line.length <= HEADLINE_MAX_CHARS);
+	const title = displayName ?? name;
+	const headline = facts.release?.headline?.value ?? headlineSource ?? (version === void 0 ? title : `${title} ${version}`);
+	const tagline = facts.release?.subheadline?.value ?? facts.project.tagline?.value;
 	const subheadline = tagline !== void 0 && tagline.length > 0 ? cleanLine(tagline) : cleanLine(features[1] ?? fixes[1] ?? fixes[0] ?? `What's new in ${version ?? name}`);
 	const highlights = [];
 	const addHighlight = (line, prefix = "") => {
@@ -387,8 +409,22 @@ function firstSentence(text) {
 * sentences, and the fitting pass comfortably handles more.
 */
 const HEADLINE_MAX_CHARS = 72;
+/**
+* Emoji ranges, removed from anything that reaches a card.
+*
+* No font we register carries these glyphs, so `\u{1F310} Human-friendly ...` (got's real
+* GitHub description) rendered a tofu box on shipseal.dev. Takumi ships an emoji helper, but it
+* rewrites each emoji into an <img> pointing at jsDelivr, and `generate()` does no network.
+*
+* The ranges deliberately start at U+2600, which keeps the textual symbols people put in real
+* product names: (c) U+00A9, (r) U+00AE and (tm) U+2122 all sit below it.
+*/
+const EMOJI = /[\u{1F000}-\u{1FAFF}]|[\u{2600}-\u{27BF}]|[\u{FE00}-\u{FE0F}]|\u200D/gu;
+function stripEmoji(text) {
+	return text.replaceAll(EMOJI, "").replace(/\s+/g, " ").trim();
+}
 function cleanLine(text) {
-	const stripped = text.replace(/\s*\u2014\s*/g, ": ").replace(/\s+\u2013\s+/g, ", ").replaceAll("–", "-").replaceAll("!", ".").replace(/\s+/g, " ").trim();
+	const stripped = stripEmoji(text).replace(/\s*\u2014\s*/g, ": ").replace(/\s+\u2013\s+/g, ", ").replaceAll("–", "-").replaceAll("!", ".").replace(/\s+/g, " ").trim();
 	const noTrail = stripped.endsWith(".") ? stripped.slice(0, -1) : stripped;
 	const first = noTrail.at(0);
 	if (first === void 0) return noTrail;
@@ -396,7 +432,7 @@ function cleanLine(text) {
 }
 function ctaFor(facts) {
 	const npm = facts.project.npmPackage?.value;
-	if (npm !== void 0 && npm.length > 0) return `npm i ${npm}`;
+	if (npm !== void 0 && npm.length > 0) return facts.project.cli?.value === true ? `npx ${npm}@latest` : `npm i ${npm}`;
 	const url = facts.project.url?.value ?? facts.project.repo?.value;
 	if (url === void 0) return facts.project.name.value;
 	return url.replace(/^https?:\/\//, "");
@@ -551,7 +587,9 @@ const jsxs = jsx;
 
 //#endregion
 //#region src/templates/code-card.tsx
-const propsSchema$4 = z.object({
+/** Advance width of a monospace glyph as a fraction of the font size. */
+const MONO_ADVANCE = .6;
+const propsSchema$5 = z.object({
 	headline: z.string(),
 	headingFamily: z.string(),
 	monoFamily: z.string(),
@@ -567,7 +605,7 @@ const codeCard = {
 	id: "code-card",
 	events: ["release"],
 	formats: ["x", "linkedin"],
-	propsSchema: propsSchema$4,
+	propsSchema: propsSchema$5,
 	slots(format) {
 		return { headline: {
 			maxLines: 1,
@@ -578,10 +616,10 @@ const codeCard = {
 		} };
 	},
 	slotText(raw) {
-		return { headline: propsSchema$4.parse(raw).headline };
+		return { headline: propsSchema$5.parse(raw).headline };
 	},
 	slotFont(raw, slot) {
-		const props = propsSchema$4.parse(raw);
+		const props = propsSchema$5.parse(raw);
 		if (slot === "headline") return {
 			family: props.headingFamily,
 			weight: props.headingWeight,
@@ -615,10 +653,19 @@ const codeCard = {
 		};
 	},
 	render(raw, ctx) {
-		const props = propsSchema$4.parse(raw);
+		const props = propsSchema$5.parse(raw);
 		const colors = themeColors(ctx.brand, ctx.theme);
 		const pad = ctx.format.safeZone;
 		const headline = ctx.fitted.headline;
+		const boxPad = 28;
+		const lineHeight = 1.35;
+		const lines = props.lines.length === 0 ? 1 : props.lines.length;
+		const longest = Math.max(1, ...props.lines.map((line) => line.reduce((total, token) => total + token.text.length, 0)));
+		const headlineHeight = (headline?.fontSize ?? 36) * 1.25;
+		const attributionHeight = ctx.attribution ? 49.2 : 0;
+		const innerWidth = ctx.format.width - 2 * pad - 56;
+		const innerHeight = ctx.format.height - 2 * pad - headlineHeight - 24 - attributionHeight - 56;
+		const codeSize = Math.max(18, Math.min(44, Math.floor(Math.min(innerWidth / (longest * MONO_ADVANCE), innerHeight / (lines * lineHeight)))));
 		return /* @__PURE__ */ jsxs("div", {
 			style: {
 				display: "flex",
@@ -644,29 +691,36 @@ const codeCard = {
 						display: "flex",
 						flexDirection: "column",
 						flexGrow: 1,
-						backgroundColor: colors.card,
-						borderRadius: props.radius,
-						padding: 28,
-						gap: 0
+						justifyContent: "center"
 					},
-					children: props.lines.map((line, lineIndex) => /* @__PURE__ */ jsx("div", {
+					children: /* @__PURE__ */ jsx("div", {
 						style: {
 							display: "flex",
-							flexDirection: "row",
-							flexWrap: "nowrap"
+							flexDirection: "column",
+							backgroundColor: colors.card,
+							borderRadius: props.radius,
+							padding: boxPad,
+							gap: 0
 						},
-						children: line.map((token, tokenIndex) => /* @__PURE__ */ jsx("div", {
+						children: props.lines.map((line, lineIndex) => /* @__PURE__ */ jsx("div", {
 							style: {
-								fontFamily: props.monoFamily,
-								fontWeight: props.monoWeight,
-								fontSize: 22,
-								color: token.color,
-								whiteSpace: "pre",
-								lineHeight: 1.35
+								display: "flex",
+								flexDirection: "row",
+								flexWrap: "nowrap"
 							},
-							children: token.text
-						}, `${String(lineIndex)}-${String(tokenIndex)}`))
-					}, String(lineIndex)))
+							children: line.map((token, tokenIndex) => /* @__PURE__ */ jsx("div", {
+								style: {
+									fontFamily: props.monoFamily,
+									fontWeight: props.monoWeight,
+									fontSize: codeSize,
+									color: token.color,
+									whiteSpace: "pre",
+									lineHeight
+								},
+								children: token.text
+							}, `${String(lineIndex)}-${String(tokenIndex)}`))
+						}, String(lineIndex)))
+					})
 				}),
 				ctx.attribution ? /* @__PURE__ */ jsx("div", {
 					style: {
@@ -735,7 +789,7 @@ const rowSchema = z.object({
 	changeText: z.string(),
 	regression: z.boolean()
 });
-const propsSchema$3 = z.object({
+const propsSchema$4 = z.object({
 	title: z.string(),
 	note: z.string(),
 	rows: z.array(rowSchema),
@@ -749,7 +803,7 @@ const bench = {
 	id: "bench",
 	events: ["bench"],
 	formats: ["x", "linkedin"],
-	propsSchema: propsSchema$3,
+	propsSchema: propsSchema$4,
 	slots(format) {
 		const width = format.width - 2 * format.safeZone;
 		const slots = { title: {
@@ -769,7 +823,7 @@ const bench = {
 		return slots;
 	},
 	slotText(raw) {
-		const props = propsSchema$3.parse(raw);
+		const props = propsSchema$4.parse(raw);
 		const text = { title: props.title };
 		props.rows.forEach((row, index) => {
 			text[`change-${String(index)}`] = row.changeText;
@@ -777,7 +831,7 @@ const bench = {
 		return text;
 	},
 	slotFont(raw, slot) {
-		const props = propsSchema$3.parse(raw);
+		const props = propsSchema$4.parse(raw);
 		if (slot === "title") return {
 			family: props.headingFamily,
 			weight: props.headingWeight,
@@ -820,7 +874,7 @@ const bench = {
 		};
 	},
 	render(raw, ctx) {
-		const props = propsSchema$3.parse(raw);
+		const props = propsSchema$4.parse(raw);
 		const colors = themeColors(ctx.brand, ctx.theme);
 		const pad = ctx.format.safeZone;
 		const title = ctx.fitted.title;
@@ -952,7 +1006,7 @@ function formatMetric(value) {
 
 //#endregion
 //#region src/templates/milestone.tsx
-const propsSchema$2 = z.object({
+const propsSchema$3 = z.object({
 	name: z.string(),
 	numberText: z.string(),
 	metricLabel: z.string(),
@@ -972,7 +1026,7 @@ const milestone = {
 		"x",
 		"linkedin"
 	],
-	propsSchema: propsSchema$2,
+	propsSchema: propsSchema$3,
 	slots(format) {
 		const width = format.width - 2 * format.safeZone;
 		return {
@@ -993,14 +1047,14 @@ const milestone = {
 		};
 	},
 	slotText(raw) {
-		const props = propsSchema$2.parse(raw);
+		const props = propsSchema$3.parse(raw);
 		return {
 			number: props.numberText,
 			thankYou: props.thankYou
 		};
 	},
 	slotFont(raw, slot) {
-		const props = propsSchema$2.parse(raw);
+		const props = propsSchema$3.parse(raw);
 		if (slot === "number") return {
 			family: props.headingFamily,
 			weight: props.headingWeight,
@@ -1044,7 +1098,7 @@ const milestone = {
 		};
 	},
 	render(raw, ctx) {
-		const props = propsSchema$2.parse(raw);
+		const props = propsSchema$3.parse(raw);
 		const colors = themeColors(ctx.brand, ctx.theme);
 		const pad = ctx.format.safeZone;
 		const number = ctx.fitted.number;
@@ -1138,9 +1192,39 @@ const milestone = {
 	}
 };
 
+//#endregion
+//#region src/templates/primitives/seal.ts
+/**
+* The core promise, made visible on the card.
+*
+* "sealed · 7 commits · 2026-09-11" turns "every number has a source" from a claim on the
+* website into a mark in the feed. Every segment is a fact, so rule 1 holds: a missing fact
+* drops its segment and is reported, it never becomes a placeholder or an estimate.
+*/
+function sealStamp(facts) {
+	const segments = ["sealed"];
+	const missing = [];
+	const commits = facts.release?.commitCount?.value;
+	if (commits === void 0) missing.push({
+		fact: "release.commitCount",
+		effect: "seal stamp omits the commit count"
+	});
+	else segments.push(`${formatCount$1(commits)} ${commits === 1 ? "commit" : "commits"}`);
+	const date = facts.release?.date?.value;
+	if (date === void 0) missing.push({
+		fact: "release.date",
+		effect: "seal stamp omits the date"
+	});
+	else segments.push(date);
+	return {
+		segments,
+		missing
+	};
+}
+
 //#endregion
 //#region src/templates/release-hero.tsx
-const propsSchema$1 = z.object({
+const propsSchema$2 = z.object({
 	name: z.string(),
 	version: z.string(),
 	headline: z.string(),
@@ -1152,7 +1236,8 @@ const propsSchema$1 = z.object({
 	bodyWeight: z.number(),
 	radius: z.number(),
 	showCta: z.boolean(),
-	showLogo: z.boolean()
+	showLogo: z.boolean(),
+	seal: z.array(z.string())
 });
 const releaseHero = {
 	id: "release-hero",
@@ -1163,7 +1248,7 @@ const releaseHero = {
 		"x",
 		"linkedin"
 	],
-	propsSchema: propsSchema$1,
+	propsSchema: propsSchema$2,
 	slots(format) {
 		const width = format.width - 2 * format.safeZone;
 		return {
@@ -1191,7 +1276,7 @@ const releaseHero = {
 		};
 	},
 	slotText(raw) {
-		const props = propsSchema$1.parse(raw);
+		const props = propsSchema$2.parse(raw);
 		return {
 			headline: props.headline,
 			subheadline: props.subheadline,
@@ -1199,7 +1284,7 @@ const releaseHero = {
 		};
 	},
 	slotFont(raw, slot) {
-		const props = propsSchema$1.parse(raw);
+		const props = propsSchema$2.parse(raw);
 		if (slot === "headline") return {
 			family: props.headingFamily,
 			weight: props.headingWeight,
@@ -1222,6 +1307,8 @@ const releaseHero = {
 			fact: "brand.logo",
 			effect: "logo hidden"
 		});
+		const seal = sealStamp(facts);
+		missing.push(...seal.missing);
 		const version = facts.release?.version.value ?? "";
 		return {
 			props: {
@@ -1236,13 +1323,14 @@ const releaseHero = {
 				bodyWeight: brand.fonts.body.weight,
 				radius: brand.radius,
 				showCta: copy.cta.length > 0,
+				seal: seal.segments,
 				showLogo
 			},
 			missing
 		};
 	},
 	render(raw, ctx) {
-		const props = propsSchema$1.parse(raw);
+		const props = propsSchema$2.parse(raw);
 		const colors = themeColors(ctx.brand, ctx.theme);
 		const pad = ctx.format.safeZone;
 		const headline = ctx.fitted.headline;
@@ -1257,9 +1345,24 @@ const releaseHero = {
 				width: "100%",
 				height: "100%",
 				backgroundColor: colors.background,
-				padding: pad
+				padding: pad,
+				position: "relative"
 			},
 			children: [
+				props.showLogo && ctx.logoSrc !== void 0 ? /* @__PURE__ */ jsx("div", {
+					style: {
+						display: "flex",
+						position: "absolute",
+						right: -Math.round(ctx.format.height * .12),
+						top: Math.round(ctx.format.height * .18),
+						opacity: .06
+					},
+					children: /* @__PURE__ */ jsx("img", {
+						src: ctx.logoSrc,
+						width: Math.round(ctx.format.height * .72),
+						height: Math.round(ctx.format.height * .72)
+					})
+				}) : void 0,
 				/* @__PURE__ */ jsxs("div", {
 					style: {
 						display: "flex",
@@ -1301,7 +1404,7 @@ const releaseHero = {
 									fontFamily: props.bodyFamily,
 									fontWeight: props.bodyWeight,
 									fontSize: 22,
-									color: colors.primary
+									color: colors.foreground
 								},
 								children: `v${props.version}`
 							})
@@ -1360,15 +1463,31 @@ const releaseHero = {
 							},
 							children: cta?.text ?? props.cta
 						})
-					}) : /* @__PURE__ */ jsx("div", {}), ctx.attribution ? /* @__PURE__ */ jsx("div", {
+					}) : /* @__PURE__ */ jsx("div", {}), /* @__PURE__ */ jsxs("div", {
 						style: {
-							fontFamily: props.bodyFamily,
-							fontWeight: props.bodyWeight,
-							fontSize: 18,
-							color: colors.muted
+							display: "flex",
+							flexDirection: "column",
+							alignItems: "flex-end",
+							gap: 6
 						},
-						children: "made with shipseal.dev"
-					}) : void 0]
+						children: [/* @__PURE__ */ jsx("div", {
+							style: {
+								fontFamily: props.bodyFamily,
+								fontWeight: props.headingWeight,
+								fontSize: 20,
+								color: colors.primary
+							},
+							children: props.seal.join("  ·  ")
+						}), ctx.attribution ? /* @__PURE__ */ jsx("div", {
+							style: {
+								fontFamily: props.bodyFamily,
+								fontWeight: props.bodyWeight,
+								fontSize: 18,
+								color: colors.muted
+							},
+							children: "made with shipseal.dev"
+						}) : void 0]
+					})]
 				})
 			]
 		});
@@ -1377,7 +1496,7 @@ const releaseHero = {
 
 //#endregion
 //#region src/templates/release-highlights.tsx
-const propsSchema = z.object({
+const propsSchema$1 = z.object({
 	name: z.string(),
 	version: z.string(),
 	highlights: z.array(z.string()),
@@ -1391,7 +1510,7 @@ const releaseHighlights = {
 	id: "release-highlights",
 	events: ["release"],
 	formats: ["x", "linkedin"],
-	propsSchema,
+	propsSchema: propsSchema$1,
 	slots(format) {
 		const width = format.width - 2 * format.safeZone - 48;
 		const slots = {};
@@ -1405,7 +1524,7 @@ const releaseHighlights = {
 		return slots;
 	},
 	slotText(raw) {
-		const props = propsSchema.parse(raw);
+		const props = propsSchema$1.parse(raw);
 		const text = {};
 		props.highlights.forEach((line, index) => {
 			text[`highlight-${String(index)}`] = line;
@@ -1413,7 +1532,7 @@ const releaseHighlights = {
 		return text;
 	},
 	slotFont(raw) {
-		const props = propsSchema.parse(raw);
+		const props = propsSchema$1.parse(raw);
 		return {
 			family: props.bodyFamily,
 			weight: props.bodyWeight,
@@ -1441,7 +1560,7 @@ const releaseHighlights = {
 		};
 	},
 	render(raw, ctx) {
-		const props = propsSchema.parse(raw);
+		const props = propsSchema$1.parse(raw);
 		const colors = themeColors(ctx.brand, ctx.theme);
 		const pad = ctx.format.safeZone;
 		const title = props.version.length > 0 ? `What's new in v${props.version}` : "What's new";
@@ -1535,6 +1654,413 @@ const releaseHighlights = {
 	}
 };
 
+//#endregion
+//#region src/facts/schema.ts
+const SOURCE_IDS = [
+	"git",
+	"package-json",
+	"readme",
+	"changelog",
+	"github-api",
+	"npm-api",
+	"bench-file",
+	"user-config",
+	"brand"
+];
+const sourceIdSchema = z.enum(SOURCE_IDS);
+const provenanceSchema = z.object({
+	source: sourceIdSchema,
+	ref: z.string().min(1),
+	fetchedAt: z.iso.datetime()
+});
+function factSchema(valueSchema) {
+	return z.object({
+		value: valueSchema,
+		provenance: provenanceSchema
+	});
+}
+const stringFact = factSchema(z.string());
+const numberFact = factSchema(z.number());
+const stringListFact = factSchema(z.array(z.string()));
+const codeSnippetFact = factSchema(z.object({
+	code: z.string(),
+	lang: z.string()
+}));
+const betterFact = factSchema(z.enum(["lower", "higher"]));
+const storyPageSchema = z.object({
+	kind: z.enum([
+		"cover",
+		"change",
+		"code",
+		"comparison",
+		"upgrade"
+	]),
+	title: stringFact,
+	body: stringFact,
+	before: stringFact.optional(),
+	after: stringFact.optional()
+});
+const factsSchema = z.object({
+	story: z.array(storyPageSchema).optional(),
+	project: z.object({
+		name: stringFact,
+		tagline: stringFact.optional(),
+		url: stringFact.optional(),
+		repo: stringFact.optional(),
+		npmPackage: stringFact.optional(),
+		cli: factSchema(z.boolean()).optional(),
+		license: stringFact.optional()
+	}),
+	release: z.object({
+		version: stringFact,
+		tag: stringFact,
+		kind: factSchema(z.enum([
+			"major",
+			"minor",
+			"patch"
+		])).optional(),
+		headline: stringFact.optional(),
+		subheadline: stringFact.optional(),
+		previousVersion: stringFact.optional(),
+		date: stringFact,
+		features: z.array(stringFact),
+		fixes: z.array(stringFact),
+		breaking: z.array(stringFact),
+		commitCount: numberFact.optional(),
+		contributors: stringListFact.optional(),
+		codeSnippet: codeSnippetFact.optional()
+	}).optional(),
+	metrics: z.object({
+		stars: numberFact.optional(),
+		weeklyDownloads: numberFact.optional(),
+		contributorCount: numberFact.optional()
+	}).optional(),
+	bench: z.object({
+		title: stringFact,
+		metrics: z.array(z.object({
+			label: stringFact,
+			before: numberFact,
+			after: numberFact,
+			unit: stringFact,
+			better: betterFact
+		})),
+		note: stringFact.optional()
+	}).optional(),
+	milestone: z.object({
+		metric: stringFact,
+		threshold: numberFact
+	}).optional()
+});
+
+//#endregion
+//#region src/templates/story-page.tsx
+const propsSchema = z.object({
+	page: storyPageSchema,
+	name: z.string(),
+	version: z.string(),
+	heading: z.string(),
+	body: z.string(),
+	mono: z.string(),
+	weight: z.number()
+});
+const HEADER_HEIGHT = 36;
+const BODY_PAD = 24;
+const CODE_LINE_HEIGHT = 1.35;
+const CODE_MIN_FONT_SIZE = 14;
+const FOOTER_ALLOWANCE = 144;
+const TALL_THRESHOLD = 900;
+function geometry(format) {
+	const tall = format.height > TALL_THRESHOLD;
+	const titleHeight = tall ? 220 : 112;
+	return {
+		tall,
+		titleHeight,
+		width: format.width - 2 * format.safeZone,
+		bodyHeight: format.height - 2 * format.safeZone - titleHeight - FOOTER_ALLOWANCE
+	};
+}
+const NO_BORDER = "0px solid transparent";
+/**
+* Monospace `pre` text does not wrap, so the generic line-count fitter cannot keep it inside
+* the card: it reports two lines that fit and the long one runs off the right edge. Mono
+* glyphs are a constant fraction of the em, so the widest line gives a size directly. Same
+* approach as code-card, which is why MONO_ADVANCE is shared rather than copied.
+*/
+function codeFontSize(text, box, max) {
+	const lines = text.split("\n");
+	const longest = Math.max(1, ...lines.map((line) => line.length));
+	const byWidth = box.width / (longest * MONO_ADVANCE);
+	const byHeight = box.height / (lines.length * CODE_LINE_HEIGHT);
+	return Math.max(CODE_MIN_FONT_SIZE, Math.min(max, Math.floor(Math.min(byWidth, byHeight))));
+}
+/**
+* A body the reader is meant to copy and run: a code snippet, or upgrade instructions the
+* maintainer supplied. Generated upgrade prose (a link to the release notes) is not one, so
+* the provenance decides rather than the page kind alone.
+*/
+function isCommand(page) {
+	return page.kind === "code" || page.kind === "upgrade" && page.body.provenance.source === "user-config";
+}
+const storyPage = {
+	id: "story-page",
+	events: ["release"],
+	formats: [
+		"og",
+		"github-social",
+		"x",
+		"linkedin",
+		"square",
+		"portrait",
+		"producthunt"
+	],
+	propsSchema,
+	slots(format) {
+		const { width, titleHeight, bodyHeight, tall } = geometry(format);
+		return {
+			name: {
+				maxLines: 1,
+				maxFontSize: 24,
+				minFontSize: 18,
+				step: 2,
+				box: { width: width - 300 }
+			},
+			version: {
+				maxLines: 1,
+				maxFontSize: 22,
+				minFontSize: 16,
+				step: 2,
+				box: { width: 220 }
+			},
+			title: {
+				maxLines: tall ? 3 : 2,
+				maxFontSize: tall ? 64 : 48,
+				minFontSize: tall ? 36 : 30,
+				step: 2,
+				box: {
+					width: width - 32,
+					height: titleHeight
+				}
+			},
+			body: {
+				maxLines: Math.floor(bodyHeight / 30),
+				maxFontSize: tall ? 34 : 28,
+				minFontSize: 20,
+				step: 2,
+				box: {
+					width: width - 48,
+					height: bodyHeight - 48
+				}
+			}
+		};
+	},
+	slotText(raw) {
+		const props = propsSchema.parse(raw);
+		return {
+			name: props.name,
+			version: props.version,
+			title: props.page.title.value,
+			body: props.page.body.value
+		};
+	},
+	slotFont(raw, slot) {
+		const props = propsSchema.parse(raw);
+		const mono = slot === "body" && isCommand(props.page);
+		return {
+			family: mono ? props.mono : slot === "title" ? props.heading : props.body,
+			weight: slot === "title" ? props.weight : 400,
+			lineHeight: mono ? 1.35 : 1.2,
+			whiteSpace: mono ? "pre" : "normal"
+		};
+	},
+	buildProps(facts, _copy, brand) {
+		const page = facts.story?.[0];
+		if (page === void 0) throw new ShipsealError("story-page.no-page", "The story-page template has no story page to render.", "Run shipseal story to build a story pack. Do not list story-page in release.templates.");
+		return {
+			props: {
+				page,
+				name: brand.name,
+				version: facts.release?.tag.value ?? "",
+				heading: brand.style === "terminal" ? brand.fonts.mono.family : brand.fonts.heading.family,
+				body: brand.fonts.body.family,
+				mono: brand.fonts.mono.family,
+				weight: brand.fonts.heading.weight
+			},
+			missing: []
+		};
+	},
+	render(raw, ctx) {
+		const props = propsSchema.parse(raw);
+		const colors = themeColors(ctx.brand, ctx.theme);
+		const { tall, bodyHeight, width } = geometry(ctx.format);
+		const editorial = ctx.brand.style === "editorial";
+		const terminal = ctx.brand.style === "terminal";
+		const code = isCommand(props.page);
+		const comparison = props.page.kind === "comparison";
+		const title = ctx.fitted.title;
+		const body = ctx.fitted.body;
+		const hasBody = props.page.body.value.trim().length > 0;
+		const bodyText = body?.text ?? props.page.body.value;
+		const bodyFontSize = code ? codeFontSize(bodyText, {
+			width: width - 48,
+			height: bodyHeight - 48
+		}, tall ? 34 : 28) : body?.fontSize ?? 28;
+		const paneWidth = tall ? width : (width - 16) / 2;
+		const paneHeight = tall ? (bodyHeight - 16) / 2 : bodyHeight;
+		return /* @__PURE__ */ jsxs("div", {
+			style: {
+				display: "flex",
+				flexDirection: "column",
+				width: "100%",
+				height: "100%",
+				backgroundColor: colors.background,
+				color: colors.foreground,
+				padding: ctx.format.safeZone,
+				gap: 24,
+				borderTop: editorial ? `16px solid ${colors.primary}` : NO_BORDER
+			},
+			children: [
+				/* @__PURE__ */ jsxs("div", {
+					style: {
+						display: "flex",
+						justifyContent: "space-between",
+						alignItems: "center",
+						height: HEADER_HEIGHT,
+						flexShrink: 0,
+						borderBottom: terminal ? `1px solid ${colors.muted}` : NO_BORDER,
+						paddingBottom: terminal ? 12 : 0
+					},
+					children: [/* @__PURE__ */ jsxs("div", {
+						style: {
+							display: "flex",
+							gap: 12,
+							alignItems: "center"
+						},
+						children: [ctx.logoSrc !== void 0 ? /* @__PURE__ */ jsx("img", {
+							src: ctx.logoSrc,
+							width: 32,
+							height: 32
+						}) : void 0, /* @__PURE__ */ jsx("div", {
+							style: {
+								fontFamily: terminal ? props.mono : props.body,
+								fontWeight: 400,
+								fontSize: ctx.fitted.name?.fontSize ?? 24,
+								color: colors.primary
+							},
+							children: ctx.fitted.name?.text ?? props.name
+						})]
+					}), /* @__PURE__ */ jsx("div", {
+						style: {
+							fontFamily: props.mono,
+							fontWeight: 400,
+							fontSize: ctx.fitted.version?.fontSize ?? 22,
+							color: colors.muted
+						},
+						children: ctx.fitted.version?.text ?? props.version
+					})]
+				}),
+				/* @__PURE__ */ jsxs("div", {
+					style: {
+						display: "flex",
+						flexDirection: "column",
+						flexGrow: 1,
+						justifyContent: "center",
+						gap: 24,
+						minHeight: 0
+					},
+					children: [/* @__PURE__ */ jsx("div", {
+						style: {
+							display: "flex",
+							alignItems: "center",
+							flexShrink: 0,
+							paddingLeft: editorial ? 24 : 0,
+							borderLeft: editorial ? `8px solid ${colors.primary}` : NO_BORDER
+						},
+						children: /* @__PURE__ */ jsx("div", {
+							style: {
+								fontFamily: props.heading,
+								fontWeight: props.weight,
+								fontSize: title?.fontSize ?? 48,
+								lineHeight: 1.2,
+								maxWidth: width - (editorial ? 32 : 0)
+							},
+							children: title?.text ?? props.page.title.value
+						})
+					}), comparison ? /* @__PURE__ */ jsx("div", {
+						style: {
+							display: "flex",
+							flexDirection: tall ? "column" : "row",
+							gap: 16,
+							height: bodyHeight
+						},
+						children: ["before", "after"].map((label) => /* @__PURE__ */ jsxs("div", {
+							style: {
+								display: "flex",
+								flexDirection: "column",
+								gap: 8,
+								width: paneWidth,
+								height: paneHeight
+							},
+							children: [/* @__PURE__ */ jsx("div", {
+								style: {
+									fontFamily: props.body,
+									fontSize: 20,
+									color: colors.muted
+								},
+								children: label === "before" ? "Before" : "After"
+							}), /* @__PURE__ */ jsx("img", {
+								src: `story-${label}`,
+								width: paneWidth,
+								height: paneHeight - HEADER_HEIGHT,
+								style: { objectFit: "contain" }
+							})]
+						}, label))
+					}) : hasBody ? /* @__PURE__ */ jsx("div", {
+						style: {
+							display: "flex",
+							flexDirection: "column",
+							justifyContent: "flex-start",
+							maxHeight: bodyHeight,
+							padding: terminal || code ? BODY_PAD : 0,
+							backgroundColor: terminal || code ? colors.card : "transparent",
+							borderRadius: terminal ? 0 : ctx.brand.radius,
+							borderLeft: terminal ? `3px solid ${colors.primary}` : NO_BORDER
+						},
+						children: /* @__PURE__ */ jsx("div", {
+							style: {
+								fontFamily: code ? props.mono : props.body,
+								fontWeight: 400,
+								fontSize: bodyFontSize,
+								lineHeight: code ? CODE_LINE_HEIGHT : 1.2,
+								whiteSpace: code ? "pre" : "normal",
+								color: colors.foreground
+							},
+							children: bodyText
+						})
+					}) : void 0]
+				}),
+				/* @__PURE__ */ jsxs("div", {
+					style: {
+						display: "flex",
+						justifyContent: "space-between",
+						flexShrink: 0,
+						fontFamily: props.mono,
+						fontWeight: 400,
+						fontSize: 16,
+						color: colors.muted
+					},
+					children: [/* @__PURE__ */ jsx("div", {
+						style: { fontFamily: props.mono },
+						children: comparison ? "Supplied screenshots" : "Sources in manifest.json"
+					}), ctx.attribution ? /* @__PURE__ */ jsx("div", {
+						style: { fontFamily: props.mono },
+						children: "made with shipseal.dev"
+					}) : void 0]
+				})
+			]
+		});
+	}
+};
+
 //#endregion
 //#region src/templates/registry.ts
 const templates = [
@@ -1542,7 +2068,8 @@ const templates = [
 	releaseHighlights,
 	codeCard,
 	milestone,
-	bench
+	bench,
+	storyPage
 ];
 function getTemplate(id) {
 	const found = templates.find((template) => template.id === id);
@@ -1552,6 +2079,14 @@ function getTemplate(id) {
 
 //#endregion
 //#region src/core/generate.ts
+/**
+* Digest via WebCrypto, not `node:crypto`. The browser demo imports `generate()`, so nothing
+* in the pure core may reach for a Node builtin. Do not "simplify" this back to createHash.
+*/
+async function sha256Hex(bytes) {
+	const digest = await crypto.subtle.digest("SHA-256", Uint8Array.from(bytes));
+	return Array.from(new Uint8Array(digest)).map((value) => value.toString(16).padStart(2, "0")).join("");
+}
 async function generate(input) {
 	const templateIds = templateIdsFor(input.event, input.config);
 	const formatIds = input.config.formats ?? [
@@ -1613,8 +2148,10 @@ async function generate(input) {
 					src: "shipseal-logo",
 					data: logo
 				}];
+				if (input.images !== void 0) renderOpts.images = [...renderOpts.images ?? [], ...input.images];
 				const bytes = await input.renderer.render(node, renderOpts);
 				const fileName = outputName(template.id, formatId, theme, omitThemeSuffix, imageFormat);
+				const sha256 = await sha256Hex(bytes);
 				files.push({
 					fileName,
 					template: template.id,
@@ -1623,7 +2160,7 @@ async function generate(input) {
 					width: format.width,
 					height: format.height,
 					bytes,
-					sha256: createHash("sha256").update(bytes).digest("hex")
+					sha256
 				});
 			}
 		}
@@ -1745,6 +2282,7 @@ function mergeFacts(parts) {
 	if (project.url !== void 0) facts.project.url = project.url;
 	if (project.repo !== void 0) facts.project.repo = project.repo;
 	if (project.npmPackage !== void 0) facts.project.npmPackage = project.npmPackage;
+	if (project.cli !== void 0) facts.project.cli = project.cli;
 	if (project.license !== void 0) facts.project.license = project.license;
 	if (isCompleteRelease(release)) {
 		facts.release = {
@@ -1755,6 +2293,9 @@ function mergeFacts(parts) {
 			fixes: release.fixes ?? [],
 			breaking: release.breaking ?? []
 		};
+		if (release.kind !== void 0) facts.release.kind = release.kind;
+		if (release.headline !== void 0) facts.release.headline = release.headline;
+		if (release.subheadline !== void 0) facts.release.subheadline = release.subheadline;
 		if (release.previousVersion !== void 0) facts.release.previousVersion = release.previousVersion;
 		if (release.commitCount !== void 0) facts.release.commitCount = release.commitCount;
 		if (release.contributors !== void 0) facts.release.contributors = release.contributors;
@@ -1890,7 +2431,7 @@ async function collectReadme(cwd) {
 		ref: "README.md H1",
 		fetchedAt
 	});
-	if (tagline !== void 0) project.tagline = fact(tagline, {
+	if (tagline !== void 0) project.tagline = fact(stripEmoji(tagline), {
 		source: "readme",
 		ref: "README.md first paragraph",
 		fetchedAt
@@ -2028,6 +2569,17 @@ async function collectChangelog(cwd, version, changelogPath = "CHANGELOG.md") {
 		fixes,
 		breaking
 	} };
+	for (const slot of ["headline", "subheadline"]) {
+		const text = new RegExp(`<!--\\s*shipseal:\\s*${slot}\\s+"([^"]+)"\\s*-->`).exec(section.body)?.[1]?.trim();
+		if (text !== void 0 && text.length > 0) out.release = {
+			...out.release,
+			[slot]: fact(text, {
+				source: "user-config",
+				ref: `${changelogPath} ${section.heading} shipseal:${slot} marker`,
+				fetchedAt
+			})
+		};
+	}
 	const snippet = extractFirstCodeFence(section.body);
 	if (snippet !== void 0) out.release = {
 		...out.release,
@@ -2071,7 +2623,7 @@ function findVersionSection(markdown, version) {
 	}
 }
 function cleanChangelogItem(item) {
-	return item.replace(/^\s*[-*]\s*/, "").replace(/\[`[a-f0-9]{7,40}`]\([^)]+\)/gi, "").replace(/^[a-f0-9]{7,40}:\s*/i, "").replace(/\(#\d+\)/g, "").replace(/\[#\d+]\([^)]+\)/g, "").replace(/Thanks\s+\[@[\w-]+]\([^)]+\)!?\s*-?\s*/gi, "").replace(/\[@[\w-]+]\([^)]+\)/g, "").replace(/\(@[\w-]+\)/g, "").replace(/\s+by\s+@[\w-]+/gi, "").replace(/@[\w-]+/g, "").replace(/^Thanks\s*!?\s*-?\s*/i, "").replace(/^\s*[-*]\s*/, "").replace(/\s+/g, " ").trim().replace(/\.$/, "");
+	return item.replace(/^\s*[-*]\s*/, "").replace(/\[`[a-f0-9]{7,40}`]\([^)]+\)/gi, "").replace(/^[a-f0-9]{7,40}:\s*/i, "").replace(/\(#\d+\)/g, "").replace(/\[#\d+]\([^)]+\)/g, "").replace(/Thanks\s+\[@[\w-]+]\([^)]+\)!?\s*-?\s*/gi, "").replace(/\[@[\w-]+]\([^)]+\)/g, "").replace(/\(@[\w-]+\)/g, "").replace(/\s+by\s+@[\w-]+/gi, "").replace(/@[\w-]+/g, "").replace(/^Thanks\s*!?\s*-?\s*/i, "").replace(/^\s*[-*]\s*/, "").replaceAll(/`([^`]+)`/g, "$1").replaceAll("`", "").replace(/\s+/g, " ").trim().replace(/\.$/, "");
 }
 function headingIncludesVersion(heading, version) {
 	const unwrapped = heading.replace(/[[\]]/g, " ");
@@ -2201,11 +2753,19 @@ async function collectGit(cwd, event) {
 			fetchedAt
 		})
 	};
-	if (previousTag !== void 0) release.previousVersion = fact(versionFromTag(previousTag), {
-		source: "git",
-		ref: `git tag ${previousTag}`,
-		fetchedAt
-	});
+	if (previousTag !== void 0) {
+		release.previousVersion = fact(versionFromTag(previousTag), {
+			source: "git",
+			ref: `git tag ${previousTag}`,
+			fetchedAt
+		});
+		const kind = releaseKind(versionFromTag(previousTag), versionFromTag(tag));
+		if (kind !== void 0) release.kind = fact(kind, {
+			source: "git",
+			ref: `semver ${previousTag}..${tag}`,
+			fetchedAt
+		});
+	}
 	if (names.length > 0) release.contributors = fact(names, {
 		source: "git",
 		ref: `git log ${range} unique authors`,
@@ -2294,6 +2854,30 @@ function githubSlug(url) {
 	const cleaned = url.replace(/^git\+/, "").replace(/\.git$/, "");
 	return /github\.com[/:]([^/]+\/[^/]+)$/.exec(cleaned)?.[1];
 }
+/**
+* How significant is this release, by semver alone?
+*
+* Compared against the previous tag rather than read from a changelog heading, so it is a fact
+* with a reference someone can re-run. Returns undefined when either tag is not semver, or when
+* the two are equal: a caller should treat "unknown" as "announce it", never as "skip it".
+*/
+function releaseKind(previous, current) {
+	const before = parseSemver(previous);
+	const after = parseSemver(current);
+	if (before === void 0 || after === void 0) return;
+	if (after[0] !== before[0]) return "major";
+	if (after[1] !== before[1]) return "minor";
+	return after[2] === before[2] ? void 0 : "patch";
+}
+function parseSemver(value) {
+	const match = /^(\d+)\.(\d+)\.(\d+)/.exec(value.replace(/^v/, ""));
+	if (match === null) return;
+	return [
+		Number(match[1]),
+		Number(match[2]),
+		Number(match[3])
+	];
+}
 
 //#endregion
 //#region src/sources/github.ts
@@ -2326,7 +2910,7 @@ async function collectGithub(options) {
 	};
 	if (repo.description !== void 0 && repo.description !== null && repo.description.length > 0) out.project = {
 		...out.project,
-		tagline: fact(repo.description, {
+		tagline: fact(stripEmoji(repo.description), {
 			source: "github-api",
 			ref: `GET /repos/${slug.owner}/${slug.repo} description`,
 			fetchedAt
@@ -2492,6 +3076,7 @@ async function npmPackageExists(name, fetchImpl = fetch) {
 const pkgSchema = z.object({
 	private: z.boolean().optional(),
 	name: z.string().optional(),
+	bin: z.union([z.string(), z.record(z.string(), z.string())]).optional(),
 	description: z.string().optional(),
 	version: z.string().optional(),
 	homepage: z.string().optional(),
@@ -2521,7 +3106,7 @@ async function collectPackageJson(cwd, packagePath = "package.json") {
 		ref: rawName === void 0 ? `${packagePath} directory name` : `${packagePath}#name`,
 		fetchedAt
 	}) };
-	if (pkg.data.description !== void 0 && pkg.data.description.length > 0) project.tagline = fact(pkg.data.description, {
+	if (pkg.data.description !== void 0 && pkg.data.description.length > 0) project.tagline = fact(stripEmoji(pkg.data.description), {
 		source: "package-json",
 		ref: `${packagePath}#description`,
 		fetchedAt
@@ -2543,6 +3128,11 @@ async function collectPackageJson(cwd, packagePath = "package.json") {
 		ref: `${packagePath}#name`,
 		fetchedAt
 	});
+	if (pkg.data.bin !== void 0 && pkg.data.private !== true) project.cli = fact(true, {
+		source: "package-json",
+		ref: `${packagePath}#bin`,
+		fetchedAt
+	});
 	if (pkg.data.license !== void 0) project.license = fact(pkg.data.license, {
 		source: "package-json",
 		ref: `${packagePath}#license`,
@@ -2597,9 +3187,23 @@ async function collectFacts(options) {
 	const changelog = await collectBestChangelog(options.cwd, version, options.changelogPath ?? "CHANGELOG.md", options.packagePath);
 	const readme = await collectReadme(options.cwd);
 	const snippet = options.snippet !== void 0 && options.snippet !== null && options.snippet.length > 0 ? await collectConfiguredSnippet(options.cwd, options.snippet) : {};
+	const workspacePkg = pkg.project?.npmPackage === void 0 ? await collectWorkspaceNpmPackage(options.cwd, options.skipNetwork === true ? {} : { verify: async (name) => npmPackageExists(name, options.fetchImpl ?? fetch) }) : {};
+	const overrides = {};
+	for (const slot of ["headline", "subheadline"]) {
+		const text = options[slot]?.trim();
+		if (text !== void 0 && text.length > 0) overrides.release = {
+			...overrides.release,
+			[slot]: fact(text, {
+				source: "user-config",
+				ref: `--${slot} or release.${slot}`,
+				fetchedAt: (/* @__PURE__ */ new Date()).toISOString()
+			})
+		};
+	}
 	const parts = [
+		overrides,
 		pkg,
-		pkg.project?.npmPackage === void 0 ? await collectWorkspaceNpmPackage(options.cwd, options.skipNetwork === true ? {} : { verify: async (name) => npmPackageExists(name, options.fetchImpl ?? fetch) }) : {},
+		workspacePkg,
 		remote,
 		git,
 		snippet,
@@ -2656,16 +3260,19 @@ async function collectWorkspaceNpmPackage(cwd, options = {}) {
 	const paths = await workspaceManifests(cwd);
 	const found = (await Promise.all(paths.map((path) => collectPackageJson(cwd, path)))).map((facts, index) => ({
 		name: facts.project?.npmPackage?.value,
+		cli: facts.project?.cli,
 		path: paths[index] ?? ""
 	})).filter((entry) => entry.name !== void 0);
 	const only = found.length === 1 ? found[0] : void 0;
 	if (only === void 0) return {};
 	if (options.verify !== void 0 && await options.verify(only.name) === false) return {};
-	return { project: { npmPackage: fact(only.name, {
+	const project = { npmPackage: fact(only.name, {
 		source: "package-json",
 		ref: `${only.path}#name`,
 		fetchedAt: (/* @__PURE__ */ new Date()).toISOString()
-	}) } };
+	}) };
+	if (only.cli !== void 0) project.cli = only.cli;
+	return { project };
 }
 async function workspaceManifests(cwd) {
 	return (await workspaceChangelogs(cwd)).map((path) => path.replace(/CHANGELOG\.md$/, "package.json"));
@@ -2693,27 +3300,18 @@ function gitRepoFromParts(pkg, readme) {
 //#endregion
 //#region src/render/takumi.ts
 const GEIST_MONO_FAMILY = "Geist Mono";
-const FONT_REL = join("assets", "fonts", "GeistMono[wght].ttf");
-async function createTakumiRenderer() {
+/** Path of the vendored font, relative to the package root. Resolved in `takumi-node.ts`. */
+const FONT_REL = "assets/fonts/GeistMono[wght].ttf";
+/** Both runtimes end here: one adapter, one registered font, whoever supplied the bytes. */
+async function createRendererWithFont(font) {
 	const renderer = new Renderer();
-	const fontPath = join(resolvePackageRoot(), FONT_REL);
-	const data = await readFile(fontPath);
 	await renderer.registerFont({
 		name: GEIST_MONO_FAMILY,
-		data,
+		data: font,
 		generic: "monospace"
 	});
 	return new TakumiRenderer(renderer);
 }
-function resolvePackageRoot(from = import.meta.url) {
-	let dir = dirname(fileURLToPath(from));
-	for (;;) {
-		if (existsSync(join(dir, "package.json")) && existsSync(join(dir, FONT_REL))) return dir;
-		const parent = dirname(dir);
-		if (parent === dir) throw new ShipsealError("render.font-missing", `Could not find vendored font ${FONT_REL}.`, "Reinstall shipseal so assets/fonts/GeistMono[wght].ttf is present next to package.json.");
-		dir = parent;
-	}
-}
 function countLines(node) {
 	const ys = /* @__PURE__ */ new Set();
 	const walk = (current) => {
@@ -2882,6 +3480,23 @@ function asReactElementLike(element) {
 	};
 }
 
+//#endregion
+//#region src/render/takumi-node.ts
+async function createTakumiRenderer() {
+	const fontPath = join(resolvePackageRoot(), FONT_REL);
+	const data = await readFile(fontPath);
+	return createRendererWithFont(data);
+}
+function resolvePackageRoot(from = import.meta.url) {
+	let dir = dirname(fileURLToPath(from));
+	for (;;) {
+		if (existsSync(join(dir, "package.json")) && existsSync(join(dir, "assets/fonts/GeistMono[wght].ttf"))) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) throw new ShipsealError("render.font-missing", `Could not find vendored font ${FONT_REL}.`, "Reinstall shipseal so assets/fonts/GeistMono[wght].ttf is present next to package.json.");
+		dir = parent;
+	}
+}
+
 //#endregion
 //#region src/copy/number-guard.ts
 function allowedNumbers(facts) {
@@ -3112,6 +3727,7 @@ function flattenFacts(facts) {
 		if (typeof value === "object" && value !== null) for (const [key, nested] of Object.entries(value)) walk(prefix.length === 0 ? key : `${prefix}.${key}`, nested);
 	};
 	walk("project", facts.project);
+	if (facts.story !== void 0) walk("story", facts.story);
 	if (facts.release !== void 0) walk("release", facts.release);
 	if (facts.metrics !== void 0) walk("metrics", facts.metrics);
 	if (facts.bench !== void 0) walk("bench", facts.bench);
@@ -3827,12 +4443,12 @@ function allVariables(css) {
 	return vars;
 }
 /**
-* Resolve a declaration to a hex colour.
+* Resolve a declaration to a hex color.
 *
-* Handles two things a plain colour parser does not. First, `var(--brand-500)` indirection,
+* Handles two things a plain color parser does not. First, `var(--brand-500)` indirection,
 * up to three hops within the same file. Second, bare channel lists: shadcn writes
 * `--background: 0 0% 100%` and applies it as `hsl(var(--background))`, so the value is only
-* a colour once wrapped. Percent signs on the last two channels mean HSL, three plain
+* a color once wrapped. Percent signs on the last two channels mean HSL, three plain
 * numbers mean RGB.
 */
 function resolveColor(raw, vars, depth = 0) {
@@ -3993,7 +4609,7 @@ const SIGNATURE = Buffer.from([
 	26,
 	10
 ]);
-/** Channels per pixel for each PNG colour type. Index is the colour type. */
+/** Channels per pixel for each PNG color type. Index is the color type. */
 const CHANNELS = {
 	0: 1,
 	2: 3,
@@ -4143,10 +4759,10 @@ function toRgba(data, width, height, colorType, bytesPerSample, palette, palette
 	return pixels;
 }
 /**
-* Most common non-neutral colour in a logo, as a hex string.
+* Most common non-neutral color in a logo, as a hex string.
 *
 * Nearly transparent pixels are ignored so a transparent background does not win, and greys
-* are ignored because a logo's black wordmark is not its brand colour. Colours are bucketed
+* are ignored because a logo's black wordmark is not its brand color. Colors are bucketed
 * into 16 levels per channel so anti-aliased edges group with the solid fill they belong to,
 * then the winning bucket reports the average of the real pixels inside it rather than the
 * bucket centre, which would drift the hue.
@@ -4483,7 +5099,7 @@ async function detectColors(cwd, logoPath, sources, notes) {
 			merged.primary = fromPng;
 			sources.push({
 				field: "colors.primary",
-				source: `dominant colour in ${logoPath}`
+				source: `dominant color in ${logoPath}`
 			});
 		}
 		const svg = logoPath.endsWith(".svg") ? await readMaybe(join(cwd, logoPath)) : void 0;
@@ -4625,8 +5241,8 @@ function normalizeGitUrl(url) {
 	return url.replace(/^git\+/, "").replace(/\.git$/, "");
 }
 /**
-* Dominant non-neutral colour of a PNG logo, or undefined when the file cannot be read or
-* carries no colour. Detection reports the colour as not found rather than falling back to a
+* Dominant non-neutral color of a PNG logo, or undefined when the file cannot be read or
+* carries no color. Detection reports the color as not found rather than falling back to a
 * built-in default that would be presented to the user as "your brand".
 */
 async function dominantLogoColor(path) {
@@ -4898,6 +5514,12 @@ function missingMetric(metric) {
 
 //#endregion
 //#region src/commands/release.ts
+/** Lowest kind worth announcing, most significant first. */
+const ANNOUNCE_ORDER = [
+	"major",
+	"minor",
+	"patch"
+];
 async function runRelease(flags) {
 	const cwd = flags.cwd;
 	const config = overlayReleaseConfig(await loadConfig(cwd), flags);
@@ -4923,9 +5545,25 @@ async function runRelease(flags) {
 	if (config.release?.snippet !== void 0) collectOpts.snippet = config.release.snippet;
 	if (env.githubToken !== void 0) collectOpts.githubToken = env.githubToken;
 	if (env.fetchImpl !== void 0) collectOpts.fetchImpl = env.fetchImpl;
+	const headline = flags.headline ?? config.release?.headline ?? void 0;
+	if (headline !== void 0) collectOpts.headline = headline;
+	const subheadline = flags.subheadline ?? config.release?.subheadline ?? void 0;
+	if (subheadline !== void 0) collectOpts.subheadline = subheadline;
 	const facts = await collectFacts(collectOpts);
+	const announce = config.release?.announce ?? "patch";
+	const kind = facts.release?.kind?.value;
+	if (kind !== void 0 && ANNOUNCE_ORDER.indexOf(kind) > ANNOUNCE_ORDER.indexOf(announce)) return {
+		dryRun: flags.dryRun === true,
+		skipped: true,
+		message: `This is a ${kind} release and release.announce is "${announce}". Nothing to generate.`,
+		facts,
+		copy: deterministicCopy(facts, config.release?.maxHighlights, brand.name),
+		copyMode: "deterministic",
+		warnings: [],
+		exitCode: 0
+	};
 	const noCopy = flags.copy === false;
-	const resolved = await resolveCopy(facts, config, noCopy, deterministicCopy(facts, config.release?.maxHighlights));
+	const resolved = await resolveCopy(facts, config, noCopy, deterministicCopy(facts, config.release?.maxHighlights, brand.name));
 	if (flags.dryRun === true) {
 		const dry = {
 			dryRun: true,
@@ -4977,6 +5615,691 @@ function overlayReleaseConfig(config, flags) {
 	});
 }
 
+//#endregion
+//#region src/core/story.ts
+const DEFAULT_CHANGE_PAGES = 4;
+const STORY_FORMATS$1 = "portrait, square, og, github-social, x, linkedin, or producthunt";
+function storyFacts(facts, config, brand, generatedAt) {
+	const release = facts.release;
+	if (release === void 0) throw new ShipsealError("story.no-release", "No release facts are available for a story.", "Choose a published release or pass --tag to a local repository.");
+	const copy = deterministicCopy(facts, config.release?.maxHighlights, brand.name);
+	const configured = (value, ref) => fact(value, {
+		source: "user-config",
+		ref,
+		fetchedAt: generatedAt
+	});
+	const changes = [
+		...release.breaking,
+		...release.features,
+		...release.fixes
+	];
+	const headlineSource = release.headline ?? changes.find((item) => cleanLine(firstSentence(item.value)) === copy.headline) ?? release.version;
+	const pages = [{
+		kind: "cover",
+		title: fact(copy.headline, headlineSource.provenance),
+		body: release.subheadline ?? facts.project.tagline ?? (brand.tagline === void 0 ? fact("Release notes", release.tag.provenance) : fact(brand.tagline, {
+			source: "user-config",
+			ref: "brand.json#tagline",
+			fetchedAt: generatedAt
+		}))
+	}];
+	for (const item of changes.slice(0, config.release?.maxHighlights ?? DEFAULT_CHANGE_PAGES)) {
+		const collapsed = item.value.replaceAll(/\s+/g, " ").trim();
+		const sentence = firstSentence(collapsed);
+		const remainder = collapsed.slice(sentence.length).trim();
+		pages.push({
+			kind: "change",
+			title: fact(cleanLine(sentence), item.provenance),
+			body: fact(remainder.length > 0 ? cleanLine(remainder) : "", item.provenance)
+		});
+	}
+	if (release.codeSnippet !== void 0) pages.push({
+		kind: "code",
+		title: fact("Code example", release.codeSnippet.provenance),
+		body: fact(release.codeSnippet.value.code, release.codeSnippet.provenance)
+	});
+	const options = config.release?.story;
+	if (options?.before !== void 0 && options.after !== void 0) pages.push({
+		kind: "comparison",
+		title: configured("Before and after", "release.story.before + release.story.after"),
+		body: configured("Supplied screenshots", "release.story"),
+		before: configured(options.before, "release.story.before"),
+		after: configured(options.after, "release.story.after")
+	});
+	const hasUpgrade = options?.upgrade !== void 0 && options.upgrade.trim().length > 0;
+	let upgrade;
+	if (hasUpgrade && options?.upgrade !== void 0) upgrade = configured(options.upgrade.trim(), "release.story.upgrade");
+	else {
+		const repo = facts.project.repo;
+		upgrade = repo === void 0 ? fact(copy.cta, facts.project.url?.provenance ?? facts.project.name.provenance) : fact(`Read the release notes at github.com/${repo.value}/releases/tag/${encodeURIComponent(release.tag.value)}`, repo.provenance);
+	}
+	pages.push({
+		kind: "upgrade",
+		title: fact(hasUpgrade ? "How to upgrade" : "Get the release", upgrade.provenance),
+		body: upgrade
+	});
+	return {
+		...facts,
+		story: pages
+	};
+}
+async function generateStory(input) {
+	const facts = storyFacts(input.facts, input.config, input.brand, input.generatedAt);
+	const pages = facts.story ?? [];
+	const result = {
+		files: [],
+		warnings: [],
+		missing: [],
+		facts,
+		copy: input.copy,
+		copyMode: "deterministic",
+		generatedAt: input.generatedAt,
+		computed: {}
+	};
+	const formats = input.config.formats ?? ["portrait"];
+	if (formats.length === 0 || formats.includes("readme-banner")) throw new ShipsealError("story.bad-format", "The story format selection contains no supported output or includes readme-banner.", `Use ${STORY_FORMATS$1}.`);
+	for (const [index, page] of pages.entries()) {
+		const rendered = await generate({
+			...input,
+			facts: {
+				...facts,
+				story: [page]
+			},
+			config: {
+				...input.config,
+				formats,
+				release: {
+					...input.config.release,
+					templates: ["story-page"]
+				}
+			}
+		});
+		const id = `story-${String(index + 1).padStart(2, "0")}-${page.kind}`;
+		result.files.push(...rendered.files.map((file) => ({
+			...file,
+			fileName: file.fileName.replace("story-page", id)
+		})));
+		result.warnings.push(...rendered.warnings.map((warning) => ({
+			...warning,
+			slot: `page-${String(index + 1)}.${warning.slot}`
+		})));
+		result.missing.push(...rendered.missing);
+		result.computed[`story.pages[${String(index)}]`] = {
+			value: {
+				kind: page.kind,
+				files: result.files.filter((file) => file.fileName.startsWith(id)).map((file) => file.fileName)
+			},
+			computedFrom: [`story[${String(index)}].title`, `story[${String(index)}].body`]
+		};
+	}
+	if (facts.release?.codeSnippet === void 0) result.missing.push({
+		template: "story-page",
+		fact: "release.codeSnippet",
+		effect: "code page omitted"
+	});
+	if (pages.every((page) => page.kind !== "change")) result.missing.push({
+		template: "story-page",
+		fact: "release.features",
+		effect: "change pages omitted because release notes have no changes"
+	});
+	return result;
+}
+
+//#endregion
+//#region src/outputs/downloads.ts
+const encode = (value) => new TextEncoder().encode(value);
+const isJpeg = (bytes) => bytes[0] === 255 && bytes[1] === 216;
+function joinBytes(parts) {
+	const result = new Uint8Array(parts.reduce((sum, part) => sum + part.length, 0));
+	let offset = 0;
+	for (const part of parts) {
+		result.set(part, offset);
+		offset += part.length;
+	}
+	return result;
+}
+/**
+* Image-only PDF: each JPEG becomes one page as a DCTDecode stream, so the page is the exact
+* rendered layout rather than a reflow of it. Pages are placed at half the pixel size, which
+* puts a 1080x1350 render on a 540x675pt page at 144dpi.
+*
+* Object numbering: 1 is the catalog, 2 the page tree, then each page contributes three
+* objects (page, image, content stream) at 3 + index * 3.
+*/
+function carouselPdf(pages) {
+	if (pages.length === 0 || pages.some((page) => !isJpeg(page.bytes))) throw new ShipsealError("pdf.invalid-pages", "A carousel requires nonempty JPEG pages.", "Render the story as JPEG before building the PDF.");
+	const objects = [encode("<< /Type /Catalog /Pages 2 0 R >>"), encode(`<< /Type /Pages /Count ${String(pages.length)} /Kids [${pages.map((_, index) => `${String(3 + index * 3)} 0 R`).join(" ")}] >>`)];
+	for (const [index, page] of pages.entries()) {
+		const id = 3 + index * 3;
+		const width = page.width / 2;
+		const height = page.height / 2;
+		objects.push(encode(`<< /Type /Page /Parent 2 0 R /MediaBox [0 0 ${String(width)} ${String(height)}] /Resources << /XObject << /Image ${String(id + 1)} 0 R >> >> /Contents ${String(id + 2)} 0 R >>`));
+		objects.push(joinBytes([
+			encode(`<< /Type /XObject /Subtype /Image /Width ${String(page.width)} /Height ${String(page.height)} /ColorSpace /DeviceRGB /BitsPerComponent 8 /Filter /DCTDecode /Length ${String(page.bytes.length)} >>\nstream\n`),
+			page.bytes,
+			encode("\nendstream")
+		]));
+		const content = `q ${String(width)} 0 0 ${String(height)} 0 0 cm /Image Do Q`;
+		objects.push(encode(`<< /Length ${String(encode(content).length)} >>\nstream\n${content}\nendstream`));
+	}
+	const header = encode("%PDF-1.4\n%Shipseal\n");
+	const parts = [header];
+	const offsets = [];
+	let position = header.length;
+	for (const [index, object] of objects.entries()) {
+		offsets.push(position);
+		const bytes = joinBytes([
+			encode(`${String(index + 1)} 0 obj\n`),
+			object,
+			encode("\nendobj\n")
+		]);
+		parts.push(bytes);
+		position += bytes.length;
+	}
+	const size = objects.length + 1;
+	parts.push(encode(`xref\n0 ${String(size)}\n0000000000 65535 f \n` + offsets.map((offset) => `${String(offset).padStart(10, "0")} 00000 n \n`).join("") + `trailer\n<< /Size ${String(size)} /Root 1 0 R >>\nstartxref\n${String(position)}\n%%EOF\n`));
+	return joinBytes(parts);
+}
+function crc32(bytes) {
+	let value = 4294967295;
+	for (const byte of bytes) {
+		value ^= byte;
+		for (let bit = 0; bit < 8; bit += 1) value = value >>> 1 ^ ((value & 1) === 1 ? 3988292384 : 0);
+	}
+	return (value ^ 4294967295) >>> 0;
+}
+/**
+* ZIP with STORE and no compression: PNG and JPEG are already compressed, so deflating them
+* costs time and saves nothing. Every timestamp is the fixed DOS date 1980-01-01 (0x0021) so
+* the same inputs always produce the same archive bytes.
+*/
+function zipFiles(files) {
+	const FIXED_DOS_DATE = 33;
+	const names = /* @__PURE__ */ new Set();
+	const local = [];
+	const central = [];
+	let offset = 0;
+	for (const file of files) {
+		if (!/^[a-zA-Z0-9_.-]+$/.test(file.name) || names.has(file.name)) throw new ShipsealError("zip.bad-name", "An archive file name is unsafe or duplicated.", "Use unique file names without path separators.");
+		names.add(file.name);
+		const name = encode(file.name);
+		const checksum = crc32(file.bytes);
+		const header = /* @__PURE__ */ new Uint8Array(30);
+		const headerView = new DataView(header.buffer);
+		headerView.setUint32(0, 67324752, true);
+		headerView.setUint16(4, 20, true);
+		headerView.setUint16(12, FIXED_DOS_DATE, true);
+		headerView.setUint32(14, checksum, true);
+		headerView.setUint32(18, file.bytes.length, true);
+		headerView.setUint32(22, file.bytes.length, true);
+		headerView.setUint16(26, name.length, true);
+		local.push(header, name, file.bytes);
+		const entry = /* @__PURE__ */ new Uint8Array(46);
+		const entryView = new DataView(entry.buffer);
+		entryView.setUint32(0, 33639248, true);
+		entryView.setUint16(4, 20, true);
+		entryView.setUint16(6, 20, true);
+		entryView.setUint16(14, FIXED_DOS_DATE, true);
+		entryView.setUint32(16, checksum, true);
+		entryView.setUint32(20, file.bytes.length, true);
+		entryView.setUint32(24, file.bytes.length, true);
+		entryView.setUint16(28, name.length, true);
+		entryView.setUint32(42, offset, true);
+		central.push(entry, name);
+		offset += header.length + name.length + file.bytes.length;
+	}
+	const end = /* @__PURE__ */ new Uint8Array(22);
+	const endView = new DataView(end.buffer);
+	endView.setUint32(0, 101010256, true);
+	endView.setUint16(8, files.length, true);
+	endView.setUint16(10, files.length, true);
+	endView.setUint32(12, central.reduce((sum, part) => sum + part.length, 0), true);
+	endView.setUint32(16, offset, true);
+	return joinBytes([
+		...local,
+		...central,
+		end
+	]);
+}
+
+//#endregion
+//#region src/studio/pack.ts
+/** Every format the `story-page` template declares, in the order the selector lists them. */
+const STORY_FORMATS = [
+	"portrait",
+	"square",
+	"og",
+	"github-social",
+	"x",
+	"linkedin",
+	"producthunt"
+];
+const encodeJson = (value) => new TextEncoder().encode(`${JSON.stringify(value, null, 2)}\n`);
+const selectionSchema = z.object({
+	pack: z.enum(["story", "release"]).default("story"),
+	style: brandSchema.shape.style,
+	theme: z.enum(["dark", "light"]),
+	accent: brandSchema.shape.colors.shape.primary,
+	headline: z.string().max(500).default(""),
+	upgrade: z.string().max(4e3).default(""),
+	format: z.enum([...STORY_FORMATS, "all"]).default("portrait")
+}).strict();
+function selectedConfig(config, selection) {
+	const formats = selection.format === "all" ? selection.pack === "story" ? [...STORY_FORMATS] : [...V1_FORMAT_IDS] : [selection.format];
+	const landscape = new Set(V1_FORMAT_IDS);
+	if (selection.pack === "release" && formats.some((format) => !landscape.has(format))) throw new ShipsealError("preview.format", "The standard release templates do not support this format.", "Choose a landscape format or switch to a story pack.");
+	return {
+		...config,
+		formats,
+		release: {
+			...config.release,
+			headline: selection.headline || null,
+			story: {
+				...config.release?.story,
+				upgrade: selection.upgrade
+			}
+		},
+		output: { imageFormat: "png" }
+	};
+}
+function selectedBrand(brand, selection) {
+	return {
+		...brand,
+		style: selection.style,
+		colors: {
+			...brand.colors,
+			primary: selection.accent
+		}
+	};
+}
+async function buildStudioPack(input) {
+	const release = input.facts.release;
+	if (release === void 0) throw new ShipsealError("preview.no-release", "No release is selected.", "Load a repository release first.");
+	const config = selectedConfig(input.config, input.selection);
+	const brand = selectedBrand(input.brand, input.selection);
+	const facts = {
+		...input.facts,
+		release: { ...release }
+	};
+	if (input.selection.headline) facts.release = {
+		...release,
+		headline: fact(input.selection.headline, {
+			source: "user-config",
+			ref: "release.headline",
+			fetchedAt: input.generatedAt
+		})
+	};
+	const event = {
+		kind: "release",
+		tag: release.tag.value
+	};
+	const request = {
+		event,
+		facts,
+		brand,
+		config,
+		copy: deterministicCopy(facts, config.release?.maxHighlights, brand.name),
+		copyMode: "deterministic",
+		renderer: input.renderer,
+		themes: [input.selection.theme],
+		generatedAt: input.generatedAt
+	};
+	if (input.logos !== void 0) request.logos = input.logos;
+	if (input.images !== void 0) request.images = input.images;
+	const result = await (input.selection.pack === "story" ? generateStory : generate)(request);
+	const manifest = buildManifest({
+		result,
+		event,
+		brand,
+		shipsealVersion: input.version
+	});
+	manifest.brand.source = input.brandSource ?? ".shipseal/brand.json + preview selections";
+	const downloads = result.files.map((file) => ({
+		name: file.fileName,
+		bytes: file.bytes
+	}));
+	if (input.selection.pack === "story") {
+		const pdfFormat = config.formats?.[0] ?? "portrait";
+		const jpeg = await generateStory({
+			...request,
+			config: {
+				...config,
+				formats: [pdfFormat],
+				output: { imageFormat: "jpeg" }
+			}
+		});
+		const pdf = carouselPdf(jpeg.files);
+		downloads.push({
+			name: "story.pdf",
+			bytes: pdf
+		});
+		manifest.computed["story.pdf"] = {
+			value: {
+				format: pdfFormat,
+				pages: jpeg.files.length,
+				bytes: pdf.length
+			},
+			computedFrom: ["story"]
+		};
+	}
+	downloads.push({
+		name: "brand.json",
+		bytes: encodeJson(brand)
+	}, {
+		name: "config.json",
+		bytes: encodeJson(config)
+	}, {
+		name: "manifest.json",
+		bytes: encodeJson(manifest)
+	});
+	return {
+		result,
+		manifest,
+		downloads,
+		archive: zipFiles(downloads),
+		brand,
+		config
+	};
+}
+
+//#endregion
+//#region src/commands/story.ts
+const STORY_IMAGE_LABELS = ["before", "after"];
+const MAX_STORY_IMAGE_BYTES = 5e6;
+/**
+* Screenshots are supplied by the maintainer, never generated or captured here: no headless
+* browser is a hard rule (AGENTS.md rule 2).
+*/
+async function readStoryImage(cwd, label, path) {
+	let data;
+	try {
+		data = await readFile(resolve(cwd, path));
+	} catch (error) {
+		throw new ShipsealError("story.image-missing", `Could not read the ${label} screenshot: ${path}.`, "Set release.story.before and release.story.after to existing PNG or JPEG files.", { cause: error });
+	}
+	const png = data[0] === 137 && data[1] === 80 && data[2] === 78 && data[3] === 71;
+	const jpeg = data[0] === 255 && data[1] === 216;
+	if (!png && !jpeg || data.length > MAX_STORY_IMAGE_BYTES) throw new ShipsealError("story.image-invalid", `The ${label} screenshot is not a supported image or exceeds the size limit.`, "Use a PNG or JPEG smaller than 5 MB.");
+	return {
+		src: `story-${label}`,
+		data
+	};
+}
+async function loadStoryImages(cwd, config) {
+	const configured = STORY_IMAGE_LABELS.flatMap((label) => {
+		const path = config.release?.story?.[label];
+		return path === void 0 ? [] : [{
+			label,
+			path
+		}];
+	});
+	return Promise.all(configured.map((image) => readStoryImage(cwd, image.label, image.path)));
+}
+async function runStory(flags) {
+	const brand = await loadBrand(flags.cwd);
+	const config = await loadConfig(flags.cwd);
+	const tag = flags.tag ?? await gitCurrentTag(flags.cwd);
+	if (tag === void 0) throw new ShipsealError("story.no-tag", "No release tag was found.", "Pass --tag with an existing release tag.");
+	const parsed = selectionSchema.safeParse({
+		pack: "story",
+		style: flags.style ?? brand.style,
+		theme: flags.theme ?? brand.theme,
+		accent: brand.colors.primary ?? "#ff4d4d",
+		headline: flags.headline ?? config.release?.headline ?? "",
+		upgrade: config.release?.story?.upgrade ?? "",
+		format: flags.format ?? "portrait"
+	});
+	if (!parsed.success) {
+		const fields = [...new Set(parsed.error.issues.map((issue) => issue.path.join(".")))];
+		throw new ShipsealError("story.bad-options", `These story options are not valid: ${fields.join(", ")}.`, "Use --format portrait, square, og, github-social, x, linkedin, producthunt or all; --style minimal, editorial or terminal; --theme dark or light.", { cause: parsed.error });
+	}
+	const selection = parsed.data;
+	const collectOptions = {
+		cwd: flags.cwd,
+		event: {
+			kind: "release",
+			tag
+		},
+		skipNetwork: true
+	};
+	if (flags.package !== void 0) collectOptions.packagePath = flags.package;
+	if (config.release?.changelogPath !== void 0) collectOptions.changelogPath = config.release.changelogPath;
+	if (config.release?.snippet !== void 0) collectOptions.snippet = config.release.snippet;
+	const input = {
+		facts: await collectFacts(collectOptions),
+		brand,
+		config,
+		selection,
+		renderer: await createTakumiRenderer(),
+		version: readShipsealVersion(),
+		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		images: await loadStoryImages(flags.cwd, config),
+		brandSource: ".shipseal/brand.json + story flags"
+	};
+	const logos = await loadLogos(flags.cwd, brand);
+	if (logos !== void 0) input.logos = logos;
+	const pack = await buildStudioPack(input);
+	const dir = resolve(flags.cwd, flags.out ?? config.outputDir ?? ".shipseal/output", `story-${tag.replaceAll(/[^a-zA-Z0-9_.-]/g, "-")}`);
+	await mkdir(dir, { recursive: true });
+	await Promise.all(pack.downloads.map((file) => writeFile(join(dir, file.name), file.bytes)));
+	await writeFile(join(dir, "story.zip"), pack.archive);
+	return {
+		dir,
+		manifest: pack.manifest,
+		exitCode: flags.strict === true && pack.manifest.warnings.length > 0 ? 2 : 0
+	};
+}
+
+//#endregion
+//#region src/commands/preview.ts
+/** Localhost only, so the page is served inline rather than from a template file. */
+const PAGE = `<!doctype html><html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1"><title>Shipseal preview</title>
+</head><body style="margin:0;background:#0c0c0f"><main id="studio"></main><script type="module">
+import { mountStudio } from '/studio-client.js';
+const token = new URL(location.href).searchParams.get('token');
+async function api(path, value) {
+  const response = await fetch(path, {
+    method: value === undefined ? 'GET' : 'POST',
+    headers: { 'Content-Type': 'application/json', 'X-Shipseal-Token': token },
+    ...(value === undefined ? {} : { body: JSON.stringify(value) }),
+  });
+  const body = await response.json();
+  if (!response.ok) throw new Error(body.error);
+  return body;
+}
+mountStudio(document.getElementById('studio'), {
+  mode: 'local',
+  load: () => api('/api/state'),
+  render: (value) => api('/api/render', value),
+  save: (value) => api('/api/save', value),
+});
+<\/script></body></html>`;
+const PAGE_HEADERS = {
+	"Content-Type": "text/html; charset=utf-8",
+	"Cache-Control": "no-store",
+	"Referrer-Policy": "no-referrer",
+	"Content-Security-Policy": "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' blob:; connect-src 'self'; frame-ancestors 'none'"
+};
+function json(response, status, value) {
+	response.writeHead(status, {
+		"Content-Type": "application/json",
+		"Cache-Control": "no-store",
+		"X-Content-Type-Options": "nosniff"
+	});
+	response.end(JSON.stringify(value));
+}
+async function readSelection(request) {
+	let text = "";
+	for await (const value of request) {
+		if (!Buffer.isBuffer(value)) throw new ShipsealError("preview.body", "The request body is not valid bytes.", "Reload the preview.");
+		text += value.toString("utf8");
+		if (text.length > 16384) throw new ShipsealError("preview.body-size", "The preview request is too large.", "Shorten the headline or upgrade instructions.");
+	}
+	try {
+		const raw = JSON.parse(text);
+		return selectionSchema.parse(raw);
+	} catch (error) {
+		throw new ShipsealError("preview.selection", "The preview options are invalid.", "Reload the preview and choose supported options.", { cause: error });
+	}
+}
+/** Write through a temporary file so an interrupted save never truncates the original. */
+async function writeAtomic(destination, value) {
+	const temporary = `${destination}.${randomUUID()}.tmp`;
+	await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+	await rename(temporary, destination);
+}
+async function startPreview(options) {
+	const resolvedTag = options.tag ?? await gitCurrentTag(options.cwd);
+	if (resolvedTag === void 0) throw new ShipsealError("preview.no-tag", "No release tag was found.", "Pass --tag with an existing release tag.");
+	const tag = resolvedTag;
+	await loadBrand(options.cwd);
+	const token = randomUUID();
+	let origin = "";
+	async function handle(request, response) {
+		if (request.headers.host !== new URL(origin).host) {
+			json(response, 403, { error: "Invalid preview host. Open the localhost URL printed by Shipseal." });
+			return;
+		}
+		const url = new URL(request.url ?? "/", origin);
+		if (request.method === "GET" && url.pathname === "/") {
+			response.writeHead(200, PAGE_HEADERS);
+			response.end(PAGE);
+			return;
+		}
+		if (request.method === "GET" && url.pathname === "/studio-client.js") {
+			const script = await readFile(join(resolvePackageRoot(), "dist", "studio-client.js"));
+			response.writeHead(200, {
+				"Content-Type": "text/javascript",
+				"Cache-Control": "no-store"
+			});
+			response.end(script);
+			return;
+		}
+		if (request.headers["x-shipseal-token"] !== token || request.method === "POST" && request.headers.origin !== origin) {
+			json(response, 403, { error: "This preview request is not authorized. Reload the localhost URL printed by Shipseal." });
+			return;
+		}
+		const brand = await loadBrand(options.cwd);
+		const config = await loadConfig(options.cwd);
+		const collect = {
+			cwd: options.cwd,
+			event: {
+				kind: "release",
+				tag
+			},
+			skipNetwork: true
+		};
+		if (options.package !== void 0) collect.packagePath = options.package;
+		if (config.release?.changelogPath !== void 0) collect.changelogPath = config.release.changelogPath;
+		if (config.release?.snippet !== void 0) collect.snippet = config.release.snippet;
+		if (request.method === "GET" && url.pathname === "/api/state") {
+			const facts = await collectFacts(collect);
+			json(response, 200, {
+				name: brand.name,
+				style: brand.style,
+				theme: brand.theme,
+				accent: brand.colors.primary ?? "#ff4d4d",
+				headline: config.release?.headline ?? "",
+				upgrade: config.release?.story?.upgrade ?? "",
+				headlines: [...facts.release?.breaking ?? [], ...facts.release?.features ?? []].map((item) => cleanLine(firstSentence(item.value))),
+				notes: ["Local facts come from your checkout. Change files and refresh this page to reload them. Screenshots use release.story.before and release.story.after in config.json."],
+				releases: [{
+					tag,
+					label: tag
+				}],
+				tag
+			});
+			return;
+		}
+		if (request.method !== "POST") {
+			json(response, 404, { error: "Preview route not found." });
+			return;
+		}
+		const selection = await readSelection(request);
+		if (url.pathname === "/api/save") {
+			const nextConfig = selectedConfig(config, selection);
+			nextConfig.formats = config.formats;
+			await Promise.all([writeAtomic(join(options.cwd, ".shipseal", "brand.json"), selectedBrand(brand, selection)), writeAtomic(join(options.cwd, ".shipseal", "config.json"), nextConfig)]);
+			json(response, 200, { saved: true });
+			return;
+		}
+		if (url.pathname !== "/api/render") {
+			json(response, 404, { error: "Preview route not found." });
+			return;
+		}
+		const packInput = {
+			facts: await collectFacts(collect),
+			brand,
+			config,
+			selection,
+			renderer: await createTakumiRenderer(),
+			generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			version: readShipsealVersion(),
+			images: await loadStoryImages(options.cwd, config)
+		};
+		const logos = await loadLogos(options.cwd, brand);
+		if (logos !== void 0) packInput.logos = logos;
+		const pack = await buildStudioPack(packInput);
+		const output = {
+			files: pack.result.files.map((file) => ({
+				name: file.fileName,
+				data: Buffer.from(file.bytes).toString("base64"),
+				width: file.width,
+				height: file.height
+			})),
+			archive: Buffer.from(pack.archive).toString("base64"),
+			manifest: pack.manifest
+		};
+		const pdf = pack.downloads.find((file) => file.name === "story.pdf");
+		if (pdf !== void 0) output.pdf = Buffer.from(pdf.bytes).toString("base64");
+		json(response, 200, output);
+	}
+	const server = createServer((request, response) => {
+		handle(request, response).catch((error) => {
+			json(response, 400, { error: error instanceof ShipsealError ? formatError(error) : `${error instanceof Error ? error.message : "Preview failed"}. Check the files and retry.` });
+		});
+	});
+	await new Promise((accept, reject) => {
+		server.once("error", reject);
+		server.listen(options.port ?? 4175, "127.0.0.1", () => {
+			server.removeListener("error", reject);
+			accept();
+		});
+	});
+	const address = server.address();
+	if (address === null || typeof address === "string") throw new ShipsealError("preview.listen", "The preview server could not start.", "Choose another --port and retry.");
+	origin = `http://127.0.0.1:${String(address.port)}`;
+	return {
+		server,
+		url: `${origin}/?token=${token}`,
+		token
+	};
+}
+async function runPreview(options) {
+	let preview;
+	try {
+		preview = await startPreview(options);
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "EADDRINUSE") throw new ShipsealError("preview.port", "The preview port is already in use.", "Pass --port with another available port.", { cause: error });
+		throw error;
+	}
+	process.stdout.write(`Preview: ${preview.url}\nPress Ctrl+C to stop.\n`);
+	await new Promise((accept) => {
+		const stop = () => {
+			preview.server.close();
+			preview.server.closeAllConnections();
+		};
+		process.once("SIGINT", stop);
+		process.once("SIGTERM", stop);
+		preview.server.once("close", () => {
+			process.removeListener("SIGINT", stop);
+			process.removeListener("SIGTERM", stop);
+			accept();
+		});
+	});
+}
+
 //#endregion
 //#region src/cli.ts
 async function runCli(argv = process.argv) {
@@ -5004,6 +6327,46 @@ async function runCli(argv = process.argv) {
 			for (const note of result.detection.notes) process.stdout.write(`  note: ${note}\n`);
 		}
 	});
+	cli.command("story", "Generate an ordered release story, PDF carousel and ZIP").option("--tag <tag>", "Release tag").option("--format <format>", "portrait, square, og, github-social, x, linkedin, producthunt, or all").option("--style <style>", "minimal, editorial, or terminal").option("--theme <theme>", "dark or light").option("--headline <text>", "Override the cover headline").option("--out <dir>", "Output directory").option("--package <path>", "package.json path for monorepos").option("--strict", "Fit warnings exit with code 2").option("--no-copy", "Use source text only (stories always use deterministic copy)").action(async (flags) => {
+		const options = {
+			cwd: stringFlag(flags.cwd, process.cwd()),
+			strict: flags.strict === true
+		};
+		for (const key of [
+			"tag",
+			"format",
+			"style",
+			"theme",
+			"headline",
+			"out",
+			"package"
+		]) {
+			const value = optionalString(flags[key]);
+			if (value !== void 0) options[key] = value;
+		}
+		const result = await runStory(options);
+		process.exitCode = result.exitCode;
+		if (flags.json === true) writeJson(result);
+		else if (flags.quiet !== true) writeHumanResult({
+			...result,
+			dryRun: false,
+			facts: result.manifest.facts,
+			warnings: result.manifest.warnings
+		});
+	});
+	cli.command("preview", "Preview release and story packs locally, then save your choices").option("--tag <tag>", "Release tag").option("--port <port>", "Localhost port (default: 4175)").option("--package <path>", "package.json path for monorepos").action(async (flags) => {
+		const options = { cwd: stringFlag(flags.cwd, process.cwd()) };
+		for (const key of ["tag", "package"]) {
+			const value = optionalString(flags[key]);
+			if (value !== void 0) options[key] = value;
+		}
+		if (flags.port !== void 0) {
+			const port = Number(flags.port);
+			if (!Number.isInteger(port) || port < 0 || port > 65535) throw new ShipsealError("preview.port", "The preview port is invalid.", "Pass an integer from 0 through 65535.");
+			options.port = port;
+		}
+		await runPreview(options);
+	});
 	cli.command("doctor", "Check Node, git, brand, fonts, and Takumi").action(async (flags) => {
 		const result = await runDoctor(stringFlag(flags.cwd, process.cwd()));
 		if (flags.json === true) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
@@ -5014,7 +6377,7 @@ async function runCli(argv = process.argv) {
 		}
 		if (!result.ok) process.exitCode = 1;
 	});
-	cli.command("release", "Generate the release pack").option("--tag <tag>", "Release tag").option("--from <tag>", "Previous tag").option("--formats <list>", "Comma-separated formats").option("--templates <list>", "Comma-separated templates").option("--themes <dark|light|both>", "Themes to render").option("--copy", "Allow optional LLM copy (default: on when config.copy.llm is true)").option("--out <dir>", "Output directory").option("--strict", "Fit warnings exit with code 2").option("--dry-run", "Collect facts and print them; render nothing").option("--package <path>", "package.json path for monorepos").option("--upload", "Upload PNG files to the GitHub release").action(async (flags) => {
+	cli.command("release", "Generate the release pack").option("--tag <tag>", "Release tag").option("--from <tag>", "Previous tag").option("--formats <list>", "Comma-separated formats").option("--templates <list>", "Comma-separated templates").option("--themes <dark|light|both>", "Themes to render").option("--copy", "Allow optional LLM copy (default: on when config.copy.llm is true)").option("--out <dir>", "Output directory").option("--strict", "Fit warnings exit with code 2").option("--dry-run", "Collect facts and print them; render nothing").option("--package <path>", "package.json path for monorepos").option("--headline <text>", "Headline for the cards, overriding the changelog").option("--subheadline <text>", "Subheadline for the cards").option("--upload", "Upload PNG files to the GitHub release").action(async (flags) => {
 		const releaseFlags = {
 			cwd: stringFlag(flags.cwd, process.cwd()),
 			strict: flags.strict === true,
@@ -5023,6 +6386,10 @@ async function runCli(argv = process.argv) {
 		applySharedFlags(releaseFlags, flags);
 		const tag = optionalString(flags.tag);
 		if (tag !== void 0) releaseFlags.tag = tag;
+		const headline = optionalString(flags.headline);
+		if (headline !== void 0) releaseFlags.headline = headline;
+		const subheadline = optionalString(flags.subheadline);
+		if (subheadline !== void 0) releaseFlags.subheadline = subheadline;
 		const from = optionalString(flags.from);
 		if (from !== void 0) releaseFlags.from = from;
 		const templates = optionalString(flags.templates);