rubylens 0.1.0 → 0.2.0

data/assets/shells/report.html

@@ -22,20 +22,20 @@
   </header>
   <aside class="panel" id="panel" aria-label="Explore this codebase">
     <div class="panel-header">
-      <div><h2>Explore this codebase</h2><p>Show a system, focus its stars, or fly to a Ruby code highlight.</p></div>
-      <div class="panel-header-actions"><button type="button" id="panel-toggle" aria-expanded="true" aria-controls="panel-body">Hide</button></div>
+      <div class="panel-title"><p class="panel-kicker">Stellar navigator</p><h2>Explorer</h2></div>
+      <div class="panel-header-actions"><button type="button" id="panel-toggle" aria-label="Collapse Explorer" aria-expanded="true" aria-controls="panel-body">Collapse</button></div>
     </div>
     <div id="panel-body">
       <div class="explorer-search" id="explorer-search-region" role="search">
-        <label for="explorer-search">Search classes, modules, and gems</label>
-        <input type="search" id="explorer-search" placeholder="Class, module, or gem name" autocomplete="off" spellcheck="false" aria-controls="search-results" aria-describedby="search-status">
-        <p class="search-status" id="search-status" role="status" aria-live="polite">Search Core, Tests, and Gems.</p>
+        <label for="explorer-search">Find a star or system</label>
+        <input type="search" id="explorer-search" placeholder="Class, module, or gem" autocomplete="off" spellcheck="false" aria-controls="search-results" aria-describedby="search-status">
+        <p class="search-status" id="search-status" role="status" aria-live="polite"></p>
         <div class="search-results" id="search-results" role="region" aria-label="Search results" hidden></div>
       </div>
       <div id="controls"></div>
-    <div class="foot">Double-click a dependency system or gem cloud, press Enter or F on its selected marker, or tap that marker again to expand it. Escape exits spatial focus; Reset restores the default view. This owner-only report embeds class, module, and gem names for hover details; dependency stars remain anonymous. Source, comments, and paths are excluded. Do not share the HTML unless you intend to disclose codebase structure.</div></div>
+    <div class="foot">Keep private — includes codebase names and structure, but not source or file paths.</div></div>
   </aside>
-  <div class="toolbar"><button type="button" id="motion" aria-label="Pause drift" aria-keyshortcuts="Space" aria-pressed="false" title="Pause drift (Space)">Pause drift</button><button type="button" id="reset-view" aria-label="Reset to default view" aria-keyshortcuts="0" title="Reset view (0)">Reset</button><button type="button" id="pan-mode" aria-label="Pan mode" aria-keyshortcuts="P" aria-pressed="false" title="Pan mode (P)">Pan</button><button type="button" id="zoom-out" aria-label="Zoom out" aria-keyshortcuts="-" title="Zoom out (−)">−</button><output class="zoom-level" id="zoom-level" aria-label="Zoom level">200%</output><button type="button" id="zoom-in" aria-label="Zoom in" aria-keyshortcuts="+" title="Zoom in (+)">+</button><button type="button" id="help-open" aria-label="Keyboard shortcuts" aria-keyshortcuts="?" aria-haspopup="dialog" title="Keyboard shortcuts (?)">?</button></div>
+  <div class="toolbar"><button type="button" id="motion" aria-label="Pause drift" aria-keyshortcuts="Space" aria-pressed="false" title="Pause drift (Space)">Pause drift</button><button type="button" id="reset-view" aria-label="Reset to default view" aria-keyshortcuts="0" title="Reset view (0)">Reset</button><button type="button" id="pan-mode" aria-label="Pan mode" aria-keyshortcuts="P" aria-pressed="false" title="Pan mode (P)">Pan</button><button type="button" id="zoom-out" aria-label="Zoom out" aria-keyshortcuts="-" title="Zoom out (−)">−</button><output class="zoom-level" id="zoom-level" aria-label="Zoom level">200%</output><button type="button" id="zoom-in" aria-label="Zoom in" aria-keyshortcuts="+" title="Zoom in (+)">+</button><button type="button" id="ui-toggle" aria-label="Hide interface" aria-keyshortcuts="H" aria-pressed="false" title="Hide interface (H)">Hide UI</button><button type="button" id="help-open" aria-label="Keyboard shortcuts" aria-keyshortcuts="?" aria-haspopup="dialog" title="Keyboard shortcuts (?)">?</button></div>
   <div class="hint">Drag to orbit · scroll to zoom · press ? for all shortcuts</div>
   <aside class="tooltip" id="tooltip" role="status" hidden><p class="tooltip-category" id="tooltip-category"></p><p class="tooltip-name" id="tooltip-name"></p><p class="tooltip-context" id="tooltip-context"></p><dl class="tooltip-metrics" id="tooltip-metrics"></dl></aside>
   <div class="help-overlay" id="shortcuts-help" role="dialog" aria-modal="true" aria-label="Shortcuts and controls" hidden>
@@ -49,6 +49,7 @@
             <div><dt>Shift-drag or right-drag</dt><dd>Move the view</dd></div>
             <div><dt>Scroll or pinch</dt><dd>Zoom at the cursor</dd></div>
             <div><dt>Click a star</dt><dd>Select and fly to it</dd></div>
+            <div><dt>Tap while UI is hidden</dt><dd>Show the interface</dd></div>
             <div><dt>Double-click a gem cloud</dt><dd>Expand its stars</dd></div>
             <div><dt>Double-click empty space</dt><dd>Zoom in · Shift zooms out</dd></div>
           </dl>
@@ -63,6 +64,7 @@
             <div><dt>Space</dt><dd>Pause or resume drift</dd></div>
             <div><dt>Enter / F</dt><dd>Expand the selected gem cloud</dd></div>
             <div><dt>/</dt><dd>Search</dd></div>
+            <div><dt>H</dt><dd>Hide or show the interface</dd></div>
             <div><dt>Esc</dt><dd>Exit focus and fly back</dd></div>
             <div><dt>?</dt><dd>Show or hide this list</dd></div>
           </dl>

data/assets/shells/showcase.html

@@ -13,6 +13,7 @@
 <body data-rubylens-mode="showcase">
   <main class="showcase-stage" id="showcase-stage">
     <canvas id="cosmos" role="img" aria-label="Stellar artwork of a Ruby codebase."></canvas>
+    <canvas id="travel-cosmos" aria-hidden="true"></canvas>
     <header class="masthead">
       <p class="eyebrow">RubyLens · codebase galaxy</p>
       <h1>Ruby project</h1>

data/assets/styles/report.css

@@ -8,6 +8,12 @@
     canvas.is-star:not(.is-pan):not(.is-dragging-pan):not(:active) { cursor: pointer; }
     canvas.is-pan:active, canvas.is-dragging-pan:active { cursor: grabbing; }
     canvas:focus-visible { outline: 2px solid rgba(216, 200, 255, .85); outline-offset: -4px; }
+    body.is-ui-hidden .masthead,
+    body.is-ui-hidden .panel,
+    body.is-ui-hidden .toolbar,
+    body.is-ui-hidden .hint,
+    body.is-ui-hidden .tooltip,
+    body.is-ui-hidden .help-overlay { display: none; }
     .masthead { position: fixed; top: 28px; left: 32px; z-index: 2; pointer-events: none; max-width: 760px; }
     .eyebrow { margin: 0 0 10px; color: #b6a9c9; font-size: 11px; font-weight: 750; letter-spacing: .18em; text-transform: uppercase; }
     h1 { margin: 0; font: 500 clamp(28px, 4vw, 54px)/.95 ui-serif, Georgia, serif; letter-spacing: -.045em; }
@@ -25,14 +31,15 @@
     .warning-row { display: grid; gap: 2px; }
     .warning-row strong { color: #f1e9dc; font-size: 11px; overflow-wrap: anywhere; }
     .warning-row span, .warning-note { margin: 0; color: #958875; font-size: 9px; line-height: 1.45; }
-    .panel { position: fixed; z-index: 3; top: 20px; right: 20px; width: min(348px, calc(100vw - 40px)); max-height: calc(100vh - 40px); overflow: auto; border: 1px solid rgba(255,255,255,.1); border-radius: 18px; background: rgba(9, 9, 18, .82); box-shadow: 0 24px 80px rgba(0,0,0,.4); backdrop-filter: blur(18px); transition: width 180ms cubic-bezier(.16, 1, .3, 1); }
+    .panel { position: fixed; z-index: 3; top: 20px; right: 20px; width: min(348px, calc(100vw - 40px)); max-height: calc(100vh - 40px); overflow: auto; border: 1px solid rgba(255,255,255,.1); border-radius: 18px; background: rgba(9, 9, 18, .86); box-shadow: 0 24px 80px rgba(0,0,0,.42); backdrop-filter: blur(18px); }
     .panel.is-collapsed { width: 190px; overflow: hidden; }
-    .panel-header { position: sticky; top: 0; z-index: 1; display: flex; justify-content: space-between; gap: 16px; align-items: start; padding: 18px 18px 14px; border-bottom: 1px solid rgba(255,255,255,.08); background: rgba(9, 9, 18, .92); }
+    .panel-header { position: sticky; top: 0; z-index: 1; display: flex; justify-content: space-between; gap: 16px; align-items: center; padding: 16px 18px 15px; border-bottom: 1px solid rgba(255,255,255,.08); background: rgba(9, 9, 18, .94); }
     .panel.is-collapsed .panel-header { align-items: center; padding-block: 13px; border-bottom: 0; }
-    .panel.is-collapsed .panel-header p { display: none; }
+    .panel.is-collapsed .panel-kicker { display: none; }
+    .panel-title { display: grid; gap: 3px; min-width: 0; }
+    .panel-kicker { margin: 0; color: #a99db8; font-size: 9px; font-weight: 750; letter-spacing: .14em; line-height: 1.2; text-transform: uppercase; }
     .panel-header-actions { display: flex; flex: none; gap: 6px; }
-    .panel h2 { margin: 0; font-size: 14px; letter-spacing: -.01em; }
-    .panel-header p { margin: 4px 0 0; color: #8d8798; font-size: 11px; line-height: 1.4; }
+    .panel h2 { margin: 0; color: #f3eef8; font-size: 15px; letter-spacing: -.02em; }
     button { border: 1px solid rgba(255,255,255,.12); border-radius: 9px; padding: 7px 10px; background: rgba(255,255,255,.06); color: #eeeaf4; font: inherit; font-size: 11px; cursor: pointer; }
     button:hover { background: rgba(255,255,255,.1); }
     button:disabled { opacity: .45; cursor: not-allowed; }
@@ -42,40 +49,59 @@
     summary::-webkit-details-marker { display: none; }
     summary::after { content: "⌄"; margin-left: auto; color: #777080; font-size: 12px; transition: transform 160ms cubic-bezier(.16, 1, .3, 1); }
     details[open] summary::after { transform: rotate(180deg); }
-    .swatch { width: 8px; height: 8px; border-radius: 50%; box-shadow: 0 0 14px currentColor; }
-    .swatch.core { color: #f15f87; background: currentColor; }
-    .swatch.tests { color: #69d7ff; background: currentColor; }
-    .swatch.dependencies { color: #ffc86a; background: currentColor; }
-    .section-heading { display: grid; gap: 2px; }
+    .explorer-section { --accent: 216, 200, 255; }
+    .explorer-section.core { --accent: 232, 126, 158; }
+    .explorer-section.tests { --accent: 110, 192, 222; }
+    .explorer-section.dependencies { --accent: 218, 166, 87; }
+    .explorer-section > summary { gap: 10px; min-height: 58px; padding-block: 12px; }
+    .explorer-section > summary::before { content: ""; align-self: stretch; flex: 0 0 1px; width: 1px; border-radius: 1px; background: rgba(var(--accent), .48); transition: background-color 180ms cubic-bezier(.16, 1, .3, 1); }
+    .explorer-section[open] > summary { background: linear-gradient(90deg, rgba(var(--accent), .075), transparent 72%); }
+    .explorer-section[open] > summary::before { background: rgba(var(--accent), .92); }
+    .explorer-section > summary::after { margin-left: 0; }
+    .section-heading { display: grid; flex: 1 1 auto; gap: 3px; min-width: 0; }
     .section-heading strong { color: #eee9f4; font-size: 12px; }
-    .section-heading small { color: #837c8d; font-size: 10px; font-weight: 500; }
+    .section-heading small { overflow: hidden; color: #958e9f; font-size: 9px; font-weight: 500; text-overflow: ellipsis; white-space: nowrap; }
+    .section-state { flex: none; color: #9992a2; font-size: 8px; font-weight: 700; letter-spacing: .04em; text-transform: uppercase; }
+    .section-state .focused, .section-state .hidden { display: none; }
+    .explorer-section:has(.section-actions button[aria-pressed="true"]) .section-state .visible { display: none; }
+    .explorer-section:has(.section-actions button[aria-pressed="true"]) .section-state .focused { display: inline; color: rgba(var(--accent), .95); }
+    .explorer-section:has(.visibility input:not(:checked)) .section-state .visible,
+    .explorer-section:has(.visibility input:not(:checked)) .section-state .focused { display: none; }
+    .explorer-section:has(.visibility input:not(:checked)) .section-state .hidden { display: inline; }
     .section-note { margin: -4px 0 13px; color: #756e7e; font-size: 9px; line-height: 1.4; }
     .section-body { padding: 0 18px 16px; }
-    .section-actions { display: flex; align-items: center; gap: 8px; margin-bottom: 14px; }
+    .section-actions { display: flex; align-items: center; gap: 8px; margin-bottom: 12px; }
     .ruby-breakdown { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 8px 18px; margin: 0 0 14px; padding: 10px 0; border-block: 1px solid rgba(255,255,255,.08); }
     .ruby-breakdown div { min-width: 0; }
     .ruby-breakdown dt, .ruby-breakdown dd { margin: 0; }
     .ruby-breakdown dt { color: #837c8d; font-size: 9px; }
     .ruby-breakdown dd { margin-top: 2px; color: #f3edf9; font-size: 13px; font-weight: 700; font-variant-numeric: tabular-nums; }
-    .section-actions button[aria-pressed="true"] { border-color: rgba(216,200,255,.36); background: rgba(216,200,255,.14); color: #fff; }
-    .visibility { display: inline-flex; align-items: center; gap: 7px; margin-right: auto; color: #b8b1c0; font-size: 11px; cursor: pointer; }
-    .visibility input { width: 15px; height: 15px; margin: 0; accent-color: #d8c8ff; }
-    .fact-label { margin: 0 0 7px; color: #7f788b; font-size: 10px; }
-    .facts { display: grid; gap: 5px; }
-    .fact { display: grid; grid-template-columns: 1fr auto; gap: 4px 12px; width: 100%; padding: 9px 10px; text-align: left; }
-    .fact:hover { border-color: rgba(255,255,255,.2); }
+    .section-actions button[aria-pressed="true"] { border-color: rgba(var(--accent), .4); background: rgba(var(--accent), .13); color: #fff; }
+    .visibility { position: relative; display: inline-flex; align-items: center; gap: 8px; margin-right: auto; color: #b8b1c0; font-size: 11px; cursor: pointer; }
+    .visibility input { position: absolute; width: 1px; height: 1px; overflow: hidden; opacity: 0; }
+    .visibility-track { position: relative; width: 25px; height: 14px; border: 1px solid rgba(255,255,255,.2); border-radius: 999px; background: rgba(255,255,255,.07); transition: border-color 160ms ease, background-color 160ms ease; }
+    .visibility-track::after { content: ""; position: absolute; top: 2px; left: 2px; width: 8px; height: 8px; border-radius: 50%; background: #8d8796; transition: transform 180ms cubic-bezier(.16, 1, .3, 1), background-color 160ms ease; }
+    .visibility input:checked + .visibility-track { border-color: rgba(var(--accent), .45); background: rgba(var(--accent), .14); }
+    .visibility input:checked + .visibility-track::after { background: rgb(var(--accent)); transform: translateX(11px); }
+    .visibility input:focus-visible + .visibility-track { outline: 2px solid rgba(216, 200, 255, .9); outline-offset: 2px; }
+    .fact-label { margin: 0 0 5px; color: #8d8697; font-size: 9px; font-weight: 650; }
+    .facts { border-block: 1px solid rgba(255,255,255,.075); }
+    .fact { display: grid; grid-template-columns: 1fr auto; gap: 4px 12px; width: 100%; border: 0; border-radius: 0; padding: 9px 7px; background: transparent; text-align: left; transition: background-color 160ms ease; }
+    .fact + .fact { border-top: 1px solid rgba(255,255,255,.065); }
+    .fact:hover { background: rgba(var(--accent), .065); }
     .fact-title { display: flex; align-items: center; gap: 6px; min-width: 0; color: #a9a2b1; font-size: 10px; }
     .fact-scope { flex: none; border: 1px solid rgba(255,255,255,.1); border-radius: 999px; padding: 2px 5px; color: #817a89; font-size: 8px; font-weight: 650; }
     .fact-value { grid-row: 1 / span 2; grid-column: 2; align-self: center; color: #fffafd; font-size: 12px; font-weight: 750; font-variant-numeric: tabular-nums; }
     .fact-name { overflow: hidden; color: #ece6f2; font-size: 11px; font-weight: 650; text-overflow: ellipsis; white-space: nowrap; }
-    .fact[aria-pressed="true"] { border-color: rgba(255,255,255,.28); background: rgba(255,255,255,.12); }
-    .explorer-search { display: grid; gap: 7px; padding: 14px 18px; border-bottom: 1px solid rgba(255,255,255,.08); }
+    .fact[aria-pressed="true"] { background: rgba(var(--accent), .13); }
+    .explorer-search { display: grid; gap: 7px; padding: 14px 18px 15px; border-bottom: 1px solid rgba(255,255,255,.08); }
     .explorer-search[hidden] { display: none; }
     .explorer-search label { color: #b8b1c0; font-size: 10px; font-weight: 700; }
     .explorer-search input { width: 100%; min-width: 0; border: 1px solid rgba(255,255,255,.13); border-radius: 9px; padding: 9px 10px; background: rgba(255,255,255,.055); color: #f4eff8; font: inherit; font-size: 12px; }
     .explorer-search input::placeholder { color: #8f8998; opacity: 1; }
     .explorer-search input:focus-visible { outline: 2px solid rgba(216, 200, 255, .9); outline-offset: 2px; }
-    .search-status { min-height: 14px; margin: 0; color: #817a89; font-size: 9px; line-height: 1.45; }
+    .search-status { margin: 0; color: #9a93a3; font-size: 9px; line-height: 1.45; }
+    .search-status:empty { display: none; }
     .search-results { display: grid; gap: 5px; }
     .search-results[hidden] { display: none; }
     .search-result { display: grid; grid-template-columns: minmax(0, 1fr) auto; gap: 3px 10px; width: 100%; padding: 9px 10px; text-align: left; }
@@ -119,9 +145,9 @@
       .warning-details { max-height: clamp(48px, calc(54vh - 220px), 240px); }
       .panel { top: auto; bottom: 14px; right: 14px; left: 14px; width: auto; max-height: 46vh; }
       .panel.is-collapsed { right: 14px; left: auto; width: 190px; }
-      .toolbar { right: 14px; left: 14px; bottom: 88px; gap: 5px; }
-      .toolbar button { min-height: 40px; padding-inline: 8px; }
+      .toolbar { right: 14px; left: 14px; bottom: 88px; flex-wrap: wrap; gap: 4px; }
+      .toolbar button { min-height: 40px; padding-inline: 6px; white-space: nowrap; }
       .panel:not(.is-collapsed) ~ .toolbar { bottom: calc(46vh + 28px); }
       .hint { display: none; }
     }
-    @media (prefers-reduced-motion: reduce) { .panel, summary::after { transition: none; } }
+    @media (prefers-reduced-motion: reduce) { summary::after { transition: none; } }

data/assets/styles/showcase.css

@@ -39,6 +39,9 @@
     @media (prefers-reduced-motion: reduce) {
       .cinema-annotation, .cinema-annotation::before, .cinema-annotation::after, .cinema-annotation-copy { transition: none; }
     }
+    /* Clip export drives annotation opacity per frame from a synthetic clock;
+       wall-clock CSS fades would make captured frames nondeterministic. */
+    html[data-rubylens-clip] .cinema-annotation, html[data-rubylens-clip] .cinema-annotation::before, html[data-rubylens-clip] .cinema-annotation::after, html[data-rubylens-clip] .cinema-annotation-copy { transition: none; }
     @media (max-width: 600px) {
       .galaxy-summary { font-size: 24px; }
       .showcase-status { max-width: 720px; font-size: 24px; }

data/lib/rubylens/art_model_builder.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "dependency_warning"
+require_relative "errors"
 require_relative "morphology_classifier"
 
 module RubyLens
@@ -15,6 +16,9 @@ module RubyLens
       random = Random.new(@seed)
       morphology = MorphologyClassifier.new(snapshot).call
       namespace_order = (0...snapshot.fetch("namespaces").length).to_a.shuffle(random: random)
+      namespace_index = Array.new(namespace_order.length)
+      namespace_order.each_with_index { |old_index, new_index| namespace_index[old_index] = new_index }
+      constant_reference_rows = valid_constant_reference_rows(snapshot)
       namespaces = namespace_order.map do |index|
         row = snapshot.fetch("namespaces").fetch(index)
         [random.rand(0..0xffff_ffff), *row]
@@ -26,7 +30,6 @@ module RubyLens
       package_morphologies = []
       packages = package_order.map do |old_index|
         package = snapshot.fetch("packages").fetch(old_index)
-        declaration_count = package.fetch("declaration_count")
         package_seed = random.rand(0..0xffff_ffff)
         package_morphology = MorphologyClassifier.new(package:, phase_seed: package_seed).call
         package_morphologies << [package_morphology.fetch("family"), *package_morphology.fetch("knobs")]
@@ -34,20 +37,37 @@ module RubyLens
           package_seed,
           package.fetch("role"),
           package.fetch("location"),
-          declaration_count,
+          package.fetch("declarations").length,
           *package.fetch("ruby_counts"),
           dependency_system_index.fetch(old_index, -1),
         ]
       end
       package_names = package_order.map { |old_index| snapshot.fetch("packages").fetch(old_index).fetch("name") }
-      indexed_dependency_count = snapshot.fetch("packages").sum do |package|
-        package.fetch("declaration_count")
+      dependency_offsets = []
+      dependency_count = 0
+      snapshot.fetch("packages").each do |package|
+        dependency_offsets << dependency_count
+        dependency_count += package.fetch("declarations").length
+      end
+      dependency_target_rows = {}.compare_by_identity
+      constant_reference_rows.each do |_referring_index, referenced_index|
+        dependency_ordinal = referenced_index - namespace_order.length
+        next if dependency_ordinal.negative? || dependency_ordinal >= dependency_count
+
+        next_package_index = dependency_offsets.bsearch_index { |offset| offset > dependency_ordinal }
+        old_package_index = (next_package_index || dependency_offsets.length) - 1
+        package = snapshot.fetch("packages").fetch(old_package_index)
+        local_index = dependency_ordinal - dependency_offsets.fetch(old_package_index)
+        dependency_target_rows[package.fetch("declarations").fetch(local_index)] = dependency_ordinal
       end
       dependencies = []
+      dependency_index = {}
       package_order.each do |old_index|
         package = snapshot.fetch("packages").fetch(old_index)
         declarations = package.fetch("declarations").sort.shuffle(random: random)
         declarations.each do |declaration|
+          original_ordinal = dependency_target_rows[declaration]
+          dependency_index[original_ordinal] = dependencies.length if original_ordinal
           dependencies << [
             random.rand(0..0xffff_ffff),
             package_index.fetch(old_index),
@@ -55,21 +75,25 @@ module RubyLens
           ]
         end
       end
+      constant_reference_links = build_constant_reference_links(
+        constant_reference_rows,
+        namespace_index,
+        dependency_index,
+      )
       {
-        "schema" => "rubylens.art.v10",
+        "schema" => "rubylens.art.v13",
         "projectName" => snapshot.fetch("project_name"),
-        "morphology" => morphology,
+        "morphology" => [morphology.fetch("family"), *morphology.fetch("knobs")],
         "totals" => {
           "namespaces" => namespaces.length,
           "packages" => packages.length,
-          "dependencyStars" => indexed_dependency_count,
-          "renderedDependencyStars" => dependencies.length,
+          "dependencyStars" => dependencies.length,
         },
         "domains" => signal_domains(namespaces, snapshot.fetch("dependency_signal_maxima")),
-        "componentCounts" => snapshot.fetch("components"),
         "categoryStats" => snapshot.fetch("category_stats"),
         "namespaceNames" => namespace_names,
         "namespaces" => namespaces,
+        "constantReferenceLinks" => constant_reference_links,
         "packageNames" => package_names,
         "packages" => packages,
         "packageMorphologies" => package_morphologies,
@@ -89,6 +113,34 @@ module RubyLens
 
     private
 
+    def valid_constant_reference_rows(snapshot)
+      rows = snapshot.fetch("constant_reference_links", [])
+      return [] unless rows.is_a?(Array)
+
+      rows.select do |row|
+        row.is_a?(Array) && row.length == 2 && row.all?(Integer) && row.none?(&:negative?)
+      end
+    end
+
+    def build_constant_reference_links(rows, namespace_index, dependency_index)
+      snapshot_namespace_count = namespace_index.length
+      candidates = rows.filter_map do |row|
+        referring_index, referenced_index = row
+        remapped_referring_index = namespace_index[referring_index]
+        remapped_referenced_index = if referenced_index < snapshot_namespace_count
+          namespace_index[referenced_index]
+        else
+          dependency = dependency_index[referenced_index - snapshot_namespace_count]
+          snapshot_namespace_count + dependency if dependency
+        end
+        next if remapped_referring_index.nil? || remapped_referenced_index.nil?
+
+        [remapped_referring_index, remapped_referenced_index]
+      end
+
+      candidates.shuffle(random: Random.new(@seed ^ 0xC057_A17E))
+    end
+
     def build_dependency_systems(snapshot, package_index)
       system_random = Random.new(@seed ^ 0xD3E5_157E)
       package_system_index = {}
@@ -105,7 +157,7 @@ module RubyLens
     end
 
     def signal_domains(namespaces, dependency_maxima)
-      namespace_columns = [4, 5, 6, 7, 8, 9]
+      namespace_columns = [3, 4, 5, 6, 7, 8]
       namespace_domains = namespace_columns.map { |column| maximum(namespaces, column) }
       SIGNAL_FIELDS.each_with_index.to_h do |field, index|
         [field, [namespace_domains[index], dependency_maxima[index]].max]

data/lib/rubylens/artifact_marker.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RubyLens
+  # Recognizes RubyLens's own artifacts by scanning the head of a file for a
+  # format marker, so default output paths are only ever replaced in kind.
+  module ArtifactMarker
+    HEAD_BYTES = 2048
+
+    module_function
+
+    def present?(path, marker, head_bytes: HEAD_BYTES)
+      File.file?(path) && File.open(path, "rb") { |file| file.read(head_bytes).to_s.include?(marker) }
+    rescue Errno::ENOENT, Errno::EACCES
+      false
+    end
+  end
+end

data/lib/rubylens/atomic_output.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "securerandom"
+
+module RubyLens
+  # Owner-only atomic replacement shared by every writer: outputs are staged in
+  # a 0600 temporary alongside the target and renamed into place, so a partial
+  # write never becomes visible and permissions never loosen mid-write.
+  module AtomicOutput
+    module_function
+
+    def replace(output)
+      output = File.expand_path(output)
+      FileUtils.mkdir_p(File.dirname(output), mode: 0o700)
+      temporary = File.join(File.dirname(output), ".#{File.basename(output)}.#{SecureRandom.hex(6)}.tmp")
+      File.open(temporary, File::WRONLY | File::CREAT | File::EXCL, 0o600).close
+      yield temporary
+      File.chmod(0o600, temporary)
+      File.rename(temporary, output)
+      File.chmod(0o600, output)
+      output
+    ensure
+      FileUtils.rm_f(temporary) if temporary && File.exist?(temporary)
+    end
+  end
+end

data/lib/rubylens/cli.rb

@@ -6,6 +6,35 @@ require_relative "../rubylens"
 
 module RubyLens
   class CLI
+    # One entry per generating command: everything that differs between
+    # report, showcase, and clip lives here, not in per-command methods.
+    COMMANDS = {
+      "report" => {
+        default_name: Generator::DEFAULT_REPORT_NAME,
+        generator: :generate_report,
+        warning: "RubyLens reports contain private codebase structure. Keep the output local unless you intend to share it.",
+        details_option: false,
+        output_kind: "HTML",
+        report_progress: false,
+      },
+      "clip" => {
+        default_name: ClipGenerator::DEFAULT_CLIP_NAME,
+        generator: :generate_clip,
+        warning: "RubyLens clips show the same picture as showcases: the project name plus the galaxy's shape and scale; --details adds aggregate statistics and selected Ruby and dependency names. Share them intentionally.",
+        details_option: true,
+        output_kind: "MP4",
+        report_progress: true,
+      },
+      "showcase" => {
+        default_name: ShowcaseGenerator::DEFAULT_SHOWCASE_NAME,
+        generator: :generate_showcase,
+        warning: "RubyLens showcases disclose the project name and visual codebase structure; --details also includes aggregate statistics and selected Ruby and dependency names. Share them intentionally.",
+        details_option: true,
+        output_kind: "HTML",
+        report_progress: false,
+      },
+    }.freeze
+
     def initialize(arguments)
       @arguments = arguments.dup
     end
@@ -15,8 +44,7 @@ module RubyLens
       command = arguments.shift
       return print_version if %w[-v --version version].include?(command)
       return print_help(0) if command.nil? || %w[-h --help help].include?(command)
-      return generate_report(arguments) if command == "report"
-      return generate_showcase(arguments) if command == "showcase"
+      return generate(command, arguments) if COMMANDS.key?(command)
 
       $stderr.puts "Unknown command: #{command}"
       print_help(2)
@@ -27,28 +55,8 @@ module RubyLens
 
     private
 
-    def generate_report(arguments)
-      generate_html(
-        arguments,
-        command: "report",
-        default_name: "rubylens-report.html",
-        generator: RubyLens.method(:generate_report),
-        warning: "RubyLens reports contain private codebase structure. Keep the output local unless you intend to share it.",
-      )
-    end
-
-    def generate_showcase(arguments)
-      generate_html(
-        arguments,
-        command: "showcase",
-        default_name: "rubylens-showcase.html",
-        generator: RubyLens.method(:generate_showcase),
-        warning: "RubyLens showcases disclose the project name and visual codebase structure; --details also includes aggregate statistics and selected Ruby and dependency names. Share them intentionally.",
-        details_option: true,
-      )
-    end
-
-    def generate_html(arguments, command:, default_name:, generator:, warning:, details_option: false)
+    def generate(command, arguments)
+      specification = COMMANDS.fetch(command)
       options = {}
       help = false
       parser = OptionParser.new do |option|
@@ -56,13 +64,13 @@ module RubyLens
         option.separator ""
         option.separator "TARGET defaults to the current working directory."
         option.separator ""
-        option.on("-o", "--output FILE", "Output HTML (default: TARGET/#{default_name})") do |value|
+        option.on("-o", "--output FILE", "Output #{specification.fetch(:output_kind)} (default: TARGET/#{specification.fetch(:default_name)})") do |value|
           options[:output] = value
         end
         option.on("--lockfile FILE", "Gemfile.lock used to select exact dependency versions") do |value|
           options[:lockfile] = value
         end
-        if details_option
+        if specification.fetch(:details_option)
           option.on("--details", "Include aggregate statistics and cinematic code/dependency labels") do
             options[:details] = true
           end
@@ -81,19 +89,27 @@ module RubyLens
       raise OptionParser::InvalidArgument, "unexpected argument: #{arguments.first}" unless arguments.empty?
 
       generator_options = { path: target, output: options[:output], lockfile: options[:lockfile] }
-      generator_options[:details] = options.fetch(:details, false) if details_option
-      result = generator.call(**generator_options)
+      generator_options[:details] = options.fetch(:details, false) if specification.fetch(:details_option)
+      generator_options[:progress] = progress_printer if specification.fetch(:report_progress)
+      result = RubyLens.public_send(specification.fetch(:generator), **generator_options)
       print_result(result)
-      $stderr.puts warning
+      $stderr.puts specification.fetch(:warning)
       0
     end
 
+    def progress_printer
+      last_step = -1
+      lambda do |rendered, total|
+        step = rendered * 10 / total
+        next unless step > last_step
+
+        last_step = step
+        $stderr.puts "Rendering clip: #{rendered * 100 / total}% (#{rendered}/#{total} frames)"
+      end
+    end
+
     def print_result(result)
-      $stdout.puts JSON.generate(
-        output: result.output_path,
-        counts: result.counts,
-        warnings: result.warnings,
-      )
+      $stdout.puts JSON.generate(result.to_payload)
     end
 
     def print_version
@@ -110,10 +126,11 @@ module RubyLens
 
         Commands:
           report [OPTIONS] [TARGET]     Generate a private, interactive galaxy report
-          showcase [OPTIONS] [TARGET]   Generate a shareable, cinematic galaxy showcase
+          clip [OPTIONS] [TARGET]       Generate a shareable galaxy video (MP4, needs Chrome + ffmpeg)
+          showcase [OPTIONS] [TARGET]   Generate a shareable, cinematic galaxy showcase page
           version                       Print the RubyLens version
 
-        Run `rubylens report --help` or `rubylens showcase --help` for options.
+        Run `rubylens report --help`, `rubylens clip --help`, or `rubylens showcase --help` for options.
       HELP
       status
     end