@jkwd/inbase 0.1.7 → 0.1.9

package/README.md

@@ -7,7 +7,13 @@
 
 A first-person 3D map of a JavaScript or TypeScript codebase. Files become blocks, folders become walkable areas, and imports become lines in the air.
 
-Install the package in a project, run `inbase init`, then `inbase run`. Cursor uses the installed skill so code changes go through the visual map.
+<p align="center">
+  <img src="docs/inbase-1.png" alt="First-person walk view of the codebase map" width="47%" />
+  &nbsp;&nbsp;&nbsp;
+  <img src="docs/inbase-2.png" alt="Map view with 3D overlay" width="47%" />
+</p>
+
+Install the package in a project, run `inbase init`, then `inbase run`. Cursor’s LLM then plans and patches through the visual map instead of editing files directly.
 
 The npm package is `@jkwd/inbase` (npm blocks the unscoped name `inbase`). The command is still `inbase`.
 
@@ -35,7 +41,21 @@ Open the printed URL (http://localhost:5173 by default), click the scene, then w
 inbase run --target /path/to/your/project
 ```
 
-`inbase init` copies a Cursor skill into `.cursor/skills/inbase/` and gitignores `.inbase/`. After that, ask Cursor to change source files in this repo — it should follow the visual plan/patch workflow while `inbase run` is up.
+`inbase init` copies a Cursor skill into `.cursor/skills/inbase/` and gitignores `.inbase/`. Keep `inbase run` open, then ask Cursor to change source files — the LLM follows the visual plan and patch loop described below.
+
+## LLM integration
+
+<img src="docs/inbase-llm.png" alt="LLM working through a plan in the heads-up display overlay" align="left" width="280" hspace="16" />
+
+Inbase does not call a model itself. The visual coding loop currently supports **Cursor**. The installed skill makes the agent work through the map: it reports a plan, waits on the **HUD** (heads-up display — the overlay panel on the 3D map), and publishes each step as a patch you can walk before it is applied.
+
+When a chat starts, that overlay asks whether to set up a **blueprint**. **Create blueprint** lets you place files (`Space`) and folders (`B`), then **Send blueprint** — that layout is the source of truth for the chat. **Let LLM continue** skips placement and lets the agent choose files from the request.
+
+Turn on **Make LLM look where I look** if the agent should prefer the island you are standing on and the blocks you are facing. With **Step by step** on, click **Run step** for each patch. With it off, the LLM implements the full plan; you can still walk Previous/Next over the diffs, then **Complete**. Send an alternative instruction from the HUD to revise the remaining plan, or **Stop** to end the session.
+
+The LLM never writes project files itself. Patches apply when you run or complete steps in the visualizer.
+
+<br clear="all" />
 
 ## Commands
 
@@ -47,6 +67,10 @@ inbase run --target /path/to/your/project
 
 Session commands (`start-session`, `wait-for-blueprint`, `report-plan`, `wait-for-approval`, `propose-patch`) are used by the Cursor skill. You do not need to run them yourself.
 
+## Editor support
+
+The map runs in the browser. The LLM plan and patch loop currently works in **Cursor** only (`inbase init` installs a skill into `.cursor/skills/inbase/`).
+
 ## Language support
 
 Source files (`.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs`) become blocks with **functions**, **classes**, and **variables**, plus import edges from `import` and `require()`. Styles and docs (`.css`, `.scss`, `.html`, `.json`, `.md`) show up as blocks without symbols. Only relative specifiers (`./`, `../`) become edges — package names like `react` or `@angular/core` do not.

package/apps/explorer/scripts/session-store.d.ts

@@ -62,6 +62,10 @@ export function discardInactiveDiffSessions(
   targetRoot?: string | null,
   waiterIds?: Iterable<string>,
 ): string[]
+export function clearDiffSessions(
+  dataDir: string,
+  targetRoot?: string | null,
+): void
 export function listSessionIntents(
   dataDir: string,
   knownFileIds?: string[],

package/apps/explorer/scripts/session-store.mjs

@@ -1154,6 +1154,22 @@ export function discardInactiveDiffSessions(
   return liveIds
 }
 
+export function clearDiffSessions(dataDir, targetRoot = null) {
+  for (const sessionId of listStoredSessionIds(dataDir)) {
+    discardStoredSession(dataDir, sessionId, targetRoot)
+  }
+  writeActiveSession(dataDir, null)
+  writeBlueprintSession(dataDir, null)
+
+  const root = diffSessionsRoot(dataDir)
+  fs.mkdirSync(root, { recursive: true })
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    if (entry.name === '.gitkeep') continue
+    fs.rmSync(path.join(root, entry.name), { recursive: true, force: true })
+  }
+  unstageDiffSessionArtifacts(dataDir, targetRoot)
+}
+
 export function stopSession(dataDir, sessionId, targetRoot = null) {
   const safeId = assertSessionId(sessionId)
   writeStoppedMarker(dataDir, safeId)

package/apps/explorer/src/App.tsx

@@ -1,7 +1,7 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { Canvas } from '@react-three/fiber'
 import { emptyIntent, fetchAgentIntent, fetchAgentIntents, inspectTargetFile, performAgentAction, persistSessionBlueprint } from './agentIntent'
-import { fetchCodebase } from './codebase'
+import { fetchCodebase, updateCodebase } from './codebase'
 import {
   layoutWorld,
   markCreatedFolders,
@@ -72,17 +72,35 @@ function intentSignature(intent: AgentIntent) {
 export default function App() {
   const [graph, setGraph] = useState<CodebaseGraph | null>(null)
   const [loadError, setLoadError] = useState<string | null>(null)
+  const [updatingModel, setUpdatingModel] = useState(false)
+  const updatingModelRef = useRef(false)
 
-  const refreshGraph = useCallback(async () => {
-    const next = await fetchCodebase()
+  const applyGraph = useCallback((next: CodebaseGraph | null, failed: string) => {
     if (next) {
       setGraph(next)
       setLoadError(null)
-      return
+      return true
     }
-    setLoadError((current) => current ?? 'Could not load the project map.')
+    setLoadError((current) => current ?? failed)
+    return false
   }, [])
 
+  const refreshGraph = useCallback(async () => {
+    applyGraph(await fetchCodebase(), 'Could not load the project map.')
+  }, [applyGraph])
+
+  const updateModel = useCallback(async () => {
+    if (updatingModelRef.current) return
+    updatingModelRef.current = true
+    setUpdatingModel(true)
+    try {
+      applyGraph(await updateCodebase(), 'Could not update the project map.')
+    } finally {
+      updatingModelRef.current = false
+      setUpdatingModel(false)
+    }
+  }, [applyGraph])
+
   useEffect(() => {
     void refreshGraph()
   }, [refreshGraph])
@@ -95,15 +113,26 @@ export default function App() {
     )
   }
 
-  return <Explorer graph={graph} onRefreshGraph={refreshGraph} />
+  return (
+    <Explorer
+      graph={graph}
+      onRefreshGraph={refreshGraph}
+      onUpdateModel={updateModel}
+      updatingModel={updatingModel}
+    />
+  )
 }
 
 function Explorer({
   graph,
   onRefreshGraph,
+  onUpdateModel,
+  updatingModel,
 }: {
   graph: CodebaseGraph
   onRefreshGraph: () => Promise<void>
+  onUpdateModel: () => Promise<void>
+  updatingModel: boolean
 }) {
   const [intents, setIntents] = useState<AgentIntent[]>([])
   const [focusedSessionId, setFocusedSessionId] = useState<string | null>(null)
@@ -238,7 +267,6 @@ function Explorer({
   const [inspectTick, setInspectTick] = useState(0)
   const [flyTo, setFlyTo] = useState<FlyTo | null>(null)
   const [locked, setLocked] = useState(false)
-  const [currentFolder, setCurrentFolder] = useState(graph.targetName)
   const [followLook, setFollowLook] = useState(false)
   const [importedBy, setImportedBy] = useState(false)
   const [changePathsOnly, setChangePathsOnly] = useState(false)
@@ -287,6 +315,7 @@ function Explorer({
   const toggleMap = useCallback(() => {
     if (mode === 'walk') {
       setLandAt(walkPos.current)
+      setFlyTo(null)
       setLocked(false)
       document.exitPointerLock()
       setMode('map')
@@ -322,6 +351,7 @@ function Explorer({
     (fileId: string, fly: boolean) => {
       const placed = layout.files[fileId]
       if (!placed) return
+      const from = walkPos.current
       const [x, z] = standInFront(placed)
       walkPos.current = [x, z]
       setAimedRelation(null)
@@ -330,6 +360,7 @@ function Explorer({
         fly
           ? {
               nonce: Date.now(),
+              from: [from[0], from[1]],
               lookAt: [placed.position[0], placed.position[1], placed.position[2]],
             }
           : null,
@@ -1099,7 +1130,6 @@ function Explorer({
             onSelect={selectFile}
             onSelectFolder={selectFolder}
             onLockedChange={setLocked}
-            onFolderChange={setCurrentFolder}
             onLand={landFromMap}
             onWalkPosition={rememberWalk}
             onContext={persistUserContext}
@@ -1145,7 +1175,6 @@ function Explorer({
         landAt={landAt}
         aimedRelation={aimedRelation}
         aimedFileId={aimedFileId}
-        currentFolder={currentFolder}
         intent={intent}
         intents={intents}
         focusedSessionId={focusedSessionId}
@@ -1156,6 +1185,8 @@ function Explorer({
         onWalk={openWalk}
         followLook={followLook}
         onToggleFollowLook={toggleFollowLook}
+        onUpdateModel={onUpdateModel}
+        updatingModel={updatingModel}
         importedBy={importedBy}
         onToggleImportedBy={toggleImportedBy}
         changePathsOnly={changePathsOnly}

package/apps/explorer/src/codebase.ts

@@ -1,14 +1,32 @@
 import type { CodebaseGraph } from './types'
 
+function parseCodebase(data: unknown): CodebaseGraph | null {
+  if (
+    !data ||
+    typeof data !== 'object' ||
+    !Array.isArray((data as CodebaseGraph).files) ||
+    !Array.isArray((data as CodebaseGraph).folders)
+  ) {
+    return null
+  }
+  return data as CodebaseGraph
+}
+
 export async function fetchCodebase(): Promise<CodebaseGraph | null> {
   try {
     const response = await fetch(`/api/codebase?t=${Date.now()}`)
     if (!response.ok) return null
-    const data = (await response.json()) as CodebaseGraph
-    if (!data || !Array.isArray(data.files) || !Array.isArray(data.folders)) {
-      return null
-    }
-    return data
+    return parseCodebase(await response.json())
+  } catch {
+    return null
+  }
+}
+
+export async function updateCodebase(): Promise<CodebaseGraph | null> {
+  try {
+    const response = await fetch('/api/codebase', { method: 'POST' })
+    if (!response.ok) return null
+    return parseCodebase(await response.json())
   } catch {
     return null
   }

package/apps/explorer/src/index.css

@@ -174,11 +174,22 @@ button {
   padding: 8px 12px;
 }
 
+.hud-button:disabled {
+  opacity: 0.55;
+  cursor: default;
+}
+
 .hud-button[data-active='true'] {
   border-color: #5d9ec4;
   color: #d7eef8;
 }
 
+.hud-bottom-actions {
+  display: flex;
+  gap: 8px;
+  flex: none;
+}
+
 .hud-chip,
 .hud-panel {
   background: rgba(25, 28, 34, 0.86);
@@ -240,6 +251,51 @@ button {
   background: rgba(25, 28, 34, 0.94);
 }
 
+.map-you-are-here {
+  display: grid;
+  justify-items: center;
+  transform: translateY(-10px);
+}
+
+.map-you-are-here-pin {
+  width: 18px;
+  height: 18px;
+  background: #e8c36a;
+  border: 2px solid #fff8e4;
+  border-radius: 50% 50% 50% 0;
+  box-shadow:
+    0 0 0 0 rgba(232, 195, 106, 0.7),
+    0 2px 10px rgba(0, 0, 0, 0.55);
+  transform: rotate(-45deg);
+  animation: map-you-are-here-pulse 1.7s ease-out infinite;
+}
+
+.map-you-are-here-pin::after {
+  content: '';
+  position: absolute;
+  inset: 4px;
+  border-radius: 50%;
+  background: #1a1408;
+}
+
+@keyframes map-you-are-here-pulse {
+  0% {
+    box-shadow:
+      0 0 0 0 rgba(232, 195, 106, 0.75),
+      0 2px 10px rgba(0, 0, 0, 0.55);
+  }
+  70% {
+    box-shadow:
+      0 0 0 12px rgba(232, 195, 106, 0),
+      0 2px 10px rgba(0, 0, 0, 0.55);
+  }
+  100% {
+    box-shadow:
+      0 0 0 0 rgba(232, 195, 106, 0),
+      0 2px 10px rgba(0, 0, 0, 0.55);
+  }
+}
+
 .hud-bottom {
   position: absolute;
   left: 0;
@@ -256,12 +312,119 @@ button {
   pointer-events: auto;
 }
 
-.hud-hints {
+.hud-instructions-overlay {
+  position: absolute;
+  inset: 0;
+  z-index: 20;
+  display: grid;
+  place-items: center;
+  background: rgba(25, 28, 34, 0.72);
+  pointer-events: auto;
+}
+
+.hud-instructions-card {
+  width: min(520px, calc(100% - 32px));
+  max-height: min(80dvh, 720px);
+  overflow: auto;
+  padding: 24px;
+  background: var(--vc-editor);
+  border: 1px solid var(--vc-border);
+}
+
+.hud-instructions-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  margin-bottom: 16px;
+}
+
+.hud-instructions-header h1 {
+  margin: 0;
+  font-size: 20px;
+  font-weight: 600;
+}
+
+.hud-instructions-sections {
+  display: flex;
+  flex-direction: column;
+  gap: 22px;
+}
+
+.hud-instructions-section h2 {
   display: flex;
+  align-items: center;
   gap: 8px;
-  flex-wrap: wrap;
-  color: #9aa3b2;
+  margin: 0 0 10px;
+  color: #8b95a5;
   font-size: 12px;
+  font-weight: 600;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.hud-instructions-section[data-current='true'] h2 {
+  color: #d7eef8;
+}
+
+.hud-instructions-current {
+  padding: 2px 6px;
+  border: 1px solid #5d9ec4;
+  border-radius: 3px;
+  color: #d7eef8;
+  font-size: 10px;
+  letter-spacing: 0.04em;
+}
+
+.hud-instructions-list {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.hud-instructions-list .hud-instruction {
+  display: grid;
+  grid-template-columns: minmax(7.5rem, auto) 1fr;
+  align-items: center;
+  gap: 12px;
+  margin-top: 0;
+  color: #b7c0ce;
+  font-size: 14px;
+  line-height: 1.45;
+}
+
+.hud-instructions-list .hud-instruction:not(:has(.hud-instruction-keys)) {
+  grid-template-columns: 1fr;
+}
+
+.hud-instruction-keys {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+  gap: 4px;
+}
+
+.hud-instructions-card kbd {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 1.6rem;
+  height: 1.6rem;
+  padding: 0 7px;
+  border: 1px solid #3a4250;
+  border-bottom-width: 2px;
+  border-radius: 4px;
+  background: var(--vc-surface);
+  color: #e7ebf2;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 11px;
+  font-weight: 600;
+  letter-spacing: 0.02em;
+  line-height: 1;
+  white-space: nowrap;
 }
 
 .hud-icon-row {
@@ -419,6 +582,8 @@ button {
 
 .hud-thumbnail {
   position: fixed;
+  display: flex;
+  flex-direction: column;
   right: 20px;
   bottom: 72px;
   left: auto;
@@ -431,6 +596,19 @@ button {
   box-shadow: 0 8px 24px rgba(0, 0, 0, 0.45);
 }
 
+.hud-right-stack .hud-thumbnail[data-maximized='true'],
+.hud-thumbnail[data-maximized='true'] {
+  position: fixed;
+  top: 68px;
+  right: 20px;
+  bottom: 72px;
+  left: 20px;
+  z-index: 40;
+  width: auto;
+  max-width: none;
+  margin-top: 0;
+}
+
 .hud-thumbnail-bar {
   display: flex;
   align-items: center;
@@ -555,13 +733,21 @@ button {
   position: relative;
   width: 100%;
   height: 220px;
+  min-height: 0;
+  flex: none;
   background: #000;
   touch-action: none;
   user-select: none;
   cursor: grab;
 }
 
-.hud-thumbnail-stage[data-panning='true'] {
+.hud-thumbnail[data-maximized='true'] .hud-thumbnail-stage {
+  height: auto;
+  flex: 1 1 auto;
+}
+
+.hud-thumbnail-stage[data-panning='true'],
+.hud-thumbnail-stage[data-orbiting='true'] {
   cursor: grabbing;
 }
 

package/apps/explorer/src/scene/Bridge.tsx

@@ -183,18 +183,63 @@ function segmentDir(from: [number, number], to: [number, number]): [number, numb
   return [dx / length, dz / length]
 }
 
+function signFontSize(label: string, lintelW: number) {
+  return Math.min(0.42, (lintelW - 0.55) / Math.max(label.length * 0.62, 3))
+}
+
+function GateSign({
+  z,
+  rotY,
+  signY,
+  lintelW,
+  label,
+}: {
+  z: number
+  rotY: number
+  signY: number
+  lintelW: number
+  label: string
+}) {
+  return (
+    <group>
+      <mesh position={[0, signY, z]}>
+        <boxGeometry args={[lintelW - 0.18, SIGN_H, SIGN_D]} />
+        <meshLambertMaterial color={SIGN_COLOR} />
+      </mesh>
+      <Suspense fallback={null}>
+        <Text
+          position={[0, signY, z + Math.sign(z) * (SIGN_D / 2 + 0.01)]}
+          rotation={[0, rotY, 0]}
+          fontSize={signFontSize(label, lintelW)}
+          color="#e7ebf2"
+          anchorX="center"
+          anchorY="middle"
+          maxWidth={lintelW - 0.4}
+          overflowWrap="break-word"
+          outlineWidth={0.02}
+          outlineColor="#07080b"
+        >
+          {label}
+        </Text>
+      </Suspense>
+    </group>
+  )
+}
+
 function Gate({
   x,
   z,
   faceX,
   faceZ,
   label,
+  backLabel,
 }: {
   x: number
   z: number
   faceX: number
   faceZ: number
   label: string
+  backLabel: string
 }) {
   const rotationY = Math.atan2(faceX, faceZ)
   const postX = CONFIG.bridgeWidth / 2 + POST_W / 2
@@ -204,7 +249,6 @@ function Gate({
   const capY = POST_H + LINTEL_H + CAP_H / 2
   const signY = POST_H + LINTEL_H / 2
   const signZ = POST_D / 2 + SIGN_D / 2 + 0.01
-  const fontSize = Math.min(0.42, (lintelW - 0.55) / Math.max(label.length * 0.62, 3))
 
   return (
     <group position={[x, 0, z]} rotation={[0, rotationY, 0]}>
@@ -224,25 +268,16 @@ function Gate({
         <boxGeometry args={[capW, CAP_H, POST_D + 0.08]} />
         <meshLambertMaterial color={CAP_COLOR} />
       </mesh>
-      <mesh position={[0, signY, signZ]}>
-        <boxGeometry args={[lintelW - 0.18, SIGN_H, SIGN_D]} />
-        <meshLambertMaterial color={SIGN_COLOR} />
-      </mesh>
-      <Suspense fallback={null}>
-        <Text
-          position={[0, signY, signZ + SIGN_D / 2 + 0.01]}
-          fontSize={fontSize}
-          color="#e7ebf2"
-          anchorX="center"
-          anchorY="middle"
-          maxWidth={lintelW - 0.4}
-          overflowWrap="break-word"
-          outlineWidth={0.02}
-          outlineColor="#07080b"
-        >
-          {label}
-        </Text>
-      </Suspense>
+      <GateSign z={signZ} rotY={0} signY={signY} lintelW={lintelW} label={label} />
+      {backLabel ? (
+        <GateSign
+          z={-signZ}
+          rotY={Math.PI}
+          signY={signY}
+          lintelW={lintelW}
+          label={backLabel}
+        />
+      ) : null}
     </group>
   )
 }
@@ -292,6 +327,7 @@ export function Bridge({ bridge, folders }: BridgeProps) {
           faceX={-startDir[0]}
           faceZ={-startDir[1]}
           label={bridge.label}
+          backLabel={bridge.fromLabel}
         />
       )}
       {end && endDir && (
@@ -301,6 +337,7 @@ export function Bridge({ bridge, folders }: BridgeProps) {
           faceX={endDir[0]}
           faceZ={endDir[1]}
           label={bridge.fromLabel}
+          backLabel={bridge.label}
         />
       )}
     </group>

package/apps/explorer/src/scene/MapView.tsx

@@ -1,5 +1,5 @@
 import { useEffect, useLayoutEffect, useMemo, useRef } from 'react'
-import { useThree } from '@react-three/fiber'
+import { useFrame, useThree } from '@react-three/fiber'
 import { Html, MapControls, OrthographicCamera } from '@react-three/drei'
 import * as THREE from 'three'
 import { folderAt, worldBounds } from '../layout'
@@ -280,7 +280,7 @@ export function MapView({
             key={folder.path}
             position={[folder.x, 14, folder.z + 1.35]}
             center
-            zIndexRange={[1, 0]}
+            zIndexRange={[80, 50]}
             style={{ pointerEvents: 'none' }}
           >
             <div
@@ -307,7 +307,7 @@ export function MapView({
             </div>
           </Html>
         ))}
-      {marker && <LandMarker marker={marker} />}
+      {enabled && marker && <LandMarker marker={marker} />}
     </>
   )
 }
@@ -323,12 +323,41 @@ function folderKindLabel(
 }
 
 function LandMarker({ marker }: { marker: [number, number] }) {
+  const camera = useThree((state) => state.camera)
+  const ring = useRef<THREE.Group>(null)
+
+  useFrame(() => {
+    if (!(camera instanceof THREE.OrthographicCamera) || !ring.current) return
+    const size = THREE.MathUtils.clamp(16 / Math.max(camera.zoom, 0.04), 2.4, 22)
+    ring.current.scale.setScalar(size)
+  })
+
   return (
-    <group position={[marker[0], 0.2, marker[1]]}>
-      <mesh rotation={[-Math.PI / 2, 0, 0]}>
-        <ringGeometry args={[0.55, 0.85, 24]} />
-        <meshBasicMaterial color="#e8c36a" side={THREE.DoubleSide} />
-      </mesh>
+    <group position={[marker[0], 0.35, marker[1]]}>
+      <group ref={ring}>
+        <mesh rotation={[-Math.PI / 2, 0, 0]}>
+          <circleGeometry args={[0.62, 32]} />
+          <meshBasicMaterial color="#e8c36a" transparent opacity={0.28} />
+        </mesh>
+        <mesh rotation={[-Math.PI / 2, 0, 0]} position={[0, 0.02, 0]}>
+          <ringGeometry args={[0.5, 0.72, 32]} />
+          <meshBasicMaterial color="#e8c36a" side={THREE.DoubleSide} />
+        </mesh>
+        <mesh rotation={[-Math.PI / 2, 0, 0]} position={[0, 0.04, 0]}>
+          <circleGeometry args={[0.18, 20]} />
+          <meshBasicMaterial color="#fff6d4" />
+        </mesh>
+      </group>
+      <Html
+        center
+        zIndexRange={[20, 10]}
+        style={{ pointerEvents: 'none' }}
+        position={[0, 2.8, 0]}
+      >
+        <div className="map-you-are-here" role="img" aria-label="You are here">
+          <span className="map-you-are-here-pin" aria-hidden="true" />
+        </div>
+      </Html>
     </group>
   )
 }