@popcraft/kit 0.30.0 → 0.32.0

package/src/templates/themes/comic-hero-page.ts

@@ -0,0 +1,326 @@
+// The comic hero pack's page and lettering kit: frames and tiers, panels as mask groups holding a generated picture,
+// and the letterer's tools (balloons with tails that point at the speaker, captions, sound effects).
+//
+// A page is a sheet laid out as a vertical stack of tiers (each a fixed box), and panels are placed in a tier at
+// hand-picked frames, so a frame can be a canted box, a wedge or a slanted slice. Every panel is a mask group of
+// [frame shape as mask, its ground, the picture, the ink edge]: the picture is clipped to the frame and a person can
+// drop their own into it. Touching frames get different grounds. Lettering sits in the tier, over the frames, so a
+// balloon can cross a gutter, placed along the reading path: left to right, top to bottom.
+
+import type { Kit } from '../kit'
+import type { VectorPath } from '@/lib/document/types'
+import { art, type ArtId } from './comic-hero-art'
+
+export interface Pt { x: number; y: number }
+export interface Frame { x: number; y: number; width: number; height: number; points: Pt[] }
+
+const COLORS = {
+  paper: '#F1ECE2', text: '#0E0D10', onPaper: '#3A3640',
+  primary: '#C8102E', onPrimary: '#FFFFFF',
+  accent: '#F5C518', onAccent: '#0E0D10',
+  card: '#FFFFFF', onCard: '#0E0D10',
+} as const
+
+/** The story's title and issue, as brand fields a kit or a person can change. */
+export const STORY = { title: 'Nightstar', series: 'Blackout', issue: 'No. 1' } as const
+
+/** A comic page's brand, its style's palette, its type and its lettering components. */
+export function comicSetup(k: Kit, o: { paper?: string } = {}) {
+  k.quantizeGeometry = true
+  k.brand({ ...COLORS, ...(o.paper ? { paper: o.paper } : {}) }, { title: STORY.title, series: STORY.series, issue: STORY.issue })
+  // The panels' grounds (seen only where a picture does not reach) and the ink that edges every frame.
+  k.palette({ heroG1: '#1B2238', heroG2: '#2E2A26', heroG3: '#3A1F24', heroInk: '#0E0D10' })
+  k.textStyle('Lettering', { size: 12, fontWeight: 800, lineHeight: 14, letterSpacing: 0, textAlign: 'CENTER' })
+  k.textStyle('Caption', { size: 11, fontWeight: 700, lineHeight: 14, letterSpacing: 0 })
+  const line = 2.5
+  // Balloons come in three widths, each its own component: an instance laid out at its component's width
+  // measures its words at that width, so a balloon is never asked to be narrower than the lines it was set in.
+  for (const [suffix, bw] of BALLOON_WIDTHS) {
+    k.component(`Speech balloon${suffix}`, { width: bw, padding: { top: 11, right: 14, bottom: 13, left: 14 }, radius: 22, fill: 'card', stroke: { color: 'onCard', width: line, align: 'INSIDE' }, align: 'CENTER', props: { Text: 'SAY SOMETHING.' } }, id => {
+      k.propText(id, 'Text', { style: 'Lettering', color: 'onCard', align: 'CENTER', width: 'FILL' })
+    })
+    k.component(`Thought balloon${suffix}`, { width: bw, padding: { top: 14, right: 16, bottom: 15, left: 16 }, radius: 26, fill: 'card', stroke: { color: 'onCard', width: line, align: 'INSIDE', dash: [3, 4] }, align: 'CENTER', props: { Text: 'WONDER ABOUT IT.' } }, id => {
+      k.propText(id, 'Text', { style: 'Lettering', color: 'onCard', align: 'CENTER', width: 'FILL' })
+    })
+  }
+}
+
+/** The display styles, each made the first time a page sets type in it (a style nobody uses is clutter). */
+const DISPLAY = {
+  'SFX': { size: 30, fontWeight: 900, fontStyle: 'italic' as const, lineHeight: 30, letterSpacing: -1, textAlign: 'CENTER' as const },
+  'SFX big': { size: 64, fontWeight: 900, fontStyle: 'italic' as const, lineHeight: 60, letterSpacing: -2.5, textAlign: 'CENTER' as const },
+  'Masthead': { size: 70, fontWeight: 900, lineHeight: 64, letterSpacing: -3.5, textAlign: 'CENTER' as const },
+  'Title': { size: 30, fontWeight: 900, lineHeight: 30, letterSpacing: -1 },
+  'Credit': { size: 10, fontWeight: 700, lineHeight: 12, letterSpacing: 1 },
+}
+const made = new WeakMap<Kit, Set<string>>()
+/** `name`, one of the display styles, made on first use. */
+export function display(k: Kit, name: keyof typeof DISPLAY): string {
+  const set = made.get(k) ?? new Set<string>()
+  made.set(k, set)
+  if (!set.has(name)) { k.textStyle(name, DISPLAY[name]); set.add(name) }
+  return name
+}
+
+/** The balloon components' widths: small, regular and wide. */
+const BALLOON_WIDTHS: [string, number][] = [[' (small)', 96], ['', 128], [' (wide)', 160]]
+const balloonFor = (w: number): [string, number] => BALLOON_WIDTHS.find(([, bw]) => w <= bw) ?? BALLOON_WIDTHS[BALLOON_WIDTHS.length - 1]
+
+// ─── Page geometry ────────────────────────────────────────────────────────────────────────────────────────────────
+
+export const rectFrame = (x: number, y: number, width: number, height: number): Frame =>
+  ({ x, y, width, height, points: [{ x: 0, y: 0 }, { x: width, y: 0 }, { x: width, y: height }, { x: 0, y: height }] })
+
+/** A frame from corners in tier space: its box, and the corners made panel-local. */
+export function frameOf(corners: Pt[]): Frame {
+  const xs = corners.map(p => p.x), ys = corners.map(p => p.y)
+  const x = Math.min(...xs), y = Math.min(...ys)
+  return { x: Math.round(x), y: Math.round(y), width: Math.round(Math.max(...xs) - x), height: Math.round(Math.max(...ys) - y), points: corners.map(p => ({ x: Math.round(p.x - x), y: Math.round(p.y - y) })) }
+}
+
+/** Widths filling `total` in the proportions `parts`, with `gutter` between them. */
+export function shares(total: number, gutter: number, parts: number[]): number[] {
+  const sum = parts.reduce((a, b) => a + b, 0), free = total - gutter * (parts.length - 1)
+  const out = parts.map(p => Math.floor((free * p) / sum))
+  out[out.length - 1] = free - out.slice(0, -1).reduce((a, b) => a + b, 0)
+  return out
+}
+
+/** A plain tier: rectangles side by side. */
+export function tier(width: number, height: number, parts: number[], gutter = 10, y = 0): Frame[] {
+  let x = 0
+  return shares(width, gutter, parts).map(w => { const f = rectFrame(x, y, w, height); x += w + gutter; return f })
+}
+
+/** A tier cut by SLANTED gutters (each leans `lean` px): frames that share a diagonal edge read as motion. */
+export function slantTier(width: number, height: number, parts: number[], lean = 24, gutter = 10, y = 0): Frame[] {
+  const widths = shares(width, gutter, parts), edges: number[] = [0]
+  widths.forEach((w, i) => edges.push(edges[i] + w + (i < widths.length - 1 ? gutter : 0)))
+  return widths.map((_, i) => {
+    const first = i === 0, last = i === widths.length - 1
+    const lTop = first ? 0 : edges[i] + lean, lBot = first ? 0 : edges[i] - lean
+    const rTop = last ? width : edges[i + 1] - gutter + lean, rBot = last ? width : edges[i + 1] - gutter - lean
+    return frameOf([{ x: lTop, y }, { x: rTop, y }, { x: rBot, y: y + height }, { x: lBot, y: y + height }])
+  })
+}
+
+/** A frame whose top and bottom edges tilt: `dy0` / `dy1` px down at the right end of each (a Dutch tier). */
+export function tilted(x: number, y: number, w: number, h: number, dyTop: number, dyBot: number): Frame {
+  return frameOf([{ x, y: y + Math.max(0, -dyTop) }, { x: x + w, y: y + Math.max(0, dyTop) }, { x: x + w, y: y + h - Math.max(0, -dyBot) }, { x, y: y + h - Math.max(0, dyBot) }])
+}
+
+/** A slice of a ring around (cx, cy): the radial page. */
+export function wedgeRing(cx: number, cy: number, rIn: number, rOut: number, from: number, to: number): Frame {
+  const pts: Pt[] = [], steps = 12
+  for (let i = 0; i <= steps; i++) { const a = ((from + ((to - from) * i) / steps) * Math.PI) / 180; pts.push({ x: cx + rOut * Math.cos(a), y: cy + rOut * Math.sin(a) }) }
+  for (let i = steps; i >= 0; i--) { const a = ((from + ((to - from) * i) / steps) * Math.PI) / 180; pts.push({ x: cx + rIn * Math.cos(a), y: cy + rIn * Math.sin(a) }) }
+  return frameOf(pts)
+}
+
+/** A circle (n-gon) frame: the radial page's hub. */
+export function disc(cx: number, cy: number, r: number): Frame {
+  return frameOf(Array.from({ length: 36 }, (_, i) => ({ x: cx + r * Math.cos((i * Math.PI) / 18), y: cy + r * Math.sin((i * Math.PI) / 18) })))
+}
+
+/** Grow a polygon from its centroid: the paper keyline an inset frame sits on. */
+export function inflate(points: Pt[], by: number): Pt[] {
+  const cx = points.reduce((a, p) => a + p.x, 0) / points.length, cy = points.reduce((a, p) => a + p.y, 0) / points.length
+  return points.map(p => { const dx = p.x - cx, dy = p.y - cy, d = Math.max(1, Math.hypot(dx, dy)); return { x: p.x + (dx / d) * by, y: p.y + (dy / d) * by } })
+}
+
+// ─── The page ─────────────────────────────────────────────────────────────────────────────────────────────────────
+
+/** A sheet as a column of tiers with `gutter` between them, inside `margin`. Returns the live area. */
+export function pageGrid(k: Kit, sheet: string, margin: number, gutter: number): { W: number; H: number } {
+  k.flowSheet(sheet, gutter, margin)
+  const n = k.node(sheet)
+  return { W: n.width - margin * 2, H: n.height - margin * 2 }
+}
+
+/** A tier: a fixed box in the sheet's column. */
+export const tierBox = (k: Kit, sheet: string, W: number, h: number, name: string) => k.stack(sheet, { width: W, height: h, name })
+
+/** Tier heights that fill `H` in proportion to `parts`, with `gutter` between. */
+export const rows = (H: number, gutter: number, parts: number[]) => shares(H, gutter, parts)
+
+/**
+ * A panel at frame `f` in `tierId`: a mask group of [the frame's shape as mask, its ground, picture `pic`, the ink
+ * edge]. `ground` is the panel's own ground (touching panels must differ). Returns the group.
+ */
+export function panel(k: Kit, tierId: string, f: Frame, pic: ArtId, o: { ground: Ground; name?: string; keyline?: number; edge?: boolean }): string {
+  if (o.keyline) {
+    const inTier = f.points.map(p => ({ x: p.x + f.x, y: p.y + f.y }))
+    const grown = inflate(inTier, o.keyline)
+    const xs = grown.map(p => p.x), ys = grown.map(p => p.y), gx = Math.max(0, Math.min(...xs)), gy = Math.max(0, Math.min(...ys))
+    const tierN = k.node(tierId)
+    const clamp = grown.map(p => ({ x: Math.min(tierN.width, Math.max(0, p.x)) - gx, y: Math.min(tierN.height, Math.max(0, p.y)) - gy }))
+    const bw = Math.max(...clamp.map(p => p.x)), bh = Math.max(...clamp.map(p => p.y))
+    k.vector(tierId, bw, bh, [{ closed: true, points: clamp }], 'paper', { name: 'Keyline', absolute: { x: gx, y: gy } })
+  }
+  const id = k.group(tierId, { x: f.x, y: f.y, width: f.width, height: f.height }, { name: o.name ?? 'Panel', absolute: true })
+  k.patch(id, { isMaskGroup: true, isPhotoFrame: true })
+  const shape: VectorPath = { closed: true, points: f.points.map(p => ({ x: p.x, y: p.y })) }
+  k.vector(id, f.width, f.height, [shape], 'paper', { name: 'Panel mask', mask: true })
+  k.rect(id, f.width, f.height, o.ground, { name: 'Ground' })
+  k.image(id, art(pic), f.width, f.height, { name: 'Picture' })
+  if (o.edge !== false) k.vector(id, f.width, f.height, [shape], [], { name: 'Panel edge', stroke: { color: 'heroInk', width: 3, join: 'MITER' } })
+  return id
+}
+
+/** The panel grounds: touching panels take different ones. */
+export type Ground = 'heroG1' | 'heroG2' | 'heroG3'
+
+// ─── Lettering ────────────────────────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * A speech balloon at (x, y) in the tier, `width` wide, its tail running from inside the balloon to `to` (the
+ * speaker's mouth, in tier space). The tail is drawn first, so the balloon covers its root and only the point shows.
+ */
+export function say(k: Kit, tierId: string, words: string, o: { x: number; y: number; width?: number; to?: Pt; thought?: boolean; name?: string }) {
+  const [suffix, w] = balloonFor(o.width ?? 128)
+  o = { ...o, ...within(k, tierId, o.x, o.y, w, 70) }
+  if (o.to) {
+    const root = { x: o.x + w * 0.5 + (o.to.x > o.x + w / 2 ? w * 0.12 : -w * 0.12), y: o.y + 16 }
+    // The tail stops short of the mouth: it points at the speaker, it does not touch them. The balloon's height is
+    // estimated from its words (about 6.6 px a capital at 12 px), so the tail runs some 30 px past its foot.
+    const lines = Math.ceil((words.length * 6.6) / (w - 28)), foot = o.y + 24 + lines * 14
+    const dist = Math.hypot(o.to.x - root.x, o.to.y - root.y) || 1, reach = Math.min(dist, Math.max(foot - root.y + 30, 34))
+    o = { ...o, to: { x: root.x + ((o.to.x - root.x) * reach) / dist, y: root.y + ((o.to.y - root.y) * reach) / dist } }
+    if (o.thought && o.to) {
+      // A thought trails off in bubbles toward the thinker.
+      const paths: VectorPath[] = []
+      for (let i = 1; i <= 3; i++) {
+        const t = 0.45 + i * 0.16, cx = root.x + (o.to.x - root.x) * t, cy = root.y + (o.to.y - root.y) * t, r = 7 - i * 1.6
+        paths.push({ closed: true, points: Array.from({ length: 10 }, (_, j) => ({ x: cx + r * Math.cos((j * Math.PI) / 5), y: cy + r * Math.sin((j * Math.PI) / 5) })) })
+      }
+      tailVector(k, tierId, paths, 'Thought bubble')
+    } else if (o.to) {
+      const dx = o.to.x - root.x, dy = o.to.y - root.y, len = Math.hypot(dx, dy) || 1, nx = -dy / len, ny = dx / len, half = 9
+      tailVector(k, tierId, [{ closed: true, points: [{ x: root.x + nx * half, y: root.y + ny * half }, { x: o.to.x, y: o.to.y }, { x: root.x - nx * half, y: root.y - ny * half }] }], 'Balloon tail')
+    }
+  }
+  return k.instance(tierId, `${o.thought ? 'Thought balloon' : 'Speech balloon'}${suffix}`, { Text: words.toUpperCase() }, { absolute: { x: Math.round(o.x), y: Math.round(o.y) }, name: o.name ?? (o.thought ? 'Thought' : 'Balloon') })
+}
+
+/** (x, y) pulled back so a `w` × `h` box stays inside the tier. */
+function within(k: Kit, tierId: string, x: number, y: number, w: number, h: number): Pt {
+  const t = k.node(tierId)
+  return { x: Math.max(0, Math.min(x, t.width - w)), y: Math.max(0, Math.min(y, t.height - h)) }
+}
+
+/** Paths in tier space as a card-filled, ink-lined layer boxed tight round them. */
+function tailVector(k: Kit, tierId: string, paths: VectorPath[], name: string) {
+  const xs = paths.flatMap(p => p.points.map(q => q.x)), ys = paths.flatMap(p => p.points.map(q => q.y))
+  const x0 = Math.min(...xs), y0 = Math.min(...ys)
+  const local = paths.map(p => ({ ...p, points: p.points.map(q => ({ x: q.x - x0, y: q.y - y0 })) }))
+  k.vector(tierId, Math.max(1, Math.max(...xs) - x0), Math.max(1, Math.max(...ys) - y0), local, 'card', { name, stroke: { color: 'onCard', width: 2, join: 'MITER' }, absolute: { x: x0, y: y0 } })
+}
+
+/** A caption box at (x, y): the narrator, in the corner where the reader's eye enters the panel. */
+export function caption(k: Kit, tierId: string, words: string, o: { x: number; y: number; width?: number; name?: string }) {
+  o = { ...o, ...within(k, tierId, o.x, o.y, o.width ?? 200, 50) }
+  const id = k.stack(tierId, { width: o.width ?? 200, padding: { top: 7, right: 10, bottom: 8, left: 10 }, fill: 'accent', stroke: { color: 'onAccent', width: 2, align: 'INSIDE', join: 'MITER' }, name: o.name ?? 'Caption box', absolute: { x: Math.round(o.x), y: Math.round(o.y) } })
+  k.text(id, words.replace(/(\{\{.*?\}\})|([^{]+)/g, (m, tok) => (tok ? m : m.toUpperCase())), { style: 'Caption', color: 'onAccent', width: 'FILL', name: 'Caption words' })
+  return id
+}
+
+/**
+ * A sound effect drawn into the art: the word on an impact star (accent, inked, on a hard ink shadow), tilted.
+ * `big` for the one hit a page is built round.
+ */
+export function sfx(k: Kit, tierId: string, words: string, o: { x: number; y: number; w: number; h: number; deg?: number; big?: boolean; fill?: 'accent' | 'primary'; seed?: number; name?: string }) {
+  const fill = o.fill ?? 'accent', ink = fill === 'accent' ? 'onAccent' : 'onPrimary'
+  // The burst is sized to its word: about 25 px a letter at 34 px (48 big), plus the spikes.
+  const need = words.length * (o.big ? 46 : 25) + 50
+  if (o.w < need) o = { ...o, h: Math.round(o.h * (need / o.w) ** 0.5), w: need }
+  o = { ...o, ...within(k, tierId, o.x, o.y, o.w, o.h) }
+  const id = k.stack(tierId, { width: o.w, height: o.h, align: 'CENTER', justify: 'CENTER', name: o.name ?? 'Sound effect', absolute: { x: Math.round(o.x), y: Math.round(o.y) } })
+  const n = 13, pts: Pt[] = []
+  let s = (o.seed ?? 7) >>> 0
+  const r = () => { s = (Math.imul(s, 1664525) + 1013904223) >>> 0; return s / 2 ** 32 }
+  for (let i = 0; i < n * 2; i++) {
+    const a = (i * Math.PI) / n - Math.PI / 2, rad = i % 2 ? 0.62 + r() * 0.08 : 0.9 + r() * 0.1
+    pts.push({ x: o.w / 2 + (o.w / 2) * rad * Math.cos(a), y: o.h / 2 + (o.h / 2) * rad * Math.sin(a) })
+  }
+  const star: VectorPath = { closed: true, points: pts }
+  k.vector(id, o.w, o.h, [star], ink, { name: 'Impact star shadow', absolute: { x: 0, y: 0 } })
+  k.vector(id, o.w, o.h, [{ closed: true, points: pts.map(p => ({ x: p.x - 5, y: p.y - 5 })) }], fill, { name: 'Impact star', stroke: { color: ink, width: 3, join: 'MITER' }, absolute: { x: 0, y: 0 } })
+  k.text(id, words.toUpperCase(), { style: display(k, o.big ? 'SFX big' : 'SFX'), color: ink, align: 'CENTER', name: 'Sound effect words', autoWidth: true })
+  if (o.deg) k.patch(id, { rotation: o.deg })
+  return id
+}
+
+/** The folio: the series and page number in the foot margin, on paper (the one line read off the art). */
+export const FOLIO = 24
+export function folio(k: Kit, sheet: string, words: string) {
+  k.text(sheet, words.toUpperCase(), { style: display(k, 'Credit'), color: 'text', width: 'FILL', name: 'Folio' })
+}
+
+/** A full-bleed sheet's foot: a paper strip under the art with the line in it, so the line is read on paper. */
+export function foot(k: Kit, tierId: string, w: number, h: number, words: string, name: string) {
+  const id = k.stack(tierId, { width: w, height: h, padding: { top: 14, right: 32, bottom: 14, left: 32 }, justify: 'CENTER', fill: 'text', name: 'Foot', absolute: { x: 0, y: k.node(tierId).height - h } })
+  k.text(id, words.toUpperCase(), { style: display(k, 'Title'), color: 'paper', width: 'FILL', name })
+  return id
+}
+
+/** The meta every comic page shares: a print page in the comic category. */
+export function comicMeta(name: string, description: string, tags: string[]) {
+  return {
+    name, description, category: 'comic', tags: ['comic', 'print', 'nightstar', 'action', ...tags],
+    platforms: ['print' as const], formats: ['page' as const], useCases: ['comic' as const],
+    created: '2026-09-22', updated: '2026-10-11',
+  }
+}
+
+/** A frame the size of the sheet plus its bleed on every side, for a tier at the sheet's origin. */
+export function bleedFrame(k: Kit, w: number, h: number): Frame {
+  const b = k.doc.settings?.bleed
+  const [l, t, r, bo] = [b?.left ?? 0, b?.top ?? 0, b?.right ?? 0, b?.bottom ?? 0]
+  return rectFrame(-l, -t, w + l + r, h + t + bo)
+}
+
+/** The comic page and spread sizes in px. */
+export const SIZE = {
+  page: { w: Math.round(6.625 * 96), h: Math.round(10.25 * 96) },
+  cover: { w: Math.round(6.875 * 96), h: Math.round(10.5 * 96) },
+  spread: { w: Math.round(13.25 * 96), h: Math.round(10.25 * 96) },
+} as const
+
+/** A polygon (tier space) cut to the tier's box, as a frame. */
+export function clipFrame(pts: Pt[], w: number, h: number): Frame {
+  const edges: [(p: Pt) => boolean, (a: Pt, b: Pt) => Pt][] = [
+    [p => p.x >= 0, (a, b) => ({ x: 0, y: a.y + ((b.y - a.y) * (0 - a.x)) / (b.x - a.x) })],
+    [p => p.x <= w, (a, b) => ({ x: w, y: a.y + ((b.y - a.y) * (w - a.x)) / (b.x - a.x) })],
+    [p => p.y >= 0, (a, b) => ({ x: a.x + ((b.x - a.x) * (0 - a.y)) / (b.y - a.y), y: 0 })],
+    [p => p.y <= h, (a, b) => ({ x: a.x + ((b.x - a.x) * (h - a.y)) / (b.y - a.y), y: h })],
+  ]
+  let out = pts
+  for (const [inside, cross] of edges) {
+    const src = out
+    out = []
+    for (let i = 0; i < src.length; i++) {
+      const a = src[i], b = src[(i + 1) % src.length]
+      if (inside(a)) { out.push(a); if (!inside(b)) out.push(cross(a, b)) } else if (inside(b)) out.push(cross(a, b))
+    }
+  }
+  return frameOf(out)
+}
+
+/**
+ * A slice of the page around a hub at (cx, cy): from angle `from` to `to` (degrees, clockwise from +x), starting
+ * `rIn` out, with gutters of even width `g` along both radial edges, running out to the tier's edges.
+ */
+export function radialSlice(cx: number, cy: number, rIn: number, from: number, to: number, g: number, w: number, h: number): Frame {
+  const R = Math.hypot(w, h) * 2, pts: Pt[] = []
+  const edge = (deg: number, side: number, t: number): Pt => {
+    const a = (deg * Math.PI) / 180, d = { x: Math.cos(a), y: Math.sin(a) }, n = { x: -Math.sin(a), y: Math.cos(a) }
+    return { x: cx + n.x * side * (g / 2) + d.x * t, y: cy + n.y * side * (g / 2) + d.y * t }
+  }
+  const steps = 8
+  for (let i = 0; i <= steps; i++) { const a = ((from + ((to - from) * i) / steps) * Math.PI) / 180; pts.push({ x: cx + rIn * Math.cos(a), y: cy + rIn * Math.sin(a) }) }
+  pts.push(edge(to, -1, R))
+  const mid = (((from + to) / 2) * Math.PI) / 180
+  pts.push({ x: cx + R * 1.5 * Math.cos(mid), y: cy + R * 1.5 * Math.sin(mid) })
+  pts.push(edge(from, 1, R))
+  return clipFrame(pts, w, h)
+}

package/src/templates/themes/comic-hero.ts

@@ -1,5 +1,18 @@
-// Comic hero pack: one gritty action series (generated art, editable lettering). Registered empty so its pack PR never edits index.ts; every source in it, in gallery order.
+// Comic hero pack: one gritty action series (generated art, editable lettering), "Nightstar: Blackout", in reading
+// order: cover, the chase, the fight, the blackout, the last punch, the questions and the pin-up.
 import type { TemplateSource } from '../build'
+import heroCoverModern from '../print/comic-hero-cover-modern'
+import heroChase from '../print/comic-hero-chase'
+import heroWidescreen from '../print/comic-hero-widescreen'
+import heroGridBreak from '../print/comic-hero-grid-break'
+import heroCascade from '../print/comic-hero-cascade'
+import heroOverlap from '../print/comic-hero-overlap'
+import heroNested from '../print/comic-hero-nested'
+import heroParallel from '../print/comic-hero-parallel'
+import heroMangaAction from '../print/comic-hero-manga-action'
+import heroInterrogation from '../print/comic-hero-interrogation'
+import heroPinup from '../print/comic-hero-pinup'
+import heroIssue from '../print/comic-hero-issue'
 
-const pack: readonly TemplateSource[] = []
+const pack: readonly TemplateSource[] = [heroCoverModern, heroChase, heroWidescreen, heroGridBreak, heroCascade, heroOverlap, heroNested, heroParallel, heroMangaAction, heroInterrogation, heroPinup, heroIssue]
 export default pack

package/src/templates/themes/comic-indie-art.ts

@@ -0,0 +1,73 @@
+// "Last Summer on Alder Street"'s art: one picture a panel, made for these pages with an image model (GPT Image 2,
+// through the Vercel AI Gateway) from one style line and one fixed sentence per character, so the cast stays on model
+// from page to page. Shipped as the portfolios' art is (../web/portfolio-art.ts): JPEG under the media store's
+// content hash in public/templates/media. Made for these templates: free to use with them.
+
+export const INDIE_ART = {
+  'gag-1': { hash: '7278309005e257083761d335f87c1ea2', width: 1280, height: 853, subject: "Wide shot of a cluttered sunny flat kitchen in the morning: Theo carries a stack of empty cardboard boxes past Juno, who sits at the table with a coffee mug, not looking up." },
+  'gag-2': { hash: '74c096aec779b8b2d3dd47dd0d02d93b', width: 1280, height: 853, subject: "Same kitchen, same framing: Theo carries an even taller stack of cardboard boxes past Juno, who now peers over her mug at him." },
+  'gag-3': { hash: 'a8dbddf1dd83322ed04c2ab535638359', width: 1280, height: 853, subject: "Same kitchen: the boxes are stacked to the ceiling, Juno stands up, arms folded, eyebrow raised at Theo who freezes guiltily." },
+  'gag-4': { hash: '01fa53b2ac15ff9dfc7b533e9ac1df57', width: 1280, height: 853, subject: "Close medium shot: Theo sheepishly offers Juno a single roll of packing tape like a gift, Juno deadpan." },
+  'strip-1': { hash: '703aed5d82aa21a0a7cab51feab13bee', width: 1280, height: 853, subject: "Juno opens the flat's front door to find Mrs Okafor holding a huge leggy tomato plant in a pot, warm hallway light." },
+  'strip-2': { hash: '23a1d00f97b7e08e75eaf84714d789c3', width: 1280, height: 853, subject: "Mrs Okafor pushes the tomato plant into Juno's arms, smiling knowingly; Juno awkward, leaves in her face." },
+  'strip-3': { hash: 'd7492163159c81911b0e81776946286c', width: 1280, height: 853, subject: "Juno alone in the hallway hugging the giant tomato plant, looking toward a half-packed box in the background, a little lost." },
+  'talk-1': { hash: 'b9ea25bab982909e9883639ba12f0a86', width: 1280, height: 853, subject: "Two-shot: Juno and Theo sit at opposite ends of a worn green sofa in a small living room at dusk, lamp light, boxes behind them." },
+  'talk-2': { hash: '87f0dba9b035f0c3464211cb208ae348', width: 853, height: 1280, subject: "Close-up profile of Theo facing right, eyes down, rubbing the back of his neck, warm lamp light." },
+  'talk-3': { hash: 'c81ce1b77f0e3a030e56cc8753b633d5', width: 853, height: 1280, subject: "Close-up profile of Juno facing left, jaw set, glasses catching lamp light." },
+  'talk-4': { hash: 'a85bb81ceb51c2571a75de40f4fa7369', width: 853, height: 1280, subject: "Close-up of Theo turning to face us, earnest, a small apologetic smile." },
+  'talk-5': { hash: 'd71d59b54e57edcd73744e754fd9e1a2', width: 853, height: 1280, subject: "Close-up of Juno looking away out a window, sunset colours on her face, eyes wet but not crying." },
+  'talk-6': { hash: '23f5f1d9ed62e4a581b6d100da88ca7b', width: 1280, height: 853, subject: "Two-shot from behind the sofa: Juno and Theo now sitting closer, both looking at the window, shoulders almost touching." },
+  'silent-1': { hash: 'c720a8acf2f8d1327884e800a82b8fbb', width: 1280, height: 853, subject: "Juno walks out of a red-brick terraced house onto a quiet tree-lined street at golden hour, hands in cardigan pockets." },
+  'silent-2': { hash: '9512d89de474ecc6993d23db349b7bc7', width: 1024, height: 1024, subject: "Juno passes a corner shop with crates of fruit outside, glancing at a cafe where two chairs sit empty." },
+  'silent-3': { hash: '3c96304d31faebcf83fabf1139bae4b5', width: 1024, height: 1024, subject: "Close-up of Juno's hand brushing along a chain-link fence covered in morning glories." },
+  'silent-4': { hash: 'f6000b487b383f1f80659128b5f2e918', width: 1024, height: 1024, subject: "Juno stops on a small footbridge over a canal, leaning on the rail, sunset reflecting in the water." },
+  'silent-5': { hash: '11a48aed6ac5a63ee1f2453ed9158310', width: 1024, height: 1024, subject: "A narrowboat drifts under the footbridge on a golden canal, ducks in its wake, no people visible." },
+  'silent-6': { hash: '49f8e54dd649900ebf68d781355dc68d', width: 1280, height: 853, subject: "Juno, small in the frame, sits on a bench by the canal under a huge orange evening sky." },
+  'neg-1': { hash: 'a4e2acb20644b2676056e5a77cbe2c54', width: 853, height: 1280, subject: "Juno sits alone on the worn wooden stairs of an old apartment stairwell, knees hugged, single warm light from above, lots of dark shadow." },
+  'neg-2': { hash: '91581bb8ab834a4f3726fe7b67c2454c', width: 1024, height: 1024, subject: "Mrs Okafor lowers herself to sit beside Juno on the stairs, offering her a small paper bag of plums." },
+  'neg-3': { hash: 'add60674b9245b03ff9f05a695da729b', width: 1280, height: 853, subject: "Juno and Mrs Okafor seen small from the top of the stairwell, sitting side by side eating plums, deep shadows around them." },
+  'riso-1': { hash: '885801e1cd1c8e6afd5413c22f3a0423', width: 1280, height: 853, subject: "Flashback, years earlier: younger Juno and Theo struggle to carry a green sofa up a narrow staircase, laughing." },
+  'riso-2': { hash: '3f1f03442ea4c3f235e1677bc29baf8e', width: 1024, height: 1024, subject: "Flashback: Juno and Theo sitting on the floor of an empty flat eating takeaway noodles from cartons by candlelight." },
+  'riso-3': { hash: '7f28cf9edf034e02648cecc863dfddac', width: 1024, height: 1024, subject: "Flashback: Theo painting a wall of the empty flat a warm terracotta colour, paint on his nose." },
+  'riso-4': { hash: 'd3215f1687917d6c093c326b766b98c2', width: 1024, height: 1024, subject: "Flashback: younger Mrs Okafor in her doorway hands Juno a spare key on a red string." },
+  'riso-5': { hash: 'f842fdebf33c9e05df871ef7ff94a65e', width: 1024, height: 1024, subject: "Flashback: Juno putting a small tomato seedling in a pot on a windowsill." },
+  'riso-6': { hash: 'd5d1426f40a95fd777cc85feefec496d', width: 1280, height: 853, subject: "Flashback: Juno and Theo asleep on the green sofa in the unpacked flat, morning sun pouring in." },
+  'zine-1': { hash: '5d076bd8c3c6a0e13dd3bfa6e365d96c', width: 1024, height: 1024, subject: "Juno and Theo sprawled on the living-room floor drawing a party flyer with markers, scissors and glue around them." },
+  'zine-2': { hash: 'a9481090802497624cb73a623e5eb2b7', width: 1024, height: 1024, subject: "Theo cutting out a paper sun shape with scissors, tongue poking out in concentration." },
+  'zine-3': { hash: '57fa82febd9a935169d62325a0e1e4c6', width: 1024, height: 1024, subject: "Juno feeding a sheet into an old photocopier in a tiny print shop lit pink." },
+  'zine-4': { hash: 'db42a2bb05dd170319d2f69ee7381ecf', width: 1024, height: 1024, subject: "Juno and Theo holding up warm fresh photocopies, grinning, in the print shop." },
+  'zine-5': { hash: 'aadef44e85bd40011e22b2b6fa96a92e', width: 1024, height: 1024, subject: "Juno taping a flyer to a lamp post on the street at evening." },
+  'zine-6': { hash: 'fc15cc0a1d2b05148bd79042c9094378', width: 1024, height: 1024, subject: "Mrs Okafor reading a flyer slid under her door, smiling, reading glasses on her nose." },
+  'web-1': { hash: 'c3d34559e732a1489f6f38746fd0b1b5', width: 1280, height: 853, subject: "Juno and Theo climb a ladder through a hatch onto a flat tar rooftop carrying a tangle of string lights." },
+  'web-2': { hash: '6a4e270e1205bcf3d96fabed6c73f32f', width: 1280, height: 853, subject: "Theo balancing on an upturned crate hanging string lights between two chimneys, sky turning orange." },
+  'web-3': { hash: 'c59a21c74bf19a77966eb9f5d1855d23', width: 1280, height: 853, subject: "Juno arranging mismatched chairs and potted plants on the rooftop, the tomato plant in pride of place." },
+  'web-4': { hash: 'f74227b40602a67fee78ff5716a59f15', width: 1280, height: 853, subject: "Close-up of string lights flickering on against a deep orange and violet sky over rooftops." },
+  'web-5': { hash: '1b5867887ae2ef854abacce4265074ab', width: 1280, height: 853, subject: "Wide shot: the finished rooftop with glowing lights, Juno and Theo standing back admiring it, city skyline at dusk." },
+  'manga-1': { hash: '26bc139ef62bce888d2c74f9ed2cd3b2', width: 1280, height: 853, subject: "Lively rooftop party at dusk: friends dancing under string lights, Mrs Okafor holding a plate of food, Juno and Theo laughing in the middle." },
+  'manga-2': { hash: '38042d09bd02f9a1705ac3c5d762aaa5', width: 853, height: 1280, subject: "Mrs Okafor dancing with surprising energy, arms raised, under the string lights." },
+  'manga-3': { hash: '7293bb7864906a4ca7e032fcec439e22', width: 1024, height: 1024, subject: "Close-up: a fat raindrop splashes onto a paper plate of jollof rice on the rooftop." },
+  'manga-4': { hash: '20905e8fc620309c95b8e0791f5106eb', width: 1280, height: 853, subject: "Sudden heavy summer rain on the rooftop, Juno and Theo scrambling to cover the record player with a jacket, both soaked and laughing." },
+  'manga-5': { hash: 'e25acbb7127fa8477f3883c00de13b57', width: 1024, height: 1024, subject: "Mrs Okafor calmly opening a huge golf umbrella in the rain." },
+  'manga-6': { hash: '86c6caef7d63da6bd2de241dc797f929', width: 1280, height: 853, subject: "Juno, Theo and Mrs Okafor squeezed together under one big umbrella on the wet rooftop, lights reflecting in puddles." },
+  'icon-1': { hash: '1356a79a188f5eef8fe728b918b7f557', width: 900, height: 900, subject: "Two mismatched coffee mugs side by side on a sunlit kitchen windowsill, still life." },
+  'icon-2': { hash: '389c17f33c4caa20ebce699d7c54193d', width: 900, height: 900, subject: "A ring of keys on a red string hanging on a hook by a door, still life." },
+  'icon-3': { hash: 'fed8cc1df96978caa384a1145334c228', width: 900, height: 900, subject: "A potted tomato plant heavy with red tomatoes on a windowsill, still life." },
+  'icon-4': { hash: '470f93f1619abe9669fec1f8380868ca', width: 900, height: 900, subject: "A stack of vinyl records leaning against a green sofa, still life." },
+  'icon-5': { hash: '5d7e780cb6c9885df54232c4557a2992', width: 900, height: 900, subject: "A taped cardboard box with a bicycle helmet on top, still life." },
+  'icon-6': { hash: 'dfc999e2f0c13dd3d7831a5cb7199650', width: 900, height: 900, subject: "A wall with a terracotta-painted patch and pencil height marks, still life." },
+  'icon-7': { hash: '658b68e0fdd56fe3463d06db380e82d9', width: 900, height: 900, subject: "Two toothbrushes in one cup in a small tiled bathroom, still life." },
+  'icon-8': { hash: '419e000f9e5f13053a2bdb5def981789', width: 900, height: 900, subject: "A rumpled blanket on an empty green sofa in evening light, still life." },
+  'icon-9': { hash: 'd923966ad48dda7a1ca0ab4bed402661', width: 900, height: 900, subject: "An open window with a curtain blowing, a sunset sky outside, still life." },
+  'hour-1': { hash: 'a3d065213622660994c37684a5b576a1', width: 1280, height: 853, subject: "Wide shot: Juno and Theo sit on the edge of the rooftop at sunset, legs dangling, the city spread below." },
+  'hour-2': { hash: '3d8f4de451b45e44fc2f985c40c1a76c', width: 1280, height: 853, subject: "Medium shot: Theo hands Juno one of the red-string spare keys, Juno looks at it." },
+  'hour-3': { hash: '199e5d72656c0a6201fc3660cd5ef6e7', width: 1024, height: 1024, subject: "Extreme close-up of Juno's hand closing around a key on a red string, sunset light." },
+  'hour-4': { hash: '58726efa52734b9f560123c086b44ded', width: 1280, height: 853, subject: "Juno rests her head on Theo's shoulder, both looking at the sunset, back view." },
+  'hour-5': { hash: '823c59f93e221b37145a2e6fb346d1d3', width: 1280, height: 853, subject: "Very wide shot: two tiny silhouettes on the rooftop against an enormous orange and pink sunset sky." },
+  'back-1': { hash: 'be8e16cc738e2a3c6c15a426534885ba', width: 900, height: 900, subject: "Theo waving from the window of a departing train, a duffel bag beside him, morning light." },
+  'back-2': { hash: '76cabed26da043b88bb115fb65bf45a7', width: 900, height: 900, subject: "Juno and Mrs Okafor watering the tomato plant together on a sunny windowsill, smiling." },
+} as const
+
+export type IndieArtId = keyof typeof INDIE_ART
+
+/** A panel's picture address in a design: the media store's, by its hash. */
+export const indieArt = (id: IndieArtId): string => `media://${INDIE_ART[id].hash}`

package/src/templates/themes/comic-indie-page.ts

@@ -0,0 +1,182 @@
+// The indie comic pages' kit: "Last Summer on Alder Street", one slice-of-life story told across the comic formats.
+// The art is generated (comic-indie-art.ts); everything a person reads is lettering they can edit. A page is a sheet
+// laid out as a vertical stack of tiers, and each panel is a mask group of [frame shape as mask, its ground, the art,
+// the ink edge], so the art is clipped to the frame and a person can drop their own picture into it. Lettering sits
+// in the tier, over the frames, along the reading path.
+
+import type { Kit } from '../kit'
+import type { Effect, VectorPath } from '@/lib/document/types'
+import { indieArt, type IndieArtId } from './comic-indie-art'
+
+export interface Pt { x: number; y: number }
+export interface Frame { x: number; y: number; width: number; height: number; points: Pt[] }
+
+const COLORS = {
+  paper: '#FBF1E4', text: '#2A1E1A', onPaper: '#4A3A35',
+  primary: '#D9603B', onPrimary: '#FFF8EE',
+  accent: '#F6C66B', onAccent: '#2A1E1A',
+  card: '#FFF8EE', onCard: '#2A1E1A',
+} as const
+
+/** The panels' grounds (what shows while art loads, or if a person removes it) and the ink. */
+const GROUNDS = { g1: '#F2A65A', g2: '#C8553D', g3: '#6E4B6B', g4: '#F7D9A8', ink: '#2A1E1A' } as const
+
+export const STORY = { title: 'Last Summer on Alder Street', series: 'Alder Street', issue: 'No. 1' } as const
+
+/** A page's brand, palette, type and lettering components. */
+export function indieSetup(k: Kit) {
+  k.quantizeGeometry = true
+  k.brand({ ...COLORS }, { title: STORY.title, series: STORY.series, issue: STORY.issue })
+  k.palette({ ...GROUNDS })
+  k.textStyle('Lettering', { size: 12, fontWeight: 700, lineHeight: 14, letterSpacing: 0, textAlign: 'CENTER' })
+  k.textStyle('Caption', { size: 11, fontWeight: 600, lineHeight: 14, letterSpacing: 0 })
+  for (const [suffix, bw] of BALLOON_WIDTHS) {
+    k.component(`Speech balloon${suffix}`, { width: bw, padding: { top: 10, right: 13, bottom: 12, left: 13 }, radius: 22, fill: 'card', stroke: { color: 'onCard', width: 2, align: 'INSIDE' }, align: 'CENTER', props: { Text: 'Say something.' } }, id => {
+      k.propText(id, 'Text', { style: 'Lettering', color: 'onCard', align: 'CENTER', width: 'FILL' })
+    })
+  }
+}
+
+const DISPLAY = {
+  'SFX': { size: 26, fontWeight: 900, fontStyle: 'italic' as const, lineHeight: 26, letterSpacing: -1, textAlign: 'CENTER' as const },
+  'Title': { size: 26, fontWeight: 900, lineHeight: 28, letterSpacing: -0.5 },
+  'Masthead': { size: 40, fontWeight: 900, lineHeight: 40, letterSpacing: -1.5 },
+  'Body': { size: 11, fontWeight: 400, lineHeight: 16, letterSpacing: 0 },
+  'Credit': { size: 9, fontWeight: 700, lineHeight: 12, letterSpacing: 1 },
+}
+const made = new WeakMap<Kit, Set<string>>()
+/** One of the display styles, made on first use. */
+export function display(k: Kit, name: keyof typeof DISPLAY): string {
+  const set = made.get(k) ?? new Set<string>()
+  made.set(k, set)
+  if (!set.has(name)) { k.textStyle(name, DISPLAY[name]); set.add(name) }
+  return name
+}
+
+const BALLOON_WIDTHS: [string, number][] = [[' (small)', 96], ['', 128], [' (wide)', 168]]
+const balloonFor = (w: number): [string, number] => BALLOON_WIDTHS.find(([, bw]) => w <= bw) ?? BALLOON_WIDTHS[BALLOON_WIDTHS.length - 1]
+
+// ─── Geometry ─────────────────────────────────────────────────────────────────────────────────────────────────────
+
+export const rectFrame = (x: number, y: number, width: number, height: number): Frame =>
+  ({ x, y, width, height, points: [{ x: 0, y: 0 }, { x: width, y: 0 }, { x: width, y: height }, { x: 0, y: height }] })
+
+/** A frame from corners in tier space. */
+export function frameOf(corners: Pt[]): Frame {
+  const xs = corners.map(p => p.x), ys = corners.map(p => p.y)
+  const x = Math.min(...xs), y = Math.min(...ys)
+  return { x: Math.round(x), y: Math.round(y), width: Math.round(Math.max(...xs) - x), height: Math.round(Math.max(...ys) - y), points: corners.map(p => ({ x: Math.round(p.x - x), y: Math.round(p.y - y) })) }
+}
+
+export function shares(total: number, gutter: number, parts: number[]): number[] {
+  const sum = parts.reduce((a, b) => a + b, 0), free = total - gutter * (parts.length - 1)
+  const out = parts.map(p => Math.floor((free * p) / sum))
+  out[out.length - 1] = free - out.slice(0, -1).reduce((a, b) => a + b, 0)
+  return out
+}
+
+/** Rectangles side by side. */
+export function tier(width: number, height: number, parts: number[], gutter = 10): Frame[] {
+  let x = 0
+  return shares(width, gutter, parts).map(w => { const f = rectFrame(x, 0, w, height); x += w + gutter; return f })
+}
+
+/** Frames side by side on gutters that lean `lean` px. */
+export function slantTier(width: number, height: number, parts: number[], lean = 16, gutter = 10): Frame[] {
+  const widths = shares(width, gutter, parts), edges: number[] = [0]
+  widths.forEach((w, i) => edges.push(edges[i] + w + (i < widths.length - 1 ? gutter : 0)))
+  return widths.map((_, i) => {
+    const first = i === 0, last = i === widths.length - 1
+    const lTop = first ? 0 : edges[i] + lean, lBot = first ? 0 : edges[i] - lean
+    const rTop = last ? width : edges[i + 1] - gutter + lean, rBot = last ? width : edges[i + 1] - gutter - lean
+    return frameOf([{ x: lTop, y: 0 }, { x: rTop, y: 0 }, { x: rBot, y: height }, { x: lBot, y: height }])
+  })
+}
+
+/** A sheet as a column of tiers. Returns the live area. */
+export function pageGrid(k: Kit, sheet: string, margin: number, gutter: number): { W: number; H: number } {
+  k.flowSheet(sheet, gutter, margin)
+  const n = k.node(sheet)
+  return { W: n.width - margin * 2, H: n.height - margin * 2 - FOLIO - gutter }
+}
+
+/** The folio line under the page's last tier: the series and the page's own title, on the paper. */
+const FOLIO = 14
+export function folio(k: Kit, sheet: string, label: string) {
+  const row = k.stack(sheet, { width: 'FILL', height: FOLIO, direction: 'HORIZONTAL', justify: 'SPACE_BETWEEN', align: 'CENTER', name: 'Folio' })
+  k.text(row, STORY.title, { style: display(k, 'Credit'), color: 'text', name: 'Folio title' })
+  k.text(row, label, { style: display(k, 'Credit'), color: 'onPaper', name: 'Folio label' })
+}
+
+export const tierBox = (k: Kit, sheet: string, W: number, h: number, name: string, fill?: string) =>
+  k.stack(sheet, { width: W, height: h, name, ...(fill ? { fill } : {}) })
+
+export const rows = (H: number, gutter: number, parts: number[]) => shares(H, gutter, parts)
+
+/** A Ben-Day screen: the one flashback page's second plate. */
+const TONE: Effect[] = [{ id: 'e1', type: 'HALFTONE', angle: 45, dotSize: 7, contrast: 0.5, colorMode: 'SOURCE', shape: 'CIRCLE', layout: 'UNIFORM', toneSource: 'LINEAR_GRADIENT', gradientAngle: 90, center: { x: 0.5, y: 0.5 }, visible: true } as Effect]
+
+/** A panel at frame `f`: a mask group of [shape as mask, ground, art, (tone), ink edge]. */
+export function panel(k: Kit, tierId: string, f: Frame, art: IndieArtId, o: { ground: keyof typeof GROUNDS; name: string; tone?: boolean; keyline?: boolean }): string {
+  if (o.keyline) k.rect(tierId, f.width + 12, f.height + 12, 'paper', { name: 'Keyline', absolute: { x: f.x - 6, y: f.y - 6 } })
+  const id = k.group(tierId, { x: f.x, y: f.y, width: f.width, height: f.height }, { name: o.name, absolute: true })
+  k.patch(id, { isMaskGroup: true, isPhotoFrame: true })
+  const shape: VectorPath = { closed: true, points: f.points.map(p => ({ x: p.x, y: p.y })) }
+  k.vector(id, f.width, f.height, [shape], 'paper', { name: 'Panel mask', mask: true })
+  k.rect(id, f.width, f.height, o.ground, { name: 'Ground' })
+  k.image(id, indieArt(art), f.width, f.height, { name: `${o.name} art` })
+  if (o.tone) { const t = k.rect(id, f.width, f.height, 'g3', { name: 'Ben-Day screen', effects: TONE, opacity: 0.35 }); k.patch(t, { blendMode: 'MULTIPLY' }) }
+  k.vector(id, f.width, f.height, [shape], [], { name: 'Panel edge', stroke: { color: 'ink', width: 2.5, join: 'ROUND' } })
+  return id
+}
+
+// ─── Lettering ────────────────────────────────────────────────────────────────────────────────────────────────────
+
+/** A speech balloon at (x, y) in the tier, its tail pointing toward `to` (the speaker, in tier space). */
+export function say(k: Kit, tierId: string, words: string, o: { x: number; y: number; width?: number; to?: Pt; name?: string }) {
+  const [suffix, w] = balloonFor(o.width ?? 128)
+  if (o.to) {
+    const root = { x: o.x + w * 0.5 + (o.to.x > o.x + w / 2 ? w * 0.12 : -w * 0.12), y: o.y + 16 }
+    const lines = Math.ceil((words.length * 6.2) / (w - 26)), foot = o.y + 22 + lines * 14
+    const dist = Math.hypot(o.to.x - root.x, o.to.y - root.y) || 1, reach = Math.min(dist, Math.max(foot - root.y + 22, 30))
+    const to = { x: root.x + ((o.to.x - root.x) * reach) / dist, y: root.y + ((o.to.y - root.y) * reach) / dist }
+    const dx = to.x - root.x, dy = to.y - root.y, len = Math.hypot(dx, dy) || 1, nx = -dy / len, ny = dx / len, half = 8
+    const pts = [{ x: root.x + nx * half, y: root.y + ny * half }, to, { x: root.x - nx * half, y: root.y - ny * half }]
+    const x0 = Math.min(...pts.map(p => p.x)), y0 = Math.min(...pts.map(p => p.y))
+    k.vector(tierId, Math.max(1, Math.max(...pts.map(p => p.x)) - x0), Math.max(1, Math.max(...pts.map(p => p.y)) - y0),
+      [{ closed: true, points: pts.map(p => ({ x: p.x - x0, y: p.y - y0 })) }], 'card', { name: 'Balloon tail', stroke: { color: 'onCard', width: 2, join: 'ROUND' }, absolute: { x: x0, y: y0 } })
+  }
+  return k.instance(tierId, `Speech balloon${suffix}`, { Text: words }, { absolute: { x: Math.round(o.x), y: Math.round(o.y) }, name: o.name ?? 'Balloon' })
+}
+
+/** A caption box: the narrator. */
+export function caption(k: Kit, tierId: string, words: string, o: { x: number; y: number; width?: number; name?: string }) {
+  const id = k.stack(tierId, { width: o.width ?? 200, padding: { top: 6, right: 9, bottom: 7, left: 9 }, fill: 'accent', stroke: { color: 'onAccent', width: 1.5, align: 'INSIDE' }, name: o.name ?? 'Caption box', absolute: { x: Math.round(o.x), y: Math.round(o.y) } })
+  k.text(id, words, { style: 'Caption', color: 'onAccent', width: 'FILL', name: 'Caption words' })
+  return id
+}
+
+/** A small sound effect on a soft impact star. */
+export function sfx(k: Kit, tierId: string, words: string, o: { x: number; y: number; w: number; h: number; deg?: number; seed?: number; name?: string }) {
+  const id = k.stack(tierId, { width: o.w, height: o.h, align: 'CENTER', justify: 'CENTER', name: o.name ?? 'Sound effect', absolute: { x: Math.round(o.x), y: Math.round(o.y) } })
+  const n = 11, pts: Pt[] = []
+  let s = (o.seed ?? 7) >>> 0
+  const r = () => { s = (Math.imul(s, 1664525) + 1013904223) >>> 0; return s / 2 ** 32 }
+  for (let i = 0; i < n * 2; i++) {
+    const a = (i * Math.PI) / n - Math.PI / 2, rad = i % 2 ? 0.7 + r() * 0.06 : 0.92 + r() * 0.08
+    pts.push({ x: o.w / 2 + (o.w / 2) * rad * Math.cos(a), y: o.h / 2 + (o.h / 2) * rad * Math.sin(a) })
+  }
+  k.vector(id, o.w, o.h, [{ closed: true, points: pts }], 'accent', { name: 'Impact star', stroke: { color: 'onAccent', width: 2, join: 'ROUND' }, absolute: { x: 0, y: 0 } })
+  k.text(id, words, { style: display(k, 'SFX'), color: 'onAccent', align: 'CENTER', name: 'Sound effect words', autoWidth: true })
+  if (o.deg) k.patch(id, { rotation: o.deg })
+  return id
+}
+
+/** The meta every page of the story shares. */
+export function indieMeta(name: string, description: string, tags: string[]) {
+  return {
+    name, description, category: 'comic', tags: ['comic', 'print', 'alder street', 'slice of life', 'indie', ...tags],
+    platforms: ['print' as const], formats: ['page' as const], useCases: ['comic' as const],
+    created: '2026-09-22', updated: '2026-10-10',
+  }
+}