steppy-dev 0.3.0__py3-none-any.whl

steppy/templates/guide.md.j2

@@ -0,0 +1,18 @@
+# {{ title }}
+
+> Guide pour l'application **{{ role }}**
+
+{% for step in steps %}
+## Étape {{ step.index }} : {{ step.title }}
+
+{% if step.subtitle %}
+*{{ step.subtitle }}*
+
+{% endif %}
+{% if step.text %}
+{{ step.text }}
+
+{% endif %}
+![Étape {{ step.index }}]({{ step.screenshot }})
+
+{% endfor %}

steppy/templates/init/config.yaml

@@ -0,0 +1,124 @@
+# yaml-language-server: $schema=./steppy-config.schema.json
+#
+# Steppy configuration — created by `steppy init`.
+#
+# A "role" is one front-end app / persona you test. This starter uses
+# admin / editor / viewer; rename them (and their URLs) to fit your product,
+# then add/remove roles freely.
+#
+# Credentials use ${ENV_VAR} references so no secrets live in this committed
+# file. Set the vars in your environment/CI, or copy credentials.yaml.example to
+# credentials.yaml (gitignored) and fill in real values. ${VAR:-default}
+# supplies a fallback. See SECURITY.md in the Steppy repo for details.
+#
+# The `# yaml-language-server` line above wires up autocomplete + inline typo
+# checking in editors with the YAML extension (VS Code, etc.).
+apps:
+  admin:
+    name: "My App — Admin"
+    url: "http://localhost:3000"
+    auth:
+      # `form` = generic hosted-login form-fill (works with any IdP that has a
+      # fillable login form: Auth0, Keycloak, …). Other modes: storage-state,
+      # bypass, token. See STEPPY-REFERENCE.md.
+      mode: form
+      credentials:
+        username: "${STEPPY_ADMIN_USERNAME}"
+        password: "${STEPPY_ADMIN_PASSWORD}"
+    # Per-locale localStorage values, set before screenshots so the app renders
+    # in the right language during `steppy run --guide`.
+    i18n:
+      localstorage:
+        key: "app-language"
+        values:
+          en: "en"
+          fr: "fr"
+  editor:
+    name: "My App — Editor"
+    url: "http://localhost:3001"
+    auth:
+      mode: form
+      credentials:
+        username: "${STEPPY_EDITOR_USERNAME}"
+        password: "${STEPPY_EDITOR_PASSWORD}"
+  viewer:
+    name: "My App — Viewer"
+    url: "http://localhost:3002"
+    auth:
+      mode: form
+      credentials:
+        username: "${STEPPY_VIEWER_USERNAME}"
+        password: "${STEPPY_VIEWER_PASSWORD}"
+
+# Auth settings. The `form:` block holds the three login-form selectors; name an
+# IdP `preset:` (auth0 | keycloak) to fill them at once.
+auth:
+  storage_state_dir: "./.auth"
+  storage_state_ttl: 3600  # seconds (1 hour)
+  form:
+    # preset: keycloak      # -> #username / #password / #kc-login
+    username_selector: "input[name='username'], input[name='email'], #username"
+    password_selector: "input[name='password'], #password"
+    submit_selector: "button[type='submit'], button[name='action'][value='default']"
+    post_login_url_pattern: "**/callback**"
+    consent_selector: null
+
+# Supported locales for guide generation. Add any locale code here.
+locales:
+  - en
+  - fr
+
+default_locale: en
+
+screenshot:
+  viewport:
+    width: 1280
+    height: 720
+  format: png
+  full_page: false
+  highlight: true
+  highlight_color: "rgba(255, 0, 0, 0.3)"
+  highlight_border: "2px solid red"
+
+timing:
+  navigation_wait: 2000
+  action_wait: 500
+  sqs_wait: 5000
+  step_timeout: 30000
+
+# Where artifacts are written and read back, resolved against the project root.
+# `screenshots_dir` is honoured by the capture side and by every reader
+# (`steppy guide`, `steppy build`, `steppy bundle`); `guides_dir` is where
+# `steppy guide` writes. Pointing either outside `output/` works, but only
+# `output/` is bundled, uploaded by the CI template, gitignored, and mounted
+# back to the host by `steppy run --workers N`.
+output:
+  screenshots_dir: "./output/screenshots"
+  guides_dir: "./output/guides"
+
+# Optional blocks not shown here (all off / absent by default):
+#   report:    JUnit XML, HTML report, Playwright trace + video on failure, retries
+#   parallel:  `steppy run --workers N` — Docker-backed parallel execution, plus the
+#              retry pass (flaky vs. real failures), circuit breaker and auth isolation
+#   coverage:  `steppy run --coverage` + the `steppy coverage` gap report. Set
+#              `coverage.non_ui` there (health checks, webhooks, cron callbacks)
+#              or CI counts them against you — triage flags live in the
+#              gitignored .steppy/coverage.db and a fresh checkout has none.
+#   security:  shell-capture gate; see also `screenshot.mask` for redaction
+#   pdf:       paper settings for `--pdf` / `--handbook`
+#   video:     `--video` narrated MP4 export, incl. the `video.tts` provider
+#              (none | piper | espeak | elevenlabs | openai | azure | google | http).
+#              Run `steppy video check` to verify the toolchain.
+#   tours:     in-app tours from `tour:`-enabled scenarios — `steppy generate`
+#              writes tour JSON into your app's assets plus a CI replay per tour.
+#              Minimal: `tours: {enabled: true, targets: [{type: app-assets,
+#              path: ../your-app/public/tours}]}`; CI gate: `steppy tours
+#              --check`. The overlay's buttons ship in en/fr/nl/de (other tour
+#              languages need the host's `strings`). See docs/tours.md in the
+#              Steppy repository.
+#   cloud:     `url:` of a Steppy control plane, for `steppy bundle upload`.
+#              The URL only — the token is read from STEPPY_CLOUD_TOKEN (or
+#              --token) and has no config key on purpose, because this file is
+#              committed. Everything else here works with no plane at all.
+# Each is documented with commented examples in the Steppy repo's own config.yaml,
+# and your editor will autocomplete them from the $schema line at the top.

steppy/templates/init/credentials.yaml.example

@@ -0,0 +1,30 @@
+# credentials.yaml — LOCAL, GIT-IGNORED credential overlay.
+#
+# Copy this file to `credentials.yaml` (same directory as config.yaml) and fill
+# in real values. It is deep-merged ON TOP of config.yaml at load time, so it
+# only needs the `apps.<role>.auth.credentials` blocks you want to override —
+# everything else is inherited from config.yaml.
+#
+# `credentials.yaml` is listed in .gitignore and must never be committed. Prefer
+# this file (or ${ENV_VAR} references in config.yaml) over inline plaintext
+# secrets. See SECURITY.md for the full credential-handling guidance.
+#
+# You can ALSO keep credentials.yaml env-referenced if you like — the same
+# ${VAR} / ${VAR:-default} interpolation applies to this overlay.
+
+apps:
+  admin:
+    auth:
+      credentials:
+        username: "test-admin@example.com"
+        password: "change-me"
+  editor:
+    auth:
+      credentials:
+        username: "test-editor@example.com"
+        password: "change-me"
+  viewer:
+    auth:
+      credentials:
+        username: "test-viewer@example.com"
+        password: "change-me"

steppy/templates/init/scenarios/example--first-flow.md

@@ -0,0 +1,53 @@
+---
+title: Create a project
+description: A starter scenario — an admin creates a new project
+tags:
+  - e2e
+  - user-guide-admin
+priority: high
+guide:
+  enabled: true
+---
+
+# This is a starter scenario written by `steppy init`. Each `###` heading is a
+# step; each `- key: value` bullet is a field. Replace the selectors, URLs, and
+# text with your app's. Run `steppy validate` to check it, then `steppy generate`
+# to produce the Playwright test. See STEPPY-REFERENCE.md for the full grammar.
+
+### 1. Admin opens the projects list
+- role: admin
+- action: navigate
+- target: /projects
+- screenshot: admin
+- guide-text:
+  en: "From the main menu, open 'Projects' to see all projects."
+  fr: "Depuis le menu principal, ouvrez 'Projets' pour voir tous les projets."
+
+### 2. Admin starts a new project
+- role: admin
+- action: click
+- selector: [data-testid="new-project-btn"]
+- screenshot: admin
+- guide-text:
+  en: "Click 'New project' in the top-right corner."
+  fr: "Cliquez sur 'Nouveau projet' en haut à droite."
+
+### 3. Admin names the project
+- role: admin
+- action: fill
+- selector: [data-testid="project-name"]
+- value: "Website redesign"
+- screenshot: admin
+- guide-text:
+  en: "Give the project a clear, descriptive name."
+  fr: "Donnez au projet un nom clair et descriptif."
+
+### 4. Admin saves the project
+- role: admin
+- action: click
+- selector: [data-testid="save-project-btn"]
+- expect: contains([data-testid="toast"], "Project created")
+- screenshot: admin
+- guide-text:
+  en: "Save to create the project — it now appears in the list."
+  fr: "Enregistrez pour créer le projet — il apparaît maintenant dans la liste."

steppy/templates/report/_head.html.j2

@@ -0,0 +1,14 @@
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    {# Always private. A run report has no SEO value, and ADR 0013 is emphatic
+       that a published Pages site means permanently indexed screenshots — so
+       there is deliberately no config knob to turn this off. The guides site
+       keeps its own SeoConfig for the case where publishing IS the point.
+
+       This meta is the real control: robots.txt only stops the fetch, and a
+       crawler that never fetches the page never learns it is noindex. #}
+    <meta name="robots" content="noindex,nofollow,noarchive">
+    <title>{{ page_title }}</title>
+    <link rel="stylesheet" href="{{ root }}assets/report.css">
+    {# The app icon from docs/brand/steppy-icon.svg, inlined so the report stays one self-contained tree. #}
+    <link rel="icon" type="image/svg+xml" href="data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220.00 0.00 200.00 200.00%22 width=%22200%22 height=%22200%22 role=%22img%22 aria-label=%22steppy%22%3E%3Ctitle%3Esteppy%3C/title%3E%3Crect width=%22200%22 height=%22200%22 rx=%2250%22 fill=%22%2315332A%22/%3E%3Cg transform=%22translate%2815 15%29 scale%280.85%29%22%3E%3Cpath d=%22M68 40H42V160H68M132 40H158V160H132%22 fill=%22none%22 stroke=%22%23E4E9E1%22 stroke-width=%2218%22 stroke-linejoin=%22miter%22/%3E%3Cpath d=%22M74 102L95 123L130 80%22 fill=%22none%22 stroke=%22%23D2561A%22 stroke-width=%2220%22 stroke-linecap=%22round%22 stroke-linejoin=%22round%22/%3E%3C/g%3E%3C/svg%3E">

steppy/templates/report/_mark.html.j2

@@ -0,0 +1,3 @@
+{# The steppy mark (logo track C), inline so the brackets follow the theme
+   via report.css; aria-hidden because the h1 beside it carries the text. #}
+<svg class="steppy-mark" viewBox="0 0 200 200" aria-hidden="true" focusable="false"><path class="steppy-mark-brackets" d="M68 40H42V160H68M132 40H158V160H132" fill="none" stroke-width="18" stroke-linejoin="miter"/><path class="steppy-mark-check" d="M74 102L95 123L130 80" fill="none" stroke-width="20" stroke-linecap="round" stroke-linejoin="round"/></svg>

steppy/templates/report/coverage.html.j2

@@ -0,0 +1,124 @@
+{# The gap buckets. Not line coverage: this answers "which of my declared routes
+   and API endpoints has any e2e scenario actually exercised". Autoescape is ON. #}
+<!doctype html>
+<html lang="en">
+<head>
+{% include "report/_head.html.j2" %}
+</head>
+<body>
+    <header class="steppy-report-header">
+        <h1>{% include "report/_mark.html.j2" %}E2E surface coverage</h1>
+        <p class="steppy-report-meta steppy-small">
+            <span><a href="{{ root }}index.html">&larr; Run report</a></span>
+            <span>source: {{ coverage.tier }}</span>
+        </p>
+    </header>
+
+    <main class="steppy-report-main">
+
+        <section class="steppy-report-section">
+            <div class="steppy-badge-line">
+                {% if coverage.badge.percent is not none %}
+                <span class="steppy-pct">{{ coverage.badge.percent }}%</span>
+                <span class="steppy-muted">
+                    {{ coverage.badge.tested }} of {{ coverage.badge.declared }} declared
+                    {{ coverage.badge.surface if coverage.badge.surface != 'all' else 'endpoints and routes' }}
+                    a UI test could reach
+                </span>
+                {% else %}
+                <span class="steppy-pct steppy-muted">n/a</span>
+                <span class="steppy-muted">
+                    nothing declared. Configure <code>coverage.apis</code> (and optionally
+                    <code>coverage.sitemap</code>), then run <code>steppy coverage refresh</code>.
+                </span>
+                {% endif %}
+            </div>
+            <p class="steppy-small steppy-muted">
+                This is not line coverage. It answers which of the routes and API endpoints you
+                <em>declared</em> any scenario actually exercised — the denominator is the declared
+                surface minus what is marked non-UI-testable.
+            </p>
+            {% if coverage.non_ui.declared %}
+            <p class="steppy-small">
+                {{ coverage.non_ui.declared }} declared item{{ '' if coverage.non_ui.declared == 1 else 's' }}
+                discounted as <code>non_ui</code>
+                ({% for source, count in coverage.non_ui.by_source.items() %}{{ count }} from {{ source }}{% if not loop.last %}, {% endif %}{% endfor %}).
+                Committed rules live in <code>coverage.non_ui</code>; a <code>store</code> source is
+                a flag set locally with <code>steppy coverage triage set</code>.
+            </p>
+            {% endif %}
+        </section>
+
+        {% if not coverage.capabilities_strength %}
+        <div class="steppy-notice">
+            <strong>Assert strength is not shown.</strong> These numbers were rebuilt from the
+            run's raw records, and a bundle carries no <code>scenarios/*.md</code> to count assert
+            steps in — so every tested endpoint would read as weakly covered, which would be a
+            plausible-looking lie. Run <code>steppy coverage report</code> in the project for the
+            strong/weak split.
+        </div>
+        {% endif %}
+
+        {% for kind in ('endpoints', 'routes') %}
+        {% set counts = coverage.counts.get(kind) %}
+        {% if counts %}
+        <section class="steppy-report-section">
+            <h2>{{ kind | capitalize }}</h2>
+            <p class="steppy-report-meta">
+                <span><strong>{{ counts.declared }}</strong> declared</span>
+                <span><strong>{{ counts.tested }}</strong> tested{% if coverage.capabilities_strength %} ({{ counts.tested_strong }} strongly asserted){% endif %}</span>
+                <span><strong>{{ counts.declared_unreached }}</strong> never reached ({{ counts.declared_unreached_actionable }} actionable)</span>
+                <span><strong>{{ counts.discovered_uncovered }}</strong> seen but weakly covered</span>
+                {% if counts.discovered_tested %}<span><strong>{{ counts.discovered_tested }}</strong> tested but undeclared</span>{% endif %}
+            </p>
+
+            {% set unreached = bucket(kind, 'declared_unreached') | rejectattr('triage', 'equalto', 'non_ui') | list %}
+            {% if unreached %}
+            <h3 class="steppy-small">Declared but never reached &mdash; where a new scenario pays off</h3>
+            <div class="steppy-scroll">
+                <table class="steppy-report-table">
+                    <thead><tr>{% if kind == 'endpoints' %}<th>API</th><th>Method</th>{% endif %}<th>Path</th></tr></thead>
+                    <tbody>
+                        {% for row in unreached[:200] %}
+                        <tr>{% if kind == 'endpoints' %}<td>{{ row.api }}</td><td>{{ row.method }}</td>{% endif %}<td><code>{{ row.key }}</code></td></tr>
+                        {% endfor %}
+                    </tbody>
+                </table>
+            </div>
+            {% if unreached | length > 200 %}
+            <p class="steppy-small steppy-muted">&hellip; and {{ unreached | length - 200 }} more; see <a href="{{ root }}report.json">report.json</a>.</p>
+            {% endif %}
+            {% endif %}
+
+            {% set weak = bucket(kind, 'discovered_uncovered') %}
+            {% if weak %}
+            <h3 class="steppy-small">Exercised but not asserted</h3>
+            <div class="steppy-scroll">
+                <table class="steppy-report-table">
+                    <thead><tr>{% if kind == 'endpoints' %}<th>API</th><th>Method</th>{% endif %}<th>Path</th><th>Scenarios</th></tr></thead>
+                    <tbody>
+                        {% for row in weak[:200] %}
+                        <tr>{% if kind == 'endpoints' %}<td>{{ row.api }}</td><td>{{ row.method }}</td>{% endif %}<td><code>{{ row.key }}</code></td><td class="steppy-small">{{ row.scenarios | join(', ') }}</td></tr>
+                        {% endfor %}
+                    </tbody>
+                </table>
+            </div>
+            {% endif %}
+        </section>
+        {% endif %}
+        {% endfor %}
+
+        {% if coverage.warnings %}
+        <section class="steppy-report-section">
+            <h2>Warnings</h2>
+            <ul class="steppy-small">{% for warning in coverage.warnings %}<li>{{ warning }}</li>{% endfor %}</ul>
+        </section>
+        {% endif %}
+
+    </main>
+
+    <footer class="steppy-report-footer">
+        <p><a href="{{ root }}index.html">&larr; Run report</a></p>
+    </footer>
+</body>
+</html>

steppy/templates/report/index.html.j2

@@ -0,0 +1,203 @@
+{# Run report landing page. Rendered with autoescape ON — every value below comes
+   from a bundle, and a failure tail is arbitrary page content. #}
+<!doctype html>
+<html lang="en">
+<head>
+{% include "report/_head.html.j2" %}
+</head>
+<body>
+    <header class="steppy-report-header">
+        <h1>{% include "report/_mark.html.j2" %}{{ title }}</h1>
+        <p class="steppy-report-meta steppy-small">
+            <span>{{ report.run.run_id }}</span>
+            <span>{{ report.run.created_at }}</span>
+            <span>steppy {{ report.run.steppy_version }}</span>
+            <span>{{ report.run.executor }}</span>
+        </p>
+    </header>
+
+    <main class="steppy-report-main">
+
+        <section class="steppy-report-section">
+            <div class="steppy-counts">
+                <span class="steppy-verdict" data-outcome="{{ report.totals.verdict }}">{{ report.totals.verdict | upper }}</span>
+                <span class="steppy-muted">
+                    {{ report.totals.scenarios }} scenario{{ '' if report.totals.scenarios == 1 else 's' }},
+                    {{ report.totals.tests }} test{{ '' if report.totals.tests == 1 else 's' }}
+                </span>
+                {% for outcome, count in report.totals.outcomes.items() %}
+                <span class="steppy-chip" data-outcome="{{ outcome }}">{{ count }} {{ outcome }}</span>
+                {% endfor %}
+            </div>
+            <dl class="steppy-report-meta">
+                {% if report.run.git.branch or report.run.git.sha %}
+                <div><dt>Commit</dt><dd>{{ report.run.git.branch or '(detached)' }}{% if report.run.git.sha %} @ {{ report.run.git.sha[:8] }}{% endif %}{% if report.run.git.pr %} (PR #{{ report.run.git.pr }}){% endif %}</dd></div>
+                {% endif %}
+                {% if report.dimensions.locales %}
+                <div><dt>Locales</dt><dd>{{ report.dimensions.locales | join(', ') }}</dd></div>
+                {% endif %}
+                {% if report.dimensions.layouts %}
+                <div><dt>Layouts</dt><dd>{{ report.dimensions.layouts | join(', ') }}</dd></div>
+                {% endif %}
+                {% if report.run.spec.workers and report.run.spec.workers > 1 %}
+                <div><dt>Workers</dt><dd>{{ report.run.spec.workers }}</dd></div>
+                {% endif %}
+                {% if report.run.spec.guide %}<div><dt>Mode</dt><dd>guide capture</dd></div>{% endif %}
+                {# Named for what it is: under --workers N this is not wall clock,
+                   and a bundle carries no finished_at to compute that from. #}
+                <div><dt>Test time</dt><dd>{{ report.totals.duration_ms_sum | duration }}</dd></div>
+            </dl>
+        </section>
+
+        {% if report.truncated %}
+        <div class="steppy-notice">
+            <strong>Truncated.</strong> The size budget dropped artifacts that belonged in this
+            bundle, so something below may be missing. Screenshots and their sidecars are never
+            dropped — see the warnings for what was.
+        </div>
+        {% endif %}
+
+        {% if not report.capabilities.step_timeline and report.totals.tests %}
+        <div class="steppy-notice">
+            No per-step timeline was recorded for this run, so the pages below show outcomes
+            without step detail. Either the run did not pass <code>--bundle</code> (which sets
+            <code>STEPPY_STEP_EVENTS=1</code>), it set <code>STEPPY_STEP_EVENTS=0</code>, or the
+            tests were generated before per-step markers existed — re-run
+            <code>steppy generate</code> in that case.
+        </div>
+        {% endif %}
+
+        {% if not report.totals.tests %}
+        <div class="steppy-notice">
+            This run recorded <strong>no test outcomes</strong>. The scenarios below were
+            reconstructed from the captures on disk. Add <code>--bundle</code> to the run
+            (<code>steppy run --bundle</code>) so outcomes, failure tails and step boundaries are
+            written down.
+        </div>
+        {% endif %}
+
+        {% if report.failure_causes %}
+        <section class="steppy-report-section">
+            <h2>Failure causes ({{ report.failure_causes | length }} distinct)</h2>
+            <p class="steppy-small steppy-muted">
+                Grouped by normalised failure text, biggest first. One broken selector across
+                forty scenarios is one row here, not forty tracebacks. The tail shown is the
+                first occurrence's — the rest are the same failure.
+            </p>
+            {% for cause in report.failure_causes %}
+            <div class="steppy-cause">
+                <div class="steppy-cause-head">
+                    <span class="steppy-cause-count">&times;{{ cause.count }}</span>
+                    <span class="steppy-cause-headline">{{ cause.headline }}</span>
+                    <span class="steppy-fingerprint">{{ cause.fingerprint }}</span>
+                </div>
+                <p class="steppy-small steppy-muted">
+                    {% for slug in cause.scenarios[:8] %}<a href="{{ scenario_href(slug) }}">{{ slug }}</a>{% if not loop.last %}, {% endif %}{% endfor %}
+                    {% if cause.scenarios | length > 8 %} and {{ cause.scenarios | length - 8 }} more{% endif %}
+                </p>
+                {% if cause.exemplar_tail %}
+                <pre class="steppy-tail">{{ cause.exemplar_tail }}</pre>
+                {% endif %}
+            </div>
+            {% endfor %}
+        </section>
+        {% endif %}
+
+        <section class="steppy-report-section">
+            <h2>Scenarios</h2>
+            <div class="steppy-scroll">
+                <table class="steppy-report-table">
+                    <thead>
+                        <tr>
+                            <th>Scenario</th>
+                            {% if matrix_columns %}{% for column in matrix_columns %}<th>{{ column.label }}</th>{% endfor %}
+                            {% else %}<th>Outcome</th>{% endif %}
+                            <th>Test time</th>
+                        </tr>
+                    </thead>
+                    <tbody>
+                        {% for scenario in report.scenarios %}
+                        <tr>
+                            <td><a href="{{ scenario.href }}">{{ scenario.slug }}</a></td>
+                            {% if matrix_columns %}
+                            {% for column in matrix_columns %}
+                            {% set cell = matrix_cell(scenario, column) %}
+                            <td>{% if cell %}<span class="steppy-chip" data-outcome="{{ cell }}">{{ cell }}</span>{% else %}<span class="steppy-muted">&mdash;</span>{% endif %}</td>
+                            {% endfor %}
+                            {% else %}
+                            <td><span class="steppy-chip" data-outcome="{{ scenario.outcome }}">{{ scenario.outcome }}</span></td>
+                            {% endif %}
+                            <td class="steppy-muted">{{ scenario.duration_ms_sum | duration }}</td>
+                        </tr>
+                        {% endfor %}
+                    </tbody>
+                </table>
+            </div>
+        </section>
+
+        {% if report.coverage.tier != 'none' %}
+        <section class="steppy-report-section">
+            <h2>E2E surface coverage</h2>
+            <div class="steppy-badge-line">
+                {% if report.coverage.badge.percent is not none %}
+                <span class="steppy-pct">{{ report.coverage.badge.percent }}%</span>
+                <span class="steppy-muted">
+                    {{ report.coverage.badge.tested }} of {{ report.coverage.badge.declared }}
+                    declared endpoints and routes a UI test could reach
+                </span>
+                {% else %}
+                <span class="steppy-pct steppy-muted">n/a</span>
+                <span class="steppy-muted">nothing declared — configure <code>coverage.apis</code> and run <code>steppy coverage refresh</code></span>
+                {% endif %}
+            </div>
+            <p class="steppy-small"><a href="coverage.html">Full gap report</a></p>
+        </section>
+        {% endif %}
+
+        {% if report.artifacts.by_kind %}
+        <section class="steppy-report-section">
+            <h2>Artifacts in this run</h2>
+            <p class="steppy-small steppy-muted">
+                What the run produced, by kind. Traces and videos are listed rather than copied
+                here — a Playwright trace needs <code>playwright show-trace</code> to open, so a
+                link would be a dead end.
+            </p>
+            <div class="steppy-scroll">
+                <table class="steppy-report-table">
+                    <thead><tr><th>Kind</th><th>Files</th><th>Size</th></tr></thead>
+                    <tbody>
+                        {% for kind, group in report.artifacts.by_kind.items() %}
+                        <tr><td>{{ kind }}</td><td>{{ group.count }}</td><td>{{ group.bytes | filesize }}</td></tr>
+                        {% endfor %}
+                    </tbody>
+                </table>
+            </div>
+        </section>
+        {% endif %}
+
+        {% if report.warnings or report.coverage.warnings %}
+        <section class="steppy-report-section">
+            <h2>Warnings</h2>
+            <ul class="steppy-small">
+                {% for warning in report.warnings %}<li>{{ warning }}</li>{% endfor %}
+                {% for warning in report.coverage.warnings %}<li>{{ warning }}</li>{% endfor %}
+            </ul>
+        </section>
+        {% endif %}
+
+    </main>
+
+    <footer class="steppy-report-footer">
+        <p>
+            Generated by Steppy {{ report.generated_by }} from {{ report.source.kind }}
+            <code>{{ report.source.label }}</code>.
+            Machine-readable: <a href="report.json">report.json</a>{% if report.coverage.tier != 'none' %},
+            <a href="badge.json">badge.json</a>{% endif %}.
+        </p>
+        <p>
+            This page is marked <code>noindex</code>. It is a run report, not documentation —
+            and a published Pages site means published screenshots.
+        </p>
+    </footer>
+</body>
+</html>