@dfosco/storyboard-react 4.0.0-beta.27 → 4.0.0-beta.29

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@dfosco/storyboard-react",
-  "version": "4.0.0-beta.27",
+  "version": "4.0.0-beta.29",
   "type": "module",
   "dependencies": {
-    "@dfosco/storyboard-core": "4.0.0-beta.27",
-    "@dfosco/tiny-canvas": "4.0.0-beta.27",
+    "@dfosco/storyboard-core": "4.0.0-beta.29",
+    "@dfosco/tiny-canvas": "4.0.0-beta.29",
     "@neodrag/react": "^2.3.1",
     "glob": "^11.0.0",
     "jsonc-parser": "^3.3.1",

package/src/canvas/CanvasPage.bridge.test.jsx

@@ -1,7 +1,7 @@
-import { fireEvent, render, screen, act } from '@testing-library/react'
+import { fireEvent, render, screen, act, waitFor } from '@testing-library/react'
 import CanvasPage from './CanvasPage.jsx'
 import { getCanvasPrimerAttrs, getCanvasThemeVars } from './canvasTheme.js'
-import { updateCanvas } from './canvasApi.js'
+import { addWidget, checkGitHubCliAvailable, fetchGitHubEmbed, updateCanvas } from './canvasApi.js'
 
 vi.mock('@dfosco/tiny-canvas', () => ({
   Canvas: ({ children, onDragEnd }) => (
@@ -77,6 +77,8 @@ vi.mock('./widgets/figmaUrl.js', () => ({
 
 vi.mock('./canvasApi.js', () => ({
   addWidget: vi.fn(),
+  checkGitHubCliAvailable: vi.fn(),
+  fetchGitHubEmbed: vi.fn(),
   updateCanvas: vi.fn(() => Promise.resolve({ success: true })),
   removeWidget: vi.fn(),
   uploadImage: vi.fn(),
@@ -94,9 +96,26 @@ vi.mock('./useUndoRedo.js', () => ({
 }))
 
 describe('CanvasPage canvas bridge', () => {
+  function dispatchTextPaste(text) {
+    const event = new Event('paste', { bubbles: true, cancelable: true })
+    Object.defineProperty(event, 'clipboardData', {
+      value: {
+        getData: (type) => (type === 'text/plain' ? text : ''),
+        items: [],
+      },
+    })
+    document.dispatchEvent(event)
+  }
+
   beforeEach(() => {
     delete window.__storyboardCanvasBridgeState
     vi.clearAllMocks()
+    addWidget.mockResolvedValue({
+      success: true,
+      widget: { id: 'widget-link', type: 'link-preview', position: { x: 0, y: 0 }, props: {} },
+    })
+    checkGitHubCliAvailable.mockResolvedValue({ available: true })
+    fetchGitHubEmbed.mockResolvedValue({ success: false })
   })
 
   it('publishes bridge state and responds to status requests', () => {
@@ -145,6 +164,72 @@ describe('CanvasPage canvas bridge', () => {
     document.removeEventListener('storyboard:canvas:unmounted', unmountedHandler)
   })
 
+  it('shows gh install banner when gh is unavailable during GitHub URL paste', async () => {
+    checkGitHubCliAvailable.mockResolvedValue({
+      available: false,
+      installUrl: 'https://github.com/cli/cli',
+    })
+
+    render(<CanvasPage name="design-overview" />)
+
+    await act(async () => {
+      dispatchTextPaste('https://github.com/dfosco/storyboard/issues/42')
+      await Promise.resolve()
+    })
+
+    await waitFor(() => {
+      expect(addWidget).toHaveBeenCalled()
+    })
+    expect(fetchGitHubEmbed).not.toHaveBeenCalled()
+    expect(screen.getByRole('link', { name: 'Install GitHub CLI' })).toHaveAttribute(
+      'href',
+      'https://github.com/cli/cli',
+    )
+  })
+
+  it('hydrates GitHub metadata when gh is available during paste', async () => {
+    checkGitHubCliAvailable.mockResolvedValue({ available: true })
+    fetchGitHubEmbed.mockResolvedValue({
+      success: true,
+      snapshot: {
+        kind: 'issue',
+        parentKind: 'issue',
+        context: 'GitHub · dfosco/storyboard · Issue #42',
+        title: '#42 Ship GitHub embeds',
+        body: 'Details from GitHub',
+        authors: ['dfosco'],
+        createdAt: '2026-01-01T00:00:00Z',
+        updatedAt: '2026-01-02T00:00:00Z',
+      },
+    })
+
+    render(<CanvasPage name="design-overview" />)
+
+    await act(async () => {
+      dispatchTextPaste('https://github.com/dfosco/storyboard/issues/42')
+      await Promise.resolve()
+    })
+
+    await waitFor(() => {
+      expect(fetchGitHubEmbed).toHaveBeenCalledWith('https://github.com/dfosco/storyboard/issues/42')
+    })
+    expect(addWidget).toHaveBeenCalledWith(
+      'design-overview',
+      expect.objectContaining({
+        type: 'link-preview',
+        props: expect.objectContaining({
+          title: '#42 Ship GitHub embeds',
+          width: 580,
+          height: 400,
+          github: expect.objectContaining({
+            context: 'GitHub · dfosco/storyboard · Issue #42',
+            body: 'Details from GitHub',
+          }),
+        }),
+      }),
+    )
+  })
+
   it.skip('persists dragged JSON widgets and JSX sources to canvas JSONL via update API', async () => {
     render(<CanvasPage canvasId="design-overview" />)
 

package/src/canvas/CanvasPage.jsx

@@ -9,10 +9,19 @@ import { schemas, getDefaults } from './widgets/widgetProps.js'
 import { getFeatures, isResizable } from './widgets/widgetConfig.js'
 import { createPasteContext, resolvePaste } from './widgets/pasteRules.js'
 import { getPasteRules } from '@dfosco/storyboard-core'
+import { isGitHubEmbedUrl } from './widgets/githubUrl.js'
 import WidgetChrome from './widgets/WidgetChrome.jsx'
 import ComponentWidget from './widgets/ComponentWidget.jsx'
 import useUndoRedo from './useUndoRedo.js'
-import { addWidget as addWidgetApi, updateCanvas, removeWidget as removeWidgetApi, uploadImage, getCanvas as getCanvasApi } from './canvasApi.js'
+import {
+  addWidget as addWidgetApi,
+  checkGitHubCliAvailable,
+  fetchGitHubEmbed,
+  getCanvas as getCanvasApi,
+  removeWidget as removeWidgetApi,
+  updateCanvas,
+  uploadImage,
+} from './canvasApi.js'
 import PageSelector from './PageSelector.jsx'
 import { stories as storyIndex } from 'virtual:storyboard-data-index'
 import styles from './CanvasPage.module.css'
@@ -24,6 +33,7 @@ const ZOOM_MAX = 200
 const VIEWPORT_TTL_MS = 15 * 60 * 1000
 
 const CANVAS_BRIDGE_STATE_KEY = '__storyboardCanvasBridgeState'
+const GH_INSTALL_URL = 'https://github.com/cli/cli'
 
 /** Matches branch-deploy base path prefixes like /branch--my-feature/ */
 const BRANCH_PREFIX_RE = /^\/branch--[^/]+/
@@ -42,7 +52,7 @@ function getToolbarColorMode(theme) {
 
 function resolveCanvasThemeFromStorage() {
   if (typeof localStorage === 'undefined') return 'light'
-  let sync = { prototype: true, toolbar: false, codeBoxes: true, canvas: false }
+  let sync = { prototype: true, toolbar: false, codeBoxes: true, canvas: true }
   try {
     const rawSync = localStorage.getItem('sb-theme-sync')
     if (rawSync) sync = { ...sync, ...JSON.parse(rawSync) }
@@ -248,7 +258,7 @@ function computeCanvasBounds(widgets, componentEntries) {
 }
 
 /** Renders a single JSON-defined widget by type lookup. */
-function WidgetRenderer({ widget, onUpdate, widgetRef }) {
+function WidgetRenderer({ widget, onUpdate, widgetRef, onRefreshGitHub, canRefreshGitHub }) {
   const Component = getWidgetComponent(widget.type)
   if (!Component) {
     console.warn(`[canvas] Unknown widget type: ${widget.type}`)
@@ -256,7 +266,14 @@ function WidgetRenderer({ widget, onUpdate, widgetRef }) {
   }
   const resizable = isResizable(widget.type) && !!onUpdate
   // Only pass ref to forwardRef-wrapped components (e.g. PrototypeEmbed)
-  const elementProps = { id: widget.id, props: widget.props, onUpdate, resizable }
+  const elementProps = {
+    id: widget.id,
+    props: widget.props,
+    onUpdate,
+    resizable,
+    onRefreshGitHub,
+    canRefreshGitHub,
+  }
   if (Component.$$typeof === Symbol.for('react.forward_ref')) {
     elementProps.ref = widgetRef
   }
@@ -278,10 +295,31 @@ const ChromeWrappedWidget = memo(function ChromeWrappedWidget({
   onUpdate,
   onRemove,
   onCopy,
+  onRefreshGitHub,
+  canRefreshGitHub,
   readOnly,
 }) {
   const widgetRef = useRef(null)
-  const features = getFeatures(widget.type, { isLocalDev: !readOnly })
+  const rawFeatures = getFeatures(widget.type, { isLocalDev: !readOnly })
+
+  // Dynamically adjust features based on widget state
+  const features = useMemo(() => {
+    const isGitHub = !!widget.props?.github
+    return rawFeatures.map((f) => {
+      // Toggle collapse label and hide when content is short (no github = no collapse)
+      if (f.action === 'toggle-collapse') {
+        if (!isGitHub) return null
+        return {
+          ...f,
+          label: widget.props?.collapsed ? 'Expand height' : 'Collapse height',
+          icon: widget.props?.collapsed ? 'unfold' : 'fold',
+        }
+      }
+      // Hide refresh-github for non-GitHub link previews
+      if (f.action === 'refresh-github' && !isGitHub) return null
+      return f
+    }).filter(Boolean)
+  }, [rawFeatures, widget.props?.github, widget.props?.collapsed])
 
   const handleAction = useCallback((actionId) => {
     if (actionId === 'delete') {
@@ -289,10 +327,28 @@ const ChromeWrappedWidget = memo(function ChromeWrappedWidget({
     } else if (actionId === 'copy') {
       onCopy?.(widget)
     } else if (actionId === 'copy-text') {
-      const text = widget.props?.text || widget.props?.content || ''
+      const title = widget.props?.title || ''
+      const body = widget.props?.text || widget.props?.content || widget.props?.github?.body || ''
+      const text = title && body ? `# ${title}\n\n${body}` : title || body
       navigator.clipboard?.writeText(text).catch(() => {})
+    } else if (actionId === 'open-external') {
+      const url = widget.props?.url || widget.props?.src
+      if (url) window.open(url, '_blank', 'noopener,noreferrer')
+    } else if (actionId === 'refresh-github') {
+      const url = widget.props?.url
+      if (url && onRefreshGitHub) onRefreshGitHub(widget.id, url)
+    } else if (actionId === 'toggle-collapse') {
+      const wasCollapsed = !!widget.props?.collapsed
+      onUpdate?.(widget.id, { collapsed: !wasCollapsed })
+      // When collapsing, pan viewport to center the widget
+      if (!wasCollapsed) {
+        requestAnimationFrame(() => {
+          const el = document.getElementById(widget.id)
+          if (el) el.scrollIntoView({ behavior: 'smooth', block: 'center' })
+        })
+      }
     }
-  }, [widget, onRemove, onCopy])
+  }, [widget, onRemove, onCopy, onRefreshGitHub])
 
   const handleWidgetFieldUpdate = useCallback((updates) => {
     onUpdate?.(widget.id, updates)
@@ -317,6 +373,8 @@ const ChromeWrappedWidget = memo(function ChromeWrappedWidget({
         widget={widget}
         onUpdate={onUpdate ? handleWidgetFieldUpdate : undefined}
         widgetRef={widgetRef}
+        onRefreshGitHub={onRefreshGitHub}
+        canRefreshGitHub={canRefreshGitHub}
       />
     </WidgetChrome>
   )
@@ -340,7 +398,8 @@ const ChromeWrappedWidget = memo(function ChromeWrappedWidget({
  *
  * @param {{ canvasId: string }} props - Canvas name as indexed by the data plugin
  */
-export default function CanvasPage({ canvasId, siblingPages = [], canvasMeta = null }) {
+export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages = [], canvasMeta = null }) {
+  const canvasId = canvasIdProp || name || ''
   const { canvas, jsxExports, jsxError, loading } = useCanvas(canvasId)
   const isLocalDev = typeof window !== 'undefined' && window.__SB_LOCAL_DEV__ === true && !new URLSearchParams(window.location.search).has('prodMode')
 
@@ -364,6 +423,7 @@ export default function CanvasPage({ canvasId, siblingPages = [], canvasMeta = n
   const [canvasTheme, setCanvasTheme] = useState(() => resolveCanvasThemeFromStorage())
   const [snapEnabled, setSnapEnabled] = useState(canvas?.snapToGrid ?? false)
   const [snapGridSize, setSnapGridSize] = useState(canvas?.gridSize || 40)
+  const [showGhInstallBanner, setShowGhInstallBanner] = useState(false)
 
   // Refs for snap settings (used by drop handler inside effect closure)
   const snapEnabledRef = useRef(snapEnabled)
@@ -574,6 +634,58 @@ export default function CanvasPage({ canvasId, siblingPages = [], canvasMeta = n
     }
   }, [canvasId, localWidgets, undoRedo])
 
+  const showMissingGhBanner = useCallback(() => {
+    setShowGhInstallBanner(true)
+  }, [])
+
+  const buildGitHubPreviewUpdates = useCallback(async (url) => {
+    try {
+      const availability = await checkGitHubCliAvailable()
+      if (!availability?.available) {
+        showMissingGhBanner()
+        return null
+      }
+
+      const result = await fetchGitHubEmbed(url)
+      if (result?.code === 'gh_unavailable') {
+        showMissingGhBanner()
+        return null
+      }
+      if (!result?.success || !result?.snapshot) return null
+
+      const snapshot = result.snapshot
+      return {
+        title: snapshot.title || '',
+        width: 580,
+        height: 400,
+        github: {
+          kind: snapshot.kind || 'issue',
+          parentKind: snapshot.parentKind || snapshot.kind || 'issue',
+          context: snapshot.context || '',
+          body: snapshot.body || '',
+          bodyHtml: snapshot.bodyHtml || '',
+          authors: Array.isArray(snapshot.authors)
+            ? snapshot.authors.filter((author) => typeof author === 'string' && author.trim())
+            : [],
+          createdAt: snapshot.createdAt ?? null,
+          updatedAt: snapshot.updatedAt ?? null,
+          fetchedAt: new Date().toISOString(),
+        },
+      }
+    } catch (err) {
+      console.error('[canvas] Failed to fetch GitHub embed metadata:', err)
+      return null
+    }
+  }, [showMissingGhBanner])
+
+  const handleRefreshGitHubWidget = useCallback(async (widgetId, url) => {
+    if (!widgetId || !url) return { updated: false }
+    const updates = await buildGitHubPreviewUpdates(url)
+    if (!updates) return { updated: false }
+    handleWidgetUpdate(widgetId, updates)
+    return { updated: true }
+  }, [buildGitHubPreviewUpdates, handleWidgetUpdate])
+
   const debouncedSourceSave = useRef(
     debounce((canvasId, sources) => {
       updateCanvas(canvasId, { sources }).catch((err) =>
@@ -1371,7 +1483,13 @@ export default function CanvasPage({ canvasId, siblingPages = [], canvasMeta = n
       e.preventDefault()
       const resolved = resolvePaste(text, pasteCtx, getPasteRules())
       if (!resolved) return
-      const { type, props } = resolved
+      const { type } = resolved
+      let props = resolved.props
+
+      if (type === 'link-preview' && isGitHubEmbedUrl(props?.url || text)) {
+        const githubUpdates = await buildGitHubPreviewUpdates(props?.url || text)
+        if (githubUpdates) props = { ...props, ...githubUpdates }
+      }
 
       const center = getViewportCenter(scrollRef.current, zoomRef.current / 100)
       const pos = centerPositionForWidget(center, type, props)
@@ -1392,6 +1510,7 @@ export default function CanvasPage({ canvasId, siblingPages = [], canvasMeta = n
 
     document.addEventListener('paste', handlePaste)
     return () => document.removeEventListener('paste', handlePaste)
+  // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [canvasId, undoRedo, localWidgets])
 
   // --- Drag and drop handlers for images from Finder/file manager ---
@@ -1768,6 +1887,8 @@ export default function CanvasPage({ canvasId, siblingPages = [], canvasMeta = n
           onUpdate={isLocalDev ? handleWidgetUpdate : undefined}
           onCopy={isLocalDev ? handleWidgetCopy : undefined}
           onRemove={isLocalDev ? handleWidgetRemoveAndDeselect : undefined}
+          onRefreshGitHub={isLocalDev ? handleRefreshGitHubWidget : undefined}
+          canRefreshGitHub={isLocalDev}
           readOnly={!isLocalDev}
         />
       </div>
@@ -1816,6 +1937,28 @@ export default function CanvasPage({ canvasId, siblingPages = [], canvasMeta = n
           </Canvas>
         </div>
       </div>
+      {showGhInstallBanner && (
+        <aside className={styles.ghInstallBanner} role="status" aria-live="polite">
+          <span className={styles.ghInstallBannerText}>
+            GitHub embeds require local <code>gh</code> CLI access.
+          </span>
+          <a
+            href={GH_INSTALL_URL}
+            target="_blank"
+            rel="noopener noreferrer"
+            className={styles.ghInstallBannerLink}
+          >
+            Install GitHub CLI
+          </a>
+          <button
+            type="button"
+            className={styles.ghInstallBannerDismiss}
+            onClick={() => setShowGhInstallBanner(false)}
+          >
+            Dismiss
+          </button>
+        </aside>
+      )}
     </>
   )
 }

package/src/canvas/CanvasPage.module.css

@@ -86,3 +86,57 @@
   pointer-events: none;
   user-select: none;
 }
+
+.ghInstallBanner {
+  position: fixed;
+  left: 50%;
+  bottom: 12px;
+  transform: translateX(-50%);
+  z-index: 15;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 8px 12px;
+  border-radius: 8px;
+  border: 1px solid var(--borderColor-default, #d1d9e0);
+  background: color-mix(in srgb, var(--bgColor-default, #ffffff) 88%, transparent);
+  box-shadow: 0 6px 20px rgba(0, 0, 0, 0.16);
+  backdrop-filter: blur(8px);
+  font-size: 12px;
+  color: var(--fgColor-default, #1f2328);
+}
+
+.ghInstallBannerText {
+  white-space: nowrap;
+}
+
+.ghInstallBannerText code {
+  font-size: 11px;
+  padding: 1px 4px;
+  border-radius: 4px;
+  background: var(--bgColor-muted, #f6f8fa);
+}
+
+.ghInstallBannerLink {
+  color: var(--fgColor-accent, #0969da);
+  font-weight: 600;
+  text-decoration: none;
+}
+
+.ghInstallBannerLink:hover {
+  text-decoration: underline;
+}
+
+.ghInstallBannerDismiss {
+  border: 1px solid var(--borderColor-default, #d1d9e0);
+  background: var(--bgColor-default, #ffffff);
+  color: var(--fgColor-default, #1f2328);
+  border-radius: 6px;
+  font-size: 11px;
+  padding: 4px 8px;
+  cursor: pointer;
+}
+
+.ghInstallBannerDismiss:hover {
+  background: var(--bgColor-muted, #f6f8fa);
+}

package/src/canvas/CanvasPage.multiselect.test.jsx

@@ -103,6 +103,8 @@ vi.mock('./widgets/figmaUrl.js', () => ({
 
 vi.mock('./canvasApi.js', () => ({
   addWidget: vi.fn(),
+  checkGitHubCliAvailable: vi.fn(() => Promise.resolve({ available: true })),
+  fetchGitHubEmbed: vi.fn(() => Promise.resolve({ success: false })),
   updateCanvas: vi.fn(() => Promise.resolve({ success: true })),
   removeWidget: vi.fn(() => Promise.resolve({ success: true })),
   uploadImage: vi.fn(),

package/src/canvas/canvasApi.js

@@ -53,3 +53,11 @@ export function toggleImagePrivacy(filename) {
 export function getCanvas(canvasId) {
   return request(`/read?name=${encodeURIComponent(canvasId)}`, 'GET')
 }
+
+export function checkGitHubCliAvailable() {
+  return request('/github/available', 'GET')
+}
+
+export function fetchGitHubEmbed(url) {
+  return request('/github/embed', 'POST', { url })
+}