Code map
Diagram Studio v7 · maintainable sources and interaction boundaries
diagram-studio.html is the executable release. Its source files are under source/. python source/build.py inserts the CSS and JavaScript into shell.html, producing the standalone file without a JavaScript build tool or network call. The build checks for unsafe inline script terminators.
This is still a plain-JavaScript prototype with shared global controller state, not a framework migration. The source split makes the modules inspectable and testable; it does not make their browser controllers independent. No repository changes or commits were made.
1. Runtime load order
| Source | Responsibility |
|---|---|
shell.html and styles.css |
Application structure, SVG layers, inspector panels, full-viewport comparison dialog, timeline deck, and brush controls. |
layout-engine.js |
DOM-free global layout, compound hierarchy, constraints, direction, start/end intent, metrics, and optional checkpoint recording. Exposes LayoutLab. |
routing-engine.js |
DOM-free automatic port/route search and diagnostics. Exposes RouteLab. |
explorer-engine.js |
Candidate configurations, parameter axes, scene projection, independent layout/routing candidates. Exposes ExplorerLab. |
sculpt-engine.js |
DOM-free timeline construction, checkpoint summaries, lookahead, local influence fields, and brush dabs. Exposes SculptLab. |
studio-app.js |
Document normalization, committed graph state, editing commands, renderer, camera, persistence, normal layout controls, exports, undo/redo, and public API. |
explorer-ui.js |
Grid/Overlay comparison, click correspondence, camera modes, candidate workers, applying a candidate, experiment export. |
sculpt-ui.js |
Timeline/brush transactions, pointer gestures, hover and ghost previews, local holds, bookmarking, replay, and temporal-history import/export. |
These are classic scripts, not ES module imports. The DOM-free engines also expose CommonJS exports for Node tests. The browser controllers deliberately reuse editor functions rather than introducing a second diagram renderer.
2. Committed document and render state
D in studio-app.js is the committed schema-2 document. graph contains nodes, edges and groups. layout.nodes contains geometry, manual markers and pins. layout.edges stores port constraints, route waypoints and label offsets. layout.labels, layout.containers, layout.intent, styles, collapsed, settings, camera and theme remain separate concerns.
normalize validates imports, stable IDs, references, hierarchy, geometry and finite settings. migrateLegacy extracts the old active graph from an obsolete saved-view document rather than resurrecting that user interface.
S holds selection, tool state, active drags, undo/redo, route caches and layout state. S.animationNodes is the old short animation buffer. S.sculptNodes is the new render-only geometry override. geometryNode reads it before ordinary geometry, while snapshot() and diagramStudio.get() still read D. This is the primary safety boundary for timelines and in-progress brush strokes.
renderScene, renderNode, renderGroup, makeRoutes, renderEdges and renderOverlay are reused by the new interactions. sculptOverlay appends non-interactive ghosts, motion guides, influence rings, and hold markers. Export removes the entire editor overlay layer. Rendered preview routes use S.sculptRoutePrior for a consistent prior-side context, and S.pendingRouteResult adopts the exact chosen routing on Keep.
3. Layout path recording
LayoutLab.compute(input, opts) still clones its input. New opts.fixedIds supplements ordinary pins and manual-position protection in the existing direct, branch and fixed tests. This protects held descendants against an ancestor translation without writing temporary pins into the document.
With opts.trace, the internal captureTrace records positions, iteration counter, phase and geometry metrics. It samples at an increasing stride and thins old samples near the 96-frame bound. Start and finish are forced captures. Intermediate samples avoid new overlap counts relative to the initial metric and avoid worsening frame spill. They are not guaranteed to monotonically improve every metric or preserve topology during motion between stops.
SculptLab.journey invokes the selected method in warm-settle mode by default. It removes duplicate consecutive coordinate snapshots, ensures the first geometry equals the source and the last equals the actual returned document, computes checkpoint movement summaries, and creates the separate diagram-studio-journey envelope. lookahead finds the first later checkpoint with a meaningful screen-space displacement, or the final checkpoint if less remains.
openJourney freezes the baseline, options, local holds, route prior and document signature. journeyCompute runs the exact same engines in a Blob worker. A worker creation/startup failure falls back to the yielding main-thread engine. The generation counter and signature guard prevent stale completion from being adopted. Cancelling a worker terminates it; cancelling a fallback invalidates its result even if the asynchronous solver continues to finish.
journeyScrub changes the render buffer and selected index. A hover uses a separate peek index. journeyBookmark captures a restoration source without committing it. journeyKeep captures the displayed routes, clears preview state, adopts the chosen geometry, and calls remember once. The camera is preserved. closeJourney discards the override and leaves the committed graph unchanged.
journeyFitPath explicitly computes a union of the recorded rectangles and fits it above the timeline deck. Repeated scrubbing does not call Fit automatically.
4. Brush computation
SculptLab.field finds visible leaf shapes and computes smooth falloff by point-to-rectangle distance. Actual pins, pinned ancestors, selected manual protection and local holds are excluded. Expanded and collapsed containers are not brush movement targets.
SculptLab.dab always returns a cloned document. It chooses one local policy: spring/alignment tidy, stronger directed movement, rectangle separation, coordinate restoration, or protection-only hit testing. Exterior neighbors may contribute forces, but nodes outside the influence support are never moved. Directed pressure uses the lowest common container's direction; feedback edges are identified by the existing topology routine.
Movement is capped per shape by field weight, strength and step. constrainedTarget clips against the current parent interior without resizing it. New/worsened rectangle intersections are checked only for changed-versus-visible pairs; ancestry and starting areas are cached per dab. A bounded line search attenuates the proposal. The brush does not compare proposals against the whole graph's spring/stress energy.
The returned object includes document, weights, locked, moved, maxDisplacement, blocked, attenuation and mode when applicable. These diagnostics distinguish an empty field, protected target, geometric blockage and an accepted local change.
5. Brush gesture transaction
SCULPT owns tool preferences, the pointer, hover result, active stroke, restore source, local hold set and timers. brushActivate enters W mode. Hovering calls sculptHoverAt, which computes a prospective dab and displays its outline without writing D.
brushStart captures the committed baseline and signature. The stroke has its own working document. sculptStrokeDab advances that document; the renderer sees its geometry through S.sculptNodes. Pointer movement and an approximately 90-ms held-pointer timer request more dabs. Pointer-up adopts the entire working geometry once. sculptCancelStroke drops it on Escape, pointer cancellation, lost capture or blur.
sculptRememberHolds attaches the before/after local hold sets to the corresponding history entry. Protection-only changes receive their own entry even though the document snapshot is identical. sculptHistory restores the appropriate set on undo/redo. Local holds are deliberately not serialized into the graph. sculptCheckDocument prevents a hold/reference from leaking into a different diagram with coincidentally reused node IDs.
sculptFixedIds feeds the hold set into normal runLayout, the timeline, and exConfig → ExplorerLab.candidate. Protecting an area should not depend on which layout entry point the user chooses.
6. Durability and import/export
Ordinary committed diagram persistence retains the existing diagram-studio-v5 key for continuity. UI preferences use their existing separate key. The new latest-history key is diagram-studio-v7-last-journey.
sculptArchive retains the recording in memory and writes it to the separate history key only below the serialization cap and when storage is available. reopenJourney checks compatibility before rendering an old recording against the current source. sculptImportJourney validates the history envelope, normalizes its baseline, checks IDs, finite coordinates, metrics, pins and bookmark indices, then opens it through an undoable document replacement.
Normal exports are handled by exportDocument → exportSVG / exportPNG. An active timeline or uncommitted stroke blocks normal diagram export. Brush controls and ghosts are never exported as diagram content. Timeline export is explicit and can contain the full source diagram, image data and all recorded coordinates.
No download destination is verified merely because a Blob was constructed. The browser suite checks serialization and PNG Blob production separately from native download behavior.
7. Public API additions
The existing window.diagramStudio API remains. New methods are:
// Record the selected layout from committed positions; wait until it is ready.
await diagramStudio.timeline({ algorithm: 'flow', maxIterations: 640 });
const history = diagramStudio.getJourney();
console.info('[timeline]', history.frames.length, history.report.termination);
// Select an exact recorded checkpoint. This is preview, not a document write.
diagramStudio.scrub(Math.floor((history.frames.length - 1) / 2));
diagramStudio.bookmarkFrame();
// Keep the endpoint, then restore only an area from the bookmark.
diagramStudio.scrub(history.frames.length - 1);
diagramStudio.keepFrame({ brush: true });
// Brush tool configuration, or one programmatic local dab.
diagramStudio.brush({ mode: 'restore', radius: 140, strength: 45 });
const result = diagramStudio.brushDab({
mode: 'tidy',
point: { x: 640, y: 320 }, // World coordinates.
worldRadius: 180,
strength: 35,
});
console.info('[brush]', result.moved, result.maxDisplacement, result.blocked);
// Ordinary undo/redo work for the accepted frame and the complete stroke.
diagramStudio.undo();
diagramStudio.redo();
diagramStudio.clearLocalHolds();
timelineState() reports preview indices, stop reports, bookmarks, brush settings, eligible/protected IDs and local holds. cancelTimeline() discards the preview. get() continues to return committed state while the timeline is open. Normal set() / import invalidates an open preview instead of allowing later completion to overwrite the replacement.
8. Migration boundaries
The most important extraction is a transaction coordinator, not another algorithm registry. Preserve the distinction between committed data, temporal recording, render-only geometry, restoration source and session protection. Those states have different lifetimes and different undo behavior.
Move the pure engines into typed modules first. Model timeline and stroke controllers as explicit states such as idle, computing, inspecting, painting and committing. Keep worker cancellation/generation checks at every asynchronous boundary. Avoid tying data persistence to a reactive render buffer; a store update caused by scrubbing must not be mistaken for a source edit.
Replace the current global hooks with explicit interfaces for geometry projection, route computation, history commands, document identity, view camera and diagnostics. Keep keyboard/tool routing centralized so a key cannot both paint and activate a second global command. Preserve Escape priority: cancel active stroke, cancel preview, exit transient tool, clear selection.
Local holds are not a replacement for a general constraint system. A production version might persist them as editing-session intent, but should distinguish them from pins and semantic graph data. A richer history model could retain multiple branches and selective undo; the current release deliberately retains one latest recording plus ordinary command history.
9. Verification entry points
verification/geometry.cjs exercises the inherited layout/routing constraints and broad sample cases. verification/sculpt-geometry.cjs exercises path endpoints, recording determinism, bounded sample memory, influence continuity, source immutability, outside-field identity, pins, held descendants, repeated dabs and collision safety.
verification/browser_checks.py covers existing editor/comparison interactions. verification/sculpt-browser.py covers native range keyboard handling, hover peeking, preview isolation, exact Keep, temporal restore, held strokes, cancellation, undo/redo of holds, history replay/import, ordinary exports and adapter-based boot restoration.
The tests operate on the actual rebuilt artifact. Read the current ledger for counts, browser policy restrictions and unverified environments. Geometry tests do not establish continuous animation safety, attractive output for every graph, physical-device behavior, or production performance.
Recorded history validation
sculptValidateJourney is shared by explicit history import and the separate last-path storage loader. It validates frames, finite metrics, and pin invariants before adoption. Invocation-only constraints (fixedIds, selection, scope, solver effort) are recorded under the history artifact's execution field, never copied into ordinary diagram settings. Importing a recording does not reactivate its session-owned local holds.