Workspace Observatory

A standalone VS Code extension that renders a live workspace graph with Three.js. Open this directory as your VS Code project, run npm install, then press F5. In the Extension Development Host, open a project folder and run Observatory: Open 3D Map from the Command Palette.

npm install
npm run check
npm test
npm run build

The bundled extension uses local assets only; it does not load scripts from a CDN. Webview messages can open or reveal only nodes present in the scanned graph. There is no arbitrary command execution bridge.

Exploring

• Click a node to focus it with an eased camera transition. The default view includes the focused node, five ancestors, and five descendant levels (where available). Up returns to its parent.
• Click a file satellite or its list entry to open the file in the editor.
• Drag to orbit, scroll to zoom, and use Fit to reset the camera.
• Search spans the indexed graph. Use File Type to narrow results.
• Run Observatory: Focus Current File to show the active editor's file.
• Run Observatory: Toggle Dependency Links, or use the checkbox, to control amber import edges.
• Hover a node for metadata. The details panel includes modification time, size, diagnostics, and resolved imports.
• The native button list supports keyboard navigation and remains usable without WebGL. Camera motion has no automatic rotation; damping is disabled when reduced motion is requested.

Architecture

src/extension.ts scans workspace folders through VS Code's filesystem API, resolves lightweight relative JS/TS imports, and watches filesystem, save, configuration, and diagnostic events. Graph updates are coalesced in 60 ms windows without resetting the timer on each keystroke; scans are serialized. Embedded buffer changes are sent in 40 ms windows. src/graph.js computes add/remove/update events between snapshots. The webview asks for a snapshot when ready, so reloading or hiding the panel does not lose the graph.

src/webview.js renders five levels above and below the focus using instanced meshes, layered rings, and containment/import lines. The visible hierarchy is arranged as nested orbital systems, with spacing reserved for whole child systems. Camera transitions take 850 ms, respect reduced motion, and yield immediately to manual orbit controls. Fit frames the visible neighborhood. Rendering is capped at 300 visible nodes; search can locate files outside the current branch. GPU geometry and materials are released when rebuilding the scene.

The scanner indexes at most observatory.maxFiles files per workspace folder (1,500 by default, at most 5,000). observatory.exclude excludes generated/vendor folders; boolean files.exclude entries are also respected. The UI indicates when indexing hits the limit. The scanner reads at most 256 KB per JS/TS source and performs at most eight concurrent metadata/read operations per workspace folder.

Starter limitations

Indexing caches file lists, source text and parsed TypeScript files in memory. Ordinary edits update cached source and recompute symbol relationships only for the affected workspace root; file creation/deletion, exclusion changes and explicit Rescan still perform full discovery. The cache is not persistent across extension restarts. Empty folders are not represented. .gitignore and conditional files.exclude rules are not interpreted. Import extraction is heuristic: it handles relative static imports, re-exports, require calls, and literal dynamic imports, but not aliases, external packages, or language-server references, and may match commented code. Dependency links display only when both endpoints are visible (search can bring multiple branches into view).

Git churn and custom ignore controls are future work. The interface reuses the supplied Schema-on-Read Observatory HTML styles: its palette, glass panels, typography, scanlines, header, and timeline. Space Grotesk and JetBrains Mono are bundled locally with their OFL licenses in media/fonts. The scene uses matching bloom, radar rings, and stars; dashboard content and graph geometry remain workspace-specific. Narrow layouts keep the explorer available for keyboard and non-WebGL access. The automated tests cover graph changes and relative import resolution; real Extension Host and WebGL interaction should be smoke-tested using F5.

Manual smoke test

1. Open a small JS/TS workspace and run Open 3D Map. Expand a root and folder.
2. Open a file from both the canvas and the list; check the editor and metadata.
3. Create, rename, save, and delete a file; verify the map updates.
4. Search two linked files and toggle dependency links.
5. Run Focus Current File, then close/reopen and hide/reveal the map.
6. Check a multi-root workspace, a scan exceeding the file cap, keyboard-only navigation, reduced motion, and WebGL unavailable.

Symbol navigation and static paths

JS/TS files below 256 KB are analyzed with the bundled TypeScript parser and type checker, using only indexed source text. Files expand into namespaces, classes, functions, arrow functions, and methods. Symbols retain the five-level hierarchy context, and directly connected callers/referenced symbols are also brought into view, subject to the 300-node display cap.

Select a symbol to see incoming/outgoing relationships in the explorer. Click a relationship to focus its other endpoint; click a source entry to open that exact line. Selecting a symbol opens its definition. Green arrows and moving markers indicate caller → callee; red arrows indicate non-call reference → symbol. Motion is illustrative, not execution telemetry, and stops with reduced motion enabled. Calls and references have separate toggles and counters.

The analyzer resolves local declarations, relative imports, aliases, namespaces, re-exports, and methods where TypeScript can determine the receiver. It excludes comments, string content and shadowed imports; references include imports, exports and type syntax. Unresolved external packages, tsconfig path aliases, computed/dynamic dispatch, runtime values, argument/return propagation and cross-workspace imports are not traced. No code is executed. A missing connection does not establish that code is unused. Source sites are capped at 20 per relationship; its count includes all resolved uses.

First-person camera

Click the scene and press W/A/S/D to enter exploration directly, or use First person. Right-drag on the scene also enters exploration and rotates the camera without mouse capture. W/A/S/D moves forward/left/back/right on the horizontal plane; E or Space rises, Q or C descends, and Shift boosts speed. Travel speed scales with the orbital scene size. Click the scene to capture the mouse for free look. If mouse capture is unavailable in the webview, drag the scene to look instead.

Left/Right arrows rotate the camera and Up/Down arrows tilt it. The four on-screen arrow buttons support both clicking and holding, and enter first-person mode automatically. Escape or Exit first person returns to orbit controls at the current position. Fit or selecting a node also returns to orbit navigation. Movement stops on key release, loss of focus, or a hidden tab; typing in search fields does not move the camera. This is free-flight navigation without collision or gravity.

Orbital view

Folders and files form parent systems; classes/functions orbit their files, and methods orbit their classes. Multiple shells use independently tilted and rotated planes, with spacing reserved in three dimensions. Spacing accounts for each visible subtree, keeping neighboring systems apart. Faint orbital tracks replace containment spokes. Reference-style wireframe nodes, luminous cores, crossed rings, additive halos, radar rings, and a grounding grid preserve the original Observatory treatment; overlapping screen labels are suppressed. Select a node to prioritize its call/reference relationships; other visible routes remain present. When symbols are hidden, routes connect through their nearest visible file or class. The details panel keeps exact symbol relationships and source sites. At most 160 relationship routes are drawn at once, with the displayed and total counts shown.

Uncheck Orbiting systems to pause. Orbits also pause for reduced motion, first-person navigation, and camera transitions. The view retains five ancestor and five descendant levels, and Fit frames the visible systems. Orbit animation illustrates hierarchy, not program execution.

Connections animate independently of the orbit pause control. Animate connections controls illustrative trails on calls (green), references (red), and imports (amber). The playback panel names the caller/user and target symbol, including class-qualified method names. Click a playback or route entry to inspect the caller and open source sites. This visualization uses resolved static relationships, not measured runtime events or invented calls. Reduced-motion preferences stop the illustrative animation.

Live edit highlighting

Typing (including unsaved changes, undo and redo) patches the current graph instance through 40 ms embedded-buffer and 60 ms graph-update windows; native edits skip the embedded-buffer window. Edit updates reuse the existing node meshes, decorations, labels and retained connection objects rather than clearing the scene. Camera position, flight mode, animation time and retained orbital paths are preserved; only added/removed items allocate/release render objects. Symbol identities use declaration ancestry, kind and name so inserting text before a declaration does not remove and recreate it. Renaming a declaration or changing its scope creates a new identity. The latest edited file and declarations enclosing the edit use gold; directly related symbols and their files use pink with dashed label/list borders. Matching relationship routes use gold. Highlights appear in the 3D scene, labels and explorer list, and persist until the next edit. Edit context is brought into view without moving the camera; use Fit if needed. Search, file-type filters and link toggles still apply, with the existing 300-node / 160-route limits.

References include statically resolved calls, callbacks, imports, exports, namespace uses and type annotations in indexed JS/TS files. They are not a guarantee of every runtime or language-server reference. Source-site lists retain their 20-site cap. To smoke-test, edit inside a function in an unsaved buffer, then inside a namespace or class; verify gold enclosing declarations and pink callers/targets, follow a reference site, and undo the edit.

Live-update smoke test: focus a function, pause orbits, move the camera, then insert lines above the function and edit its body without saving. Verify that selection, camera and existing node positions stay fixed while highlights and source locations update. Add/remove a function or call and verify that only the corresponding nodes/routes appear/disappear. Repeat in first-person mode and with undo/redo.

Destination framing

Selecting a folder, file or symbol centers that destination in the canvas area left uncovered by the side panels, while fitting the visible neighborhood and its connections. The caption shows the workspace and complete ancestor path (for example, vscode / src), and the selected node has a YOU ARE HERE label. Selection is retained within the 300-node display limit. The camera follows the destination's orbit until manual camera movement or Fit releases it. Fit still frames the whole visible neighborhood. Resizing keeps a followed destination in view; unsaved edits continue to update the existing scene.

Smoke-test a large folder such as vscode/src: select it from the explorer, confirm its marked node is centered between the panels, and repeat after resizing to a narrow window and with reduced motion enabled. Pan or enter first-person mode to verify that following releases immediately.

Labels are clickable, keyboard-focusable navigation buttons (Enter/Space activate). Nodes have a minimum 10-pixel hit radius at distant zoom levels, with their visible rings included. Clicking retains the node pressed at pointer-down even if it moves before release; dragging does not navigate. In first-person mode, clicking a node navigates to it; clicking empty space requests mouse-look. With mouse capture active, picking uses the crosshair.

File, definition and reference-site clicks open inside the 3D view by default. The embedded CodeMirror editor provides file tabs, line numbers, syntax highlighting for JS/TS, JSON, CSS, HTML and Markdown, search, indentation and undo/redo. Other text files open as plain text. Save or Cmd/Ctrl+S saves the active file; typing updates VS Code's shared unsaved document buffer and the live graph. External/native edits sync back when there is no local draft. Conflicting updates preserve your draft and require an explicit reload; copy the draft before discarding it.

Drag the FILE EDITOR header to move the floating panel; resize from its bottom-right corner. Drag the header onto the right-edge Open in VS Code target to detach, or click Open in VS Code ↗. Pending changes synchronize first, then the native editor opens in a separate group with the same unsaved buffer. You can then drag its native tab into another group or window using VS Code's normal controls. Direct arbitrary native-tab docking from the webview is not implemented. Reset position restores the panel; × hides it without discarding drafts. Clicking the file again brings it back. Keyboard users can focus the drag handle and use arrow keys.

Files larger than two million characters and binary files are offered in the native editor. The embedded editor does not include VS Code extensions, language-server completion or debugging; detach to use those features. CodeMirror is bundled locally, with no CDN scripts. Changes use version checks and minimal WorkspaceEdits against documents explicitly opened from indexed nodes. Drafts are retained in webview state; hidden panels keep their live context.

Embedded-editor smoke test: open a file and a symbol, edit without saving, verify live graph changes, save with Cmd/Ctrl+S, undo/redo, switch file tabs, resize and drag the panel, then detach via the right-edge target. Verify identical unsaved text in the native editor and propagation of native edits back into the embedded view. Trigger an external edit while an embedded change is pending to verify conflict recovery. Confirm that typing WASD/arrows never moves the camera.

Live-update performance: unsaved edits do not rediscover or reread workspace files. External file changes read only the changed file. Unchanged source skips semantic analysis; affected roots reuse parsed source files and the previous TypeScript program while rebuilding resolved relationships for correctness. Diagnostics bypass source analysis and update the metric without redrawing the scene. Unchanged graph/highlight results do not trigger webview redraws. Analysis and rendering time are additional to the scheduling windows; these are not end-to-end latency guarantees.

Relationship visibility is independent of scene fog. Routes use screen-space strokes (1.8 px normally, 2.8 px when emphasized) with higher baseline opacity. Arrows, moving markers and collapsed self-loops scale with camera depth so they remain legible in distant overview views. Geometry buffers are reused during animation. Link toggles and the 160-route display cap still apply.

Graph palette, inspired by emerald and gold nebulae: folders/workspaces Teal #35C9A5; files Violet #B594E8; classes/functions/methods/namespaces Emerald lime #88DD64; edited Starlight gold #FFE080; related Lavender #C5A0EF; imports Amber #EBA33D; invocations Green #70DC79; references Copper #F18A57. Near-black green backgrounds, warm ivory text, and translucent glows carry the palette through the scene, panels, and embedded editor.