npm - yaml-flow - Versions diffs - 3.1.1 → 5.0.0 - Mend

yaml-flow 3.1.1 → 5.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (194) hide show

package/examples/index.html ADDED Viewed

@@ -0,0 +1,799 @@
+            <div class="command"><code>node step-machine-cli.js &lt;flow.yaml&gt; [--initial-data &lt;json&gt;]</code><button class="copy-btn" data-copy="node step-machine-cli.js <flow.yaml>">Copy</button></div>
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>yaml-flow Examples Catalog</title>
+  <style>
+    :root {
+      --bg: #f4f7fb;
+      --card: #ffffff;
+      --ink: #122036;
+      --muted: #51607a;
+      --line: #d9e1ef;
+      --accent: #0f6bff;
+      --accent-soft: #e8f0ff;
+      --success-soft: #e9fbf2;
+      --warm-soft: #fff6e7;
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      font-family: "Segoe UI", Tahoma, sans-serif;
+      color: var(--ink);
+      background:
+        radial-gradient(circle at 10% 10%, #e8f2ff 0, transparent 30%),
+        radial-gradient(circle at 90% 0%, #e4fff6 0, transparent 28%),
+        var(--bg);
+    }
+    a { color: var(--accent); text-decoration: none; }
+    a:hover { text-decoration: underline; }
+    .wrap {
+      max-width: 1240px;
+      margin: 24px auto;
+      padding: 0 16px 32px;
+    }
+    .hero {
+      background: linear-gradient(120deg, #083a7a, #0f6bff 60%, #18a4ff);
+      color: #fff;
+      border-radius: 14px;
+      padding: 22px;
+      box-shadow: 0 10px 24px rgba(15, 107, 255, 0.22);
+    }
+    .hero h1 {
+      margin: 0 0 8px;
+      font-size: 1.7rem;
+    }
+    .hero p {
+      margin: 0;
+      opacity: 0.95;
+      max-width: 980px;
+      line-height: 1.55;
+    }
+    .hero a {
+      color: #fff;
+      font-weight: 700;
+    }
+    .panel,
+    .section,
+    .howto,
+    details.catalog {
+      margin-top: 16px;
+      background: var(--card);
+      border: 1px solid var(--line);
+      border-radius: 12px;
+      overflow: hidden;
+    }
+    .panel-body,
+    .section-body,
+    .howto-body,
+    .catalog-body {
+      padding: 14px;
+    }
+    .section-head,
+    .howto-head,
+    .catalog summary {
+      padding: 12px 14px;
+      background: #f7faff;
+      border-bottom: 1px solid var(--line);
+    }
+    .section-head h2,
+    .howto-head h2,
+    .catalog summary {
+      margin: 0;
+      font-size: 1rem;
+    }
+    .section-head p,
+    .howto-head p {
+      margin: 6px 0 0;
+      color: var(--muted);
+      font-size: 13px;
+    }
+    .catalog summary {
+      cursor: pointer;
+      font-weight: 700;
+      list-style: none;
+    }
+    .catalog summary::-webkit-details-marker { display: none; }
+    .tools {
+      display: grid;
+      grid-template-columns: 2fr 1fr 1fr;
+      gap: 10px;
+    }
+    input,
+    select {
+      width: 100%;
+      padding: 10px 12px;
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      font-size: 14px;
+      background: #fff;
+    }
+    .subtle {
+      margin: 0 0 12px;
+      color: var(--muted);
+      font-size: 13px;
+      line-height: 1.5;
+    }
+    .quickstart-grid,
+    .example-grid,
+    .howto-grid {
+      display: grid;
+      gap: 12px;
+    }
+    .quickstart-grid {
+      grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
+    }
+    .quickstart-grid .card {
+      border: 2px solid #bfd6ff;
+      background: linear-gradient(180deg, #ffffff 0%, #f3f8ff 100%);
+      box-shadow: 0 10px 24px rgba(15, 107, 255, 0.08);
+    }
+    .quickstart-grid .card h3 {
+      font-size: 1.05rem;
+    }
+    .quickstart-grid .command code {
+      background: #eaf2ff;
+      border-color: #cfe0ff;
+    }
+    .example-grid {
+      grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+    }
+    .howto-grid {
+      grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
+    }
+    .card,
+    .example-card,
+    .howto-card {
+      border: 1px solid var(--line);
+      border-radius: 12px;
+      padding: 14px;
+      background: #fff;
+      min-height: 100%;
+    }
+    .card { background: linear-gradient(180deg, #ffffff, #fbfdff); }
+    .example-card h3,
+    .howto-card h3,
+    .card h3 {
+      margin: 8px 0 6px;
+      font-size: 1rem;
+    }
+    .example-card p,
+    .howto-card p,
+    .card p {
+      margin: 0;
+      color: var(--muted);
+      font-size: 13px;
+      line-height: 1.5;
+    }
+    .chip-row {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 6px;
+      margin-bottom: 8px;
+    }
+    .chip {
+      display: inline-block;
+      border-radius: 999px;
+      padding: 3px 9px;
+      font-size: 11px;
+      border: 1px solid #cfe0ff;
+      background: var(--accent-soft);
+      color: #1e4c99;
+    }
+    .chip.starter {
+      background: var(--success-soft);
+      border-color: #c7edd8;
+      color: #13683a;
+    }
+    .quickstart-grid .chip.starter {
+      background: #dff6e8;
+      border-color: #bde7cb;
+      color: #0f6a36;
+      font-weight: 700;
+    }
+    .chip.advanced {
+      background: var(--warm-soft);
+      border-color: #ffe3af;
+      color: #8a5c00;
+    }
+    .command {
+      margin-top: 12px;
+      display: flex;
+      align-items: center;
+      gap: 8px;
+      flex-wrap: wrap;
+    }
+    code {
+      background: #f3f7ff;
+      border: 1px solid #dde8ff;
+      border-radius: 6px;
+      padding: 1px 5px;
+      font-family: Consolas, monospace;
+      font-size: 12px;
+    }
+    .command code {
+      display: inline-block;
+      padding: 6px 8px;
+      max-width: 100%;
+      word-break: break-word;
+    }
+    .copy-btn {
+      border: 1px solid #cdd8ef;
+      background: #fff;
+      border-radius: 6px;
+      padding: 5px 8px;
+      font-size: 11px;
+      cursor: pointer;
+    }
+    .copy-btn:hover {
+      border-color: var(--accent);
+      color: var(--accent);
+    }
+    .meta-links {
+      margin-top: 10px;
+      font-size: 13px;
+      color: var(--muted);
+    }
+    .hidden { display: none !important; }
+    .table-wrap {
+      overflow-x: auto;
+    }
+    table {
+      width: 100%;
+      border-collapse: collapse;
+      min-width: 920px;
+    }
+    th,
+    td {
+      text-align: left;
+      vertical-align: top;
+      padding: 10px;
+      border-bottom: 1px solid var(--line);
+      font-size: 13px;
+      line-height: 1.45;
+    }
+    th {
+      background: #fcfdff;
+      position: sticky;
+      top: 0;
+      z-index: 1;
+    }
+    @media (max-width: 980px) {
+      .tools { grid-template-columns: 1fr; }
+    }
+  </style>
+</head>
+<body>
+  <div class="wrap">
+    <section class="hero">
+      <h1>yaml-flow Examples Catalog</h1>
+      <p>Discovery-first guide to runnable yaml-flow examples across browser demos, CLI-driven workflows, and npm library surfaces. Start with a small number of recommended examples, then drill into the full catalog only if you need the exhaustive inventory. See <a href="../docs/index.html">docs</a> for architecture and reference material.</p>
+    </section>
+    <section class="panel">
+      <div class="panel-body">
+        <p class="subtle">Use search and filters across the example cards and the full catalog. Supporting docs: <a href="../docs/index.html">Docs index</a>, <a href="../docs/browser-runtime-livecards-boards.html">browser runtime</a>, <a href="../docs/board-live-cards-cli.html">board-live-cards CLI</a>, <a href="../docs/step-machine-cli.html">step-machine CLI</a>.</p>
+        <div class="tools">
+          <input id="search" placeholder="Search by example name, path, command, or what it demonstrates" />
+          <select id="surfaceFilter">
+            <option value="all">All surfaces</option>
+            <option value="browser">Browser</option>
+            <option value="cli">CLI</option>
+            <option value="npm-lib">npm library</option>
+          </select>
+          <select id="modelFilter">
+            <option value="all">All models</option>
+            <option value="livecards">LiveCards / Boards</option>
+            <option value="step-machine">Step Machine</option>
+            <option value="event-graph">Event Graph</option>
+            <option value="reactive">Reactive / Continuous Event Graph</option>
+            <option value="inference">Inference</option>
+            <option value="graph-of-graphs">Graph-of-Graphs</option>
+            <option value="batch">Batch / Scenario</option>
+          </select>
+        </div>
+      </div>
+    </section>
+    <section class="section" data-role="examples">
+      <div class="section-head">
+        <h2>Start Here</h2>
+        <p>Recommended first stops depending on what you want to understand quickly.</p>
+      </div>
+      <div class="section-body">
+        <div class="quickstart-grid">
+          <article class="card example-card" data-surface="browser" data-model="livecards" data-search="livecards example board demo shell board canvas interactive renderer open example-board/demo-shell.html">
+            <div class="chip-row">
+              <span class="chip">Browser</span>
+              <span class="chip">LiveCards</span>
+              <span class="chip starter">Starter</span>
+            </div>
+            <h3><a href="example-board/demo-shell.html">LiveCards example board demo</a></h3>
+            <p>Fastest way to see the maintained LiveCards browser renderer, board/canvas views, refresh flows, and JSONata-backed example cards in one place.</p>
+            <div class="command"><code>Open example-board/demo-shell.html</code><button class="copy-btn" data-copy="example-board/demo-shell.html">Copy path</button></div>
+          </article>
+          <article class="card example-card" data-surface="browser" data-model="step-machine" data-search="step machine browser demo flowengine open browser/step-machine-browser/index.html">
+            <div class="chip-row">
+              <span class="chip">Browser</span>
+              <span class="chip">Step Machine</span>
+              <span class="chip starter">Starter</span>
+            </div>
+            <h3><a href="browser/step-machine-browser/index.html">Step Machine Browser Demo</a></h3>
+            <p>Fastest way to understand the basic step-machine mental model directly in the browser.</p>
+            <div class="command"><code>Open browser/step-machine-browser/index.html</code><button class="copy-btn" data-copy="browser/step-machine-browser/index.html">Copy path</button></div>
+          </article>
+          <article class="card example-card" data-surface="npm-lib" data-model="step-machine" data-search="simple greeting createEngine loadFlow FileStore npx tsx examples/npm-libs/node/simple-greeting.ts">
+            <div class="chip-row">
+              <span class="chip">npm library</span>
+              <span class="chip">Step Machine</span>
+              <span class="chip starter">Starter</span>
+            </div>
+            <h3>Simple Greeting</h3>
+            <p>Best first TypeScript example for understanding the core step-machine APIs outside the browser demos.</p>
+            <div class="command"><code>npx tsx examples/npm-libs/node/simple-greeting.ts</code><button class="copy-btn" data-copy="npx tsx examples/npm-libs/node/simple-greeting.ts">Copy</button></div>
+          </article>
+          <article class="card example-card" data-surface="npm-lib" data-model="reactive" data-search="reactive pipeline self-driving graph createReactiveGraph npx tsx examples/npm-libs/continuous-event-graph/reactive-pipeline.ts">
+            <div class="chip-row">
+              <span class="chip">npm library</span>
+              <span class="chip">Reactive Graph</span>
+              <span class="chip starter">Starter</span>
+            </div>
+            <h3>Reactive Pipeline</h3>
+            <p>Best first example for push-driven orchestration and automatic downstream execution in the reactive runtime.</p>
+            <div class="command"><code>npx tsx examples/npm-libs/continuous-event-graph/reactive-pipeline.ts</code><button class="copy-btn" data-copy="npx tsx examples/npm-libs/continuous-event-graph/reactive-pipeline.ts">Copy</button></div>
+          </article>
+        </div>
+      </div>
+    </section>
+    <section class="howto">
+      <div class="howto-head">
+        <h2>Execution Shortcuts</h2>
+        <p>Keep this page lightweight. Only the essential execution entrypoints are listed here; deeper operational detail lives in the linked docs.</p>
+      </div>
+      <div class="howto-body">
+        <div class="howto-grid">
+          <article class="howto-card">
+            <h3>TypeScript examples</h3>
+            <p>Most library examples under <code>examples/npm-libs</code> use the same runner.</p>
+            <div class="command"><code>npx tsx &lt;example-file.ts&gt;</code><button class="copy-btn" data-copy="npx tsx <example-file.ts>">Copy</button></div>
+          </article>
+          <article class="howto-card">
+            <h3>JavaScript scripts</h3>
+            <p>Used for browser-support scripts and example wrappers.</p>
+            <div class="command"><code>node &lt;example-file.js&gt;</code><button class="copy-btn" data-copy="node <example-file.js>">Copy</button></div>
+          </article>
+          <article class="howto-card">
+            <h3>step-machine CLI</h3>
+            <p>Use the root CLI when you want YAML-driven flow execution rather than embedding the library APIs.</p>
+            <div class="command"><code>node step-machine-cli.js &lt;flow.yaml&gt; [--initial-data &lt;json&gt;]</code><button class="copy-btn" data-copy="node step-machine-cli.js <flow.yaml>">Copy</button></div>
+            <div class="meta-links"><a href="../docs/step-machine-cli.html">CLI reference</a></div>
+          </article>
+          <article class="howto-card">
+            <h3>board-live-cards CLI</h3>
+            <p>Use the board runtime CLI for orchestration, status, retriggering, and source lifecycle operations.</p>
+            <div class="command"><code>node board-live-cards-cli.js &lt;command&gt;</code><button class="copy-btn" data-copy="node board-live-cards-cli.js help">Copy</button></div>
+            <div class="meta-links"><a href="../docs/board-live-cards-cli.html">CLI reference</a></div>
+          </article>
+        </div>
+      </div>
+    </section>
+    <section class="section" data-role="examples">
+      <div class="section-head">
+        <h2>Browser Demos</h2>
+        <p>Open these directly in the browser to understand the client-side runtime and visual behavior.</p>
+      </div>
+      <div class="section-body">
+        <div class="example-grid">
+          <article class="example-card" data-surface="browser" data-model="livecards" data-search="livecards example board demo shell interactive board canvas showcase">
+            <div class="chip-row"><span class="chip">Browser</span><span class="chip">LiveCards</span></div>
+            <h3><a href="example-board/demo-shell.html">LiveCards Example Board Demo</a></h3>
+            <p>Interactive example-board shell for the browser runtime, including board/canvas views, refresh flows, and compute-backed example cards.</p>
+            <div class="command"><code>Open example-board/demo-shell.html</code><button class="copy-btn" data-copy="example-board/demo-shell.html">Copy path</button></div>
+          </article>
+          <article class="example-card" data-surface="browser" data-model="step-machine" data-search="step machine browser greeting demo flowengine inlined">
+            <div class="chip-row"><span class="chip">Browser</span><span class="chip">Step Machine</span></div>
+            <h3><a href="browser/step-machine-browser/index.html">Step Machine Browser Demo</a></h3>
+            <p>Simple greeting flow rendered entirely in the browser using an inlined FlowEngine-style implementation.</p>
+            <div class="command"><code>Open browser/step-machine-browser/index.html</code><button class="copy-btn" data-copy="browser/step-machine-browser/index.html">Copy path</button></div>
+          </article>
+          <article class="example-card" data-surface="browser" data-model="livecards" data-search="portfolio tracker browser boards portfolio-tracker node javascript board-live-cards cli">
+            <div class="chip-row"><span class="chip">Browser support</span><span class="chip">LiveCards</span><span class="chip advanced">Advanced</span></div>
+            <h3>Portfolio Tracker Board Driver</h3>
+            <p>Node-driven portfolio tracker demo that exercises end-to-end board-live-cards orchestration for a browser-facing board workflow.</p>
+            <div class="command"><code>node examples/browser/boards/portfolio-tracker/portfolio-tracker.js</code><button class="copy-btn" data-copy="node examples/browser/boards/portfolio-tracker/portfolio-tracker.js">Copy</button></div>
+          </article>
+          <article class="example-card" data-surface="browser" data-model="livecards" data-search="portfolio tracker task-executor external source cli delegation custom">
+            <div class="chip-row"><span class="chip">Browser support</span><span class="chip">LiveCards</span><span class="chip">Task-Executor</span></div>
+            <h3>Portfolio Tracker with Task-Executor</h3>
+            <p>Portfolio tracker with external source execution via task-executor. Demonstrates delegating source.cli execution to a custom executor script.</p>
+            <div class="command"><code>node examples/browser/boards/portfolio-tracker/portfolio-tracker.js --task-executor "node C:\path\to\portfolio-tracker-task-executor.cjs"</code><button class="copy-btn" data-copy="node examples/browser/boards/portfolio-tracker/portfolio-tracker.js --task-executor &quot;node C:\path\to\portfolio-tracker-task-executor.cjs&quot;">Copy</button></div>
+          </article>
+        </div>
+      </div>
+    </section>
+    <section class="section" data-role="examples">
+      <div class="section-head">
+        <h2>CLI Workflows</h2>
+        <p>Use these when you want orchestration behavior driven by YAML flows, CLI handlers, or reusable scenario inputs.</p>
+      </div>
+      <div class="section-body">
+        <div class="example-grid">
+          <article class="example-card" data-surface="cli" data-model="step-machine" data-search="portfolio tracker flow yaml step-machine cli run-portfolio-tracker.bat failure transitions jsonata">
+            <div class="chip-row"><span class="chip">CLI</span><span class="chip">Step Machine</span></div>
+            <h3>Portfolio Tracker Flow</h3>
+            <p>YAML-driven step-machine workflow with JSONata transforms, handler variables, and explicit failure transitions.</p>
+            <div class="command"><code>run-portfolio-tracker.bat</code><button class="copy-btn" data-copy="run-portfolio-tracker.bat">Copy</button></div>
+          </article>
+          <article class="example-card" data-surface="cli" data-model="step-machine" data-search="portfolio tracker baseline direct step-machine cli initial-data">
+            <div class="chip-row"><span class="chip">CLI</span><span class="chip">Step Machine</span></div>
+            <h3>Portfolio Tracker: Baseline Direct</h3>
+            <p>Runs the portfolio tracker flow directly through step-machine-cli with the baseline input payload inline.</p>
+            <div class="command"><code>node step-machine-cli.js examples/cli/step-machine-cli/portfolio-tracker/portfolio-tracker.flow.yaml --initial-data '{...baseline...}'</code><button class="copy-btn" data-copy="node step-machine-cli.js examples/cli/step-machine-cli/portfolio-tracker/portfolio-tracker.flow.yaml --initial-data '{&quot;runtime_root&quot;:&quot;./runtime&quot;,&quot;board_name&quot;:&quot;portfolio-tracker-board&quot;,&quot;cards_template_dir&quot;:&quot;./cards&quot;,&quot;completion_tasks&quot;:[&quot;portfolio-form&quot;,&quot;price-fetch&quot;,&quot;holdings-table&quot;,&quot;portfolio-value&quot;],&quot;price_fetch_task&quot;:&quot;price-fetch&quot;,&quot;prices_t1&quot;:{&quot;AAPL&quot;:198.5,&quot;MSFT&quot;:425.3,&quot;GOOG&quot;:178.9,&quot;AMZN&quot;:192.4,&quot;TSLA&quot;:168.75},&quot;holdings_t2&quot;:[{&quot;symbol&quot;:&quot;AAPL&quot;,&quot;qty&quot;:50},{&quot;symbol&quot;:&quot;MSFT&quot;,&quot;qty&quot;:30},{&quot;symbol&quot;:&quot;GOOG&quot;,&quot;qty&quot;:100}],&quot;prices_t2&quot;:{&quot;AAPL&quot;:198.5,&quot;MSFT&quot;:425.3,&quot;GOOG&quot;:178.9,&quot;AMZN&quot;:192.4,&quot;TSLA&quot;:168.75},&quot;prices_t3&quot;:{&quot;AAPL&quot;:205,&quot;MSFT&quot;:425.3,&quot;GOOG&quot;:178.9,&quot;AMZN&quot;:192.4,&quot;TSLA&quot;:168.75}}'">Copy</button></div>
+          </article>
+          <article class="example-card" data-surface="cli" data-model="step-machine" data-search="portfolio tracker price shock direct step-machine cli initial-data">
+            <div class="chip-row"><span class="chip">CLI</span><span class="chip">Step Machine</span></div>
+            <h3>Portfolio Tracker: Price Shock Direct</h3>
+            <p>Runs the same portfolio flow directly with a shock payload so you can test the alternate market path without a harness layer.</p>
+            <div class="command"><code>node step-machine-cli.js examples/cli/step-machine-cli/portfolio-tracker/portfolio-tracker.flow.yaml --initial-data '{...price-shock...}'</code><button class="copy-btn" data-copy="node step-machine-cli.js examples/cli/step-machine-cli/portfolio-tracker/portfolio-tracker.flow.yaml --initial-data '{&quot;runtime_root&quot;:&quot;./runtime&quot;,&quot;board_name&quot;:&quot;portfolio-tracker-board&quot;,&quot;cards_template_dir&quot;:&quot;./cards&quot;,&quot;completion_tasks&quot;:[&quot;portfolio-form&quot;,&quot;price-fetch&quot;,&quot;holdings-table&quot;,&quot;portfolio-value&quot;],&quot;price_fetch_task&quot;:&quot;price-fetch&quot;,&quot;prices_t1&quot;:{&quot;AAPL&quot;:198.5,&quot;MSFT&quot;:425.3,&quot;GOOG&quot;:178.9,&quot;AMZN&quot;:192.4,&quot;TSLA&quot;:168.75},&quot;holdings_t2&quot;:[{&quot;symbol&quot;:&quot;AAPL&quot;,&quot;qty&quot;:50},{&quot;symbol&quot;:&quot;MSFT&quot;,&quot;qty&quot;:30},{&quot;symbol&quot;:&quot;GOOG&quot;,&quot;qty&quot;:100}],&quot;prices_t2&quot;:{&quot;AAPL&quot;:155,&quot;MSFT&quot;:390,&quot;GOOG&quot;:132,&quot;AMZN&quot;:171,&quot;TSLA&quot;:143},&quot;prices_t3&quot;:{&quot;AAPL&quot;:148,&quot;MSFT&quot;:365,&quot;GOOG&quot;:125,&quot;AMZN&quot;:160,&quot;TSLA&quot;:129}}'">Copy</button></div>
+          </article>
+        </div>
+      </div>
+    </section>
+    <section class="section" data-role="examples">
+      <div class="section-head">
+        <h2>npm Library Examples: Step Machine</h2>
+        <p>Library-level usage for explicit flow control, stateful execution, and conversational loops.</p>
+      </div>
+      <div class="section-body">
+        <div class="example-grid">
+          <article class="example-card" data-surface="npm-lib" data-model="step-machine" data-search="simple greeting step machine file persistence">
+            <div class="chip-row"><span class="chip">npm library</span><span class="chip">Step Machine</span></div>
+            <h3>Simple Greeting</h3>
+            <p>Basic step-machine flow with file persistence. Best first TypeScript example for the core flow APIs.</p>
+            <div class="command"><code>npx tsx examples/npm-libs/node/simple-greeting.ts</code><button class="copy-btn" data-copy="npx tsx examples/npm-libs/node/simple-greeting.ts">Copy</button></div>
+          </article>
+          <article class="example-card" data-surface="npm-lib" data-model="step-machine" data-search="ai conversation retries transition handling memory store">
+            <div class="chip-row"><span class="chip">npm library</span><span class="chip">Step Machine</span></div>
+            <h3>AI Conversation</h3>
+            <p>Conversation loop with retry and transition handling. Good for multi-step conversational control flow.</p>
+            <div class="command"><code>npx tsx examples/npm-libs/node/ai-conversation.ts</code><button class="copy-btn" data-copy="npx tsx examples/npm-libs/node/ai-conversation.ts">Copy</button></div>
+          </article>
+        </div>
+      </div>
+    </section>
+    <section class="section" data-role="examples">
+      <div class="section-head">
+        <h2>npm Library Examples: Inference</h2>
+        <p>Examples where LLM inference complements graph execution rather than replacing it.</p>
+      </div>
+      <div class="section-body">
+        <div class="example-grid">
+          <article class="example-card" data-surface="npm-lib" data-model="inference" data-search="pluggable adapters inference cli adapter http adapter">
+            <div class="chip-row"><span class="chip">npm library</span><span class="chip">Inference</span></div>
+            <h3>Pluggable Adapters</h3>
+            <p>Shows swappable LLM adapters and the inference extension points used for completion detection.</p>
+            <div class="command"><code>npx tsx examples/npm-libs/inference/pluggable-adapters.ts</code><button class="copy-btn" data-copy="npx tsx examples/npm-libs/inference/pluggable-adapters.ts">Copy</button></div>
+          </article>
+          <article class="example-card" data-surface="npm-lib" data-model="inference" data-search="data pipeline iterative evidence accumulation inferAndApply">
+            <div class="chip-row"><span class="chip">npm library</span><span class="chip">Inference</span></div>
+            <h3>Data Pipeline</h3>
+            <p>Demonstrates iterative evidence accumulation and repeated inference rounds over a live graph.</p>
+            <div class="command"><code>npx tsx examples/npm-libs/inference/data-pipeline.ts</code><button class="copy-btn" data-copy="npx tsx examples/npm-libs/inference/data-pipeline.ts">Copy</button></div>
+          </article>
+          <article class="example-card" data-surface="npm-lib" data-model="inference" data-search="copilot cli inference backend github copilot">
+            <div class="chip-row"><span class="chip">npm library</span><span class="chip">Inference</span></div>
+            <h3>Copilot CLI</h3>
+            <p>Uses GitHub Copilot CLI as the inference backend for completion suggestions.</p>
+            <div class="command"><code>npx tsx examples/npm-libs/inference/copilot-cli.ts</code><button class="copy-btn" data-copy="npx tsx examples/npm-libs/inference/copilot-cli.ts">Copy</button></div>
+          </article>
+          <article class="example-card" data-surface="npm-lib" data-model="inference" data-search="azure deployment logs checkpoint inference">
+            <div class="chip-row"><span class="chip">npm library</span><span class="chip">Inference</span></div>
+            <h3>Azure Deployment</h3>
+            <p>Deployment checkpoint inference from logs, showing how evidence becomes completion recommendations.</p>
+            <div class="command"><code>npx tsx examples/npm-libs/inference/azure-deployment.ts</code><button class="copy-btn" data-copy="npx tsx examples/npm-libs/inference/azure-deployment.ts">Copy</button></div>
+          </article>
+        </div>
+      </div>
+    </section>
+    <section class="section" data-role="examples">
+      <div class="section-head">
+        <h2>npm Library Examples: Event Graph</h2>
+        <p>Explicit DAG scheduling and state transitions without the long-lived reactive runtime.</p>
+      </div>
+      <div class="section-body">
+        <div class="example-grid">
+          <article class="example-card" data-surface="npm-lib" data-model="event-graph" data-search="research pipeline fan out fan in manual event graph driver">
+            <div class="chip-row"><span class="chip">npm library</span><span class="chip">Event Graph</span></div>
+            <h3>Research Pipeline</h3>
+            <p>Manual event-graph driver with fan-out and fan-in behavior for multi-branch research tasks.</p>
+            <div class="command"><code>npx tsx examples/npm-libs/event-graph/research-pipeline.ts</code><button class="copy-btn" data-copy="npx tsx examples/npm-libs/event-graph/research-pipeline.ts">Copy</button></div>
+          </article>
+          <article class="example-card" data-surface="npm-lib" data-model="event-graph" data-search="executor pipeline validations next apply createInitialExecutionState">
+            <div class="chip-row"><span class="chip">npm library</span><span class="chip">Event Graph</span></div>
+            <h3>Executor Pipeline</h3>
+            <p>Library-mode execution loop with runtime and static validation layered into the event graph.</p>
+            <div class="command"><code>npx tsx examples/npm-libs/event-graph/executor-pipeline.ts</code><button class="copy-btn" data-copy="npx tsx examples/npm-libs/event-graph/executor-pipeline.ts">Copy</button></div>
+          </article>
+          <article class="example-card" data-surface="npm-lib" data-model="event-graph" data-search="executor diamond parallel branch execution">
+            <div class="chip-row"><span class="chip">npm library</span><span class="chip">Event Graph</span></div>
+            <h3>Executor Diamond</h3>
+            <p>Diamond DAG with parallel branches to show how multiple downstream tasks can become eligible together.</p>
+            <div class="command"><code>npx tsx examples/npm-libs/event-graph/executor-diamond.ts</code><button class="copy-btn" data-copy="npx tsx examples/npm-libs/event-graph/executor-diamond.ts">Copy</button></div>
+          </article>
+          <article class="example-card" data-surface="npm-lib" data-model="event-graph" data-search="ci cd pipeline approval gates retries failure routing">
+            <div class="chip-row"><span class="chip">npm library</span><span class="chip">Event Graph</span></div>
+            <h3>CI/CD Pipeline</h3>
+            <p>Approval gates, retries, and conditional failure routing using the event-graph execution model.</p>
+            <div class="command"><code>npx tsx examples/npm-libs/event-graph/ci-cd-pipeline.ts</code><button class="copy-btn" data-copy="npx tsx examples/npm-libs/event-graph/ci-cd-pipeline.ts">Copy</button></div>
+          </article>
+        </div>
+      </div>
+    </section>
+    <section class="section" data-role="examples">
+      <div class="section-head">
+        <h2>npm Library Examples: Reactive and Continuous Event Graph</h2>
+        <p>Long-lived graphs, automatic downstream execution, runtime mutation, and LiveCards bridge examples.</p>
+      </div>
+      <div class="section-body">
+        <div class="example-grid">
+          <article class="example-card" data-surface="npm-lib" data-model="reactive" data-search="reactive pipeline self-driving etl createReactiveGraph">
+            <div class="chip-row"><span class="chip">npm library</span><span class="chip">Reactive</span></div>
+            <h3>Reactive Pipeline</h3>
+            <p>Self-driving pipeline where one push triggers a complete downstream execution cascade.</p>
+            <div class="command"><code>npx tsx examples/npm-libs/continuous-event-graph/reactive-pipeline.ts</code><button class="copy-btn" data-copy="npx tsx examples/npm-libs/continuous-event-graph/reactive-pipeline.ts">Copy</button></div>
+          </article>
+          <article class="example-card" data-surface="npm-lib" data-model="reactive" data-search="reactive monitoring runtime changes callback handler fire and forget">
+            <div class="chip-row"><span class="chip">npm library</span><span class="chip">Reactive</span></div>
+            <h3>Reactive Monitoring</h3>
+            <p>Continuous monitoring topology with runtime changes, escalation paths, and side-effect handlers.</p>
+            <div class="command"><code>npx tsx examples/npm-libs/continuous-event-graph/reactive-monitoring.ts</code><button class="copy-btn" data-copy="npx tsx examples/npm-libs/continuous-event-graph/reactive-monitoring.ts">Copy</button></div>
+          </article>
+          <article class="example-card" data-surface="npm-lib" data-model="reactive" data-search="stock dashboard dynamic graph mutation snapshot restore lineage queries">
+            <div class="chip-row"><span class="chip">npm library</span><span class="chip">Reactive</span></div>
+            <h3>Stock Dashboard</h3>
+            <p>Runtime graph mutation, snapshots, restore, and lineage queries in a continuous event graph.</p>
+            <div class="command"><code>npx tsx examples/npm-libs/continuous-event-graph/stock-dashboard.ts</code><button class="copy-btn" data-copy="npx tsx examples/npm-libs/continuous-event-graph/stock-dashboard.ts">Copy</button></div>
+          </article>
+          <article class="example-card" data-surface="npm-lib" data-model="reactive" data-search="soc incident board side effect handlers">
+            <div class="chip-row"><span class="chip">npm library</span><span class="chip">Reactive</span></div>
+            <h3>SOC Incident Board</h3>
+            <p>Security-operations workflow with side-effect handlers in the reactive execution model.</p>
+            <div class="command"><code>npx tsx examples/npm-libs/continuous-event-graph/soc-incident-board.ts</code><button class="copy-btn" data-copy="npx tsx examples/npm-libs/continuous-event-graph/soc-incident-board.ts">Copy</button></div>
+          </article>
+          <article class="example-card" data-surface="npm-lib" data-model="reactive" data-search="portfolio tracker external pushes retrigger">
+            <div class="chip-row"><span class="chip">npm library</span><span class="chip">Reactive</span></div>
+            <h3>Portfolio Tracker</h3>
+            <p>Portfolio workflow that mixes external pushes with retrigger behavior.</p>
+            <div class="command"><code>npx tsx examples/npm-libs/continuous-event-graph/portfolio-tracker.ts</code><button class="copy-btn" data-copy="npx tsx examples/npm-libs/continuous-event-graph/portfolio-tracker.ts">Copy</button></div>
+          </article>
+          <article class="example-card" data-surface="npm-lib" data-model="livecards" data-search="live cards board bridge definitions to reactive graph">
+            <div class="chip-row"><span class="chip">npm library</span><span class="chip">LiveCards</span></div>
+            <h3>Live Cards Board</h3>
+            <p>Bridges LiveCards definitions into the reactive graph runtime.</p>
+            <div class="command"><code>npx tsx examples/npm-libs/continuous-event-graph/live-cards-board.ts</code><button class="copy-btn" data-copy="npx tsx examples/npm-libs/continuous-event-graph/live-cards-board.ts">Copy</button></div>
+          </article>
+          <article class="example-card" data-surface="npm-lib" data-model="livecards" data-search="live portfolio dashboard large live card portfolio">
+            <div class="chip-row"><span class="chip">npm library</span><span class="chip">LiveCards</span><span class="chip advanced">Advanced</span></div>
+            <h3>Live Portfolio Dashboard</h3>
+            <p>Large LiveCards portfolio dashboard backed by reactive task handlers.</p>
+            <div class="command"><code>npx tsx examples/npm-libs/continuous-event-graph/live-portfolio-dashboard.ts</code><button class="copy-btn" data-copy="npx tsx examples/npm-libs/continuous-event-graph/live-portfolio-dashboard.ts">Copy</button></div>
+          </article>
+        </div>
+      </div>
+    </section>
+    <section class="section" data-role="examples">
+      <div class="section-head">
+        <h2>npm Library Examples: Graph-of-Graphs and Batch</h2>
+        <p>Nested orchestration and concurrent item processing patterns.</p>
+      </div>
+      <div class="section-body">
+        <div class="example-grid">
+          <article class="example-card" data-surface="npm-lib" data-model="graph-of-graphs" data-search="url processing pipeline outer dag inner dag batched">
+            <div class="chip-row"><span class="chip">npm library</span><span class="chip">Graph-of-Graphs</span></div>
+            <h3>URL Processing Pipeline</h3>
+            <p>Outer DAG orchestrates batched inner DAGs, demonstrating nested orchestration layers.</p>
+            <div class="command"><code>npx tsx examples/npm-libs/graph-of-graphs/url-processing-pipeline.ts</code><button class="copy-btn" data-copy="npx tsx examples/npm-libs/graph-of-graphs/url-processing-pipeline.ts">Copy</button></div>
+          </article>
+          <article class="example-card" data-surface="npm-lib" data-model="graph-of-graphs" data-search="multi stage etl mixed event graph step machine nested">
+            <div class="chip-row"><span class="chip">npm library</span><span class="chip">Graph-of-Graphs</span></div>
+            <h3>Multi-stage ETL</h3>
+            <p>Mixed event-graph plus step-machine nested orchestration for multi-stage ETL.</p>
+            <div class="command"><code>npx tsx examples/npm-libs/graph-of-graphs/multi-stage-etl.ts</code><button class="copy-btn" data-copy="npx tsx examples/npm-libs/graph-of-graphs/multi-stage-etl.ts">Copy</button></div>
+          </article>
+          <article class="example-card" data-surface="npm-lib" data-model="batch" data-search="batch processing per item step machine flow">
+            <div class="chip-row"><span class="chip">npm library</span><span class="chip">Batch</span></div>
+            <h3>Batch Step Machine</h3>
+            <p>Concurrent processing with a per-item step-machine flow.</p>
+            <div class="command"><code>npx tsx examples/npm-libs/batch/batch-step-machine.ts</code><button class="copy-btn" data-copy="npx tsx examples/npm-libs/batch/batch-step-machine.ts">Copy</button></div>
+          </article>
+        </div>
+      </div>
+    </section>
+    <details class="catalog">
+      <summary>Full Catalog</summary>
+      <div class="catalog-body table-wrap">
+        <table>
+          <thead>
+            <tr>
+              <th>Example</th>
+              <th>Surface</th>
+              <th>Model</th>
+              <th>Run / Open</th>
+              <th>Demonstrates</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr data-surface="browser" data-model="livecards"><td><a href="example-board/demo-shell.html"><code>examples/example-board/demo-shell.html</code></a></td><td>Browser</td><td>LiveCards</td><td><code>Open example-board/demo-shell.html</code></td><td>Maintained example-board browser demo for board/canvas rendering and compute-backed cards</td></tr>
+            <tr data-surface="browser" data-model="step-machine"><td><a href="browser/step-machine-browser/index.html"><code>examples/browser/step-machine-browser/index.html</code></a></td><td>Browser</td><td>Step Machine</td><td><code>Open browser/step-machine-browser/index.html</code></td><td>Simple browser-side step-machine demo</td></tr>
+            <tr data-surface="browser" data-model="livecards"><td><code>examples/browser/boards/portfolio-tracker/portfolio-tracker.js</code></td><td>Browser support</td><td>LiveCards</td><td><code>node examples/browser/boards/portfolio-tracker/portfolio-tracker.js</code></td><td>End-to-end board-live-cards portfolio driver</td></tr>
+            <tr data-surface="cli" data-model="step-machine"><td><code>examples/cli/step-machine-cli/portfolio-tracker/run-portfolio-tracker.bat</code></td><td>CLI</td><td>Step Machine</td><td><code>run-portfolio-tracker.bat</code></td><td>Portfolio tracker YAML flow orchestration</td></tr>
+            <tr data-surface="cli" data-model="step-machine"><td><code>examples/cli/step-machine-cli/portfolio-tracker/portfolio-tracker.flow.yaml</code></td><td>CLI</td><td>Step Machine</td><td><code>node step-machine-cli.js examples/cli/step-machine-cli/portfolio-tracker/portfolio-tracker.flow.yaml --initial-data '{...baseline...}'</code></td><td>Direct baseline portfolio tracker invocation</td></tr>
+            <tr data-surface="cli" data-model="step-machine"><td><code>examples/cli/step-machine-cli/portfolio-tracker/portfolio-tracker.flow.yaml</code></td><td>CLI</td><td>Step Machine</td><td><code>node step-machine-cli.js examples/cli/step-machine-cli/portfolio-tracker/portfolio-tracker.flow.yaml --initial-data '{...price-shock...}'</code></td><td>Direct price-shock portfolio tracker invocation</td></tr>
+            <tr data-surface="npm-lib" data-model="step-machine"><td><code>examples/npm-libs/node/simple-greeting.ts</code></td><td>npm library</td><td>Step Machine</td><td><code>npx tsx examples/npm-libs/node/simple-greeting.ts</code></td><td>Basic step-machine flow with file persistence</td></tr>
+            <tr data-surface="npm-lib" data-model="step-machine"><td><code>examples/npm-libs/node/ai-conversation.ts</code></td><td>npm library</td><td>Step Machine</td><td><code>npx tsx examples/npm-libs/node/ai-conversation.ts</code></td><td>Conversation loop with retries</td></tr>
+            <tr data-surface="npm-lib" data-model="inference"><td><code>examples/npm-libs/inference/pluggable-adapters.ts</code></td><td>npm library</td><td>Inference</td><td><code>npx tsx examples/npm-libs/inference/pluggable-adapters.ts</code></td><td>Swappable LLM adapters</td></tr>
+            <tr data-surface="npm-lib" data-model="inference"><td><code>examples/npm-libs/inference/data-pipeline.ts</code></td><td>npm library</td><td>Inference</td><td><code>npx tsx examples/npm-libs/inference/data-pipeline.ts</code></td><td>Iterative evidence accumulation</td></tr>
+            <tr data-surface="npm-lib" data-model="inference"><td><code>examples/npm-libs/inference/copilot-cli.ts</code></td><td>npm library</td><td>Inference</td><td><code>npx tsx examples/npm-libs/inference/copilot-cli.ts</code></td><td>Copilot CLI inference backend</td></tr>
+            <tr data-surface="npm-lib" data-model="inference"><td><code>examples/npm-libs/inference/azure-deployment.ts</code></td><td>npm library</td><td>Inference</td><td><code>npx tsx examples/npm-libs/inference/azure-deployment.ts</code></td><td>Deployment checkpoint inference</td></tr>
+            <tr data-surface="npm-lib" data-model="event-graph"><td><code>examples/npm-libs/event-graph/research-pipeline.ts</code></td><td>npm library</td><td>Event Graph</td><td><code>npx tsx examples/npm-libs/event-graph/research-pipeline.ts</code></td><td>Manual fan-out/fan-in driver</td></tr>
+            <tr data-surface="npm-lib" data-model="event-graph"><td><code>examples/npm-libs/event-graph/executor-pipeline.ts</code></td><td>npm library</td><td>Event Graph</td><td><code>npx tsx examples/npm-libs/event-graph/executor-pipeline.ts</code></td><td>Validated event-graph loop</td></tr>
+            <tr data-surface="npm-lib" data-model="event-graph"><td><code>examples/npm-libs/event-graph/executor-diamond.ts</code></td><td>npm library</td><td>Event Graph</td><td><code>npx tsx examples/npm-libs/event-graph/executor-diamond.ts</code></td><td>Diamond DAG execution</td></tr>
+            <tr data-surface="npm-lib" data-model="event-graph"><td><code>examples/npm-libs/event-graph/ci-cd-pipeline.ts</code></td><td>npm library</td><td>Event Graph</td><td><code>npx tsx examples/npm-libs/event-graph/ci-cd-pipeline.ts</code></td><td>Approval gates and failure routing</td></tr>
+            <tr data-surface="npm-lib" data-model="reactive"><td><code>examples/npm-libs/continuous-event-graph/reactive-pipeline.ts</code></td><td>npm library</td><td>Reactive</td><td><code>npx tsx examples/npm-libs/continuous-event-graph/reactive-pipeline.ts</code></td><td>Self-driving reactive pipeline</td></tr>
+            <tr data-surface="npm-lib" data-model="reactive"><td><code>examples/npm-libs/continuous-event-graph/reactive-monitoring.ts</code></td><td>npm library</td><td>Reactive</td><td><code>npx tsx examples/npm-libs/continuous-event-graph/reactive-monitoring.ts</code></td><td>Continuous monitoring with runtime changes</td></tr>
+            <tr data-surface="npm-lib" data-model="reactive"><td><code>examples/npm-libs/continuous-event-graph/stock-dashboard.ts</code></td><td>npm library</td><td>Reactive</td><td><code>npx tsx examples/npm-libs/continuous-event-graph/stock-dashboard.ts</code></td><td>Mutation, snapshots, lineage</td></tr>
+            <tr data-surface="npm-lib" data-model="reactive"><td><code>examples/npm-libs/continuous-event-graph/soc-incident-board.ts</code></td><td>npm library</td><td>Reactive</td><td><code>npx tsx examples/npm-libs/continuous-event-graph/soc-incident-board.ts</code></td><td>SOC workflow with side effects</td></tr>
+            <tr data-surface="npm-lib" data-model="reactive"><td><code>examples/npm-libs/continuous-event-graph/portfolio-tracker.ts</code></td><td>npm library</td><td>Reactive</td><td><code>npx tsx examples/npm-libs/continuous-event-graph/portfolio-tracker.ts</code></td><td>Portfolio workflow with external pushes</td></tr>
+            <tr data-surface="npm-lib" data-model="livecards"><td><code>examples/npm-libs/continuous-event-graph/live-cards-board.ts</code></td><td>npm library</td><td>LiveCards</td><td><code>npx tsx examples/npm-libs/continuous-event-graph/live-cards-board.ts</code></td><td>LiveCards definitions bridged to reactive graph</td></tr>
+            <tr data-surface="npm-lib" data-model="livecards"><td><code>examples/npm-libs/continuous-event-graph/live-portfolio-dashboard.ts</code></td><td>npm library</td><td>LiveCards</td><td><code>npx tsx examples/npm-libs/continuous-event-graph/live-portfolio-dashboard.ts</code></td><td>Large live-card portfolio dashboard</td></tr>
+            <tr data-surface="npm-lib" data-model="graph-of-graphs"><td><code>examples/npm-libs/graph-of-graphs/url-processing-pipeline.ts</code></td><td>npm library</td><td>Graph-of-Graphs</td><td><code>npx tsx examples/npm-libs/graph-of-graphs/url-processing-pipeline.ts</code></td><td>Outer DAG orchestrating inner DAGs</td></tr>
+            <tr data-surface="npm-lib" data-model="graph-of-graphs"><td><code>examples/npm-libs/graph-of-graphs/multi-stage-etl.ts</code></td><td>npm library</td><td>Graph-of-Graphs</td><td><code>npx tsx examples/npm-libs/graph-of-graphs/multi-stage-etl.ts</code></td><td>Mixed nested orchestration</td></tr>
+            <tr data-surface="npm-lib" data-model="batch"><td><code>examples/npm-libs/batch/batch-step-machine.ts</code></td><td>npm library</td><td>Batch</td><td><code>npx tsx examples/npm-libs/batch/batch-step-machine.ts</code></td><td>Batch processing with step-machine per item</td></tr>
+          </tbody>
+        </table>
+      </div>
+    </details>
+  </div>
+  <script>
+    const searchEl = document.getElementById('search');
+    const surfaceFilterEl = document.getElementById('surfaceFilter');
+    const modelFilterEl = document.getElementById('modelFilter');
+    function matchesFilters(text, surface, model) {
+      const q = (searchEl.value || '').toLowerCase().trim();
+      const wantedSurface = surfaceFilterEl.value;
+      const wantedModel = modelFilterEl.value;
+      const qMatch = !q || text.includes(q);
+      const surfaceMatch = wantedSurface === 'all' || surface === wantedSurface;
+      const modelMatch = wantedModel === 'all' || model === wantedModel;
+      return qMatch && surfaceMatch && modelMatch;
+    }
+    function applyFilters() {
+      document.querySelectorAll('.example-card').forEach(card => {
+        const text = (card.dataset.search || card.innerText || '').toLowerCase();
+        const surface = card.dataset.surface || '';
+        const model = card.dataset.model || '';
+        card.classList.toggle('hidden', !matchesFilters(text, surface, model));
+      });
+      document.querySelectorAll('section[data-role="examples"]').forEach(section => {
+        const visibleCards = section.querySelectorAll('.example-card:not(.hidden)').length;
+        section.classList.toggle('hidden', visibleCards === 0);
+      });
+      document.querySelectorAll('.catalog tbody tr').forEach(row => {
+        const text = row.innerText.toLowerCase();
+        const surface = row.dataset.surface || '';
+        const model = row.dataset.model || '';
+        row.classList.toggle('hidden', !matchesFilters(text, surface, model));
+      });
+    }
+    document.querySelectorAll('.copy-btn').forEach(btn => {
+      btn.addEventListener('click', async () => {
+        const text = btn.getAttribute('data-copy') || '';
+        try {
+          await navigator.clipboard.writeText(text);
+          const prev = btn.textContent;
+          btn.textContent = 'Copied';
+          setTimeout(() => { btn.textContent = prev; }, 1000);
+        } catch {
+          const prev = btn.textContent;
+          btn.textContent = 'Copy failed';
+          setTimeout(() => { btn.textContent = prev; }, 1200);
+        }
+      });
+    });
+    searchEl.addEventListener('input', applyFilters);
+    surfaceFilterEl.addEventListener('change', applyFilters);
+    modelFilterEl.addEventListener('change', applyFilters);
+  </script>
+</body>
+</html>