📦 @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:

🏛️ 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

🛠️ 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

The same values are edited on the Live Canvas Preview page under Plugins. The page shows one description line under the title and the settings form below it. Save writes each field through the plugin settings service. While that service is loading, the form shows a loading state. When the service is not available, the form shows an unavailable state instead of an error page. The settings namespace is dsh-live-canvas; the package name is not a valid settings identifier.

⚙️ 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

⌨️ Interactive Controls & Shortcuts

🔒 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