@dfosco/storyboard-core 1.17.1 → 1.17.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dfosco/storyboard-core",
-  "version": "1.17.1",
+  "version": "1.17.3",
   "type": "module",
   "license": "MIT",
   "repository": {

package/src/comments/commentCache.js

@@ -53,3 +53,57 @@ export function clearCachedComments(route) {
     // ignore
   }
 }
+
+// --- Pending (failed) comments ---
+
+const PENDING_PREFIX = 'sb-pending-comments:'
+
+/**
+ * Save a pending comment that failed to submit.
+ * @param {string} route
+ * @param {{ id: string, x: number, y: number, text: string, author: object }} comment
+ */
+export function savePendingComment(route, comment) {
+  try {
+    const pending = getPendingComments(route)
+    // Replace if same id already exists, else append
+    const idx = pending.findIndex(c => c.id === comment.id)
+    if (idx >= 0) pending[idx] = comment
+    else pending.push(comment)
+    localStorage.setItem(PENDING_PREFIX + route, JSON.stringify(pending))
+  } catch {
+    // ignore
+  }
+}
+
+/**
+ * Get all pending (failed) comments for a route.
+ * @param {string} route
+ * @returns {Array<{ id: string, x: number, y: number, text: string, author: object }>}
+ */
+export function getPendingComments(route) {
+  try {
+    const raw = localStorage.getItem(PENDING_PREFIX + route)
+    return raw ? JSON.parse(raw) : []
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Remove a pending comment (after successful retry or dismissal).
+ * @param {string} route
+ * @param {string} pendingId
+ */
+export function removePendingComment(route, pendingId) {
+  try {
+    const pending = getPendingComments(route).filter(c => c.id !== pendingId)
+    if (pending.length > 0) {
+      localStorage.setItem(PENDING_PREFIX + route, JSON.stringify(pending))
+    } else {
+      localStorage.removeItem(PENDING_PREFIX + route)
+    }
+  } catch {
+    // ignore
+  }
+}

package/src/comments/index.js

@@ -33,7 +33,7 @@ export {
 } from './api.js'
 
 // Cache
-export { getCachedComments, setCachedComments, clearCachedComments } from './commentCache.js'
+export { getCachedComments, setCachedComments, clearCachedComments, savePendingComment, getPendingComments, removePendingComment } from './commentCache.js'
 
 // GraphQL client (for advanced use)
 export { graphql } from './graphql.js'

package/src/comments/ui/authModal.js

@@ -34,7 +34,7 @@ export function openAuthModal() {
         </div>
         <div class="pa4">
           <p class="ma0 mb3 lh-copy sb-fg-muted sb-f-sm">
-            Create a <a class="sb-fg-accent no-underline" href="https://github.com/settings/tokens/new?scopes=repo&description=Storyboard+Comments" target="_blank" rel="noopener">GitHub Personal Access Token</a> with access to <b>github/storyboard</b> repository and <b>Discussions</b> read/write scope. Then enter the token below to sign in and enable commenting features.
+            Create a <a class="sb-fg-accent no-underline" href="https://github.com/settings/personal-access-tokens/new" target="_blank" rel="noopener">GitHub Fine-Grained Personal Access Token</a> with access to <b>github/storyboard</b> repository and <b>Discussions</b> read/write scope. Then enter the token below to sign in and enable commenting features.
           </p>
           <label class="db mb1 fw5 sb-fg sb-f-sm" for="sb-auth-token-input">Personal Access Token</label>
           <input class="sb-input w-100 ph3 pv2 br2 f6 code db" id="sb-auth-token-input" type="password"

package/src/comments/ui/comments.css

@@ -139,7 +139,18 @@
 .sb-comment-window * { scrollbar-width: none; }
 .sb-comment-window *::-webkit-scrollbar { display: none; }
 .sb-composer        { width: 280px; z-index: 100001; }
-.sb-comment-overlay { z-index: 99998; pointer-events: none; }
+.sb-comment-overlay {
+  position: absolute;
+  top: 0; left: 0; right: 0; bottom: 0;
+  z-index: 99998;
+  pointer-events: none;
+}
+.sb-comment-mode {
+  position: relative;
+}
+.sb-comment-mode .sb-comment-overlay {
+  pointer-events: auto;
+}
 .sb-auth-backdrop   { z-index: 100000; background: rgba(0,0,0,0.5); backdrop-filter: blur(4px); }
 .sb-comments-drawer-backdrop { z-index: 99997; background: rgba(0,0,0,0.4); }
 .sb-comments-drawer { z-index: 99998; width: 420px; max-width: 90vw; }
@@ -187,6 +198,25 @@
   border-color: var(--sb-fg-muted);
   opacity: 0.5;
 }
+.sb-comment-pin-pending {
+  border-color: var(--sb-fg-muted) !important;
+  opacity: 0.6;
+  animation: sb-pin-pulse 1.2s ease-in-out infinite;
+}
+.sb-comment-pin-failed {
+  border-color: var(--sb-fg-danger) !important;
+  cursor: pointer;
+  animation: sb-pin-shake 0.4s ease-in-out;
+}
+@keyframes sb-pin-pulse {
+  0%, 100% { opacity: 0.6; }
+  50% { opacity: 1; }
+}
+@keyframes sb-pin-shake {
+  0%, 100% { transform: translateX(0); }
+  25% { transform: translateX(-3px); }
+  75% { transform: translateX(3px); }
+}
 
 /* Error alert */
 .sb-error-alert {

package/src/comments/ui/composer.js

@@ -5,7 +5,6 @@
  * Styled with Tachyons + sb-* custom classes for light/dark mode support.
  */
 
-import { createComment } from '../api.js'
 import { getCachedUser } from '../auth.js'
 
 /**
@@ -16,7 +15,7 @@ import { getCachedUser } from '../auth.js'
  * @param {string} route - Current route path
  * @param {object} [callbacks] - Optional callbacks
  * @param {() => void} [callbacks.onCancel] - Called when composer is dismissed
- * @param {(comment: object) => void} [callbacks.onSubmit] - Called after successful submit
+ * @param {(text: string) => void} [callbacks.onSubmitOptimistic] - Called with text for optimistic submission
  * @returns {{ el: HTMLElement, destroy: () => void }}
  */
 export function showComposer(container, xPct, yPct, route, callbacks = {}) {
@@ -47,8 +46,8 @@ export function showComposer(container, xPct, yPct, route, callbacks = {}) {
       </template>
       <div class="flex items-center justify-end pa3">
         <button class="sb-btn-cancel ph3 pv2 br2 f7 fw5 pointer mr1" @click="cancel()">Cancel</button>
-        <button class="sb-btn-success ph3 pv2 br2 f7 fw5 pointer bn" :disabled="submitting"
-                @click="submit()" x-text="submitting ? 'Posting…' : 'Comment'">Comment</button>
+        <button class="sb-btn-success ph3 pv2 br2 f7 fw5 pointer bn"
+                @click="submit()">Comment</button>
       </div>
     </div>
   `
@@ -81,22 +80,13 @@ export function showComposer(container, xPct, yPct, route, callbacks = {}) {
       submitting: false,
       error: null,
 
-      async submit() {
+      submit() {
         const val = this.text.trim()
         if (!val) return
 
-        this.submitting = true
-        this.error = null
-
-        try {
-          const comment = await createComment(route, xPct, yPct, val)
-          destroy()
-          callbacks.onSubmit?.(comment)
-        } catch (err) {
-          this.error = err.message
-          this.submitting = false
-          console.error('[storyboard] Failed to post comment:', err)
-        }
+        // Close composer immediately and hand off to optimistic handler
+        destroy()
+        callbacks.onSubmitOptimistic?.(val)
       },
 
       cancel() {

package/src/comments/ui/mount.js

@@ -7,10 +7,10 @@
 
 import Alpine from 'alpinejs'
 import { isCommentsEnabled } from '../config.js'
-import { isAuthenticated } from '../auth.js'
+import { isAuthenticated, getCachedUser } from '../auth.js'
 import { toggleCommentMode, setCommentMode, isCommentModeActive, subscribeToCommentMode } from '../commentMode.js'
-import { fetchRouteCommentsSummary, fetchCommentDetail, moveComment } from '../api.js'
-import { getCachedComments, setCachedComments, clearCachedComments } from '../commentCache.js'
+import { fetchRouteCommentsSummary, fetchCommentDetail, moveComment, createComment } from '../api.js'
+import { getCachedComments, setCachedComments, clearCachedComments, savePendingComment, getPendingComments, removePendingComment } from '../commentCache.js'
 import { showComposer } from './composer.js'
 import { openAuthModal } from './authModal.js'
 import { showCommentWindow, closeCommentWindow } from './commentWindow.js'
@@ -27,17 +27,19 @@ function esc(str) {
   return d.innerHTML
 }
 
-function getContentContainer() {
-  return document.body
-}
-
 function ensureOverlay() {
   if (overlay) return overlay
-  const container = getContentContainer()
 
   overlay = document.createElement('div')
-  overlay.className = 'sb-comment-overlay absolute top-0 right-0 bottom-0 left-0 pe-none'
-  container.appendChild(overlay)
+  overlay.className = 'sb-comment-overlay'
+  document.body.appendChild(overlay)
+
+  // Click handler for placing comments lives on the overlay itself
+  overlay.addEventListener('click', (e) => {
+    if (!isCommentModeActive()) return
+    if (e.target.closest('.sb-composer') || e.target.closest('.sb-comment-pin') || e.target.closest('.sb-comment-window')) return
+    handleOverlayClick(e)
+  })
 
   return overlay
 }
@@ -74,6 +76,99 @@ function reloadComments() {
   loadAndRenderComments()
 }
 
+/**
+ * Render an optimistic pin immediately after the user submits a comment.
+ * Returns callbacks to mark it as succeeded or failed.
+ */
+function renderOptimisticPin(ov, xPct, yPct, text, user) {
+  const pendingId = `pending-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+  const pin = document.createElement('div')
+  pin.className = 'sb-comment-pin sb-comment-pin-pending absolute br-100 sb-bg pointer sb-shadow pe-auto overflow-hidden'
+  pin.style.left = `${xPct}%`
+  pin.style.top = `${yPct}%`
+  pin.title = `${user?.login ?? 'you'}: ${text.slice(0, 80)}`
+
+  pin.innerHTML = user?.avatarUrl
+    ? `<img class="br-100 db sb-pin-img" src="${esc(user.avatarUrl)}" alt="${esc(user.login)}" draggable="false" />`
+    : ''
+
+  ov.appendChild(pin)
+  renderedPins.push(pin)
+
+  return {
+    pendingId,
+    succeed: () => {
+      pin.classList.remove('sb-comment-pin-pending')
+    },
+    fail: () => {
+      pin.classList.remove('sb-comment-pin-pending')
+      pin.classList.add('sb-comment-pin-failed')
+      pin.title = `⚠ Failed to post — click to retry: ${text.slice(0, 60)}`
+
+      // Save to localStorage for persistence
+      const route = getCurrentRoute()
+      savePendingComment(route, { id: pendingId, x: xPct, y: yPct, text, author: user })
+
+      // Click to retry
+      pin.addEventListener('click', async (e) => {
+        e.stopPropagation()
+        pin.classList.remove('sb-comment-pin-failed')
+        pin.classList.add('sb-comment-pin-pending')
+        pin.title = 'Retrying…'
+        try {
+          await createComment(route, xPct, yPct, text)
+          removePendingComment(route, pendingId)
+          pin.classList.remove('sb-comment-pin-pending')
+          reloadComments()
+        } catch {
+          pin.classList.remove('sb-comment-pin-pending')
+          pin.classList.add('sb-comment-pin-failed')
+          pin.title = `⚠ Failed to post — click to retry: ${text.slice(0, 60)}`
+        }
+      })
+    },
+  }
+}
+
+/**
+ * Render pins for pending (failed) comments from localStorage.
+ */
+function renderPendingPins(ov) {
+  const route = getCurrentRoute()
+  const pending = getPendingComments(route)
+  for (const p of pending) {
+    const pin = document.createElement('div')
+    pin.className = 'sb-comment-pin sb-comment-pin-failed absolute br-100 sb-bg pointer sb-shadow pe-auto overflow-hidden'
+    pin.style.left = `${p.x}%`
+    pin.style.top = `${p.y}%`
+    pin.title = `⚠ Failed to post — click to retry: ${p.text?.slice(0, 60) ?? ''}`
+
+    pin.innerHTML = p.author?.avatarUrl
+      ? `<img class="br-100 db sb-pin-img" src="${esc(p.author.avatarUrl)}" alt="${esc(p.author.login)}" draggable="false" />`
+      : ''
+
+    pin.addEventListener('click', async (e) => {
+      e.stopPropagation()
+      pin.classList.remove('sb-comment-pin-failed')
+      pin.classList.add('sb-comment-pin-pending')
+      pin.title = 'Retrying…'
+      try {
+        await createComment(route, p.x, p.y, p.text)
+        removePendingComment(route, p.id)
+        pin.remove()
+        reloadComments()
+      } catch {
+        pin.classList.remove('sb-comment-pin-pending')
+        pin.classList.add('sb-comment-pin-failed')
+        pin.title = `⚠ Failed to post — click to retry: ${p.text?.slice(0, 60) ?? ''}`
+      }
+    })
+
+    ov.appendChild(pin)
+    renderedPins.push(pin)
+  }
+}
+
 function renderPin(ov, comment, index) {
   const hue = Math.round((index * 137.5) % 360)
   const pin = document.createElement('div')
@@ -97,21 +192,19 @@ function renderPin(ov, comment, index) {
   pin.addEventListener('mousedown', (e) => {
     if (e.button !== 0) return
     dragged = false
-    const container = getContentContainer()
-    const containerRect = container.getBoundingClientRect()
     const startX = e.clientX
     const startY = e.clientY
-    const startLeft = (parseFloat(pin.style.left) / 100) * containerRect.width
-    const startTop = (parseFloat(pin.style.top) / 100) * containerRect.height
+    const startLeftPct = parseFloat(pin.style.left)
+    const startTopPct = parseFloat(pin.style.top)
 
     const onMove = (ev) => {
       const dx = ev.clientX - startX
       const dy = ev.clientY - startY
       if (!dragged && Math.abs(dx) < 4 && Math.abs(dy) < 4) return
       dragged = true
-      const cr = container.getBoundingClientRect()
-      const xPct = Math.round(((startLeft + dx) / cr.width) * 1000) / 10
-      const yPct = Math.round(((startTop + dy) / cr.height) * 1000) / 10
+      const xPct = Math.round((startLeftPct + (dx / window.innerWidth) * 100) * 10) / 10
+      const docHeight = document.documentElement.scrollHeight
+      const yPct = Math.round((startTopPct + (dy / docHeight) * 100) * 10) / 10
       pin.style.left = `${xPct}%`
       pin.style.top = `${yPct}%`
     }
@@ -121,11 +214,11 @@ function renderPin(ov, comment, index) {
       document.removeEventListener('mouseup', onUp)
       if (!dragged) return
 
-      const cr = container.getBoundingClientRect()
       const dx = ev.clientX - startX
       const dy = ev.clientY - startY
-      const xPct = Math.round(((startLeft + dx) / cr.width) * 1000) / 10
-      const yPct = Math.round(((startTop + dy) / cr.height) * 1000) / 10
+      const xPct = Math.round((startLeftPct + (dx / window.innerWidth) * 100) * 10) / 10
+      const docHeight = document.documentElement.scrollHeight
+      const yPct = Math.round((startTopPct + (dy / docHeight) * 100) * 10) / 10
       comment.meta = { ...comment.meta, x: xPct, y: yPct }
 
       try {
@@ -183,6 +276,7 @@ function renderCachedPins() {
       renderPin(ov, comment, i)
     }
   })
+  renderPendingPins(ov)
 }
 
 async function loadAndRenderComments() {
@@ -206,13 +300,17 @@ async function loadAndRenderComments() {
       setCachedComments(route, discussion)
     }
     clearPins()
-    if (!discussion?.comments?.length) return
+    if (!discussion?.comments?.length) {
+      renderPendingPins(ov)
+      return
+    }
 
     discussion.comments.forEach((comment, i) => {
       if (comment.meta?.x != null && comment.meta?.y != null) {
         renderPin(ov, comment, i)
       }
     })
+    renderPendingPins(ov)
 
     autoOpenCommentFromUrl(ov, discussion)
   } catch (err) {
@@ -228,9 +326,9 @@ async function autoOpenCommentFromUrl(ov, discussion) {
   if (!comment) return
 
   if (comment.meta?.y != null) {
-    const container = getContentContainer()
-    const yPx = (comment.meta.y / 100) * container.scrollHeight
-    const viewTop = container.scrollTop || window.scrollY
+    const docHeight = document.documentElement.scrollHeight
+    const yPx = (comment.meta.y / 100) * docHeight
+    const viewTop = window.scrollY
     const viewBottom = viewTop + window.innerHeight
     if (yPx < viewTop || yPx > viewBottom) {
       const scrollTarget = Math.max(0, yPx - window.innerHeight / 3)
@@ -272,17 +370,29 @@ function handleOverlayClick(e) {
     activeComposer = null
   }
 
-  const container = getContentContainer()
-  const rect = container.getBoundingClientRect()
-  const xPct = Math.round(((e.clientX - rect.left) / rect.width) * 1000) / 10
-  const yPct = Math.round(((e.clientY - rect.top + container.scrollTop) / container.scrollHeight) * 1000) / 10
+  // x as percentage of viewport width, y as percentage of full document height
+  const xPct = Math.round((e.clientX / window.innerWidth) * 1000) / 10
+  const docHeight = document.documentElement.scrollHeight
+  const yPct = Math.round(((e.clientY + window.scrollY) / docHeight) * 1000) / 10
 
   const ov = ensureOverlay()
-  activeComposer = showComposer(ov, xPct, yPct, getCurrentRoute(), {
+  const route = getCurrentRoute()
+  activeComposer = showComposer(ov, xPct, yPct, route, {
     onCancel: () => { activeComposer = null },
-    onSubmit: () => {
+    onSubmitOptimistic: (text) => {
       activeComposer = null
-      reloadComments()
+      const user = getCachedUser()
+      const opt = renderOptimisticPin(ov, xPct, yPct, text, user)
+      // Fire API call in background
+      createComment(route, xPct, yPct, text)
+        .then(() => {
+          opt.succeed()
+          reloadComments()
+        })
+        .catch((err) => {
+          console.error('[storyboard] Failed to post comment:', err)
+          opt.fail()
+        })
     },
   })
 }
@@ -327,17 +437,6 @@ export function mountComments() {
 
   subscribeToCommentMode(setBodyCommentMode)
 
-  // Click handler for placing comments — uses document so devtools/modals can be excluded
-  document.addEventListener('click', (e) => {
-    if (!isCommentModeActive()) return
-    // Let devtools, modals, drawers, and existing comment UI handle their own clicks
-    if (e.target.closest('.sb-devtools-wrapper') || e.target.closest('.sb-auth-backdrop') ||
-        e.target.closest('.sb-comments-drawer') || e.target.closest('.sb-comments-drawer-backdrop') ||
-        e.target.closest('.sb-composer') || e.target.closest('.sb-comment-pin') ||
-        e.target.closest('.sb-comment-window')) return
-    handleOverlayClick(e)
-  })
-
   window.addEventListener('keydown', (e) => {
     const tag = e.target.tagName
     if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT' || e.target.isContentEditable) {

package/src/comments/ui/mount.test.js

@@ -21,12 +21,16 @@ vi.mock('../api.js', () => ({
   fetchRouteCommentsSummary: vi.fn(),
   fetchCommentDetail: vi.fn(),
   moveComment: vi.fn(),
+  createComment: vi.fn(),
 }))
 
 vi.mock('../commentCache.js', () => ({
   getCachedComments: vi.fn(() => null),
   setCachedComments: vi.fn(),
   clearCachedComments: vi.fn(),
+  savePendingComment: vi.fn(),
+  getPendingComments: vi.fn(() => []),
+  removePendingComment: vi.fn(),
 }))
 
 vi.mock('./composer.js', () => ({
@@ -74,11 +78,15 @@ describe('mount.js', () => {
       fetchRouteCommentsSummary: vi.fn(),
       fetchCommentDetail: vi.fn(),
       moveComment: vi.fn(),
+      createComment: vi.fn(),
     }))
     vi.doMock('../commentCache.js', () => ({
       getCachedComments: vi.fn(() => null),
       setCachedComments: vi.fn(),
       clearCachedComments: vi.fn(),
+      savePendingComment: vi.fn(),
+      getPendingComments: vi.fn(() => []),
+      removePendingComment: vi.fn(),
     }))
     vi.doMock('./composer.js', () => ({ showComposer: vi.fn() }))
     vi.doMock('./authModal.js', () => ({ openAuthModal: vi.fn() }))