@jkwd/inbase 0.1.21 → 0.1.23

package/apps/explorer/src/ui/NameInput.tsx

@@ -1,28 +1,63 @@
-import { useEffect, useRef } from 'react'
+import { useEffect, useRef, useState } from 'react'
+import { beginKeyboardIsolation } from '../keyboard'
 
 type NameInputProps = {
   placeholder: string
+  fallbackName?: string
   onCommit: (name: string) => void
   onCancel: () => void
 }
 
-export function NameInput({ placeholder, onCommit, onCancel }: NameInputProps) {
+export function NameInput({
+  placeholder,
+  fallbackName,
+  onCommit,
+  onCancel,
+}: NameInputProps) {
   const input = useRef<HTMLInputElement>(null)
+  const form = useRef<HTMLFormElement>(null)
+  const onCommitRef = useRef(onCommit)
+  const fallbackRef = useRef(fallbackName)
+  onCommitRef.current = onCommit
+  fallbackRef.current = fallbackName
 
   useEffect(() => {
     const timer = window.setTimeout(() => input.current?.focus(), 40)
     return () => window.clearTimeout(timer)
   }, [])
 
+  const commit = (allowFallback: boolean) => {
+    const typed = input.current?.value ?? ''
+    const value = typed.trim()
+      ? typed
+      : allowFallback
+        ? (fallbackRef.current ?? '')
+        : ''
+    if (!value.trim()) return
+    onCommitRef.current(value)
+  }
+
+  useEffect(() => {
+    const onPointerDown = (event: PointerEvent) => {
+      if (event.button !== 0) return
+      const target = event.target
+      if (!(target instanceof Element)) return
+      if (form.current?.contains(target)) return
+      if (!target.closest('.stage')) return
+      commit(true)
+    }
+    window.addEventListener('pointerdown', onPointerDown, true)
+    return () => window.removeEventListener('pointerdown', onPointerDown, true)
+  }, [])
+
   return (
     <form
+      ref={form}
       className="block-name-form"
       onPointerDown={(event) => event.stopPropagation()}
       onSubmit={(event) => {
         event.preventDefault()
-        const value = input.current?.value ?? ''
-        if (!value.trim()) return
-        onCommit(value)
+        commit(false)
       }}
     >
       <input
@@ -43,3 +78,77 @@ export function NameInput({ placeholder, onCommit, onCancel }: NameInputProps) {
     </form>
   )
 }
+
+export function InfoNameField({
+  name,
+  onRename,
+}: {
+  name: string
+  onRename: (name: string) => boolean
+}) {
+  const [value, setValue] = useState(name)
+  const [focused, setFocused] = useState(false)
+  const nameRef = useRef(name)
+  const skipCommit = useRef(false)
+  nameRef.current = name
+
+  useEffect(() => {
+    setValue(name)
+  }, [name])
+
+  useEffect(() => {
+    if (!focused) return
+    return beginKeyboardIsolation()
+  }, [focused])
+
+  const commit = () => {
+    const trimmed = value.trim()
+    if (!trimmed) {
+      setValue(nameRef.current)
+      return
+    }
+    if (trimmed === nameRef.current) return
+    if (!onRename(trimmed)) setValue(nameRef.current)
+  }
+
+  return (
+    <input
+      className="hud-info-name"
+      value={value}
+      aria-label="File name"
+      title="Rename file"
+      autoComplete="off"
+      spellCheck={false}
+      onChange={(event) => setValue(event.target.value)}
+      onFocus={(event) => {
+        setFocused(true)
+        const field = event.currentTarget
+        window.requestAnimationFrame(() => field.select())
+      }}
+      onBlur={() => {
+        setFocused(false)
+        if (skipCommit.current) {
+          skipCommit.current = false
+          return
+        }
+        commit()
+      }}
+      onPointerDown={(event) => event.stopPropagation()}
+      onKeyDown={(event) => {
+        event.stopPropagation()
+        if (event.code === 'Enter') {
+          event.preventDefault()
+          commit()
+          skipCommit.current = true
+          event.currentTarget.blur()
+        }
+        if (event.code === 'Escape') {
+          event.preventDefault()
+          skipCommit.current = true
+          setValue(nameRef.current)
+          event.currentTarget.blur()
+        }
+      }}
+    />
+  )
+}

package/apps/explorer/src/userContext.ts

@@ -28,16 +28,6 @@ export async function fetchUserContext(): Promise<UserContext | null> {
   }
 }
 
-export function persistFollowLook(followLook: boolean) {
-  fetch('/api/user-context', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: `${JSON.stringify({ followLook })}\n`,
-  }).catch(() => {
-    lastWritten = ''
-  })
-}
-
 export function persistShowBranchChanges(showBranchChanges: boolean) {
   fetch('/api/user-context', {
     method: 'POST',
@@ -60,7 +50,6 @@ function flushUserContext() {
   pending = null
   if (!context) return
   const {
-    followLook: _followLook,
     showBranchChanges: _showBranchChanges,
     userCreatedBlocks: _userCreatedBlocks,
     userCreatedIslands: _userCreatedIslands,

package/apps/explorer/src/userCreated.ts

@@ -32,6 +32,7 @@ export function toCreatedFile(block: UserCreatedBlock): FileNode {
     symbols: [],
     imports: [],
     userCreated: true,
+    colorHex: block.colorHex,
   }
 }
 
@@ -174,6 +175,7 @@ export function withUserCreatedGraph(
       files: [],
       children: [],
       userCreated: true,
+      colorHex: island.colorHex,
     })
     if (parent) {
       const parentFolder = folders.get(parent)
@@ -259,7 +261,12 @@ function overlayIslands(
   for (const island of islands) {
     const id = islandKey(island)
     if (layout.folders[id]) {
-      folders[id] = { ...folders[id], added: true, name: island.name || folders[id].name }
+      folders[id] = {
+        ...folders[id],
+        added: true,
+        name: island.name || folders[id].name,
+        colorHex: island.colorHex ?? folders[id].colorHex,
+      }
       continue
     }
     const parentPath = island.parent
@@ -286,6 +293,7 @@ function overlayIslands(
       width,
       depth,
       added: true,
+      colorHex: island.colorHex,
     }
     bridges.push({
       id: `${parentPath}→${id}`,
@@ -534,6 +542,51 @@ export function dropBlueprintSymbolPointer(
   )
 }
 
+export function remapBlueprintFileId(
+  fromId: string,
+  toId: string,
+  data: {
+    functions: PatchSymbolAddition[]
+    variables: PatchSymbolAddition[]
+    imports: PatchImportAddition[]
+    notes: BlueprintNote[]
+    pointers: BlueprintPointer[]
+  },
+) {
+  if (!fromId || fromId === toId) return data
+  return {
+    functions: data.functions.map((item) =>
+      item.file === fromId ? { ...item, file: toId } : item,
+    ),
+    variables: data.variables.map((item) =>
+      item.file === fromId ? { ...item, file: toId } : item,
+    ),
+    imports: data.imports.map((item) => ({
+      ...item,
+      file: item.file === fromId ? toId : item.file,
+      from: item.from === fromId ? toId : item.from,
+    })),
+    notes: data.notes.map((item) =>
+      item.file === fromId ? { ...item, file: toId } : item,
+    ),
+    pointers: data.pointers.map((item) =>
+      item.kind !== 'folder' && item.path === fromId
+        ? { ...item, path: toId }
+        : item,
+    ),
+  }
+}
+
+export function blueprintImportRawFromFile(file: {
+  id: string
+  name: string
+}): string {
+  const trimmed = file.name.trim()
+  const dot = trimmed.lastIndexOf('.')
+  const base = dot > 0 ? trimmed.slice(0, dot) : trimmed
+  return `${base || trimmed} from ${file.id}`
+}
+
 export function parseBlueprintImport(
   raw: string,
   file: string,

package/apps/explorer/vite.config.ts

@@ -8,18 +8,29 @@ import type { IncomingMessage, ServerResponse } from 'node:http'
 import { emptyIntent } from './scripts/patch-lib.mjs'
 import { readBranchChanges } from './scripts/branch-changes.mjs'
 import { writeRunningInstance, isolatedViteConfig, packageDirFromPackage } from '../../bin/project.mjs'
-import { dataDir, targetRoot } from './scripts/target-config.mjs'
+import {
+  dataDir,
+  isWorkspaceDevSwitcherEnabled,
+  setWorkspaceTarget,
+  targetRoot,
+  workspaceDevTargetsState,
+} from './scripts/target-config.mjs'
 import { editorFileUri, openInEditor } from './scripts/open-editor.mjs'
 import {
   answerBlueprint,
   clearDiffSessions,
+  ensureSessionPool,
   continueDiff,
   inspectTargetFile,
   invokeStep,
   listSessionIntents,
   nextAttachSessionId,
+  listOpenSessionIds,
   readActiveSession,
+  recycleDisconnectedSessions,
   requestReplan,
+  notifySessionExplain,
+  requestExplainProposal,
   sendBlueprint,
   sessionIntent,
   setInitialInstruction,
@@ -31,10 +42,20 @@ import {
   stopSession,
   updateBlueprint,
   readBlueprint,
+  listLocalBlueprints,
   setBlueprintHidden,
   clearBlueprint,
   cleanupBlueprint,
 } from './scripts/session-store.mjs'
+import {
+  askExplainQuestion,
+  explainTargetLabel,
+  parseExplainTargetKind,
+  readExplain,
+  requestExplainTarget,
+  setExplainStep,
+  stopExplain,
+} from './scripts/explain-store.mjs'
 
 const here = path.dirname(fileURLToPath(import.meta.url))
 const isolation = isolatedViteConfig(dataDir)
@@ -44,10 +65,12 @@ const scanScript = path.resolve(here, 'scripts/scan-target.mjs')
 
 // The rescan runs with cwd set to the explorer, so hand it the already-resolved
 // root and data dir instead of letting relative env values resolve differently.
-const scanEnv = {
-  ...process.env,
-  VISUAL_CODER_TARGET: targetRoot,
-  INBASE_DATA_DIR: dataDir,
+function scanEnv() {
+  return {
+    ...process.env,
+    VISUAL_CODER_TARGET: targetRoot,
+    INBASE_DATA_DIR: dataDir,
+  }
 }
 
 function readBody(req: IncomingMessage) {
@@ -65,7 +88,7 @@ function rescanTarget(when: string) {
   const scan = spawnSync(process.execPath, [scanScript], {
     cwd: here,
     encoding: 'utf8',
-    env: scanEnv,
+    env: scanEnv(),
   })
   if (scan.status !== 0) {
     console.error(scan.stderr || scan.stdout || `scan failed ${when}`)
@@ -136,14 +159,24 @@ function jsonFilePlugin(): Plugin {
   return {
     name: 'visual-coder-json-files',
     configureServer(server) {
+      const serverPort = server.config.server.port ?? 5173
       writeRunningInstance({
         dataDir,
         targetRoot,
-        port: server.config.server.port ?? 5173,
+        port: serverPort,
       })
-      // Always boot with no LLM session. Leftover diffs and pointers are not restored.
+      // Discard leftover LLM sessions, then open 5 empty chat slots.
       clearDiffSessions(dataDir, targetRoot)
+      ensureSessionPool(dataDir)
       rescanTarget('after discarding leftover LLM sessions')
+      let lastLiveSessionKey = listOpenSessionIds(dataDir).join('\0')
+      function syncDisconnectedSessions() {
+        const recycled = recycleDisconnectedSessions(dataDir, targetRoot)
+        const liveKey = listOpenSessionIds(dataDir).join('\0')
+        const changed = recycled.length > 0 || liveKey !== lastLiveSessionKey
+        lastLiveSessionKey = liveKey
+        if (changed) rescanTarget('after LLM session reset')
+      }
       server.middlewares.use('/api/user-context', (req, res, next) => {
         if (req.method === 'GET') {
           sendJson(res, 200, readUserContext())
@@ -174,6 +207,7 @@ function jsonFilePlugin(): Plugin {
 
       server.middlewares.use('/api/agent-intent', (req, res, next) => {
         if (req.method === 'GET') {
+          syncDisconnectedSessions()
           const url = new URL(req.url ?? '/', 'http://visual-coder.local')
           const sessionId = url.searchParams.get('sessionId')
           const diffId = url.searchParams.get('diffId') ?? undefined
@@ -192,6 +226,7 @@ function jsonFilePlugin(): Plugin {
             nextAttachSessionId: nextAttachSessionId(dataDir),
             intents: listSessionIntents(dataDir, knownFileIds()),
             blueprint: readBlueprint(dataDir),
+            localBlueprints: listLocalBlueprints(dataDir),
           })
           return
         }
@@ -212,6 +247,18 @@ function jsonFilePlugin(): Plugin {
         next()
       })
 
+      server.middlewares.use('/api/explain', (req, res, next) => {
+        if (req.method === 'GET') {
+          sendJson(res, 200, readExplain(dataDir))
+          return
+        }
+        if (req.method === 'POST') {
+          void decideExplain(req, res)
+          return
+        }
+        next()
+      })
+
       server.middlewares.use('/api/inspect-file', (req, res, next) => {
         if (req.method === 'POST') {
           void inspectFile(req, res)
@@ -219,10 +266,113 @@ function jsonFilePlugin(): Plugin {
         }
         next()
       })
+
+      server.middlewares.use('/api/dev-targets', (req, res, next) => {
+        if (req.method === 'GET') {
+          sendJson(res, 200, workspaceDevTargetsState())
+          return
+        }
+        if (req.method === 'POST') {
+          void switchDevTarget(req, res, serverPort)
+          return
+        }
+        next()
+      })
     },
   }
 }
 
+async function switchDevTarget(
+  req: IncomingMessage,
+  res: ServerResponse,
+  port: number,
+) {
+  if (!isWorkspaceDevSwitcherEnabled()) {
+    sendJson(res, 404, { error: 'dev target switcher is not available' })
+    return
+  }
+  try {
+    const body = JSON.parse(await readBody(req)) as { id?: string }
+    const id = body.id?.trim()
+    if (!id || id === 'custom') {
+      sendJson(res, 400, { error: 'id is required' })
+      return
+    }
+    setWorkspaceTarget(id)
+    writeRunningInstance({ dataDir, targetRoot, port })
+    stopExplain(dataDir)
+    clearDiffSessions(dataDir, targetRoot)
+    ensureSessionPool(dataDir)
+    if (!rescanTarget('after switching target')) {
+      sendJson(res, 500, { error: 'scan failed' })
+      return
+    }
+    sendJson(res, 200, {
+      ...workspaceDevTargetsState(),
+      codebase: readCodebase(),
+    })
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'invalid request'
+    sendJson(res, 400, { error: message })
+  }
+}
+
+async function decideExplain(req: IncomingMessage, res: ServerResponse) {
+  try {
+    const body = JSON.parse(await readBody(req)) as {
+      action?: string
+      step?: string | number
+      question?: string
+      kind?: string
+      path?: string
+      name?: string
+      sessionId?: string
+    }
+    if (body.action === 'stop') {
+      sendJson(res, 200, stopExplain(dataDir))
+      return
+    }
+    if (body.action === 'start') {
+      const next = requestExplainTarget(dataDir, {
+        kind: parseExplainTargetKind(body.kind) ?? 'file',
+        path: body.path ?? '',
+        name: body.name,
+        question: body.question,
+      })
+      const sessionId = body.sessionId?.trim()
+      if (sessionId && next.pendingStart) {
+        notifySessionExplain(
+          dataDir,
+          sessionId,
+          explainTargetLabel(next.pendingStart),
+        )
+      }
+      sendJson(res, 200, next)
+      return
+    }
+    if (body.action === 'set_step') {
+      if (body.step == null || body.step === '') {
+        sendJson(res, 400, { error: 'step is required' })
+        return
+      }
+      sendJson(res, 200, setExplainStep(dataDir, body.step))
+      return
+    }
+    if (body.action === 'ask') {
+      sendJson(
+        res,
+        200,
+        askExplainQuestion(dataDir, body.step ?? '', body.question ?? ''),
+      )
+      return
+    }
+    sendJson(res, 400, { error: 'invalid explain action' })
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'invalid request'
+    sendJson(res, 400, { error: message })
+  }
+}
+
 async function inspectFile(req: IncomingMessage, res: ServerResponse) {
   try {
     const body = JSON.parse(await readBody(req)) as {
@@ -262,6 +412,7 @@ async function decideIntent(req: IncomingMessage, res: ServerResponse) {
       step?: number
       stepByStep?: boolean
       hidden?: boolean
+      color?: string
       userCreatedBlocks?: unknown[]
       userCreatedIslands?: unknown[]
       addedFunctions?: unknown[]
@@ -283,6 +434,7 @@ async function decideIntent(req: IncomingMessage, res: ServerResponse) {
       action !== 'invoke' &&
       action !== 'continue' &&
       action !== 'instruct' &&
+      action !== 'explain_proposal' &&
       action !== 'stop' &&
       action !== 'blueprint_yes' &&
       action !== 'blueprint_no' &&
@@ -350,12 +502,15 @@ async function decideIntent(req: IncomingMessage, res: ServerResponse) {
         body.instruction ?? '',
         targetRoot,
       )
+    } else if (action === 'explain_proposal') {
+      requestExplainProposal(dataDir, body.sessionId, body.diffId)
     } else if (action === 'blueprint_yes') {
       answerBlueprint(dataDir, body.sessionId, true)
     } else if (action === 'blueprint_no') {
       answerBlueprint(dataDir, body.sessionId, false)
     } else if (action === 'blueprint_update') {
       updateBlueprint(dataDir, body.sessionId, {
+        color: body.color,
         userCreatedBlocks: body.userCreatedBlocks,
         userCreatedIslands: body.userCreatedIslands,
         addedFunctions: body.addedFunctions,
@@ -365,21 +520,13 @@ async function decideIntent(req: IncomingMessage, res: ServerResponse) {
         pointers: body.pointers,
       })
     } else if (action === 'blueprint_clear') {
-      clearBlueprint(dataDir)
+      clearBlueprint(dataDir, body.color)
     } else if (action === 'blueprint_cleanup') {
-      cleanupBlueprint(dataDir, knownFileIds(), knownFolderPaths())
+      cleanupBlueprint(dataDir, knownFileIds(), knownFolderPaths(), body.color)
     } else if (action === 'blueprint_set_hidden') {
-      setBlueprintHidden(dataDir, Boolean(body.hidden))
+      setBlueprintHidden(dataDir, Boolean(body.hidden), body.color)
     } else if (action === 'blueprint_send') {
-      sendBlueprint(dataDir, body.sessionId, {
-        userCreatedBlocks: body.userCreatedBlocks,
-        userCreatedIslands: body.userCreatedIslands,
-        addedFunctions: body.addedFunctions,
-        addedVariables: body.addedVariables,
-        addedImports: body.addedImports,
-        notes: body.notes,
-        pointers: body.pointers,
-      })
+      sendBlueprint(dataDir, body.sessionId)
     } else if (action === 'setup_session') {
       const manifest = setupSession(dataDir, {
         sessionId: body.sessionId,
@@ -453,11 +600,10 @@ function readUserContext() {
     >
     return {
       ...parsed,
-      followLook: Boolean(parsed.followLook),
       showBranchChanges: Boolean(parsed.showBranchChanges),
     }
   } catch {
-    return { followLook: false, showBranchChanges: false }
+    return { showBranchChanges: false }
   }
 }
 
@@ -468,15 +614,12 @@ async function writeUserContext(req: IncomingMessage, res: ServerResponse) {
     const next = {
       ...existing,
       ...incoming,
-      followLook:
-        typeof incoming.followLook === 'boolean'
-          ? incoming.followLook
-          : Boolean(existing.followLook),
       showBranchChanges:
         typeof incoming.showBranchChanges === 'boolean'
           ? incoming.showBranchChanges
           : Boolean(existing.showBranchChanges),
     }
+    delete next.followLook
     delete next.userCreatedBlocks
     delete next.userCreatedIslands
     fs.mkdirSync(path.dirname(userContextFile), { recursive: true })
@@ -517,6 +660,10 @@ export default defineConfig({
       '@react-three/fiber',
       '@react-three/drei',
     ],
+    exclude: ['kokoro-js', '@huggingface/transformers'],
+  },
+  worker: {
+    format: 'es',
   },
   server: {
     ...isolation.server,

package/bin/inbase.mjs

@@ -18,6 +18,7 @@ import {
 import {
   proposePatch,
   reportPlan,
+  runExplain,
   startSession,
   attachSession,
   waitForApproval,
@@ -33,12 +34,16 @@ Usage:
 
 Agent commands (used by the Cursor skill):
   inbase start-session --session <id> --name "short name"
-  inbase attach [--session <id>]
+  inbase attach [--session <id>] [--color <name>]
   inbase wait-for-blueprint --session <id>
   inbase report-plan --session <id> --feature "name" --steps "one" [--steps "two"]
   inbase wait-for-approval --session <id>
   inbase propose-patch --session <id> [file.patch|-]
   inbase propose-patch --session <id> --clear
+  inbase explain start --question "How does this work?"
+  inbase explain report --question "..." --step "Title" --body "..." --files path
+  inbase explain wait
+  inbase explain stop
 
 Options for run:
   --target <dir>           Project to map (default: current directory)
@@ -112,7 +117,7 @@ async function runServer(args) {
   const local = server.resolvedUrls?.local?.[0] ?? `http://localhost:${port}/`
   console.log(`Inbase is mapping ${targetRoot}`)
   console.log(`Open ${local}`)
-  console.log('Leave this running. In Cursor, the inbase skill talks to this server.')
+  console.log('Leave this running. Open a Cursor chat to connect — 5 chats can be connected at once.')
 }
 
 export async function main(argv = process.argv.slice(2)) {
@@ -175,6 +180,10 @@ export async function main(argv = process.argv.slice(2)) {
     await proposePatch(args)
     return
   }
+  if (command === 'explain') {
+    await runExplain(args)
+    return
+  }
 
   console.error(`Unknown command: ${command}\n`)
   printHelp()

package/bin/project.mjs

@@ -55,13 +55,15 @@ export function resolveOptionalPath(value, fallback) {
 
 export const INSTANCE_FILE = 'instance.json'
 
-function isPidAlive(pid) {
+export function isPidAlive(pid) {
   if (!Number.isInteger(pid)) return true
   try {
     process.kill(pid, 0)
     return true
-  } catch {
-    return false
+  } catch (error) {
+    // Cursor's agent sandbox cannot signal other processes (EPERM) even when
+    // they are alive. POSIX EPERM means the pid exists; only ESRCH is gone.
+    return error?.code === 'EPERM'
   }
 }
 
@@ -131,7 +133,7 @@ export function ensureDataDir(dataDir) {
   if (!fs.existsSync(userContextFile)) {
     fs.writeFileSync(
       userContextFile,
-      `${JSON.stringify({ followLook: false, showBranchChanges: false }, null, 2)}\n`,
+      `${JSON.stringify({ showBranchChanges: false }, null, 2)}\n`,
     )
   }
   return dataDir