figdown 0.1.5 → 0.1.7

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "figdown",
   "displayName": "FigDown",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Figures as text: create and maintain documentation figures as FigDown .fd sources with deterministic SVG artifacts embedded in Markdown — block diagrams, topologies, flowcharts, bit-level layouts, tables, timing waveforms.",
   "author": {
     "name": "FigDown",

package/dist/figdown.js

@@ -1,4 +1,4 @@
-// figdown.js — FigDown embeddable library (0.1.5)
+// figdown.js — FigDown embeddable library (0.1.7)
 // GENERATED FILE, DO NOT EDIT. Built from editor/figdown.html.
 // Regenerate with: node tools/make-lib.js
 (function (root, factory) {
@@ -10,7 +10,7 @@
   }
 }(typeof globalThis !== 'undefined' ? globalThis : this, function () {
   'use strict';
-var VERSION = "0.1.5";
+var VERSION = "0.1.7";
 
 // ---- engine (extracted verbatim from editor/figdown.html) ----
 var __engine = (function () {
@@ -24,7 +24,7 @@ const SHAPES = ['box','rounded','circle','ellipse','diamond','cylinder'];
 // input to that promise, and under core §13 a 0.x renderer may differ from
 // the next — which makes the recorded version the only thing that can
 // explain a diff between two renderings of one source.
-const FIGDOWN_VERSION = '0.1.5';
+const FIGDOWN_VERSION = '0.1.7';
 // Retired shape VALUES keep a named diagnostic (PROCESS §5(d)), the same way
 // retired option keys do: `cloud` was the one value that named a domain
 // (the internet cloud) in an enum the language keeps purely geometric
@@ -3112,6 +3112,45 @@ function renderScene(doc,y0){
     const halo=' paint-order="stroke" stroke="#fff" stroke-width="3"';
     const seg=(p,q,t,lbl,fs)=>reqLabel({p,q,t0:t,text:lbl,fs,col:ecol,halo,e,A,B,kind:'end'});
     if(isBack.has(e)&&!pinned(e.a)&&!pinned(e.b)){
+      // ── ROUTING-CHANGE ARCHITECTURE NOTE ──────────
+      // Edge labels are DEFERRED: every label is registered against its
+      // FINAL segment geometry (reqLabel/lblReq above) and placed by ONE
+      // greedy pass after all edges are drawn; arrowheads are computed from
+      // final terminal points (arrowTri). Therefore a routing change made
+      // HERE — upstream of reqLabel/noteSegs/arrowTri — gets label and
+      // arrowhead re-placement for free. A change spliced into the emitted
+      // SVG downstream, or made outside the engine, will strand both.
+      // Two prototype rounds re-derived this the hard way (floating
+      // arrowheads, orphaned labels): that was external splicing, not an
+      // engine gap. Patch routing here; do not "fix" the label machinery.
+      if(A===B){
+        // Self-transition: a small side loop on the node, the
+        // convention of every drawing tool — never a lap of the figure
+        // through the back-edge channel. Side order r,l,b,t; first side
+        // whose loop box overlaps no other node wins (deterministic).
+        const scy=A.y+A.h/2, scx=A.x+A.w/2;
+        const mkLoop=sd=>sd==='r'?[[A.x+A.w,scy-8],[A.x+A.w+20,scy-8],[A.x+A.w+20,scy+8],[A.x+A.w,scy+8]]
+          :sd==='l'?[[A.x,scy-8],[A.x-20,scy-8],[A.x-20,scy+8],[A.x,scy+8]]
+          :sd==='b'?[[scx-8,A.y+A.h],[scx-8,A.y+A.h+20],[scx+8,A.y+A.h+20],[scx+8,A.y+A.h]]
+          :[[scx-8,A.y],[scx-8,A.y-20],[scx+8,A.y-20],[scx+8,A.y]];
+        const loopHit=pp=>{
+          const x0=Math.min(...pp.map(p=>p[0]))-2, x1=Math.max(...pp.map(p=>p[0]))+2;
+          const z0=Math.min(...pp.map(p=>p[1]))-2, z1=Math.max(...pp.map(p=>p[1]))+2;
+          return nodes.some(n=>n!==A&&!n.boundary&&n.x<x1&&n.x+n.w>x0&&n.y<z1&&n.y+n.h>z0);
+        };
+        let sp=null;
+        for(const sd of ['r','l','b','t']){ const pp=mkLoop(sd); if(!loopHit(pp)){ sp=pp; break; } }
+        if(!sp) sp=mkLoop('r');
+        for(const p of sp){ W=Math.max(W,p[0]+4); Hh=Math.max(Hh,p[1]+16-y0-20); }
+        esvg.push('<path data-edge="'+e.line+'" d="'+roundPath(sp)+'" fill="none" stroke="'+col+'" stroke-width="1.6"'+dash+'/>');
+        noteSegs(e,sp);
+        if(e.mid) reqLabel({p:sp[1],q:sp[2],text:e.mid,fs:11,col:lcol,halo,e,A,B,kind:'mid',first:false});
+        if(e.tail) seg(sp[0],sp[1],0.5,e.tail,10);
+        if(e.head) seg(sp[3],sp[2],0.5,e.head,10);
+        if(wantsStart) arrowTri(sp[0],sp[1],col);
+        if(wantsEnd)   arrowTri(sp[sp.length-1],sp[sp.length-2],col);
+        continue;
+      }
       // back-edge (retry loop): polyline through a side channel beyond the
       // occupied lanes instead of a straight line hidden under the spine,
       // using the nested slot from the channel plan. Ring-eligible loops
@@ -3238,6 +3277,50 @@ function renderScene(doc,y0){
       // their neighbours turns a 40-point staircase into the 2–4 bends a
       // dummy-vertex chain should have, without moving the drawn line.
       simplifyPts(pts);
+      // Waypoint prune: after collinear simplification a
+      // chain can still carry a staircase of near-collinear jogs — the drift
+      // clamp allows only a few px of sideways movement per rank, so a run
+      // that wants to move 35px sideways alternates short diagonals and
+      // verticals that Douglas-Peucker cannot collapse (each angle differs).
+      // The rule: an interior waypoint SURVIVES only if removing it would
+      // make the edge pierce something. Obstacles are the same set the
+      // straight-edge router uses below: non-incident nodes, plus group
+      // boxes when NEITHER endpoint lies inside (a run through a group
+      // interior asserts membership the figure does not declare). Fixed
+      // left-to-right scan to fixpoint — deterministic. Endpoints are then
+      // re-derived so the edge leaves its node facing the first bend, and
+      // each re-derived terminal segment is re-checked: if it would hit an
+      // obstacle the old endpoint stays.
+      {
+        const pobs=nodes.filter(n=>n!==A&&n!==B&&!n.boundary).map(n=>({x:n.x,y:n.y,w:n.w,h:n.h}));
+        const ep0=pts[0], ep1=pts[pts.length-1];
+        for(const k in gBox){
+          const b=gBox[k];
+          const inG=(px,py)=>px>b.x0&&px<b.x1&&py>b.yA&&py<b.yB;
+          if(!inG(ep0[0],ep0[1])&&!inG(ep1[0],ep1[1]))
+            pobs.push({x:b.x0,y:b.yA,w:b.x1-b.x0,h:b.yB-b.yA});
+        }
+        let ch=true, pruned=false;
+        while(ch){ ch=false;
+          for(let i=1;i+1<pts.length;i++)
+            if(!segHitsObs(pts[i-1],pts[i+1],pobs)){ pts.splice(i,1); ch=true; pruned=true; i--; }
+        }
+        // untouched chains stay byte-identical: endpoints and the label
+        // segment are only re-derived when the prune removed a waypoint
+        if(pruned){
+        const nb0=borderPoint(A,pts[1][0],pts[1][1]);
+        if(!segHitsObs(nb0,pts[1],pobs)) pts[0]=nb0;
+        const nb1=borderPoint(B,pts[pts.length-2][0],pts[pts.length-2][1]);
+        if(!segHitsObs(nb1,pts[pts.length-2],pobs)) pts[pts.length-1]=nb1;
+        if(midSeg){ let bi=0,bl=-1;
+          for(let i=0;i+1<pts.length;i++){
+            const l=Math.hypot(pts[i+1][0]-pts[i][0],pts[i+1][1]-pts[i][1]);
+            if(l>bl){ bl=l; bi=i; }
+          }
+          midSeg=[pts[bi],pts[bi+1]];
+        }
+        }
+      }
       esvg.push('<path data-edge="'+e.line+'" d="'+roundPath(pts)+'" fill="none" stroke="'+col+'" stroke-width="1.6"'+dash+'/>');
       noteSegs(e,pts);
       if(midSeg) reqLabel({p:midSeg[0],q:midSeg[1],text:e.mid,fs:11,col:lcol,halo,e,A,B,kind:'mid',first:false});
@@ -3585,6 +3668,89 @@ function routeAround(p,q,obs){
   return pts.length>2?pts:null;
 }
 
+// ---- shared-edge grid (0.1.6) ----
+// A boundary between two cells belongs to BOTH of them. Drawing each cell as a
+// stroked rect drew that boundary twice, and the second painting won: a marked
+// cell's colour, or a conditional field's dash, was whatever the neighbour
+// happened to paint last. So the grid is now emitted edge-by-edge, each edge
+// exactly once, and its appearance is decided by its (at most two) owners.
+//
+// WHAT THE OLD DRAWING DESTROYED. A `present=` field's shared edge was
+// overwritten solid by a plain neighbour. `STYLE-KEY-SCOPE` rules that the dash IS
+// conditional presence and that nothing else can set or clear it — so the
+// model's flag was being silently erased at render time. This is a
+// correctness fix, not a cosmetic one.
+//
+// WHY NOT HALF-WIDTH. The obvious alternative gives each owner half the
+// boundary: two 0.5px bands, one per side. Point-sampled at 1× — the size a
+// figure is actually read at — a shared edge between an orange mark and a
+// green one reads #2E6E34: one muddy pixel with the orange unrecoverable,
+// because half-width strokes sit at quarter-pixel offsets and the rasteriser
+// averages them. The bands here land on integer pixels and every colour
+// survives exactly. A zoomed crop hides this entirely, which is why the
+// decision was made at 1× and must be re-checked at 1× if it is revisited.
+//
+// THE RESIDUAL AMBIGUITY, stated rather than hidden. A dashed edge between a
+// conditional field and a plain one can be read locally as if the plain one
+// were conditional too. Today's drawing has the same ambiguity whenever the
+// dash happens to win the overwrite; this is strictly better, not solved.
+//
+// WHAT IT COSTS. Two adjacent marked cells put 3px of ink at their shared
+// boundary (ring + line + ring) against 1px elsewhere: the grid stays even,
+// but that region reads heavier. Four differently marked cells meeting at a
+// point give four ring corners around one crossing — busy at 8×, invisible
+// at 1×.
+//
+// `edges` are runs produced by edgeRuns(); `def` is the block's grid colour.
+function edgeSvg(edges, def){
+  const W=1, out=[];
+  const L=(v,p,s,e,col,dash,w)=>'<line x1="'+(v?p:s)+'" y1="'+(v?s:p)+'" x2="'+(v?p:e)+'" y2="'+(v?e:p)
+    +'" stroke="'+col+'"'+(w!==1?' stroke-width="'+w+'"':'')+(dash?' stroke-dasharray="5 3"':'')+'/>';
+  for(const g of edges){
+    const A=g.a, B=g.b;
+    // The shared line: default colour, full weight, dashed iff EITHER owner
+    // carries `present=`. A field with both `stroke=` and `present=` therefore
+    // gets a dashed boundary AND a separate coloured ring, not a coloured
+    // dash — the two marks answer different questions and must not merge.
+    out.push(L(g.v, g.p, g.s, g.e, def, (A&&A.d)||(B&&B.d), W));
+    // The class marks: solid, full weight, inset INSIDE their own cell. An end
+    // pulls in by W/2 where the owner stops and the ring turns the corner;
+    // it is left long where the owner continues past that end and the next run
+    // carries on, so a run that ends only because the NEIGHBOUR changed joins
+    // with no seam and no ring protrudes past its own cell. The test is the
+    // ownership map (does this cell own the next unit too?), not the geometry.
+    if(A&&A.c) out.push(L(g.v, g.p-W, g.s+(g.ca0?0:W/2), g.e-(g.ca1?0:W/2), A.c, false, W));
+    if(B&&B.c) out.push(L(g.v, g.p+W, g.s+(g.cb0?0:W/2), g.e-(g.cb1?0:W/2), B.c, false, W));
+  }
+  return out.join('');
+}
+// Walk one grid line unit by unit and merge collinear units that have the same
+// pair of owners into a single run. `v` is 1 for a vertical line, `p` its fixed
+// coordinate; `n` units; `span(i)` -> [start,end]; `ownAt(i)` -> [before,after]
+// where an owner is {id, c:colour|null, d:dashed}. A unit with no owner, or
+// with the SAME owner on both sides (a merged/spanning cell's interior), draws
+// nothing at all — which is where the doubled interior lines went.
+function edgeRuns(v, p, n, span, ownAt){
+  const out=[]; let run=null;
+  const sid=(o)=>o?o.id:null;
+  const cont=(i,k,o)=>!!o && sid((ownAt(i)||[])[k])===o.id;
+  for(let i=0;i<n;i++){
+    const o=ownAt(i)||[], a=o[0]||null, b=o[1]||null;
+    const skip=(!a&&!b)||(a&&b&&a.id===b.id);
+    const key=skip?null:JSON.stringify([a&&[a.c,a.d], b&&[b.c,b.d]]);
+    const sp=span(i);
+    if(run && run.key===key && run.e===sp[0]){ run.e=sp[1]; run.i1=i; continue; }
+    if(run){ out.push(run); run=null; }
+    if(!skip) run={v:v,p:p,s:sp[0],e:sp[1],key:key,a:a,b:b,i0:i,i1:i};
+  }
+  if(run) out.push(run);
+  for(const r of out){
+    r.ca0=cont(r.i0-1,0,r.a); r.ca1=cont(r.i1+1,0,r.a);
+    r.cb0=cont(r.i0-1,1,r.b); r.cb1=cont(r.i1+1,1,r.b);
+  }
+  return out;
+}
+
 // ---- bitfield ----
 function renderBitfield(b,y0){
   const cell=Math.max(18,Math.min(28,Math.floor(760/b.word))), rh=30, ruler=16;
@@ -3777,9 +3943,11 @@ function renderBitfield(b,y0){
   // one edge a per-row rect cannot leave out: a rect strokes four sides or
   // none, and "none" would also lose the two verticals that must continue.
   // Fill stays a single closed region, so `fill=` paints the field once with
-  // no seam, and the stroke carries `present=`'s dash around the whole
-  // outline instead of around each row (`STYLE-KEY-SCOPE`: the dash IS conditional
-  // presence, and nothing else may set or clear it).
+  // no seam. Since 0.1.6 the path is unstroked and the boundary comes from the
+  // shared-edge grid instead; the internal boundary is still never drawn,
+  // because both of its sides are owned by the same field and edgeRuns() skips
+  // a unit whose two owners are one (`STYLE-KEY-SCOPE`: the dash IS conditional presence,
+  // and nothing else may set or clear it).
   const boxOutline=(bx)=>{
     const bands=[];
     for(const s of bx){
@@ -3801,6 +3969,11 @@ function renderBitfield(b,y0){
     }
     return 'M'+pts.map(p=>p[0]+' '+p[1]).join(' L')+' Z';
   };
+  // Shared-edge grid (0.1.6): field fills carry no stroke of their own. Every
+  // bit column of every row records which field owns it, and the grid is
+  // emitted once, edge by edge, after the fields — see edgeSvg() above.
+  const BOWN=new Map(), BDEF=b.stroke||'#555';
+  const bkey=(rw,cl)=>rw+':'+cl; let BOXN=0;
   let pos=0; // bit cursor
   for(const f of b.fields){
     if(f.wrap){ pos=Math.ceil((pos||1)/b.word)*b.word; continue; }
@@ -3826,9 +3999,11 @@ function renderBitfield(b,y0){
     // `PRESENCE-CONDITION-EXPRESSION`: the carrier is now `present=`, and BOTH of its
     // written forms dash — `present=""` claims conditional presence just as
     // `present="C = 1"` does; only the caption below distinguishes them.
-    const dash=f.present!==undefined?' stroke-dasharray="5 3"':'';
+    // 0.1.6: the dash and the class colour no longer ride on the box's own
+    // stroke — they are properties of the shared boundary and of the ring
+    // inside the cell respectively, recorded per bit below and drawn once.
     const cfill=f.fill||b.fill||'#fff';
-    const paint=' fill="'+cfill+'" stroke="'+(f.stroke||b.stroke||'#555')+'"'+dash;
+    const paint=' fill="'+cfill+'" stroke="none"';
     // Draw one occurrence. `suffix` is the derived index label — '' for a
     // field that is not one element of a run, ' [0]' / ' [n]' for the two
     // occurrences `REPEATED-RUN-DRAWING` draws. It is APPENDED to the author's label, and the
@@ -3863,6 +4038,13 @@ function renderBitfield(b,y0){
         ? '<rect x="'+bx[0].x+'" y="'+bx[0].y+'" width="'+bx[0].w+'" height="'+(bx.length*rh)+'"'+paint
         : '<path d="'+boxOutline(bx)+'"'+paint;
       const tag=flat?'rect':'path';
+      // Record ownership per BIT, one entry per (row, column) this occurrence
+      // covers. Every occurrence of a repeated field is its own owner id, so
+      // the boundary between two occurrences is a real boundary and is drawn.
+      const bid=b.id+'_'+(BOXN++);
+      const brec={id:bid, c:f.stroke||null, d:f.present!==undefined};
+      bx.forEach(function(s){ const c0=Math.round(s.x/cell), n=Math.round(s.w/cell);
+        for(let k=0;k<n;k++) BOWN.set(bkey(s.row,c0+k), brec); });
       svg.push(desc?shape+'>'+desc+'</'+tag+'>':shape+'/>');
       // ONE caption per box: the NAME on the first box, CONT on every later
       // one. The first box, not the widest — reading order is the order the
@@ -3923,6 +4105,29 @@ function renderBitfield(b,y0){
       }
     }
   }
+  // The shared-edge grid for the bitfield: one pass over every vertical bit
+  // boundary and every horizontal row boundary, each emitted once.
+  let maxRow=-1;
+  BOWN.forEach(function(v,k){ const r=+k.split(':')[0]; if(r>maxRow) maxRow=r; });
+  const yrow=(r)=>y+r*rh+shiftFor(r);
+  const at=(r,c)=>(r<0||r>maxRow||c<0||c>=b.word)?null:(BOWN.get(bkey(r,c))||null);
+  const BE=[];
+  for(let c=0;c<=b.word;c++)
+    BE.push.apply(BE, edgeRuns(1, c*cell, maxRow+1,
+      i=>[yrow(i), yrow(i)+rh], i=>[at(i,c-1), at(i,c)]));
+  // A horizontal boundary is a row's TOP, shared with the row above when the
+  // two are vertically adjacent. A row also needs a bottom of its own when the
+  // row below is not adjacent — an elision strip has been inserted between
+  // them, and shiftFor() has pushed it down.
+  const hb=[];
+  for(let r=0;r<=maxRow;r++){
+    hb.push({y:yrow(r), ar:(r>0 && yrow(r-1)+rh===yrow(r))?r-1:-1, br:r});
+    if(r===maxRow || yrow(r+1)!==yrow(r)+rh) hb.push({y:yrow(r)+rh, ar:r, br:-1});
+  }
+  for(const hbe of hb)
+    BE.push.apply(BE, edgeRuns(0, hbe.y, b.word,
+      i=>[i*cell, (i+1)*cell], i=>[hbe.ar<0?null:at(hbe.ar,i), hbe.br<0?null:at(hbe.br,i)]));
+  svg.push(edgeSvg(BE, BDEF));
   for(const e of elis){
     const st=(b.stroke||'#555');
     // `ELISION-MARK-EXTENT`: THE SIDE DOTS ARE ALWAYS DRAWN. This reverses `ELISION-MARK-EXTENT`,
@@ -4018,6 +4223,14 @@ function renderTable(t,y0){
   // cell marks: h1..hN address header tiers top-down, r>=1 the data rows
   const markOf=(r,c)=>(t.marks||[]).find(mk=>(mk.hdr?mk.r-1:H+mk.r-1)===r&&mk.c===c+1);
   const yTop=y+4;
+  // Shared-edge grid (0.1.6): cell fills carry no stroke of their own. Every
+  // grid cell records its owning (anchor) cell, and the grid is emitted once,
+  // edge by edge, after the cells — see edgeSvg() above. Table cells have no
+  // conditional-presence mark, so `d` is always false here; the dash branch
+  // exists for the bitfield and is kept common so both genres draw alike.
+  const NC=t.cols.length, DEF=t.stroke||'#c9c7bf';
+  const OWN=grid.map(()=>new Array(NC).fill(null));
+  const xAt=[0]; for(let i=0;i<NC;i++) xAt.push(xAt[i]+widths[i]);
   for(let r=0;r<grid.length;r++){
     for(let c=0;c<grid[r].length;c++){
       const cell=grid[r][c];
@@ -4033,7 +4246,11 @@ function renderTable(t,y0){
       // addressable cells carry table-id:row:col (row 0 = bottom header tier)
       const addrR = r>=H ? (r-H+1) : (r===H-1 ? 0 : null);
       const addr = addrR===null ? '' : ' data-cell="'+t.id+':'+addrR+':'+(c+1)+'" style="cursor:pointer"';
-      svg.push('<rect x="'+x+'" y="'+yy+'" width="'+wsum+'" height="'+h+'" fill="'+fill+'" stroke="'+((mk&&mk.stroke)||t.stroke||'#c9c7bf')+'"'+addr+'/>');
+      // A merged cell owns every grid square it spans, so its internal
+      // boundaries have the same owner on both sides and are never drawn.
+      const rec={id:'c'+r+'_'+c, c:(mk&&mk.stroke)||null, d:false};
+      for(let rr=r;rr<r+rs;rr++) for(let cc=c;cc<c+cs;cc++) if(OWN[rr]) OWN[rr][cc]=rec;
+      svg.push('<rect x="'+x+'" y="'+yy+'" width="'+wsum+'" height="'+h+'" fill="'+fill+'" stroke="none"'+addr+'/>');
       // alignment: headers centered; data follows GFM colon alignment (default left)
       const al=cell.hdr?'center':(alignOf(c)||'left');
       const tx=al==='center'?x+wsum/2:(al==='right'?x+wsum-7:x+7);
@@ -4049,6 +4266,16 @@ function renderTable(t,y0){
       }
     }
   }
+  // Each edge drawn exactly once, owned by the (at most two) cells it divides.
+  const EDG=[];
+  const cellAt=(r,c)=>(r<0||r>=grid.length||c<0||c>=NC)?null:OWN[r][c];
+  for(let c=0;c<=NC;c++)
+    EDG.push.apply(EDG, edgeRuns(1, xAt[c], grid.length,
+      i=>[yTop+yAt[i], yTop+yAt[i+1]], i=>[cellAt(i,c-1), cellAt(i,c)]));
+  for(let r=0;r<=grid.length;r++)
+    EDG.push.apply(EDG, edgeRuns(0, yTop+yAt[r], NC,
+      i=>[xAt[i], xAt[i+1]], i=>[cellAt(r-1,i), cellAt(r,i)]));
+  svg.push(edgeSvg(EDG, DEF));
   const yEnd=yTop+yAt[grid.length];
   return {svg:svg.join(''), y:yEnd+6, w:totalW+2};
 }