steppy-dev 0.3.0__py3-none-any.whl

steppy/templates/_steppy_tours.py

@@ -0,0 +1,404 @@
+"""In-app tour replay helpers — generated by Steppy, do not edit.
+
+Written next to ``conftest.py`` only when ``tours.enabled`` is set in
+``config.yaml``, and imported by the ``test_<slug>__tour`` functions that
+``steppy generate`` appends to opted-in scenarios. A replay follows the tour
+the way a user would: it checks the popover shows each step anchored on its
+target, performs the scenario's own action, and checks the tour moved on.
+
+Standalone on purpose (stdlib only): the generated suite must not depend on
+Steppy being importable at test time. The constants below mirror
+``steppy.naming`` / ``steppy.tour_spec`` and the overlay's DOM contract;
+``tests/test_tour_replay_helpers_mirror.py`` keeps them equal.
+
+Events are collected with a context-level init script plus an exposed binding,
+so they survive full navigations; callbacks only append to a list (sync
+Playwright API calls are not allowed inside them), and every wait pumps
+through ``page.wait_for_timeout`` so those callbacks are delivered.
+"""
+
+import json
+import os
+import time
+
+TOUR_HOST_TAG = "steppy-tour-host"
+TOUR_EVENTS = ("tour-start", "tour-step", "tour-complete", "tour-dismiss", "tour-offpath", "tour-error")
+TOURS_KILL_SWITCH_GLOBAL = "__STEPPY_TOURS_DISABLED__"
+TOUR_PROBE_BINDING = "__steppy_tour_event"
+ATTR_STEP_ID = "data-step-id"
+
+DEFINE_TIMEOUT_MS = 15000
+ADVANCE_TIMEOUT_MS = 10000
+INPUT_GRACE_MS = 750
+POLL_MS = 100
+SLACK_PX = 2
+
+_now = time.monotonic
+
+
+class TourReplayError(AssertionError):
+    """A tour step the replay could not follow — the message names tour, step and test-id."""
+
+
+_PROBE_JS = """
+(() => {
+  if (window.top !== window || window.__steppyTourProbe) return;
+  window.__steppyTourProbe = true;
+  for (const name of %s) {
+    window.addEventListener(name, (event) => {
+      let detail = null;
+      try { detail = JSON.parse(JSON.stringify(event.detail ?? null)); } catch (_) {}
+      try { window.%s({type: name, detail, path: location.pathname}); } catch (_) {}
+    }, true);
+  }
+})();
+""" % (json.dumps(list(TOUR_EVENTS)), TOUR_PROBE_BINDING)
+
+_START_JS = """
+async ({tag, id, params, locale, timeoutMs}) => {
+  const ready = await Promise.race([
+    customElements.whenDefined(tag).then(() => true),
+    new Promise((resolve) => setTimeout(() => resolve(false), timeoutMs)),
+  ]);
+  const host = document.querySelector(tag);
+  if (!host) return {error: 'missing'};
+  if (!ready) return {error: 'undefined'};
+  if (locale) host.locale = locale;
+  try {
+    return {ok: await host.start(id, {params})};
+  } catch (err) {
+    return {error: 'threw', message: String(err)};
+  }
+}
+"""
+
+_SNAPSHOT_JS = """
+([tag]) => {
+  const out = {path: location.pathname, defined: !!customElements.get(tag), host: false, active: false,
+               current: null, bubble: null, spotlight: null, pill: false,
+               viewport: {w: innerWidth, h: innerHeight}};
+  const host = document.querySelector(tag);
+  if (!host) return out;
+  out.host = true;
+  out.active = !!host.isActive;
+  out.current = host.current ? JSON.parse(JSON.stringify(host.current)) : null;
+  const root = host.shadowRoot;
+  if (!root) return out;
+  const shown = (el) => {
+    if (!el || !el.isConnected) return false;
+    const cs = getComputedStyle(el);
+    if (cs.display === 'none' || cs.visibility === 'hidden') return false;
+    const r = el.getBoundingClientRect();
+    return r.width > 0 && r.height > 0;
+  };
+  const rect = (el) => { const r = el.getBoundingClientRect(); return {x: r.left, y: r.top, w: r.width, h: r.height}; };
+  const bubble = root.querySelector('[part~="bubble"]');
+  if (shown(bubble)) {
+    const next = bubble.querySelector('[part~="next"]');
+    const body = bubble.querySelector('[part~="body"]') || bubble;
+    out.bubble = {stepId: bubble.getAttribute('data-step-id'), state: bubble.getAttribute('data-state'),
+                  rect: rect(bubble), text: body.textContent.trim(),
+                  next: next ? {disabled: !!next.disabled} : null};
+  }
+  const spot = root.querySelector('[part~="spotlight"]');
+  if (shown(spot)) out.spotlight = rect(spot);
+  out.pill = shown(root.querySelector('[part~="pill"]'));
+  return out;
+}
+"""
+
+
+def _callspec(request):
+    params = getattr(getattr(request.node, "callspec", None), "params", None) or {}
+    for value in params.values():
+        if isinstance(value, tuple) and len(value) == 2:
+            return value
+    return (None, None)
+
+
+def _css_string(value):
+    return '"' + str(value).replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+class TourProbe:
+    """Per-test state: the page, the baked tour spec and every tour event seen."""
+
+    def __init__(self, page, request, spec, *, step_runs):
+        self.page = page
+        self.spec = spec
+        self.step_runs = step_runs
+        self.steps = {step["id"]: step for step in spec["steps"]}
+        self.order = [step["id"] for step in spec["steps"]]
+        self.events = []
+        self.navigations = 0
+        self.start_mark = None
+        self.locale, self.layout = _callspec(request)
+        self.timeout_ms = max(int(spec.get("timeout_ms") or 0), DEFINE_TIMEOUT_MS)
+        page.context.expose_binding(TOUR_PROBE_BINDING, lambda source, payload: self.events.append(payload))
+        page.context.add_init_script(_PROBE_JS)
+        page.on("framenavigated", self._on_nav)
+        request.node._steppy_tour_probe = self
+
+    def _on_nav(self, frame):
+        if frame == self.page.main_frame and self.start_mark is not None:
+            self.navigations += 1
+
+    # ── plumbing ──────────────────────────────────────────────────────────
+
+    def pump(self, ms=POLL_MS):
+        self.page.wait_for_timeout(ms)
+
+    def snapshot(self):
+        try:
+            return self.page.evaluate(_SNAPSHOT_JS, [TOUR_HOST_TAG])
+        except Exception as exc:  # a navigation can destroy the context mid-call
+            return {"error": str(exc), "bubble": None, "spotlight": None, "active": False, "current": None}
+
+    def since_start(self, *types):
+        events = self.events[self.start_mark or 0 :]
+        return [e for e in events if not types or e.get("type") in types]
+
+    def advanced_past(self, step_id):
+        snap = self.snapshot()
+        if snap.get("error"):
+            return False
+        current = snap.get("current") or {}
+        if not snap.get("active"):
+            return bool(self.since_start("tour-complete"))
+        return current.get("stepId") not in (None, step_id)
+
+    # ── reporting ─────────────────────────────────────────────────────────
+
+    def describe(self, step_id):
+        step = self.steps.get(step_id) or {}
+        parts = [f'scenario step {step.get("scenario_step")} "{step.get("title", "")}"', step.get("action", "?")]
+        if step.get("target"):
+            parts.append(f'test-id "{step["target"]}"')
+        return f"[tour {self.spec['id']}] step '{step_id}' ({', '.join(parts)})"
+
+    def fail(self, step_id, problem, hint=None):
+        snap = self.snapshot()
+        bubble = snap.get("bubble") or {}
+        current = (snap.get("current") or {}).get("stepId")
+        lines = [f"{self.describe(step_id) if step_id else '[tour ' + self.spec['id'] + ']'}: {problem}"]
+        if hint:
+            lines.append(f"  hint: {hint}")
+        lines.append(
+            f"  page: {snap.get('path')}  tour: {'active' if snap.get('active') else 'inactive'}"
+            f"{', current ' + repr(current) if current else ''}  bubble: {bubble.get('state') or 'none'}"
+            f"  navigations since start: {self.navigations}"
+        )
+        tail = []
+        for event in self.events[-8:]:
+            detail = event.get("detail") or {}
+            label = detail.get("stepId") or detail.get("reason") or detail.get("source") or ""
+            if event.get("type") == "tour-error":
+                label = ", ".join(
+                    str(v) for v in (detail.get("reason"), detail.get("stepId") or detail.get("testId")) if v
+                )
+            tail.append(f"{event.get('type')}({label})")
+        lines.append("  last events: " + (" | ".join(tail) if tail else "none"))
+        raise TourReplayError("\n".join(lines))
+
+    def check_terminal(self, step_id, allow_complete=False):
+        for event in self.since_start("tour-error", "tour-dismiss", "tour-offpath"):
+            detail = event.get("detail") or {}
+            kind = event["type"]
+            if kind == "tour-error" and detail.get("reason") == "target-timeout":
+                which = detail.get("testId") or detail.get("stepId")
+                self.fail(
+                    detail.get("stepId") or step_id,
+                    f"target-timeout: the overlay never found [{self.spec['attribute']}={_css_string(which)}]"
+                    + (" (the waitFor gate)" if detail.get("kind") == "waitFor" else ""),
+                    "the test-id was renamed or removed in the app, or the element appears too late",
+                )
+            if kind == "tour-error":
+                self.fail(step_id, f"tour-error {detail.get('reason')}: {detail.get('message', '')}")
+            if kind == "tour-dismiss":
+                self.fail(step_id, f"the tour was dismissed ({detail.get('via') or detail.get('reason')})")
+            if kind == "tour-offpath":
+                self.fail(step_id, "the tour went off-path: its target disappeared and did not come back")
+        if not allow_complete and self.since_start("tour-complete"):
+            self.fail(step_id, "the tour completed before reaching this step")
+
+
+# ── the four calls a generated replay makes ───────────────────────────────
+
+
+def _tour_start(tour, params):
+    page, spec = tour.page, tour.spec
+    for name, query in (spec.get("layouts") or {}).items():
+        matches = bool(page.evaluate("(q) => matchMedia(q).matches", query))
+        expected = bool(tour.step_runs(None, [name]))
+        if matches != expected:
+            size = page.viewport_size or {}
+            raise TourReplayError(
+                f"[tour {spec['id']}] layout mismatch: this replay runs layout '{tour.layout or 'default'}' "
+                f"(viewport {size.get('width')}x{size.get('height')}) but tours.layouts['{name}'] = '{query}' "
+                f"evaluates {str(matches).lower()} there, so the overlay and the scenario disagree about {name} steps"
+            )
+    page.context.add_init_script(f"globalThis.{TOURS_KILL_SWITCH_GLOBAL} = false;")
+    page.evaluate(f"() => {{ globalThis.{TOURS_KILL_SWITCH_GLOBAL} = false; }}")
+    tour.start_mark = len(tour.events)
+    locale = tour.locale or spec.get("default_locale")
+    result = page.evaluate(
+        _START_JS,
+        {"tag": TOUR_HOST_TAG, "id": spec["id"], "params": params, "locale": locale, "timeoutMs": DEFINE_TIMEOUT_MS},
+    )
+    if result.get("error") == "missing":
+        tour.fail(None, f"<{TOUR_HOST_TAG}> is not on the page", "mount it once in the app shell")
+    if result.get("error") == "undefined":
+        tour.fail(None, f"<{TOUR_HOST_TAG}> was never defined", "import @steppy/player/tour in the app bundle")
+    if result.get("error"):
+        tour.fail(None, f"start() threw: {result.get('message')}")
+    deadline = _now() + tour.timeout_ms / 1000
+    while not tour.since_start("tour-start"):
+        for event in tour.since_start("tour-error"):
+            detail = event.get("detail") or {}
+            reason = detail.get("reason")
+            hints = {
+                "load-failed": "the app does not serve the tour files (check the manifest URL and the app-assets target)",
+                "invalid-data": "the tour files the app serves were rejected; regenerate them with steppy tours",
+                "schema-unsupported": "the app's overlay is older than the tour files",
+                "entry-params": f"route {(spec.get('entry') or {}).get('route')} could not be filled from {params}",
+            }
+            tour.fail(None, f"the tour did not start: {reason} {detail.get('message', '')}".rstrip(), hints.get(reason))
+        if _now() > deadline:
+            tour.fail(None, "tour-start never fired", "is the kill switch set, or the host `disabled`?")
+        tour.pump()
+    expected = os.environ.get("STEPPY_TOUR_EXPECT_BUILD_ID")
+    started = tour.since_start("tour-start")[0].get("detail") or {}
+    if expected and started.get("buildId") != expected:
+        tour.fail(
+            None,
+            f"the app serves tours built for {started.get('buildId')!r}, expected {expected!r}",
+            "rebuild the app after steppy tours, or align tours.build_id",
+        )
+
+
+def _tour_expect_step(tour, step_id, selector=None):
+    if tour.steps[step_id]["advance"] == "visible":
+        return _expect_visible_step(tour, step_id)
+    deadline = _now() + tour.timeout_ms / 1000
+    why = "the popover for this step never appeared"
+    while True:
+        tour.check_terminal(step_id)
+        snap = tour.snapshot()
+        bubble = snap.get("bubble")
+        if bubble and bubble.get("stepId") == step_id:
+            if bubble.get("state") == "fallback":
+                tour.fail(
+                    step_id,
+                    "target-timeout: the overlay shows its 'Can't find this element' fallback",
+                    "the test-id was renamed or removed in the app",
+                )
+            if not bubble.get("text"):
+                tour.fail(step_id, "the popover has no text")
+            if selector is None:
+                return
+            why = _anchored(tour, selector, snap)
+            if why is None:
+                return
+        elif bubble and bubble.get("stepId") in tour.order and step_id in tour.order:
+            if tour.order.index(bubble["stepId"]) > tour.order.index(step_id):
+                tour.fail(step_id, f"the tour skipped ahead to '{bubble['stepId']}'", "stale tour files?")
+        elif bubble and bubble.get("stepId") not in tour.order:
+            tour.fail(step_id, f"the overlay shows an unknown step '{bubble.get('stepId')}'", "stale tour files?")
+        if _now() > deadline:
+            tour.fail(step_id, why)
+        tour.pump()
+
+
+def _expect_visible_step(tour, step_id):
+    """A ``visible`` step advances by itself as soon as its target shows — when
+    the target is already there, in the same pass that reaches the step, before
+    any popover is drawn. So the proof the overlay reached it is its
+    ``tour-step`` event, not a popover; ``_tour_ensure_advanced`` then waits for
+    the tour to move past it."""
+    deadline = _now() + tour.timeout_ms / 1000
+    while True:
+        tour.check_terminal(step_id, allow_complete=True)
+        if any((e.get("detail") or {}).get("stepId") == step_id for e in tour.since_start("tour-step")):
+            return
+        bubble = tour.snapshot().get("bubble")
+        if bubble and bubble.get("stepId") in tour.order and step_id in tour.order:
+            if tour.order.index(bubble["stepId"]) > tour.order.index(step_id):
+                tour.fail(step_id, f"the tour skipped ahead to '{bubble['stepId']}'", "stale tour files?")
+        if tour.since_start("tour-complete"):
+            tour.fail(step_id, "the tour completed before reaching this step")
+        if _now() > deadline:
+            tour.fail(step_id, "the tour never reached this step")
+        tour.pump()
+
+
+def _anchored(tour, selector, snap):
+    """None when the spotlight sits on the element CI acts on, else why not."""
+    locator = tour.page.locator(selector)
+    try:
+        box = locator.first.bounding_box(timeout=1000)
+        if box is None:
+            box = locator.filter(visible=True).first.bounding_box(timeout=1000)
+    except Exception:
+        box = None
+    if box is None:
+        return f"the target {selector} is not visible"
+    cx, cy = box["x"] + box["width"] / 2, box["y"] + box["height"] / 2
+    spot = snap.get("spotlight")
+    if not spot:
+        return "the popover shows but no spotlight is drawn"
+    inside = (spot["x"] - SLACK_PX <= cx <= spot["x"] + spot["w"] + SLACK_PX) and (
+        spot["y"] - SLACK_PX <= cy <= spot["y"] + spot["h"] + SLACK_PX
+    )
+    if not inside:
+        return f"the spotlight {spot} is not on the target {box}"
+    b = (snap.get("bubble") or {}).get("rect")
+    if b and b["x"] <= cx <= b["x"] + b["w"] and b["y"] <= cy <= b["y"] + b["h"]:
+        return "the popover covers the centre of its own target"
+    return None
+
+
+def _tour_ensure_advanced(tour, step_id):
+    kind = tour.steps[step_id]["advance"]
+    if kind in ("input", "manual"):
+        if kind == "input":
+            grace = _now() + INPUT_GRACE_MS / 1000
+            while _now() < grace:
+                if tour.advanced_past(step_id):
+                    return
+                tour.pump()
+        selector = f'{TOUR_HOST_TAG} [part~="bubble"][{ATTR_STEP_ID}={_css_string(step_id)}] [part~="next"]'
+        button = tour.page.locator(selector)
+        if button.count() == 0:
+            if tour.advanced_past(step_id):
+                return
+            tour.fail(step_id, "the popover has no Next button")
+        if button.first.is_disabled():
+            tour.fail(step_id, "Next is disabled: the overlay saw an empty value", "did the action fill the field?")
+        button.first.click()
+    deadline = _now() + ADVANCE_TIMEOUT_MS / 1000
+    while not tour.advanced_past(step_id):
+        tour.check_terminal(step_id, allow_complete=True)
+        if _now() > deadline:
+            hints = {
+                "change": "the overlay saw no value change on its target (a body-appended option list "
+                "the popover covers? an already-selected value?)",
+                "click": "the click did not reach the target the tour points at",
+            }
+            tour.fail(step_id, f"the tour did not advance after the step's action ({kind})", hints.get(kind))
+        tour.pump()
+
+
+def _tour_expect_complete(tour):
+    deadline = _now() + tour.timeout_ms / 1000
+    while not tour.since_start("tour-complete"):
+        tour.check_terminal(None, allow_complete=True)
+        if _now() > deadline:
+            tour.fail(None, "tour-complete never fired after the last step")
+        tour.pump()
+    for event in tour.since_start("tour-error", "tour-dismiss", "tour-offpath"):
+        tour.fail(None, f"{event['type']} during the tour: {event.get('detail')}")
+    seen = {(e.get("detail") or {}).get("stepId") for e in tour.since_start("tour-step")}
+    for step in tour.spec["steps"]:
+        applicable = not step.get("layouts") or tour.step_runs(None, step["layouts"])
+        if applicable and step["id"] not in seen:
+            tour.fail(step["id"], "the tour completed without showing this step")

steppy/templates/angular/component-interactive.ts.j2

@@ -0,0 +1,109 @@
+// GENERATED BY STEPPY — DO NOT EDIT. Regenerate with: steppy build
+//
+// Interactive guide host component for "{{ slug }}". Mounts the
+// ``<steppy-guide>`` Lit web component (shipped as @steppy/player's ESM
+// bundle) against the per-guide ``guide.json`` manifest emitted alongside
+// the screenshots in the host app's ``public/assets/{{ role }}/{{ slug }}/`` directory.
+//
+// The player bundle (``steppy-player.js``) is fetched once on first mount —
+// no host npm install required. Subsequent interactive components reuse the
+// already-loaded custom element.
+import {
+  Component,
+  CUSTOM_ELEMENTS_SCHEMA,
+  inject,
+{% if has_multiple_layouts %}
+  input,
+{% endif %}
+  OnInit,
+  ViewEncapsulation,
+} from '@angular/core';
+import { toSignal } from '@angular/core/rxjs-interop';
+import { map, startWith } from 'rxjs/operators';
+import { TranslateService } from '@ngx-translate/core';
+
+const PLAYER_BUNDLE_URL = '/assets/{{ role }}/steppy-player.js';
+const MANIFEST_URL = '/assets/{{ role }}/{{ slug }}/guide.json';
+let playerScriptLoading: Promise<void> | null = null;
+
+function ensurePlayerLoaded(): Promise<void> {
+  // Idempotent: only inserts the <script> tag once per page, regardless of
+  // how many interactive guides mount.
+  if (playerScriptLoading) return playerScriptLoading;
+  if (typeof window === 'undefined' || typeof document === 'undefined') {
+    return Promise.resolve();
+  }
+  if (customElements.get('steppy-guide')) {
+    playerScriptLoading = Promise.resolve();
+    return playerScriptLoading;
+  }
+  playerScriptLoading = new Promise<void>((resolve, reject) => {
+    const script = document.createElement('script');
+    script.type = 'module';
+    script.src = PLAYER_BUNDLE_URL;
+    script.async = true;
+    script.onload = () => resolve();
+    script.onerror = (err) => reject(err);
+    document.head.appendChild(script);
+  });
+  return playerScriptLoading;
+}
+
+@Component({
+  selector: 'app-guide-{{ slug }}-interactive',
+  standalone: true,
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  template: `
+    <steppy-guide
+      class="steppy-guide-host"
+      [attr.src]="manifestUrl"
+      [attr.locale]="locale()"
+{% if has_multiple_layouts %}
+      [attr.variant]="variant()"
+      hide-layout-switcher
+{% endif %}
+{% if cursor_mode %}
+      cursor="{{ cursor_mode }}"
+{% endif %}
+      template="{{ default_template }}"
+    ></steppy-guide>
+  `,
+  styles: [`
+    :host { display: block; }
+    .steppy-guide-host { display: block; width: 100%; }
+  `],
+  encapsulation: ViewEncapsulation.None,
+})
+export class {{ class_name }}InteractiveComponent implements OnInit {
+  private readonly translate = inject(TranslateService);
+
+  readonly manifestUrl = MANIFEST_URL;
+{% if has_multiple_layouts %}
+  // Layout (variant) is driven by the host toolbar's layout toggle (the parent
+  // component binds [variant]="selectedLayout()"); the player's built-in
+  // switcher is suppressed via `hide-layout-switcher`.
+  readonly variant = input<string>('{{ default_layout }}');
+{% endif %}
+
+  // Bridge ngx-translate's current language into the player's locale
+  // attribute. The player handles the switch internally on attribute change.
+  readonly locale = toSignal(
+    this.translate.onLangChange.pipe(
+      map((event) => event.lang),
+      startWith(
+        this.translate.currentLang ||
+        this.translate.getDefaultLang() ||
+        '{{ default_locale }}',
+      ),
+    ),
+    { initialValue:
+        this.translate.currentLang ||
+        this.translate.getDefaultLang() ||
+        '{{ default_locale }}',
+    },
+  );
+
+  ngOnInit(): void {
+    void ensurePlayerLoaded();
+  }
+}

steppy/templates/angular/component-video.ts.j2

@@ -0,0 +1,112 @@
+// GENERATED BY STEPPY — DO NOT EDIT. Regenerate with: steppy build
+//
+// Video guide host component for "{{ slug }}". Plays the narrated MP4 that
+// ``steppy build --video`` rendered from this guide's captures, served from the
+// host app's ``public/assets/{{ role }}/{{ slug }}/`` directory alongside the
+// screenshots.
+//
+// Unlike the interactive mode there is no player bundle to load: the artifact
+// is a plain ``.mp4`` with a WebVTT caption track, so a native ``<video>`` is
+// the whole implementation. Locale (and layout, when the guide has several)
+// select which rendering to play.
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  effect,
+  ElementRef,
+  inject,
+{% if has_multiple_layouts %}
+  input,
+{% endif %}
+  ViewChild,
+  ViewEncapsulation,
+} from '@angular/core';
+import { toSignal } from '@angular/core/rxjs-interop';
+import { map, startWith } from 'rxjs/operators';
+import { TranslateService } from '@ngx-translate/core';
+
+const ASSET_BASE = '/assets/{{ role }}/{{ slug }}';
+
+// key -> {src, poster, captions}, keyed exactly as the build named the files.
+const VIDEOS: Record<string, { src: string; poster: string; captions: string }> = {
+{% for key, item in videos.items() %}
+  '{{ key }}': {
+    src: `${ASSET_BASE}/{{ item.file }}`,
+    poster: `${ASSET_BASE}/{{ item.poster_file }}`,
+    captions: `${ASSET_BASE}/{{ item.captions_file }}`,
+  },
+{% endfor %}
+};
+
+const FALLBACK_KEY = '{{ default_key }}';
+
+@Component({
+  selector: 'app-guide-{{ slug }}-video',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  template: `
+    <video
+      #player
+      class="steppy-video-host"
+      controls
+      playsinline
+      preload="metadata"
+      [poster]="current().poster"
+    >
+      <source [src]="current().src" type="video/mp4" />
+      <track kind="captions" [src]="current().captions" [srclang]="locale()" default />
+    </video>
+  `,
+  styles: [`
+    :host { display: block; }
+    .steppy-video-host { display: block; width: 100%; background: #000; border-radius: 8px; }
+  `],
+  encapsulation: ViewEncapsulation.None,
+})
+export class {{ class_name }}VideoComponent {
+  private readonly translate = inject(TranslateService);
+
+  @ViewChild('player') private playerRef?: ElementRef<HTMLVideoElement>;
+
+{% if has_multiple_layouts %}
+  readonly variant = input<string>('{{ default_layout }}');
+{% endif %}
+
+  readonly locale = toSignal(
+    this.translate.onLangChange.pipe(
+      map((event) => event.lang),
+      startWith(
+        this.translate.currentLang ||
+        this.translate.getDefaultLang() ||
+        '{{ default_locale }}',
+      ),
+    ),
+    { initialValue:
+        this.translate.currentLang ||
+        this.translate.getDefaultLang() ||
+        '{{ default_locale }}',
+    },
+  );
+
+  readonly current = computed(() => {
+{% if has_multiple_layouts %}
+    const key = `${this.locale()}-${this.variant()}`;
+{% else %}
+    const key = this.locale();
+{% endif %}
+    return VIDEOS[key] ?? VIDEOS[FALLBACK_KEY];
+  });
+
+  constructor() {
+    // Changing a <source> element after load is a no-op — the browser only
+    // re-reads the media when load() is called on the <video> itself.
+    effect(() => {
+      this.current();
+      const element = this.playerRef?.nativeElement;
+      if (!element) return;
+      element.pause();
+      element.load();
+    });
+  }
+}