specbook 0.1.0

data/app/views/specbook/viewer/_screenshots_sidebar.html.erb

@@ -0,0 +1,24 @@
+<div class="sidebar" id="screenshots-sidebar">
+  <div class="filter-bar" style="flex-wrap:wrap; gap:0.3rem 0.75rem;">
+    <span id="total-count" style="font-size:0.75rem; color:#94a3b8;"></span>
+    <span style="font-size:0.75rem;"><span id="pass-count" style="color:#4ade80;"></span> <span id="fail-count" style="color:#f87171;"></span></span>
+    <span style="margin-left:auto; font-size:0.75rem; display:flex; gap:0.5rem;">
+      <a href="#" id="expand-all" style="color:#94a3b8; text-decoration:none;">expand all</a>
+      <a href="#" id="collapse-all" style="color:#94a3b8; text-decoration:none;">collapse all</a>
+    </span>
+  </div>
+  <div class="filter-bar" style="gap:0.3rem; padding:0.4rem 1.25rem; border-bottom:1px solid #334155;">
+    <button class="filter-btn active" data-status-filter="all">All</button>
+    <button class="filter-btn" data-status-filter="passing" style="color:#4ade80;">Passing</button>
+    <button class="filter-btn" data-status-filter="failing" style="color:#f87171;">Failing</button>
+    <span style="color:#334155;margin:0 0.2rem;">|</span>
+    <button class="filter-btn active" data-type-filter="all">All</button>
+    <button class="filter-btn" data-type-filter="visual">📷 Visual</button>
+    <button class="filter-btn" data-type-filter="code">💻 Code</button>
+  </div>
+  <div style="padding:0.4rem 1.25rem; border-bottom:1px solid #334155;">
+    <input type="text" id="spec-search" placeholder="Search specs..." style="width:100%; padding:0.4rem 0.6rem; background:#0f172a; border:1px solid #475569; border-radius:4px; color:#e2e8f0; font-size:0.9rem; outline:none;" />
+  </div>
+  <div id="example-list"></div>
+  <div id="feature-list" class="feature-sidebar"></div>
+</div>

data/app/views/specbook/viewer/_styles.html.erb

@@ -0,0 +1,178 @@
+<style>
+* { margin: 0; padding: 0; box-sizing: border-box; }
+body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; background: #0f172a; color: #e2e8f0; height: 100vh; display: flex; flex-direction: column; overflow: hidden; font-size: 15px; }
+
+.top-bar { background: #1e293b; border-bottom: 1px solid #334155; padding: 0.75rem 1.5rem; display: flex; align-items: center; gap: 1rem; flex-shrink: 0; }
+.top-bar h1 { font-size: 1rem; font-weight: 600; white-space: nowrap; }
+.top-bar a { margin-left: auto; font-size: 0.95rem; color: #94a3b8; text-decoration: none; }
+.top-bar a:hover { color: #e2e8f0; }
+
+.content-area { display: flex; flex: 1; overflow: hidden; }
+.sidebar { width: 340px; background: #1e293b; border-right: 1px solid #334155; overflow-y: auto; flex-shrink: 0; }
+.filter-bar { display: flex; gap: 0.5rem; padding: 0.75rem 1.25rem; border-bottom: 1px solid #334155; }
+.filter-btn { padding: 0.3rem 0.6rem; border-radius: 4px; border: 1px solid #475569; background: transparent; color: #94a3b8; cursor: pointer; font-size: 1rem; }
+.filter-btn.active { background: #334155; color: #e2e8f0; border-color: #60a5fa; }
+
+.example-item { padding: 0.5rem 1.25rem 0.5rem 3.4rem; border-bottom: 1px solid #0f172a; cursor: pointer; font-size: 0.95rem; line-height: 1.4; transition: background 0.15s; }
+.depth-3 .example-item { padding-left: 4.6rem; }
+.example-item:hover { background: #334155; }
+.example-item.active { background: #1d4ed8; }
+.example-file { font-size: 1rem; color: #64748b; margin-top: 0.25rem; }
+
+.group-header { padding: 0.5rem 1.25rem; border-bottom: 1px solid #334155; cursor: pointer; font-size: 0.95rem; font-weight: 600; color: #94a3b8; display: flex; align-items: center; gap: 0.5rem; transition: background 0.15s; }
+.group-header:hover { background: #334155; color: #e2e8f0; }
+.group-header .chevron { font-size: 0.6rem; display: inline-block; width: 0.8em; }
+.subgroup-header .chevron { font-size: 0.6rem; display: inline-block; width: 0.8em; }
+.group-header .count { margin-left: auto; font-size: 0.95rem; color: #475569; font-weight: 400; }
+.group-header.has-active { color: #60a5fa; }
+.group-body { overflow: hidden; }
+.group-body.collapsed { display: none; }
+.subgroup-header { padding: 0.5rem 1.25rem 0.5rem 2.2rem; cursor: pointer; font-size: 0.95rem; font-weight: 600; color: #94a3b8; display: flex; align-items: center; gap: 0.5rem; transition: background 0.15s; border-bottom: 1px solid #334155; }
+.subgroup-header:hover { background: #334155; color: #e2e8f0; }
+.subgroup-header .count { margin-left: auto; font-size: 0.95rem; color: #475569; font-weight: 400; }
+.subgroup-body { overflow: hidden; }
+.subgroup-body.collapsed { display: none; }
+.example-item.active .example-file { color: #93c5fd; }
+.badge { display: inline-block; font-size: 0.95rem; padding: 0.1rem 0.4rem; border-radius: 3px; margin-right: 0.4rem; font-weight: 600; }
+.badge-happy { background: #166534; color: #4ade80; }
+.badge-adversarial { background: #7f1d1d; color: #f87171; }
+
+.viewer { flex: 1; display: flex; flex-direction: column; overflow: hidden; min-height: 0; }
+.screenshot-wrapper { flex: 1 1 0; display: flex; align-items: center; justify-content: center; background: #0f172a; overflow: hidden; position: relative; min-height: 0; }
+.screenshot-wrapper img { max-width: 100%; max-height: 100%; object-fit: contain; border-radius: 4px; box-shadow: 0 4px 20px rgba(0,0,0,0.5); }
+
+/* Overlays container — positioned over the image */
+#overlays { position: absolute; top: 0; left: 0; width: 100%; height: 100%; pointer-events: none; }
+
+/* Highlight box for actions */
+.overlay-box { position: absolute; border: 3px solid; border-radius: 4px; pointer-events: none; animation: pulse-highlight 1.5s ease-in-out infinite; }
+.overlay-box.click { border-color: #f97316; background: rgba(249, 115, 22, 0.12); box-shadow: 0 0 12px rgba(249, 115, 22, 0.5); }
+.overlay-box.fill { border-color: #f97316; background: rgba(249, 115, 22, 0.12); box-shadow: 0 0 12px rgba(249, 115, 22, 0.5); }
+.overlay-box.select { border-color: #f97316; background: rgba(249, 115, 22, 0.12); box-shadow: 0 0 12px rgba(249, 115, 22, 0.5); }
+.overlay-box.check { border-color: #f97316; background: rgba(249, 115, 22, 0.12); box-shadow: 0 0 12px rgba(249, 115, 22, 0.5); }
+/* Tap circle — semi-transparent orange dot indicating click/tap point */
+.tap-circle { position: absolute; border-radius: 50%; background: rgba(249, 115, 22, 0.25); border: 2px solid rgba(249, 115, 22, 0.6); pointer-events: none; z-index: 4; animation: tap-pulse 1.5s ease-in-out infinite; }
+@keyframes tap-pulse { 0%, 100% { transform: scale(0.9); opacity: 1; } 50% { transform: scale(1.1); opacity: 0.6; } }
+.overlay-box.assert { border-color: #22c55e; background: rgba(34, 197, 94, 0.12); box-shadow: 0 0 10px rgba(34, 197, 94, 0.4); }
+.overlay-box.assert-negative { border-color: #ef4444; background: rgba(239, 68, 68, 0.08); box-shadow: 0 0 10px rgba(239, 68, 68, 0.3); border-style: dashed; }
+
+@keyframes pulse-highlight { 0%, 100% { opacity: 1; } 50% { opacity: 0.7; } }
+
+/* Assertion label */
+.overlay-label { position: absolute; font-size: 1rem; font-weight: 600; padding: 0.2rem 0.5rem; border-radius: 4px; white-space: nowrap; max-width: 300px; overflow: hidden; text-overflow: ellipsis; pointer-events: none; animation: fade-in 0.3s ease; }
+.overlay-label.positive { background: rgba(34, 197, 94, 0.95); color: white; }
+.overlay-label.negative { background: rgba(239, 68, 68, 0.95); color: white; }
+
+/* Navigate arrow — red arrow pointing at URL bar area at top of screenshot */
+.nav-arrow { position: absolute; pointer-events: none; animation: arrow-bounce 1s ease-in-out infinite; }
+@keyframes arrow-bounce { 0%, 100% { transform: translateY(0); } 50% { transform: translateY(-6px); } }
+
+/* URL bar overlay */
+.url-overlay { position: absolute; background: rgba(244, 63, 94, 0.12); border: 2px solid #f43f5e; border-radius: 6px; pointer-events: none; display: flex; align-items: center; padding: 0 0.75rem; animation: pulse-highlight 1.5s ease-in-out infinite; }
+.url-overlay-text { color: #f43f5e; font-size: 1rem; font-weight: 700; font-family: monospace; }
+
+/* Action badge */
+.action-badge { position: absolute; top: 12px; left: 12px; padding: 0.4rem 0.75rem; border-radius: 6px; font-size: 1rem; font-weight: 700; text-transform: uppercase; letter-spacing: 0.05em; pointer-events: none; backdrop-filter: blur(4px); z-index: 10; animation: fade-in 0.3s ease; }
+.action-badge.click { background: rgba(249, 115, 22, 0.9); color: white; }
+.action-badge.fill { background: rgba(249, 115, 22, 0.9); color: white; }
+.action-badge.select { background: rgba(249, 115, 22, 0.9); color: white; }
+.action-badge.check { background: rgba(249, 115, 22, 0.9); color: white; }
+.action-badge.navigate { background: rgba(245, 158, 11, 0.9); color: #1e293b; }
+.action-badge.assert { background: rgba(34, 197, 94, 0.9); color: white; }
+.action-badge.confirm { background: rgba(239, 68, 68, 0.9); color: white; }
+
+/* Cursor icon */
+.cursor-icon { position: absolute; pointer-events: none; width: 24px; height: 24px; filter: drop-shadow(0 2px 4px rgba(0,0,0,0.5)); animation: click-bounce 0.6s ease; z-index: 5; }
+@keyframes click-bounce { 0% { transform: scale(1); } 30% { transform: scale(0.8); } 60% { transform: scale(1.1); } 100% { transform: scale(1); } }
+
+@keyframes fade-in { from { opacity: 0; transform: translateY(-4px); } to { opacity: 1; transform: translateY(0); } }
+
+/* Assertion list panel */
+.assertion-list { position: absolute; bottom: 12px; right: 12px; max-width: 350px; pointer-events: none; display: flex; flex-direction: column; gap: 4px; z-index: 10; }
+.assertion-item { padding: 0.3rem 0.6rem; border-radius: 4px; font-size: 1rem; font-weight: 500; backdrop-filter: blur(4px); animation: fade-in 0.3s ease; }
+.assertion-item.positive { background: rgba(34, 197, 94, 0.9); color: white; }
+.assertion-item.negative { background: rgba(239, 68, 68, 0.9); color: white; }
+
+.step-info { background: #1e293b; border-top: 1px solid #334155; padding: 0.5rem 1rem; flex-shrink: 0; min-height: 5.5em; max-height: 18em; overflow-y: auto; }
+.step-list { list-style: none; margin: 0; padding: 0; }
+.step-list li { padding: 0.25rem 0.5rem; border-radius: 4px; font-size: 1rem; color: #64748b; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; cursor: pointer; }
+.step-list li:hover { background: #334155; }
+.step-list li.active { background: #1d4ed8; color: #e2e8f0; font-weight: 500; }
+.step-list li .step-icon { display: inline-block; width: 1.2em; text-align: center; margin-right: 0.3em; }
+body.selecting .step-list li, body.selecting .scenario-block, body.selecting .example-item { cursor: text; }
+
+.controls { background: #1e293b; border-top: 1px solid #334155; padding: 0.5rem 1.5rem; display: flex; align-items: center; gap: 1rem; flex-shrink: 0; }
+.controls button { background: #334155; border: 1px solid #475569; color: #e2e8f0; padding: 0.5rem 1.25rem; border-radius: 6px; cursor: pointer; font-size: 1rem; transition: all 0.15s; }
+.controls button:hover:not(:disabled) { background: #475569; }
+.controls button:disabled { opacity: 0.4; cursor: not-allowed; }
+.controls button.primary { background: #2563eb; border-color: #3b82f6; }
+.controls button.primary:hover:not(:disabled) { background: #1d4ed8; }
+
+.progress-bar { flex: 1; height: 6px; background: #334155; border-radius: 3px; overflow: hidden; cursor: pointer; }
+.progress-fill { height: 100%; background: #3b82f6; transition: width 0.2s; border-radius: 3px; }
+
+.speed-control { display: flex; align-items: center; gap: 0.5rem; font-size: 0.95rem; color: #94a3b8; }
+.speed-control select { background: #334155; border: 1px solid #475569; color: #e2e8f0; padding: 0.25rem 0.5rem; border-radius: 4px; font-size: 0.95rem; }
+
+.autoplay-indicator { font-size: 1rem; color: #4ade80; display: none; }
+.autoplay-indicator.active { display: inline; }
+
+/* Setup step overlay — shown when no screenshot exists */
+.setup-overlay { display: flex; flex-direction: column; align-items: center; justify-content: center; height: 100%; gap: 1.5rem; color: #94a3b8; text-align: center; padding: 2rem; }
+.setup-overlay .setup-icon { font-size: 3rem; opacity: 0.5; }
+.setup-overlay .setup-keyword { color: #60a5fa; font-weight: 700; font-size: 1rem; text-transform: uppercase; letter-spacing: 0.1em; }
+.setup-overlay .setup-text { color: #e2e8f0; font-size: 1.2rem; font-weight: 500; max-width: 500px; line-height: 1.6; }
+.setup-overlay .setup-text .quoted { color: #4ade80; }
+.setup-overlay .setup-note { font-size: 0.95rem; color: #64748b; font-style: italic; }
+
+.empty-state { display: flex; flex-direction: column; align-items: center; justify-content: center; height: 100%; gap: 1rem; color: #64748b; }
+.empty-state h2 { font-size: 1.3rem; color: #94a3b8; }
+.empty-state p { max-width: 500px; text-align: center; line-height: 1.6; }
+.empty-state code { background: #334155; padding: 0.5rem 1rem; border-radius: 6px; font-size: 1rem; color: #e2e8f0; }
+
+/* Full gherkin view — for service/model specs with no screenshots */
+.gherkin-card { display: flex; flex-direction: column; align-items: center; justify-content: center; height: 100%; padding: 2rem; }
+.gherkin-card .gherkin-title { font-size: 1rem; color: #64748b; text-transform: uppercase; letter-spacing: 0.15em; margin-bottom: 0.5rem; }
+.gherkin-card .gherkin-scenario-name { font-size: 1.3rem; color: #e2e8f0; font-weight: 600; margin-bottom: 1.5rem; text-align: center; max-width: 600px; }
+.gherkin-card .gherkin-steps-list { list-style: none; padding: 0; margin: 0; max-width: 600px; width: 100%; }
+.gherkin-card .gherkin-steps-list li { padding: 0.4rem 0.75rem; font-size: 1rem; color: #cbd5e1; line-height: 1.5; border-radius: 4px; }
+.gherkin-card .gherkin-steps-list li .kw { color: #60a5fa; font-weight: 600; display: inline-block; min-width: 3.5em; }
+.gherkin-card .gherkin-steps-list li .kw-then { color: #4ade80; }
+.gherkin-card .gherkin-steps-list li .quoted { color: #4ade80; }
+.gherkin-card .gherkin-steps-list .bg-label { color: #64748b; font-size: 1rem; font-style: italic; padding: 0.5rem 0.75rem 0.15rem; }
+.gherkin-card .gherkin-status { margin-top: 1.5rem; font-size: 1rem; font-weight: 500; }
+.gherkin-card .gherkin-status.passed { color: #4ade80; }
+.gherkin-card .gherkin-status.failed { color: #f87171; }
+
+/* Step source code block */
+.step-source { margin: 0.2rem 0 0.4rem 3.5em; background: #1e293b; border: 1px solid #334155; border-radius: 4px; padding: 0.4rem 0.6rem; font-family: 'SF Mono', 'Fira Code', monospace; font-size: 1rem; color: #94a3b8; white-space: pre-wrap; line-height: 1.5; max-height: 200px; overflow-y: auto; }
+.step-source .src-file { color: #64748b; font-size: 0.95rem; display: block; margin-bottom: 0.3rem; text-decoration: none; pointer-events: auto; }
+.step-source .src-file:hover { color: #94a3b8; text-decoration: underline; }
+.step-source .src-keyword { color: #c084fc; }
+.step-source .src-string { color: #4ade80; }
+.step-source .src-comment { color: #475569; font-style: italic; }
+.step-source .src-method { color: #60a5fa; }
+
+/* Gherkin feature sidebar */
+.feature-sidebar { padding: 0; font-family: 'SF Mono', 'Menlo', 'Monaco', monospace; font-size: 1rem; line-height: 1.6; }
+.feature-header { padding: 1rem 1.25rem 0.5rem; border-bottom: 1px solid #334155; }
+.feature-keyword { color: #c084fc; font-weight: 600; }
+.feature-name { color: #e2e8f0; font-weight: 600; font-size: 1rem; }
+.feature-desc { color: #94a3b8; font-style: italic; padding: 0.25rem 0 0 1rem; font-size: 1rem; }
+.feature-background { padding: 0.75rem 1.25rem; border-bottom: 1px solid #334155; background: #1a2332; }
+.feature-bg-label { color: #94a3b8; font-weight: 600; font-size: 1rem; text-transform: uppercase; letter-spacing: 0.05em; margin-bottom: 0.25rem; }
+.gherkin-step { padding: 0.1rem 0 0.1rem 1rem; color: #cbd5e1; }
+.gherkin-step .kw { color: #60a5fa; font-weight: 600; display: inline-block; min-width: 3.5em; }
+.gherkin-step .quoted { color: #4ade80; }
+.scenario-block { border-bottom: 1px solid #334155; cursor: pointer; transition: background 0.15s; }
+.scenario-block:hover { background: #253348; }
+.scenario-block.active { background: #1e3a5f; border-left: 3px solid #3b82f6; }
+.scenario-header { padding: 0.6rem 1.25rem 0.3rem; display: flex; flex-direction: column; gap: 0.1rem; }
+.scenario-tag { color: #f87171; font-size: 1rem; }
+.scenario-name { color: #e2e8f0; font-weight: 500; }
+.scenario-status { margin-left: auto; font-size: 1rem; }
+.scenario-steps { padding: 0 1.25rem 0.6rem; }
+.scenario-steps .gherkin-step { font-size: 1rem; opacity: 0.7; }
+.scenario-block.active .scenario-steps .gherkin-step { opacity: 1; }
+.scenario-block.active .gherkin-step.current-step { background: #1d4ed8; border-radius: 3px; margin: 0 -0.5rem; padding-left: 1.5rem; }
+</style>

data/app/views/specbook/viewer/_top_bar.html.erb

@@ -0,0 +1,13 @@
+<div class="top-bar">
+  <h1>Specbook</h1>
+  <% if @traces.present? && @manifest.present? %>
+    <div style="display:flex; gap:0.5rem; margin-left:1rem;">
+      <button onclick="switchTab('screenshots')" id="tab-screenshots" style="padding:0.3rem 0.8rem; border-radius:4px; border:1px solid #475569; background:#334155; color:#e2e8f0; cursor:pointer; font-size:0.8rem;">Screenshots (<%= @manifest.size %>)</button>
+      <button onclick="switchTab('traces')" id="tab-traces" style="padding:0.3rem 0.8rem; border-radius:4px; border:1px solid #475569; background:transparent; color:#94a3b8; cursor:pointer; font-size:0.8rem;">Traces (<%= @traces.size %>)</button>
+    </div>
+  <% end %>
+  <span class="autoplay-indicator" id="autoplay-indicator">&#9654; Playing</span>
+  <% if Specbook.config.back_link %>
+    <a href="<%= Specbook.config.back_link[:href] %>"><%= Specbook.config.back_link[:text] || "← Back" %></a>
+  <% end %>
+</div>

data/app/views/specbook/viewer/_traces_sidebar.html.erb

@@ -0,0 +1,15 @@
+<div class="sidebar" id="traces-sidebar" style="display:none;">
+  <div style="padding:0.75rem 1.25rem; border-bottom:1px solid #334155;">
+    <input type="text" id="trace-search" placeholder="Filter specs..." style="width:100%; background:#0f172a; border:1px solid #475569; color:#e2e8f0; padding:0.4rem 0.6rem; border-radius:4px; font-size:0.8rem;">
+  </div>
+  <div id="trace-list" style="overflow-y:auto;">
+    <% @traces.each_with_index do |t, i| %>
+      <div class="example-item trace-item" data-index="<%= i %>" data-name="<%= t["name"].downcase %>" onclick="selectTrace(<%= i %>)">
+        <span class="badge badge-<%= t["type"] %>"><%= t["type"] %></span>
+        <span style="font-size:0.7rem; padding:0.1rem 0.3rem; border-radius:3px; background:<%= t["status"] == "passed" ? "#166534" : "#7f1d1d" %>; color:<%= t["status"] == "passed" ? "#4ade80" : "#f87171" %>; margin-right:0.3rem;"><%= t["status"] == "passed" ? "✓" : "✗" %></span>
+        <%= t["name"] %>
+        <div class="example-file"><%= t["file"] %>:<%= t["line"] %></div>
+      </div>
+    <% end %>
+  </div>
+</div>

data/app/views/specbook/viewer/_viewer_panel.html.erb

@@ -0,0 +1,44 @@
+<div class="viewer">
+  <div id="traces-viewer" style="flex:1; display:none; align-items:center; justify-content:center;">
+    <div id="trace-detail" style="text-align:center; color:#64748b;">
+      <h2 style="font-size:1.2rem; color:#94a3b8; margin-bottom:0.5rem;">Click a spec to view its trace</h2>
+    </div>
+  </div>
+
+  <div id="screenshots-viewer" style="flex:1; display:flex; flex-direction:column;">
+  <% if @manifest.empty? && @traces.empty? %>
+    <div class="empty-state">
+      <h2>No recordings yet</h2>
+      <p>Run specs with recording enabled:</p>
+      <code>RECORD_SPECS=1 CI=1 bundle exec rspec spec/system/</code>
+      <p style="margin-top:0.5rem;">Playwright traces give you DOM snapshots, network activity, and action timeline.</p>
+      <p>Then refresh this page.</p>
+    </div>
+  <% elsif @manifest.present? %>
+    <div class="screenshot-wrapper" id="screenshot-wrapper">
+      <img id="screenshot-img" src="" alt="Spec screenshot">
+      <div id="overlays"></div>
+    </div>
+    <div class="step-info" id="step-info">
+      <ol class="step-list" id="step-list"></ol>
+    </div>
+    <div class="controls">
+      <button id="btn-prev" title="Previous (←)">&#9664; Prev</button>
+      <button id="btn-next" class="primary" title="Next (→)">Next &#9654;</button>
+      <div class="progress-bar" id="progress-bar">
+        <div class="progress-fill" id="progress-fill"></div>
+      </div>
+      <button id="btn-play" title="Play/Pause (Space)">&#9654; Play</button>
+      <div class="speed-control">
+        <label>Speed:</label>
+        <select id="speed-select">
+          <option value="3000">Slow (3s)</option>
+          <option value="1500" selected>Normal (1.5s)</option>
+          <option value="800">Fast (0.8s)</option>
+          <option value="400">Very Fast</option>
+        </select>
+      </div>
+    </div>
+  <% end %>
+  </div>
+</div>

data/app/views/specbook/viewer/show.html.erb

@@ -0,0 +1,27 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<%= csrf_meta_tags %>
+<title>Specbook</title>
+<%= render "styles" %>
+</head>
+<body>
+
+<%= render "top_bar" %>
+
+<div class="content-area">
+  <%= render "traces_sidebar" %>
+  <%= render "screenshots_sidebar" %>
+  <%= render "viewer_panel" %>
+</div>
+
+<script>
+window.Specbook = window.Specbook || {};
+window.Specbook.config = <%= raw @specbook_js_config.to_json %>;
+</script>
+
+<%= render "app_js" %>
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,6 @@
+Specbook::Engine.routes.draw do
+  root to: "viewer#show"
+  get "screenshots/:filename", to: "viewer#screenshot", as: :screenshot, constraints: { filename: /[^\/]+/ }
+  get "traces/:filename", to: "viewer#trace", as: :trace, constraints: { filename: /[^\/]+/ }
+  post "traces/:filename/view", to: "viewer#view_trace", as: :view_trace, constraints: { filename: /[^\/]+/ }
+end

data/lib/generators/specbook/install/USAGE

@@ -0,0 +1,25 @@
+Description:
+    Installs Specbook: writes config/initializers/specbook.rb and prints
+    further setup steps.
+
+Example:
+    rails generate specbook:install
+
+    This will create:
+        config/initializers/specbook.rb
+
+    You will then need to:
+
+      1. Mount the engine in config/routes.rb:
+
+           mount Specbook::Engine => "/specs"
+
+      2. Add to spec/rails_helper.rb (or test_helper):
+
+           require "specbook/rspec"
+
+      3. Record specs with:
+
+           RECORD_SPECS=1 bundle exec rspec
+
+      4. Visit /specs in your dev server.

data/lib/generators/specbook/install/install_generator.rb

@@ -0,0 +1,19 @@
+require "rails/generators"
+
+module Specbook
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Install Specbook: copies an initializer and prints next steps."
+
+      def copy_initializer
+        template "specbook.rb", "config/initializers/specbook.rb"
+      end
+
+      def show_readme
+        readme "README" if behavior == :invoke
+      end
+    end
+  end
+end

data/lib/generators/specbook/install/templates/README

@@ -0,0 +1,22 @@
+
+==================================================================
+Specbook installed!
+
+Next steps:
+
+  1. Mount the engine in config/routes.rb:
+
+       mount Specbook::Engine => "/specs"
+
+  2. Add to spec/rails_helper.rb:
+
+       require "specbook/rspec"
+
+  3. Record specs with:
+
+       RECORD_SPECS=1 bundle exec rspec
+
+  4. Visit /specs in your dev server.
+
+  Configure Specbook in config/initializers/specbook.rb.
+==================================================================

data/lib/generators/specbook/install/templates/specbook.rb

@@ -0,0 +1,45 @@
+# Specbook configuration.
+#
+# Specbook is a viewer + recorder for Rails system specs. See README for full docs.
+# All options below are optional — defaults are sensible.
+Specbook.configure do |config|
+  # Authorization. Default: dev/test environments only. Provide a lambda
+  # taking the controller; return truthy to allow access.
+  #
+  # config.authorize_with = ->(controller) { controller.current_user&.admin? }
+
+  # A "back" link in the top bar. Default: no link.
+  #
+  # config.back_link = { href: "/admin", text: "← Back to admin" }
+
+  # URL prefix for opening files in your editor. Default: nil (file:line is
+  # rendered as plain text).
+  #
+  # config.editor_base = "vscode://file#{Rails.root}"
+
+  # Per-actor colors for visual differentiation in the viewer.
+  #
+  # config.actor_colors = {
+  #   "Alice" => "#3b82f6",
+  #   "Bob"   => "#f59e0b"
+  # }
+
+  # Top-level directory groupings for the sidebar.
+  #
+  # config.ui_domains = %w[admin public mobile]
+
+  # Pattern → icon mapping for non-screenshot Gherkin steps. Defaults provide
+  # generic login/setup/redirect rules; add domain-specific rules here.
+  #
+  # config.setup_overlay_rules = [
+  #   { pattern: /booking exists/i, icon: "📅", note: "Test setup" }
+  # ] + Specbook::Configuration.new.setup_overlay_rules
+
+  # Where artifacts are written. Defaults below match Rails.root paths.
+  #
+  # config.screenshot_root = Rails.root.join("tmp/spec_screenshots")
+  # config.trace_root      = Rails.root.join("tmp/spec_traces")
+  # config.feature_root    = Rails.root
+  # config.max_runs           = 20
+  # config.trace_viewer_port  = 9322
+end

data/lib/specbook/configuration.rb

@@ -0,0 +1,50 @@
+module Specbook
+  class Configuration
+    attr_accessor :max_runs,
+                  :trace_viewer_port,
+                  :actor_colors,
+                  :ui_domains,
+                  :setup_overlay_rules,
+                  :back_link,
+                  :editor_base,
+                  :authorize_with
+
+    attr_writer :screenshot_root, :trace_root, :feature_root
+
+    def initialize
+      @max_runs            = 20
+      @trace_viewer_port   = 9322
+      @actor_colors        = {}
+      @ui_domains          = []
+      @setup_overlay_rules = [
+        { pattern: /\b(?:logs in|signs in|signed in)\b/i, icon: "🔑", note: "Authentication — switching user session" },
+        { pattern: /\bexists?\b/i,                        icon: "🔧", note: "Test setup — creating test data" },
+        { pattern: /\bredirected to\b/i,                  icon: "✅", note: "Assertion passed — verified redirect" }
+      ]
+      @back_link       = nil
+      @editor_base     = nil
+      @authorize_with  = nil
+      @screenshot_root = nil
+      @trace_root      = nil
+      @feature_root    = nil
+    end
+
+    def screenshot_root
+      @screenshot_root || rails_root.join("tmp/spec_screenshots")
+    end
+
+    def trace_root
+      @trace_root || rails_root.join("tmp/spec_traces")
+    end
+
+    def feature_root
+      @feature_root || rails_root
+    end
+
+    private
+
+    def rails_root
+      defined?(Rails) ? Rails.root : Pathname.new(Dir.pwd)
+    end
+  end
+end

data/lib/specbook/engine.rb

@@ -0,0 +1,7 @@
+require "rails/engine"
+
+module Specbook
+  class Engine < ::Rails::Engine
+    isolate_namespace Specbook
+  end
+end

data/lib/specbook/recorders/playwright_trace.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+# Playwright trace recorder for spec presentations.
+# Enable with: RECORD_TRACES=1 CI=1 bundle exec rspec spec/system/
+#
+# Captures Playwright traces (DOM snapshots, network, console, action timeline)
+# for each system spec. View with: npx playwright show-trace tmp/spec_traces/<name>.zip
+
+if ENV["RECORD_TRACES"]
+  require "fileutils"
+
+  module Specbook
+    module Recorders
+      module PlaywrightTrace
+        TRACE_DIR = Specbook.config.trace_root
+        mattr_accessor :manifest
+        self.manifest = []
+
+        def self.slug_for(example)
+          example.full_description
+            .gsub(/[^a-zA-Z0-9]+/, "_")
+            .gsub(/\A_|_\z/, "")
+            .truncate(120, omission: "")
+        end
+
+        def self.write_manifest!
+          FileUtils.mkdir_p(TRACE_DIR)
+          File.write(
+            TRACE_DIR.join("manifest.json"),
+            JSON.pretty_generate(manifest)
+          )
+        end
+      end
+
+      # Patch visit to start tracing on first navigation
+      module TraceVisitPatch
+        def visit(path, **)
+          if !@_trace_started && page.driver.respond_to?(:with_playwright_page)
+            page.driver.with_playwright_page do |pw_page|
+              pw_page.context.tracing.start(screenshots: true, snapshots: true, sources: false)
+            end
+            @_trace_started = true
+          end
+          super
+        end
+      end
+    end
+  end
+
+  RSpec.configure do |config|
+    config.include Specbook::Recorders::TraceVisitPatch, type: :system
+
+    config.before(:each, type: :system) do
+      @_trace_started = false
+    end
+
+    config.after(:each, type: :system) do |example|
+      next unless @_trace_started
+      next unless page.driver.respond_to?(:with_playwright_page)
+
+      slug = Specbook::Recorders::PlaywrightTrace.slug_for(example)
+      filename = "#{slug}.zip"
+      filepath = Specbook::Recorders::PlaywrightTrace::TRACE_DIR.join(filename)
+      FileUtils.mkdir_p(Specbook::Recorders::PlaywrightTrace::TRACE_DIR)
+
+      begin
+        page.driver.with_playwright_page do |pw_page|
+          pw_page.context.tracing.stop(path: filepath.to_s)
+        end
+
+        Specbook::Recorders::PlaywrightTrace.manifest << {
+          name: example.full_description,
+          file: example.metadata[:file_path].sub("./", ""),
+          line: example.metadata[:line_number],
+          status: example.exception ? "failed" : "passed",
+          type: example.metadata[:adversarial] ? "adversarial" : "happy",
+          trace: filename
+        }
+      rescue => e
+        Rails.logger.warn("[Specbook::Recorders::PlaywrightTrace] stop failed: #{e.message}")
+      end
+    end
+
+    config.after(:suite) do
+      Specbook::Recorders::PlaywrightTrace.write_manifest!
+      count = Specbook::Recorders::PlaywrightTrace.manifest.size
+      puts "\n🎬 Traces saved to tmp/spec_traces/ (#{count} examples recorded)"
+      puts "   View with: npx playwright show-trace tmp/spec_traces/<name>.zip" if count > 0
+    end
+  end
+end