@filekit-studio/sketch

Local-first, interactive whiteboard and architecture diagramming SDK for React and Next.js.

Documentation • Live Playground • Tech Stencils Catalog • FileKit Studio

Features

• Local-First Privacy: Zero server calls, zero database overhead, and zero telemetry. Diagrams run and persist entirely in the client.
• Database Schema & ER Modeling: Typed 2-column database tables (tableStyle: 'database') with PK/FK icons, automatic type coloring, dynamic row addition/deletion, auto-widening text boxes, and full keyboard navigation (Enter, Shift+Enter, Backspace row removal, arrow traversal). Press M to activate.
• Live Animated Data Flow Connectors: Real-time particle pulse and flow simulation across curved, elbow, and straight magnetic connectors with configurable speed, trigger modes, and glow colors.
• Shift-Constrained 15° Angle Snapping: Hold Shift while drawing straight lines or arrows to lock to 15° angular increments (0° horizontal, 90° vertical, 45° diagonal, 30°/60° isometric) with floating degree badges.
• Arrow Badges & Harmonized Palettes: In-place double-click label editing with multi-line wrap (\n), compact auto-sizing, and single-color tone palettes with dark/light mode optimization.
• Magnetic Connection Anchor Suggestions: Real-time 12-point perimeter anchor suggestions on diagram and database table border hover for effortless connector snapping.
• Frame Containment & Anti-Stealing Duplication: Structural frames (type: 'frame') that act as isolated slide decks or component boundaries. Duplicating or moving a frame clones and shifts all enclosed shapes atomically.
• Steganographic Lossless PNG Export: Export raster PNGs with deflated vector scene metadata embedded inside PNG tEXt chunks (embedScene: true). Re-importing into Sketch restores 100% of editable vectors.
• React 18 & 19 / Next.js Ready: Native App Router and Pages Router support with zero SSR hydration mismatches.
• 675+ Production Stencils: Official cloud logos and microservice primitives (AWS, GCP, Azure, Docker, Kubernetes, Next.js, PostgreSQL, Redis, Supabase).
• Obstacle-Avoiding Routing: Hanan Grid $A^*$ orthogonal and curved arrow routing with Minkowski Sum obstacle inflation, corner fillets, and highway lane offsets.
• Presentation Deck Mode: Convert canvas frames into presentation slide decks (Alt+P) with laser pointer and spotlight focus tools.
• Headless Exporters: Serverless and headless export to vector PDF (multi-page auto-paginated), crisp PNG, and standalone SVG.
• Embedded Viewer: Lightweight <SketchViewer /> component for rendering interactive or static diagrams in docs and blogs.
• Unified .sketch File Format: Fast, portable JSON file format protected by a prototype-pollution and XSS security purifier.

Installation

npm install @filekit-studio/sketch
# or
pnpm add @filekit-studio/sketch
# or
bun add @filekit-studio/sketch

Peer Dependencies

• react >= 18.0.0
• react-dom >= 18.0.0

Required Stylesheet Import

Import the stylesheet in your root layout (app/layout.tsx or pages/_app.tsx):

// Universal modern Tailwind CSS v4 styling (Default)
import '@filekit-studio/sketch/styles.css'

// Or pick an aesthetic variant:
// import '@filekit-studio/sketch/classic.css'     // Classic clean wireframe styling
// import '@filekit-studio/sketch/neumorphic.css'  // Soft extruded 3D neumorphic styling

Zero CSS Pollution (Strict Scope Isolation):
All styles are strictly scoped under .fk-sketch-root. Importing this stylesheet will never conflict with your app's global CSS, markdown fonts, or Tailwind config.

Quick Start

Import <SketchEditor /> inside a Client Component ('use client'):

'use client'

import React from 'react'
import { SketchEditor } from '@filekit-studio/sketch'
import '@filekit-studio/sketch/styles.css'

export default function WhiteboardPage() {
  return (
    <main className="w-screen h-screen overflow-hidden">
      <SketchEditor
        boardName="System Architecture"
        storageKey="my_app_whiteboard"
        onChange={(doc) => {
          console.log('Updated:', doc.elements.length, 'elements')
        }}
        onSave={(doc) => {
          console.log('Saved:', doc)
        }}
        showGuideButton={true}
        guideHref="/docs"
      />
    </main>
  )
}

Read-Only Diagram Viewer (<SketchViewer />)

Use <SketchViewer /> to embed diagrams in documentation, blog posts, and dashboards with zero editor chrome:

'use client'

import { SketchViewer } from '@filekit-studio/sketch'
import '@filekit-studio/sketch/styles.css'

export function ArchitectureDiagram({ document }) {
  return (
    <div className="w-full h-[420px] rounded-xl overflow-hidden border">
      <SketchViewer
        value={document}
        theme="system"
        autoFit={true}
        interactive={true}
        showCopyButton={true}
        showZoomControls={true}
      />
    </div>
  )
}

Obstacle-Avoiding Arrow Routing

Route collision-free orthogonal or curved arrows around diagram nodes programmatically:

import { computeNonCollisionRoute, generateFilletSvgPath } from '@filekit-studio/sketch'

const route = computeNonCollisionRoute(
  { x: 100, y: 150 }, // Start point
  { x: 500, y: 350 }, // End point
  'right',            // Start anchor orientation ('top' | 'right' | 'bottom' | 'left')
  'left',             // End anchor orientation
  obstacles,          // Array of { x, y, width, height }
  {
    margin: 24,       // Minkowski Sum obstacle padding
    bendPenalty: 40,  // Penalize unnecessary turns
    filletRadius: 10, // Rounded 90° arc fillets
    smoothCurves: false,
  }
)

// Generate SVG path string for rendering:
const svgPath = generateFilletSvgPath(route.waypoints, 10)

Headless Export Utilities

Export diagrams without mounting the canvas component via @filekit-studio/sketch/export:

import {
  exportToPng,
  exportToSvg,
  exportWhiteboardToPdf,
} from '@filekit-studio/sketch/export'
import { extractSceneFromPng } from '@filekit-studio/sketch'

// PNG with optional steganographic lossless scene embedding
const pngDataUrl = await exportToPng(elements, {
  scale: 2,
  backgroundColor: '#ffffff',
  embedScene: true, // Injects compressed scene into PNG tEXt chunk
})

// Extract 100% editable vector scene from a FileKit PNG
const recoveredDoc = await extractSceneFromPng(pngFileBlob)

// Vector SVG string
const svgMarkup = exportToSvg(elements, {
  includeBackground: true,
})

// Multi-page Vector PDF Blob
const pdfBlob = await exportWhiteboardToPdf(elements, {
  title: 'Architecture Specification',
  author: 'FileKit Studio',
})

Database Schema & ER Entity Tables

Render typed 2-column database tables with primary keys, datatypes, and automatic palette synchronization:

import { SketchEditor, type SketchBoardElement } from '@filekit-studio/sketch'

const usersTable: SketchBoardElement = {
  id: 'table_users',
  type: 'table',
  tableStyle: 'database', // Activates Database Entity mode
  x: 100,
  y: 100,
  width: 280,
  height: 180,
  strokeColor: '#3b82f6',
  strokeWidth: 2,
  strokeStyle: 'solid',
  fillColor: '#1e293b',
  fillStyle: 'solid',
  opacity: 1,
  zIndex: 1,
  rows: 4,
  cols: 2,
  colWidths: [150, 130],
  rowHeights: [36, 32, 32, 32],
  hasHeaderRow: true,
  cells: {
    '0,0': { text: 'users', bold: true, align: 'left' },
    '1,0': { text: 'id', align: 'left' },            // Auto-displays yellow PK key icon
    '1,1': { text: 'uuid', align: 'right' },
    '2,0': { text: 'name', align: 'left' },
    '2,1': { text: 'varchar(100)', align: 'right' },
    '3,0': { text: 'email', align: 'left' },
    '3,1': { text: 'varchar(255)', align: 'right' },
  },
}

• Keyboard Navigation in Cells:
  • Enter: Inserts a clean newline without shifting cells. Row height dynamically expands.
  • Shift + Enter or Tab: Confirms cell edit and jumps to the next row/column.
  • Backspace (when row is empty): Deletes the entire empty row and contracts table height automatically.
  • ↑ ↓ → ←: Navigate between adjacent cells.
  • Shortcut: Press M to activate the Database Schema Table tool.

Live Animated Data Flow Connectors

Simulate data streaming across connectors in real time:

const animatedStream: SketchBoardElement = {
  id: 'stream_1',
  type: 'arrow',
  arrowType: 'elbow',
  x: 280,
  y: 150,
  width: 140,
  height: 80,
  strokeColor: '#3b82f6',
  strokeWidth: 2,
  strokeStyle: 'solid',
  fillColor: 'transparent',
  fillStyle: 'solid',
  opacity: 1,
  zIndex: 2,
  endArrowhead: 'arrow',
  // Live Connector Simulation:
  flowAnimation: 'packet-pulse', // 'none' | 'marching-ants' | 'packet-pulse' | 'error-backoff'
  flowSpeed: 'normal',           // 'slow' (2.4s) | 'normal' (1.4s) | 'fast' (0.7s)
  flowTrigger: 'continuous',     // 'continuous' | 'hover' | 'click' | 'step'
  flowColor: '#60a5fa',          // Custom packet glow color
}

Programmatic Controller (SketchController)

Attach a controllerRef to imperatively control the whiteboard canvas:

import React, { useRef } from 'react'
import { SketchEditor, type SketchController } from '@filekit-studio/sketch'

export function ControlledCanvas() {
  const controllerRef = useRef<SketchController | null>(null)

  const handleAddNote = () => {
    controllerRef.current?.addElement({
      type: 'sticky',
      x: 200,
      y: 200,
      width: 180,
      height: 180,
      text: 'Production Note',
      fillColor: '#fef08a',
    })
  }

  return (
    <div className="w-full h-full relative">
      <button onClick={handleAddNote}>+ Add Note</button>
      <SketchEditor controllerRef={controllerRef} />
    </div>
  )
}

Controller Methods

Component API Reference

<SketchEditor />

<SketchViewer />

License

MIT © FileKit Studio