tools/render_html.py · cgcardona/muse

<div class="dim-legend-item" style="margin-left:8px"><span style="display:inline-block;width:22px;height:14px;border-radius:3px;border:2px solid #f85149;vertical-align:middle;margin-right:6px"></span> Conflict (required resolution)</div>

679

<div class="dim-legend-item"><span style="display:inline-block;width:22px;height:14px;border-radius:3px;background:var(--bg3);border:1px solid var(--border);vertical-align:middle;margin-right:6px"></span> Unchanged</div>

680

</div>

681

682

<strong>⚡ Merge conflict at ba2f7d79</strong> — shared-state.mid had both-sides changes in

683

<strong style="color:#ef5350">structural</strong> (manual resolution required).

684

<em>✓ melodic auto-merged from left</em> · <em>✓ harmonic auto-merged from right</em> —

685

only 1 of 5 dimensions conflicted. Git would have flagged the entire file as a conflict.

</div>

</div>

</div>

<h2>How Muse Works</h2>

693

694

Muse is a version control system for <strong>state</strong> — any multidimensional

695

state that can be snapshotted, diffed, and merged. The core engine provides

696

the DAG, content-addressed storage, branching, merging, time-travel, and

697

conflict resolution. A domain plugin implements <strong>5 methods</strong> and

698

gets everything else for free.

699

700

Music is the reference implementation. Genomics sequences, scientific simulation

701

frames, 3D spatial fields, and financial time-series are all the same pattern.

</p>

</div>

</div>

</div>

<span>Generated {{GENERATED_AT}} · {{ELAPSED}}s · {{OPS}} operations</span>

711

<span><a href="https://github.com/cgcardona/muse">github.com/cgcardona/muse</a></span>

</footer>

</div>

/* ===== Embedded tour data ===== */

726

const DATA = {{DATA_JSON}};

727

728

/* ===== Constants ===== */

729

const ROW_H = 62;

730

const COL_W = 90;

731

const PAD = { top: 30, left: 55, right: 160 };

732

const R_NODE = 11;

733

const BRANCH_ORDER = ['main','alpha','beta','gamma','conflict/left','conflict/right'];

734

const PLAY_INTERVAL_MS = 1200;

735

736

/* ===== Dimension data ===== */

const DIM_COLORS = {

melodic: '#bc8cff',

rhythmic: '#3fb950',

harmonic: '#58a6ff',

dynamic: '#f9a825',

structural: '#ef5350',

743

};

744

const DIMS = ['melodic','rhythmic','harmonic','dynamic','structural'];

745

746

// Per-commit (short ID) → which dimensions changed vs parent

747

const DIM_DATA = {

748

'1339aad5': ['melodic','rhythmic','harmonic','dynamic','structural'],

749

'6f0cf90e': ['rhythmic','structural'],

750

'cc822981': ['harmonic','structural'],

751

'4d7a7752': ['melodic','rhythmic'],

752

'cb4afaed': ['melodic','dynamic'],

753

'80ff4474': ['rhythmic','dynamic'],

754

'68fa6ba2': ['melodic'],

755

'b2f26495': ['melodic','harmonic'],

756

'b18ee707': ['rhythmic','dynamic'],

757

'a8da6915': ['melodic','structural'],

758

'bbf074d4': ['harmonic','structural'],

759

'ba2f7d79': ['structural'],

760

'b94b480d': ['melodic'],

761

'ffc28a71': ['melodic'],

762

};

763

// Dims that required human resolution

764

const DIM_CONFLICTS = {

765

'ba2f7d79': ['structural'],

};

/* ===== State ===== */

770

let currentStep = -1;

771

let isPlaying = false;

772

let playTimer = null;

773

774

/* ===== Utilities ===== */

775

function escHtml(s) {

return String(s)

.replace(/&/g,'&')

.replace(/</g,'<')

.replace(/>/g,'>')

.replace(/"/g,'"');

}

/* ===== Topological sort ===== */

784

function topoSort(commits) {

785

const map = new Map(commits.map(c => [c.id, c]));

786

const visited = new Set();

787

const result = [];

788

function visit(id) {

789

if (visited.has(id)) return;

790

visited.add(id);

791

const c = map.get(id);

792

if (!c) return;

793

(c.parents || []).forEach(pid => visit(pid));

794

result.push(c);

795

}

796

commits.forEach(c => visit(c.id));

797

// Oldest commit at row 0 (top of DAG); newest at the bottom so the DAG

798

// scrolls down in sync with the operation log during playback.

return result;

}

/* ===== Layout ===== */

803

function computeLayout(commits) {

804

const sorted = topoSort(commits);

805

const branchCols = {};

806

let nextCol = 0;

807

// Assign columns in BRANCH_ORDER first, then any extras

808

BRANCH_ORDER.forEach(b => { branchCols[b] = nextCol++; });

809

commits.forEach(c => {

810

if (!(c.branch in branchCols)) branchCols[c.branch] = nextCol++;

811

});

812

const numCols = nextCol;

813

const positions = new Map();

814

sorted.forEach((c, i) => {

815

positions.set(c.id, {

816

x: PAD.left + (branchCols[c.branch] || 0) * COL_W,

817

y: PAD.top + i * ROW_H,

818

row: i,

819

col: branchCols[c.branch] || 0,

820

});

821

});

822

const svgW = PAD.left + numCols * COL_W + PAD.right;

823

const svgH = PAD.top + sorted.length * ROW_H + PAD.top;

824

return { sorted, positions, branchCols, svgW, svgH };

825

}

826

827

/* ===== Draw DAG ===== */

828

function drawDAG() {

829

const { dag, dag: { commits, branches } } = DATA;

830

if (!commits.length) return;

831

832

const layout = computeLayout(commits);

833

const { sorted, positions, svgW, svgH } = layout;

834

const branchColor = new Map(branches.map(b => [b.name, b.color]));

835

const commitMap = new Map(commits.map(c => [c.id, c]));

836

837

const svg = d3.select('#dag-svg')

838

.attr('width', svgW)

839

.attr('height', svgH);

840

841

// ---- Edges ----

842

const edgeG = svg.append('g').attr('class', 'edges');

843

sorted.forEach(commit => {

844

const pos = positions.get(commit.id);

845

(commit.parents || []).forEach((pid, pIdx) => {

846

const ppos = positions.get(pid);

847

if (!pos || !ppos) return;

848

const color = pIdx === 0

849

? (branchColor.get(commit.branch) || '#555')

850

: (branchColor.get(commitMap.get(pid)?.branch || '') || '#555');

851

852

let pathStr;

853

if (Math.abs(pos.x - ppos.x) < 4) {

854

// Same column → straight line

855

pathStr = `M${pos.x},${pos.y} L${ppos.x},${ppos.y}`;

856

} else {

857

// Different columns → S-curve bezier

858

const mid = (pos.y + ppos.y) / 2;

859

pathStr = `M${pos.x},${pos.y} C${pos.x},${mid} ${ppos.x},${mid} ${ppos.x},${ppos.y}`;

}

edgeG.append('path')

.attr('d', pathStr)

.attr('stroke', color)

864

.attr('stroke-width', 1.8)

865

.attr('fill', 'none')

866

.attr('opacity', 0.45)

867

.attr('class', `edge-from-${commit.id.slice(0,8)}`);

});

});

// ---- Nodes ----

const nodeG = svg.append('g').attr('class', 'nodes');

873

const tooltip = document.getElementById('tooltip');

874

875

sorted.forEach(commit => {

876

const pos = positions.get(commit.id);

877

if (!pos) return;

878

const color = branchColor.get(commit.branch) || '#78909c';

879

const isMerge = (commit.parents || []).length >= 2;

880

881

const g = nodeG.append('g')

882

.attr('class', 'commit-node')

883

.attr('data-id', commit.id)

884

.attr('data-short', commit.short)

885

.attr('transform', `translate(${pos.x},${pos.y})`);

if (isMerge) {

g.append('circle')

.attr('r', R_NODE + 6)

890

.attr('fill', 'none')

891

.attr('stroke', color)

892

.attr('stroke-width', 1.5)

893

.attr('opacity', 0.35);

}

g.append('circle')

.attr('r', R_NODE)

.attr('fill', color)

.attr('stroke', '#0d1117')

900

.attr('stroke-width', 2);

// Short ID

g.append('text')

.attr('x', R_NODE + 7)

905

.attr('y', 0)

906

.attr('dy', '0.35em')

907

.attr('class', 'commit-label')

908

.text(commit.short);

909

910

// Message (truncated)

911

const maxLen = 38;

912

const msg = commit.message.length > maxLen

913

? commit.message.slice(0, maxLen) + '…'

914

: commit.message;

915

g.append('text')

916

.attr('x', R_NODE + 7)

917

.attr('y', 13)

918

.attr('class', 'commit-msg')

.text(msg);

// Dimension dots below node

923

const dims = DIM_DATA[commit.short] || [];

924

if (dims.length > 0) {

925

const dotR = 4, dotSp = 11;

926

const totalW = (DIMS.length - 1) * dotSp;

927

const dotsG = g.append('g')

928

.attr('class', 'dim-dots')

929

.attr('transform', `translate(${-totalW/2},${R_NODE + 9})`);

930

DIMS.forEach((dim, di) => {

931

const active = dims.includes(dim);

932

const isConf = (DIM_CONFLICTS[commit.short] || []).includes(dim);

933

dotsG.append('circle')

934

.attr('cx', di * dotSp).attr('cy', 0).attr('r', dotR)

935

.attr('fill', active ? DIM_COLORS[dim] : '#21262d')

936

.attr('stroke', isConf ? '#f85149' : (active ? DIM_COLORS[dim] : '#30363d'))

937

.attr('stroke-width', isConf ? 1.5 : 0.8)

938

.attr('opacity', active ? 1 : 0.35);

});

}

// Hover tooltip

g.on('mousemove', (event) => {

944

tooltip.classList.add('visible');

945

document.getElementById('tip-id').textContent = commit.id;

946

document.getElementById('tip-msg').textContent = commit.message;

947

document.getElementById('tip-branch').innerHTML =

948

`<span style="color:${color}">⬤</span> ${commit.branch}`;

949

document.getElementById('tip-files').textContent =

950

commit.files.length

951

? commit.files.join('\\n')

952

: '(empty snapshot)';

953

const tipDims = DIM_DATA[commit.short] || [];

954

const tipConf = DIM_CONFLICTS[commit.short] || [];

955

const tipDimEl = document.getElementById('tip-dims');

956

if (tipDimEl) {

957

tipDimEl.innerHTML = tipDims.length

958

? tipDims.map(d => {

959

const c = tipConf.includes(d);

960

return `<span style="color:${DIM_COLORS[d]};margin-right:6px">● ${d}${c?' ⚡':''}</span>`;

}).join('')

: '';

}

tooltip.style.left = (event.clientX + 12) + 'px';

965

tooltip.style.top = (event.clientY - 10) + 'px';

966

}).on('mouseleave', () => {

967

tooltip.classList.remove('visible');

});

});

// ---- Branch legend ----

972

const legend = document.getElementById('branch-legend');

973

DATA.dag.branches.forEach(b => {

974

const item = document.createElement('div');

975

item.className = 'legend-item';

976

item.innerHTML =

977

`<span class="legend-dot" style="background:${b.color}"></span>` +

978

`<span>${escHtml(b.name)}</span>`;

979

legend.appendChild(item);

});

}

/* ===== Event log ===== */

984

function buildEventLog() {

985

const list = document.getElementById('event-list');

986

let lastAct = -1;

987

988

DATA.events.forEach((ev, idx) => {

989

if (ev.act !== lastAct) {

990

lastAct = ev.act;

991

const hdr = document.createElement('div');

992

hdr.className = 'act-header';

993

hdr.textContent = `Act ${ev.act} — ${ev.act_title}`;

994

list.appendChild(hdr);

995

}

996

997

const item = document.createElement('div');

998

item.className = 'event-item';

999

item.id = `ev-${idx}`;

1000

if (ev.exit_code !== 0 && ev.output.toLowerCase().includes('conflict')) {

1001

item.classList.add('failed');

1002

}

1003

1004

// Parse cmd into parts

1005

const parts = ev.cmd.split(' ');

1006

const cmdName = parts.slice(0,2).join(' ');

1007

const cmdArgs = parts.slice(2).join(' ');

1008

1009

// Determine output class

1010

let outClass = '';

1011

if (ev.output.toLowerCase().includes('conflict')) outClass = 'conflict';

1012

else if (ev.exit_code === 0 && ev.commit_id) outClass = 'success';

1013

1014

// Trim long output

1015

const outLines = ev.output.split('\\n').slice(0, 5).join('\\n');

1016

1017

item.innerHTML =

1018

`<div class="event-cmd">` +

1019

`<span class="cmd-prefix">$ </span>` +

1020

`<span class="cmd-name">${escHtml(cmdName)}</span>` +

1021

(cmdArgs ? ` <span class="cmd-args">${escHtml(cmdArgs.slice(0, 60))}${cmdArgs.length>60?'…':''}</span>` : '') +

1022

`</div>` +

1023

(outLines

1024

? `<div class="event-output ${outClass}">${escHtml(outLines)}</div>`

1025

: '') +

1026

(() => {

1027

if (!ev.commit_id) return '';

1028

const dims = DIM_DATA[ev.commit_id] || [];

1029

const conf = DIM_CONFLICTS[ev.commit_id] || [];

1030

if (!dims.length) return '';

1031

return '<div class="dim-pills">' + dims.map(d => {

1032

const isc = conf.includes(d);

1033

const col = DIM_COLORS[d];

1034

const cls = isc ? 'dim-pill conflict-pill' : 'dim-pill';

1035

const sty = isc ? '' : `color:${col};border-color:${col};background:${col}22`;

1036

return `<span class="${cls}" style="${sty}">${isc ? '⚡ ' : ''}${d}</span>`;

1037

}).join('') + '</div>';

1038

})() +

1039

`<div class="event-meta">` +

1040

(ev.commit_id ? `<span class="tag-commit">${escHtml(ev.commit_id)}</span>` : '') +

1041

`<span class="tag-time">${ev.duration_ms}ms</span>` +

1042

`</div>`;

1043

1044

list.appendChild(item);

});

}

/* ===== Dimension Timeline ===== */

1050

function buildDimTimeline() {

1051

const matrix = document.getElementById('dim-matrix');

1052

if (!matrix) return;

1053

const sorted = topoSort(DATA.dag.commits);

1054

1055

// Commit ID header row

1056

const hrow = document.createElement('div');

1057

hrow.className = 'dim-matrix-row';

1058

const sp = document.createElement('div');

1059

sp.className = 'dim-label-cell';

1060

hrow.appendChild(sp);

1061

sorted.forEach(c => {

1062

const cell = document.createElement('div');

1063

cell.className = 'dim-commit-cell';

1064

cell.id = `dim-col-label-${c.short}`;

1065

cell.title = c.message;

1066

cell.textContent = c.short.slice(0,6);

1067

hrow.appendChild(cell);

1068

});

1069

matrix.appendChild(hrow);

1070

1071

// One row per dimension

1072

DIMS.forEach(dim => {

1073

const row = document.createElement('div');

1074

row.className = 'dim-matrix-row';

1075

const lbl = document.createElement('div');

1076

lbl.className = 'dim-label-cell';

1077

const dot = document.createElement('span');

1078

dot.className = 'dim-label-dot';

1079

dot.style.background = DIM_COLORS[dim];

1080

lbl.appendChild(dot);

1081

lbl.appendChild(document.createTextNode(dim.charAt(0).toUpperCase() + dim.slice(1)));

1082

row.appendChild(lbl);

1083

1084

sorted.forEach(c => {

1085

const dims = DIM_DATA[c.short] || [];

1086

const conf = DIM_CONFLICTS[c.short] || [];

1087

const active = dims.includes(dim);

1088

const isConf = conf.includes(dim);

1089

const col = DIM_COLORS[dim];

1090

const cell = document.createElement('div');

1091

cell.className = 'dim-cell';

1092

const inner = document.createElement('div');

1093

inner.className = 'dim-cell-inner' + (active ? ' active' : '') + (isConf ? ' conflict-dim' : '');

1094

inner.id = `dim-cell-${dim}-${c.short}`;

1095

if (active) {

1096

inner.style.background = col + '33';

1097

inner.style.color = col;

1098

inner.textContent = isConf ? '⚡' : '●';

1099

}

1100

cell.appendChild(inner);

1101

row.appendChild(cell);

1102

});

1103

matrix.appendChild(row);

});

}

function highlightDimColumn(shortId) {

1108

document.querySelectorAll('.dim-commit-cell.col-highlight, .dim-cell-inner.col-highlight')

1109

.forEach(el => el.classList.remove('col-highlight'));

1110

if (!shortId) return;

1111

const lbl = document.getElementById(`dim-col-label-${shortId}`);

1112

if (lbl) {

1113

lbl.classList.add('col-highlight');

1114

lbl.scrollIntoView({ behavior:'smooth', block:'nearest', inline:'center' });

1115

}

1116

DIMS.forEach(dim => {

1117

const cell = document.getElementById(`dim-cell-${dim}-${shortId}`);

1118

if (cell) cell.classList.add('col-highlight');

});

}

/* ===== Replay animation ===== */

1123

function revealStep(stepIdx) {

1124

if (stepIdx < 0 || stepIdx >= DATA.events.length) return;

1125

1126

const ev = DATA.events[stepIdx];

1127

1128

// Reveal all events up to this step

1129

for (let i = 0; i <= stepIdx; i++) {

1130

const el = document.getElementById(`ev-${i}`);

1131

if (el) el.classList.add('revealed');

1132

}

1133

1134

// Mark current as active (remove previous)

1135

document.querySelectorAll('.event-item.active').forEach(el => el.classList.remove('active'));

1136

const cur = document.getElementById(`ev-${stepIdx}`);

1137

if (cur) {

1138

cur.classList.add('active');

1139

cur.scrollIntoView({ behavior: 'smooth', block: 'nearest' });

1140

}

1141

1142

// Highlight commit node

1143

document.querySelectorAll('.commit-node.highlighted').forEach(el => el.classList.remove('highlighted'));

1144

if (ev.commit_id) {

1145

const node = document.querySelector(`.commit-node[data-short="${ev.commit_id}"]`);

1146

if (node) {

1147

node.classList.add('highlighted');

1148

// Scroll DAG to show the node

1149

const transform = node.getAttribute('transform');

1150

if (transform) {

1151

const m = transform.match(/translate\$([\\d.]+),([\\d.]+)\$/);

1152

if (m) {

1153

const scroll = document.getElementById('dag-scroll');

1154

const y = parseFloat(m[2]);

1155

scroll.scrollTo({ top: Math.max(0, y - 200), behavior: 'smooth' });

}

}

}

}

// Highlight dimension matrix column

1162

highlightDimColumn(ev.commit_id || null);

1163

1164

// Update counter

1165

document.getElementById('step-counter').textContent =

1166

`Step ${stepIdx + 1} / ${DATA.events.length}`;

1167

1168

currentStep = stepIdx;

1169

}

1170

1171

function playTour() {

1172

if (isPlaying) return;

1173

isPlaying = true;

1174

document.getElementById('btn-play').textContent = '⏸ Pause';

1175

1176

function advance() {

1177

if (!isPlaying) return;

1178

const next = currentStep + 1;

1179

if (next >= DATA.events.length) {

1180

pauseTour();

1181

document.getElementById('btn-play').textContent = '✓ Done';

return;

}

revealStep(next);

playTimer = setTimeout(advance, PLAY_INTERVAL_MS);

}

advance();

}

function pauseTour() {

1191

isPlaying = false;

1192

clearTimeout(playTimer);

1193

document.getElementById('btn-play').textContent = '▶ Play Tour';

1194

highlightDimColumn(null);

1195

}

1196

1197

function resetTour() {

1198

pauseTour();

1199

currentStep = -1;

1200

document.querySelectorAll('.event-item').forEach(el => {

1201

el.classList.remove('revealed','active');

1202

});

1203

document.querySelectorAll('.commit-node.highlighted').forEach(el => {

1204

el.classList.remove('highlighted');

1205

});

1206

document.getElementById('step-counter').textContent = '';

1207

document.getElementById('log-scroll').scrollTop = 0;

1208

document.getElementById('dag-scroll').scrollTop = 0;

1209

document.getElementById('btn-play').textContent = '▶ Play Tour';

1210

}

1211

1212

/* ===== Init ===== */

1213

document.addEventListener('DOMContentLoaded', () => {

drawDAG();

buildEventLog();

buildDimTimeline();

document.getElementById('btn-play').addEventListener('click', () => {

1219

if (isPlaying) pauseTour(); else playTour();

1220

});

1221

document.getElementById('btn-reset').addEventListener('click', resetTour);

});

</script>

</body>

</html>

"""

# ---------------------------------------------------------------------------

1230

# Main render function

1231

# ---------------------------------------------------------------------------

1232

1233

1234

def render(tour: dict, output_path: pathlib.Path) -> None:

1235

"""Render the tour data into a self-contained HTML file."""

1236

print(" Rendering HTML visualization...")

1237

d3_script = _fetch_d3()

1238

1239

meta = tour.get("meta", {})

1240

stats = tour.get("stats", {})

1241

1242

# Format generated_at nicely

1243

gen_raw = meta.get("generated_at", "")

1244

try:

1245

from datetime import datetime, timezone

1246

dt = datetime.fromisoformat(gen_raw).astimezone(timezone.utc)

1247

gen_str = dt.strftime("%Y-%m-%d %H:%M UTC")

1248

except Exception:

1249

gen_str = gen_raw[:19]

1250

1251

html = _HTML_TEMPLATE

1252

html = html.replace("{{VERSION}}", str(meta.get("muse_version", "0.1.1")))

1253

html = html.replace("{{DOMAIN}}", str(meta.get("domain", "music")))

1254

html = html.replace("{{ELAPSED}}", str(meta.get("elapsed_s", "?")))

1255

html = html.replace("{{GENERATED_AT}}", gen_str)

1256

html = html.replace("{{COMMITS}}", str(stats.get("commits", 0)))

1257

html = html.replace("{{BRANCHES}}", str(stats.get("branches", 0)))

1258

html = html.replace("{{MERGES}}", str(stats.get("merges", 0)))

1259

html = html.replace("{{CONFLICTS}}", str(stats.get("conflicts_resolved", 0)))

1260

html = html.replace("{{OPS}}", str(stats.get("operations", 0)))

1261

html = html.replace("{{ARCH_HTML}}", _ARCH_HTML)

1262

html = html.replace("{{D3_SCRIPT}}", d3_script)

1263

html = html.replace("{{DATA_JSON}}", json.dumps(tour, separators=(",", ":")))

1264

1265

output_path.write_text(html, encoding="utf-8")

1266

size_kb = output_path.stat().st_size // 1024

1267

print(f" HTML written ({size_kb}KB) → {output_path}")

1268

1269

1270

# ---------------------------------------------------------------------------

1271

# Stand-alone entry point

1272

# ---------------------------------------------------------------------------

1273

1274

if __name__ == "__main__":

1275

import argparse

1276

parser = argparse.ArgumentParser(description="Render tour_de_force.json → HTML")

1277

parser.add_argument("json_file", help="Path to tour_de_force.json")

1278

parser.add_argument("--out", default=None, help="Output HTML path")

1279

args = parser.parse_args()

1280

1281

json_path = pathlib.Path(args.json_file)

1282

if not json_path.exists():

1283

print(f"❌ File not found: {json_path}", file=sys.stderr)

1284

sys.exit(1)

1285

1286

data = json.loads(json_path.read_text())

1287

out_path = pathlib.Path(args.out) if args.out else json_path.with_suffix(".html")

1288

render(data, out_path)

1289

print(f"Open: file://{out_path.resolve()}")