@dfosco/storyboard 0.6.0-beta.2 → 0.6.0-beta.21

package/src/core/canvas/collision.js

@@ -162,10 +162,14 @@ export function snapToGrid(value, gridSize) {
  *
  * Strategy:
  * 1. Try the initial position
- * 2. If collision, find the max endX among all colliders and move past it
- * 3. Repeat until no collisions or maxIterations exhausted
- * 4. If horizontal resolution exhausted, fall back to moving down
- * 5. Snap final position to grid
+ * 2. Phase 1 — move along the primary axis (default horizontal) past colliders
+ * 3. Phase 2 — fall back to the orthogonal axis (default vertical) past colliders
+ * 4. Snap final position to grid
+ *
+ * Use `preferAxis: 'vertical'` to swap the phase order — useful when widgets
+ * are being fanned out around a reference widget (e.g. hub layouts) where
+ * moving horizontally further away from the reference defeats the placement
+ * intent. Examples: 'right' / 'left' / 'above-right' / 'below-right'.
  *
  * @param {object} options
  * @param {number} options.x - Initial X position
@@ -177,6 +181,7 @@ export function snapToGrid(value, gridSize) {
  * @param {number} [options.gridSize=24] - Grid size for snapping
  * @param {number} [options.gap] - Gap between widgets (defaults to gridSize)
  * @param {number} [options.maxIterations=50] - Max collision resolution attempts
+ * @param {'horizontal'|'vertical'} [options.preferAxis='horizontal'] - Which axis to try first
  * @returns {{ x: number, y: number, adjusted: boolean }}
  */
 export function findFreePosition({
@@ -189,63 +194,63 @@ export function findFreePosition({
   gridSize = 24,
   gap = null,
   maxIterations = 50,
+  preferAxis = 'horizontal',
 }) {
   const spacing = gap ?? gridSize
   let currentX = x
   let currentY = y
   let adjusted = false
 
-  // Phase 1: Try moving right past all colliders
-  for (let i = 0; i < maxIterations; i++) {
-    const rect = { x: currentX, y: currentY, width, height }
-    const colliders = findCollisions(rect, widgets, excludeId)
-
-    if (colliders.length === 0) {
-      return {
-        x: snapToGrid(currentX, gridSize),
-        y: snapToGrid(currentY, gridSize),
-        adjusted,
+  const horizontalPhase = () => {
+    for (let i = 0; i < maxIterations; i++) {
+      const rect = { x: currentX, y: currentY, width, height }
+      const colliders = findCollisions(rect, widgets, excludeId)
+      if (colliders.length === 0) return true
+      let maxEndX = 0
+      for (const c of colliders) {
+        const b = getWidgetBounds(c)
+        const endX = b.x + b.width
+        if (endX > maxEndX) maxEndX = endX
       }
+      currentX = maxEndX + spacing
+      adjusted = true
     }
-
-    // Jump past the rightmost edge of all colliders
-    let maxEndX = 0
-    for (const c of colliders) {
-      const b = getWidgetBounds(c)
-      const endX = b.x + b.width
-      if (endX > maxEndX) maxEndX = endX
-    }
-    currentX = maxEndX + spacing
-    adjusted = true
+    return false
   }
 
-  // Phase 2: Reset X, try moving down
-  currentX = x
-
-  for (let i = 0; i < maxIterations; i++) {
-    const rect = { x: currentX, y: currentY, width, height }
-    const colliders = findCollisions(rect, widgets, excludeId)
-
-    if (colliders.length === 0) {
-      return {
-        x: snapToGrid(currentX, gridSize),
-        y: snapToGrid(currentY, gridSize),
-        adjusted,
+  const verticalPhase = () => {
+    for (let i = 0; i < maxIterations; i++) {
+      const rect = { x: currentX, y: currentY, width, height }
+      const colliders = findCollisions(rect, widgets, excludeId)
+      if (colliders.length === 0) return true
+      let maxEndY = 0
+      for (const c of colliders) {
+        const b = getWidgetBounds(c)
+        const endY = b.y + b.height
+        if (endY > maxEndY) maxEndY = endY
       }
+      currentY = maxEndY + spacing
+      adjusted = true
     }
+    return false
+  }
 
-    // Jump past the bottommost edge of all colliders
-    let maxEndY = 0
-    for (const c of colliders) {
-      const b = getWidgetBounds(c)
-      const endY = b.y + b.height
-      if (endY > maxEndY) maxEndY = endY
+  if (preferAxis === 'vertical') {
+    if (verticalPhase()) {
+      return { x: snapToGrid(currentX, gridSize), y: snapToGrid(currentY, gridSize), adjusted }
     }
-    currentY = maxEndY + spacing
-    adjusted = true
+    // Reset Y, try horizontal
+    currentY = y
+    horizontalPhase()
+  } else {
+    if (horizontalPhase()) {
+      return { x: snapToGrid(currentX, gridSize), y: snapToGrid(currentY, gridSize), adjusted }
+    }
+    // Reset X, try vertical
+    currentX = x
+    verticalPhase()
   }
 
-  // Fallback: return the last attempted position (snapped)
   return {
     x: snapToGrid(currentX, gridSize),
     y: snapToGrid(currentY, gridSize),
@@ -275,6 +280,8 @@ export function resolvePosition({
   widgets,
   excludeId = null,
   gridSize = 24,
+  gap = null,
+  preferAxis = 'horizontal',
 }) {
   const defaults = getDefaultSize(type)
   const width = props.width ?? defaults.width
@@ -288,6 +295,8 @@ export function resolvePosition({
     widgets,
     excludeId,
     gridSize,
+    gap,
+    preferAxis,
   })
 }
 

package/src/core/canvas/collision.test.js

@@ -271,6 +271,45 @@ describe('findFreePosition', () => {
     expect(result.x).toBeGreaterThan(294 + 270)
     expect(result.adjusted).toBe(true)
   })
+
+  it('preferAxis: "vertical" cascades down past colliders instead of right', () => {
+    // Simulates a hub fan-out: a leader on the left, two peers already placed
+    // above-right and below-right, then trying to place a third peer at the
+    // `right` direction (same column as the existing peers, leader-top y).
+    const widgets = [
+      { id: 'leader',      type: 'sticky-note', position: { x: 0,   y: 0 },   props: { width: 200, height: 200 } },
+      { id: 'above-right', type: 'sticky-note', position: { x: 240, y: -100 }, props: { width: 200, height: 200 } },
+      { id: 'below-right', type: 'sticky-note', position: { x: 240, y: 200 },  props: { width: 200, height: 200 } },
+    ]
+    const result = findFreePosition({
+      x: 240,
+      y: 0,
+      width: 200,
+      height: 200,
+      widgets,
+      gridSize: 24,
+      preferAxis: 'vertical',
+    })
+    // Should cascade DOWN past the above-right and below-right widgets,
+    // staying in the same X column as the fan, NOT jump far to the right.
+    expect(result.x).toBe(240)
+    expect(result.y).toBeGreaterThanOrEqual(200 + 200) // past below-right's endY
+    expect(result.adjusted).toBe(true)
+  })
+
+  it('preferAxis: "horizontal" (default) still resolves rightward', () => {
+    const widgets = [
+      { id: 'w1', type: 'sticky-note', position: { x: 0, y: 0 }, props: { width: 200, height: 200 } },
+    ]
+    const result = findFreePosition({
+      x: 50, y: 50,
+      width: 200, height: 200,
+      widgets,
+      gridSize: 24,
+    })
+    expect(result.x).toBeGreaterThanOrEqual(200)
+    expect(result.y).toBe(48) // snapped from 50
+  })
 })
 
 describe('resolvePosition', () => {

package/src/core/canvas/configReader.js

@@ -0,0 +1,110 @@
+/**
+ * Server-side reader for terminal + agents config.
+ *
+ * Replaces direct `JSON.parse(readFileSync('storyboard.config.json')).canvas.agents`
+ * reads in terminal-server / hot-pool / canvas server / terminal-welcome /
+ * server-plugin so the new `terminal.config.json` (and the library's default
+ * one shipped under `node_modules/@dfosco/storyboard/terminal.config.json`)
+ * is honored everywhere with leaf-level merge.
+ *
+ * Resolution order (lowest → highest priority), all leaf-merged:
+ *   1. Library default `<root>/{packages/storyboard,node_modules/@dfosco/storyboard}/terminal.config.json`
+ *   2. `storyboard.config.json` `canvas.terminal` + `canvas.agents` (legacy)
+ *   3. Root `terminal.config.json`
+ *
+ * Returns `{ terminal, agents, showAgentsInAddMenu }`. Empty objects when
+ * nothing is configured (rather than null) so callers can spread freely.
+ */
+
+import { readFileSync, existsSync } from 'node:fs'
+import { resolve, join } from 'node:path'
+
+/** Same shape as data-plugin's `deepMergeBuild`. */
+function deepMerge(target, source) {
+  if (!source || typeof source !== 'object') return target
+  if (!target || typeof target !== 'object') return source
+  const result = { ...target }
+  for (const key of Object.keys(source)) {
+    const sv = source[key]
+    const tv = target[key]
+    if (sv && typeof sv === 'object' && !Array.isArray(sv) && tv && typeof tv === 'object' && !Array.isArray(tv)) {
+      result[key] = deepMerge(tv, sv)
+    } else {
+      result[key] = sv
+    }
+  }
+  return result
+}
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+function resolveLibTerminalConfig(root) {
+  const candidates = [
+    join(root, 'packages', 'storyboard', 'terminal.config.json'),
+    join(root, 'node_modules', '@dfosco', 'storyboard', 'terminal.config.json'),
+  ]
+  for (const p of candidates) {
+    if (existsSync(p)) {
+      const parsed = readJson(p)
+      if (parsed) return parsed
+    }
+  }
+  return null
+}
+
+/**
+ * Read the merged terminal + agents + hotPool config for a project root.
+ *
+ * @param {string} [root] - Project root, defaults to `process.cwd()`.
+ * @returns {{ terminal: object, agents: object, showAgentsInAddMenu: boolean|undefined, hotPool: object }}
+ */
+export function readTerminalConfigMerged(root = process.cwd()) {
+  const lib = resolveLibTerminalConfig(root) || {}
+  const sb = readJson(resolve(root, 'storyboard.config.json')) || {}
+  const userTerminal = readJson(resolve(root, 'terminal.config.json')) || {}
+
+  const sbCanvas = sb.canvas || {}
+  const sbLayer = {
+    ...(sbCanvas.terminal ? { terminal: sbCanvas.terminal } : {}),
+    ...(sbCanvas.agents ? { agents: sbCanvas.agents } : {}),
+    ...(sbCanvas.showAgentsInAddMenu !== undefined
+      ? { showAgentsInAddMenu: sbCanvas.showAgentsInAddMenu }
+      : {}),
+    ...(sb.hotPool ? { hotPool: sb.hotPool } : {}),
+  }
+
+  const merged = deepMerge(deepMerge(lib, sbLayer), userTerminal)
+  return {
+    terminal: merged.terminal || {},
+    agents: merged.agents || {},
+    showAgentsInAddMenu: merged.showAgentsInAddMenu,
+    hotPool: merged.hotPool || {},
+  }
+}
+
+/**
+ * Convenience: just the agents map.
+ */
+export function readAgentsConfig(root = process.cwd()) {
+  return readTerminalConfigMerged(root).agents
+}
+
+/**
+ * Convenience: just the terminal-widget settings.
+ */
+export function readTerminalSettings(root = process.cwd()) {
+  return readTerminalConfigMerged(root).terminal
+}
+
+/**
+ * Convenience: just the hotPool config.
+ */
+export function readHotPoolConfig(root = process.cwd()) {
+  return readTerminalConfigMerged(root).hotPool
+}

package/src/core/canvas/hot-pool.js

@@ -12,7 +12,7 @@
  *   - **prompt**   — bare tmux shell (prompt widgets)
  *   - **copilot**  — tmux + `copilot --agent terminal-agent` running & ready
  *   - **claude**   — tmux + `claude --agent terminal-agent ...` running & ready
- *   - **codex**    — tmux + `codex --full-auto` running & ready
+ *   - **codex**    — tmux + `codex --dangerously-bypass-approvals-and-sandbox` running & ready
  *
  * ## Load Balancer (per-pool)
  *
@@ -25,7 +25,7 @@
  * Scale-down: After cooldown minutes with no acquisitions, the pool scales
  *             back to pool_size by killing excess warm sessions.
  *
- * ## Configuration (storyboard.config.json → hotPool)
+ * ## Configuration (terminal.config.json → hotPool, or storyboard.config.json → hotPool for legacy back-compat)
  *
  *   hotPool.enabled         — enable/disable all pools (default: true)
  *   hotPool.verbose         — log to Vite terminal (default: false)
@@ -549,7 +549,9 @@ export class HotPool {
         const poll = setInterval(() => {
           try {
             const paneContent = execSync(
-              `tmux capture-pane -t "${tmuxName}" -p`,
+              // H1: include scrollback so the readiness echo can still be
+              // matched after the agent's TUI repaints over it.
+              `tmux capture-pane -t "${tmuxName}" -p -S -200`,
               { encoding: 'utf8', timeout: 1000 }
             )
             // Strip ANSI escape sequences — agent CLIs use heavy formatting

package/src/core/canvas/server.js

@@ -52,6 +52,7 @@ import { markCanvasWrite, unmarkCanvasWrite } from './writeGuard.js'
 import { devLog } from '../logger/devLogger.js'
 import widgetsConfig from '../../../widgets.config.json' with { type: 'json' }
 import { listHubRoles, getDefaultRoleId } from './hub-roles.js'
+import { readAgentsConfig } from './configReader.js'
 
 /**
  * Read the prompt widget's execution config from widgets.config.json.
@@ -263,6 +264,17 @@ export function createCanvasHandler(ctx) {
    * @param {number} gridSize — pixel size of one grid unit (default 24)
    * @returns {{ x: number, y: number }}
    */
+  /**
+   * Map a `--direction` value to the preferred collision-resolution axis.
+   * Side placements (left/right/diagonals) cascade vertically so a fan of
+   * widgets stacks into a clean column instead of getting shoved further
+   * away from the reference widget. Above/below cascade horizontally.
+   */
+  function directionPreferAxis(direction) {
+    if (direction === 'above' || direction === 'below') return 'horizontal'
+    return 'vertical'
+  }
+
   function computeNearPosition(refWidget, direction = 'right', newType = 'sticky-note', newProps = {}, gap = 1, gridSize = 24) {
     gap = gap * gridSize
     const refBounds = getWidgetBounds(refWidget)
@@ -713,9 +725,7 @@ export function createCanvasHandler(ctx) {
     // For agent widgets, resolve startupCommand from canvas.agents config if not provided
     if (type === 'agent' && props.agentId && !props.startupCommand) {
       try {
-        const configPath = path.join(root, 'storyboard.config.json')
-        const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'))
-        const agentCfg = config?.canvas?.agents?.[props.agentId]
+        const agentCfg = readAgentsConfig(root)?.[props.agentId]
         if (agentCfg?.startupCommand) {
           props.startupCommand = agentCfg.startupCommand
         }
@@ -725,9 +735,7 @@ export function createCanvasHandler(ctx) {
     // For agent widgets without agentId, default to the first canvas.agents entry
     if (type === 'agent' && !props.agentId) {
       try {
-        const configPath = path.join(root, 'storyboard.config.json')
-        const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'))
-        const agents = config?.canvas?.agents || {}
+        const agents = readAgentsConfig(root) || {}
         const defaultEntry = Object.entries(agents).find(([, cfg]) => cfg.default) || Object.entries(agents)[0]
         if (defaultEntry) {
           const [id, cfg] = defaultEntry
@@ -1106,10 +1114,16 @@ export function createCanvasHandler(ctx) {
         }
 
         if (near || resolve || needsAutoPosition) {
+          const gs = (canvasData && canvasData.gridSize) || 24
           const resolved = resolvePosition({
             x: position.x, y: position.y, type, props,
             widgets: canvasWidgets,
-            gridSize: (canvasData && canvasData.gridSize) || 24,
+            gridSize: gs,
+            // When the user supplied --gap (grid spaces), use the same spacing
+            // for collision cascades so cascaded widgets keep the gap, not just
+            // sit one gridSize apart.
+            gap: near && typeof gap === 'number' ? gap * gs : null,
+            preferAxis: near ? directionPreferAxis(direction) : 'horizontal',
           })
           position = { x: resolved.x, y: resolved.y }
         }
@@ -1864,10 +1878,13 @@ export function createCanvasHandler(ctx) {
 
                 // Collision resolution: uses live widgetMap (includes earlier batch creates)
                 if (near || doResolve || needsAuto) {
+                  const gs = canvasData.gridSize || 24
                   const resolved = resolvePosition({
                     x: position.x, y: position.y, type, props,
                     widgets: Array.from(widgetMap.values()),
-                    gridSize: canvasData.gridSize || 24,
+                    gridSize: gs,
+                    gap: near && typeof opGap === 'number' ? opGap * gs : null,
+                    preferAxis: near ? directionPreferAxis(direction) : 'horizontal',
                   })
                   position = { x: resolved.x, y: resolved.y }
                 }
@@ -3106,15 +3123,16 @@ export function Default() {
         // Write env file for this terminal session — sourced before copilot launch
         // This avoids race conditions with tmux send-keys export
         const envFile = path.join(root, '.storyboard', 'terminals', `${tmuxName}.env`)
-        const envContent = Object.entries(envMap).map(([k, v]) => `export ${k}=${JSON.stringify(v)}`).join('\n') + '\n'
+        // Trailing echo is the readiness signal the post-startup poller
+        // matches against. Don't drop it — without it /allow-all and the
+        // identity/role/broadcast bind wait the full 30s timeout fallback.
+        const envContent = Object.entries(envMap).map(([k, v]) => `export ${k}=${JSON.stringify(v)}`).join('\n') + '\necho "Environment loaded:"\n'
         fsModule.writeFileSync(envFile, envContent)
 
         // Resolve agent config from storyboard.config.json
         let agentConfig = null
         try {
-          const configPath = path.join(root, 'storyboard.config.json')
-          const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'))
-          const agents = config?.canvas?.agents || {}
+          const agents = readAgentsConfig(root) || {}
           if (agentId && agents[agentId]) {
             agentConfig = agents[agentId]
           } else {
@@ -3150,7 +3168,8 @@ export function Default() {
           const poll = setInterval(() => {
             if (sent) { clearInterval(poll); return }
             try {
-              const pane = execSync(`tmux capture-pane -t "${tmuxName}" -p`, { encoding: 'utf8', timeout: 1000 })
+              // H1: include scrollback so the echo survives Copilot's TUI repaint.
+              const pane = execSync(`tmux capture-pane -t "${tmuxName}" -p -S -200`, { encoding: 'utf8', timeout: 1000 })
               if (pane.includes(readinessSignal)) {
                 sent = true
                 clearInterval(poll)