okf 1.11.0 → 1.13.0

data/lib/okf/render/graph/template.html.erb

@@ -50,7 +50,12 @@
  :root{
   --bg:#ffffff; --panel:#ffffff; --panel-2:#f6f7f8; --canvas:#f4f5f7; --ink:#1f2328; --ink-soft:#333333;
   --muted:#63697a; --faint:#9298a4; --line:#e6e8eb; --line-2:#eef0f2;
-  --accent:#e21e1e; --accent-ink:#c81a1a; --accent-soft:#fdecec; --edge:#cfd4db; --ok:#1a9e5f;
+  /* --edge was #cfd4db, which is 1.38:1 against the canvas — dark mode's
+     equivalent is 1.67:1, so light was always the weaker theme and anything
+     drawn *softer* than a plain edge fell off the cliff there first. #b9c0ca
+     brings it to 1.72:1, level with dark, and the cluster box borders that
+     share the token get the same benefit. */
+  --accent:#e21e1e; --accent-ink:#c81a1a; --accent-soft:#fdecec; --edge:#b9c0ca; --ok:#1a9e5f;
   --rail:#15171c; --rail-ink:#8b919c; --rail-ink-hi:#dfe2e7;
   --shadow:0 1px 2px rgba(20,24,33,.05),0 8px 24px rgba(20,24,33,.07);
  }
@@ -179,6 +184,26 @@
  .btn[aria-pressed=true]{color:var(--accent);border-color:var(--accent);background:var(--accent-soft)}
  .btn svg{width:16px;height:16px;stroke:currentColor;fill:none;stroke-width:1.7;stroke-linecap:round;stroke-linejoin:round}
  .btn[hidden]{display:none}
+ /* ── segmented control: one setting, every state on screen ──
+    Three .btn segments sharing one border, so the group reads as a single
+    control rather than three neighbours that happen to touch. `aria-checked`
+    carries the selection instead of `aria-pressed` — these are exclusive, and
+    a radio group is what a reader's screen reader should hear.
+    The segments are narrower than a standalone .btn (30 vs 34) so the whole
+    group lands near a single select's width instead of dwarfing the bar. */
+ .seg{display:inline-flex;flex:none;border:1px solid var(--line);border-radius:9px;background:var(--panel);overflow:hidden}
+ .seg .seg-b{width:32px;height:32px;border:0;border-radius:0;background:transparent}
+ /* Larger than a toolbar icon: these glyphs carry three beads and a span in the
+    space a normal icon uses for one shape, and at 16px the beads sank into the
+    line they sit on — the spine segment read as a bare dash. */
+ .seg .seg-b svg{width:19px;height:19px}
+ .seg .seg-b+.seg-b{border-left:1px solid var(--line)}
+ .seg .seg-b:hover{background:var(--panel-2);border-color:var(--line)}
+ .seg .seg-b[aria-checked=true]{color:var(--accent);background:var(--accent-soft)}
+ /* The focus ring goes on the segment, never on the group: outlining the whole
+    control put an accent border around all three at once, which reads as "this
+    setting is on" and competes with the fill that actually says so. */
+ .seg .seg-b:focus-visible{outline:2px solid var(--accent);outline-offset:-2px}
  .btn.text{width:auto;display:inline-flex;align-items:center;padding:0 12px;gap:7px;font-size:13px;font-weight:500;color:var(--ink)}
  /* `.btn.text` sets display, which outranks `.btn[hidden]` above at equal
     specificity — so hiding a text button (e.g. #fp-graph on a log) needs its own
@@ -780,9 +805,15 @@
   #app.controls-open #file-controls .combo{flex:1 1 44%;width:auto;min-width:130px}
   /* Wrapping by whatever happened to fit left one icon orphaned on a line of its
      own. The two controls carrying words take a column each, so the first line
-     is two even halves; the icon buttons then get a line to themselves and
-     spread across it. */
-  #app.controls-open #graph-controls{gap:8px}
+     is two even halves; the icon buttons then get a line to themselves.
+     Centred, because that line is the only one that does not fill the width —
+     Filters and the layout select are 50% each and reach both edges, so a
+     left-aligned icon row hung off the left with a pool of dead space to its
+     right, reading as a layout accident rather than a row. (`justify-content`
+     was simply never set: the comment here used to claim the icons spread
+     across the line, and they never did.) The first line is unaffected — its
+     two items already fill it, so there is no free space to distribute. */
+  #app.controls-open #graph-controls{gap:8px;justify-content:center}
   #app.controls-open #graph-controls>#btn-filters,
   #app.controls-open #graph-controls>.selwrap{flex:1 1 calc(50% - 4px);min-width:0}
   /* the select has to grow with its wrapper. Stretching only the wrapper left
@@ -914,6 +945,25 @@
      <svg viewBox="0 0 24 24"><rect x="9" y="3" width="6" height="5" rx="1.2"/><rect x="3" y="16" width="6" height="5" rx="1.2"/><rect x="15" y="16" width="6" height="5" rx="1.2"/><path d="M12 8v4M12 12H6v4M12 12h6v4"/></svg></button>
     <button class="btn" id="btn-ix" type="button" aria-label="Show indexes" aria-pressed="false" title="Draw the index.md map layer alongside the concepts">
      <svg viewBox="0 0 24 24"><path d="M4 5h16M4 9.6h10.5M4 14.2h16M4 18.8h7.5"/></svg></button>
+    <!-- How many links to draw. Three segments, each a miniature of what it does
+         to the graph: the same three concepts in the same places every time, and
+         only the wire between them changes — an extra span over the top, a single
+         line through, nothing.
+
+         The row is not an arbitrary arrangement. Three dots on one axis joined by
+         one stroke *is* a spine, so the middle segment depicts the word it means;
+         and because the dots never move, the eye reads the difference as wire
+         added or taken away rather than as three unrelated symbols. A triangle
+         was tried first and failed exactly there — dropping one of its edges
+         changes the shape (it reads as a "7") instead of reading as less. -->
+    <div class="seg" id="links" role="radiogroup" aria-label="How many links to draw">
+     <button class="btn seg-b" type="button" role="radio" data-links="all" aria-checked="true" title="All links — every link in the bundle">
+      <svg viewBox="0 0 24 24"><path d="M4 15h16M4 15q8-12 16 0"/><circle cx="4" cy="15" r="2.2" fill="currentColor" stroke="none"/><circle cx="12" cy="15" r="2.2" fill="currentColor" stroke="none"/><circle cx="20" cy="15" r="2.2" fill="currentColor" stroke="none"/></svg></button>
+     <button class="btn seg-b" type="button" role="radio" data-links="spine" aria-checked="false" title="Spine — each concept's strongest link, so nothing floats">
+      <svg viewBox="0 0 24 24"><path d="M4 15h16"/><circle cx="4" cy="15" r="2.2" fill="currentColor" stroke="none"/><circle cx="12" cy="15" r="2.2" fill="currentColor" stroke="none"/><circle cx="20" cy="15" r="2.2" fill="currentColor" stroke="none"/></svg></button>
+     <button class="btn seg-b" type="button" role="radio" data-links="none" aria-checked="false" title="No links — a concept's own appear when you select it">
+      <svg viewBox="0 0 24 24"><circle cx="4" cy="15" r="2.2" fill="currentColor" stroke="none"/><circle cx="12" cy="15" r="2.2" fill="currentColor" stroke="none"/><circle cx="20" cy="15" r="2.2" fill="currentColor" stroke="none"/></svg></button>
+    </div>
     <button class="btn" id="btn-panel" type="button" aria-label="Toggle inspector" aria-pressed="true"><svg viewBox="0 0 24 24"><rect x="3" y="4" width="18" height="16" rx="2"/><path d="M15 4v16"/></svg></button>
    </div>
    </div>
@@ -1152,6 +1202,11 @@
    real page in Chromium and fails on any error the page throws.
    ═════════════════════════════════════════════════════════════════════════ */
 const NODES=<%= nodes_json %>, EDGES=<%= edges_json %>, TYPES=<%= types_json %>, TAGS=<%= tags_json %>;
+/* Index-aligned with EDGES: the cut each link survives (OKF::Bundle::Skeleton).
+   Read once, at boot, to lay the graph out on its strongest links first — which
+   is earlier than any fetch could answer, and the whole reason it is inlined
+   rather than served from /skeleton with the arcs. */
+const EDGE_CUT=<%= edge_cuts_json %>;
 const NODE_ENDPOINT=<%= @node_endpoint.to_json %>, META_ENDPOINT=<%= @meta_endpoint.to_json %>;
 const BUNDLE=<%= name_json %>;
 const CATALOG_ENDPOINT="catalog",INDEX_ENDPOINT="index",LOG_ENDPOINT="log";
@@ -1249,8 +1304,12 @@ function styleSheet(){const ink=cvar('--ink'),halo=cvar('--canvas'),edge=cvar('-
   /* authorship still shows as form: a map nobody wrote is hollow and dashed */
   {selector:'node.ix-syn',style:{'background-color':cvar('--faint'),'background-opacity':.2,'color':cvar('--muted'),
    'border-width':1.5,'border-color':cvar('--faint'),'border-style':'dashed'}},
-  {selector:'edge.ixe',style:{'width':1,'opacity':.5,'line-style':'dashed','line-color':cvar('--edge'),'target-arrow-shape':'none'}},
-  {selector:'edge.ixe-syn',style:{'opacity':.3}},
+  /* A dash carries roughly half the ink of a solid line of the same weight, so
+     matching a plain edge's opacity is not the same as matching its presence —
+     these read fainter at equal numbers, and at .5 they were invisible in light
+     mode. They sit *above* a plain edge now (.85 vs .8) to land level with it. */
+  {selector:'edge.ixe',style:{'width':1.1,'opacity':.85,'line-style':'dashed','line-color':cvar('--edge'),'target-arrow-shape':'none'}},
+  {selector:'edge.ixe-syn',style:{'opacity':.55}},
   {selector:'edge.linkhid',style:{'display':'none'}},
   {selector:':parent',style:{'background-color':cvar('--ink'),'background-opacity':0.05,'border-width':1,'border-color':cvar('--edge'),'shape':'round-rectangle','padding':26,'label':'data(label)','color':cvar('--ink'),'font-size':13,'font-weight':600,'text-valign':'top','text-halign':'center','text-margin-y':-8,'min-zoomed-font-size':0,'text-outline-width':3,'text-outline-color':cvar('--canvas')}},
   /* ── state, last so it outranks every look above ──
@@ -1268,9 +1327,50 @@ function styleSheet(){const ink=cvar('--ink'),halo=cvar('--canvas'),edge=cvar('-
    a floor above the fitting zoom puts the whole picture out of reach, fit
    button included. relaxZoom() lowers it to follow anything bigger. */
 const MIN_ZOOM=.2;
+/* ── the first layout runs on the strongest links only ──
+   The boot layout is the wait on a big bundle, and it is the *edges* that make
+   it one. Measured on 414 concepts / 1829 links: cose takes 6.25s, of which
+   about 2.1s is the nodes and the rest is edges, near enough linearly.
+
+   Hiding edges does not help — it was the first thing tried, and it bought 0.5%,
+   because the layout runs over hidden elements just the same (it does help the
+   *paint*: a pan frame goes 20.7ms → 11.8ms, which is why the link layer still
+   hides rather than removes — an edge it took away has to come straight back
+   when a concept is selected). Removing them before the layout is what pays:
+   6.25s → 3.29s at half the edges.
+
+   So the first layout gets `EDGE_CUT[i]===0` — each concept's single strongest
+   link, per OKF::Bundle::Skeleton. That set is chosen rather than sampled, and
+   the property that makes it usable is that it *touches every linked concept*,
+   so nothing is left unplaced and the arrangement is a real one rather than a
+   sketch to be redone. The rest arrive on the next frame and no layout re-runs,
+   so nothing on screen moves — the reader sees the graph sooner and then sees
+   more lines in it, never a jump.
+
+   Only above BOOT_MIN_EDGES, where the saving is worth the extra path at all:
+   at 800 edges the edge share of the layout is under a second. */
+const BOOT_MIN_EDGES=800;
+/* Each edge carries its own cut, so the `spine` link setting is a comparison on
+   data the edge already holds rather than a lookup keyed on endpoints. Same
+   number, two readers: this split, and linkShown(). */
+const cutAt=(i)=>(EDGE_CUT&&EDGE_CUT.length===EDGES.length?EDGE_CUT[i]:0);
+const edgeEls=EDGES.map((e,i)=>({data:{source:e.source,target:e.target,cut:cutAt(i)}}));
+const bootSplit=(()=>{
+ if(!EDGE_CUT||EDGE_CUT.length!==EDGES.length||EDGES.length<=BOOT_MIN_EDGES)return {first:edgeEls,rest:[]};
+ const first=[],rest=[];
+ edgeEls.forEach(el=>(el.data.cut===0?first:rest).push(el));
+ return {first:first,rest:rest};})();
 const cy=cytoscape({container:document.getElementById('cy'),minZoom:MIN_ZOOM,maxZoom:1.6,wheelSensitivity:.2,
- elements:[...NODES.map(n=>({data:{id:n.id,title:n.title,c:color[typeOf[n.id]||'Untyped']||'#64748b',sz:szOf(n.id)}})),...EDGES.map(e=>({data:e}))],
+ elements:[...NODES.map(n=>({data:{id:n.id,title:n.title,c:color[typeOf[n.id]||'Untyped']||'#64748b',sz:szOf(n.id)}})),...bootSplit.first],
  style:styleSheet(),layout:{name:'<%= @layout %>',animate:false,nodeRepulsion:9000,idealEdgeLength:170,padding:40,nodeOverlap:24,avoidOverlap:true,spacingFactor:1.2,nodeDimensionsIncludeLabels:true}});
+/* Next frame, not next tick: the boot layout finished inside the constructor
+   above (animate:false), so the only thing still owed is a paint, and yielding
+   one frame is what buys the reader the early picture this whole split is for. */
+if(bootSplit.rest.length)requestAnimationFrame(()=>{
+ cy.batch(()=>cy.add(bootSplit.rest.map(el=>({group:'edges',data:el.data}))));
+ /* The late edges arrive after applyGraphFilter may already have run once, so
+    they would come back unfiltered — and under a narrowed link layer, visible. */
+ applyGraphFilter();});
 function applyCyTheme(){cy.style(styleSheet());}
 /* Debounced so the panel width transition (--side-w, .22s) fires cy.resize()
    once after it settles instead of on every frame — avoids canvas flicker. */
@@ -1505,6 +1605,11 @@ function focusNode(ele,opened){if(!ele||!ele.length)return;
     the state. (Outside cluster mode there are no :parent nodes, so this is a
     no-op there.) */
  cy.elements().removeClass('hl');cy.elements().not(':parent').addClass('dim');
+ /* With the link layer narrowed the arrows are hidden, so emphasis alone would
+    highlight a neighbourhood joined by nothing visible. Bring this node's own
+    links back first — the selection is exactly the moment they stop being
+    noise and become the answer to something. */
+ linkReveal(ele);
  ele.closedNeighborhood().removeClass('dim');ele.addClass('hl');
  centerOn(ele,opened);}
 function select(id){const ele=cy.getElementById(id);if(!ele.length)return;const opened=show(id);
@@ -1556,6 +1661,7 @@ function applyGraphFilter(){const s=q.graph.toLowerCase();const ids=ftMatch(q.gr
     re-runs: the visible set only shrinks, and every survivor is already laid. */
  if(clustered&&clusterLaid&&cy.nodes(':visible').some(n=>!n.isParent()&&!clusterLaid.has(n.id())))clusterLayout();
  ixVisibility();
+ linkVisibility();
  relaxZoom();
  bridgeSync();}
 function fbadge(){const c=activeTypes.size+activeTags.size+activeDirs.size;const b=document.getElementById('btn-filters');
@@ -1885,6 +1991,104 @@ function openMapInGraph(dir){setView('graph');showDir(dir);
     chose survives, and the map is emphasised exactly as a concept would be. */
  setIxNodes(true).then(()=>focusNode(cy.getElementById(IX+dir),true));}
 
+/* ── the link layer: how many arrows to draw ─────────────────────────────────
+   A dense bundle is unreadable because of its *arrows*, not its dots. Measured
+   on a 47-concept bundle: 227 links over 47 concepts, three quarters of them
+   crossing a directory boundary, at an average degree of 9.7 — every dot in a
+   thicket, and no amount of moving them apart fixes that.
+
+   Three settings, because there are three honest amounts of wiring:
+
+     all     the graph as authored. 227 arrows.
+     spine   each concept's single strongest link — the backbone Ruby already
+             computed (OKF::Bundle::Skeleton, the `keep_at === 0` set, inlined
+             as EDGE_CUT). 50 arrows on that bundle, 476 of 1829 on a
+             414-concept one: about one line per concept, which is tree
+             density. It is chosen rather than sampled, and the property that
+             earns it the name is that it *touches every linked concept*, so
+             nothing is left floating.
+     none    no arrows at all. The cleanest picture and the fastest to paint.
+
+   In every setting, selecting a concept reveals that concept's own links in
+   full. The wiring was never the answer to a standing question — "what is in
+   this bundle and how is it organised" is what a reader arrives with, and 227
+   lines were drowning it — but it is exactly the answer to "what does *this*
+   connect to", asked one concept at a time.
+
+   This layer only ever hides edges. It composes with cluster, file-tree and the
+   index layer rather than excluding them, which is the whole point: `--map` is
+   nothing but this set to `none` with the boxes on, and other combinations are
+   just as reachable. */
+/* The layer opens on `all`, unless the graph is dense enough that its arrows are
+   a thicket — then it opens on its spine (each concept's strongest link, the
+   backbone the boot split already lays out on). Density is undirected degree,
+   the measure this whole read is written in: the bundle that drove it ran 9.7, a
+   tree runs about 2, and THICKET_DEGREE sits between so a graph a reader can
+   already take in is left on `all`. Decided *here*, before the cytoscape() boot
+   frame reads linkMode, so a split bundle lays out on its spine and reveals it
+   without ever flashing the full set. `--map` overrides this to `none` below —
+   an explicit request outranks the heuristic. */
+const THICKET_DEGREE=6;
+const denseGraph=!!EDGE_CUT&&EDGE_CUT.length===EDGES.length&&NODES.length>0&&(2*EDGES.length/NODES.length)>=THICKET_DEGREE;
+let linkMode=(denseGraph&&!<%= map_json %>)?'spine':'all';
+const linksSeg=document.getElementById('links');
+const linkBtns=[ ...linksSeg.querySelectorAll('[data-links]') ];
+/* The markup checks `all`; if density opened us elsewhere, move the check to
+   match before the reader sees it. */
+if(linkMode!=='all')linkBtns.forEach(b=>b.setAttribute('aria-checked',String(b.dataset.links===linkMode)));
+
+/* Every edge that is a *link*. The structural ones (`tree` in file-tree mode,
+   `ixe` under the index layer) are somebody else's picture, never this one's
+   noise, so they are never touched. */
+const linkEdges=()=>cy.edges().not('.tree').not('.ixe');
+/* Which edges this setting draws. `cut` rides on each edge's own data (see the
+   cytoscape() call), so the spine is a comparison and never a lookup. */
+const linkShown=(e)=>linkMode==='all'||(linkMode==='spine'&&e.data('cut')===0);
+function linkVisibility(){if(treeMode)return;
+ linkEdges().forEach(e=>e.toggleClass('linkhid',!linkShown(e)));}
+/* The selected concept's arrows, in full, whatever the setting. Called from
+   focusNode so it rides the gesture the reader already makes rather than
+   adding one of its own. */
+function linkReveal(ele){if(linkMode==='all')return;
+ linkVisibility();
+ if(ele&&ele.length)ele.connectedEdges().not('.tree').not('.ixe').removeClass('linkhid');}
+
+function setLinks(mode){if(mode===linkMode)return;
+ linkMode=mode;
+ linkBtns.forEach(b=>b.setAttribute('aria-checked',String(b.dataset.links===mode)));
+ if(mode==='all')cy.edges().removeClass('linkhid');else linkVisibility();}
+linkBtns.forEach(b=>{b.onclick=()=>setLinks(b.dataset.links);});
+/* Arrow keys move within a radio group — that is the contract `role=radiogroup`
+   makes, and a group that only answers to clicks has made a promise it does not
+   keep. Tab still enters and leaves the group as one stop. */
+linksSeg.onkeydown=e=>{const i=linkBtns.indexOf(document.activeElement);if(i<0)return;
+ const d=e.key==='ArrowRight'||e.key==='ArrowDown'?1:e.key==='ArrowLeft'||e.key==='ArrowUp'?-1:0;
+ if(!d)return;
+ e.preventDefault();
+ const next=linkBtns[(i+d+linkBtns.length)%linkBtns.length];
+ next.focus();setLinks(next.dataset.links);};
+/* `okf server --map` / `okf render --map` open here: no arrows, and the
+   directories boxed. Not a mode of its own — a *starting point* made of two
+   ordinary controls, both of which the reader can move afterwards. Either half
+   alone is half a picture: arrows off without boxes leaves a scatter of dots
+   with nothing to read them against, and boxes with every arrow is the thicket
+   this began with.
+
+   Deferred a frame, and not for tidiness: setClustered reaches ensureLayout and
+   state declared elsewhere in this script. An inline call hit a binding in its
+   temporal dead zone once already, and the ReferenceError took every top-level
+   statement after this line with it — the page came up looking almost right,
+   with the palette, the keyboard map and the boot fit all silently unbound. A
+   frame is enough: the script has finished by then. */
+/* A dense graph opened on its spine at boot (see linkMode above); the hiding
+   itself still has to run once. A *split* bundle got it for free — the boot
+   rAF's applyGraphFilter already ran linkVisibility under the spine mode. A
+   bundle under the split floor did not, so apply it here, on the same deferred
+   frame and for the same TDZ reason. --map wins and needs no separate spine
+   pass: `none` hides strictly more. */
+if(<%= map_json %>)requestAnimationFrame(()=>{setLinks('none');setClustered(true);});
+else if(denseGraph)requestAnimationFrame(linkVisibility);
+
 /* ── fit to screen ── */
 // cy.animate({fit:…}) is a no-op in this Cytoscape build, so compute the target
 // zoom + pan and animate those (which do work): fits the visible nodes, re-centered.

data/lib/okf/render/graph.rb

@@ -45,8 +45,10 @@ module OKF
       # `okf render`: the whole page as one self-contained file, the bundle baked
       # in, so it hosts where no server answers a fetch. Takes any bundle handle
       # (an OKF::Bundle::Folder) and returns the HTML string.
-      def self.static(folder, title: nil, link: nil, layout: "cose")
-        new(folder.graph(minimal: true), title: title || folder.name, link: link, layout: layout, embed: payload(folder)).render
+      def self.static(folder, title: nil, link: nil, layout: "cose", map: false)
+        graph = folder.graph(minimal: true)
+        new(graph, title: title || folder.name, link: link, layout: layout, embed: payload(folder),
+          cuts: folder.skeleton.cuts_for(graph.edges), map: map).render
       end
 
       # What the baked page carries in place of the endpoints a live server would
@@ -73,10 +75,17 @@ module OKF
       # default — injects an empty SIBLINGS, so the switcher never appears in a
       # single bundle or a static file. +search_endpoint+ rides along with them:
       # the hub's cross-bundle /search, which only a hub can answer.
+      # +cuts+ is one integer per edge, in @graph.edges order: the cut that edge
+      # survives (OKF::Bundle::Skeleton). It rides inline rather than being
+      # fetched because its only consumer needs it *before* the first layout
+      # runs, which is earlier than any request could answer. nil is allowed and
+      # simply turns the reduced first layout off.
       def initialize(graph, title: nil, link: nil, layout: "cose", node_endpoint: "node", meta_endpoint: "node/meta", embed: nil,
                      siblings: nil, self_slug: nil, hub_path: nil, search_endpoint: nil,
-                     manage_root: nil, manage_token: nil)
+                     manage_root: nil, manage_token: nil, cuts: nil, map: false)
         @graph = graph
+        @cuts = cuts
+        @map = map
         @title = title
         @link = link
         @layout = layout
@@ -133,6 +142,21 @@ module OKF
         json_for_script(@graph.edges)
       end
 
+      # Index-aligned with EDGES: `EDGE_CUT[i]` is the cut `EDGES[i]` survives.
+      # An array of small integers rather than a keyed map, because keying it by
+      # "source target" would cost more bytes than the edge list it annotates.
+      def edge_cuts_json
+        json_for_script(@cuts)
+      end
+
+      # Whether the page opens in the Map view — every concept, boxed by the
+      # directory it lives in, with the cross-links undrawn until one is
+      # selected. A boot state rather than a different page: the toggle is the
+      # same one the reader can press, so `--map` only decides where they start.
+      def map_json
+        json_for_script(@map ? true : false)
+      end
+
       # { type => [id, …] } — the client builds an id→type map for node colour.
       def types_json
         json_for_script(@graph.type_index)

data/lib/okf/safe_read.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "path"
+
+module OKF
+  # Shell-side containment for reads. `Path.under?` is the pure decision; the
+  # `File.realpath` that feeds it is disk I/O, so it lives here, out of the pure
+  # core. Every byte a bundle serves is read through this one primitive — the
+  # Reader's bulk load, `Concept::File`, the live `log.md` re-read, the MCP
+  # shell's concept and index reads — so a symlink whose name sits inside the
+  # root but whose target does not is refused in exactly one place. A read that
+  # rolled its own check could quietly drift and reopen the escape; there is
+  # nothing to drift from here.
+  #
+  # Scope. This closes the escape a *symlink* opens — the one a bundle can carry
+  # through a git clone, a copy or a tarball, which is the portable, adversarial
+  # case (a shared bundle whose author points a link at your secrets). It does
+  # not close a *hardlink*: File.realpath cannot resolve one (a hardlink shares
+  # its target's inode and keeps its own in-root path), and the obvious guard —
+  # rejecting st_nlink > 1 — would break a bundle on a deduplicating filesystem
+  # (a Nix store, some CI caches) where ordinary files legitimately share links.
+  # A hardlink to an outside file requires local write access to the served
+  # directory on the target's own filesystem, and cannot survive being copied,
+  # so it is a narrower, non-portable threat left deliberately out of scope.
+  module SafeRead
+    module_function
+
+    # The file's real, symlink-resolved location, or Path::Error if it escapes
+    # +root+. Pass +real_root+ when resolving many paths under one root (the
+    # Reader's loop) so the root is resolved once, not per file.
+    def contained_path!(root, path, real_root: nil)
+      real = ::File.realpath(path)
+      real_root ||= ::File.realpath(root)
+      raise Path::Error, "symlink target escapes bundle root" unless Path.under?(real_root, real)
+
+      real
+    end
+
+    # +path+'s bytes, read from its *resolved* location — so a symlink swapped in
+    # anywhere but the final component is caught, since the resolved path has no
+    # links left to follow — and refused if it escapes. The microscopic window
+    # between resolving and opening the leaf is not closed here (that needs an
+    # open-by-descriptor the 2.4 stdlib does not lend itself to); reading the
+    # resolved path is strictly better than reading the caller's raw name, which
+    # re-followed every link on every read.
+    def read!(root, path, real_root: nil, encoding: "UTF-8")
+      ::File.read(contained_path!(root, path, real_root: real_root), encoding: encoding)
+    end
+  end
+end

data/lib/okf/server/app.rb

@@ -21,7 +21,7 @@ module OKF
     #   GET /node/meta?id=… its description, as an escaped HTML fragment
     #   GET /catalog        rich per-concept metadata for the catalog/files/stats
     #                       views: { concepts: [ {id, title, type, description,
-    #                       tags, timestamp, status, area, dir, links_*} ] } (JSON)
+    #                       tags, timestamp, status, top_dir, dir, links_*} ] } (JSON)
     #   GET /tags           the tag index  { tag  => [id, …] } (JSON)
     #   GET /types          the type index { type => [id, …] } (JSON)
     #   GET /index          the §6 progressive-disclosure map for the Index panel:
@@ -82,11 +82,12 @@ module OKF
       # default would have pointed its palette at the host's root instead. The
       # route answers either way — advertising it is the caller's call.
       def initialize(folder, title: nil, link: nil, layout: "cose", siblings: nil, self_slug: nil, hub_path: nil,
-                     search_endpoint: nil, manage_root: nil, manage_token: nil)
+                     search_endpoint: nil, manage_root: nil, manage_token: nil, map: false)
         @folder = folder
         @title = title
         @link = link
         @layout = layout
+        @map = map
         @siblings = siblings
         @self_slug = self_slug
         @hub_path = hub_path
@@ -156,11 +157,20 @@ module OKF
         { logs: @folder.log_entries }
       end
 
+      # Only one thing is read off it here — #cuts_for, the per-link cut the page
+      # lays a large bundle out on. No endpoint serves it: the page needs those
+      # numbers before its first layout, which is earlier than a request could
+      # answer, so they ride inline with the graph instead. Built over the boot
+      # snapshot and held, like the graph itself.
+      def skeleton
+        @skeleton ||= @folder.skeleton
+      end
+
       def page
         @page ||= OKF::Render::Graph.new(
           graph, title: @title || @folder.name, link: @link, layout: @layout,
           siblings: @siblings, self_slug: @self_slug, hub_path: @hub_path, search_endpoint: @search_endpoint,
-          manage_root: @manage_root, manage_token: @manage_token
+          manage_root: @manage_root, manage_token: @manage_token, cuts: skeleton.cuts_for(graph.edges), map: @map
         ).render
       end
 

data/lib/okf/server/hub.rb

@@ -158,12 +158,13 @@ module OKF
       # is refused outright with no flag that says otherwise — `--bind 0.0.0.0`
       # turns a personal tool into a public one, and the write surface does not
       # follow it there at all.
-      def initialize(bundles, layout: "cose", registry: nil, writable: false)
+      def initialize(bundles, layout: "cose", registry: nil, writable: false, map: false)
         @bundles = bundles
         @default = bundles.first
         @boot_registry = registry
         @layout = layout
         @writable = writable
+        @map = map
         @apps = build_apps(layout)
       end
 
@@ -252,7 +253,7 @@ module OKF
       end
 
       def apply(verb, params)
-        registry = OKF::Registry.new(@boot_registry.path)
+        registry = @boot_registry.reopen
         message = mutate(verb, registry, params)
         reload(registry)
         json("ok" => true, "message" => message)
@@ -448,6 +449,7 @@ module OKF
             bundle.folder,
             title: bundle.title,
             layout: layout,
+            map: @map,
             siblings: siblings_of(bundle),
             self_slug: bundle.slug,
             hub_path: "/",
@@ -593,7 +595,7 @@ module OKF
       # `okf registry rename` in another terminal shows on the next refresh
       # instead of waiting for a restart.
       def registry
-        @boot_registry && OKF::Registry.new(@boot_registry.path)
+        @boot_registry&.reopen
       end
 
       # ok / warn / error, with the word that carries the same message for a

data/lib/okf/skill/SKILL.md

@@ -136,7 +136,11 @@ ambiguous, ask.
 **Which target?** A leading `@` is a *registry ref*, not a path: `@slug` names a
 bundle registered with `okf registry set`, bare `@` the default — route it
 straight to `okf <verb> @slug` and skip the directory hunt (`okf search` spans
-several: `@a @b`, or `@all`). A plain path is used as given. Given no target and a
+several: `@a @b`, or `@all`). A `@slug` may instead name a **group** — a saved set
+of bundles (`okf registry group backend @a @b`, members nest); it resolves like
+any ref for the two set-taking verbs (`okf search @backend`, `okf server
+@backend`) and every single-bundle verb refuses it with exit 2, the message
+saying which two take a group. A plain path is used as given. Given no target and a
 cwd that carries no bundle, `okf registry list` is the next move, not a hunt
 across sibling directories. Producing a *new* bundle with no path? Default to
 `.okf/` at the repo root, but first detect whether the project already keeps its

data/lib/okf/skill/playbooks/menu.md

@@ -35,7 +35,8 @@ is the lede.
      to close.
    - **clean, but the shape strains** — one area dwarfing the rest in
      `okf stats`, tags spread thin across dirs in `okf tags --by dir`, hubs
-     whose inbound links are mostly foreign in `okf graph --hubs` → offer
+     whose inbound links are mostly foreign in `okf graph --hubs`, a directory
+     with almost no internal traffic in `okf graph --traffic` → offer
      **`refine`** (evidence-driven restructuring; it proposes before it
      touches anything).
 4. **Freshness is off by default.** If the bundle carries timestamps, note that a

data/lib/okf/skill/playbooks/refine.md

@@ -32,6 +32,12 @@ alarm, never the objective. <!-- rule:okf-cohesion-over-balance -->
      (the directories are right); one spread across areas names a *concern*.
    - `okf graph <dir> --hubs` — concepts ranked by inbound links, each with
      the areas those links come from: the **origin test** for every hub.
+   - `okf graph <dir> --traffic` — the same question one level up. Every
+     directory's link traffic split three ways (internal / out / in) with the
+     **cohesion** ratio, and the weighted arcs between directories. `--hubs`
+     measures concepts; step 3 decides about *directories*, and this is the
+     only read at that grain. Rows lead with the lowest cohesion, so the
+     directories with a case to answer are at the top.
 3. **Diagnose — you are the judgment.** The measurements are evidence, never
    verdicts:
    - **Concerns never become containers.** A directory built around a spread
@@ -43,6 +49,26 @@ alarm, never the objective. <!-- rule:okf-cohesion-over-balance -->
      exclusive, and roughly comparable in size. And small is not merge-worthy
      on its own — a two-concept area that is a genuinely distinct domain
      stays. <!-- rule:okf-directory-prunes -->
+   - **Cohesion discriminates the low rows, which are the ones the view floats
+     to the top.** High cohesion sorts to the bottom and means the directory
+     holds together — the shape the tree exists to express, nothing to do. The
+     rows that need reading are the near-zero ones, and two shapes land there
+     together. Heavy *outbound* with almost nothing coming back is the finding: a
+     directory that points at the bundle rather than holding a part of it is
+     behaving like a projection, and this playbook's own frame says a projection
+     rides an `index.md` or a tag, never a directory — ask what would be lost if
+     its concepts moved to the areas they point at and its listing became a map.
+     Heavy *inbound* with nothing outbound is its benign twin, a **shared
+     vocabulary**: everyone cites it, it cites nobody, a reference area doing its
+     job, not a mis-homing. Same low number, opposite verdicts — the direction of
+     the traffic is which one you are looking at.
+     <!-- rule:okf-cohesion-reads-the-container -->
+     Two cautions, both of which will otherwise generate false findings. A
+     directory holding one or two concepts has too little traffic for a ratio
+     to mean anything — read the raw counts, not the percentage. And in a
+     design bundle the central `decisions/` will read low for exactly the
+     reason its concepts fail the hub origin test: that is centrality, and the
+     measurement is confirming the bundle works, not that it is broken.
    - **The hub origin test.** Inbound majority from the hub's own area:
      well-homed, leave it. A dominant *foreign* area: that area is the better
      home. Foreign majority with *no* dominant area: a shared primitive — the