feat: idb infrastructure. (#63)

Author: knightedcodemonkey

.github/workflows/ci.yml

@@ -7,6 +7,7 @@ on:
   pull_request:
     branches:
       - main
+      - next
 
 jobs:
   ci:

.github/workflows/playwright.yml

@@ -4,6 +4,7 @@ on:
   pull_request:
     branches:
       - main
+      - next
     types:
       - opened
       - synchronize

docs/build-and-deploy.md

@@ -114,6 +114,7 @@ This command forces `KNIGHTED_PRIMARY_CDN=esm` and runs `npm run build` first, t
 Related docs:
 
 - `docs/code-mirror.md` for CodeMirror CDN integration rules, fallback behavior, and validation checklist.
+- `docs/dual-build-gh-pages-strategy.md` for the clean two-URL stable and next deployment model during UI migration.
 
 - `src/modules/cdn.js` is the source of truth for CDN-managed runtime libraries (including fallback candidates). Add/update CDN specs there instead of hardcoding module URLs inside feature modules.
 

docs/dual-build-gh-pages-strategy.md

@@ -0,0 +1,93 @@
+# Dual Build GitHub Pages Strategy
+
+## Purpose
+
+Document a clean migration strategy for delivering both stable and overhaul UI versions from one repository without adding runtime feature flags to application code.
+
+## Core Idea
+
+Build two versions of the site during deployment and publish both under one GitHub Pages branch.
+
+- Stable site at root path: /index.html
+- Overhaul site at next path: /next/index.html
+
+The URL path acts as the switch.
+
+- Stable: /develop/
+- Overhaul: /develop/next/
+
+## Why This Approach
+
+1. Keeps runtime code clean.
+2. Avoids pervasive if version checks in app modules.
+3. Allows side-by-side validation of stable and next UX.
+4. Reduces long-term cleanup work versus in-app toggles.
+
+## Deployment Layout
+
+Publish a combined artifact to the GitHub Pages branch with this shape:
+
+- /index.html and root assets from stable branch build
+- /next/index.html and next assets from overhaul branch build
+
+## CI Workflow Design
+
+A deployment workflow builds both branches in one run and publishes one artifact.
+
+1. Checkout stable branch into an isolated worktree directory.
+2. Install dependencies and build stable output.
+3. Copy stable output into publish root.
+4. Checkout overhaul branch into a second isolated worktree directory.
+5. Install dependencies and build overhaul output.
+6. Copy overhaul output into publish root under /next.
+7. Deploy combined publish folder to GitHub Pages.
+
+## Operational Guidance
+
+1. Run both builds in isolated directories to prevent cross-branch contamination.
+2. Keep Node and npm versions pinned consistently in CI.
+3. Use workflow concurrency to cancel outdated deploy jobs.
+4. Use relative asset URLs so content works under both root and /next paths.
+5. Fail the deploy if either build fails.
+
+## Source Control Model
+
+- main branch represents stable production UX.
+- overhaul branch represents next-generation UX.
+- Deploy workflow may trigger on pushes to either branch, but each run should still build both branches for a consistent dual-output artifact.
+
+## Relationship To App Architecture Work
+
+This strategy complements the multi-tab and local workspace migration by separating rollout concerns from runtime logic.
+
+- Runtime implementation remains modular and focused on architecture.
+- Deployment controls the exposure of stable versus next.
+
+## Tradeoffs
+
+Pros:
+
+1. Cleaner codebase during migration.
+2. Lower risk of runtime toggle regressions.
+3. Clear QA and stakeholder review URLs.
+
+Cons:
+
+1. Longer deploy times due to dual builds.
+2. More CI configuration complexity.
+3. Temporary branch coordination requirements.
+
+## Exit Plan
+
+After next UI is production-ready:
+
+1. Promote next code into main.
+2. Remove dual-build deployment logic.
+3. Publish only root output again.
+4. Remove migration-only docs and branch conventions.
+
+## Suggested Follow-up
+
+1. Add a deploy workflow implementation doc with exact GitHub Actions YAML and permissions.
+2. Add a release checklist for validating both URLs before each deploy.
+3. Add ownership notes for stable and next branch review responsibilities.

src/bootstrap.js

@@ -13,6 +13,7 @@ const preloadImportKeys = [
   'jsxReact',
   'react',
   'reactDomClient',
+  'idb',
 ]
 
 const isImportMapPrimary =

src/modules/cdn.js

@@ -74,6 +74,12 @@ export const cdnImportSpecs = {
     esm: 'react-dom@19.2.4/client',
     jspmGa: 'npm:react-dom@19.2.4/client.js',
   },
+  idb: {
+    importMap: 'idb',
+    esm: 'idb@8.0.3',
+    unpkg: 'idb@8.0.3/build/index.js?module',
+    jspmGa: 'npm:idb@8.0.3/build/index.js',
+  },
   sass: {
     importMap: 'sass',
     esm: [

src/modules/preview-entry-resolver.js

@@ -0,0 +1,36 @@
+const previewEntryNamePattern = /(?:^|\/)(?:app|main)\.[jt]sx?$/i
+
+const normalizeTabIdentity = tab => {
+  if (!tab || typeof tab !== 'object') {
+    return ''
+  }
+
+  if (typeof tab.path === 'string' && tab.path.trim().length > 0) {
+    return tab.path.trim()
+  }
+
+  if (typeof tab.name === 'string' && tab.name.trim().length > 0) {
+    return tab.name.trim()
+  }
+
+  return ''
+}
+
+export const isPreviewEntryTab = tab =>
+  previewEntryNamePattern.test(normalizeTabIdentity(tab))
+
+export const resolvePreviewEntryTab = tabs => {
+  if (!Array.isArray(tabs) || tabs.length === 0) {
+    return null
+  }
+
+  return tabs.find(isPreviewEntryTab) ?? null
+}
+
+export const canRenderPreview = ({ tabs, fallbackSource = '' } = {}) => {
+  if (Array.isArray(tabs) && tabs.length > 0) {
+    return Boolean(resolvePreviewEntryTab(tabs))
+  }
+
+  return typeof fallbackSource === 'string' && fallbackSource.trim().length > 0
+}

src/modules/preview-workspace-graph.js

@@ -0,0 +1,90 @@
+const normalizeImportSpecifier = value =>
+  typeof value === 'string' && value.trim().length > 0 ? value.trim() : null
+
+const normalizeGraphEntry = entry => {
+  if (!entry || typeof entry !== 'object') {
+    return null
+  }
+
+  if (typeof entry.tabId !== 'string' || entry.tabId.length === 0) {
+    return null
+  }
+
+  const imports = Array.isArray(entry.imports)
+    ? entry.imports.map(normalizeImportSpecifier).filter(Boolean)
+    : []
+
+  return {
+    tabId: entry.tabId,
+    contentHash: typeof entry.contentHash === 'string' ? entry.contentHash : '',
+    imports,
+    lastUpdated:
+      typeof entry.lastUpdated === 'number' && Number.isFinite(entry.lastUpdated)
+        ? entry.lastUpdated
+        : Date.now(),
+  }
+}
+
+export const createPreviewWorkspaceGraphCache = () => {
+  const byTabId = new Map()
+
+  const upsert = entry => {
+    const normalized = normalizeGraphEntry(entry)
+
+    if (!normalized) {
+      throw new TypeError('Graph entry is invalid.')
+    }
+
+    byTabId.set(normalized.tabId, normalized)
+    return normalized
+  }
+
+  const get = tabId => {
+    if (typeof tabId !== 'string' || tabId.length === 0) {
+      return null
+    }
+
+    return byTabId.get(tabId) ?? null
+  }
+
+  const getDependents = targetImportSpecifier => {
+    const normalizedSpecifier = normalizeImportSpecifier(targetImportSpecifier)
+
+    if (!normalizedSpecifier) {
+      return []
+    }
+
+    const dependents = []
+
+    for (const entry of byTabId.values()) {
+      if (entry.imports.includes(normalizedSpecifier)) {
+        dependents.push(entry)
+      }
+    }
+
+    return dependents
+  }
+
+  const remove = tabId => {
+    if (typeof tabId !== 'string' || tabId.length === 0) {
+      return false
+    }
+
+    return byTabId.delete(tabId)
+  }
+
+  const clear = () => {
+    byTabId.clear()
+  }
+
+  const list = () => [...byTabId.values()]
+
+  return {
+    upsert,
+    get,
+    getDependents,
+    remove,
+    clear,
+    list,
+  }
+}

src/modules/render-runtime.js

@@ -3,6 +3,7 @@ import {
   getFunctionLikeDeclarationNames,
   hasFunctionLikeDeclarationNamed,
 } from './jsx-top-level-declarations.js'
+import { canRenderPreview } from './preview-entry-resolver.js'
 import { ensureJsxTransformSource } from './jsx-transform-runtime.js'
 
 export const createRenderRuntimeController = ({
@@ -14,6 +15,7 @@ export const createRenderRuntimeController = ({
   isAutoRenderEnabled = () => false,
   getCssSource,
   getJsxSource,
+  getWorkspaceTabs,
   getPreviewHost,
   setPreviewHost,
   applyPreviewBackgroundColor,
@@ -866,7 +868,14 @@ export const createRenderRuntimeController = ({
     }
   }
 
-  const hasComponentSource = () => getJsxSource().trim().length > 0
+  const hasComponentSource = () => {
+    const tabs = typeof getWorkspaceTabs === 'function' ? getWorkspaceTabs() : undefined
+
+    return canRenderPreview({
+      tabs,
+      fallbackSource: getJsxSource(),
+    })
+  }
 
   const clearPreview = () => {
     const target = getRenderTarget()