executable-stories-formatters 1.4.0 → 1.6.0

package/templates/astro-thin/astro.config.mjs

@@ -17,28 +17,12 @@ export default defineConfig({
   // Set this to your deployed URL to enable canonical links + the sitemap
   // Starlight ships (otherwise `astro build` prints a harmless sitemap notice).
   // site: 'https://docs.example.com',
-  vite: {
-    // The Stories page is a `client:load` React island. Pre-bundle React and the
-    // report component subtree in ONE optimize pass at startup so Astro's dev
-    // server never re-optimizes them mid-render when the island first hydrates.
-    // That mid-render re-optimize otherwise drops `react-dom/client`'s
-    // `createRoot` export and 504s the page ("Outdated Optimize Dep"), leaving
-    // the island unhydrated and the page rendered as unstyled SSR fallback.
-    // If you add your OWN React islands, add their heavy deps to `include` too.
-    optimizeDeps: {
-      include: [
-        'react',
-        'react-dom',
-        'react-dom/client',
-        'react/jsx-runtime',
-        'executable-stories-react',
-        'executable-stories-react/interactive',
-      ],
-      noDiscovery: true,
-    },
-    // Keep a single React copy so hooks/context work across the island boundary.
-    resolve: { dedupe: ['react', 'react-dom'] },
-  },
+
+  // No vite tuning needed here: the integration pre-bundles React + the report
+  // components (optimizeDeps) and dedupes React itself, so fixes ship with
+  // `pnpm update executable-stories-astro`. If you add your OWN React islands,
+  // list their heavy deps in a `vite.optimizeDeps.include` of your own — it
+  // merges with the integration's list.
   integrations: [
     // React renderer for the report islands — must come before executableStories.
     react(),

package/templates/astro-thin/executable-stories.config.mjs

@@ -32,6 +32,25 @@ export default defineExecutableStories({
   //   { name: 'api', label: 'API',     source: '../apps/api/reports/raw-run.json' },
   // ],
 
+  // Audience lenses (optional): each view mounts a filtered, re-grouped index
+  // at its own URL — same tests, a different lens per audience. Tag scenarios
+  // in your tests (e.g. tags: ['audience:stakeholder']) and filter on them:
+  // views: [
+  //   { base: '/for/product', include: { tags: ['audience:stakeholder'] }, groupBy: 'tag' },
+  //   { base: '/for/design',  include: { tags: ['storyboard'] } },
+  //   { base: '/for/support', include: { tags: ['support'] } },
+  // ],
+
+  // Journeys are on by default at /journeys: tag scenarios with
+  // `journey:<id>:<order>` (e.g. tags: ['journey:guest-checkout:1']) and each
+  // id becomes an ordered multi-scenario walkthrough page.
+  // journeysBase: '/journeys',
+
+  // The UI-state catalog is on by default at /states: tag scenarios with
+  // `state:<name>` (plus optional `viewport:mobile` / `viewport:desktop`) and
+  // they appear as a thumbnail grid, viewport variants side by side.
+  // statesBase: '/states',
+
   // Theme the story pages (optional). `preset` picks a built-in palette
   // ('default' | 'terminal' | 'minimal' | 'vibrant'); `accent` is a shorthand;
   // `tokens` overrides any individual token (accent, pass, fail, warn, fg,
@@ -44,4 +63,9 @@ export default defineExecutableStories({
   // Starlight, and falls back to standalone pages otherwise. Force it with
   // 'starlight' or 'standalone' if you embed the integration in your own site.
   // shell: 'auto',
+
+  // Agent-readable endpoints (on by default): /llms.txt indexes every scenario
+  // and each story page gets a plain-Markdown twin at /stories/<slug>.md, so
+  // the deployed site is consumable by agents/curl, not just browsers.
+  // agentEndpoints: true,
 });

package/templates/astro-thin/reports/sample-run.json

@@ -1,5 +1,6 @@
 {
-  "schemaVersion": "1.0",
+  "$schema": "https://executable-stories.dev/schemas/raw-run.schema.json",
+  "schemaVersion": 1,
   "projectRoot": "/sample",
   "startedAtMs": 0,
   "finishedAtMs": 1234,
@@ -13,12 +14,26 @@
       "durationMs": 41,
       "story": {
         "scenario": "A returning customer checks out with a saved card",
-        "tags": ["checkout", "payments"],
-        "covers": ["src/checkout/**"],
+        "tags": [
+          "checkout",
+          "payments"
+        ],
+        "covers": [
+          "src/checkout/**"
+        ],
         "steps": [
-          { "keyword": "Given", "text": "a signed-in customer with a saved card" },
-          { "keyword": "And", "text": "a basket worth £42.00" },
-          { "keyword": "When", "text": "they confirm the order" },
+          {
+            "keyword": "Given",
+            "text": "a signed-in customer with a saved card"
+          },
+          {
+            "keyword": "And",
+            "text": "a basket worth \u00a342.00"
+          },
+          {
+            "keyword": "When",
+            "text": "they confirm the order"
+          },
           {
             "keyword": "Then",
             "text": "the payment is captured and an order id is returned",
@@ -27,8 +42,24 @@
                 "kind": "table",
                 "phase": "runtime",
                 "label": "Captured payment",
-                "columns": ["Field", "Value"],
-                "rows": [["amount", "£42.00"], ["status", "captured"], ["order", "ord_1A2B"]]
+                "columns": [
+                  "Field",
+                  "Value"
+                ],
+                "rows": [
+                  [
+                    "amount",
+                    "\u00a342.00"
+                  ],
+                  [
+                    "status",
+                    "captured"
+                  ],
+                  [
+                    "order",
+                    "ord_1A2B"
+                  ]
+                ]
               }
             ]
           }
@@ -48,16 +79,35 @@
       "sourceLine": 34,
       "status": "fail",
       "durationMs": 28,
-      "error": { "message": "Expected order to be created, but payment was declined (card_declined)" },
+      "error": {
+        "message": "Expected order to be created, but payment was declined (card_declined)"
+      },
       "story": {
         "scenario": "Checkout is blocked when the card is declined",
-        "tags": ["checkout", "payments"],
-        "covers": ["src/checkout/**"],
+        "tags": [
+          "checkout",
+          "payments"
+        ],
+        "covers": [
+          "src/checkout/**"
+        ],
         "steps": [
-          { "keyword": "Given", "text": "a customer whose card will be declined" },
-          { "keyword": "When", "text": "they confirm the order" },
-          { "keyword": "Then", "text": "they see a clear decline message" },
-          { "keyword": "But", "text": "no order is created" }
+          {
+            "keyword": "Given",
+            "text": "a customer whose card will be declined"
+          },
+          {
+            "keyword": "When",
+            "text": "they confirm the order"
+          },
+          {
+            "keyword": "Then",
+            "text": "they see a clear decline message"
+          },
+          {
+            "keyword": "But",
+            "text": "no order is created"
+          }
         ]
       }
     },
@@ -69,10 +119,18 @@
       "durationMs": 0,
       "story": {
         "scenario": "Gift wrapping is offered above the free-wrap threshold",
-        "tags": ["checkout"],
+        "tags": [
+          "checkout"
+        ],
         "steps": [
-          { "keyword": "Given", "text": "a basket above the free-wrap threshold" },
-          { "keyword": "Then", "text": "free gift wrapping is offered" }
+          {
+            "keyword": "Given",
+            "text": "a basket above the free-wrap threshold"
+          },
+          {
+            "keyword": "Then",
+            "text": "free gift wrapping is offered"
+          }
         ]
       }
     },
@@ -84,11 +142,21 @@
       "durationMs": 17,
       "story": {
         "scenario": "Search ranks exact title matches first",
-        "tags": ["search"],
-        "covers": ["src/search/**"],
+        "tags": [
+          "search"
+        ],
+        "covers": [
+          "src/search/**"
+        ],
         "steps": [
-          { "keyword": "Given", "text": "products titled 'Wireless Mouse' and 'Mouse Pad'" },
-          { "keyword": "When", "text": "the shopper searches for 'mouse'" },
+          {
+            "keyword": "Given",
+            "text": "products titled 'Wireless Mouse' and 'Mouse Pad'"
+          },
+          {
+            "keyword": "When",
+            "text": "the shopper searches for 'mouse'"
+          },
           {
             "keyword": "Then",
             "text": "the exact title match is ranked first",
@@ -120,12 +188,25 @@
       "durationMs": 23,
       "story": {
         "scenario": "Search tolerates a single typo",
-        "tags": ["search"],
-        "covers": ["src/search/**"],
+        "tags": [
+          "search"
+        ],
+        "covers": [
+          "src/search/**"
+        ],
         "steps": [
-          { "keyword": "Given", "text": "a product titled 'Keyboard'" },
-          { "keyword": "When", "text": "the shopper searches for 'keybord'" },
-          { "keyword": "Then", "text": "the product is still found" }
+          {
+            "keyword": "Given",
+            "text": "a product titled 'Keyboard'"
+          },
+          {
+            "keyword": "When",
+            "text": "the shopper searches for 'keybord'"
+          },
+          {
+            "keyword": "Then",
+            "text": "the product is still found"
+          }
         ]
       }
     }

package/templates/astro-thin/src/content/docs/guides/writing-docs.mdx

@@ -5,3 +5,54 @@ title: Writing docs
 Add your own `.mdx` files under `src/content/docs/` — they appear in the sidebar
 alongside the generated Stories. The generated pages are derived from tests and
 are never written to disk, so you can't accidentally edit them into a lie.
+
+## Embed live scenarios in your own pages
+
+Your hand-written pages can pull scenarios in as live evidence — rendered from
+the latest test run, so the embedded card can never drift from reality:
+
+```mdx
+---
+title: Discount policy
+---
+import StoryScenario from 'executable-stories-astro/components/StoryScenario.astro';
+import StoryStatus from 'executable-stories-astro/components/StoryStatus.astro';
+
+We cap discounts at 30% — enforced end-to-end
+(currently <StoryStatus id="checkout--caps-the-discount-at-30-percent" />):
+
+<StoryScenario id="checkout--caps-the-discount-at-30-percent" />
+```
+
+- `<StoryScenario id="…" />` embeds the full scenario card — steps, status,
+  failure output, and any docs the test attached.
+- `<StoryStatus id="…" />` is an inline status pill linked to the story page,
+  for referencing evidence mid-sentence.
+- `id` accepts the stable scenario id (copy it from the **Explorer** page), the
+  URL slug, or the exact title. An id that no longer matches renders a visible
+  callout — embedded evidence never silently disappears.
+
+## Prove a page is still true
+
+Declare which stories verify a page in its frontmatter and render a live badge:
+
+```mdx
+---
+title: ADR 0007 — cap discount at 30%
+verifiedBy: [checkout--caps-the-discount-at-30-percent]
+---
+import VerifiedBy from 'executable-stories-astro/components/VerifiedBy.astro';
+
+<VerifiedBy refs={frontmatter.verifiedBy} />
+```
+
+## For agents and tooling
+
+The site also publishes machine-readable twins (on by default):
+
+- `/llms.txt` — an index of every scenario with links to its Markdown form.
+- `/stories/<slug>.md` — a plain-Markdown twin of each story page.
+
+Point an agent at your deployed site's `/llms.txt` and it can read every
+scenario without an HTML parser. Disable with `agentEndpoints: false` in
+`executable-stories.config.mjs`.

package/templates/astro-thin/src/content/docs/index.mdx

@@ -35,6 +35,13 @@ the matching page change.
 - **Trajectory** — pins a baseline when the dev server starts and shows what
   changed *since you started this session* (e.g. "+2 passing, 1 regressed") — the
   signal to watch while iterating in an agent loop.
+- **[/llms.txt](/llms.txt)** — a machine-readable index of every scenario; each
+  story page also has a plain-Markdown twin at `/stories/<slug>.md`, so agents
+  can read the published site without an HTML parser.
+
+Your own pages can embed scenarios as live evidence too — see
+**[Writing docs](/guides/writing-docs/)** for `<StoryScenario/>` and
+`<StoryStatus/>`.
 
 ## Wiring (one-time)