@jkwd/inbase 0.1.21 → 0.1.23

package/README.md

@@ -10,7 +10,7 @@ A first-person 3D map of a codebase. Files become blocks, folders become walkabl
 <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%" />
+  <img src="docs/inbase-2.png" alt="Map view of the codebase" 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.
@@ -49,13 +49,13 @@ inbase run --target /path/to/your/project
 
 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), edits live files for each invoked step, and records that step as a patch. Those stored patches are the session record and are applied on every step update.
 
-Sessions start in the map: click **Setup LLM session**, type an **initial instruction**, optionally drop **context files** for the chat to read, optionally place a **blueprint** (`Space` for files, `B` for folders), then open a Cursor chat and run **`/inbase`**. That command connects the chat and starts the work. The layout is the source of truth for the chat. Dropped context files stay with that session until it ends. The blueprint is shared across sessions and stays on the map even after those files and folders exist; use **Hide/Show blueprint**, **Clear blueprint**, or **Cleanup blueprint** (drops planned items that already exist). When a session finishes it is discarded; the shared blueprint remains. Restarting the visualizer also starts with no LLM session; leftover session files are not restored.
+`npx inbase run` opens 5 empty chat slots on the map. Open a regular Cursor chat to connect — it takes the next unconnected slot. You can type an **initial instruction**, drop **context files**, and place a **blueprint** (right-click the map to create files and folders) on a waiting slot before or after that chat connects. The layout is the source of truth for the chat. Dropped context files stay with that session until it ends. The **global** (blue) blueprint is shared across sessions; each session color also has a **local** blueprint that only that chat sees. Both stay on the map even after those files and folders exist. Use the color chips to choose which blueprint you are editing, then **Hide**, **Clear**, or **Cleanup** (drops planned items that already exist). When a session finishes it is discarded and a new empty slot is opened; the global blueprint remains. Restarting the visualizer discards leftover sessions and opens 5 new empty slots.
 
-A normal chat request does not open a session. Use `/inbase` after Setup LLM session, or `/skipinbase [request]` to work outside the map. `/inbase` starts the session immediately; `wait-for-blueprint` only reads the optional blueprint, instruction, and attached files.
+A normal chat request connects to the next empty slot. Use `/coral add a login page` (or `/red`, `/amber`, `/lime`, `/orange`, `/violet`) to connect to that color's slot. `/blue` is the global blueprint, not a chat. Use `/explain How does login work?` while the map is open to jump into **explain mode**, or click the **?** next to a file or folder name to have the LLM explain that path and where it fits. The HUD hides, an X exits, and the LLM walks the question step by step. Each step can dim the rest of the map to 50% opacity, click a block to show import relations, and zoom into a folder. **Ask question** on the current step drills into sub-steps (`7.1`, `7.2`) until you return to the next original step. A step can also open the file **info panel**, highlight functions and vars, and draw an arrow that points at a symbol. Use `/skipinbase [request]` to work outside the map. If Inbase is not running, start it with `npx inbase run`. Only 5 chats can be connected at once. `wait-for-blueprint` only reads the optional blueprint, instruction, and attached files.
 
-If several sessions are open, `/inbase` attaches the oldest session that is still waiting. Sessions that already have an LLM are skipped, and the map window does not need to be focused.
+If several slots are waiting, the next Cursor chat attaches the oldest empty session. Sessions that already have an LLM are skipped, and the map window does not need to be focused.
 
-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 **Create proposal** to start a step, then **Accept proposal** when the patch is ready. With it off, the LLM implements the full plan; you can still walk Previous/Next over the diffs, then **Accept proposal**. Send an alternative instruction from the HUD to update the current proposal, or **Stop** to end the session.
+With **Step by step** on, click **Create proposal** to start a step, then **Accept proposal** when the patch is ready. **Explain proposal** sits next to both and has the LLM walk the current plan step or pending patch on the map. With Step by step off, the LLM implements the full plan; you can still walk Previous/Next over the diffs, then **Accept proposal**. Send an alternative instruction from the HUD to update the current proposal, or **Stop** to end the session.
 
 When no LLM is currently making changes, turn on **Show branch changes** (or press **G**) to highlight the current git branch against its base — committed, unstaged, and untracked files — instead of LLM patch files. The control is disabled while an LLM session is writing or reviewing a patch.
 
@@ -72,8 +72,12 @@ session record and are applied on every step update.
 | `inbase init` | Install the Cursor skill in this repo |
 | `inbase run` | Scan this repo and start the local map |
 | `inbase run --port 5174` | Start on another port |
+| `inbase explain start --question "..."` | Open map-only explain mode |
+| `inbase explain report --step "..."` | Publish explanation steps and map focus |
+| `inbase explain wait` | Wait for a question on a step, or until explain mode exits |
+| `inbase explain stop` | Exit explain mode |
 
-Session commands (`attach`, `wait-for-blueprint`, `report-plan`, `wait-for-approval`, `propose-patch`) are used by the Cursor skill. You do not need to run them yourself.
+Session commands (`attach`, `wait-for-blueprint`, `report-plan`, `wait-for-approval`, `propose-patch`, `explain`) are used by the Cursor skill. You do not need to run them yourself.
 
 ## Editor support
 
@@ -100,7 +104,9 @@ npm install
 npm run dev
 ```
 
-That still maps `apps/example-target` by default. To map a different project without the CLI:
+That still maps `apps/example-target` by default. In the map, **Look at** switches to the complete repository (and later example apps). That control is only in `npm run dev`, not `inbase run`.
+
+To map a different project without the CLI:
 
 ```bash
 VISUAL_CODER_TARGET=/path/to/your/project npm run dev

package/apps/explorer/package.json

@@ -14,6 +14,7 @@
   "dependencies": {
     "@react-three/drei": "^9.117.3",
     "@react-three/fiber": "^8.17.10",
+    "kokoro-js": "^1.2.1",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "three": "^0.170.0"

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

@@ -0,0 +1,135 @@
+export const EXPLAIN_FILE: string
+
+export type ExplainRelation = {
+  from: string
+  to: string
+}
+
+export type ExplainSymbolKind =
+  | 'function'
+  | 'variable'
+  | 'class'
+  | 'file'
+  | 'symbol'
+
+export type ExplainSymbolRef = {
+  kind: ExplainSymbolKind
+  name: string
+}
+
+export type ExplainPendingQuestion = {
+  parent: string
+  question: string
+  from: string
+  fromTitle: string
+}
+
+export type ExplainTargetKind =
+  | 'file'
+  | 'folder'
+  | 'function'
+  | 'variable'
+  | 'class'
+
+export type ExplainPendingStart = {
+  kind: ExplainTargetKind
+  path: string
+  name?: string
+  question: string
+}
+
+export type ExplainStep = {
+  index: string
+  title: string
+  body: string
+  asked: string
+  files: string[]
+  folders: string[]
+  select: string | null
+  zoom: string | null
+  relations: ExplainRelation[]
+  importedBy: boolean
+  info: boolean
+  highlights: ExplainSymbolRef[]
+  point: ExplainSymbolRef | null
+}
+
+export type ExplainPresentation = 'walk' | 'card'
+
+export type ExplainSession = {
+  active: boolean
+  question: string
+  steps: ExplainStep[]
+  currentStep: string
+  pendingQuestion: ExplainPendingQuestion | null
+  pendingStart: ExplainPendingStart | null
+  answering: boolean
+  presentation: ExplainPresentation
+  updatedAt: string | null
+}
+
+export function parseExplainSymbolRef(value: string): ExplainSymbolRef | null
+export function emptyExplain(): ExplainSession
+export function normalizeExplainPresentation(value: unknown): ExplainPresentation
+export function isExplainStepId(value: unknown): value is string
+export function explainStepId(value: unknown, fallback?: string): string
+export function isExplainDescendant(id: unknown, parent: unknown): boolean
+export function topLevelExplainStepId(id: unknown): string
+export function isExplainSubStep(id: unknown): boolean
+export function stripExplainSubSteps(steps: ExplainStep[]): ExplainStep[]
+export function normalizeExplain(value: unknown): ExplainSession
+export function readExplain(dataDir: string): ExplainSession
+export function parseExplainTargetKind(value: unknown): ExplainTargetKind | null
+export function explainTargetLabel(input: {
+  kind?: string
+  path?: string
+  name?: string
+}): string
+export function explainTargetQuestion(
+  kind: ExplainTargetKind,
+  path: string,
+  name?: string,
+): string
+export function startExplain(dataDir: string, question: string): ExplainSession
+export function requestExplainTarget(
+  dataDir: string,
+  input: {
+    kind: ExplainTargetKind
+    path: string
+    name?: string
+    question?: string
+  },
+): ExplainSession
+export function consumeExplainStart(dataDir: string): ExplainPendingStart | null
+export function reportExplain(
+  dataDir: string,
+  input: { question?: string; parent?: string; steps?: unknown[] },
+): ExplainSession
+export function setExplainStep(
+  dataDir: string,
+  step: string | number,
+): ExplainSession
+export function askExplainQuestion(
+  dataDir: string,
+  step: string | number,
+  question: string,
+): ExplainSession
+export function consumeExplainQuestion(
+  dataDir: string,
+): ExplainPendingQuestion | null
+export function stopExplain(dataDir: string): ExplainSession
+export function parseExplainArgs(args: string[]): {
+  question: string
+  parent: string
+  steps: ExplainStep[]
+}
+export function parseExplainCli(args: string[]):
+  | { action: 'stop' }
+  | { action: 'wait' }
+  | { action: 'start'; question: string }
+  | {
+      action: 'report'
+      question: string
+      parent: string
+      steps: ExplainStep[]
+    }