@jkwd/inbase 0.1.13 → 0.1.16

package/apps/explorer/src/agentIntent.ts

@@ -1,6 +1,7 @@
 import type {
   AgentIntent,
   AgentIntentBundle,
+  BlueprintNote,
   PatchImport,
   PatchImportAddition,
   PatchSymbolAddition,
@@ -8,7 +9,11 @@ import type {
   UserCreatedIsland,
   WorkflowAction,
 } from './types'
-import { parseUserCreatedBlocks, parseUserCreatedIslands } from './userCreated'
+import {
+  parseBlueprintNotes,
+  parseUserCreatedBlocks,
+  parseUserCreatedIslands,
+} from './userCreated'
 
 function normalizeImports(value: unknown): PatchImport[] {
   if (!Array.isArray(value)) return []
@@ -98,12 +103,15 @@ export const emptyIntent: AgentIntent = {
   initialInstruction: null,
   creationMode: false,
   canEnterBlueprint: false,
+  blueprintHidden: false,
+  blueprintRevision: 0,
   blueprintSessionId: null,
   userCreatedBlocks: [],
   userCreatedIslands: [],
   blueprintFunctions: [],
   blueprintVariables: [],
   blueprintImports: [],
+  blueprintNotes: [],
 }
 
 function normalize(data: Partial<AgentIntent> | null | undefined): AgentIntent {
@@ -149,6 +157,9 @@ function normalize(data: Partial<AgentIntent> | null | undefined): AgentIntent {
       typeof data?.initialInstruction === 'string' ? data.initialInstruction : null,
     creationMode: Boolean(data?.creationMode),
     canEnterBlueprint: Boolean(data?.canEnterBlueprint),
+    blueprintHidden: Boolean(data?.blueprintHidden),
+    blueprintRevision:
+      typeof data?.blueprintRevision === 'number' ? data.blueprintRevision : 0,
     blueprintSessionId:
       typeof data?.blueprintSessionId === 'string'
         ? data.blueprintSessionId
@@ -158,18 +169,42 @@ function normalize(data: Partial<AgentIntent> | null | undefined): AgentIntent {
     blueprintFunctions: normalizeSymbolAdditions(data?.blueprintFunctions),
     blueprintVariables: normalizeSymbolAdditions(data?.blueprintVariables),
     blueprintImports: normalizeImportAdditions(data?.blueprintImports),
+    blueprintNotes: parseBlueprintNotes(data?.blueprintNotes),
+  }
+}
+
+function normalizeBlueprint(data: Partial<AgentIntentBundle['blueprint']> | null | undefined) {
+  return {
+    hidden: Boolean(data?.hidden),
+    revision: typeof data?.revision === 'number' ? data.revision : 0,
+    enabled: Boolean(data?.enabled),
+    userCreatedBlocks: parseUserCreatedBlocks(data?.userCreatedBlocks),
+    userCreatedIslands: parseUserCreatedIslands(data?.userCreatedIslands),
+    addedFunctions: normalizeSymbolAdditions(data?.addedFunctions),
+    addedVariables: normalizeSymbolAdditions(data?.addedVariables),
+    addedImports: normalizeImportAdditions(data?.addedImports),
+    notes: parseBlueprintNotes(data?.notes),
   }
 }
 
 export async function fetchAgentIntents(): Promise<AgentIntentBundle> {
   const query = new URLSearchParams({ t: String(Date.now()) })
   const response = await fetch(`/api/agent-intent?${query}`)
-  if (!response.ok) return { focusedSessionId: null, nextAttachSessionId: null, intents: [] }
+  const emptyBlueprint = normalizeBlueprint(null)
+  if (!response.ok) {
+    return {
+      focusedSessionId: null,
+      nextAttachSessionId: null,
+      intents: [],
+      blueprint: emptyBlueprint,
+    }
+  }
   const data = (await response.json()) as {
     focusedSessionId?: string | null
     nextAttachSessionId?: string | null
     intents?: unknown
     sessionId?: string | null
+    blueprint?: Partial<AgentIntentBundle['blueprint']>
   } & Partial<AgentIntent>
   if (Array.isArray(data.intents)) {
     return {
@@ -182,6 +217,7 @@ export async function fetchAgentIntents(): Promise<AgentIntentBundle> {
       intents: data.intents
         .map((intent) => normalize(intent as Partial<AgentIntent>))
         .filter((intent) => Boolean(intent.sessionId)),
+      blueprint: normalizeBlueprint(data.blueprint),
     }
   }
   const intent = normalize(data)
@@ -189,6 +225,23 @@ export async function fetchAgentIntents(): Promise<AgentIntentBundle> {
     focusedSessionId: intent.sessionId,
     nextAttachSessionId: intent.awaitingAttach ? intent.sessionId : null,
     intents: intent.sessionId ? [intent] : [],
+    blueprint: normalizeBlueprint(data.blueprint ?? {
+      hidden: intent.blueprintHidden,
+      revision: intent.blueprintRevision,
+      enabled:
+        intent.userCreatedBlocks.length > 0 ||
+        intent.userCreatedIslands.length > 0 ||
+        intent.blueprintFunctions.length > 0 ||
+        intent.blueprintVariables.length > 0 ||
+        intent.blueprintImports.length > 0 ||
+        intent.blueprintNotes.length > 0,
+      userCreatedBlocks: intent.userCreatedBlocks,
+      userCreatedIslands: intent.userCreatedIslands,
+      addedFunctions: intent.blueprintFunctions,
+      addedVariables: intent.blueprintVariables,
+      addedImports: intent.blueprintImports,
+      notes: intent.blueprintNotes,
+    }),
   }
 }
 
@@ -219,6 +272,7 @@ export async function performAgentAction(
     addedFunctions?: PatchSymbolAddition[]
     addedVariables?: PatchSymbolAddition[]
     addedImports?: PatchImportAddition[]
+    notes?: BlueprintNote[]
   } = {},
 ) {
   const response = await fetch('/api/agent-intent', {
@@ -234,16 +288,17 @@ export async function performAgentAction(
 }
 
 export function persistSessionBlueprint(
-  sessionId: string,
+  sessionId: string | null | undefined,
   payload: {
     userCreatedBlocks: UserCreatedBlock[]
     userCreatedIslands: UserCreatedIsland[]
     addedFunctions?: PatchSymbolAddition[]
     addedVariables?: PatchSymbolAddition[]
     addedImports?: PatchImportAddition[]
+    notes?: BlueprintNote[]
   },
 ) {
-  fetch('/api/agent-intent', {
+  return fetch('/api/agent-intent', {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({
@@ -252,7 +307,34 @@ export function persistSessionBlueprint(
       ...payload,
     }),
   }).catch(() => {
-    // Keep local drafts if the session handshake is no longer open.
+    // Keep local drafts if the visualizer could not save the shared blueprint.
+  })
+}
+
+export function persistBlueprintHidden(hidden: boolean) {
+  return fetch('/api/agent-intent', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      action: 'blueprint_set_hidden',
+      hidden,
+    }),
+  })
+}
+
+export function persistBlueprintClear() {
+  return fetch('/api/agent-intent', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ action: 'blueprint_clear' }),
+  })
+}
+
+export function persistBlueprintCleanup() {
+  return fetch('/api/agent-intent', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ action: 'blueprint_cleanup' }),
   })
 }
 

package/apps/explorer/src/index.css

@@ -188,6 +188,7 @@ button {
   display: flex;
   gap: 8px;
   flex: none;
+  flex-wrap: wrap;
 }
 
 .hud-chip,
@@ -1389,6 +1390,102 @@ button {
   border-color: #9ad8ff;
 }
 
+.hud-item-actions {
+  display: flex;
+  align-items: center;
+  gap: 2px;
+  flex: none;
+}
+
+.hud-item-note {
+  flex: none;
+  padding: 2px 6px;
+  color: #b7c0ce;
+  background: transparent;
+  border: 1px solid #3a4250;
+  cursor: pointer;
+  font-size: 11px;
+}
+
+.hud-item-note:hover,
+.hud-item-note:focus-visible,
+.hud-item-note[data-open='true'] {
+  border-color: #9ad8ff;
+  color: #d7eef8;
+}
+
+.hud-item-note[data-has-note='true'],
+.hud-button[data-has-note='true'] {
+  border-color: #5d9ec4;
+  color: #d7eef8;
+}
+
+.hud-note-overlay {
+  position: absolute;
+  inset: 0;
+  z-index: 22;
+  display: grid;
+  place-items: center;
+  padding: 24px;
+  background: rgba(12, 14, 18, 0.82);
+  pointer-events: auto;
+}
+
+.hud-note-card {
+  width: min(1400px, 100%);
+  height: min(92dvh, 100%);
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  padding: 24px 24px 20px;
+  background: var(--vc-editor);
+  border: 1px solid var(--vc-border);
+}
+
+.hud-note-header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 16px;
+  flex: none;
+}
+
+.hud-note-heading {
+  min-width: 0;
+}
+
+.hud-note-header h1 {
+  margin: 0;
+  font-size: 20px;
+  font-weight: 600;
+}
+
+.hud-note-subtitle {
+  margin: 6px 0 0;
+  color: #8b95a5;
+  font-size: 13px;
+  line-height: 1.4;
+  word-break: break-all;
+}
+
+.hud-note-field {
+  width: 100%;
+  min-height: 0;
+  flex: 1;
+  resize: none;
+  box-sizing: border-box;
+  padding: 16px;
+  color: #e7ebf2;
+  background: rgba(25, 28, 34, 0.96);
+  border: 1px solid #3a4250;
+  font: 15px/1.55 ui-monospace, SFMono-Regular, Menlo, monospace;
+  outline: none;
+}
+
+.hud-note-field:focus {
+  border-color: #9ad8ff;
+}
+
 .hud-add-row {
   display: flex;
   gap: 6px;
@@ -1441,11 +1538,6 @@ button {
   font-weight: 600;
 }
 
-.block-name-overlay {
-  z-index: 20 !important;
-  pointer-events: auto;
-}
-
 .hud-name-gate {
   position: absolute;
   top: 42%;
@@ -1455,6 +1547,15 @@ button {
   z-index: 4;
 }
 
+.block-name-overlay {
+  z-index: 90 !important;
+  pointer-events: auto;
+}
+
+.block-name-overlay-map .block-name-form {
+  transform: translate(-50%, calc(-100% - 8px));
+}
+
 .block-name-form {
   pointer-events: auto;
 }

package/apps/explorer/src/keyboard.ts

@@ -0,0 +1,26 @@
+let isolation = 0
+
+export function beginKeyboardIsolation() {
+  isolation += 1
+  return () => {
+    isolation = Math.max(0, isolation - 1)
+  }
+}
+
+export function isKeyboardIsolated() {
+  return isolation > 0
+}
+
+export function isTypingInField(target: EventTarget | null) {
+  return (
+    target instanceof HTMLElement &&
+    (target.tagName === 'TEXTAREA' ||
+      target.tagName === 'INPUT' ||
+      target.tagName === 'SELECT' ||
+      target.isContentEditable)
+  )
+}
+
+export function shouldIgnoreShortcut(event: KeyboardEvent) {
+  return isKeyboardIsolated() || isTypingInField(event.target)
+}

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

@@ -2,6 +2,7 @@ import { useEffect } from 'react'
 import { useThree } from '@react-three/fiber'
 import * as THREE from 'three'
 import { folderAt } from '../layout'
+import { shouldIgnoreShortcut } from '../keyboard'
 import type { WorldLayout } from '../types'
 
 type BlockPlacerProps = {
@@ -19,16 +20,6 @@ const forward = new THREE.Vector3()
 const PLACE_MIN = 3
 const PLACE_MAX = 22
 
-function typingInField(target: EventTarget | null) {
-  return (
-    target instanceof HTMLElement &&
-    (target.tagName === 'TEXTAREA' ||
-      target.tagName === 'INPUT' ||
-      target.tagName === 'SELECT' ||
-      target.isContentEditable)
-  )
-}
-
 function lookPoint(camera: THREE.Camera): { x: number; z: number } {
   raycaster.setFromCamera(ndc, camera)
   const reached = raycaster.ray.intersectPlane(ground, hit)
@@ -70,7 +61,7 @@ export function BlockPlacer({ enabled, layout, onPlace }: BlockPlacerProps) {
   useEffect(() => {
     const onKey = (event: KeyboardEvent) => {
       if (!enabled || event.repeat || event.code !== 'Space') return
-      if (typingInField(event.target)) return
+      if (shouldIgnoreShortcut(event)) return
       event.preventDefault()
       const { x, z } = lookPoint(camera)
       const island =

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

@@ -193,11 +193,19 @@ export const FileBlock = memo(function FileBlock({
       )}
       {naming && onCommitName && onCancelName && (
         <Html
-          position={[0, height / 2 + 0.42, 0]}
-          center
+          position={
+            mapMode
+              ? [0, height / 2 + 0.04, -depth / 2]
+              : [0, height / 2 + 0.42, 0]
+          }
+          center={!mapMode}
           occlude={false}
-          wrapperClass="block-name-overlay"
-          zIndexRange={[100, 0]}
+          wrapperClass={
+            mapMode
+              ? 'block-name-overlay block-name-overlay-map'
+              : 'block-name-overlay'
+          }
+          zIndexRange={[120, 0]}
         >
           <NameInput
             placeholder="File name"

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

@@ -10,6 +10,7 @@ import {
 } from '../theme'
 import type { PlacedFolder } from '../types'
 import { MapSelectBorder } from './MapSelectBorder'
+import { NameInput } from '../ui/NameInput'
 
 type FolderAreaProps = {
   folder: PlacedFolder
@@ -19,6 +20,8 @@ type FolderAreaProps = {
   highlightKind?: ChangeKind | null
   previewLabels?: boolean
   labelVisible?: boolean
+  onCommitName?: (name: string) => void
+  onCancelName?: () => void
 }
 
 export function FolderArea({
@@ -29,6 +32,8 @@ export function FolderArea({
   highlightKind = null,
   previewLabels = false,
   labelVisible = true,
+  onCommitName,
+  onCancelName,
 }: FolderAreaProps) {
   const added = Boolean(folder.added)
   const highlight = highlightKind ? CHANGE_HIGHLIGHT[highlightKind] : null
@@ -88,6 +93,21 @@ export function FolderArea({
           <meshBasicMaterial color={aisle} />
         </mesh>
       )}
+      {naming && mapMode && onCommitName && onCancelName && (
+        <Html
+          position={[0, 1.35, -folder.depth / 2 + 1.35]}
+          center
+          occlude={false}
+          wrapperClass="block-name-overlay"
+          zIndexRange={[120, 0]}
+        >
+          <NameInput
+            placeholder="Folder name"
+            onCommit={onCommitName}
+            onCancel={onCancelName}
+          />
+        </Html>
+      )}
       <Suspense fallback={null}>
         {!naming && previewLabels && labelVisible && (
           <Html

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

@@ -1,6 +1,7 @@
 import { useEffect } from 'react'
 import { useThree } from '@react-three/fiber'
 import { folderAt } from '../layout'
+import { shouldIgnoreShortcut } from '../keyboard'
 import type { WorldLayout } from '../types'
 
 type IslandPlacerProps = {
@@ -9,23 +10,13 @@ type IslandPlacerProps = {
   onPlace: (parent: string) => void
 }
 
-function typingInField(target: EventTarget | null) {
-  return (
-    target instanceof HTMLElement &&
-    (target.tagName === 'TEXTAREA' ||
-      target.tagName === 'INPUT' ||
-      target.tagName === 'SELECT' ||
-      target.isContentEditable)
-  )
-}
-
 export function IslandPlacer({ enabled, layout, onPlace }: IslandPlacerProps) {
   const { camera } = useThree()
 
   useEffect(() => {
     const onKey = (event: KeyboardEvent) => {
       if (!enabled || event.repeat || event.code !== 'KeyB') return
-      if (typingInField(event.target)) return
+      if (shouldIgnoreShortcut(event)) return
       const island = folderAt(camera.position.x, camera.position.z, layout)
       if (!island) return
       event.preventDefault()

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

@@ -1,5 +1,4 @@
-import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react'
-import { createPortal } from 'react-dom'
+import { useEffect, useLayoutEffect, useMemo, useRef } from 'react'
 import { useFrame, useThree } from '@react-three/fiber'
 import { Html, MapControls, OrthographicCamera } from '@react-three/drei'
 import * as THREE from 'three'
@@ -19,6 +18,7 @@ type MapViewProps = {
   marker: [number, number] | null
   highlightedFolders?: Partial<Record<string, ChangeKind>>
   selectedFolder?: string | null
+  namingFolderPath?: string | null
   onLand: (x: number, z: number) => void
   onSelect: (fileId: string | null) => void
   onSelectFolder: (folderPath: string | null) => void
@@ -32,6 +32,7 @@ export function MapView({
   marker,
   highlightedFolders,
   selectedFolder = null,
+  namingFolderPath = null,
   onLand,
   onSelect,
   onSelectFolder,
@@ -84,10 +85,9 @@ export function MapView({
     const element = gl.domElement
     element.style.cursor = 'grab'
 
-    const isWalkClick = (event: PointerEvent | MouseEvent) => event.ctrlKey
+    const isWalkClick = (event: PointerEvent | MouseEvent) => event.altKey
 
-    const isWalkButton = (event: PointerEvent) =>
-      event.button === 0 || (event.ctrlKey && event.button === 2)
+    const isWalkButton = (event: PointerEvent) => event.button === 0
 
     const onDown = (event: PointerEvent) => {
       if (!isWalkButton(event)) return
@@ -184,7 +184,7 @@ export function MapView({
     }
 
     const onContextMenu = (event: MouseEvent) => {
-      if (event.ctrlKey) {
+      if (event.altKey) {
         event.preventDefault()
         return
       }
@@ -314,6 +314,7 @@ export function MapView({
           folders={layout.folders}
           highlightedFolders={highlightedFolders}
           selectedFolder={selectedFolder}
+          namingFolderPath={namingFolderPath}
         />
       )}
       {enabled && marker && <LandMarker marker={marker} />}
@@ -323,6 +324,23 @@ export function MapView({
 
 const PROJECT = new THREE.Vector3()
 const MIN_FOLDER_LABEL_PX = 28
+const FOLDER_ENTRANCE_Z = 1.35
+
+function projectToScreen(
+  x: number,
+  y: number,
+  z: number,
+  camera: THREE.Camera,
+  width: number,
+  height: number,
+) {
+  PROJECT.set(x, y, z).project(camera)
+  return {
+    x: (PROJECT.x * 0.5 + 0.5) * width,
+    y: (-PROJECT.y * 0.5 + 0.5) * height,
+    behind: PROJECT.z < -1 || PROJECT.z > 1,
+  }
+}
 
 function folderLabelClass(
   folder: PlacedFolder,
@@ -347,21 +365,50 @@ function MapFolderLabels({
   folders,
   highlightedFolders,
   selectedFolder,
+  namingFolderPath,
 }: {
   folders: Record<string, PlacedFolder>
   highlightedFolders?: Partial<Record<string, ChangeKind>>
   selectedFolder: string | null
+  namingFolderPath: string | null
 }) {
   const camera = useThree((state) => state.camera)
   const gl = useThree((state) => state.gl)
   const size = useThree((state) => state.size)
-  const layerRef = useRef<HTMLDivElement>(null)
+  const layerRef = useRef<HTMLDivElement | null>(null)
   const items = useMemo(() => Object.values(folders), [folders])
-  const [host, setHost] = useState<HTMLElement | null>(null)
 
   useLayoutEffect(() => {
-    setHost(gl.domElement.parentElement)
-  }, [gl])
+    const parent = gl.domElement.parentElement
+    if (!parent) return
+    const layer = document.createElement('div')
+    layer.className = 'map-folder-label-layer'
+    layer.style.cssText =
+      'position:absolute;inset:0;overflow:hidden;pointer-events:none;z-index:80;background:transparent;'
+    for (const folder of items) {
+      const el = document.createElement('div')
+      el.className = folderLabelClass(folder, highlightedFolders, selectedFolder)
+      el.style.position = 'absolute'
+      el.style.top = '0'
+      el.style.left = '0'
+      el.style.visibility = 'hidden'
+      const name = document.createElement('span')
+      name.className = 'map-folder-name'
+      name.textContent = folderKindLabel(
+        folder.name,
+        highlightedFolders?.[folder.path] ?? null,
+        folder.added ?? false,
+      )
+      el.appendChild(name)
+      layer.appendChild(el)
+    }
+    parent.appendChild(layer)
+    layerRef.current = layer
+    return () => {
+      layer.remove()
+      layerRef.current = null
+    }
+  }, [gl, highlightedFolders, items, selectedFolder])
 
   useFrame(() => {
     const layer = layerRef.current
@@ -372,21 +419,31 @@ function MapFolderLabels({
       const el = nodes[i] as HTMLElement | undefined
       const folder = items[i]
       if (!el || !folder) continue
-      PROJECT.set(folder.x, 14, folder.z + 1.35).project(camera)
-      const x = (PROJECT.x * 0.5 + 0.5) * size.width
-      const y = (-PROJECT.y * 0.5 + 0.5) * size.height
+      const screen = projectToScreen(
+        folder.x,
+        14,
+        folder.z + FOLDER_ENTRANCE_Z,
+        camera,
+        size.width,
+        size.height,
+      )
+      const x = screen.x
+      const y = screen.y
       const span = Math.max(folder.width, folder.depth) * zoom
       const force =
         selectedFolder === folder.path ||
         Boolean(highlightedFolders?.[folder.path] || folder.added)
       const onScreen =
-        PROJECT.z >= -1 &&
-        PROJECT.z <= 1 &&
+        !screen.behind &&
         x > -120 &&
         x < size.width + 120 &&
         y > -40 &&
         y < size.height + 40
-      if (!onScreen || (!force && span < MIN_FOLDER_LABEL_PX)) {
+      if (
+        folder.path === namingFolderPath ||
+        !onScreen ||
+        (!force && span < MIN_FOLDER_LABEL_PX)
+      ) {
         if (el.style.visibility !== 'hidden') el.style.visibility = 'hidden'
         continue
       }
@@ -401,27 +458,7 @@ function MapFolderLabels({
     }
   })
 
-  if (!host) return null
-
-  return createPortal(
-    <div ref={layerRef} className="map-folder-label-layer">
-      {items.map((folder) => (
-        <div
-          key={folder.path}
-          className={folderLabelClass(folder, highlightedFolders, selectedFolder)}
-        >
-          <span className="map-folder-name">
-            {folderKindLabel(
-              folder.name,
-              highlightedFolders?.[folder.path] ?? null,
-              folder.added ?? false,
-            )}
-          </span>
-        </div>
-      ))}
-    </div>,
-    host,
-  )
+  return null
 }
 
 function folderKindLabel(