rubylens 0.1.0 → 0.2.1

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,94 +1,237 @@
 # frozen_string_literal: true
 
 require_relative "dependency_warning"
+require_relative "errors"
 require_relative "morphology_classifier"
 
 module RubyLens
   class ArtModelBuilder
+    SCHEMA = "rubylens.art.v13"
     SIGNAL_FIELDS = %w[ancestorDepth definitionSites reopenings descendants references members].freeze
+    # Namespace row columns carrying the six signals, aligned with SIGNAL_FIELDS.
+    NAMESPACE_SIGNAL_COLUMNS = (3..8).freeze
 
+    # `order` lists snapshot ordinals in draw order and is the single authority
+    # for each shuffle; the snapshot-ordinal-to-draw-position inverse is derived
+    # where it is needed rather than stored beside it.
+    Namespaces = Data.define(
+      :order, #: Array[Integer]
+      :rows, #: Array[Array[Integer]]
+      :names, #: Array[String]
+      :reference_rows, #: Array[[Integer, Integer]]
+    ) do
+      # Link endpoints past the namespace block address dependency stars, which
+      # the snapshot numbers from zero after the namespaces.
+      #
+      #: () -> Array[Integer]
+      def referenced_dependency_ordinals
+        reference_rows.map { |_referring_index, referenced_index| referenced_index - order.length }
+      end
+
+      #: () -> Array[Integer]
+      def draw_positions
+        positions = Array.new(order.length)
+        order.each_with_index { |old_index, new_index| positions[old_index] = new_index }
+        positions
+      end
+    end
+
+    Packages = Data.define(
+      :order, #: Array[Integer]
+      :rows, #: Array[Array[Integer]]
+      :names, #: Array[String]
+      :morphologies, #: Array[Array[Integer]]
+      :systems, #: Array[Array[Integer]]
+    )
+
+    # Unlike the other two, this index is not an inverse of any stored order:
+    # a dependency star's snapshot ordinal is only known for rows travel
+    # targets, and is captured as the shuffled rows are emitted.
+    Dependencies = Data.define(
+      :rows, #: Array[Array[Integer]]
+      :index, #: Hash[Integer, Integer]
+    )
+
+    #: (?seed: Integer) -> void
     def initialize(seed: 0x51A7_E11A)
       @seed = seed
     end
 
+    # Draw order is shuffled so neighbouring stars come from unrelated parts of
+    # the codebase: adjacent points would otherwise share a package or a name
+    # prefix and read as structure the galaxy does not mean to show. Every
+    # ordinal the snapshot used is therefore remapped onto the shuffled order.
+    #: (Hash[String, untyped]) -> Hash[String, untyped]
     def build(snapshot)
       random = Random.new(@seed)
-      morphology = MorphologyClassifier.new(snapshot).call
-      namespace_order = (0...snapshot.fetch("namespaces").length).to_a.shuffle(random: random)
-      namespaces = namespace_order.map do |index|
-        row = snapshot.fetch("namespaces").fetch(index)
-        [random.rand(0..0xffff_ffff), *row]
-      end
-      namespace_names = namespace_order.map { |index| snapshot.fetch("namespace_names").fetch(index) }
-      package_order = (0...snapshot.fetch("packages").length).to_a.shuffle(random: random)
-      package_index = package_order.each_with_index.to_h
-      dependency_systems, dependency_system_index = build_dependency_systems(snapshot, package_index)
-      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")]
+      namespaces = build_namespaces(snapshot, random)
+      packages = build_packages(snapshot, random)
+      dependencies = build_dependencies(snapshot, packages, namespaces, random)
+
+      {
+        "schema" => SCHEMA,
+        "projectName" => snapshot.fetch("project_name"),
+        "morphology" => morphology_row(MorphologyClassifier.new(snapshot).call),
+        "totals" => {
+          "namespaces" => namespaces.rows.length,
+          "packages" => packages.rows.length,
+          "dependencyStars" => dependencies.rows.length,
+        },
+        "domains" => signal_domains(namespaces.rows, snapshot.fetch("dependency_signal_maxima")),
+        "categoryStats" => snapshot.fetch("category_stats"),
+        "namespaceNames" => namespaces.names,
+        "namespaces" => namespaces.rows,
+        "constantReferenceLinks" => build_constant_reference_links(
+          namespaces.reference_rows,
+          namespaces.draw_positions,
+          dependencies.index,
+        ),
+        "packageNames" => packages.names,
+        "packages" => packages.rows,
+        "packageMorphologies" => packages.morphologies,
+        "dependencySystems" => packages.systems,
+        "dependencyStars" => dependencies.rows,
+        "dependencyWarnings" => allowed_dependency_warnings(snapshot),
+        "warningCounts" => snapshot.fetch("warning_counts"),
+      }
+    end
+
+    private
+
+    #: (Hash[String, untyped], Random) -> Namespaces
+    def build_namespaces(snapshot, random)
+      rows = snapshot.fetch("namespaces")
+      names = snapshot.fetch("namespace_names")
+      order = (0...rows.length).to_a.shuffle(random: random)
+      Namespaces.new(
+        order: order,
+        rows: order.map { |old_index| [random.rand(0..0xffff_ffff), *rows.fetch(old_index)] },
+        names: order.map { |old_index| names.fetch(old_index) },
+        reference_rows: valid_constant_reference_rows(snapshot),
+      )
+    end
+
+    #: (Hash[String, untyped], Random) -> Packages
+    def build_packages(snapshot, random)
+      snapshot_packages = snapshot.fetch("packages")
+      order = (0...snapshot_packages.length).to_a.shuffle(random: random)
+      systems, system_index = build_dependency_systems(snapshot, order.each_with_index.to_h)
+      morphologies = []
+
+      rows = order.map do |old_index|
+        package = snapshot_packages.fetch(old_index)
+        seed = random.rand(0..0xffff_ffff)
+        morphologies << morphology_row(MorphologyClassifier.new(package: package, phase_seed: seed).call)
         [
-          package_seed,
+          seed,
           package.fetch("role"),
           package.fetch("location"),
-          declaration_count,
+          package.fetch("declarations").length,
           *package.fetch("ruby_counts"),
-          dependency_system_index.fetch(old_index, -1),
+          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")
-      end
-      dependencies = []
-      package_order.each do |old_index|
+
+      Packages.new(
+        order: order,
+        rows: rows,
+        names: order.map { |old_index| snapshot_packages.fetch(old_index).fetch("name") },
+        morphologies: morphologies,
+        systems: systems,
+      )
+    end
+
+    # Dependency stars are emitted package by package in shuffled order, so a
+    # snapshot ordinal is only recoverable for the rows travel actually targets.
+    # Those rows are identified before the shuffle and tracked by object
+    # identity, since equal declaration rows are common and interchangeable.
+    #: (Hash[String, untyped], Packages, Namespaces, Random) -> Dependencies
+    def build_dependencies(snapshot, packages, namespaces, random)
+      targeted = travel_target_rows(snapshot, namespaces.referenced_dependency_ordinals)
+      rows = []
+      index = {}
+      packages.order.each_with_index do |old_index, new_index|
         package = snapshot.fetch("packages").fetch(old_index)
-        declarations = package.fetch("declarations").sort.shuffle(random: random)
-        declarations.each do |declaration|
-          dependencies << [
-            random.rand(0..0xffff_ffff),
-            package_index.fetch(old_index),
-            *declaration.drop(1),
-          ]
+        package.fetch("declarations").sort.shuffle(random: random).each do |declaration|
+          original_ordinal = targeted[declaration]
+          index[original_ordinal] = rows.length if original_ordinal
+          rows << [random.rand(0..0xffff_ffff), new_index, *declaration.drop(1)]
         end
       end
-      {
-        "schema" => "rubylens.art.v10",
-        "projectName" => snapshot.fetch("project_name"),
-        "morphology" => morphology,
-        "totals" => {
-          "namespaces" => namespaces.length,
-          "packages" => packages.length,
-          "dependencyStars" => indexed_dependency_count,
-          "renderedDependencyStars" => 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,
-        "packageNames" => package_names,
-        "packages" => packages,
-        "packageMorphologies" => package_morphologies,
-        "dependencySystems" => dependency_systems,
-        "dependencyStars" => dependencies,
-        "dependencyWarnings" => snapshot.fetch("dependency_warnings", []).filter_map do |warning|
-          name = warning.fetch("name")
-          reason = warning.fetch("reason")
-          next unless name.is_a?(String) && DependencyWarning::NAME_PATTERN.match?(name)
-          next unless reason.is_a?(String) && DependencyWarning::ALLOWED_REASONS.include?(reason)
-
-          { "name" => name, "reason" => reason }
-        end,
-        "warningCounts" => snapshot.fetch("warning_counts"),
-      }
+      Dependencies.new(rows: rows, index: index)
     end
 
-    private
+    #: (Hash[String, untyped], Array[Integer]) -> Hash[Array[Integer], Integer]
+    def travel_target_rows(snapshot, dependency_ordinals)
+      offsets = []
+      total = 0
+      snapshot.fetch("packages").each do |package|
+        offsets << total
+        total += package.fetch("declarations").length
+      end
+
+      targeted = {}.compare_by_identity
+      dependency_ordinals.each do |ordinal|
+        next if ordinal.negative? || ordinal >= total
 
+        next_package = offsets.bsearch_index { |offset| offset > ordinal }
+        package_index = (next_package || offsets.length) - 1
+        declarations = snapshot.fetch("packages").fetch(package_index).fetch("declarations")
+        targeted[declarations.fetch(ordinal - offsets.fetch(package_index))] = ordinal
+      end
+      targeted
+    end
+
+    #: (Hash[String, untyped]) -> Array[Integer]
+    def morphology_row(morphology)
+      [morphology.fetch("family"), *morphology.fetch("knobs")]
+    end
+
+    # Warnings reach the artifact only if they match the closed vocabulary, so a
+    # tampered snapshot cannot smuggle arbitrary text into a shareable page.
+    #: (Hash[String, untyped]) -> Array[Hash[String, String]]
+    def allowed_dependency_warnings(snapshot)
+      snapshot.fetch("dependency_warnings", []).filter_map do |warning|
+        name = warning.fetch("name")
+        reason = warning.fetch("reason")
+        next unless name.is_a?(String) && DependencyWarning::NAME_PATTERN.match?(name)
+        next unless reason.is_a?(String) && DependencyWarning::ALLOWED_REASONS.include?(reason)
+
+        { "name" => name, "reason" => reason }
+      end
+    end
+
+    #: (Hash[String, untyped]) -> Array[[Integer, Integer]]
+    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
+
+    #: (Array[[Integer, Integer]], Array[Integer], Hash[Integer, Integer]) -> Array[[Integer, Integer]]
+    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
+
+    #: (Hash[String, untyped], Hash[Integer, Integer]) -> [Array[Array[Integer]], Hash[Integer, Integer]]
     def build_dependency_systems(snapshot, package_index)
       system_random = Random.new(@seed ^ 0xD3E5_157E)
       package_system_index = {}
@@ -104,17 +247,16 @@ module RubyLens
       [systems, package_system_index]
     end
 
-    def signal_domains(namespaces, dependency_maxima)
-      namespace_columns = [4, 5, 6, 7, 8, 9]
-      namespace_domains = namespace_columns.map { |column| maximum(namespaces, column) }
+    # Each signal is scaled against the larger of its workspace and dependency
+    # maxima, so the two populations stay comparable in the same scene.
+    #: (Array[Array[Integer]], Array[Integer]) -> Hash[String, Integer]
+    def signal_domains(namespace_rows, dependency_maxima)
+      namespace_domains = NAMESPACE_SIGNAL_COLUMNS.map do |column|
+        namespace_rows.map { |row| row[column].to_i }.max || 0
+      end
       SIGNAL_FIELDS.each_with_index.to_h do |field, index|
         [field, [namespace_domains[index], dependency_maxima[index]].max]
       end
     end
-
-    def maximum(rows, column)
-      rows.map { |row| row[column].to_i }.max || 0
-    end
-
   end
 end

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