deepspace 0.3.10 → 0.4.0

package/features/canvas/src/components/CanvasView.tsx

@@ -0,0 +1,369 @@
+/**
+ * CanvasView — SVG canvas with shape rendering, mouse interaction, zoom/pan, and multi-user cursors.
+ */
+
+import { useState, useRef, useCallback, useEffect } from 'react'
+import { useCanvas, type CanvasShapeClient } from 'deepspace'
+import { CanvasToolbar, type CanvasTool } from './CanvasToolbar'
+import { ShapeRenderer } from './ShapeRenderer'
+import { Badge } from 'deepspace'
+
+interface CanvasViewProps {
+  docId: string
+  className?: string
+}
+
+interface DragState {
+  type: 'create' | 'move'
+  startX: number
+  startY: number
+  shapeId?: string
+  originalX?: number
+  originalY?: number
+}
+
+// User colors for multi-user cursors
+const CURSOR_COLORS = ['#ef4444', '#3b82f6', '#22c55e', '#f59e0b', '#8b5cf6', '#ec4899', '#14b8a6']
+
+export function CanvasView({ docId, className }: CanvasViewProps) {
+  const {
+    shapes,
+    viewports,
+    connected,
+    addShape,
+    moveShape,
+    deleteShape,
+    setViewport,
+    undo,
+    redo,
+  } = useCanvas(docId)
+
+  const [activeTool, setActiveTool] = useState<CanvasTool>('select')
+  const [activeColor, setActiveColor] = useState('#6366f1')
+  const [selectedShapeId, setSelectedShapeId] = useState<string | null>(null)
+  const [dragState, setDragState] = useState<DragState | null>(null)
+  const [pan, setPan] = useState({ x: 0, y: 0 })
+  const [zoom, setZoom] = useState(1)
+  const [isPanning, setIsPanning] = useState(false)
+  const [panStart, setPanStart] = useState({ x: 0, y: 0, panX: 0, panY: 0 })
+
+  const svgRef = useRef<SVGSVGElement>(null)
+
+  // Convert screen coordinates to canvas coordinates
+  const screenToCanvas = useCallback(
+    (clientX: number, clientY: number) => {
+      const svg = svgRef.current
+      if (!svg) return { x: 0, y: 0 }
+      const rect = svg.getBoundingClientRect()
+      return {
+        x: (clientX - rect.left - pan.x) / zoom,
+        y: (clientY - rect.top - pan.y) / zoom,
+      }
+    },
+    [pan, zoom],
+  )
+
+  // Report viewport on pan/zoom change
+  useEffect(() => {
+    const svg = svgRef.current
+    if (!svg) return
+    const rect = svg.getBoundingClientRect()
+    setViewport({
+      x: -pan.x / zoom,
+      y: -pan.y / zoom,
+      width: rect.width / zoom,
+      height: rect.height / zoom,
+      zoom,
+    })
+  }, [pan, zoom, setViewport])
+
+  // Keyboard shortcuts
+  useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Delete' || e.key === 'Backspace') {
+        if (selectedShapeId && document.activeElement === document.body) {
+          e.preventDefault()
+          deleteShape(selectedShapeId)
+          setSelectedShapeId(null)
+        }
+      }
+      if ((e.metaKey || e.ctrlKey) && e.key === 'z') {
+        e.preventDefault()
+        if (e.shiftKey) {
+          redo()
+        } else {
+          undo()
+        }
+      }
+    }
+    window.addEventListener('keydown', handleKeyDown)
+    return () => window.removeEventListener('keydown', handleKeyDown)
+  }, [selectedShapeId, deleteShape, undo, redo])
+
+  // Mouse down on SVG background
+  const handleSvgMouseDown = useCallback(
+    (e: React.MouseEvent) => {
+      // Middle mouse button or space+click for panning
+      if (e.button === 1) {
+        e.preventDefault()
+        setIsPanning(true)
+        setPanStart({ x: e.clientX, y: e.clientY, panX: pan.x, panY: pan.y })
+        return
+      }
+
+      if (e.button !== 0) return
+
+      const pos = screenToCanvas(e.clientX, e.clientY)
+
+      if (activeTool === 'select') {
+        // Deselect when clicking background
+        setSelectedShapeId(null)
+        // Start panning
+        setIsPanning(true)
+        setPanStart({ x: e.clientX, y: e.clientY, panX: pan.x, panY: pan.y })
+        return
+      }
+
+      // Start creating a shape
+      setDragState({
+        type: 'create',
+        startX: pos.x,
+        startY: pos.y,
+      })
+    },
+    [activeTool, screenToCanvas, pan],
+  )
+
+  // Mouse down on a shape
+  const handleShapeMouseDown = useCallback(
+    (e: React.MouseEvent, shapeId: string) => {
+      if (activeTool !== 'select') return
+
+      const shape = shapes.find((s) => s.id === shapeId)
+      if (!shape) return
+
+      setSelectedShapeId(shapeId)
+      setDragState({
+        type: 'move',
+        startX: e.clientX,
+        startY: e.clientY,
+        shapeId,
+        originalX: shape.x,
+        originalY: shape.y,
+      })
+    },
+    [activeTool, shapes],
+  )
+
+  // Mouse move
+  const handleMouseMove = useCallback(
+    (e: React.MouseEvent) => {
+      if (isPanning) {
+        setPan({
+          x: panStart.panX + (e.clientX - panStart.x),
+          y: panStart.panY + (e.clientY - panStart.y),
+        })
+        return
+      }
+
+      if (!dragState) return
+
+      if (dragState.type === 'move' && dragState.shapeId) {
+        const dx = (e.clientX - dragState.startX) / zoom
+        const dy = (e.clientY - dragState.startY) / zoom
+        moveShape(dragState.shapeId, dragState.originalX! + dx, dragState.originalY! + dy)
+      }
+    },
+    [dragState, isPanning, panStart, zoom, moveShape],
+  )
+
+  // Mouse up
+  const handleMouseUp = useCallback(
+    (e: React.MouseEvent) => {
+      if (isPanning) {
+        setIsPanning(false)
+        return
+      }
+
+      if (!dragState) return
+
+      if (dragState.type === 'create') {
+        const pos = screenToCanvas(e.clientX, e.clientY)
+        const x = Math.min(dragState.startX, pos.x)
+        const y = Math.min(dragState.startY, pos.y)
+        const width = Math.max(Math.abs(pos.x - dragState.startX), 20)
+        const height = Math.max(Math.abs(pos.y - dragState.startY), 20)
+
+        addShape({
+          type: activeTool,
+          x,
+          y,
+          width,
+          height,
+          props: {
+            stroke: activeColor,
+            fill: 'transparent',
+            ...(activeTool === 'text' ? { text: 'Text' } : {}),
+          },
+        })
+
+        // Switch back to select after creating
+        setActiveTool('select')
+      }
+
+      setDragState(null)
+    },
+    [dragState, isPanning, screenToCanvas, activeTool, activeColor, addShape],
+  )
+
+  // Wheel for zoom
+  const handleWheel = useCallback(
+    (e: React.WheelEvent) => {
+      e.preventDefault()
+      const svg = svgRef.current
+      if (!svg) return
+
+      const rect = svg.getBoundingClientRect()
+      const mouseX = e.clientX - rect.left
+      const mouseY = e.clientY - rect.top
+
+      const zoomFactor = e.deltaY > 0 ? 0.9 : 1.1
+      const newZoom = Math.min(Math.max(zoom * zoomFactor, 0.1), 5)
+
+      // Zoom towards mouse position
+      setPan({
+        x: mouseX - (mouseX - pan.x) * (newZoom / zoom),
+        y: mouseY - (mouseY - pan.y) * (newZoom / zoom),
+      })
+      setZoom(newZoom)
+    },
+    [zoom, pan],
+  )
+
+  const handleDelete = useCallback(() => {
+    if (selectedShapeId) {
+      deleteShape(selectedShapeId)
+      setSelectedShapeId(null)
+    }
+  }, [selectedShapeId, deleteShape])
+
+  return (
+    <div data-testid="canvas-view" className={`flex flex-col h-full ${className ?? ''}`}>
+      <CanvasToolbar
+        activeTool={activeTool}
+        activeColor={activeColor}
+        hasSelection={selectedShapeId !== null}
+        onToolChange={setActiveTool}
+        onColorChange={setActiveColor}
+        onDelete={handleDelete}
+        onUndo={undo}
+        onRedo={redo}
+      />
+
+      <div className="relative flex-1 overflow-hidden bg-background">
+        {/* Connection status */}
+        <div className="absolute top-3 right-3 z-10">
+          {connected ? (
+            <Badge variant="success" className="text-xs">
+              <span className="w-1.5 h-1.5 bg-success rounded-full mr-1" />
+              Connected
+            </Badge>
+          ) : (
+            <Badge variant="secondary" className="text-xs">
+              <span className="w-1.5 h-1.5 bg-warning rounded-full animate-pulse mr-1" />
+              Connecting...
+            </Badge>
+          )}
+        </div>
+
+        {/* Zoom indicator */}
+        <div className="absolute bottom-3 right-3 z-10">
+          <span className="text-xs text-muted-foreground bg-card/80 px-2 py-1 rounded border border-border">
+            {Math.round(zoom * 100)}%
+          </span>
+        </div>
+
+        <svg
+          ref={svgRef}
+          data-testid="canvas-svg"
+          className="w-full h-full"
+          style={{
+            cursor: activeTool === 'select' ? (isPanning ? 'grabbing' : 'default') : 'crosshair',
+          }}
+          onMouseDown={handleSvgMouseDown}
+          onMouseMove={handleMouseMove}
+          onMouseUp={handleMouseUp}
+          onMouseLeave={handleMouseUp}
+          onWheel={handleWheel}
+        >
+          {/* Grid background */}
+          <defs>
+            <pattern
+              id="grid"
+              width={20 * zoom}
+              height={20 * zoom}
+              patternUnits="userSpaceOnUse"
+              x={pan.x % (20 * zoom)}
+              y={pan.y % (20 * zoom)}
+            >
+              <circle cx={1} cy={1} r={0.5} fill="currentColor" className="text-border" />
+            </pattern>
+          </defs>
+          <rect width="100%" height="100%" fill="url(#grid)" />
+
+          {/* Canvas content with pan/zoom transform */}
+          <g transform={`translate(${pan.x}, ${pan.y}) scale(${zoom})`}>
+            {/* Shapes */}
+            {shapes.map((shape) => (
+              <ShapeRenderer
+                key={shape.id}
+                shape={shape}
+                isSelected={shape.id === selectedShapeId}
+                onMouseDown={handleShapeMouseDown}
+              />
+            ))}
+
+            {/* Other users' cursors */}
+            {viewports.map((vp, i) => (
+              <g key={vp.userId} pointerEvents="none">
+                {/* Cursor dot */}
+                <circle
+                  cx={vp.x + vp.width / 2}
+                  cy={vp.y + 20}
+                  r={4 / zoom}
+                  fill={CURSOR_COLORS[i % CURSOR_COLORS.length]}
+                />
+                {/* User label */}
+                <text
+                  x={vp.x + vp.width / 2 + 8 / zoom}
+                  y={vp.y + 24 / zoom}
+                  fontSize={11 / zoom}
+                  fill={CURSOR_COLORS[i % CURSOR_COLORS.length]}
+                  fontFamily="system-ui, sans-serif"
+                >
+                  User {vp.userId.slice(0, 6)}
+                </text>
+              </g>
+            ))}
+          </g>
+
+          {/* Drag preview for shape creation */}
+          {dragState?.type === 'create' && (
+            <rect
+              x={0}
+              y={0}
+              width={0}
+              height={0}
+              fill="transparent"
+              stroke={activeColor}
+              strokeWidth={1}
+              strokeDasharray="4 3"
+              pointerEvents="none"
+              style={{ display: 'none' }}
+            />
+          )}
+        </svg>
+      </div>
+    </div>
+  )
+}

package/features/canvas/src/components/ShapeRenderer.tsx

@@ -0,0 +1,114 @@
+/**
+ * ShapeRenderer — Renders individual shapes as SVG elements.
+ *
+ * Supports: rect, ellipse, line, text
+ */
+
+import type { CanvasShapeClient } from 'deepspace'
+
+interface ShapeRendererProps {
+  shape: CanvasShapeClient
+  isSelected: boolean
+  onMouseDown: (e: React.MouseEvent, shapeId: string) => void
+}
+
+const SELECTION_PADDING = 4
+
+export function ShapeRenderer({ shape, isSelected, onMouseDown }: ShapeRendererProps) {
+  const fill = (shape.props.fill as string) ?? 'transparent'
+  const stroke = (shape.props.stroke as string) ?? '#6366f1'
+  const strokeWidth = (shape.props.strokeWidth as number) ?? 2
+
+  const handleMouseDown = (e: React.MouseEvent) => {
+    e.stopPropagation()
+    onMouseDown(e, shape.id)
+  }
+
+  return (
+    <g
+      data-testid={`shape-${shape.id}`}
+      onMouseDown={handleMouseDown}
+      style={{ cursor: 'move' }}
+    >
+      {/* Selection outline */}
+      {isSelected && (
+        <rect
+          x={shape.x - SELECTION_PADDING}
+          y={shape.y - SELECTION_PADDING}
+          width={shape.width + SELECTION_PADDING * 2}
+          height={shape.height + SELECTION_PADDING * 2}
+          fill="none"
+          style={{ stroke: 'var(--color-primary)' }}
+          strokeWidth={1.5}
+          strokeDasharray="4 3"
+          rx={2}
+          pointerEvents="none"
+        />
+      )}
+
+      {/* Shape */}
+      {shape.type === 'rect' && (
+        <rect
+          x={shape.x}
+          y={shape.y}
+          width={shape.width}
+          height={shape.height}
+          fill={fill}
+          stroke={stroke}
+          strokeWidth={strokeWidth}
+          rx={4}
+        />
+      )}
+
+      {shape.type === 'ellipse' && (
+        <ellipse
+          cx={shape.x + shape.width / 2}
+          cy={shape.y + shape.height / 2}
+          rx={shape.width / 2}
+          ry={shape.height / 2}
+          fill={fill}
+          stroke={stroke}
+          strokeWidth={strokeWidth}
+        />
+      )}
+
+      {shape.type === 'line' && (
+        <line
+          x1={shape.x}
+          y1={shape.y}
+          x2={shape.x + shape.width}
+          y2={shape.y + shape.height}
+          stroke={stroke}
+          strokeWidth={strokeWidth}
+          strokeLinecap="round"
+        />
+      )}
+
+      {shape.type === 'text' && (
+        <>
+          <rect
+            x={shape.x}
+            y={shape.y}
+            width={shape.width}
+            height={shape.height}
+            fill={fill === 'transparent' ? 'transparent' : fill}
+            stroke={isSelected ? stroke : 'transparent'}
+            strokeWidth={isSelected ? strokeWidth : 0}
+            rx={2}
+          />
+          <text
+            x={shape.x + 8}
+            y={shape.y + shape.height / 2}
+            dominantBaseline="central"
+            fill={stroke}
+            fontSize={14}
+            fontFamily="system-ui, sans-serif"
+            pointerEvents="none"
+          >
+            {(shape.props.text as string) ?? 'Text'}
+          </text>
+        </>
+      )}
+    </g>
+  )
+}

package/features/cron/feature.json

@@ -0,0 +1,33 @@
+{
+  "id": "cron",
+  "name": "Cron Heartbeat",
+  "category": "data",
+  "description": "Scheduled background tasks via the per-app CronRoom DO",
+  "details": "Reference implementation of a working cron job. Registers a 1-minute 'heartbeat' task in src/cron.ts (consumed by AppCronRoom at construction time). Each fire is logged to the DO's cron_history table; /cron-log subscribes via useCronMonitor and renders live history. Useful both as a working example and as the basis for the cron e2e spec.",
+  "files": [
+    {
+      "src": "src/cron.ts",
+      "dest": "src/cron.ts",
+      "overwrite": true
+    },
+    {
+      "src": "src/CronLogPage.tsx",
+      "dest": "src/pages/cron-log.tsx"
+    }
+  ],
+  "route": {
+    "path": "/cron-log",
+    "protected": false
+  },
+  "requires": [],
+  "instructions": [
+    "Deploy the app: npm run deploy",
+    "Within ~90s, visit /cron-log on the deployed app — you should see one new row per minute as the AppCronRoom alarm fires the heartbeat task.",
+    "Open the page on a desktop browser and look at devtools → Network → WS → /ws/cron/app:<APP_NAME> to see live cron.* protocol frames."
+  ],
+  "patterns": [
+    "Task config lives in code (src/cron.ts), not JSON. AppCronRoom validates at construction time.",
+    "Per-app CronRoom DO shards work; no global KV bottleneck. CPU is correctly attributed to the app owner via the tail-worker.",
+    "Heartbeat tasks (intervalMinutes: 1) are useful as low-cost liveness probes for cron infrastructure."
+  ]
+}

package/features/cron/src/CronLogPage.tsx

@@ -0,0 +1,100 @@
+/**
+ * Cron Log Page
+ *
+ * Subscribes to the app's CronRoom via `useCronMonitor` and renders live
+ * task state + execution history. The DO is keyed by `app:${APP_NAME}` so
+ * a single shared CronRoom DO instance backs the whole app — same pattern
+ * as RecordRoom.
+ *
+ * Used both as a UI surface for verifying that scheduled tasks are firing
+ * in production, and as the data source for the cron e2e spec at
+ * tests/feature-tests/tests/cron.spec.ts.
+ */
+
+import { useCronMonitor } from 'deepspace'
+import { SCOPE_ID } from '../constants'
+
+export default function CronLogPage() {
+  const { tasks, history, connected } = useCronMonitor(SCOPE_ID)
+
+  // Newest first.
+  const sorted = [...history].sort((a, b) => {
+    return new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime()
+  })
+
+  return (
+    <div data-testid="cron-log-page" style={{ padding: 24 }}>
+      <h1>Cron Log</h1>
+      <p>
+        Each row is one tick of a scheduled task fired by the AppCronRoom DO.
+        Heartbeat ticks every minute once the DO alarm picks up the registered
+        config.
+      </p>
+
+      <div data-testid="cron-log-status" style={{ marginBottom: 12 }}>
+        Connection: {connected ? 'live' : 'connecting…'}
+      </div>
+
+      <h2>Tasks</h2>
+      <table data-testid="cron-tasks" style={{ borderCollapse: 'collapse', width: '100%' }}>
+        <thead>
+          <tr>
+            <th style={{ textAlign: 'left', borderBottom: '1px solid var(--color-border)', padding: 8 }}>Name</th>
+            <th style={{ textAlign: 'left', borderBottom: '1px solid var(--color-border)', padding: 8 }}>Schedule</th>
+            <th style={{ textAlign: 'left', borderBottom: '1px solid var(--color-border)', padding: 8 }}>Last run</th>
+            <th style={{ textAlign: 'left', borderBottom: '1px solid var(--color-border)', padding: 8 }}>Next run</th>
+          </tr>
+        </thead>
+        <tbody>
+          {tasks.map((task) => (
+            <tr key={task.name} data-testid="cron-task-row" data-task={task.name}>
+              <td style={{ padding: 8 }}>{task.name}</td>
+              <td style={{ padding: 8 }}>
+                {task.schedule
+                  ? `${task.schedule} (${task.timezone ?? 'UTC'})`
+                  : `every ${task.intervalMinutes ?? '?'} min`}
+              </td>
+              <td style={{ padding: 8 }}>{task.lastRunAt ?? '—'}</td>
+              <td style={{ padding: 8 }}>{task.nextRunAt ?? '—'}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+
+      <h2 style={{ marginTop: 24 }}>History</h2>
+      <div data-testid="cron-log-count">{sorted.length} entries</div>
+
+      <table style={{ marginTop: 16, borderCollapse: 'collapse', width: '100%' }}>
+        <thead>
+          <tr>
+            <th style={{ textAlign: 'left', borderBottom: '1px solid var(--color-border)', padding: 8 }}>Task</th>
+            <th style={{ textAlign: 'left', borderBottom: '1px solid var(--color-border)', padding: 8 }}>Started (UTC)</th>
+            <th style={{ textAlign: 'left', borderBottom: '1px solid var(--color-border)', padding: 8 }}>Duration</th>
+            <th style={{ textAlign: 'left', borderBottom: '1px solid var(--color-border)', padding: 8 }}>Outcome</th>
+          </tr>
+        </thead>
+        <tbody data-testid="cron-log-rows">
+          {sorted.map((entry, idx) => (
+            <tr
+              key={`${entry.taskName}-${entry.startedAt}-${idx}`}
+              data-testid="cron-log-row"
+              data-task={entry.taskName}
+              data-success={entry.success ? '1' : '0'}
+            >
+              <td style={{ padding: 8 }}>{entry.taskName}</td>
+              <td style={{ padding: 8 }}>{entry.startedAt}</td>
+              <td style={{ padding: 8 }}>{entry.durationMs} ms</td>
+              <td style={{ padding: 8 }}>{entry.success ? 'ok' : `error: ${entry.error ?? '?'}`}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+
+      {sorted.length === 0 && connected && (
+        <p data-testid="cron-log-empty" style={{ marginTop: 24, opacity: 0.6 }}>
+          No cron ticks recorded yet. The first one should appear within ~90s of deploy.
+        </p>
+      )}
+    </div>
+  )
+}

package/features/cron/src/cron.ts

@@ -0,0 +1,25 @@
+/**
+ * Cron task definitions for the heartbeat reference feature.
+ *
+ * AppCronRoom (declared in worker.ts) reads `tasks` at construction time
+ * and validates them. The DO alarm fires `runTask(name, env)` on the
+ * configured schedule; each fire is recorded in the DO's `cron_history`
+ * table and pushed to subscribers over `/ws/cron/:roomId`.
+ *
+ * The heartbeat task here is the low-cost liveness probe used by both
+ * the cron e2e spec and as a quick sanity check after a deploy. To add
+ * your own task, append a {name, intervalMinutes} or {name, schedule,
+ * timezone} entry to `tasks` and dispatch on `name` inside `runTask`.
+ */
+
+import type { CronTask } from 'deepspace/worker'
+
+export const tasks: CronTask[] = [
+  { name: 'heartbeat', intervalMinutes: 1 },
+]
+
+export async function runTask(_name: string, _env: unknown): Promise<void> {
+  // No-op work — the DO records every invocation in cron_history regardless,
+  // which is what the e2e spec asserts against. Real apps would dispatch on
+  // `_name` here and call into integrations / records via buildCronContext.
+}