+
+
+
+
+
+export type { CellEditorMode } from './ui'
+
+export const useCellEditorModes = (notebookId: string | null | undefined) => {
+ const { cellEditorModes } = useNotebookUIState()
+ if (!notebookId) return EMPTY_MODES
+ return cellEditorModes[notebookId] ?? EMPTY_MODES
+}
+
+export const useCellEditorModeForCell = (
+ notebookId: string,
+ cellId: string,
+): CellEditorMode => {
+ const { cellEditorModes } = useNotebookUIState()
+ if (!notebookId) return 'preview'
+ return cellEditorModes[notebookId]?.[cellId] ?? 'preview'
+}
+
+export const setCellEditorMode = (
+ notebookId: string,
+ cellId: string,
+ mode: CellEditorMode,
+) => {
+ notebookUIActions.setCellEditorMode(notebookId, cellId, mode)
+}
+
+export const toggleCellEditorMode = (notebookId: string, cellId: string) => {
+ notebookUIActions.toggleCellEditorMode(notebookId, cellId)
+}
+
+export const removeCellEditorMode = (notebookId: string, cellId: string) => {
+ notebookUIActions.removeCellEditorMode(notebookId, cellId)
+}
+
+export const resetCellEditorModes = (notebookId: string | null | undefined) => {
+ if (!notebookId) return
+ notebookUIActions.resetCellEditorModes(notebookId)
+}
diff --git a/web/atoms/notebook/cell-runtime.ts b/web/atoms/notebook/cell-runtime.ts
new file mode 100644
index 00000000..5f8d2395
--- /dev/null
+++ b/web/atoms/notebook/cell-runtime.ts
@@ -0,0 +1,28 @@
+import { proxy } from "valtio";
+import { useSnapshot } from "valtio";
+
+const cellCollapsedState = proxy>({});
+
+export const useCellCollapsedValue = () => useSnapshot(cellCollapsedState);
+
+export const toggleCellCollapsedAction = (cellId: string) => {
+ const current = cellCollapsedState[cellId] ?? false;
+ if (current) {
+ delete cellCollapsedState[cellId];
+ return;
+ }
+ cellCollapsedState[cellId] = true;
+};
+
+export const setCellCollapsedAction = (cellId: string, collapsed: boolean) => {
+ if (!collapsed) {
+ delete cellCollapsedState[cellId];
+ return;
+ }
+ cellCollapsedState[cellId] = collapsed;
+};
+
+export const useCellCollapsedForCell = (cellId: string): boolean => {
+ const snapshot = useSnapshot(cellCollapsedState);
+ return snapshot[cellId] === true;
+};
diff --git a/web/atoms/notebook/constants.ts b/web/atoms/notebook/constants.ts
new file mode 100644
index 00000000..036f0c75
--- /dev/null
+++ b/web/atoms/notebook/constants.ts
@@ -0,0 +1,7 @@
+export const NOTEBOOK_HISTORY_ENTRY_ORIGIN = {
+ INITIAL: "initial" as const,
+ USER: "user" as const,
+};
+
+export type NotebookHistoryEntryOrigin =
+ (typeof NOTEBOOK_HISTORY_ENTRY_ORIGIN)[keyof typeof NOTEBOOK_HISTORY_ENTRY_ORIGIN];
diff --git a/web/atoms/notebook/errors.ts b/web/atoms/notebook/errors.ts
new file mode 100644
index 00000000..5b21086f
--- /dev/null
+++ b/web/atoms/notebook/errors.ts
@@ -0,0 +1,53 @@
+// Standardized error types for notebook domain operations.
+
+export class NotebookError extends Error {
+ readonly code: string;
+ constructor(message: string, code = 'NOTEBOOK_ERROR') {
+ super(message);
+ this.name = this.constructor.name;
+ this.code = code;
+ }
+}
+
+export class NotebookNotReadyError extends NotebookError {
+ constructor(message = 'Notebook is not ready') {
+ super(message, 'NOTEBOOK_NOT_READY');
+ }
+}
+
+export class NotebookStateError extends NotebookError {
+ constructor(message = 'Invalid notebook state') {
+ super(message, 'NOTEBOOK_STATE');
+ }
+}
+
+export class CellNotFoundError extends NotebookError {
+ readonly cellId: string;
+ constructor(cellId: string, message = 'Cell not found') {
+ super(`${message}: ${cellId}`, 'CELL_NOT_FOUND');
+ this.cellId = cellId;
+ }
+}
+
+export class NotebookBoundaryError extends NotebookError {
+ readonly cellId: string;
+ readonly direction: 'up' | 'down';
+ constructor(cellId: string, direction: 'up' | 'down', message = 'Cell at boundary') {
+ super(`${message}: ${cellId} (${direction})`, 'NOTEBOOK_BOUNDARY');
+ this.cellId = cellId;
+ this.direction = direction;
+ }
+}
+
+// Small helper to prefix console messages consistently
+export function logNotebookError(context: string, error: unknown) {
+ const prefix = '[Notebook]';
+ if (error instanceof Error) {
+
+ console.error(`${prefix} ${context}:`, error.name, error.message);
+ } else {
+
+ console.error(`${prefix} ${context}:`, error);
+ }
+}
+
diff --git a/web/atoms/notebook/hooks/index.ts b/web/atoms/notebook/hooks/index.ts
new file mode 100644
index 00000000..21007f5d
--- /dev/null
+++ b/web/atoms/notebook/hooks/index.ts
@@ -0,0 +1,3 @@
+export * from './useNotebookState';
+export * from './useNotebookOperations';
+export * from './safe';
diff --git a/web/atoms/notebook/hooks/safe.ts b/web/atoms/notebook/hooks/safe.ts
new file mode 100644
index 00000000..1c5aa5ab
--- /dev/null
+++ b/web/atoms/notebook/hooks/safe.ts
@@ -0,0 +1,6 @@
+import { useNotebookRuntime } from "@/modules/notebook/providers/notebook-runtime-context";
+
+export function useNotebookReady(): boolean {
+ const { ready } = useNotebookRuntime();
+ return ready;
+}
diff --git a/web/atoms/notebook/hooks/useNotebookOperations.ts b/web/atoms/notebook/hooks/useNotebookOperations.ts
new file mode 100644
index 00000000..5e07d85d
--- /dev/null
+++ b/web/atoms/notebook/hooks/useNotebookOperations.ts
@@ -0,0 +1,111 @@
+import { useCallback, useMemo } from 'react';
+import toast from 'react-hot-toast';
+import * as execOps from '../operations/execution-ops';
+import { resolveErrorMessage } from '@/lib/errors';
+import { useNotebookRuntime } from '@/modules/notebook/providers/notebook-runtime-context';
+import { getNotebookRoot } from '@/modules/notebook/collab/yjs/schema/access/root';
+import { NB_DATABASE_ID } from '@/modules/notebook/collab/yjs/schema/core/keys';
+import { useSnapshot } from 'valtio';
+
+export function useNotebookOperations() {
+ const { resource, store } = useNotebookRuntime();
+ const root = useMemo(() => getNotebookRoot(resource.doc), [resource.doc]);
+ const snapshot = useSnapshot(store.state);
+ const databaseId = (snapshot as any)[NB_DATABASE_ID] ?? null;
+ const executedBy = resource.provider.awareness.clientID;
+
+ /**
+ * Execute a single cell.
+ * Shows toast notifications for success/error.
+ */
+ const executeCell = useCallback(
+ async (cellId: string): Promise => {
+ if (!root) {
+ toast.error('Notebook not loaded');
+ return false;
+ }
+
+ const dbId = databaseId ? Number(databaseId) : null;
+
+ if (!dbId) {
+ toast.error('Select a database before executing cells');
+ return false;
+ }
+
+ try {
+ await execOps.executeCell(root, cellId, { databaseId: dbId, executedBy });
+ return true;
+ } catch (err) {
+ const message = resolveErrorMessage(err, 'Failed to execute cell');
+ toast.error(message);
+ return false;
+ }
+ },
+ [root, databaseId]
+ );
+
+ /**
+ * Execute multiple cells sequentially.
+ * Shows summary toast after completion.
+ */
+ const executeCells = useCallback(
+ async (
+ cellIds: string[],
+ options?: { stopOnError?: boolean }
+ ): Promise<{ success: number; failed: number }> => {
+ if (!root) {
+ toast.error('Notebook not loaded');
+ return { success: 0, failed: 0 };
+ }
+
+ const dbId = databaseId ? Number(databaseId) : null;
+
+ if (!dbId) {
+ toast.error('Select a database before executing cells');
+ return { success: 0, failed: 0 };
+ }
+
+ try {
+ const results = await execOps.executeCells(root, cellIds, {
+ databaseId: dbId,
+ executedBy,
+ stopOnError: options?.stopOnError ?? false,
+ });
+
+ const successCount = results.filter((r) => r.success).length;
+ const failedCount = results.filter((r) => !r.success).length;
+
+ return { success: successCount, failed: failedCount };
+ } catch (err) {
+ const message = resolveErrorMessage(err, 'Failed to execute cells');
+ toast.error(message);
+ return { success: 0, failed: cellIds.length };
+ }
+ },
+ [root, databaseId]
+ );
+
+ /**
+ * Clear all cell outputs.
+ * Shows success toast.
+ */
+ const clearOutputs = useCallback(() => {
+ if (!root) {
+ toast.error('Notebook not loaded');
+ return;
+ }
+
+ try {
+ execOps.clearOutputs(root);
+ } catch (err) {
+ const message = resolveErrorMessage(err, 'Failed to clear outputs');
+ toast.error(message);
+ }
+ }, [root]);
+
+ return {
+ executeCell,
+ executeCells,
+ clearOutputs,
+ };
+}
diff --git a/web/atoms/notebook/hooks/useNotebookState.ts b/web/atoms/notebook/hooks/useNotebookState.ts
new file mode 100644
index 00000000..a3a8c29d
--- /dev/null
+++ b/web/atoms/notebook/hooks/useNotebookState.ts
@@ -0,0 +1,125 @@
+import { useCallback, useMemo } from 'react';
+import { useSnapshot } from 'valtio';
+import * as cellOps from '../operations/cell-ops';
+import * as metadataOps from '../operations/metadata-ops';
+import type { CellModel, CellMetadataModel } from '@/modules/notebook/collab/yjs/schema/core/types';
+import { NotebookBoundaryError, NotebookNotReadyError, logNotebookError } from '../errors';
+import { useNotebookRuntime } from '@/modules/notebook/providers/notebook-runtime-context';
+import { getNotebookRoot } from '@/modules/notebook/collab/yjs/schema/access/root';
+import { NB_DATABASE_ID, NB_TITLE, NB_CELL_ORDER } from '@/modules/notebook/collab/yjs/schema/core/keys';
+
+export function useNotebookState() {
+ const { resource, store } = useNotebookRuntime();
+ const snapshot = useSnapshot(store.state);
+ const root = useMemo(() => getNotebookRoot(resource.doc), [resource.doc]);
+
+ const title = (snapshot as any)[NB_TITLE] ?? 'Untitled Notebook';
+ const databaseId = snapshot[NB_DATABASE_ID] ?? null;
+ const cellOrder = snapshot[NB_CELL_ORDER] ?? [];
+
+ const setTitle = useCallback(
+ (nextTitle: string) => {
+ (store.state as any)[NB_TITLE] = nextTitle;
+ },
+ [store.state],
+ );
+
+ const setDatabaseId = useCallback(
+ (nextId: number | string | null) => {
+ (store.state as any)[NB_DATABASE_ID] = nextId === null ? null : String(nextId);
+ },
+ [store.state],
+ );
+
+ // Operation: Add cell
+ const addCell = useCallback(
+ (kind: CellModel['kind'], source?: string, index?: number): string | null => {
+ if (!root) {
+ // Not fatal; return fallback and log consistently
+ logNotebookError('Cannot add cell: notebook not loaded', new NotebookNotReadyError());
+ return null;
+ }
+
+ try {
+ return cellOps.addCell(root, { kind, source, index });
+ } catch (err) {
+ logNotebookError('Failed to add cell', err);
+ return null;
+ }
+ },
+ [root]
+ );
+
+ // Operation: Delete cell
+ const deleteCell = useCallback(
+ (cellId: string): void => {
+ if (!root) {
+ logNotebookError('Cannot delete cell: notebook not loaded', new NotebookNotReadyError());
+ return;
+ }
+
+ try {
+ cellOps.deleteCell(root, cellId);
+ } catch (err) {
+ logNotebookError('Failed to delete cell', err);
+ }
+ },
+ [root]
+ );
+
+ // Operation: Move cell
+ const moveCell = useCallback(
+ (cellId: string, direction: 'up' | 'down'): void => {
+ if (!root) {
+ logNotebookError('Cannot move cell: notebook not loaded', new NotebookNotReadyError());
+ return;
+ }
+
+ try {
+ const moved = cellOps.moveCell(root, cellId, direction);
+ if (!moved) {
+ // Boundary no-op: not an error, but keep consistent, low-noise log for debugging
+ // Avoid throwing; UI already disables boundary moves.
+ console.debug('[Notebook] Move cell no-op (boundary):', { cellId, direction });
+ }
+ } catch (err) {
+ // If a caller wants to differentiate boundary, cell-ops now returns false instead of throwing
+ if (err instanceof NotebookBoundaryError) return;
+ logNotebookError('Failed to move cell', err);
+ }
+ },
+ [root]
+ );
+
+ // Operation: Update cell metadata
+ const updateCellMetadata = useCallback(
+ (cellId: string, metadata: Partial): void => {
+ if (!root) {
+ logNotebookError('Cannot update cell metadata: notebook not loaded', new NotebookNotReadyError());
+ return;
+ }
+
+ try {
+ metadataOps.updateCellMetadata(root, cellId, metadata);
+ } catch (err) {
+ logNotebookError('Failed to update cell metadata', err);
+ }
+ },
+ [root]
+ );
+
+ return {
+ // State
+ title,
+ databaseId,
+ cellOrder,
+ // Setters
+ setTitle,
+ setDatabaseId,
+ // Operations
+ addCell,
+ deleteCell,
+ moveCell,
+ updateCellMetadata,
+ };
+}
diff --git a/web/atoms/notebook/index.ts b/web/atoms/notebook/index.ts
new file mode 100644
index 00000000..268360f8
--- /dev/null
+++ b/web/atoms/notebook/index.ts
@@ -0,0 +1,3 @@
+export * from './ui'
+export * from './cell-editor-modes'
+export * from './save-status'
diff --git a/web/atoms/notebook/operations/cell-ops.ts b/web/atoms/notebook/operations/cell-ops.ts
new file mode 100644
index 00000000..68299599
--- /dev/null
+++ b/web/atoms/notebook/operations/cell-ops.ts
@@ -0,0 +1,69 @@
+import * as Y from 'yjs';
+import type { YNotebook, CellModel } from '@/modules/notebook/collab/yjs/schema/core/types';
+import {
+ createCell,
+ insertCell as rawInsertCell,
+ softDeleteCell,
+ moveCell as rawMoveCell,
+} from '@/modules/notebook/collab/yjs/schema';
+import { NB_CELL_ORDER, CELL_ID } from '@/modules/notebook/collab/yjs/schema/core/keys';
+import { CellNotFoundError, NotebookStateError } from '@/atoms/notebook/errors';
+
+export function addCell(
+ root: YNotebook,
+ options: {
+ kind: CellModel['kind'];
+ source?: string;
+ index?: number;
+ }
+): string {
+ const { kind, source = '', index } = options;
+
+ // Create new cell
+ const newCell = createCell({ kind, source });
+
+ // Insert into notebook
+ rawInsertCell(root, newCell, index);
+
+ // Get and validate cell ID
+ const cellId = newCell.get(CELL_ID);
+ if (typeof cellId !== 'string') {
+ throw new NotebookStateError('Failed to create cell: missing cell ID');
+ }
+
+ return cellId;
+}
+
+export function deleteCell(root: YNotebook, cellId: string): void {
+ // soft delete is idempotent; rely on lower-level op to no-op if missing
+ softDeleteCell(root, cellId);
+}
+
+export function moveCell(
+ root: YNotebook,
+ cellId: string,
+ direction: 'up' | 'down'
+): boolean {
+ const orderArray = root.get(NB_CELL_ORDER) as Y.Array | undefined;
+ if (!orderArray) {
+ throw new NotebookStateError('Cell order array not found in notebook');
+ }
+
+ const currentOrder = orderArray.toArray();
+ const fromIndex = currentOrder.indexOf(cellId);
+
+ if (fromIndex === -1) {
+ throw new CellNotFoundError(cellId, 'Cell not found in order array');
+ }
+
+ const toIndex = direction === 'up' ? fromIndex - 1 : fromIndex + 1;
+
+ // Check boundaries - return explicit false to denote no-op
+ if (toIndex < 0 || toIndex >= currentOrder.length) {
+ return false;
+ }
+
+ // Perform move
+ rawMoveCell(root, cellId, toIndex);
+ return true;
+}
diff --git a/web/atoms/notebook/operations/execution-ops.ts b/web/atoms/notebook/operations/execution-ops.ts
new file mode 100644
index 00000000..b95669a9
--- /dev/null
+++ b/web/atoms/notebook/operations/execution-ops.ts
@@ -0,0 +1,144 @@
+import * as Y from 'yjs';
+import type { YNotebook, YCell, CellModel } from '@/modules/notebook/collab/yjs/schema/core/types';
+import {
+ startExecuteCell,
+ applyExecuteResultForCurrentRun,
+ getOutputEntry,
+} from '@/modules/notebook/collab/yjs/schema';
+import {
+ NB_CELL_MAP,
+ NB_OUTPUTS,
+ CELL_KIND,
+ CELL_SOURCE,
+ CELL_META,
+} from '@/modules/notebook/collab/yjs/schema/core/keys';
+import { EXECUTION_ORIGIN } from '@/modules/notebook/collab/yjs/schema';
+import { DefaultService } from '@/api-gen/services/DefaultService';
+import { type QueryResponse } from '@/api-gen';
+import { resolveErrorMessage } from '@/lib/errors';
+
+function errorResponse(message: string): QueryResponse {
+ return {
+ columns: [],
+ rows: [],
+ rowsAffected: 0,
+ error: message,
+ };
+}
+
+export async function executeCell(
+ root: YNotebook,
+ cellId: string,
+ options: { databaseId: number; executedBy?: number }
+): Promise {
+ const cellMap = root.get(NB_CELL_MAP) as Y.Map | undefined;
+ if (!cellMap) {
+ throw new Error('Cell map not found in notebook');
+ }
+
+ const cell = cellMap.get(cellId);
+ if (!cell) {
+ throw new Error(`Cell ${cellId} not found`);
+ }
+
+ // Check cell kind
+ const kind = cell.get(CELL_KIND) as CellModel['kind'] | undefined;
+ if (kind !== 'sql') {
+ throw new Error('Only SQL cells can be executed');
+ }
+
+ // Check if already running
+ const existing = getOutputEntry(root, cellId);
+ if (existing?.get('running') === true) {
+ throw new Error('Cell is already running');
+ }
+
+ // Get source code
+ const sourceText = cell.get(CELL_SOURCE) as Y.Text | undefined;
+ const source = sourceText?.toString() ?? '';
+ const trimmed = source.trim();
+
+ if (trimmed.length === 0) {
+ // Empty query - mark as failed
+ startExecuteCell(root, cellId, { executedBy: options.executedBy });
+ applyExecuteResultForCurrentRun(root, cellId, errorResponse('Query is empty'));
+ throw new Error('Query is empty');
+ }
+
+ // Get metadata
+ const meta = cell.get(CELL_META) as Y.Map | undefined;
+ const backgroundDDL = meta?.get('backgroundDDL') === true;
+
+ // Start execution
+ startExecuteCell(root, cellId, { executedBy: options.executedBy });
+
+ try {
+ // Execute query
+ const result = await DefaultService.queryDatabase(options.databaseId, {
+ query: trimmed,
+ backgroundDDL,
+ });
+
+ // Apply result
+ applyExecuteResultForCurrentRun(root, cellId, result);
+ } catch (error) {
+ // Apply error
+ const message = resolveErrorMessage(error, 'Failed to execute query');
+ applyExecuteResultForCurrentRun(root, cellId, errorResponse(message));
+ throw error; // Re-throw for caller to handle
+ }
+}
+
+export async function executeCells(
+ root: YNotebook,
+ cellIds: string[],
+ options: { databaseId: number; stopOnError?: boolean; executedBy?: number }
+): Promise> {
+ const { databaseId, stopOnError = false, executedBy } = options;
+ const results: Array<{ cellId: string; success: boolean; error?: string }> = [];
+
+ for (const cellId of cellIds) {
+ try {
+ await executeCell(root, cellId, { databaseId, executedBy });
+ results.push({ cellId, success: true });
+ } catch (error) {
+ const message = resolveErrorMessage(error, 'Execution failed');
+ results.push({ cellId, success: false, error: message });
+
+ if (stopOnError) {
+ break;
+ }
+ }
+ }
+
+ return results;
+}
+
+export function clearOutputs(root: YNotebook): void {
+ const doc = root.doc as Y.Doc | undefined;
+
+ const apply = () => {
+ const outputs = root.get(NB_OUTPUTS) as Y.Map> | undefined;
+ if (!outputs) return;
+
+ outputs.forEach((entry, key) => {
+ const isRunning = entry.get('running') === true;
+ if (isRunning) {
+ // Preserve active runs; drop any prior results and stale flags
+ entry.delete('result');
+ entry.delete('completedAt');
+ entry.set('stale', false);
+ } else {
+ // Remove completed outputs
+ outputs.delete(String(key));
+ }
+ });
+ };
+
+ // Use transaction if doc available
+ if (doc) {
+ doc.transact(apply, EXECUTION_ORIGIN);
+ } else {
+ apply();
+ }
+}
diff --git a/web/atoms/notebook/operations/index.ts b/web/atoms/notebook/operations/index.ts
new file mode 100644
index 00000000..a3bccd00
--- /dev/null
+++ b/web/atoms/notebook/operations/index.ts
@@ -0,0 +1,3 @@
+export * from './cell-ops';
+export * from './execution-ops';
+export * from './metadata-ops';
diff --git a/web/atoms/notebook/operations/metadata-ops.ts b/web/atoms/notebook/operations/metadata-ops.ts
new file mode 100644
index 00000000..d38a2d21
--- /dev/null
+++ b/web/atoms/notebook/operations/metadata-ops.ts
@@ -0,0 +1,68 @@
+import * as Y from 'yjs';
+import type { YNotebook, YCell } from '@/modules/notebook/collab/yjs/schema/core/types';
+import { NB_CELL_MAP, NB_METADATA, CELL_META } from '@/modules/notebook/collab/yjs/schema/core/keys';
+
+export function updateCellMetadata(
+ root: YNotebook,
+ cellId: string,
+ metadata: Record
+): void {
+ const cellMap = root.get(NB_CELL_MAP) as Y.Map | undefined;
+ if (!cellMap) {
+ throw new Error('Cell map not found in notebook');
+ }
+
+ const cell = cellMap.get(cellId);
+ if (!cell) {
+ throw new Error(`Cell ${cellId} not found`);
+ }
+
+ const doc = cell.doc as Y.Doc | undefined;
+
+ const apply = () => {
+ let metaMap = cell.get(CELL_META) as Y.Map | undefined;
+ if (!metaMap) {
+ metaMap = new Y.Map();
+ cell.set(CELL_META, metaMap);
+ }
+
+ // Merge metadata
+ for (const [key, value] of Object.entries(metadata)) {
+ metaMap.set(key, value);
+ }
+ };
+
+ // Use transaction if doc available
+ if (doc) {
+ doc.transact(apply);
+ } else {
+ apply();
+ }
+}
+
+export function updateNotebookMetadata(
+ root: YNotebook,
+ metadata: Record
+): void {
+ const doc = root.doc as Y.Doc | undefined;
+
+ const apply = () => {
+ let metaMap = root.get(NB_METADATA) as Y.Map | undefined;
+ if (!metaMap) {
+ metaMap = new Y.Map();
+ root.set(NB_METADATA, metaMap);
+ }
+
+ // Merge metadata
+ for (const [key, value] of Object.entries(metadata)) {
+ metaMap.set(key, value);
+ }
+ };
+
+ // Use transaction if doc available
+ if (doc) {
+ doc.transact(apply);
+ } else {
+ apply();
+ }
+}
diff --git a/web/atoms/notebook/save-status.ts b/web/atoms/notebook/save-status.ts
new file mode 100644
index 00000000..6af18016
--- /dev/null
+++ b/web/atoms/notebook/save-status.ts
@@ -0,0 +1,58 @@
+import { proxy, useSnapshot } from 'valtio'
+
+export type SaveStatus = 'saved' | 'saving' | 'unsaved'
+
+export interface NotebookSaveState {
+ /** Current save status per notebook */
+ status: Record
+ /** Timestamp of last successful save per notebook */
+ lastSavedAt: Record
+}
+
+const defaultSaveState: NotebookSaveState = {
+ status: {},
+ lastSavedAt: {},
+}
+
+export const notebookSaveState = proxy(defaultSaveState)
+
+export const notebookSaveActions = {
+ setStatus(notebookId: string, status: SaveStatus) {
+ notebookSaveState.status[notebookId] = status
+ if (status === 'saved') {
+ notebookSaveState.lastSavedAt[notebookId] = Date.now()
+ }
+ },
+ markUnsaved(notebookId: string) {
+ if (notebookSaveState.status[notebookId] !== 'saving') {
+ notebookSaveState.status[notebookId] = 'unsaved'
+ }
+ },
+ markSaving(notebookId: string) {
+ notebookSaveState.status[notebookId] = 'saving'
+ },
+ markSaved(notebookId: string) {
+ notebookSaveState.status[notebookId] = 'saved'
+ notebookSaveState.lastSavedAt[notebookId] = Date.now()
+ },
+ cleanup(notebookId: string) {
+ delete notebookSaveState.status[notebookId]
+ delete notebookSaveState.lastSavedAt[notebookId]
+ },
+} as const
+
+export const useNotebookSaveState = () => useSnapshot(notebookSaveState)
+
+export const useNotebookSaveStatus = (notebookId: string): SaveStatus => {
+ const state = useNotebookSaveState()
+ return state.status[notebookId] ?? 'saved'
+}
+
+export const useNotebookLastSavedAt = (notebookId: string): number | null => {
+ const state = useNotebookSaveState()
+ return state.lastSavedAt[notebookId] ?? null
+}
+
+export const getNotebookSaveStatus = (notebookId: string): SaveStatus => {
+ return notebookSaveState.status[notebookId] ?? 'saved'
+}
diff --git a/web/atoms/notebook/ui.ts b/web/atoms/notebook/ui.ts
new file mode 100644
index 00000000..3aac57e2
--- /dev/null
+++ b/web/atoms/notebook/ui.ts
@@ -0,0 +1,137 @@
+import { useSnapshot } from 'valtio'
+
+import { proxyWithLocalStorage } from '@/lib/state/proxy-with-local-storage'
+
+export type NotebookBottomPanelTab =
+ | 'streaming-graph'
+ | 'history'
+ | 'export'
+ | 'progress'
+
+export type NotebookSidebarTab = 'notebooks' | 'schema'
+
+export type CellEditorMode = 'editor' | 'preview'
+
+export interface NotebookBottomPanelState {
+ isOpen: boolean
+ activeTab: NotebookBottomPanelTab
+}
+
+export interface NotebookSidebarState {
+ activeTab: NotebookSidebarTab
+ schemaExpandedNodes: Record
+ schemaSearchQuery: string
+}
+
+export interface NotebookUIState {
+ bottomPanel: NotebookBottomPanelState
+ sidebar: NotebookSidebarState
+ cellEditorModes: Record>
+}
+
+const NOTEBOOK_UI_STORAGE_KEY = 'notebook-ui-state'
+
+const defaultNotebookUIState: NotebookUIState = {
+ bottomPanel: {
+ isOpen: false,
+ activeTab: 'history',
+ },
+ sidebar: {
+ activeTab: 'notebooks',
+ schemaExpandedNodes: {},
+ schemaSearchQuery: '',
+ },
+ cellEditorModes: {},
+}
+
+export const notebookUIState = proxyWithLocalStorage({
+ key: NOTEBOOK_UI_STORAGE_KEY,
+ defaultState: defaultNotebookUIState,
+ persistKeys: ['bottomPanel', 'sidebar'],
+})
+
+const ensureNotebookEditorModes = (notebookId: string) => {
+ if (!notebookId) return null
+ if (!notebookUIState.cellEditorModes[notebookId]) {
+ notebookUIState.cellEditorModes[notebookId] = {}
+ }
+ return notebookUIState.cellEditorModes[notebookId]
+}
+
+export const notebookUIActions = {
+ setBottomPanel(updates: Partial) {
+ Object.assign(notebookUIState.bottomPanel, updates)
+ },
+ toggleBottomPanel() {
+ notebookUIState.bottomPanel.isOpen = !notebookUIState.bottomPanel.isOpen
+ },
+ openBottomPanel(tab?: NotebookBottomPanelTab) {
+ notebookUIState.bottomPanel.isOpen = true
+ if (tab) {
+ notebookUIState.bottomPanel.activeTab = tab
+ }
+ },
+ closeBottomPanel() {
+ notebookUIState.bottomPanel.isOpen = false
+ },
+ setActiveBottomPanelTab(tab: NotebookBottomPanelTab) {
+ notebookUIState.bottomPanel.activeTab = tab
+ },
+ setCellEditorMode(notebookId: string, cellId: string, mode: CellEditorMode) {
+ const modes = ensureNotebookEditorModes(notebookId)
+ if (!modes) return
+ modes[cellId] = mode
+ },
+ toggleCellEditorMode(notebookId: string, cellId: string) {
+ const modes = ensureNotebookEditorModes(notebookId)
+ if (!modes) return
+ const current = modes[cellId] ?? 'preview'
+ modes[cellId] = current === 'editor' ? 'preview' : 'editor'
+ },
+ removeCellEditorMode(notebookId: string, cellId: string) {
+ const notebookModes = notebookUIState.cellEditorModes[notebookId]
+ if (!notebookModes || !(cellId in notebookModes)) return
+ delete notebookModes[cellId]
+ },
+ resetCellEditorModes(notebookId: string) {
+ if (!notebookId) return
+ delete notebookUIState.cellEditorModes[notebookId]
+ },
+ // Sidebar actions
+ setSidebarTab(tab: NotebookSidebarTab) {
+ notebookUIState.sidebar.activeTab = tab
+ },
+ toggleSchemaNode(nodeId: string) {
+ const current = notebookUIState.sidebar.schemaExpandedNodes[nodeId] ?? false
+ notebookUIState.sidebar.schemaExpandedNodes[nodeId] = !current
+ },
+ setSchemaNodeExpanded(nodeId: string, expanded: boolean) {
+ notebookUIState.sidebar.schemaExpandedNodes[nodeId] = expanded
+ },
+ setSchemaSearchQuery(query: string) {
+ notebookUIState.sidebar.schemaSearchQuery = query
+ },
+ expandAllSchemaNodes(nodeIds: string[]) {
+ nodeIds.forEach((id) => {
+ notebookUIState.sidebar.schemaExpandedNodes[id] = true
+ })
+ },
+ collapseAllSchemaNodes() {
+ notebookUIState.sidebar.schemaExpandedNodes = {}
+ },
+} as const
+
+export const useNotebookUIState = () => useSnapshot(notebookUIState)
+
+export const useNotebookBottomPanelState = () =>
+ useNotebookUIState().bottomPanel
+
+export const useNotebookSidebarState = () => useNotebookUIState().sidebar
+
+export const getNotebookUIState = (): NotebookUIState => notebookUIState
+
+export const getCellEditorMode = (
+ notebookId: string,
+ cellId: string,
+): CellEditorMode =>
+ notebookUIState.cellEditorModes[notebookId]?.[cellId] ?? 'preview'
diff --git a/web/components/common/MarkdownRenderer.tsx b/web/components/common/MarkdownRenderer.tsx
new file mode 100644
index 00000000..1ca5a42f
--- /dev/null
+++ b/web/components/common/MarkdownRenderer.tsx
@@ -0,0 +1,138 @@
+'use client'
+
+import { memo, useMemo, useState, useEffect } from 'react'
+import { unified } from 'unified'
+import remarkParse from 'remark-parse'
+import remarkRehype from 'remark-rehype'
+// import rehypeShiki from '@shikijs/rehype'
+import rehypeStringify from 'rehype-stringify'
+import { visit } from 'unist-util-visit'
+import type { Element } from 'hast'
+import { cn } from '@/lib/utils'
+
+interface MarkdownRendererProps {
+ content: string
+ className?: string
+ /** Cell ID used for generating heading IDs for outline navigation */
+ cellId?: string
+ // 可选的 Shiki 配置
+ themes?: {
+ light: string
+ dark: string
+ }
+ // 是否支持内联代码高亮
+ enableInlineHighlight?: boolean
+}
+
+/**
+ * Rehype plugin to add data-heading-id attributes to heading elements.
+ * This enables the floating outline to track and scroll to headings.
+ */
+function rehypeHeadingIds(cellId: string) {
+ return () => {
+ // headingIndex is reset each time the plugin runs (per process call)
+ return (tree: any) => {
+ let headingIndex = 0
+ visit(tree, 'element', (node: Element) => {
+ if (['h1', 'h2', 'h3', 'h4', 'h5', 'h6'].includes(node.tagName)) {
+ node.properties = node.properties || {}
+ node.properties['data-heading-id'] = `${cellId}-h-${headingIndex++}`
+ }
+ })
+ }
+ }
+}
+
+const MarkdownRenderer = memo(function MarkdownRenderer({
+ content,
+ className,
+ cellId,
+}: MarkdownRendererProps) {
+ const [processedContent, setProcessedContent] = useState('')
+ const [isLoading, setIsLoading] = useState(true)
+ const [lastContent, setLastContent] = useState('')
+ const [lastCellId, setLastCellId] = useState(undefined)
+
+ // 创建 unified 处理器，使用 useMemo 避免重复创建
+ // Recreate processor when cellId changes to ensure correct heading IDs
+ const processor = useMemo(() => {
+ const p = unified()
+ .use(remarkParse) // 解析 Markdown
+ .use(remarkRehype) // 转换为 HTML AST
+
+ // Add heading ID plugin only if cellId is provided
+ if (cellId) {
+ p.use(rehypeHeadingIds(cellId))
+ }
+
+ // .use(rehypeShiki, {
+ // themes,
+ // inline: enableInlineHighlight ? 'tailing-curly-colon' : false,
+ // defaultColor: 'light-dark()',
+ // })
+ return p.use(rehypeStringify) // 转换为 HTML 字符串
+ }, [cellId])
+
+ // 处理 Markdown 内容
+ useEffect(() => {
+ // 如果内容和 cellId 都没有变化，避免重新处理
+ if (content === lastContent && cellId === lastCellId && processedContent) {
+ return
+ }
+
+ let isCancelled = false
+
+ const processContent = async () => {
+ try {
+ setIsLoading(true)
+ const result = await processor.process(content)
+ const html = result.toString()
+
+ if (!isCancelled) {
+ setProcessedContent(html)
+ setLastContent(content)
+ setLastCellId(cellId)
+ }
+ } catch (error) {
+ console.error('Markdown processing error:', error)
+ if (!isCancelled) {
+ setProcessedContent(content) // 降级到原始内容
+ setLastContent(content)
+ setLastCellId(cellId)
+ }
+ } finally {
+ if (!isCancelled) {
+ setIsLoading(false)
+ }
+ }
+ }
+
+ processContent()
+
+ return () => {
+ isCancelled = true
+ }
+ }, [processor, content, lastContent, processedContent, cellId, lastCellId])
+
+ if (isLoading) {
+ return (
+
+ )
+ }
+
+ return (
+
+ )
+})
+
+export { MarkdownRenderer }
\ No newline at end of file
diff --git a/web/components/common/app-sidebar.tsx b/web/components/common/app-sidebar.tsx
index 478e3189..d903c207 100644
--- a/web/components/common/app-sidebar.tsx
+++ b/web/components/common/app-sidebar.tsx
@@ -13,6 +13,7 @@ import {
Code,
Moon,
Sun,
+ NotebookPen,
} from "lucide-react"
import Link from "next/link"
import Image from "next/image"
@@ -48,6 +49,11 @@ const mainMenuItems = [
href: "/sqlconsole",
icon: Code,
},
+ {
+ title: "Notebook",
+ href: "/notebook",
+ icon: NotebookPen,
+ },
{
title: "Metrics Store",
href: "/metricsstore",
diff --git a/web/components/ui/avatar.tsx b/web/components/ui/avatar.tsx
new file mode 100644
index 00000000..51e507ba
--- /dev/null
+++ b/web/components/ui/avatar.tsx
@@ -0,0 +1,50 @@
+"use client"
+
+import * as React from "react"
+import * as AvatarPrimitive from "@radix-ui/react-avatar"
+
+import { cn } from "@/lib/utils"
+
+const Avatar = React.forwardRef<
+ React.ElementRef,
+ React.ComponentPropsWithoutRef
+>(({ className, ...props }, ref) => (
+
+))
+Avatar.displayName = AvatarPrimitive.Root.displayName
+
+const AvatarImage = React.forwardRef<
+ React.ElementRef,
+ React.ComponentPropsWithoutRef
+>(({ className, ...props }, ref) => (
+
+))
+AvatarImage.displayName = AvatarPrimitive.Image.displayName
+
+const AvatarFallback = React.forwardRef<
+ React.ElementRef,
+ React.ComponentPropsWithoutRef
+>(({ className, ...props }, ref) => (
+
+))
+AvatarFallback.displayName = AvatarPrimitive.Fallback.displayName
+
+export { Avatar, AvatarImage, AvatarFallback }
diff --git a/web/components/ui/monaco-editor.tsx b/web/components/ui/monaco-editor.tsx
new file mode 100644
index 00000000..04f667c8
--- /dev/null
+++ b/web/components/ui/monaco-editor.tsx
@@ -0,0 +1,178 @@
+"use client";
+
+import { memo, useRef, useCallback, useImperativeHandle, useEffect, useState } from "react";
+import Editor, { OnMount, OnChange } from "@monaco-editor/react";
+import { cn } from "@/lib/utils";
+import type { editor } from "monaco-editor";
+import { useIsDark } from "@/hooks/useIsDark";
+
+interface MonacoEditorProps {
+ // value?: string;
+ defaultValue?: string;
+ language?: string;
+ onChange?: (value: string) => void;
+ onMount?: (editor: editor.IStandaloneCodeEditor) => void;
+ onReady?: (editor: editor.IStandaloneCodeEditor) => void;
+ placeholder?: string;
+ height?: string | number;
+ className?: string;
+ options?: editor.IStandaloneEditorConstructionOptions;
+ readOnly?: boolean;
+ autoResize?: boolean;
+ minHeight?: number;
+ maxHeight?: number;
+ ref?: React.Ref;
+}
+
+interface MonacoEditorHandle {
+ focus: () => void;
+ getValue: () => string;
+ setValue: (value: string) => void;
+ getEditor: () => editor.IStandaloneCodeEditor | null;
+}
+
+const MonacoEditor = memo(function MonacoEditor({
+ // value,
+ defaultValue,
+ language = "sql",
+ onChange,
+ onMount,
+ onReady,
+ height = 200,
+ className,
+ options,
+ readOnly = false,
+ autoResize = false,
+ minHeight = 100,
+ maxHeight = 600,
+ ref,
+}: MonacoEditorProps) {
+ const isDark = useIsDark();
+ const editorRef = useRef(null);
+ const [editorHeight, setEditorHeight] = useState(
+ typeof height === 'number' ? height : 200
+ );
+
+ useEffect(() => {
+ return () => {
+ // Cleanup editor instance when component unmounts
+ if (editorRef.current) {
+ editorRef.current.dispose();
+ editorRef.current = null;
+ }
+ };
+ }, []);
+
+ const updateHeight = useCallback(() => {
+ if (!autoResize || !editorRef.current) return;
+
+ const contentHeight = editorRef.current.getContentHeight();
+ const newHeight = Math.max(minHeight, Math.min(contentHeight, maxHeight));
+
+ if (newHeight !== editorHeight) {
+ setEditorHeight(newHeight);
+ editorRef.current.layout();
+ }
+ }, [autoResize, editorHeight, minHeight, maxHeight]);
+
+ useEffect(() => {
+ if (autoResize && editorRef.current) {
+ // Update height when value changes
+ updateHeight();
+
+ // Listen to content size changes
+ const disposable = editorRef.current.onDidContentSizeChange(() => {
+ updateHeight();
+ });
+
+ return () => {
+ disposable.dispose();
+ };
+ }
+ }, [autoResize, updateHeight]);
+
+ const handleEditorDidMount: OnMount = useCallback(
+ (editor) => {
+ editorRef.current = editor;
+
+ if (autoResize) {
+ // Initial height update
+ updateHeight();
+
+ // Listen to content size changes
+ editor.onDidContentSizeChange(() => {
+ updateHeight();
+ });
+ }
+
+ onMount?.(editor);
+ onReady?.(editor);
+ },
+ [onMount, onReady, autoResize, updateHeight]
+ );
+
+ const handleEditorChange: OnChange = useCallback(
+ (newValue) => {
+ onChange?.(newValue || "");
+ },
+ [onChange]
+ );
+
+ useImperativeHandle(
+ ref,
+ () => ({
+ focus: () => editorRef.current?.focus(),
+ getValue: () => editorRef.current?.getValue() || "",
+ setValue: (newValue: string) => editorRef.current?.setValue(newValue),
+ getEditor: () => editorRef.current,
+ }),
+ []
+ );
+
+ const defaultOptions: editor.IStandaloneEditorConstructionOptions = {
+ minimap: { enabled: false },
+ lineNumbers: "on",
+ fontSize: 14,
+ tabSize: 2,
+ insertSpaces: true,
+ wordWrap: "on",
+ folding: false,
+ renderLineHighlight: "all",
+ smoothScrolling: true,
+ cursorBlinking: "smooth",
+ suggestOnTriggerCharacters: true,
+ quickSuggestions: true,
+ parameterHints: { enabled: true },
+ autoClosingBrackets: "always",
+ autoClosingQuotes: "always",
+ bracketPairColorization: { enabled: true },
+ readOnly,
+ scrollbar: {
+ handleMouseWheel: !autoResize,
+ },
+ scrollBeyondLastLine: !autoResize,
+ ...options,
+ };
+
+ return (
+
+ }
+ />
+
+ );
+});
+
+export { MonacoEditor };
+export type { MonacoEditorHandle, MonacoEditorProps };
diff --git a/web/components/ui/shiki/ShikiCodeBlock.tsx b/web/components/ui/shiki/ShikiCodeBlock.tsx
new file mode 100644
index 00000000..0415e1ac
--- /dev/null
+++ b/web/components/ui/shiki/ShikiCodeBlock.tsx
@@ -0,0 +1,137 @@
+"use client";
+
+import { cn } from "@/lib/utils";
+import { Suspense, useRef } from "react";
+import type { BundledLanguage } from "shiki";
+import { useShiki } from "./use-shiki";
+import { useIsDark } from "@/hooks/useIsDark";
+
+interface ShikiCodeBlockProps {
+ value: string;
+ language?: BundledLanguage;
+ className?: string;
+ title?: string;
+ copyable?: boolean;
+ onDoubleClick?: () => void;
+ emptyText?: string;
+}
+
+function HighlightedCode({
+ value,
+ language,
+ isDark,
+ emptyText,
+}: {
+ value: string;
+ language: BundledLanguage;
+ isDark: boolean;
+ emptyText: string;
+}) {
+ const trimmedValue = value.trim();
+
+ const theme = isDark ? "dark-plus" : "light-plus";
+
+ const highlighted = useShiki(
+ trimmedValue ? value : " ",
+ {
+ lang: language,
+ theme,
+ engine: "oniguruma",
+ },
+ [value, language, theme] // Cache key dependencies
+ );
+
+ if (!trimmedValue) {
+ return (
+
{emptyText}
+ );
+ }
+
+ return <>{highlighted};
+}
+
+export function ShikiCodeBlock({
+ value,
+ language = "sql",
+ className,
+ title,
+ onDoubleClick,
+ emptyText = "Empty content",
+}: ShikiCodeBlockProps) {
+ const containerRef = useRef
(null);
+ const isDark = useIsDark();
+
+ const fallback = (
+
+ {value || emptyText}
+
+ );
+
+ // If no title provided, render minimal version
+ if (!title) {
+ return (
+ pre]:!bg-transparent [&>pre]:h-full [&>pre]:overflow-auto [&>pre]:text-sm [&>pre]:leading-relaxed [&>pre]:whitespace-pre-wrap [&>pre]:break-words [&_.shiki-pre]:bg-transparent [&_.shiki-pre]:p-3 [&_.shiki-pre]:pt-2 [&_.shiki-pre]:font-mono [&_.shiki-code]:font-mono",
+ className
+ )}
+ onDoubleClick={onDoubleClick}
+ ref={containerRef}
+ >
+
+
+
+
+ );
+ }
+
+ // Full version with title and optional copy functionality
+ return (
+
+
+
{title}
+
+
+
+
+
+ {value || emptyText}
+
+
+ }
+ >
+
+
+
+
+