dsh-live-canvas

📦 @goodandready/dsh-live-canvas

---

⚡ Overview & The Problem

When coding assistants work in standard terminal or chat windows, they typically produce static code snippets or markdown blocks. This creates critical friction:

1. No Live Feedback: Developers cannot see or test interactivity, form validations, animations, or responsive breakpoints without manually copying code into a local build toolchain.
2. Context Fragmentation: Reviewing UI changes requires switching back and forth between IDE, terminal, browser, and design tools.
3. Verbose Text Overload: Explaining architecture, roadmaps, and wireframes in raw text produces walls of markdown that are difficult to scan.

The Solution: dsh-live-canvas

Inspired by Thariq Shihipar's The Unreasonable Effectiveness of HTML, Plannotator, and modern visual studios (Figma, Retool, V0), @goodandready/dsh-live-canvas transforms DeepSeek Harness into a complete, standalone frontend development suite. It provides in-memory ESM bundling, real-time SSE hot-reloading, in-chat interactive preview cards, a split-view code editor, time-travel history debugging, 1-click cloud deployment, and 30 dedicated Agent Tools.

---

🧭 Sidebar Layouts & Surface Compatibility

@goodandready/dsh-live-canvas supports all DSH navigation layouts with zero external dependencies:

Environment	Supported Surface	Capabilities
DSH 0.1.5-alpha.1+ (Native)	Native Right Sidebar (sidebarRightTabs, sidebar.right.pane.tab)	Full Live Canvas workspace tab + native file viewer for dsh-resource://file (.html, .jsx, .tsx, .svg, .mermaid, .md).
Legacy DSH Profiles	dsh-better-sidebar integration	Dedicated tab (live-canvas) and registered file viewer (live-canvas-viewer).
Dual Profiles (Both enabled)	Coexists seamlessly	Distinct, deterministic IDs (@goodandready/dsh-live-canvas vs live-canvas), no duplicate mounting, independent cleanup disposers.
Minimal / Standalone Profiles	Standalone Drawer & Modals	Self-contained slide-over drawer with hotkeys (Alt+C), zero reliance on external sidebar plugins.

🏛️ System Architecture

graph TD
    classDef agent fill:#1e1b4b,stroke:#6366f1,stroke-width:2px,color:#fff;
    classDef core fill:#064e3b,stroke:#10b981,stroke-width:2px,color:#fff;
    classDef ui fill:#451a03,stroke:#f59e0b,stroke-width:2px,color:#fff;
    classDef sandbox fill:#18181b,stroke:#71717a,stroke-width:2px,color:#fff;

    Agent[🤖 DeepSeek Harness Agent / 30 Tools]:::agent
    Store[💾 PreviewStore LRU Cache & History Snapshots]:::core
    Watcher[📁 WorkspaceWatcher File Change Detection]:::core
    Bundler[⚡ Smart Recursive ESM Bundler & Transpiler]:::core
    Deployer[🌍 Multi-Platform Deploy Engine]:::core
    FigmaBridge[🎨 Figma Vector Bridge]:::core
    SoundEngine[🔊 Web Audio FX Synthesis]:::core
    Themes[🎨 AI Theme Tokens Engine]:::core

    WebUI[💻 DSH WebUI BetterSidebar Tab]:::ui
    ChatCards[💬 In-Chat Live Preview Tool Cards]:::ui
    EditorDrawer[📝 Split-View Code Editor Drawer]:::ui
    TimeTravelUI[⏳ Time-Travel History Scrubber]:::ui
    DeployModal[🌍 Instant Deploy Dialog]:::ui

    SandboxFrame[🛡️ Sandboxed Iframe Preview Runtime]:::sandbox
    WYSIWYG[✏️ Double-Click Inline WYSIWYG Editor]:::sandbox
    DnD[↕️ Drag & Drop Section Reordering]:::sandbox
    Blueprint[📐 Blueprint Grayscale Filter Mode]:::sandbox

    Agent -->|live_canvas_* tools| Store
    Watcher -->|Auto file sync| Store
    Store --> Bundler
    Deployer --> Store
    FigmaBridge --> Store
    Themes --> SandboxFrame
    Bundler --> SandboxFrame
    SoundEngine --> SandboxFrame

    WebUI --> EditorDrawer
    WebUI --> TimeTravelUI
    WebUI --> DeployModal
    WebUI --> SandboxFrame
    ChatCards -->|1-Click Activate Tab| WebUI

    SandboxFrame --> WYSIWYG
    SandboxFrame --> DnD
    SandboxFrame --> Blueprint
    WYSIWYG -->|POST /api/save-content| Watcher
    DnD -->|POST /api/save-reorder| Watcher

---

✨ Exhaustive Feature Breakdown

• 🏠 Projects Hub & Recent Sessions (v0.2.14): Dedicated dashboard displaying all active preview sessions and workspace components (React, HTML, Vue, SVG, Markdown) sorted by activity, featuring instant search and 1-click loading.
• ↕️ Interactive Chat Card Resizing: Smooth vertical height resizing (160px to 800px) via drag handle, quick preset dimensions (S 200px, M 320px, L 480px), and Wide View mode (⤢).
• 🔄 Dedicated In-Canvas Refresh: Frame reload button in toolbar and support for F5 / Ctrl+R shortcuts inside the canvas frame without reloading the DSH host application.
• 🛡️ Defensive Tool Output Schemas: AI agent tools return structured refusal metadata (code, allowedRoots, reason) on path policy violations, enabling autonomous model error recovery.

1. 🗄️ Retool-Style CRUD Admin Dashboard Studio (lib/crud.js / Tool 26)

• Instant Data Grids: Generates full-featured data management micro-apps with live search, column sorting, and status filter pills (Active, Pending, Suspended).
• Interactive Modals: Form validation for creating and editing records on the fly.
• Persistent Database: Automatically syncs record changes to localStorage so data survives page reloads.
• CSV Data Export: 1-click export of table data directly to downloadable .csv files.

2. ⏳ Time-Travel Debugger & History Timeline Scrubber (lib/timetravel.js / Tool 27)

• Visual Revision Slider: Interactive scrubber bar allowing developers and agents to slide through historical session snapshots.
• Instant Rollback: 1-click restore of any previous snapshot directly back into the live canvas without touching Git.
• Timestamped Revisions: Compares intermediate iterations generated across conversation turns.

3. 🌍 1-Click Multi-Platform Web Deployment (lib/deploy.js / Tool 28)

• Vercel: Prepares static distribution with vercel.json routing rules.
• Cloudflare Pages: Generates _routes.json and security headers (_headers).
• Netlify: Packages static dist with SPA redirects (_redirects).
• GitHub Gist: Generates standalone single-file HTML ready for immediate public sharing via Gist preview.

4. 🎨 Figma & Penpot Vector Bridge (lib/figma.js / Tool 29)

• SVG-to-Tailwind Converter: Pasted vector SVG code from Figma or Penpot is automatically parsed into clean, responsive React JSX or HTML with Tailwind CSS classes.
• Export to Figma: Wraps canvas components into standard SVG with foreignObject for direct pasting (Ctrl+V) into Figma design files.

5. 🔊 UI Sound FX & Micro-Interactions Synthesis (lib/sound.js / Tool 30)

• Zero-Dependency Web Audio API: Pure mathematical synthesis of UI feedback sounds without external audio assets.
• Curated Sound Presets: Tactile click, switch tap, 2-tone success chime, warning error buzz, modal pop, and 3-tone levelup arpeggio.

6. 📋 Effective HTML Artifact Archetypes (lib/wireframe.js, lib/plan.js, lib/diagram.js, lib/prototype.js)

• 📐 Low-Fi Wireframes (Tool 21): Monochromatic blueprint layouts with skeleton loaders and placeholder image boxes to evaluate UX hierarchy without styling bias.
• 📋 Interactive Release Plans (Tool 22): Release readiness roadmaps with priority badges (P0, P1, P2), dynamic progress bars, milestone checkboxes, and persistent state.
• 📊 Living Architecture Diagrams (Tool 23): Zoomable node-graph diagrams with animated data flow lines and detailed service popups on click.
• 🧪 Multi-Step Prototype Flows (Tool 24): Onboarding wizards and checkout flows with step transitions and validation state machines.
• ✍️ Visual Annotation Sign-Off (Tool 25): Boxed markup with resolution statuses (open / resolved) and response threads.

7. 💬 In-Chat Live Preview Tool Cards (LiveCanvasChatCard)

• Embedded Sandbox Preview: Directly in the chat stream, tool executions render an interactive preview card.
• 1-Click Studio Activation: Clicking 🚀 Open in Live Canvas automatically opens the BetterSidebar Live Canvas tab and loads the session.

8. ⚡ Smart Multi-File ESM Bundler (lib/transpiler.js)

• Recursive Local Import Resolution: Resolves relative ./Header.jsx, ./Card.tsx, ./data.js, and ./styles.css imports in-memory.
• Babel JSX & PostCSS: Transpiles modern React 18, Vue, HTML5, SVG, and Mermaid diagrams without external build tools.
• Asset Streaming: Safely streams local workspace images via GET /dsh-live-canvas/assets/*.

9. 🎨 AI Theme Tokens Engine (lib/themes.js)

• 1-Click Design System Switcher: Linear Dark, Vercel Clean, Swiss Editorial, Glassmorphism Neon, and Cyberpunk Terminal.

10. 🔍 Visual Regression & Layout Audit (Tool 18)

• Inspects canvas DOM for text overflow clipping, missing alt attributes, low contrast, and viewport responsiveness issues.

11. 📱 QR Code Mobile Live Share (Tool 20)

• Generates instant SVG QR codes and local network URLs for testing canvas previews on real smartphones over Wi-Fi.

12. 📦 1-Click Vite Project ZIP Packager (lib/packager.js / Tool 13)

• Bundles the active canvas into a complete production-ready Vite + React or Vite + Vue project with package.json, vite.config.js, and tailwind.config.js.

---

🛠️ Complete 30 Agent Tools Reference

#	Tool Name	Description	Key Parameters	Return Values
1	live_canvas_preview	Renders or updates preview session for HTML/React/SVG/Mermaid	content, componentType, title, theme	previewUrl, canvasId, success
2	live_canvas_inspect	Retrieves user DOM clicks, CSS selectors, and element attributes	canvasId, limit	inspections: [...], count
3	live_canvas_reload	Forces instant SSE reload on open preview frames	canvasId	reloaded, timestamp
4	live_canvas_diagnose	Queries sandbox console errors and exceptions for self-healing	canvasId, level	logs: [...], hasErrors
5	live_canvas_export	Exports standalone zero-dependency HTML bundle	canvasId, saveToDisk	downloadUrl, savedPath
6	live_canvas_annotations	Queries or clears boxed visual annotations and user markup	canvasId, action	annotations: [...], count
7	live_canvas_gallery	Creates multi-variant Storybook comparison matrix	variants, title	variantsCount, previewUrl
8	live_canvas_watch	Scans and binds workspace files to live file watcher	subDir, exts	files: [...], watchedFiles
9	live_canvas_controls	Updates Storybook-style interactive props sliders	canvasId, values, schema	values: {...}, schema: {...}
10	live_canvas_diff	Visual split slider comparing two session snapshots	canvasId, fromId, toId	diffUrl, snapshotCount
11	live_canvas_matrix	Multi-device viewport matrix (Mobile, Tablet, Desktop)	canvasId	matrixUrl
12	live_canvas_mock	Configures intercepted REST API mock routes in preview frame	canvasId, endpoints	endpointsCount, mockData
13	live_canvas_pack	1-Click Vite+React or Vite+Vue project ZIP bundle packager	canvasId, framework	downloadUrl, writtenDir
14	live_canvas_refine_element	Targets AI visual/structural refinement to a DOM element	canvasId, selector, prompt	success, message
15	live_canvas_storybook	Auto-scans workspace components and creates UI Kit gallery	subDir, framework	galleryUrl, componentsCount
16	live_canvas_insert_block	Inserts curated design block (Hero, Bento, Pricing, FAQ, Footer)	blockId, canvasId	blockId, title
17	live_canvas_vision_import	Converts image mockup/screenshot into interactive canvas	imagePath, framework	previewUrl, framework
18	live_canvas_visual_audit	Inspects canvas DOM for overflow, contrast, and layout issues	canvasId	score, issuesCount, issues
19	live_canvas_generate_mock	Generates realistic mock JSON datasets and injects into sandbox	type, count, canvasId	datasetType, mockData
20	live_canvas_share	Generates mobile QR code and local network preview URL	canvasId	shareUrl, qrSvg
21	live_canvas_create_wireframe	Generates low-fidelity structural HTML wireframe artifact	title, layout, canvasId	previewUrl, layout
22	live_canvas_create_plan	Generates interactive HTML project plan & release roadmap	title, version, canvasId	previewUrl, version
23	live_canvas_create_diagram	Generates living interactive architecture diagram artifact	title, diagramType, canvasId	previewUrl, diagramType
24	live_canvas_create_prototype	Generates multi-step interactive prototype wizard flow	title, flowType, canvasId	previewUrl, flowType
25	live_canvas_resolve_annotation	Marks visual user annotation as resolved with notes	canvasId, annotationId, note	status: 'resolved'
26	live_canvas_create_crud	Generates Retool-style admin CRUD dashboard with table and modals	title, entityName, canvasId	previewUrl, entityName
27	live_canvas_timetravel	Steps through snapshot history timeline or restores revisions	canvasId, action, snapshotIndex	timetravelUrl, snapshotsCount
28	live_canvas_instant_deploy	Generates ready-to-ship bundle for Vercel, Cloudflare, Netlify, Gist	canvasId, target	downloadUrl, instructions
29	live_canvas_figma_bridge	Converts Figma SVG vector code to Tailwind or exports component SVG	svg, action, canvasId	action, componentName
30	live_canvas_sound_fx	Synthesizes and previews Web Audio UI feedback sounds	action, soundType	presetsCount, soundType
31	live_canvas_capture_snapshot	Captures visual canvas metadata, DOM tree, or HTML for agent visual feedback	canvasId, format	snapshot, format

---

🛠️ In-Canvas DevTools & Diagnostic Feedback Loop

• Mini-Console Drawer: Real-time log/warn/error interception inside the sandbox with collapsible bottom drawer, level filtering, and toolbar badge count.
• Component State Presets Switcher: Instant switching between Default, Loading, Empty, Error, and Overflow states via toolbar selector and DOM event triggers.
• Agent Vision Feedback Loop: live_canvas_capture_snapshot lets coding agents query DOM structure or extract complete rendered HTML snapshots.
• Standalone Single-File HTML Export: 1-click single-file bundle export at /dsh-live-canvas/api/standalone embedding all fonts, Tailwind, and scripts.
• W3C Design Tokens Bridge: Parses W3C / Figma design token JSON structures into live CSS custom properties.

📦 Installation

Install into your DeepSeek Harness profile with one command:

dsh plugin --profile web add @goodandready/dsh-live-canvas

---

⚙️ Configuration (settings.yaml)

plugins:
  "@goodandready/dsh-live-canvas":
    defaultViewport: "responsive" # Options: responsive, mobile, tablet, desktop, matrix
    autoOpenOnHtmlGen: true       # Automatically focus Live Canvas tab upon UI generation
    enableHotReload: true         # Enable SSE real-time hot-reloading on code updates
    maxSessionCache: 50           # Maximum active preview sessions in LRU memory cache
    enableFileWatcher: true       # Enable filesystem watcher for live project sync
    workspaceDir: ""              # Custom project root path (defaults to working directory)
    workspaceRoots: []            # Explicit allowed workspace root directories for path sandboxing

Parameter	Type	Default	Description
defaultViewport	string	"responsive"	Initial viewport dimension (responsive, mobile, tablet, desktop, matrix)
autoOpenOnHtmlGen	boolean	true	Automatically opens BetterSidebar Live Canvas tab when agent generates UI
enableHotReload	boolean	true	Real-time SSE hot-reload stream for sandbox frames
maxSessionCache	number	50	Maximum number of active preview sessions kept in memory
enableFileWatcher	boolean	true	Monitors workspace directory for file changes
workspaceDir	string	""	Base directory for scanning workspace components
workspaceRoots	string[]	[]	Explicit allowed root paths for file viewing and workspace scanning. Blocks path traversal outside allowed folders.

---

⌨️ Interactive Controls & Shortcuts

Action	Shortcut / Trigger	Result
Instant Canvas Refresh	Click 🔄 Refresh or press F5 / Ctrl+R	Reloads active preview frame without reloading DSH host
Chat Card Drag Resize	Drag bottom border handle on chat preview	Smoothly resize chat preview height from 160px to 800px
Chat Card Wide Mode	Click ⤢ in chat card header	Expands chat preview card to full message width
Projects Hub	Select 🏠 Projects Hub in toolbar dropdown	Open interactive project dashboard with recent sessions and file search
Inline WYSIWYG Text Edit	Double-click text element on canvas	Edit heading/paragraph inline and save with Enter
Split-View Code Editor	Click 💻 Code in toolbar	Collapsible side-by-side code editor with live debounce sync
Blueprint Mode	Click 📐 Wireframe in toolbar	Toggles high-contrast monochromatic structural view
Drag & Drop Reordering	Click ↕️ D&D in toolbar	Drag section and card blocks to reorder layout visually
Time-Travel Scrubber	Click ⏳ Timeline in toolbar	Slide through revision history and restore previous snapshots
1-Click Web Deploy	Click 🌍 Deploy in toolbar	Prepares Vercel, Cloudflare, Netlify, or Gist deployment package
Sound FX Toggle	Click 🔊 Sound in toolbar	Enables/disables synthesized Web Audio feedback
Inspect Element	Click 🔍 Inspect in toolbar	Click any DOM element to capture CSS selector and computed styles
Visual Annotations	Click 🖍 Annotate in toolbar	Draw bounding boxes and leave review comments for the agent

---

🔒 Security & Sandboxing Architecture

Live Canvas operates with enterprise-grade defensive sandboxing:

• Strict Path Sandboxing (resolveSafePath): All file access requests via API and agent tools (live_canvas_preview, /dsh-live-canvas/api/open-file, /dsh-live-canvas/api/workspace/files) must resolve within authorized workspace roots (workspaceRoots or the current process working directory). Attempts to traverse into sensitive parent directories (such as /etc, system binaries, or sibling folders) are rejected with ERR_PATH_OUTSIDE_ROOTS and HTTP 403 Forbidden.
• CSRF & Origin Verification (isTrustedRequest): Mutating endpoints require verified same-origin requests matching standard browser headers (Sec-Fetch-Site: same-origin, Origin, or Referer) or loopback authorization.
• Content Security Policy: Canvas previews are rendered inside sandboxed iframes with strict CSP directives (default-src 'self' 'unsafe-inline' 'unsafe-eval' data: blob: https: http:; X-Frame-Options: SAMEORIGIN; X-Content-Type-Options: nosniff).

---

🔄 Host-Side 1-Click Updater

Live Canvas includes an integrated host-side updater conforming to the DSH plugin standard:

• Automated Update Checking: Background checking queries registry.npmjs.org for new releases, taking into account semver prereleases.
• DSH Card UI Integration: Shows current vs latest version, "Check for Updates" button, and 1-click update trigger.
• Safe Host Installation: Executes profile update using the local package manager (pnpm / dsh plugin add), verifying host loopback and authorization headers (X-DSH-Update-Key).

---

📄 License

MIT © GooDAnDReaDY