@teleporthq/teleport-shared 0.43.69 → 0.43.71

package/src/page-transition/variants.ts

@@ -0,0 +1,407 @@
+/**
+ * The three states of a route transition for a preset, and the preset the
+ * back button plays. Mirrored VERBATIM from teleport-gui's
+ * `constants/primitives/page-transition.ts` — the settings picker demonstrates
+ * these exact states. Plain JS inside the bodies on purpose: their compiled
+ * source is injected into the generated `TqPageTransition` wrapper with
+ * `toString()`, so no template literals, no backticks, no helpers from outside
+ * the two functions.
+ */
+export interface PageTransitionContext {
+  reverse: boolean
+  originX: string
+  originY: string
+}
+
+export interface PageTransitionPanel {
+  from: Record<string, unknown>
+  cover: Record<string, unknown>
+  away: Record<string, unknown>
+  side?: 'left' | 'right'
+}
+
+export interface PageTransitionVariants {
+  initial: Record<string, unknown>
+  animate: Record<string, unknown>
+  exit: Record<string, unknown>
+}
+
+export function reversePageTransitionPreset(preset: string): string {
+  const pairs: Record<string, string> = {
+    'slide-up': 'slide-down',
+    'slide-down': 'slide-up',
+    'slide-left': 'slide-right',
+    'slide-right': 'slide-left',
+    'zoom-in': 'zoom-out',
+    'zoom-out': 'zoom-in',
+    'wipe-down': 'wipe-up',
+    'wipe-up': 'wipe-down',
+    'wipe-left': 'wipe-right',
+    'wipe-right': 'wipe-left',
+    stack: 'unstack',
+    unstack: 'stack',
+  }
+  return pairs[preset] || preset
+}
+
+export interface PageTransitionCustomState {
+  opacity: number
+  x: number
+  y: number
+  scale: number
+  blur: number
+}
+
+export interface PageTransitionCustom {
+  durationSeconds: number
+  easing: string
+  arrive: PageTransitionCustomState
+  leave: PageTransitionCustomState
+}
+
+export function pageTransitionVariants(
+  preset: string,
+  slidePx: number,
+  context?: PageTransitionContext,
+  options?: Record<string, string>,
+  custom?: PageTransitionCustom
+): PageTransitionVariants | null {
+  const reverse = context ? context.reverse : false
+  const originX = context ? context.originX : '50%'
+  const originY = context ? context.originY : '50%'
+  const name = reverse ? reversePageTransitionPreset(preset) : preset
+  const bold = options
+    ? options.distance === 'bold' || options.depth === 'bold' || options.amount === 'bold'
+    : false
+  const near = bold ? slidePx * 4 : slidePx
+  const far = near * 2
+  const blurPx = options && options.softness === 'heavy' ? 28 : 12
+  const shrink = bold ? 0.85 : 0.94
+  const zoomOut = bold ? 0.85 : 0.96
+  const zoomIn = bold ? 1.15 : 1.04
+  if (name === 'custom') {
+    // Neutral in the middle; the two ends are exactly the user's values.
+    const c = custom || {
+      arrive: { opacity: 0, x: 0, y: 24, scale: 1, blur: 0 },
+      leave: { opacity: 0, x: 0, y: -24, scale: 1, blur: 0 },
+    }
+    return {
+      initial: {
+        opacity: c.arrive.opacity,
+        x: c.arrive.x,
+        y: c.arrive.y,
+        scale: c.arrive.scale,
+        filter: 'blur(' + c.arrive.blur + 'px)',
+      },
+      animate: { opacity: 1, x: 0, y: 0, scale: 1, filter: 'blur(0px)' },
+      exit: {
+        opacity: c.leave.opacity,
+        x: c.leave.x,
+        y: c.leave.y,
+        scale: c.leave.scale,
+        filter: 'blur(' + c.leave.blur + 'px)',
+      },
+    }
+  }
+  if (name === 'fade') {
+    return { initial: { opacity: 0 }, animate: { opacity: 1 }, exit: { opacity: 0 } }
+  }
+  if (name === 'crossfade') {
+    return {
+      initial: { opacity: 0, scale: 1.02 },
+      animate: { opacity: 1, scale: 1 },
+      exit: { opacity: 0, scale: 0.98 },
+    }
+  }
+  if (name === 'blur') {
+    return {
+      initial: { opacity: 0, filter: 'blur(' + blurPx + 'px)' },
+      animate: { opacity: 1, filter: 'blur(0px)' },
+      exit: { opacity: 0, filter: 'blur(' + blurPx + 'px)' },
+    }
+  }
+  if (name === 'slide-up') {
+    return {
+      initial: { opacity: 0, y: near },
+      animate: { opacity: 1, y: 0 },
+      exit: { opacity: 0, y: -near },
+    }
+  }
+  if (name === 'slide-down') {
+    return {
+      initial: { opacity: 0, y: -near },
+      animate: { opacity: 1, y: 0 },
+      exit: { opacity: 0, y: near },
+    }
+  }
+  if (name === 'slide-left') {
+    return {
+      initial: { opacity: 0, x: far },
+      animate: { opacity: 1, x: 0 },
+      exit: { opacity: 0, x: -far },
+    }
+  }
+  if (name === 'slide-right') {
+    return {
+      initial: { opacity: 0, x: -far },
+      animate: { opacity: 1, x: 0 },
+      exit: { opacity: 0, x: far },
+    }
+  }
+  if (name === 'stack') {
+    return {
+      initial: { opacity: 0, y: far },
+      animate: { opacity: 1, y: 0, scale: 1 },
+      exit: { opacity: 0, scale: shrink },
+    }
+  }
+  if (name === 'unstack') {
+    return {
+      initial: { opacity: 0, scale: shrink },
+      animate: { opacity: 1, y: 0, scale: 1 },
+      exit: { opacity: 0, y: far },
+    }
+  }
+  if (name === 'zoom-in') {
+    return {
+      initial: { opacity: 0, scale: zoomOut },
+      animate: { opacity: 1, scale: 1 },
+      exit: { opacity: 0, scale: zoomIn },
+    }
+  }
+  if (name === 'zoom-out') {
+    return {
+      initial: { opacity: 0, scale: zoomIn },
+      animate: { opacity: 1, scale: 1 },
+      exit: { opacity: 0, scale: zoomOut },
+    }
+  }
+  if (name === 'wipe-down') {
+    return {
+      initial: { clipPath: 'inset(0 0 100% 0)' },
+      animate: { clipPath: 'inset(0 0 0% 0)' },
+      exit: { clipPath: 'inset(100% 0 0 0)' },
+    }
+  }
+  if (name === 'wipe-up') {
+    return {
+      initial: { clipPath: 'inset(100% 0 0 0)' },
+      animate: { clipPath: 'inset(0% 0 0 0)' },
+      exit: { clipPath: 'inset(0 0 100% 0)' },
+    }
+  }
+  if (name === 'wipe-left') {
+    return {
+      initial: { clipPath: 'inset(0 0 0 100%)' },
+      animate: { clipPath: 'inset(0 0 0 0%)' },
+      exit: { clipPath: 'inset(0 100% 0 0)' },
+    }
+  }
+  if (name === 'wipe-right') {
+    return {
+      initial: { clipPath: 'inset(0 100% 0 0)' },
+      animate: { clipPath: 'inset(0 0% 0 0)' },
+      exit: { clipPath: 'inset(0 0 0 100%)' },
+    }
+  }
+  if (name === 'circle') {
+    const at = ' at ' + originX + ' ' + originY + ')'
+    return {
+      initial: { clipPath: 'circle(0%' + at },
+      animate: { clipPath: 'circle(150%' + at },
+      exit: { clipPath: 'circle(0%' + at },
+    }
+  }
+  if (name === 'cover' || name === 'curtain') {
+    // The panels do the work; the page itself only has to STAY while it is
+    // being covered. An exit that changes nothing would end instantly, so it
+    // moves opacity by an invisible amount — that is what keeps the leaving
+    // page on screen for exactly one panel sweep.
+    return { initial: { opacity: 1 }, animate: { opacity: 1 }, exit: { opacity: 0.999 } }
+  }
+  return null
+}
+
+export function pageTransitionCover(preset: string): PageTransitionPanel[] | null {
+  if (preset === 'cover') {
+    return [{ from: { y: '100%' }, cover: { y: '0%' }, away: { y: '-100%' } }]
+  }
+  if (preset === 'curtain') {
+    return [
+      { from: { x: '-100%' }, cover: { x: '0%' }, away: { x: '-100%' }, side: 'left' },
+      { from: { x: '100%' }, cover: { x: '0%' }, away: { x: '100%' }, side: 'right' },
+    ]
+  }
+  return null
+}
+
+/**
+ * The matcher for a route a page opted out of transitions with: exact path,
+ * optional trailing slash, and `[param]` segments (how the editor spells a
+ * details page) matching any single segment. Injected into the wrapper.
+ */
+export function pageTransitionSkipPattern(route: string): RegExp {
+  const escaped = route.replace(/[.*+?^$()|{}\\]/g, '\\$&')
+  return new RegExp('^' + escaped.replace(/\[[^\]]+\]/g, '[^/]+') + '/?$')
+}
+
+/** How far a page travels while sliding, in px — pages move, they do not fly. */
+export const PAGE_TRANSITION_SLIDE_PX = 24
+
+/**
+ * The preset's choices with gaps filled by defaults and unknown words replaced
+ * by the default. Mirrored verbatim from teleport-gui; runs at generation time.
+ */
+export function resolvePageTransitionOptions(
+  preset: string,
+  chosen?: Record<string, string>
+): Record<string, string> {
+  const catalog: Record<string, Array<[string, string[]]>> = {
+    blur: [['softness', ['light', 'heavy']]],
+    'slide-up': [['distance', ['subtle', 'bold']]],
+    'slide-down': [['distance', ['subtle', 'bold']]],
+    'slide-left': [['distance', ['subtle', 'bold']]],
+    'slide-right': [['distance', ['subtle', 'bold']]],
+    stack: [['depth', ['subtle', 'bold']]],
+    'zoom-in': [['amount', ['subtle', 'bold']]],
+    'zoom-out': [['amount', ['subtle', 'bold']]],
+    circle: [['origin', ['click', 'center']]],
+    cover: [['color', ['brand', 'dark', 'light']]],
+    curtain: [['color', ['brand', 'dark', 'light']]],
+  }
+  const resolved: Record<string, string> = {}
+  const entries = catalog[preset] || []
+  for (let i = 0; i < entries.length; i++) {
+    const key = entries[i][0]
+    const words = entries[i][1]
+    const value = chosen ? chosen[key] : undefined
+    const known =
+      value !== undefined &&
+      (words.indexOf(value) >= 0 || (key === 'color' && isPageTransitionColorValue(value)))
+    resolved[key] = known ? (value as string) : words[0]
+  }
+  return resolved
+}
+
+/**
+ * A colour a cover panel may carry: a project token id, a hex colour, or
+ * rgb/hsl with plain numbers — the value lands verbatim in generated code.
+ * Mirrored verbatim from teleport-gui.
+ */
+export function isPageTransitionColorValue(value: string | undefined): boolean {
+  if (typeof value !== 'string' || value.length === 0 || value.length > 120) {
+    return false
+  }
+  return (
+    /^token:[a-z0-9_-]+$/i.test(value) ||
+    /^--[a-z0-9_-]+$/i.test(value) ||
+    /^#[0-9a-f]{3,8}$/i.test(value) ||
+    /^(rgb|rgba|hsl|hsla)\([0-9.,%\s]+\)$/i.test(value)
+  )
+}
+
+/** The CSS colour a cover-family panel paints with: token → var(), literal as is, words → theme tokens. Mirrored verbatim from teleport-gui. */
+export function pageTransitionCoverColor(color: string | undefined): string {
+  const dark = 'var(--dl-color-theme-neutral-dark, #111111)'
+  if (color === 'dark') {
+    return dark
+  }
+  if (color === 'light') {
+    return 'var(--dl-color-theme-neutral-light, #ffffff)'
+  }
+  if (
+    color &&
+    color !== 'brand' &&
+    color.indexOf('token:') !== 0 &&
+    isPageTransitionColorValue(color)
+  ) {
+    return color.indexOf('--') === 0 ? 'var(' + color + ', ' + dark + ')' : color
+  }
+  return 'var(--dl-color-theme-primary1, ' + dark + ')'
+}
+
+const CUSTOM_EASINGS = [
+  'ease',
+  'ease-in',
+  'ease-out',
+  'ease-in-out',
+  'linear',
+  'spring',
+  'back',
+  'bounce',
+]
+
+const DEFAULT_CUSTOM: PageTransitionCustom = {
+  durationSeconds: 0.35,
+  easing: 'ease-out',
+  arrive: { opacity: 0, x: 0, y: 24, scale: 1, blur: 0 },
+  leave: { opacity: 0, x: 0, y: -24, scale: 1, blur: 0 },
+}
+
+const clamp = (value: unknown, min: number, max: number, fallback: number): number => {
+  const n = typeof value === 'number' && Number.isFinite(value) ? value : fallback
+  return Math.min(max, Math.max(min, n))
+}
+
+const sanitizeCustomState = (
+  input: Partial<PageTransitionCustomState> | undefined,
+  fallback: PageTransitionCustomState
+): PageTransitionCustomState => ({
+  opacity: clamp(input?.opacity, 0, 1, fallback.opacity),
+  x: clamp(input?.x, -400, 400, fallback.x),
+  y: clamp(input?.y, -400, 400, fallback.y),
+  scale: clamp(input?.scale, 0.25, 2, fallback.scale),
+  blur: clamp(input?.blur, 0, 60, fallback.blur),
+})
+
+/** Every custom value inside its range and a known easing; mirrored verbatim from teleport-gui. Runs at generation time. */
+export function sanitizePageTransitionCustom(
+  input: Partial<PageTransitionCustom> | undefined
+): PageTransitionCustom {
+  const easing =
+    typeof input?.easing === 'string' && CUSTOM_EASINGS.indexOf(input.easing) >= 0
+      ? input.easing
+      : DEFAULT_CUSTOM.easing
+  return {
+    durationSeconds: clamp(input?.durationSeconds, 0.05, 3, DEFAULT_CUSTOM.durationSeconds),
+    easing,
+    arrive: sanitizeCustomState(input?.arrive, DEFAULT_CUSTOM.arrive),
+    leave: sanitizeCustomState(input?.leave, DEFAULT_CUSTOM.leave),
+  }
+}
+
+/** What the editor exports under `globals.settings.pageTransition`. */
+export interface PageTransitionConfig {
+  preset: string
+  duration: number
+  easing: string
+  skipRoutes?: string[]
+  options?: Record<string, string>
+  custom?: { arrive?: Record<string, number>; leave?: Record<string, number> }
+  /** False when the author turned the flying pictures off; absent means they fly. */
+  flyingPictures?: boolean
+}
+
+/** The same curves the motion widget plays, so a route transition shares the site's motion character. */
+export const PAGE_TRANSITION_EASING_CURVES: Record<string, [number, number, number, number]> = {
+  ease: [0.25, 0.1, 0.25, 1],
+  'ease-in': [0.42, 0, 1, 1],
+  'ease-out': [0, 0, 0.58, 1],
+  'ease-in-out': [0.42, 0, 0.58, 1],
+  linear: [0, 0, 1, 1],
+  spring: [0.34, 1.56, 0.64, 1],
+  back: [0.68, -0.6, 0.32, 1.6],
+  bounce: [0.22, 1.2, 0.36, 1],
+}
+
+/** The resolved transition the editor exported, or null when pages switch instantly. */
+export const projectPageTransition = (uidl: {
+  globals?: { settings?: unknown }
+}): PageTransitionConfig | null => {
+  const settings = (uidl.globals?.settings || {}) as { pageTransition?: PageTransitionConfig }
+  const transition = settings.pageTransition
+  if (!transition || !transition.preset || transition.preset === 'none') {
+    return null
+  }
+  return transition
+}

package/src/page-transition/view-transition-css.ts

@@ -0,0 +1,237 @@
+import * as PageTransition from './variants'
+
+/**
+ * A site's page transition as View Transitions CSS. The static HTML export
+ * plays it between two ordinary pages (cross-document View Transitions, no
+ * script driving it); the Next export uses the same rules for the one kind of
+ * navigation it plays as a View Transition, an image flying from a list into
+ * its details page (see morph-source.ts).
+ *
+ * The states are not written here. They come from the same registry the Next
+ * export's TqPageTransition is generated from (teleport-shared), evaluated once
+ * at generation time, so a preset looks the same in both exports and a new
+ * preset reaches both. What differs is only who plays them:
+ *
+ *   Next   AnimatePresence, mode "wait": the leaving page runs its exit, then
+ *          the arriving page runs initial → animate.
+ *   HTML   the browser holds a picture of the leaving page and one of the
+ *          arriving page; the first animates over [0, D], the second waits D
+ *          and animates over [D, 2D]. Same order, same timing.
+ *
+ * The reveals (Circle, the Wipes) are the exception, in both exports: the
+ * arriving page is revealed OVER the leaving one, which holds still underneath
+ * for the whole run. Played one after the other, the leaving page was wiped
+ * away to the site's bare background and the arriving one wiped in over it —
+ * a white sheet between every two pages. Here the leaving picture keeps no
+ * animation (the browser would otherwise fade it out under the arriving one)
+ * and the arriving picture opens over [0, D].
+ *
+ * A browser without the feature (Firefox today) simply navigates, which is
+ * also what a visitor who asked for less motion gets.
+ */
+
+type State = Record<string, unknown>
+
+export const BACK_ATTR = 'data-tq-nav'
+export const ORIGIN_X = '--tq-origin-x'
+export const ORIGIN_Y = '--tq-origin-y'
+
+const hasAny = (state: State, keys: string[]): boolean =>
+  keys.some((key) => state[key] !== undefined)
+
+/** One keyframe. Both ends of an animation declare the same properties, so every one of them interpolates. */
+const declarations = (state: State, other: State): string[] => {
+  const lines: string[] = []
+  const both = (keys: string[]) => hasAny(state, keys) || hasAny(other, keys)
+  if (both(['opacity'])) {
+    lines.push(`opacity: ${state.opacity ?? 1};`)
+  }
+  if (both(['x', 'y', 'scale'])) {
+    lines.push(
+      `transform: translate(${state.x ?? 0}px, ${state.y ?? 0}px) scale(${state.scale ?? 1});`
+    )
+  }
+  if (both(['filter'])) {
+    lines.push(`filter: ${state.filter ?? 'blur(0px)'};`)
+  }
+  if (both(['clipPath'])) {
+    lines.push(`clip-path: ${state.clipPath ?? 'inset(0 0 0 0)'};`)
+  }
+  return lines
+}
+
+const keyframes = (name: string, from: State, to: State): string =>
+  `@keyframes ${name} {\n  from { ${declarations(from, to).join(' ')} }\n  to { ${declarations(
+    to,
+    from
+  ).join(' ')} }\n}`
+
+/**
+ * The cover family in the Next export is one or two coloured panels that close
+ * over the leaving page and open on the arriving one. A picture of a page can
+ * be clipped, so here the panel is what shows where the picture is clipped
+ * away: the colour sits behind both pictures and the clip edge is the panel's
+ * leading edge. Same sweep, same colour, no extra element on any page.
+ */
+const COVER_CLIPS: Record<string, { covered: string; opening: string }> = {
+  // one panel rising from the bottom, then leaving through the top
+  cover: { covered: 'inset(0 0 100% 0)', opening: 'inset(100% 0 0 0)' },
+  // two panels meeting in the middle, then parting
+  curtain: { covered: 'inset(0 50% 0 50%)', opening: 'inset(0 50% 0 50%)' },
+}
+const OPEN = 'inset(0 0 0 0)'
+
+interface Animations {
+  leave: [State, State]
+  arrive: [State, State]
+}
+
+const animationsFor = (
+  preset: string,
+  context: PageTransition.PageTransitionContext,
+  options: Record<string, string>,
+  custom: PageTransition.PageTransitionCustom | undefined
+): Animations | null => {
+  const cover = COVER_CLIPS[preset]
+  if (cover) {
+    return {
+      leave: [{ clipPath: OPEN }, { clipPath: cover.covered }],
+      arrive: [{ clipPath: cover.opening }, { clipPath: OPEN }],
+    }
+  }
+  const variants = PageTransition.pageTransitionVariants(
+    preset,
+    PageTransition.PAGE_TRANSITION_SLIDE_PX,
+    context,
+    options,
+    custom
+  )
+  if (!variants) {
+    return null
+  }
+  return {
+    leave: [variants.animate, variants.exit],
+    arrive: [variants.initial, variants.animate],
+  }
+}
+
+/** The name of the one image that flies from the leaving page into the arriving page. */
+export const MORPH_NAME = 'tq-morph'
+
+export interface ViewTransitionPlan {
+  css: string
+  /** The back button plays a different preset, so the page has to tell the stylesheet which way it came. */
+  needsDirection: boolean
+  /** The reveal grows from where the visitor pressed, so the page has to hand that point over. */
+  needsOrigin: boolean
+  /** A picture flies from the followed link into the next page; off when the author turned it off. */
+  flies: boolean
+  /** The arriving page is revealed over the leaving one, which holds (Circle, the Wipes). */
+  revealsOver: boolean
+}
+
+export const viewTransitionPlan = (
+  config: PageTransition.PageTransitionConfig,
+  target: { crossDocument: boolean } = { crossDocument: true }
+): ViewTransitionPlan | null => {
+  const preset = String(config.preset).replace(/[^a-z-]/g, '')
+  const chosen =
+    config.options && typeof config.options === 'object'
+      ? Object.fromEntries(
+          Object.entries(config.options).filter(([, value]) => typeof value === 'string')
+        )
+      : undefined
+  const options = PageTransition.resolvePageTransitionOptions(preset, chosen)
+  const duration = Number.isFinite(config.duration) && config.duration > 0 ? config.duration : 0.35
+  const curve =
+    PageTransition.PAGE_TRANSITION_EASING_CURVES[config.easing] ||
+    PageTransition.PAGE_TRANSITION_EASING_CURVES['ease-out']
+  const custom =
+    preset === 'custom'
+      ? PageTransition.sanitizePageTransitionCustom({
+          durationSeconds: duration,
+          easing: config.easing,
+          arrive: config.custom?.arrive as never,
+          leave: config.custom?.leave as never,
+        })
+      : undefined
+
+  const needsOrigin = preset === 'circle' && options.origin !== 'center'
+  const origin = needsOrigin
+    ? { originX: `var(${ORIGIN_X}, 50%)`, originY: `var(${ORIGIN_Y}, 50%)` }
+    : { originX: '50%', originY: '50%' }
+  const forward = animationsFor(preset, { reverse: false, ...origin }, options, custom)
+  if (!forward) {
+    return null
+  }
+  const needsDirection = PageTransition.reversePageTransitionPreset(preset) !== preset
+  const back = needsDirection
+    ? animationsFor(preset, { reverse: true, originX: '50%', originY: '50%' }, options, custom)
+    : null
+
+  const timing = `${duration}s cubic-bezier(${curve.join(', ')})`
+  // A reveal opens the arriving page over the leaving one: only the arrival
+  // animates, from the start, and the leaving picture just stays.
+  const revealsOver = !COVER_CLIPS[preset] && forward.arrive[1].clipPath !== undefined
+  const arriveTiming = revealsOver ? `${timing} both` : `${timing} ${duration}s both`
+  const rules = [
+    // Opting every page in is for page-to-page navigations only; a single-page
+    // app starts its own transitions and must not turn full reloads into them.
+    ...(target.crossDocument ? ['@view-transition {\n  navigation: auto;\n}'] : []),
+    '::view-transition-old(root),\n::view-transition-new(root) {\n  mix-blend-mode: normal;\n}',
+    revealsOver
+      ? '::view-transition-old(root) {\n  animation: none;\n}'
+      : `::view-transition-old(root) {\n  animation: tq-page-leave ${timing} both;\n}`,
+    `::view-transition-new(root) {\n  animation: tq-page-arrive ${arriveTiming};\n}`,
+    ...(revealsOver ? [] : [keyframes('tq-page-leave', forward.leave[0], forward.leave[1])]),
+    keyframes('tq-page-arrive', forward.arrive[0], forward.arrive[1]),
+  ]
+  if (COVER_CLIPS[preset]) {
+    rules.push(
+      `::view-transition-group(root) {\n  background: ${PageTransition.pageTransitionCoverColor(
+        options.color
+      )};\n}`
+    )
+  }
+  if (back) {
+    if (!revealsOver) {
+      rules.push(
+        `html[${BACK_ATTR}="back"]::view-transition-old(root) {\n  animation-name: tq-page-leave-back;\n}`
+      )
+    }
+    rules.push(
+      `html[${BACK_ATTR}="back"]::view-transition-new(root) {\n  animation-name: tq-page-arrive-back;\n}`,
+      ...(revealsOver ? [] : [keyframes('tq-page-leave-back', back.leave[0], back.leave[1])]),
+      keyframes('tq-page-arrive-back', back.arrive[0], back.arrive[1])
+    )
+  }
+  // The flying image spans both halves (the leaving page's and the arriving
+  // page's — one half when the arrival plays over the leaving page), and a
+  // card's 4:3 picture grows into a 16:9 hero cropped, never stretched. A
+  // picture the arriving page does not show has nowhere to land: it leaves
+  // with its page instead of lingering over the next one.
+  const flies = config.flyingPictures !== false
+  if (flies) {
+    const flight = revealsOver ? duration : duration * 2
+    rules.push(
+      `::view-transition-group(${MORPH_NAME}) {\n  animation-duration: ${flight}s;\n  animation-timing-function: cubic-bezier(${curve.join(
+        ', '
+      )});\n}`,
+      `::view-transition-old(${MORPH_NAME}),\n::view-transition-new(${MORPH_NAME}) {\n  height: 100%;\n  object-fit: cover;\n  overflow: clip;\n  animation-duration: ${flight}s;\n}`,
+      revealsOver
+        ? `::view-transition-old(${MORPH_NAME}):only-child {\n  animation: tq-morph-away ${timing} both;\n}`
+        : `::view-transition-old(${MORPH_NAME}):only-child {\n  animation: tq-page-leave ${timing} both, tq-morph-away ${timing} both;\n}`,
+      `::view-transition-new(${MORPH_NAME}):only-child {\n  animation: tq-page-arrive ${arriveTiming}, tq-morph-in ${arriveTiming};\n}`,
+      '@keyframes tq-morph-away {\n  to { opacity: 0; }\n}',
+      '@keyframes tq-morph-in {\n  from { opacity: 0; }\n}'
+    )
+  }
+  const indented = rules.map((rule) => rule.replace(/^/gm, '  ')).join('\n')
+  return {
+    css: `@media (prefers-reduced-motion: no-preference) {\n${indented}\n}\n`,
+    needsDirection,
+    needsOrigin,
+    flies,
+    revealsOver,
+  }
+}

package/src/scroll-scene/chapter-index.ts

@@ -0,0 +1,25 @@
+/**
+ * Which chapter is ON STAGE at a scene progress: the chapter whose moment is
+ * the latest one the visitor has passed (a later chapter wins a tie), -1 before
+ * any moment is reached. Moments are read in document order but need not be
+ * monotone — an author's "Snap here" can put an early chapter's moment late.
+ * The published TqScrollScene announces every change of this index as a
+ * `tq-chapter-reached` DOM event on the chapter element — the hook the
+ * "A Chapter Is Reached" workflow trigger listens for.
+ *
+ * Plain JS inside: this function's SOURCE is injected into the generated
+ * runtime via toString(), so no TypeScript-only runtime constructs and no
+ * template literals.
+ */
+export function activeChapterIndex(moments: number[], progress: number): number {
+  let active = -1
+  let best = -Infinity
+  for (let index = 0; index < moments.length; index++) {
+    const moment = moments[index]
+    if (moment <= progress + 0.000001 && moment >= best) {
+      best = moment
+      active = index
+    }
+  }
+  return active
+}