@dfosco/storyboard-core 1.22.0 → 1.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dfosco/storyboard-core",
-  "version": "1.22.0",
+  "version": "1.24.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -13,11 +13,14 @@
   ],
   "exports": {
     ".": "./src/index.js",
+    "./vite/server": "./src/vite/server-plugin.js",
     "./comments": "./src/comments/index.js",
-    "./comments/ui/comments.css": "./src/comments/ui/comments.css"
+    "./comments/ui/comments.css": "./src/comments/ui/comments.css",
+    "./workshop/ui/mount.js": "./src/workshop/ui/mount.js"
   },
   "dependencies": {
     "alpinejs": "^3.15.8",
+    "jsonc-parser": "^3.3.1",
     "tachyons": "^4.12.0"
   }
 }

package/src/vite/server-plugin.js

@@ -0,0 +1,176 @@
+/**
+ * Storyboard Server Plugin — core dev-server infrastructure.
+ *
+ * Always-on Vite plugin that mounts a middleware backbone at `/_storyboard/`.
+ * Reads `storyboard.config.json` for workshop features and plugin config.
+ * Workshop API routes are wired directly; plugins register via the registry.
+ *
+ * Usage in vite.config.js:
+ *   import storyboardServer from '@dfosco/storyboard-core/vite/server'
+ *   storyboardServer()  // reads storyboard.config.json, no args needed
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { parse as parseJsonc } from 'jsonc-parser'
+import { features as workshopFeatures } from '../workshop/features/registry.js'
+
+const API_PREFIX = '/_storyboard/'
+
+/**
+ * Parse JSON request body from an IncomingMessage.
+ */
+function parseJsonBody(req) {
+  return new Promise((resolve, reject) => {
+    let body = ''
+    req.on('data', (chunk) => { body += chunk })
+    req.on('end', () => {
+      if (!body) return resolve({})
+      try { resolve(JSON.parse(body)) }
+      catch { reject(new Error('Invalid JSON body')) }
+    })
+    req.on('error', reject)
+  })
+}
+
+/**
+ * Send a JSON response.
+ */
+function sendJson(res, status, data) {
+  res.writeHead(status, { 'Content-Type': 'application/json' })
+  res.end(JSON.stringify(data))
+}
+
+/**
+ * Read storyboard.config.json from the project root.
+ */
+function readConfig(root) {
+  const configPath = path.join(root, 'storyboard.config.json')
+  if (!fs.existsSync(configPath)) return {}
+  try {
+    const raw = fs.readFileSync(configPath, 'utf-8')
+    return parseJsonc(raw) || {}
+  } catch {
+    return {}
+  }
+}
+
+/**
+ * Check if any workshop feature is enabled.
+ */
+function hasAnyWorkshopFeature(workshopConfig) {
+  if (!workshopConfig?.features) return false
+  return Object.values(workshopConfig.features).some(Boolean)
+}
+
+/**
+ * Core storyboard server Vite plugin.
+ */
+export default function storyboardServer() {
+  let root = ''
+  let base = '/'
+  let config = {}
+
+  // Route handler registry — plugins register here during setup
+  const routeHandlers = new Map()
+  const clientScripts = []
+
+  return {
+    name: 'storyboard-server',
+
+    configResolved(viteConfig) {
+      root = viteConfig.root
+      base = viteConfig.base || '/'
+      config = readConfig(root)
+    },
+
+    configureServer(server) {
+      const workshopConfig = config.workshop || {}
+
+      // If workshop is explicitly disabled, skip everything
+      if (workshopConfig.enabled === false) return
+
+      const enabledFeatures = workshopConfig.features || {}
+
+      // Wire workshop API routes for each enabled feature
+      for (const [featureName, featureModule] of Object.entries(workshopFeatures)) {
+        if (enabledFeatures[featureName] === false) continue
+        if (featureModule.serverSetup) {
+          const templatesDir = path.resolve(
+            path.dirname(new URL(import.meta.url).pathname),
+            `../workshop/features/${featureName}/templates`
+          )
+          routeHandlers.set('workshop', featureModule.serverSetup({ root, sendJson }, templatesDir))
+        }
+      }
+
+      // Inject workshop client UI when any feature is enabled
+      if (hasAnyWorkshopFeature(workshopConfig)) {
+        // Resolve the actual filesystem path for the mount script.
+        // Use /@fs/ prefix so Vite serves it through its module pipeline.
+        const mountPath = path.resolve(
+          path.dirname(new URL(import.meta.url).pathname),
+          '../workshop/ui/mount.js'
+        )
+        clientScripts.push('/@fs' + mountPath)
+      }
+
+      // Plugin registry for external plugins (future use).
+      // Plugins call registerRoutes/registerClientScript in their setup().
+      // const pluginCtx = { server, root, config, registerRoutes, registerClientScript }
+      // Future: auto-discover and initialize plugins from pluginsConfig here
+
+      // Mount the /_storyboard/ middleware router
+      // Vite's dev server strips the base path from req.url for middleware,
+      // but the base-redirect plugin may redirect bare URLs first.
+      // We check both with and without base prefix.
+      server.middlewares.use(async (req, res, next) => {
+        if (!req.url) return next()
+
+        // Strip base path if present to normalize the URL
+        let url = req.url
+        const baseNoTrail = base.replace(/\/$/, '')
+        if (baseNoTrail && url.startsWith(baseNoTrail)) {
+          url = url.slice(baseNoTrail.length) || '/'
+        }
+
+        if (!url.startsWith(API_PREFIX)) return next()
+
+        // Parse: /_storyboard/{prefix}/{rest}
+        const pathAfterPrefix = url.slice(API_PREFIX.length)
+        const slashIndex = pathAfterPrefix.indexOf('/')
+        const prefix = slashIndex === -1 ? pathAfterPrefix : pathAfterPrefix.slice(0, slashIndex)
+        const restPath = slashIndex === -1 ? '/' : pathAfterPrefix.slice(slashIndex)
+
+        const handler = routeHandlers.get(prefix)
+        if (!handler) {
+          sendJson(res, 404, { error: `No handler registered for prefix: ${prefix}` })
+          return
+        }
+
+        try {
+          let body = {}
+          if (req.method === 'POST' || req.method === 'PUT' || req.method === 'PATCH') {
+            body = await parseJsonBody(req)
+          }
+          await handler(req, res, { body, path: restPath, method: req.method })
+        } catch (err) {
+          console.error(`[storyboard-server] Error in ${prefix}:`, err)
+          sendJson(res, 500, { error: err.message || 'Internal server error' })
+        }
+      })
+    },
+
+    transformIndexHtml() {
+      if (clientScripts.length === 0) return []
+
+      return clientScripts.map((src) => ({
+        tag: 'script',
+        attrs: { type: 'module', src: base + src.replace(/^\//, '') },
+        injectTo: 'body',
+      }))
+    },
+  }
+}
+
+export { sendJson }

package/src/workshop/features/createPage/client.js

@@ -0,0 +1,73 @@
+/**
+ * Create Page form — Alpine.js component for the Workshop Dev Panel.
+ * Handles page name input, validation preview, and API submission.
+ */
+
+/**
+ * Register the createPageForm Alpine.js data component.
+ */
+export function registerCreatePageForm(Alpine) {
+  Alpine.data('createPageForm', () => ({
+    name: '',
+    createScene: true,
+    template: 'blank',
+    submitting: false,
+    error: null,
+    success: null,
+
+    get pascalName() {
+      return this.name
+        .replace(/[^a-zA-Z0-9\s_-]/g, '')
+        .split(/[\s_-]+/)
+        .filter(Boolean)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join('')
+    },
+
+    get routePreview() {
+      return this.pascalName ? `/${this.pascalName}` : ''
+    },
+
+    async submit() {
+      if (!this.pascalName || this.submitting) return
+      this.submitting = true
+      this.error = null
+      this.success = null
+
+      try {
+        // Build API URL with the app's base path
+        const basePath = document.querySelector('base')?.getAttribute('href') || '/'
+        const apiUrl = basePath.replace(/\/$/, '') + '/_storyboard/workshop/pages'
+
+        const res = await fetch(apiUrl, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            name: this.name,
+            template: this.template,
+            createScene: this.createScene,
+          }),
+        })
+        const data = await res.json()
+
+        if (!res.ok) {
+          this.error = data.error || 'Failed to create page'
+          return
+        }
+
+        this.success = `Created ${data.path}`
+        this.name = ''
+
+        // Navigate after HMR picks up the new file
+        setTimeout(() => {
+          const base = document.querySelector('base')?.href || '/'
+          window.location.href = base + data.route.slice(1)
+        }, 1500)
+      } catch (err) {
+        this.error = err.message || 'Network error'
+      } finally {
+        this.submitting = false
+      }
+    },
+  }))
+}

package/src/workshop/features/createPage/index.js

@@ -0,0 +1,59 @@
+/**
+ * Pages feature — create new pages from the Workshop Dev Panel.
+ *
+ * Each workshop feature exports a standard interface:
+ *   - name:          Feature identifier (matches config key in workshop.features)
+ *   - label:         Display name for the menu item
+ *   - icon:          Emoji or HTML for the menu icon
+ *   - overlayId:     Unique ID for the overlay (used by x-if in mount.js)
+ *   - serverSetup:   Called by the server plugin to register API routes
+ *   - clientSetup:   Called by mount.js to register Alpine components
+ *   - overlayHtml:   Returns the overlay HTML string for the create form
+ */
+
+export { createPagesHandler as serverSetup } from './server.js'
+export { registerCreatePageForm as clientSetup } from './client.js'
+
+export const name = 'createPage'
+export const label = 'Create page'
+export const icon = '📄'
+export const overlayId = 'createPage'
+
+export function overlayHtml() {
+  return `
+    <div class="sb-workshop-modal sb-bg ba sb-b-default br3 sb-shadow" x-data="createPageForm">
+      <div class="flex items-center justify-between ph4 pv3 bb sb-b-muted">
+        <h2 class="ma0 f5 fw6 sb-fg">Create page</h2>
+        <button class="sb-workshop-close-btn bg-transparent bn br2 sb-fg-muted pointer" @click="$dispatch('close-overlay')" aria-label="Close">&times;</button>
+      </div>
+      <div class="pa4" @close-overlay.window="closeOverlay()">
+        <label class="db mb1 fw5 sb-fg f6" for="sb-workshop-page-name">Page name</label>
+        <input class="sb-input w-100 ph3 pv2 br2 f6 db mb2" id="sb-workshop-page-name" type="text"
+               placeholder="e.g. Dashboard, User Settings" autocomplete="off" spellcheck="false"
+               x-model="name" @keydown.enter="submit()" />
+
+        <div class="mb3 f7 sb-fg-muted lh-copy" x-show="routePreview">
+          Route: <code class="dib ph1 sb-bg-muted br1 code sb-fg" x-text="routePreview"></code>
+        </div>
+
+        <label class="flex items-center mb3 pointer sb-fg f6">
+          <input type="checkbox" class="mr2" x-model="createScene" />
+          Create scene file
+        </label>
+
+        <template x-if="error">
+          <div class="mb3 ph3 pv2 br2 sb-fg-danger f7 sb-error-bg" x-text="error"></div>
+        </template>
+        <template x-if="success">
+          <div class="mb3 ph3 pv2 br2 sb-fg-success f7" x-text="success"></div>
+        </template>
+
+        <div class="flex justify-end">
+          <button class="sb-workshop-btn sb-workshop-btn-secondary mr2" @click="$dispatch('close-overlay')">Cancel</button>
+          <button class="sb-workshop-btn sb-workshop-btn-primary" @click="submit()" :disabled="!pascalName || submitting"
+                  x-text="submitting ? 'Creating…' : 'Create'"></button>
+        </div>
+      </div>
+    </div>
+  `
+}

package/src/workshop/features/createPage/server.js

@@ -0,0 +1,148 @@
+/**
+ * Workshop API — page creation and listing.
+ *
+ * Routes (mounted at /_storyboard/workshop/):
+ *   GET  /pages  — list existing pages
+ *   POST /pages  — create a new page (+ optional scene)
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+const SCENE_SKELETON = JSON.stringify({ $global: [] }, null, 2) + '\n'
+
+/**
+ * Convert a raw name to PascalCase for use as component name + filename.
+ * "my cool page" → "MyCoolPage"
+ */
+function toPascalCase(str) {
+  return str
+    .replace(/[^a-zA-Z0-9\s_-]/g, '')
+    .split(/[\s_-]+/)
+    .filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join('')
+}
+
+/**
+ * Validate a page name.
+ */
+function validatePageName(name) {
+  if (!name || typeof name !== 'string') {
+    return { valid: false, error: 'Page name is required' }
+  }
+
+  const pascalName = toPascalCase(name.trim())
+
+  if (!pascalName) {
+    return { valid: false, error: 'Page name must contain at least one alphanumeric character' }
+  }
+
+  if (/^[0-9]/.test(pascalName)) {
+    return { valid: false, error: 'Page name cannot start with a number' }
+  }
+
+  const reserved = ['_app', 'index', 'App', 'Index']
+  if (reserved.includes(pascalName)) {
+    return { valid: false, error: `"${pascalName}" is a reserved page name` }
+  }
+
+  return { valid: true, pascalName }
+}
+
+/**
+ * Read a template file and replace {{PageName}} placeholders.
+ */
+function renderTemplate(templatesDir, templateName, pageName) {
+  const tplPath = path.join(templatesDir, `${templateName}.html`)
+  if (!fs.existsSync(tplPath)) {
+    throw new Error(`Template not found: ${templateName}`)
+  }
+  const tpl = fs.readFileSync(tplPath, 'utf-8')
+  return tpl.replaceAll('{{PageName}}', pageName)
+}
+
+/**
+ * List all existing page files in src/pages/.
+ */
+function listPages(root) {
+  const pagesDir = path.join(root, 'src', 'pages')
+  if (!fs.existsSync(pagesDir)) return []
+
+  return fs.readdirSync(pagesDir)
+    .filter((f) => f.endsWith('.jsx') && !f.startsWith('_'))
+    .map((f) => {
+      const name = f.replace('.jsx', '')
+      const route = name === 'index' ? '/' : `/${name}`
+      return { name, file: f, route }
+    })
+}
+
+/**
+ * Create the pages API route handler.
+ * @param {object} ctx - Server context ({ root, sendJson })
+ * @param {string} templatesDir - Absolute path to templates directory
+ */
+export function createPagesHandler(ctx, templatesDir) {
+  const { root, sendJson } = ctx
+
+  return async (req, res, { body, path: routePath, method }) => {
+    if (routePath === '/pages' && method === 'GET') {
+      const pages = listPages(root)
+      sendJson(res, 200, { pages })
+      return
+    }
+
+    if (routePath === '/pages' && method === 'POST') {
+      const { name, template = 'blank', createScene = true } = body
+
+      const validation = validatePageName(name)
+      if (!validation.valid) {
+        sendJson(res, 400, { error: validation.error })
+        return
+      }
+
+      const { pascalName } = validation
+      const pagesDir = path.join(root, 'src', 'pages')
+      const pagePath = path.join(pagesDir, `${pascalName}.jsx`)
+
+      if (fs.existsSync(pagePath)) {
+        sendJson(res, 409, { error: `Page "${pascalName}" already exists` })
+        return
+      }
+
+      let content
+      try {
+        content = renderTemplate(templatesDir, template, pascalName)
+      } catch (err) {
+        sendJson(res, 400, { error: err.message })
+        return
+      }
+
+      fs.mkdirSync(pagesDir, { recursive: true })
+      fs.writeFileSync(pagePath, content, 'utf-8')
+
+      const result = {
+        success: true,
+        path: `src/pages/${pascalName}.jsx`,
+        route: `/${pascalName}`,
+      }
+
+      if (createScene) {
+        const dataDir = path.join(root, 'src', 'data')
+        const scenePath = path.join(dataDir, `${pascalName}.scene.json`)
+
+        if (!fs.existsSync(scenePath)) {
+          fs.mkdirSync(dataDir, { recursive: true })
+          fs.writeFileSync(scenePath, SCENE_SKELETON, 'utf-8')
+          result.scenePath = `src/data/${pascalName}.scene.json`
+        }
+      }
+
+      sendJson(res, 201, result)
+      return
+    }
+
+    sendJson(res, 404, { error: `Unknown route: ${method} ${routePath}` })
+  }
+}

package/src/workshop/features/createPage/templates/blank.html

@@ -0,0 +1,9 @@
+import { useSceneData } from '@dfosco/storyboard-react'
+
+export default function {{PageName}}() {
+  return (
+    <main className="pa4">
+      <h1>{{PageName}}</h1>
+    </main>
+  )
+}

package/src/workshop/features/registry.js

@@ -0,0 +1,20 @@
+/**
+ * Workshop feature registry.
+ *
+ * Maps feature names (matching keys in storyboard.config.json → workshop.features)
+ * to their module paths. The server plugin and client mount use this registry
+ * to dynamically load only the enabled features.
+ *
+ * To add a new feature:
+ * 1. Create a directory under features/ with index.js exporting the standard interface
+ * 2. Add its import here
+ */
+
+import * as createPage from './createPage/index.js'
+
+/**
+ * All available workshop features, keyed by config name.
+ */
+export const features = {
+  createPage,
+}

package/src/workshop/ui/mount.js

@@ -0,0 +1,111 @@
+/**
+ * Workshop Dev Panel — floating button + menu + overlays.
+ *
+ * Uses Alpine.js for reactivity and Tachyons + sb-* tokens for styling.
+ * Injected into the page by the storyboard server plugin via transformIndexHtml.
+ *
+ * Features are loaded from the registry and rendered dynamically based on
+ * which features are enabled in storyboard.config.json → workshop.features.
+ */
+
+import Alpine from 'alpinejs'
+import './workshop.css'
+import { features as allFeatures } from '../features/registry.js'
+
+const WRENCH_ICON = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16"><path fill="currentColor" d="M5.433 2.304A4.494 4.494 0 0 0 3.5 6c0 1.598.832 3.002 2.09 3.802.518.328.929.923.902 1.64v.008l-.164 3.337a.75.75 0 1 1-1.498-.073l.163-3.34c.007-.14-.1-.313-.36-.465A5.986 5.986 0 0 1 2 6a5.994 5.994 0 0 1 2.567-4.92 1.482 1.482 0 0 1 1.673-.04c.462.296.76.827.76 1.423v2.076c0 .332.214.572.491.572.268 0 .492-.24.492-.572V2.463c0-.596.298-1.127.76-1.423a1.482 1.482 0 0 1 1.673.04A5.994 5.994 0 0 1 13 6a5.986 5.986 0 0 1-2.633 4.909c-.26.152-.367.325-.36.465l.164 3.34a.75.75 0 1 1-1.498.073l-.164-3.337v-.008c-.027-.717.384-1.312.902-1.64A4.494 4.494 0 0 0 11.5 6a4.494 4.494 0 0 0-1.933-3.696c-.024.017-.067.067-.067.159v2.076c0 1.074-.84 2.072-1.991 2.072-1.161 0-2.009-.998-2.009-2.072V2.463c0-.092-.043-.142-.067-.16Z"></path></svg>`
+
+let _mounted = false
+
+/**
+ * Resolve which features are enabled from a data attribute on the script tag,
+ * injected by the server plugin. Falls back to all features enabled.
+ */
+function getEnabledFeatures() {
+  const script = document.querySelector('script[data-workshop-features]')
+  if (script) {
+    try { return JSON.parse(script.dataset.workshopFeatures) } catch { /* ignore */ }
+  }
+  // Fallback: enable all registered features
+  return Object.fromEntries(Object.keys(allFeatures).map((k) => [k, true]))
+}
+
+export function mountWorkshop() {
+  if (_mounted) return
+  _mounted = true
+
+  const enabledConfig = getEnabledFeatures()
+  const enabledFeatures = Object.entries(allFeatures)
+    .filter(([name]) => enabledConfig[name] !== false)
+
+  // Register Alpine panel component
+  Alpine.data('workshopPanel', () => ({
+    open: false,
+    overlay: null,
+    toggle() { this.open = !this.open },
+    close() { this.open = false },
+    showOverlay(name) {
+      this.overlay = name
+      this.open = false
+    },
+    closeOverlay() { this.overlay = null },
+  }))
+
+  // Let each enabled feature register its Alpine components
+  for (const [, feature] of enabledFeatures) {
+    if (feature.clientSetup) feature.clientSetup(Alpine)
+  }
+
+  // Build menu items from enabled features
+  const menuItems = enabledFeatures
+    .filter(([, f]) => f.label && f.overlayId)
+    .map(([, f]) => `
+      <button class="sb-workshop-menu-item" @click="showOverlay('${f.overlayId}')">
+        <span class="sb-workshop-menu-icon">${f.icon || ''}</span> ${f.label}
+      </button>
+    `).join('')
+
+  // Build overlay templates from enabled features
+  const overlays = enabledFeatures
+    .filter(([, f]) => f.overlayId && f.overlayHtml)
+    .map(([, f]) => `
+      <template x-if="overlay === '${f.overlayId}'">
+        <div class="sb-workshop-backdrop" @click.self="closeOverlay()">
+          ${f.overlayHtml()}
+        </div>
+      </template>
+    `).join('')
+
+  const container = document.createElement('div')
+  container.id = 'sb-workshop'
+  container.innerHTML = `
+    <div class="sb-workshop-wrapper" x-data="workshopPanel">
+      <button class="sb-workshop-trigger" @click="toggle()" aria-label="Workshop" title="Workshop">
+        ${WRENCH_ICON}
+      </button>
+
+      <div class="sb-workshop-menu" x-show="open" x-transition @click.outside="close()">
+        <div class="sb-workshop-menu-header">Workshop</div>
+        ${menuItems}
+        <div class="sb-workshop-hint">Dev-only tools</div>
+      </div>
+
+      ${overlays}
+    </div>
+  `
+
+  document.body.appendChild(container)
+  Alpine.initTree(container)
+
+  // Cmd+. / Ctrl+. toggles workshop visibility (matches devtools shortcut)
+  const wrapper = container.querySelector('.sb-workshop-wrapper')
+  let visible = true
+  window.addEventListener('keydown', (e) => {
+    if (e.key === '.' && (e.metaKey || e.ctrlKey)) {
+      visible = !visible
+      wrapper.style.display = visible ? '' : 'none'
+    }
+  })
+}
+
+// Auto-mount
+mountWorkshop()

package/src/workshop/ui/workshop.css

@@ -0,0 +1,160 @@
+/*
+  Workshop Dev Panel styles.
+  Uses Tachyons utilities + sb-* custom properties from the storyboard theme system.
+*/
+
+/* --- Wrapper & trigger --- */
+.sb-workshop-wrapper {
+  position: fixed;
+  bottom: 24px;
+  right: 76px; /* offset to sit left of the DevTools beaker (24 + 48 + 4) */
+  z-index: 9999;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
+}
+
+.sb-workshop-trigger {
+  display: flex;
+  align-items: center;
+  padding: 12px;
+  background-color: var(--sb-bg, #161b22);
+  color: var(--sb-fg-muted, #8b949e);
+  border: 1px solid var(--sb-border, #30363d);
+  border-radius: 50%;
+  cursor: pointer;
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.4);
+  transition: opacity 150ms ease, transform 150ms ease;
+  user-select: none;
+}
+.sb-workshop-trigger:hover { transform: scale(1.05); }
+.sb-workshop-trigger:active { transform: scale(0.97); }
+.sb-workshop-trigger svg { width: 16px; height: 16px; fill: currentColor; }
+
+/* --- Menu --- */
+.sb-workshop-menu {
+  position: absolute;
+  bottom: 56px;
+  right: 0;
+  min-width: 200px;
+  background-color: var(--sb-bg, #161b22);
+  border: 1px solid var(--sb-border, #30363d);
+  border-radius: 12px;
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.4);
+  overflow: hidden;
+}
+
+.sb-workshop-menu-header {
+  padding: 10px 16px 6px;
+  font-size: 11px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--sb-fg-muted, #8b949e);
+}
+
+.sb-workshop-menu-item {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  width: 100%;
+  padding: 10px 16px;
+  font-size: 13px;
+  color: var(--sb-fg, #e6edf3);
+  background: none;
+  border: none;
+  cursor: pointer;
+  text-align: left;
+}
+.sb-workshop-menu-item:hover {
+  background-color: var(--sb-bg-muted, #21262d);
+}
+
+.sb-workshop-menu-icon {
+  width: 16px;
+  height: 16px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 14px;
+}
+
+.sb-workshop-hint {
+  padding: 8px 16px;
+  font-size: 11px;
+  color: var(--sb-fg-muted, #8b949e);
+  border-top: 1px solid var(--sb-border-muted, #21262d);
+}
+
+/* --- Modal backdrop & panel --- */
+.sb-workshop-backdrop {
+  position: fixed;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  left: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background-color: rgba(0, 0, 0, 0.5);
+  z-index: 10000;
+}
+
+.sb-workshop-modal {
+  width: 100%;
+  max-width: 480px;
+  background-color: var(--sb-bg, #161b22);
+  color: var(--sb-fg, #e6edf3);
+  overflow: hidden;
+}
+
+.sb-workshop-close-btn {
+  font-size: 20px;
+  line-height: 1;
+  width: 32px;
+  height: 32px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+.sb-workshop-close-btn:hover {
+  background-color: var(--sb-bg-muted, #21262d);
+}
+
+/* --- Buttons --- */
+.sb-workshop-btn {
+  display: inline-flex;
+  align-items: center;
+  padding: 6px 16px;
+  font-size: 13px;
+  font-weight: 500;
+  border-radius: 6px;
+  border: 1px solid transparent;
+  cursor: pointer;
+  transition: background-color 100ms ease;
+}
+.sb-workshop-btn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.sb-workshop-btn-primary {
+  background-color: var(--sb-btn-success, #238636);
+  color: #ffffff;
+  border-color: rgba(240, 246, 252, 0.1);
+}
+.sb-workshop-btn-primary:hover:not(:disabled) {
+  background-color: #2ea043;
+}
+
+.sb-workshop-btn-secondary {
+  background-color: var(--sb-bg-muted, #21262d);
+  color: var(--sb-fg, #e6edf3);
+  border-color: var(--sb-border, #30363d);
+}
+.sb-workshop-btn-secondary:hover:not(:disabled) {
+  background-color: var(--sb-border-muted, #30363d);
+}
+
+/* --- Error state --- */
+.sb-error-bg {
+  background-color: rgba(209, 36, 47, 0.1);
+}