legend-state-dev-tools 0.0.1

package/README.md

@@ -0,0 +1,138 @@
+# legend-state-dev-tools
+
+> **Early-stage project** -- I discovered Legend State recently and chose it for a project I was working on. It had everything I needed from a state manager, but I couldn't live without dev tools, so I built this. It appears to work, but it hasn't been thoroughly tested yet -- consider it a proof of concept for now.
+
+[![npm version](https://img.shields.io/npm/v/legend-state-dev-tools)](https://www.npmjs.com/package/legend-state-dev-tools)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+Visual dev tools for Legend State v3 -- inspect and edit observable state in real time.
+
+<!-- screenshot -->
+
+## Features
+
+- Real-time state tree view powered by `json-edit-react`
+- Inline editing of observable values
+- Multiple color themes (dark and light variants)
+- Draggable toolbar
+- Configurable panel positioning (left or right)
+- Read-only mode
+- Clean teardown via `destroy()`
+
+## Installation
+
+```bash
+npm install legend-state-dev-tools
+```
+
+```bash
+pnpm add legend-state-dev-tools
+```
+
+```bash
+yarn add legend-state-dev-tools
+```
+
+### Peer dependencies
+
+| Package | Version |
+|---------|---------|
+| `@legendapp/state` | `>= 3.0.0-beta.0` |
+| `react` | `>= 18.0.0` |
+| `react-dom` | `>= 18.0.0` |
+
+## Quick Start
+
+```ts
+import { observable } from '@legendapp/state';
+import { init } from 'legend-state-dev-tools';
+import 'legend-state-dev-tools/dist/style.css';
+
+const state$ = observable({ count: 0, user: { name: 'Alice' } });
+
+const devtools = init(state$);
+
+// Later, to clean up:
+// devtools.destroy();
+```
+
+## API Reference
+
+### `init(observable$, options?)`
+
+Mounts the dev tools UI and returns a handle for cleanup.
+
+**Parameters**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `observable$` | `ObservableParam<any>` | The Legend State observable to inspect |
+| `options` | `DevToolsOptions` | Optional configuration (see below) |
+
+**Options**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | `boolean` | `true` | Enable or disable the dev tools |
+| `readOnly` | `boolean` | `false` | Prevent editing of state values |
+| `theme` | `string` | `'githubDark'` | Color theme for the JSON editor |
+| `rootName` | `string` | `'state$'` | Label shown as the root node name |
+| `position` | `'left' \| 'right'` | `'right'` | Side of the screen for the panel |
+
+**Returns**
+
+```ts
+{ destroy: () => void }
+```
+
+Call `destroy()` to unmount the toolbar, panel, and state subscription.
+
+## Themes
+
+The following themes are available (provided by `json-edit-react`):
+
+| Theme key | Description |
+|-----------|-------------|
+| `githubDark` | GitHub dark (default) |
+| `githubLight` | GitHub light |
+| `monoDark` | Monochrome dark |
+| `monoLight` | Monochrome light |
+
+## Example
+
+A working example is included in `examples/basic/`. To run it:
+
+```bash
+npm install
+npm run dev
+```
+
+This builds the core package and starts the Vite dev server for the example app.
+
+## Development
+
+```bash
+git clone <repo-url>
+cd legend-state-dev-tools
+npm install
+npm run build   # build the core package
+npm run dev     # build + start example dev server
+```
+
+## Architecture
+
+The project is a monorepo with the main package in `packages/core/` and examples in `examples/`.
+
+| Module | Path | Role |
+|--------|------|------|
+| `index` | `packages/core/src/index.ts` | Public API (`init`, options, lifecycle) |
+| `state-bridge` | `packages/core/src/state-bridge.ts` | Subscribes to observables, produces snapshots, writes back edits |
+| `json-editor-mount` | `packages/core/src/ui/json-editor-mount.tsx` | Mounts the `json-edit-react` editor with theme resolution |
+| `panel` | `packages/core/src/ui/panel.ts` | Slide-out panel DOM management |
+| `toolbar` | `packages/core/src/ui/toolbar.ts` | Draggable floating toolbar |
+| `template-engine` | `packages/core/src/ui/template-engine.ts` | Lightweight HTML templating (Eta) |
+| `styles` | `packages/core/src/styles.css` | Panel and toolbar CSS |
+
+## License
+
+MIT

package/examples/basic/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Legend State Dev Tools - Example</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/examples/basic/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "legend-state-dev-tools-example",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build"
+  },
+  "dependencies": {
+    "@legendapp/state": "^3.0.0-beta.43",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "json-edit-react": "^1.16.0",
+    "legend-state-dev-tools": "*"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "@vitejs/plugin-react": "^4.3.0",
+    "typescript": "^5.3.0",
+    "vite": "^6.0.0"
+  }
+}

package/examples/basic/src/App.tsx

@@ -0,0 +1,50 @@
+import React from 'react';
+import { observer } from '@legendapp/state/react';
+import { state$ } from './state';
+
+export const App = observer(function App() {
+  // In Legend State v3, use .get() to subscribe to values
+  const count = (state$.count as any).get();
+  const userName = (state$.user.name as any).get();
+
+  return (
+    <div style={{ padding: 40, fontFamily: 'sans-serif', maxWidth: 600 }}>
+      <h1>Legend State Dev Tools Demo</h1>
+      <p>Open the dev tools panel using the floating button at the bottom-right.</p>
+
+      <div style={{ marginTop: 24, padding: 16, background: '#f5f5f5', borderRadius: 8, color: '#1a1a1a' }}>
+        <h2>Counter: {count}</h2>
+        <button onClick={() => (state$.count as any).set((c: number) => c + 1)}>
+          Increment
+        </button>
+        <button onClick={() => (state$.count as any).set(0)} style={{ marginLeft: 8 }}>
+          Reset
+        </button>
+      </div>
+
+      <div style={{ marginTop: 24, padding: 16, background: '#f5f5f5', borderRadius: 8, color: '#1a1a1a' }}>
+        <h2>User: {userName}</h2>
+        <input
+          value={userName}
+          onChange={(e) => (state$.user.name as any).set(e.target.value)}
+          style={{ padding: '4px 8px', fontSize: 14 }}
+        />
+      </div>
+
+      <div style={{ marginTop: 24, padding: 16, background: '#f5f5f5', borderRadius: 8, color: '#1a1a1a' }}>
+        <h2>Todos</h2>
+        <button
+          onClick={() =>
+            (state$.todos as any).push({
+              id: Date.now(),
+              text: `New todo ${Date.now()}`,
+              done: false,
+            })
+          }
+        >
+          Add Todo
+        </button>
+      </div>
+    </div>
+  );
+});

package/examples/basic/src/main.tsx

@@ -0,0 +1,16 @@
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import { init } from 'legend-state-dev-tools';
+import 'legend-state-dev-tools/dist/styles.css';
+import { state$ } from './state';
+import { App } from './App';
+
+// Initialize dev tools
+init(state$, {
+  rootName: 'state$',
+  theme: 'githubDark',
+  readOnly: false,
+});
+
+const root = createRoot(document.getElementById('root')!);
+root.render(<App />);

package/examples/basic/src/state.ts

@@ -0,0 +1,17 @@
+import { observable } from '@legendapp/state';
+
+export const state$ = observable({
+  count: 0,
+  user: {
+    name: 'Alice',
+    email: 'alice@example.com',
+    preferences: {
+      darkMode: true,
+      notifications: true,
+    },
+  },
+  todos: [
+    { id: 1, text: 'Learn Legend State', done: true },
+    { id: 2, text: 'Try dev tools', done: false },
+  ],
+});

package/examples/basic/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "jsx": "react-jsx",
+    "resolveJsonModule": true,
+    "isolatedModules": true
+  },
+  "include": ["src"]
+}

package/examples/basic/vite.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+});

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "legend-state-dev-tools",
+  "version": "0.0.1",
+  "private": false,
+  "workspaces": [
+    "packages/*",
+    "examples/*"
+  ],
+  "scripts": {
+    "build": "npm run build -w packages/core",
+    "dev": "npm run build && npm run dev -w examples/basic",
+    "clean": "rm -rf node_modules packages/*/dist packages/*/node_modules examples/*/node_modules"
+  },
+  "license": "MIT"
+}

package/packages/core/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "legend-state-dev-tools",
+  "version": "0.1.0",
+  "description": "Dev tools for Legend State v3 - view and edit observable state",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "typescript": "^5.3.0",
+    "vite": "^6.0.0",
+    "vite-plugin-dts": "^4.0.0"
+  },
+  "peerDependencies": {
+    "@legendapp/state": ">=3.0.0-beta.0",
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "dependencies": {
+    "eta": "^3.5.0",
+    "json-edit-react": "^1.16.0"
+  }
+}

package/packages/core/src/eta.d.ts

@@ -0,0 +1,4 @@
+declare module '*.eta' {
+  const content: string;
+  export default content;
+}

package/packages/core/src/index.ts

@@ -0,0 +1,130 @@
+import type { ObservableParam } from '@legendapp/state';
+import { Toolbar } from './ui/toolbar';
+import { Panel } from './ui/panel';
+import { createStateBridge, type StateBridge } from './state-bridge';
+import { mountJsonEditor, type JsonEditorBridge } from './ui/json-editor-mount';
+import { createCleanup } from './ui/shared-utils';
+
+export interface DevToolsOptions {
+  enabled?: boolean;
+  readOnly?: boolean;
+  theme?: string;
+  rootName?: string;
+  position?: 'left' | 'right';
+}
+
+export interface DevTools {
+  destroy: () => void;
+}
+
+export function init(
+  observable$: ObservableParam<any>,
+  options: DevToolsOptions = {}
+): DevTools {
+  const {
+    enabled = true,
+    readOnly = false,
+    theme = 'githubDark',
+    rootName = 'state$',
+    position = 'right',
+  } = options;
+
+  if (!enabled) {
+    return { destroy: () => {} };
+  }
+
+  const cleanup = createCleanup();
+  let panel: Panel | null = null;
+  let toolbar: Toolbar | null = null;
+  let bridge: StateBridge | null = null;
+  let editorBridge: JsonEditorBridge | null = null;
+
+  // Create panel
+  panel = new Panel({
+    rootName,
+    readOnly,
+    position,
+    onClose: () => {
+      hidePanel();
+    },
+  });
+
+  const showPanel = () => {
+    if (!panel) return;
+    panel.show();
+    toolbar?.setPanelVisible(true);
+
+    // Poll for editor root element (innerHTML may not be ready immediately)
+    const tryMount = (retries = 10) => {
+      const editorRoot = panel?.getEditorRoot();
+      if (!editorRoot) {
+        if (retries > 0) {
+          setTimeout(() => tryMount(retries - 1), 16);
+        } else {
+          console.warn('[Legend State DevTools] Could not find #lsdt-json-editor-root after retries');
+        }
+        return;
+      }
+      if (editorBridge) return;
+
+      const initialData = bridge?.getSnapshot() ?? {};
+
+      editorBridge = mountJsonEditor(editorRoot, {
+        initialData,
+        onEdit: (newData: unknown) => {
+          bridge?.setData(newData);
+        },
+        readOnly,
+        theme,
+        rootName,
+      });
+    };
+    tryMount();
+  };
+
+  const hidePanel = () => {
+    if (editorBridge) {
+      editorBridge.destroy();
+      editorBridge = null;
+    }
+    panel?.hide();
+    toolbar?.setPanelVisible(false);
+  };
+
+  const togglePanel = () => {
+    if (panel?.isVisible()) {
+      hidePanel();
+    } else {
+      showPanel();
+    }
+  };
+
+  // Create toolbar
+  toolbar = new Toolbar({
+    onTogglePanel: togglePanel,
+    rootName,
+  });
+  toolbar.mount();
+  cleanup.add(() => toolbar?.unmount());
+
+  // Create state bridge
+  bridge = createStateBridge(observable$, {
+    onSnapshot: (snapshot) => {
+      editorBridge?.updateData(snapshot);
+    },
+  });
+  cleanup.add(() => bridge?.destroy());
+  cleanup.add(() => {
+    if (editorBridge) {
+      editorBridge.destroy();
+      editorBridge = null;
+    }
+  });
+  cleanup.add(() => panel?.unmount());
+
+  return {
+    destroy: () => {
+      cleanup.run();
+    },
+  };
+}

package/packages/core/src/state-bridge.ts

@@ -0,0 +1,56 @@
+import type { ObservableParam } from '@legendapp/state';
+
+export interface StateBridgeOptions {
+  onSnapshot: (snapshot: unknown) => void;
+}
+
+export interface StateBridge {
+  getSnapshot: () => unknown;
+  setData: (newData: unknown) => void;
+  destroy: () => void;
+}
+
+export function createStateBridge(
+  observable$: ObservableParam<any>,
+  options: StateBridgeOptions
+): StateBridge {
+  // Get initial snapshot
+  const getSnapshot = () => {
+    try {
+      return JSON.parse(JSON.stringify((observable$ as any).peek()));
+    } catch {
+      return undefined;
+    }
+  };
+
+  // Subscribe to changes using onChange
+  let dispose: (() => void) | null = null;
+  try {
+    dispose = (observable$ as any).onChange(
+      () => {
+        const snapshot = getSnapshot();
+        options.onSnapshot(snapshot);
+      },
+      { trackingType: false }
+    );
+  } catch {
+    console.warn('[Legend State DevTools] Could not subscribe to observable changes via onChange');
+  }
+
+  return {
+    getSnapshot,
+    setData: (newData: unknown) => {
+      try {
+        (observable$ as any).set(newData);
+      } catch (e) {
+        console.error('[Legend State DevTools] Failed to set data:', e);
+      }
+    },
+    destroy: () => {
+      if (dispose) {
+        dispose();
+        dispose = null;
+      }
+    },
+  };
+}

package/packages/core/src/styles.css

@@ -0,0 +1,184 @@
+/* Legend State Dev Tools Styles */
+
+/* Toolbar */
+#lsdt-toolbar {
+  position: fixed;
+  bottom: 20px;
+  right: 20px;
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+  color: white;
+  padding: 10px 14px;
+  border-radius: 12px;
+  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3);
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  font-size: 14px;
+  z-index: 999999;
+  cursor: move;
+  user-select: none;
+  backdrop-filter: blur(10px);
+  border: 1px solid rgba(255, 255, 255, 0.2);
+  transition: all 0.2s ease;
+}
+
+#lsdt-toolbar.dragging {
+  opacity: 0.8;
+  cursor: grabbing;
+}
+
+.lsdt-toolbar-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+}
+
+.lsdt-toolbar-title {
+  font-weight: 600;
+  font-size: 13px;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  white-space: nowrap;
+}
+
+.lsdt-toolbar-indicator {
+  width: 8px;
+  height: 8px;
+  background: #4ade80;
+  border-radius: 50%;
+  box-shadow: 0 0 6px rgba(74, 222, 128, 0.6);
+  flex-shrink: 0;
+}
+
+.lsdt-toggle-btn {
+  background: rgba(255, 255, 255, 0.2);
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  color: white;
+  padding: 5px 10px;
+  border-radius: 6px;
+  cursor: pointer;
+  font-size: 12px;
+  font-weight: 500;
+  transition: all 0.2s;
+  white-space: nowrap;
+}
+
+.lsdt-toggle-btn:hover {
+  background: rgba(255, 255, 255, 0.3);
+  transform: translateY(-1px);
+}
+
+.lsdt-toggle-btn.active {
+  background: rgba(255, 255, 255, 0.4);
+  border-color: rgba(255, 255, 255, 0.5);
+}
+
+/* Panel */
+#lsdt-panel {
+  position: fixed;
+  top: 20px;
+  right: 20px;
+  width: 420px;
+  max-height: calc(100vh - 100px);
+  background: #1e1e2e;
+  border-radius: 12px;
+  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.4);
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  z-index: 999999;
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+  border: 1px solid rgba(255, 255, 255, 0.1);
+}
+
+#lsdt-panel.lsdt-panel-left {
+  right: auto;
+  left: 20px;
+}
+
+.lsdt-panel-header {
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+  color: white;
+  padding: 14px 16px;
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  flex-shrink: 0;
+}
+
+.lsdt-panel-header h3 {
+  margin: 0;
+  font-size: 15px;
+  font-weight: 600;
+}
+
+.lsdt-panel-actions {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.lsdt-readonly-badge {
+  font-size: 10px;
+  background: rgba(255, 255, 255, 0.2);
+  padding: 2px 8px;
+  border-radius: 4px;
+  font-weight: 500;
+}
+
+.lsdt-close-btn {
+  background: rgba(255, 255, 255, 0.2);
+  border: none;
+  color: white;
+  width: 24px;
+  height: 24px;
+  border-radius: 50%;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 16px;
+  transition: background 0.2s;
+}
+
+.lsdt-close-btn:hover {
+  background: rgba(255, 255, 255, 0.3);
+}
+
+.lsdt-panel-content {
+  padding: 0;
+  overflow-y: auto;
+  flex: 1;
+  min-height: 200px;
+  max-height: calc(100vh - 180px);
+}
+
+/* json-edit-react overrides for dark panel */
+#lsdt-json-editor-root {
+  font-size: 13px;
+}
+
+#lsdt-json-editor-root > div {
+  border-radius: 0 !important;
+  border: none !important;
+}
+
+/* Responsive */
+@media (max-width: 768px) {
+  #lsdt-toolbar {
+    bottom: 10px;
+    right: 10px;
+    font-size: 12px;
+  }
+
+  #lsdt-panel {
+    width: calc(100vw - 20px);
+    right: 10px;
+    top: 10px;
+    max-height: calc(100vh - 80px);
+  }
+
+  #lsdt-panel.lsdt-panel-left {
+    left: 10px;
+  }
+}

package/packages/core/src/ui/json-editor-mount.tsx

@@ -0,0 +1,144 @@
+import React, { Component, useEffect, useState, type ErrorInfo, type ReactNode } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { JsonEditor, githubDarkTheme, githubLightTheme, monoDarkTheme, monoLightTheme } from 'json-edit-react';
+
+const themeMap: Record<string, object> = {
+  githubDark: githubDarkTheme,
+  githubLight: githubLightTheme,
+  monoDark: monoDarkTheme,
+  monoLight: monoLightTheme,
+};
+
+class ErrorBoundary extends Component<
+  { children: ReactNode },
+  { error: Error | null }
+> {
+  state = { error: null as Error | null };
+  static getDerivedStateFromError(error: Error) {
+    return { error };
+  }
+  componentDidCatch(error: Error, info: ErrorInfo) {
+    console.error('[Legend State DevTools] React error:', error, info);
+  }
+  render() {
+    if (this.state.error) {
+      return React.createElement(
+        'pre',
+        { style: { color: '#ff6b6b', padding: 16, fontSize: 12 } },
+        `DevTools Error: ${this.state.error.message}\n${this.state.error.stack}`
+      );
+    }
+    return this.props.children;
+  }
+}
+
+interface JsonEditorWrapperProps {
+  data: unknown;
+  onEdit: (newData: unknown) => void;
+  readOnly: boolean;
+  theme: string;
+  rootName: string;
+}
+
+function JsonEditorWrapper({
+  data,
+  onEdit,
+  readOnly,
+  theme,
+  rootName,
+}: JsonEditorWrapperProps) {
+  const resolvedTheme = themeMap[theme] ?? githubDarkTheme;
+  return (
+    <JsonEditor
+      data={data as Record<string, unknown>}
+      setData={onEdit as any}
+      rootName={rootName}
+      theme={resolvedTheme as any}
+      collapse={2}
+      restrictEdit={readOnly}
+      restrictDelete={readOnly}
+      restrictAdd={readOnly}
+      restrictTypeSelection={readOnly ? true : undefined}
+    />
+  );
+}
+
+export interface JsonEditorBridge {
+  updateData: (data: unknown) => void;
+  destroy: () => void;
+}
+
+// Wrapper component that receives data via a callback registration
+function JsonEditorBridgeWrapper(props: {
+  initialData: unknown;
+  onEdit: (newData: unknown) => void;
+  readOnly: boolean;
+  theme: string;
+  rootName: string;
+  registerUpdater: (updater: (data: unknown) => void) => void;
+}) {
+  const [data, setData] = useState<unknown>(props.initialData);
+
+  useEffect(() => {
+    props.registerUpdater((newData: unknown) => {
+      setData(newData);
+    });
+  }, []);
+
+  const handleEdit = (newData: unknown) => {
+    setData(newData);
+    props.onEdit(newData);
+  };
+
+  return (
+    <JsonEditorWrapper
+      data={data}
+      onEdit={handleEdit}
+      readOnly={props.readOnly}
+      theme={props.theme}
+      rootName={props.rootName}
+    />
+  );
+}
+
+export function mountJsonEditor(
+  container: HTMLElement,
+  options: {
+    initialData: unknown;
+    onEdit: (newData: unknown) => void;
+    readOnly: boolean;
+    theme: string;
+    rootName: string;
+  }
+): JsonEditorBridge {
+  let root: Root | null = null;
+  let updaterFn: ((data: unknown) => void) | null = null;
+
+  root = createRoot(container);
+  root.render(
+    <ErrorBoundary>
+    <JsonEditorBridgeWrapper
+      initialData={options.initialData}
+      onEdit={options.onEdit}
+      readOnly={options.readOnly}
+      theme={options.theme}
+      rootName={options.rootName}
+      registerUpdater={(updater) => {
+        updaterFn = updater;
+      }}
+    />
+    </ErrorBoundary>
+  );
+
+  return {
+    updateData: (data: unknown) => {
+      updaterFn?.(data);
+    },
+    destroy: () => {
+      if (root) {
+        root.unmount();
+        root = null;
+      }
+    },
+  };
+}

package/packages/core/src/ui/panel.ts

@@ -0,0 +1,96 @@
+import { renderPanel, type PanelData } from './template-engine';
+
+export class Panel {
+  private container: HTMLElement | null = null;
+  private visible = false;
+  private rootName: string;
+  private readOnly: boolean;
+  private onClose?: () => void;
+  private position: 'left' | 'right';
+
+  constructor(options: {
+    rootName?: string;
+    readOnly?: boolean;
+    onClose?: () => void;
+    position?: 'left' | 'right';
+  } = {}) {
+    this.rootName = options.rootName || 'state$';
+    this.readOnly = options.readOnly || false;
+    this.onClose = options.onClose;
+    this.position = options.position || 'right';
+  }
+
+  public toggle(): void {
+    if (this.visible) {
+      this.hide();
+    } else {
+      this.show();
+    }
+  }
+
+  public show(): void {
+    this.visible = true;
+
+    if (!this.container) {
+      this.container = document.createElement('div');
+      this.container.id = 'lsdt-panel';
+      if (this.position === 'left') {
+        this.container.classList.add('lsdt-panel-left');
+      }
+      document.body.appendChild(this.container);
+      this.attachEventListeners();
+    }
+
+    this.render();
+  }
+
+  public hide(): void {
+    this.visible = false;
+    this.container?.remove();
+    this.container = null;
+  }
+
+  public isVisible(): boolean {
+    return this.visible;
+  }
+
+  public getEditorRoot(): HTMLElement | null {
+    return this.container?.querySelector('#lsdt-json-editor-root') || null;
+  }
+
+  private render(): void {
+    if (!this.container) return;
+
+    const data: PanelData = {
+      rootName: this.rootName,
+      readOnly: this.readOnly,
+    };
+
+    this.container.innerHTML = renderPanel(data);
+  }
+
+  private attachEventListeners(): void {
+    if (!this.container) return;
+    this.container.addEventListener('click', this.handleClick);
+  }
+
+  private handleClick = (e: Event): void => {
+    const target = e.target as HTMLElement;
+    const actionElement = target.closest('[data-action]');
+    if (!actionElement) return;
+
+    const action = actionElement.getAttribute('data-action');
+    if (action === 'close-panel') {
+      this.onClose?.();
+    }
+  };
+
+  public unmount(): void {
+    if (this.container) {
+      this.container.removeEventListener('click', this.handleClick);
+      this.container.remove();
+      this.container = null;
+    }
+    this.visible = false;
+  }
+}

package/packages/core/src/ui/shared-utils.ts

@@ -0,0 +1,49 @@
+/**
+ * Shared UI utilities for Legend State Dev Tools
+ */
+
+const STORAGE_PREFIX = 'lsdt';
+
+export function escapeHtml(str: string): string {
+  const div = document.createElement('div');
+  div.textContent = str;
+  return div.innerHTML;
+}
+
+export function getStoredBoolean(key: string, defaultValue: boolean): boolean {
+  const stored = localStorage.getItem(`${STORAGE_PREFIX}-${key}`);
+  if (stored === null) return defaultValue;
+  return stored === 'true';
+}
+
+export function setStoredBoolean(key: string, value: boolean): void {
+  localStorage.setItem(`${STORAGE_PREFIX}-${key}`, String(value));
+}
+
+export function getStoredString(key: string, defaultValue: string): string {
+  return localStorage.getItem(`${STORAGE_PREFIX}-${key}`) || defaultValue;
+}
+
+export function setStoredString(key: string, value: string): void {
+  localStorage.setItem(`${STORAGE_PREFIX}-${key}`, value);
+}
+
+export function createCleanup(): {
+  add: (fn: () => void) => void;
+  run: () => void;
+} {
+  const cleanupFns: (() => void)[] = [];
+  return {
+    add: (fn: () => void) => cleanupFns.push(fn),
+    run: () => {
+      cleanupFns.forEach((fn) => {
+        try {
+          fn();
+        } catch (e) {
+          console.error('[Legend State DevTools] Cleanup error:', e);
+        }
+      });
+      cleanupFns.length = 0;
+    },
+  };
+}

package/packages/core/src/ui/template-engine.ts

@@ -0,0 +1,55 @@
+/**
+ * Eta template engine wrapper for Legend State Dev Tools
+ */
+import { Eta } from 'eta';
+
+import toolbarTemplate from './templates/toolbar.eta';
+import panelTemplate from './templates/panel.eta';
+
+const eta = new Eta({
+  autoEscape: true,
+  autoTrim: false,
+});
+
+const templates: Record<string, string> = {
+  toolbar: toolbarTemplate,
+  panel: panelTemplate,
+};
+
+export function renderTemplate<T extends Record<string, unknown>>(
+  name: string,
+  data: T
+): string {
+  const template = templates[name];
+  if (!template) {
+    console.error(`[LSDT] Template not found: ${name}`);
+    return '';
+  }
+  try {
+    return eta.renderString(template, data);
+  } catch (error) {
+    console.error(`[LSDT] Error rendering template ${name}:`, error);
+    return '';
+  }
+}
+
+export interface ToolbarData {
+  [key: string]: unknown;
+  isMinimized: boolean;
+  panelVisible: boolean;
+  rootName: string;
+}
+
+export function renderToolbar(data: ToolbarData): string {
+  return renderTemplate('toolbar', data);
+}
+
+export interface PanelData {
+  [key: string]: unknown;
+  rootName: string;
+  readOnly: boolean;
+}
+
+export function renderPanel(data: PanelData): string {
+  return renderTemplate('panel', data);
+}

package/packages/core/src/ui/templates/panel.eta

@@ -0,0 +1,12 @@
+<div class="lsdt-panel-header">
+  <h3><%= it.rootName %></h3>
+  <div class="lsdt-panel-actions">
+    <% if (it.readOnly) { %>
+      <span class="lsdt-readonly-badge">Read-only</span>
+    <% } %>
+    <button class="lsdt-close-btn" data-action="close-panel" title="Close">&times;</button>
+  </div>
+</div>
+<div class="lsdt-panel-content">
+  <div id="lsdt-json-editor-root"></div>
+</div>

package/packages/core/src/ui/templates/toolbar.eta

@@ -0,0 +1,13 @@
+<div class="lsdt-toolbar-header">
+  <div class="lsdt-toolbar-title">
+    <span class="lsdt-toolbar-indicator"></span>
+    Legend State
+  </div>
+  <button
+    class="lsdt-toggle-btn <%= it.panelVisible ? 'active' : '' %>"
+    data-action="toggle-panel"
+    title="<%= it.panelVisible ? 'Hide panel' : 'Show panel' %>"
+  >
+    <%= it.panelVisible ? 'Hide' : 'Show' %> <%= it.rootName %>
+  </button>
+</div>

package/packages/core/src/ui/toolbar.ts

@@ -0,0 +1,108 @@
+import { renderToolbar, type ToolbarData } from './template-engine';
+import { getStoredBoolean, setStoredBoolean } from './shared-utils';
+
+export class Toolbar {
+  private container: HTMLElement | null = null;
+  private isDragging = false;
+  private offsetX = 0;
+  private offsetY = 0;
+  private isMinimized: boolean = getStoredBoolean('toolbar-minimized', false);
+  private panelVisible = false;
+
+  private onTogglePanel?: () => void;
+  private rootName: string;
+
+  constructor(options: { onTogglePanel?: () => void; rootName?: string } = {}) {
+    this.onTogglePanel = options.onTogglePanel;
+    this.rootName = options.rootName || 'state$';
+  }
+
+  public mount(): void {
+    if (this.container) return;
+
+    this.container = document.createElement('div');
+    this.container.id = 'lsdt-toolbar';
+    if (this.isMinimized) {
+      this.container.classList.add('lsdt-toolbar-minimized');
+    }
+
+    document.body.appendChild(this.container);
+    this.render();
+    this.attachEventListeners();
+  }
+
+  private render(): void {
+    if (!this.container) return;
+
+    const data: ToolbarData = {
+      isMinimized: this.isMinimized,
+      panelVisible: this.panelVisible,
+      rootName: this.rootName,
+    };
+
+    this.container.innerHTML = renderToolbar(data);
+  }
+
+  private attachEventListeners(): void {
+    if (!this.container) return;
+
+    this.container.addEventListener('click', this.handleClick);
+    this.container.addEventListener('mousedown', this.handleMouseDown);
+    document.addEventListener('mousemove', this.handleMouseMove);
+    document.addEventListener('mouseup', this.handleMouseUp);
+  }
+
+  private handleClick = (e: Event): void => {
+    const target = e.target as HTMLElement;
+    const actionElement = target.closest('[data-action]');
+    if (!actionElement) return;
+
+    const action = actionElement.getAttribute('data-action');
+    if (action === 'toggle-panel') {
+      this.onTogglePanel?.();
+    }
+  };
+
+  private handleMouseDown = (e: MouseEvent): void => {
+    const target = e.target as HTMLElement;
+    if (target.tagName === 'BUTTON') return;
+
+    this.isDragging = true;
+    if (this.container) {
+      this.container.classList.add('dragging');
+      const rect = this.container.getBoundingClientRect();
+      this.offsetX = e.clientX - rect.left;
+      this.offsetY = e.clientY - rect.top;
+    }
+  };
+
+  private handleMouseMove = (e: MouseEvent): void => {
+    if (!this.isDragging || !this.container) return;
+
+    this.container.style.left = `${e.clientX - this.offsetX}px`;
+    this.container.style.top = `${e.clientY - this.offsetY}px`;
+    this.container.style.right = 'auto';
+    this.container.style.bottom = 'auto';
+  };
+
+  private handleMouseUp = (): void => {
+    this.isDragging = false;
+    this.container?.classList.remove('dragging');
+  };
+
+  public setPanelVisible(visible: boolean): void {
+    this.panelVisible = visible;
+    this.render();
+  }
+
+  public unmount(): void {
+    if (this.container) {
+      this.container.removeEventListener('click', this.handleClick);
+      this.container.removeEventListener('mousedown', this.handleMouseDown);
+      this.container.remove();
+      this.container = null;
+    }
+    document.removeEventListener('mousemove', this.handleMouseMove);
+    document.removeEventListener('mouseup', this.handleMouseUp);
+  }
+}

package/packages/core/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["dist/**/*"]
+}

package/packages/core/vite.config.ts

@@ -0,0 +1,71 @@
+import { defineConfig } from 'vite';
+import { resolve } from 'path';
+import { copyFileSync } from 'fs';
+import dts from 'vite-plugin-dts';
+
+export default defineConfig({
+  plugins: [
+    {
+      name: 'eta-raw-loader',
+      transform(code, id) {
+        if (id.endsWith('.eta')) {
+          return {
+            code: `export default ${JSON.stringify(code)};`,
+            map: null,
+          };
+        }
+      },
+    },
+    dts({
+      include: ['src/**/*.ts', 'src/**/*.tsx'],
+      exclude: ['src/**/*.test.ts'],
+      rollupTypes: true,
+      insertTypesEntry: true,
+    }),
+    {
+      name: 'copy-styles',
+      closeBundle() {
+        copyFileSync(
+          resolve(__dirname, 'src/styles.css'),
+          resolve(__dirname, 'dist/styles.css')
+        );
+      },
+    },
+  ],
+  build: {
+    lib: {
+      entry: resolve(__dirname, 'src/index.ts'),
+      name: 'LegendStateDevTools',
+      formats: ['es', 'cjs'],
+      fileName: (format) => (format === 'es' ? 'index.mjs' : 'index.js'),
+    },
+    rollupOptions: {
+      external: [
+        'react',
+        'react-dom',
+        'react-dom/client',
+        'react/jsx-runtime',
+        'eta',
+        'json-edit-react',
+        '@legendapp/state',
+      ],
+      output: {
+        globals: {
+          react: 'React',
+          'react-dom': 'ReactDOM',
+          'react-dom/client': 'ReactDOMClient',
+          eta: 'Eta',
+          'json-edit-react': 'JsonEditReact',
+          '@legendapp/state': 'LegendState',
+        },
+      },
+    },
+    outDir: 'dist',
+    emptyOutDir: true,
+    sourcemap: true,
+    minify: 'esbuild',
+  },
+  resolve: {
+    extensions: ['.ts', '.tsx', '.js', '.jsx', '.eta'],
+  },
+});

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "declaration": true,
+    "declarationMap": true,
+    "jsx": "react-jsx"
+  },
+  "exclude": ["examples/**/*", "node_modules/**/*", "**/dist/**/*"]
+}