create-tanqory-theme 0.0.0-stage → 0.2.2

package/templates/nova/src/sections/Testimonials/schema.ts

@@ -0,0 +1,35 @@
+import { defineSchema, field } from '@tanqory/theme-kit'
+import { shared } from '../../components/section/shared'
+
+/**
+ * 12F · 01 testimonials (EXISTING · CHANGED) — quotes the merchant chose.
+ * Grid or carousel of 1–3 columns (1 = spotlight, one large quote); a swipe
+ * row at 390 for both. Stars are each testimonial's own rating field, never
+ * review data. Carousels here never autoplay for new setups; a saved
+ * autoplay (LEGACY-HIDDEN) keeps rotating with a pause button.
+ */
+export const testimonialsSchema = defineSchema(
+  { kind: 'section', name: 'testimonials', family: '12F', blocks: ['testimonial'] },
+  {
+    layout: field.select(['grid', 'carousel'], 'grid'),
+    columns: field.range(3, 1, 3, 1),
+    showRating: field.boolean(true),
+    showAvatar: field.boolean(true),
+    quoteSize: field.select(['md', 'lg'], 'md'),
+    cardStyle: field.select(['muted', 'plain'], 'muted'),
+    autoplay: field.boolean(false, { legacyHidden: true }),
+    // Shared Nova 12 vocabulary (12A · 00) — sharedApplicability APPLIES.
+    sectionWidth: shared.sectionWidth('wide'),
+    contentAlignment: shared.contentAlignment('left'),
+    mobileContentAlignment: shared.mobileContentAlignment('inherit'),
+    spacingTop: shared.spacingTop('large'),
+    spacingBottom: shared.spacingBottom('large'),
+    background: shared.background('surface'),
+    heading: shared.heading(),
+    eyebrow: shared.eyebrow(),
+    description: shared.description(),
+    headerSize: shared.headerSize('medium'),
+    hideOnMobile: shared.hideOnMobile(),
+    anchorId: shared.anchorId(),
+  },
+)

package/templates/nova/src/sections/Timeline/Timeline.tsx

@@ -0,0 +1,43 @@
+import { sx, sxJoin } from '@tanqory/theme-kit'
+import type { CSSProperties } from 'react'
+import { type SettingsOf } from '@tanqory/theme-kit'
+import { SectionHead } from '../../components/content/SectionHead'
+import type { StepInstance } from './blocks/Step'
+import { useNova } from '../../styles/NovaProvider'
+import { EmptySection, Shell } from '../../components/section/shell'
+import '../../components/section/shared.css'
+import '../../styles/sections/content.css'
+import { timelineSchema } from './schema'
+
+export type TimelineSettings = SettingsOf<typeof timelineSchema>
+export interface TimelineProps extends TimelineSettings {
+  steps?: StepInstance[]
+}
+
+export function Timeline(props: TimelineProps): JSX.Element | null {
+  const { layout, numbering, showImages, columns, sectionWidth, contentAlignment, heading, eyebrow, description, headerSize, steps = [] } = props
+  const { strings } = useNova()
+  const list = steps.filter((s) => s.settings.heading.trim() || s.settings.body.trim())
+  if (!list.length) return <EmptySection props={props} type="timeline" width={sectionWidth} title={strings.editorAddBlocks} />
+  const H = heading ? 'h3' : 'h2'
+  return (
+    <Shell props={props} type="timeline" width={sectionWidth} className="nv-timeline" data-layout={layout} data-numbering={numbering}>
+      <SectionHead eyebrow={eyebrow} heading={heading} description={description} headerSize={headerSize} align={contentAlignment} />
+      <ol className={sxJoin("nv-timeline__list", sx({ '--nv-cols': columns } as CSSProperties))}>
+        {list.map((s, i) => (
+          <li key={i} className="nv-timeline__step" data-first={i === 0 ? '' : undefined}>
+            <span className="nv-timeline__marker" aria-hidden>
+              {numbering === 'numbers' ? i + 1 : ''}
+            </span>
+            <div className="nv-timeline__text">
+              {showImages && s.image && <img className="nv-timeline__img" src={s.image.src} alt={s.image.alt ?? ''} width={s.image.width} height={s.image.height} loading="lazy" decoding="async" />}
+              {s.settings.label.trim() && <p className="nv-timeline__label"><bdi>{s.settings.label}</bdi></p>}
+              {s.settings.heading.trim() && <H className="nv-timeline__title"><bdi>{s.settings.heading}</bdi></H>}
+              {s.settings.body.trim() && <p className="nv-timeline__body"><bdi>{s.settings.body}</bdi></p>}
+            </div>
+          </li>
+        ))}
+      </ol>
+    </Shell>
+  )
+}

package/templates/nova/src/sections/Timeline/blocks/Step.tsx

@@ -0,0 +1,19 @@
+import { defineSchema, field, type SettingsOf } from '@tanqory/theme-kit'
+import type { NovaImage } from '@tanqory/theme-kit'
+import '../../../styles/blocks.css'
+
+/** 12D · step block (timeline) — a label ("Day 1"), a title, a short body and an image when the section shows images. */
+export const stepSchema = defineSchema(
+  { kind: 'block', name: 'step', family: '12D', parents: ['timeline'], title: 'Step', description: 'One step of a process: heading, text and an optional image.', icon: '①' },
+  {
+    heading: field.text('', { extension: '12D step: "Title uses the shared heading" (step.body) — the step title ("Throw").' }),
+    label: field.text(''),
+    body: field.textarea('Describe this step.'),
+    image: field.resource('image'),
+  },
+)
+export type StepSettings = SettingsOf<typeof stepSchema>
+export interface StepInstance {
+  settings: StepSettings
+  image?: NovaImage | null
+}

package/templates/nova/src/sections/Timeline/index.ts

@@ -0,0 +1,28 @@
+import { defineSection, imageFor, resolveSettings } from '@tanqory/theme-kit'
+import { Timeline } from './Timeline'
+import { stepSchema } from './blocks/Step'
+import { presets } from './presets'
+import { timelineSchema } from './schema'
+
+export default defineSection({
+  id: 'timeline',
+  schema: timelineSchema,
+  blocks: [stepSchema],
+  component: Timeline,
+  category: 'content',
+  zone: 'main',
+  title: 'Timeline',
+  description: 'Numbered steps for a process or a story.',
+  icon: '①',
+  presets,
+  data: (node, store) => {
+      const r = resolveSettings(timelineSchema, node.settings)
+      const issues = [...r.issues]
+      const steps = (node.blocks ?? []).filter((b) => b.type === 'step').map((b) => {
+        const br = resolveSettings(stepSchema, b.settings)
+        issues.push(...br.issues)
+        return { settings: br.settings, image: imageFor(store, br.handles.image) }
+      })
+      return { ...r.settings, steps }
+  },
+})

package/templates/nova/src/sections/Timeline/presets.ts

@@ -0,0 +1,8 @@
+import type { SectionPreset } from '@tanqory/theme-kit'
+/** What "Add section" offers as starting points. */
+export const presets: readonly SectionPreset[] = [
+  // How it is made / how it works
+  {"name": "tl-process", "label": "Process", "settings": {"layout": "horizontal", "numbering": "numbers", "columns": 4}, "blocks": []},
+  // Brand history with images
+  {"name": "tl-history", "label": "History", "settings": {"layout": "vertical", "numbering": "none", "showImages": true}, "blocks": []},
+]

package/templates/nova/src/sections/Timeline/schema.ts

@@ -0,0 +1,31 @@
+import { defineSchema, field } from '@tanqory/theme-kit'
+import { shared } from '../../components/section/shared'
+
+/**
+ * 12D · 09 timeline — a process or history in steps. Always an ordered list
+ * (numbers are decorative when numbering is none). horizontal: `columns` per
+ * row with a connecting line, more steps wrap; vertical below 1024 with the
+ * line running down. The first step's number is filled.
+ */
+export const timelineSchema = defineSchema(
+  { kind: 'section', name: 'timeline', family: '12D', blocks: ['step'] },
+  {
+    layout: field.select(['horizontal', 'vertical'], 'horizontal'),
+    numbering: field.select(['numbers', 'none'], 'numbers'),
+    showImages: field.boolean(false),
+    columns: field.range(4, 3, 5, 1),
+    // Shared Nova 12 vocabulary (12A · 00) — sharedApplicability APPLIES.
+    sectionWidth: shared.sectionWidth('wide'),
+    contentAlignment: shared.contentAlignment('left'),
+    mobileContentAlignment: shared.mobileContentAlignment('inherit'),
+    spacingTop: shared.spacingTop('large'),
+    spacingBottom: shared.spacingBottom('large'),
+    background: shared.background('surface'),
+    heading: shared.heading(),
+    eyebrow: shared.eyebrow(),
+    description: shared.description(),
+    headerSize: shared.headerSize('medium'),
+    hideOnMobile: shared.hideOnMobile(),
+    anchorId: shared.anchorId(),
+  },
+)

package/templates/nova/src/sections/TrustBadges/TrustBadges.tsx

@@ -0,0 +1,42 @@
+import { sx, sxJoin } from '@tanqory/theme-kit'
+import type { CSSProperties } from 'react'
+import { type SettingsOf } from '@tanqory/theme-kit'
+import { SectionHead } from '../../components/content/SectionHead'
+import type { BadgeBlockSettings } from '../../components/commerce/blocks/Badge'
+import { Icon } from '../../styles/Icon'
+import { useNova } from '../../styles/NovaProvider'
+import { EmptySection, Shell } from '../../components/section/shell'
+import '../../components/section/shared.css'
+import '../../styles/sections/trust.css'
+import { trustBadgesSchema } from './schema'
+
+export type TrustBadgesSettings = SettingsOf<typeof trustBadgesSchema>
+export interface TrustBadgesProps extends TrustBadgesSettings {
+  badges?: BadgeBlockSettings[]
+}
+
+export function TrustBadges(props: TrustBadgesProps): JSX.Element | null {
+  const { style, dividers, iconSize, alignment, sectionWidth, heading, headerSize, badges = [] } = props
+  const { strings } = useNova()
+  const list = badges.filter((b) => b.label.trim()).slice(0, 4)
+  if (!list.length) return <EmptySection props={props} type="trust-badges" width={sectionWidth} title={strings.editorAddBadges} hint={strings.editorAddBadgesHint} />
+  return (
+    <Shell props={props} type="trust-badges" width={sectionWidth} className="nv-badges" data-style={style} data-dividers={style === 'row' && dividers ? '' : undefined} data-icon={iconSize} data-badge-align={alignment}>
+      <SectionHead heading={heading} headerSize={headerSize} align={alignment === 'center' ? 'center' : 'left'} />
+      <ul className={sxJoin("nv-badges__list", sx({ '--nv-cols': list.length } as CSSProperties))}>
+        {list.map((b, i) => {
+          const title = b.link.trim() ? <a href={b.link}><bdi>{b.label}</bdi></a> : <bdi>{b.label}</bdi>
+          return (
+            <li key={i} className="nv-badges__item">
+              <Icon name={b.icon} size={iconSize === 'sm' ? 20 : 24} />
+              <span className="nv-badges__text">
+                <span className="nv-badges__title">{title}</span>
+                {style === 'row' && b.detail.trim() && <span className="nv-badges__detail"><bdi>{b.detail}</bdi></span>}
+              </span>
+            </li>
+          )
+        })}
+      </ul>
+    </Shell>
+  )
+}

package/templates/nova/src/sections/TrustBadges/index.ts

@@ -0,0 +1,29 @@
+import { defineSection, resolveSettings } from '@tanqory/theme-kit'
+import { badgeSchema } from '../../components/commerce/blocks/Badge'
+import { blocksOf } from '../data'
+import { TrustBadges } from './TrustBadges'
+import { presets } from './presets'
+import { trustBadgesSchema } from './schema'
+
+export default defineSection({
+  id: 'trust-badges',
+  schema: trustBadgesSchema,
+  blocks: [badgeSchema],
+  component: TrustBadges,
+  category: 'commerce',
+  zone: 'main',
+  title: 'Trust badges',
+  description: 'A strip of guarantees — icon, label and detail — in your own words.',
+  icon: '◈',
+  presets,
+  data: (node) => {
+      const r = resolveSettings(trustBadgesSchema, node.settings)
+      const issues = [...r.issues]
+      const badges = blocksOf(node, 'badge').map((b) => {
+        const br = resolveSettings(badgeSchema, b.settings)
+        issues.push(...br.issues)
+        return br.settings
+      })
+      return { ...r.settings, badges }
+  },
+})

package/templates/nova/src/sections/TrustBadges/presets.ts

@@ -0,0 +1,8 @@
+import type { SectionPreset } from '@tanqory/theme-kit'
+/** What "Add section" offers as starting points. */
+export const presets: readonly SectionPreset[] = [
+  // Near buying decisions
+  {"name": "badges-row", "label": "Policy row", "settings": {"style": "row", "dividers": true}, "blocks": []},
+  // Under product buy box / cart
+  {"name": "badges-compact", "label": "Compact", "settings": {"style": "compact", "iconSize": "sm"}, "blocks": []},
+]

package/templates/nova/src/sections/TrustBadges/schema.ts

@@ -0,0 +1,29 @@
+import { defineSchema, field } from '@tanqory/theme-kit'
+import { shared } from '../../components/section/shared'
+
+/**
+ * 12F · 03 trust-badges (EXISTING) — real policies near the buying decision,
+ * from badge blocks (12C). row: icon, title, detail with hairline dividers;
+ * compact: icon + label on one line. 2 × 2 without dividers at 390.
+ * alignment persists start · center (not the shared left · center —
+ * 12F conflict 5), so the shared contentAlignment is not exposed.
+ */
+export const trustBadgesSchema = defineSchema(
+  { kind: 'section', name: 'trust-badges', family: '12F', blocks: ['badge'] },
+  {
+    style: field.select(['row', 'compact'], 'row'),
+    dividers: field.boolean(true),
+    iconSize: field.select(['sm', 'md'], 'md'),
+    alignment: field.select(['start', 'center'], 'start'),
+    // Shared Nova 12 vocabulary (12A · 00) — sharedApplicability APPLIES.
+    sectionWidth: shared.sectionWidth('wide'),
+    mobileContentAlignment: shared.mobileContentAlignment('inherit'),
+    spacingTop: shared.spacingTop('medium'),
+    spacingBottom: shared.spacingBottom('medium'),
+    background: shared.background('surface'),
+    heading: shared.heading(),
+    headerSize: shared.headerSize('small'),
+    hideOnMobile: shared.hideOnMobile(),
+    anchorId: shared.anchorId(),
+  },
+)

package/templates/nova/src/sections/UgcGallery/UgcGallery.tsx

@@ -0,0 +1,58 @@
+import { type SettingsOf } from '@tanqory/theme-kit'
+import { CardRow } from '../../components/content/CardRow'
+import { UgcTile } from '../../components/content/UgcTile'
+import type { UgcPhotoInstance } from './blocks/UgcImage'
+import { Icon } from '../../styles/Icon'
+import { useNova } from '../../styles/NovaProvider'
+import type { UgcPost } from '@tanqory/theme-kit'
+import { EmptySection, Shell } from '../../components/section/shell'
+import '../../components/section/shared.css'
+import '../../styles/sections/trust.css'
+import { ugcGallerySchema } from './schema'
+
+export type UgcGallerySettings = SettingsOf<typeof ugcGallerySchema>
+export interface UgcGalleryProps extends UgcGallerySettings {
+  /** source manual: the image blocks. */
+  photos?: UgcPhotoInstance[]
+  /** source feed: the connected social feed — null until the platform has one (DATA REQUIREMENT). */
+  feed?: UgcPost[] | null
+}
+
+interface Tile {
+  image: NonNullable<UgcPhotoInstance['image']>
+  handle?: string
+  href?: string
+  productTitle?: string
+  soldOut?: boolean
+}
+
+export function UgcGallery(props: UgcGalleryProps): JSX.Element | null {
+  const { source, layout, columns, showCredit, showProduct, ctaLabel, ctaLink, sectionWidth, contentAlignment, heading, eyebrow, description, headerSize, photos = [], feed } = props
+  const { strings } = useNova()
+  if (source === 'feed' && !feed) return <EmptySection props={props} type="ugc-gallery" width={sectionWidth} title={strings.editorFeedTitle} hint={strings.editorFeedHint} />
+  const tiles: Tile[] =
+    source === 'feed'
+      ? (feed ?? []).map((p) => ({ image: p.image, handle: p.handle, href: p.productHandles?.[0] ? `/products/${p.productHandles[0]}` : undefined }))
+      : photos.flatMap((p) =>
+          p.image
+            ? [{ image: { ...p.image, alt: p.settings.alt.trim() || p.image.alt }, handle: p.settings.caption, href: p.settings.link.trim() || undefined, productTitle: p.product?.title, soldOut: p.product ? !p.product.available : undefined }]
+            : [],
+        )
+  const list = tiles.slice(0, 24)
+  if (!list.length) return <EmptySection props={props} type="ugc-gallery" width={sectionWidth} title={strings.editorAddPhotos} hint={strings.editorAddPhotosHint} />
+  const cta = ctaLabel.trim() && ctaLink.trim() && (
+    <a className="nv-ugc__cta" href={ctaLink}>
+      {ctaLabel}
+      <Icon name="arrow-up-right" size="sm" />
+    </a>
+  )
+  return (
+    <Shell props={props} type="ugc-gallery" width={sectionWidth} className="nv-ugc">
+      <CardRow eyebrow={eyebrow} heading={heading} description={description} headerSize={headerSize} align={contentAlignment} layout={layout} columns={Number(columns)} carouselOnMobile label={heading || strings.customerPhotos} action={cta || undefined}>
+        {list.map((t, i) => (
+          <UgcTile key={i} image={t.image} handle={showCredit ? t.handle : undefined} href={showProduct ? t.href : undefined} productTitle={t.productTitle} soldOut={t.soldOut} />
+        ))}
+      </CardRow>
+    </Shell>
+  )
+}

package/templates/nova/src/sections/UgcGallery/blocks/UgcImage.tsx

@@ -0,0 +1,27 @@
+import { defineSchema, field, type SettingsOf } from '@tanqory/theme-kit'
+import type { NovaImage, Product } from '@tanqory/theme-kit'
+import '../../../styles/blocks.css'
+
+const REUSE = '12F reuses the 12D image block in ugc-gallery (caption = @handle, link = product); the 12F contract lists no rows of its own.'
+
+/**
+ * 12F · image block in ugc-gallery — the 12D image block's fields, read as a
+ * customer photo: caption = the @handle credit, link = the product it shows.
+ * ratio and rounded do not apply (tiles are square).
+ */
+export const ugcImageSchema = defineSchema(
+  { kind: 'block', name: 'image', family: '12F', parents: ['ugc-gallery'], title: 'Image', description: 'One image, optionally linked and captioned.', icon: '▥' },
+  {
+    image: field.resource('image', '', { extension: REUSE }),
+    alt: field.text('', { extension: REUSE }),
+    caption: field.text('', { extension: REUSE }),
+    link: field.url('', { extension: REUSE }),
+  },
+)
+export type UgcImageSettings = SettingsOf<typeof ugcImageSchema>
+export interface UgcPhotoInstance {
+  settings: UgcImageSettings
+  image?: NovaImage | null
+  /** The product the link points at, when the store knows it (drives "Sold out"). */
+  product?: Product | null
+}

package/templates/nova/src/sections/UgcGallery/index.ts

@@ -0,0 +1,31 @@
+import { defineSection, imageFor, productFor, resolveSettings } from '@tanqory/theme-kit'
+import { blocksOf } from '../data'
+import { UgcGallery } from './UgcGallery'
+import { ugcImageSchema } from './blocks/UgcImage'
+import { presets } from './presets'
+import { ugcGallerySchema } from './schema'
+
+export default defineSection({
+  id: 'ugc-gallery',
+  schema: ugcGallerySchema,
+  blocks: [ugcImageSchema],
+  component: UgcGallery,
+  category: 'trust',
+  zone: 'main',
+  title: 'Customer photos',
+  description: 'Customer photos, shared with permission.',
+  icon: '▣',
+  presets,
+  data: (node, store) => {
+      const r = resolveSettings(ugcGallerySchema, node.settings)
+      const issues = [...r.issues]
+      const photos = blocksOf(node, 'image').map((b) => {
+        const br = resolveSettings(ugcImageSchema, b.settings)
+        issues.push(...br.issues)
+        // link = a product: /products/<handle> resolves to the product (drives "Sold out").
+        const handle = /\/products\/([^/?#]+)/.exec(br.settings.link)?.[1]
+        return { settings: br.settings, image: imageFor(store, br.handles.image), product: handle ? productFor(store, handle).product : null }
+      })
+      return { ...r.settings, photos, feed: store.ugcFeed ?? null }
+  },
+})

package/templates/nova/src/sections/UgcGallery/presets.ts

@@ -0,0 +1,8 @@
+import type { SectionPreset } from '@tanqory/theme-kit'
+/** What "Add section" offers as starting points. */
+export const presets: readonly SectionPreset[] = [
+  // Homes and outfits
+  {"name": "ugc-grid", "label": "Customer photos", "settings": {"source": "manual", "layout": "grid", "columns": "5"}, "blocks": []},
+  // Compact row above footer
+  {"name": "ugc-strip", "label": "Photo strip", "settings": {"layout": "carousel", "columns": "6", "showProduct": false}, "blocks": []},
+]

package/templates/nova/src/sections/UgcGallery/schema.ts

@@ -0,0 +1,35 @@
+import { defineSchema, field } from '@tanqory/theme-kit'
+import { shared } from '../../components/section/shared'
+
+/**
+ * 12F · 05 ugc-gallery (NEW) — customer photos. manual works today with
+ * image blocks (caption = @handle, link = product); feed is the DATA
+ * REQUIREMENT upgrade (a social feed + rights) and keeps the same tiles.
+ * Square tiles, grid or carousel; 2.2 visible at 390. Permission is the
+ * merchant's responsibility; the editor reminds on add.
+ */
+export const ugcGallerySchema = defineSchema(
+  { kind: 'section', name: 'ugc-gallery', family: '12F', blocks: ['image'] },
+  {
+    source: field.select(['manual', 'feed'], 'manual'),
+    layout: field.select(['grid', 'carousel'], 'grid'),
+    columns: field.select(['4', '5', '6'], '5'),
+    showCredit: field.boolean(true),
+    showProduct: field.boolean(true),
+    ctaLabel: field.text('Share yours on Instagram'),
+    ctaLink: field.url(''),
+    // Shared Nova 12 vocabulary (12A · 00) — sharedApplicability APPLIES.
+    sectionWidth: shared.sectionWidth('wide'),
+    contentAlignment: shared.contentAlignment('left'),
+    mobileContentAlignment: shared.mobileContentAlignment('inherit'),
+    spacingTop: shared.spacingTop('large'),
+    spacingBottom: shared.spacingBottom('large'),
+    background: shared.background('surface'),
+    heading: shared.heading(),
+    eyebrow: shared.eyebrow(),
+    description: shared.description(),
+    headerSize: shared.headerSize('medium'),
+    hideOnMobile: shared.hideOnMobile(),
+    anchorId: shared.anchorId(),
+  },
+)

package/templates/nova/src/sections/VideoHero/VideoHero.tsx

@@ -0,0 +1,75 @@
+import { type SettingsOf } from '@tanqory/theme-kit'
+import { HeroCopy, heroHasBody, scrimAlpha } from '../../components/content/HeroCopy'
+import { HeroFrame } from '../../components/content/HeroFrame'
+import { HeroMedia } from '../../components/content/HeroMedia'
+import { useNova } from '../../styles/NovaProvider'
+import { EditorFrame } from '../../components/states/EditorFrame'
+import type { NovaImage } from '@tanqory/theme-kit'
+import { sectionRootProps } from '../../components/section/shared'
+import '../../components/section/shared.css'
+import '../../styles/sections/promotion.css'
+import { videoHeroSchema } from './schema'
+
+export type VideoHeroSettings = SettingsOf<typeof videoHeroSchema>
+export interface VideoHeroProps extends VideoHeroSettings {
+  poster?: NovaImage | null
+  mobilePoster?: NovaImage | null
+  headingLevel?: 1 | 2
+  priority?: boolean
+}
+
+/** contentWidth (shared) → the text measure. */
+const MEASURE = { narrow: 'narrow', content: 'medium', standard: 'wide' } as const
+
+export function VideoHero(props: VideoHeroProps): JSX.Element | null {
+  const { eyebrow, heading, text, buttonLabel, buttonLink, secondaryLabel, secondaryLink, videoUrl, mobileVideoUrl, poster, mobilePoster, overlayOpacity, size, contentPosition, soundButtonUrl, sectionWidth, contentWidth, headerSize, headingLevel = 2, priority = true } = props
+  const { mode, strings } = useNova()
+  const video = videoUrl.trim() ? { src: videoUrl, poster: poster ?? undefined } : null
+  const mobileVideo = mobileVideoUrl.trim() ? { src: mobileVideoUrl, poster: mobilePoster ?? poster ?? undefined } : null
+
+  if (!video && !mobileVideo && !poster) {
+    return mode === 'editor' ? (
+      <section {...sectionRootProps(props, 'video-hero')} className="nv-video-hero">
+        <div className="nv-promo-container" data-width={sectionWidth}>
+          <EditorFrame section="video-hero" title={strings.editorAddVideo} hint={strings.editorAddVideoHint} />
+        </div>
+      </section>
+    ) : null
+  }
+
+  const moving = Boolean(video || mobileVideo)
+  const center = contentPosition === 'center'
+  const alpha = Math.max(scrimAlpha(overlayOpacity, heroHasBody(eyebrow, text)), moving ? scrimAlpha('none', true) : 0)
+  // Legacy: a saved sound-button URL renders as the "Watch the film" link unless a second action exists.
+  const secondary = secondaryLabel.trim() ? { label: secondaryLabel, link: secondaryLink } : soundButtonUrl?.trim() ? { label: strings.watchTheFilm, link: soundButtonUrl } : undefined
+
+  return (
+    <section {...sectionRootProps(props, 'video-hero')} className="nv-video-hero" data-size={size} data-position={contentPosition}>
+      <div className="nv-promo-container" data-width={sectionWidth}>
+        <HeroFrame
+          position={contentPosition}
+          align={center ? 'center' : 'left'}
+          scrim={alpha}
+          hasVideo={moving}
+          media={<HeroMedia image={poster} mobileImage={mobilePoster} video={video ?? mobileVideo} mobileVideo={mobileVideo} priority={priority} />}
+        >
+          <HeroCopy
+            className="nv-media-frame__copy"
+            eyebrow={eyebrow}
+            heading={heading}
+            body={text}
+            primary={{ label: buttonLabel, link: buttonLink }}
+            secondary={secondary}
+            secondaryStyle="link"
+            blockOnPhone
+            headerSize={headerSize}
+            level={headingLevel}
+            align={center ? 'center' : 'left'}
+            textWidth={MEASURE[contentWidth]}
+            onMedia
+          />
+        </HeroFrame>
+      </div>
+    </section>
+  )
+}

package/templates/nova/src/sections/VideoHero/index.ts

@@ -0,0 +1,22 @@
+import { defineSection, imageFor, resolveSettings } from '@tanqory/theme-kit'
+import { VideoHero } from './VideoHero'
+import { presets } from './presets'
+import { videoHeroSchema } from './schema'
+
+export default defineSection({
+  id: 'video-hero',
+  schema: videoHeroSchema,
+  component: VideoHero,
+  category: 'layout',
+  zone: 'main',
+  title: 'Video hero',
+  description: 'A hero with a muted, looping background video and a poster.',
+  icon: '▷',
+  presets,
+  data: (node, store, { page }) => {
+      const r = resolveSettings(videoHeroSchema, node.settings)
+      return { ...r.settings, poster: imageFor(store, r.handles.poster),
+      headingLevel: (page.isFirstBodySection ? 1 : 2) as 1 | 2,
+    }
+  },
+})

package/templates/nova/src/sections/VideoHero/presets.ts

@@ -0,0 +1,8 @@
+import type { SectionPreset } from '@tanqory/theme-kit'
+/** What "Add section" offers as starting points. */
+export const presets: readonly SectionPreset[] = [
+  // Quiet brand film behind copy
+  {"name": "video-ambient", "label": "Ambient film", "settings": {"size": "medium", "contentPosition": "bottom-start", "overlayOpacity": 45}, "blocks": []},
+  // Full-screen launch moment
+  {"name": "video-launch", "label": "Launch film", "settings": {"size": "fullscreen", "contentPosition": "center", "overlayOpacity": 50}, "blocks": []},
+]

package/templates/nova/src/sections/VideoHero/schema.ts

@@ -0,0 +1,43 @@
+import { defineSchema, field } from '@tanqory/theme-kit'
+import { shared } from '../../components/section/shared'
+
+/**
+ * 12B · 03 video-hero — a muted, looping ambient film behind hero copy. The
+ * poster IS the design; video is enhancement: it must look finished on a slow
+ * phone, under reduced motion, or when the file fails.
+ *
+ *   poster only → an image hero · neither → hidden (editor: setup frame)
+ *   center → a flat overlay (overlayOpacity); bottom-start → a gradient from
+ *   the text edge. Text over moving video: floor 62 + an 18% base wash.
+ *   soundButtonUrl (LEGACY-HIDDEN) renders as the "Watch the film" text link.
+ *
+ * Kept for stores that use it; new compositions use hero + video (12B conflict 5).
+ */
+export const videoHeroSchema = defineSchema(
+  { kind: 'section', name: 'video-hero', family: '12B' },
+  {
+    eyebrow: field.text(''),
+    heading: field.text('Modern essentials'),
+    text: field.richtext(''),
+    buttonLabel: field.text('Shop the collection'),
+    buttonLink: field.url('/collections/all'),
+    secondaryLabel: field.text(''),
+    secondaryLink: field.url(''),
+    videoUrl: field.url(''),
+    mobileVideoUrl: field.url(''),
+    poster: field.resource('image'),
+    overlayOpacity: field.range(45, 0, 80, 5),
+    size: field.select(['small', 'medium', 'large', 'fullscreen'], 'medium'),
+    contentPosition: field.select(['bottom-start', 'center'], 'bottom-start'),
+    soundButtonUrl: field.url('', { legacyHidden: true }),
+    // Shared Nova 12 vocabulary (12A · 00) — sharedApplicability APPLIES.
+    sectionWidth: shared.sectionWidth('full'),
+    contentWidth: shared.contentWidth('narrow'),
+    spacingTop: shared.spacingTop('none'),
+    spacingBottom: shared.spacingBottom('none'),
+    headerSize: shared.headerSize('medium'),
+    mobileContentAlignment: shared.mobileContentAlignment('inherit'),
+    hideOnMobile: shared.hideOnMobile(),
+    anchorId: shared.anchorId(),
+  },
+)