@usesidekick/react 0.1.0

package/src/provider.tsx

@@ -0,0 +1,1264 @@
+'use client';
+
+import React, { ReactNode, useCallback, useEffect, useMemo, useState, useRef, ComponentType } from 'react';
+import { createPortal } from 'react-dom';
+import { SidekickContext, SidekickContextValue } from './context';
+import { SidekickState, Override, SDK, AddedColumn, ColumnRename, ColumnOrder, HiddenColumn, RowFilter, WrappedComponent, InjectionPoint } from './types';
+import { loadFlags, setFlag as saveFlag, getFlag } from './flags';
+import { getRegisteredOverrides } from './loader';
+import { createUIPrimitives } from './primitives/ui';
+import { createDataPrimitives } from './primitives/data';
+import { createBehaviorPrimitives } from './primitives/behavior';
+import { fetchAndCompileOverrides } from './runtime-loader';
+import { configureJsxRuntime } from './jsx-runtime';
+import { configureJsxDevRuntime } from './jsx-dev-runtime';
+
+interface SidekickProviderProps {
+  children: ReactNode;
+  /** API endpoint to fetch overrides from (for production/DB-backed overrides) */
+  overridesEndpoint?: string;
+}
+
+/**
+ * Convert a kebab-case table ID to PascalCase component name.
+ * e.g., 'task-table' -> 'TaskTable'
+ */
+function tableIdToComponentName(tableId: string): string {
+  return tableId
+    .split('-')
+    .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('');
+}
+
+/**
+ * Creates a wrapper component that auto-injects added columns into a table
+ * via DOM manipulation + React portals. This allows addColumn() to work
+ * without the target component needing any Sidekick awareness.
+ */
+function createAutoColumnWrapper(
+  columns: AddedColumn[],
+  renames: ColumnRename[],
+  columnOrder?: ColumnOrder,
+  hiddenColumns?: HiddenColumn[],
+  rowFilters?: RowFilter[]
+): (Original: ComponentType) => ComponentType {
+  return (Original: ComponentType) => {
+    function AutoColumnInjector(props: Record<string, unknown>) {
+      const containerRef = useRef<HTMLDivElement>(null);
+      const [cellTargets, setCellTargets] = useState<Array<{ element: HTMLElement; taskIndex: number; colIndex: number }>>([]);
+      const allTasks = (props.tasks || []) as Record<string, unknown>[];
+
+      // Apply row filters to tasks before rendering
+      const tasks = useMemo(() => {
+        if (!rowFilters || rowFilters.length === 0) return allTasks;
+        return allTasks.filter(row =>
+          rowFilters.every(rf => rf.filter(row))
+        );
+      }, [allTasks]);
+
+      // Inject column headers and cell containers into the DOM
+      useEffect(() => {
+        const container = containerRef.current;
+        if (!container) return;
+        const table = container.querySelector('table');
+        if (!table) return;
+
+        // Clean up any previously injected elements
+        table.querySelectorAll('[data-sidekick-injected]').forEach(el => el.remove());
+        // Reset hidden columns from previous runs
+        table.querySelectorAll('[data-sidekick-hidden]').forEach(el => {
+          (el as HTMLElement).style.display = '';
+          el.removeAttribute('data-sidekick-hidden');
+        });
+
+        // Apply column renames to existing headers
+        if (renames.length > 0) {
+          const headers = table.querySelectorAll('thead th');
+          headers.forEach(th => {
+            const text = th.textContent?.trim();
+            if (text) {
+              const rename = renames.find(r => r.originalHeader === text);
+              if (rename) {
+                th.textContent = rename.newHeader;
+              }
+            }
+          });
+        }
+
+        // Reorder columns if a column order is specified
+        if (columnOrder) {
+          const headerRow = table.querySelector('thead tr');
+          if (headerRow) {
+            const ths = Array.from(headerRow.querySelectorAll('th'));
+            // Build mapping: header text -> original index
+            const headerToIndex = new Map<string, number>();
+            ths.forEach((th, i) => {
+              const text = th.textContent?.trim() ?? '';
+              headerToIndex.set(text, i);
+            });
+
+            // Build sorted index order: ordered headers first, then remaining in original order
+            const orderedIndices: number[] = [];
+            const usedIndices = new Set<number>();
+            for (const headerName of columnOrder.order) {
+              const idx = headerToIndex.get(headerName);
+              if (idx !== undefined) {
+                orderedIndices.push(idx);
+                usedIndices.add(idx);
+              }
+            }
+            // Append remaining columns in their original order
+            for (let i = 0; i < ths.length; i++) {
+              if (!usedIndices.has(i)) {
+                orderedIndices.push(i);
+              }
+            }
+
+            // Reorder thead ths
+            const sortedThs = orderedIndices.map(i => ths[i]);
+            for (const th of sortedThs) {
+              headerRow.appendChild(th);
+            }
+
+            // Reorder tbody tds to match
+            const bodyRows = table.querySelectorAll('tbody tr');
+            bodyRows.forEach(row => {
+              const tds = Array.from(row.querySelectorAll('td'));
+              const sortedTds = orderedIndices.map(i => tds[i]).filter(Boolean);
+              for (const td of sortedTds) {
+                row.appendChild(td);
+              }
+            });
+          }
+        }
+
+        // Hide columns
+        if (hiddenColumns && hiddenColumns.length > 0) {
+          const headers = table.querySelectorAll('thead th');
+          const hiddenHeaders = new Set(hiddenColumns.map(h => h.header));
+          const hiddenIndices = new Set<number>();
+
+          headers.forEach((th, i) => {
+            const text = th.textContent?.trim() ?? '';
+            if (hiddenHeaders.has(text)) {
+              (th as HTMLElement).style.display = 'none';
+              th.setAttribute('data-sidekick-hidden', 'true');
+              hiddenIndices.add(i);
+            }
+          });
+
+          if (hiddenIndices.size > 0) {
+            const bodyRows = table.querySelectorAll('tbody tr');
+            bodyRows.forEach(row => {
+              const tds = row.querySelectorAll('td');
+              tds.forEach((td, i) => {
+                if (hiddenIndices.has(i)) {
+                  (td as HTMLElement).style.display = 'none';
+                  td.setAttribute('data-sidekick-hidden', 'true');
+                }
+              });
+            });
+          }
+        }
+
+        // Add column headers
+        const headerRow = table.querySelector('thead tr');
+        if (headerRow) {
+          for (const col of columns) {
+            const th = document.createElement('th');
+            th.className = 'px-6 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider';
+            th.textContent = col.header;
+            th.setAttribute('data-sidekick-injected', 'true');
+            headerRow.appendChild(th);
+          }
+        }
+
+        // Add cell containers to each body row
+        const bodyRows = table.querySelectorAll('tbody tr');
+        const targets: Array<{ element: HTMLElement; taskIndex: number; colIndex: number }> = [];
+        bodyRows.forEach((row, rowIndex) => {
+          for (let colIndex = 0; colIndex < columns.length; colIndex++) {
+            const td = document.createElement('td');
+            td.className = 'px-6 py-4 whitespace-nowrap text-sm text-gray-500';
+            td.setAttribute('data-sidekick-injected', 'true');
+            row.appendChild(td);
+            targets.push({ element: td, taskIndex: rowIndex, colIndex });
+          }
+        });
+
+        setCellTargets(targets);
+
+        return () => {
+          table.querySelectorAll('[data-sidekick-injected]').forEach(el => el.remove());
+          table.querySelectorAll('[data-sidekick-hidden]').forEach(el => {
+            (el as HTMLElement).style.display = '';
+            el.removeAttribute('data-sidekick-hidden');
+          });
+          setCellTargets([]);
+        };
+      }, [tasks]);
+
+      // Render the original component with filtered tasks, then portal cell content into injected TDs
+      const filteredProps = (rowFilters && rowFilters.length > 0)
+        ? { ...props, tasks }
+        : props;
+      return React.createElement(React.Fragment, null,
+        React.createElement('div', { ref: containerRef },
+          React.createElement(Original, filteredProps as Record<string, unknown>)
+        ),
+        ...cellTargets.map((target, idx) => {
+          const task = tasks[target.taskIndex];
+          const col = columns[target.colIndex];
+          if (!task || !col) return null;
+
+          const accessor = col.accessor;
+          const value = typeof accessor === 'function'
+            ? accessor(task)
+            : task[accessor as string];
+
+          const content = col.render
+            ? col.render(value, task)
+            : React.createElement('span', null, String(value ?? '-'));
+
+          return createPortal(content, target.element, `sidekick-col-${idx}`);
+        })
+      );
+    }
+    AutoColumnInjector.displayName = `AutoColumnInjector(${(Original as { displayName?: string; name?: string }).displayName || (Original as { name?: string }).name || 'Component'})`;
+    return AutoColumnInjector as unknown as ComponentType;
+  };
+}
+
+/**
+ * Get a component's display name from its type (function, forwardRef, memo, lazy, etc.).
+ * Handles React.lazy types used by Next.js for client components referenced from server components.
+ */
+function getComponentName(type: unknown): string | null {
+  if (!type) return null;
+  if (typeof type === 'function') {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const fn = type as any;
+    return fn.displayName || fn.name || null;
+  }
+  if (typeof type === 'object' && type !== null) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const obj = type as any;
+    if (obj.displayName) return obj.displayName;
+    // React.lazy: { $$typeof: Symbol(react.lazy), _payload, _init }
+    // When resolved, _payload.status === 'fulfilled' and _payload.value is the actual component
+    if (obj.$$typeof?.toString() === 'Symbol(react.lazy)') {
+      const payload = obj._payload;
+      if (payload && payload.status === 'fulfilled' && payload.value) {
+        return getComponentName(payload.value);
+      }
+    }
+    if (obj.$$typeof) {
+      if (obj.type) return getComponentName(obj.type);
+      if (obj.render) return getComponentName(obj.render);
+    }
+  }
+  return null;
+}
+
+/**
+ * Recursively walk a React element tree and apply wrappers/replacements
+ * to any component types that match registered overrides.
+ *
+ * This handles components whose JSX callsite is in a server component
+ * (and therefore bypasses the custom JSX runtime interception).
+ * The SidekickProvider is a client component, so it receives the
+ * server-rendered element tree as `children` — we transform it here
+ * before React renders it.
+ */
+function transformElementTree(
+  node: ReactNode,
+  wrappers: Map<string, WrappedComponent[]>,
+  replacements: Map<string, ComponentType>,
+  wrapCache: Map<unknown, ComponentType>
+): ReactNode {
+  if (node == null || typeof node === 'boolean' || typeof node === 'string' || typeof node === 'number') {
+    return node;
+  }
+
+  if (Array.isArray(node)) {
+    let changed = false;
+    const result = node.map(child => {
+      const transformed = transformElementTree(child, wrappers, replacements, wrapCache);
+      if (transformed !== child) changed = true;
+      return transformed;
+    });
+    return changed ? result : node;
+  }
+
+  if (!React.isValidElement(node)) return node;
+
+  const element = node;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const originalType = element.type as any;
+  let newType = originalType;
+  let typeChanged = false;
+
+  // Check if this element's type is a component that should be wrapped/replaced
+  if (typeof originalType === 'function' || (typeof originalType === 'object' && originalType !== null)) {
+    const name = getComponentName(originalType);
+    if (name) {
+      // Resolve the actual component from lazy types for wrapping
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      let resolvedType: ComponentType = originalType as any;
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const maybeObj = originalType as any;
+      if (maybeObj.$$typeof?.toString() === 'Symbol(react.lazy)' &&
+          maybeObj._payload?.status === 'fulfilled' && maybeObj._payload?.value) {
+        resolvedType = maybeObj._payload.value;
+      }
+
+      const replacement = replacements.get(name);
+      if (replacement) {
+        newType = replacement;
+        typeChanged = true;
+      } else {
+        const componentWrappers = wrappers.get(name);
+        if (componentWrappers && componentWrappers.length > 0) {
+          // Cache wrapped types to keep referential identity stable across renders
+          if (!wrapCache.has(resolvedType)) {
+            const wrapped = componentWrappers.reduce(
+              (comp: ComponentType, { wrapper, where: wherePredicate }) => {
+                if (wherePredicate) {
+                  // Conditional wrapper: only apply when where(props) returns true
+                  const Wrapped = wrapper(comp);
+                  const ConditionalWrapper = (props: Record<string, unknown>) => {
+                    if (wherePredicate(props)) {
+                      return React.createElement(Wrapped, props);
+                    }
+                    return React.createElement(comp, props);
+                  };
+                  ConditionalWrapper.displayName = `ConditionalWrap(${(comp as unknown as { displayName?: string; name?: string }).displayName || (comp as unknown as { name?: string }).name || 'Component'})`;
+                  return ConditionalWrapper as unknown as ComponentType;
+                }
+                return wrapper(comp);
+              },
+              resolvedType
+            );
+            wrapCache.set(resolvedType, wrapped);
+          }
+          newType = wrapCache.get(resolvedType)!;
+          typeChanged = true;
+        }
+      }
+    }
+  }
+
+  // Recursively transform children prop
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const childrenProp = (element.props as any).children;
+  const transformedChildren = childrenProp != null
+    ? transformElementTree(childrenProp, wrappers, replacements, wrapCache)
+    : childrenProp;
+  const childrenChanged = transformedChildren !== childrenProp;
+
+  if (!typeChanged && !childrenChanged) return node;
+
+  // Rebuild the element with the new type and/or children
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const { children: _children, ...restProps } = element.props as any;
+  return React.createElement(
+    newType,
+    { ...restProps, key: element.key },
+    transformedChildren
+  );
+}
+
+function createInitialState(): SidekickState {
+  return {
+    overrides: [],
+    // UI state
+    wrappers: new Map(),
+    replacements: new Map(),
+    styles: [],
+    columns: new Map(),
+    columnRenames: new Map(),
+    hiddenColumns: new Map(),
+    columnOrders: new Map(),
+    rowFilters: new Map(),
+    menuItems: new Map(),
+    tabs: new Map(),
+    propsModifiers: new Map(),
+    actions: new Map(),
+    validations: new Map(),
+    // Data state
+    computedFields: new Map(),
+    filters: new Map(),
+    transforms: new Map(),
+    interceptors: [],
+    sortOptions: new Map(),
+    groupByOptions: new Map(),
+    // Behavior state
+    eventHandlers: new Map(),
+    keyboardShortcuts: [],
+    routeModifiers: [],
+    // DOM state
+    domModifications: [],
+    injections: [],
+    domEventListeners: [],
+  };
+}
+
+export function SidekickProvider({ children, overridesEndpoint }: SidekickProviderProps) {
+  const [state, setState] = useState<SidekickState>(createInitialState);
+  const [overrides, setOverrides] = useState<Override[]>([]);
+  const [isReady, setIsReady] = useState(false);
+
+  // Store refs for interceptor getters to avoid stale closures
+  const stateRef = useRef(state);
+  stateRef.current = state;
+
+  // Initialize overrides AND configure JSX runtime, then render children
+  useEffect(() => {
+    const initializeOverrides = async () => {
+      const newState = createInitialState();
+      const loadedOverrides: Override[] = [];
+
+      if (overridesEndpoint) {
+        // Load overrides from API
+        console.log('[Sidekick] Fetching overrides from:', overridesEndpoint);
+        const apiOverrides = await fetchAndCompileOverrides(overridesEndpoint);
+        console.log('[Sidekick] Fetched overrides:', apiOverrides.length);
+
+        for (const override of apiOverrides) {
+          loadedOverrides.push({
+            id: override.id,
+            name: override.name,
+            description: override.description,
+            version: '1.0.0',
+            enabled: override.enabled,
+          });
+
+          // Activate if enabled
+          if (override.enabled) {
+            console.log(`[Sidekick] Activating override: ${override.id}`);
+            const sdk: SDK = {
+              ui: createUIPrimitives(newState, override.id),
+              data: createDataPrimitives(newState, override.id),
+              behavior: createBehaviorPrimitives(newState, override.id),
+            };
+            try {
+              override.activate(sdk);
+              console.log(`[Sidekick] Activated override: ${override.id}`);
+            } catch (error) {
+              console.error(`[Sidekick] Failed to activate override ${override.id}:`, error);
+            }
+          }
+        }
+      } else {
+        // Load overrides from static registry (development mode)
+        const registeredOverrides = getRegisteredOverrides();
+        const flags = loadFlags();
+
+        for (const module of registeredOverrides) {
+          loadedOverrides.push({
+            id: module.manifest.id,
+            name: module.manifest.name,
+            description: module.manifest.description,
+            version: module.manifest.version,
+            enabled: flags[module.manifest.id] ?? false,
+          });
+        }
+
+        // Activate enabled overrides
+        for (const module of registeredOverrides) {
+          const isEnabled = flags[module.manifest.id] ?? false;
+          if (isEnabled) {
+            console.log(`[Sidekick] Activating override: ${module.manifest.id}`);
+            const sdk: SDK = {
+              ui: createUIPrimitives(newState, module.manifest.id),
+              data: createDataPrimitives(newState, module.manifest.id),
+              behavior: createBehaviorPrimitives(newState, module.manifest.id),
+            };
+            await module.activate(sdk);
+            console.log(`[Sidekick] After activation, wrappers:`, Array.from(newState.wrappers.keys()));
+          }
+        }
+      }
+
+      newState.overrides = loadedOverrides;
+
+      // Auto-create wrappers for tables with any modifications
+      // (added columns, renames, reorders, hidden columns, row filters)
+      // This enables addColumn/renameColumn/reorderColumns/hideColumn/filterRows to work
+      // without app components being Sidekick-aware
+      const tableIdsWithMods = new Set<string>();
+      for (const tableId of newState.columns.keys()) tableIdsWithMods.add(tableId);
+      for (const tableId of newState.columnRenames.keys()) tableIdsWithMods.add(tableId);
+      for (const tableId of newState.columnOrders.keys()) tableIdsWithMods.add(tableId);
+      for (const tableId of newState.hiddenColumns.keys()) tableIdsWithMods.add(tableId);
+      for (const tableId of newState.rowFilters.keys()) tableIdsWithMods.add(tableId);
+
+      for (const tableId of tableIdsWithMods) {
+        const cols = newState.columns.get(tableId) ?? [];
+        const tableRenames = newState.columnRenames.get(tableId) ?? [];
+        const tableOrder = newState.columnOrders.get(tableId);
+        const tableHidden = newState.hiddenColumns.get(tableId) ?? [];
+        const tableRowFilters = newState.rowFilters.get(tableId) ?? [];
+
+        // Skip if there are truly no modifications
+        if (cols.length === 0 && tableRenames.length === 0 && !tableOrder && tableHidden.length === 0 && tableRowFilters.length === 0) continue;
+
+        const componentName = tableIdToComponentName(tableId);
+        console.log(`[Sidekick] Auto-wrapping ${componentName} with ${cols.length} added columns, ${tableRenames.length} renames, ${tableOrder ? 'reorder' : 'no reorder'}, ${tableHidden.length} hidden, ${tableRowFilters.length} row filters`);
+
+        const wrapped: WrappedComponent = {
+          id: `auto-columns-${tableId}`,
+          overrideId: '__sidekick-internal__',
+          wrapper: createAutoColumnWrapper(cols, tableRenames, tableOrder, tableHidden, tableRowFilters),
+          priority: -1000, // Low priority - runs after user wrappers
+        };
+        const existing = newState.wrappers.get(componentName) ?? [];
+        existing.push(wrapped);
+        existing.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+        newState.wrappers.set(componentName, existing);
+      }
+
+      setState(newState);
+      stateRef.current = newState;
+      setOverrides(loadedOverrides);
+
+      // Configure JSX runtime AFTER overrides are loaded and state is set
+      const wrapperGetter = (name: string): ((Component: ComponentType) => ComponentType) | undefined => {
+        const wrappers = stateRef.current.wrappers.get(name);
+        if (!wrappers || wrappers.length === 0) return undefined;
+        return (Component: ComponentType) => {
+          return wrappers.reduce(
+            (wrapped, { wrapper, where: wherePredicate }) => {
+              if (wherePredicate) {
+                const Wrapped = wrapper(wrapped);
+                const ConditionalWrapper = (props: Record<string, unknown>) => {
+                  if (wherePredicate(props)) {
+                    return React.createElement(Wrapped, props);
+                  }
+                  return React.createElement(wrapped, props);
+                };
+                ConditionalWrapper.displayName = `ConditionalWrap(${(wrapped as unknown as { displayName?: string; name?: string }).displayName || (wrapped as unknown as { name?: string }).name || 'Component'})`;
+                return ConditionalWrapper as unknown as ComponentType;
+              }
+              return wrapper(wrapped);
+            },
+            Component
+          );
+        };
+      };
+
+      const replacementGetter = (name: string): ComponentType | undefined => {
+        return stateRef.current.replacements.get(name);
+      };
+
+      console.log('[Sidekick] Configuring JSX runtime with', newState.wrappers.size, 'wrappers,', newState.replacements.size, 'replacements,', newState.columns.size, 'column sets');
+      configureJsxRuntime(wrapperGetter, replacementGetter);
+      configureJsxDevRuntime(wrapperGetter, replacementGetter);
+      console.log('[Sidekick] JSX runtime configured');
+
+      // NOW allow children to render
+      setIsReady(true);
+    };
+
+    initializeOverrides();
+  }, [overridesEndpoint]);
+
+  // Inject styles into document
+  useEffect(() => {
+    if (!isReady || typeof document === 'undefined') return;
+
+    const styleId = 'sidekick-injected-styles';
+    let styleEl = document.getElementById(styleId) as HTMLStyleElement | null;
+
+    if (!styleEl) {
+      styleEl = document.createElement('style');
+      styleEl.id = styleId;
+      document.head.appendChild(styleEl);
+    }
+
+    styleEl.textContent = state.styles.map((s) => s.css).join('\n');
+
+    return () => {
+      if (styleEl && styleEl.parentNode) {
+        styleEl.parentNode.removeChild(styleEl);
+      }
+    };
+  }, [state.styles, isReady]);
+
+  // Update JSX runtime getters when state changes (after initial load)
+  useEffect(() => {
+    if (!isReady) return;
+
+    const wrapperGetter = (name: string): ((Component: ComponentType) => ComponentType) | undefined => {
+      const wrappers = state.wrappers.get(name);
+      if (!wrappers || wrappers.length === 0) return undefined;
+
+      return (Component: ComponentType) => {
+        return wrappers.reduce(
+          (wrapped, { wrapper, where: wherePredicate }) => {
+            if (wherePredicate) {
+              const Wrapped = wrapper(wrapped);
+              const ConditionalWrapper = (props: Record<string, unknown>) => {
+                if (wherePredicate(props)) {
+                  return React.createElement(Wrapped, props);
+                }
+                return React.createElement(wrapped, props);
+              };
+              ConditionalWrapper.displayName = `ConditionalWrap(${(wrapped as unknown as { displayName?: string; name?: string }).displayName || (wrapped as unknown as { name?: string }).name || 'Component'})`;
+              return ConditionalWrapper as unknown as ComponentType;
+            }
+            return wrapper(wrapped);
+          },
+          Component
+        );
+      };
+    };
+
+    const replacementGetter = (name: string): ComponentType | undefined => {
+      return state.replacements.get(name);
+    };
+
+    configureJsxRuntime(wrapperGetter, replacementGetter);
+    configureJsxDevRuntime(wrapperGetter, replacementGetter);
+  }, [state.wrappers, state.replacements, isReady]);
+
+  // --- DOM Modifications (MutationObserver) ---
+  useEffect(() => {
+    if (!isReady || typeof document === 'undefined' || state.domModifications.length === 0) return;
+
+    // Track original values for cleanup
+    const originals = new Map<Element, { type: string; value: unknown }>();
+
+    function applyModifications() {
+      for (const mod of state.domModifications) {
+        let elements: NodeListOf<Element>;
+        try {
+          elements = document.querySelectorAll(mod.selector);
+        } catch {
+          console.warn(`[Sidekick] Invalid CSS selector: "${mod.selector}"`);
+          continue;
+        }
+        elements.forEach((el) => {
+          const htmlEl = el as HTMLElement;
+          // Store original value on first application
+          if (!originals.has(el)) {
+            switch (mod.type) {
+              case 'setText': {
+                // Collect original text node values (not textContent, which would lose references)
+                const textNodes: { node: Text; value: string }[] = [];
+                const tw = document.createTreeWalker(htmlEl, NodeFilter.SHOW_TEXT);
+                let tn: Text | null;
+                while ((tn = tw.nextNode() as Text | null)) {
+                  textNodes.push({ node: tn, value: tn.nodeValue || '' });
+                }
+                originals.set(el, { type: 'setText', value: textNodes });
+                break;
+              }
+              case 'setAttribute': {
+                const { attr } = mod.value as { attr: string; value: string };
+                originals.set(el, { type: 'setAttribute', value: { attr, value: htmlEl.getAttribute(attr) } });
+                break;
+              }
+              case 'setStyle':
+                originals.set(el, { type: 'setStyle', value: htmlEl.style.cssText });
+                break;
+              case 'addClass':
+                originals.set(el, { type: 'addClass', value: mod.value });
+                break;
+              case 'removeClass':
+                originals.set(el, { type: 'removeClass', value: mod.value });
+                break;
+            }
+          }
+          // Apply the modification
+          switch (mod.type) {
+            case 'setText': {
+              // Modify existing text nodes in-place to avoid destroying React's DOM references.
+              // Using textContent would remove all child nodes, breaking React reconciliation.
+              const walker = document.createTreeWalker(htmlEl, NodeFilter.SHOW_TEXT);
+              const firstTextNode = walker.nextNode() as Text | null;
+              if (firstTextNode) {
+                firstTextNode.nodeValue = mod.value as string;
+                // Clear any remaining text nodes
+                let extra: Text | null;
+                while ((extra = walker.nextNode() as Text | null)) {
+                  extra.nodeValue = '';
+                }
+              }
+              break;
+            }
+            case 'setAttribute': {
+              const { attr, value } = mod.value as { attr: string; value: string };
+              htmlEl.setAttribute(attr, value);
+              break;
+            }
+            case 'setStyle':
+              Object.assign(htmlEl.style, mod.value as Record<string, string>);
+              break;
+            case 'addClass':
+              htmlEl.classList.add(mod.value as string);
+              break;
+            case 'removeClass':
+              htmlEl.classList.remove(mod.value as string);
+              break;
+          }
+          htmlEl.setAttribute('data-sidekick-dom-mod', 'true');
+        });
+      }
+    }
+
+    applyModifications();
+
+    const observer = new MutationObserver(() => {
+      applyModifications();
+    });
+    if (document.body) {
+      observer.observe(document.body, { childList: true, subtree: true });
+    }
+
+    return () => {
+      observer.disconnect();
+      // Restore original values
+      originals.forEach((original, el) => {
+        const htmlEl = el as HTMLElement;
+        switch (original.type) {
+          case 'setText': {
+            const textNodes = original.value as { node: Text; value: string }[];
+            for (const { node, value } of textNodes) {
+              try { node.nodeValue = value; } catch { /* node may have been removed by React */ }
+            }
+            break;
+          }
+          case 'setAttribute': {
+            const { attr, value } = original.value as { attr: string; value: string | null };
+            if (value === null) htmlEl.removeAttribute(attr);
+            else htmlEl.setAttribute(attr, value);
+            break;
+          }
+          case 'setStyle':
+            htmlEl.style.cssText = original.value as string;
+            break;
+          case 'addClass':
+            htmlEl.classList.remove(original.value as string);
+            break;
+          case 'removeClass':
+            htmlEl.classList.add(original.value as string);
+            break;
+        }
+        htmlEl.removeAttribute('data-sidekick-dom-mod');
+      });
+    };
+  }, [state.domModifications, isReady]);
+
+  // --- Keyboard Shortcuts (keydown listener) ---
+  useEffect(() => {
+    if (!isReady || typeof document === 'undefined' || state.keyboardShortcuts.length === 0) return;
+
+    function matchesKeys(event: KeyboardEvent, keys: string): boolean {
+      const parts = keys.toLowerCase().split('+').map(s => s.trim());
+      const keyName = parts[parts.length - 1];
+      const modifiers = new Set(parts.slice(0, -1));
+
+      const needsCtrl = modifiers.has('ctrl') || modifiers.has('cmd') || modifiers.has('meta');
+      const needsShift = modifiers.has('shift');
+      const needsAlt = modifiers.has('alt');
+
+      if (needsCtrl !== (event.ctrlKey || event.metaKey)) return false;
+      if (needsShift !== event.shiftKey) return false;
+      if (needsAlt !== event.altKey) return false;
+
+      return event.key.toLowerCase() === keyName || event.code.toLowerCase() === keyName;
+    }
+
+    function handleKeydown(event: KeyboardEvent) {
+      for (const shortcut of state.keyboardShortcuts) {
+        if (matchesKeys(event, shortcut.keys)) {
+          event.preventDefault();
+          try {
+            shortcut.action();
+          } catch (error) {
+            console.error(`[Sidekick] Keyboard shortcut error for "${shortcut.keys}":`, error);
+          }
+          return;
+        }
+      }
+    }
+
+    document.addEventListener('keydown', handleKeydown);
+    return () => {
+      document.removeEventListener('keydown', handleKeydown);
+    };
+  }, [state.keyboardShortcuts, isReady]);
+
+  // --- Fetch Interception (monkey-patch window.fetch) ---
+  useEffect(() => {
+    if (!isReady || typeof window === 'undefined' || state.interceptors.length === 0) return;
+
+    const originalFetch = window.fetch;
+
+    window.fetch = async function sidekickFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response> {
+      const response = await originalFetch.call(window, input, init);
+      const url = typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url;
+      const method = init?.method || 'GET';
+
+      for (const interceptor of stateRef.current.interceptors) {
+        const pattern = interceptor.pathPattern;
+        const matches = typeof pattern === 'string'
+          ? url.includes(pattern)
+          : pattern.test(url);
+
+        if (matches) {
+          try {
+            const cloned = response.clone();
+            const json = await cloned.json();
+            const modified = interceptor.handler(json, { path: url, method });
+            return new Response(JSON.stringify(modified), {
+              status: response.status,
+              statusText: response.statusText,
+              headers: response.headers,
+            });
+          } catch {
+            // If JSON parsing fails or handler errors, return original
+            return response;
+          }
+        }
+      }
+
+      return response;
+    };
+
+    return () => {
+      window.fetch = originalFetch;
+    };
+  }, [state.interceptors, isReady]);
+
+  // --- DOM Injections (MutationObserver + Portals) ---
+  const [injectionContainers, setInjectionContainers] = useState<Array<{ injection: InjectionPoint; container: HTMLElement }>>([]);
+
+  useEffect(() => {
+    if (!isReady || typeof document === 'undefined' || state.injections.length === 0) return;
+
+    const containers: Array<{ injection: InjectionPoint; container: HTMLElement }> = [];
+
+    function createContainers() {
+      // Clean up previous containers
+      document.querySelectorAll('[data-sidekick-injection]').forEach(el => el.remove());
+      containers.length = 0;
+
+      for (const injection of state.injections) {
+        let target: Element | null;
+        try {
+          target = document.querySelector(injection.selector);
+        } catch {
+          console.warn(`[Sidekick] Invalid CSS selector: "${injection.selector}"`);
+          continue;
+        }
+        if (!target) continue;
+
+        const container = document.createElement('div');
+        container.setAttribute('data-sidekick-injection', injection.id);
+
+        switch (injection.position) {
+          case 'before':
+            target.parentNode?.insertBefore(container, target);
+            break;
+          case 'after':
+            target.parentNode?.insertBefore(container, target.nextSibling);
+            break;
+          case 'prepend':
+            target.insertBefore(container, target.firstChild);
+            break;
+          case 'append':
+            target.appendChild(container);
+            break;
+        }
+
+        containers.push({ injection, container });
+      }
+
+      setInjectionContainers([...containers]);
+    }
+
+    createContainers();
+
+    const observer = new MutationObserver(() => {
+      // Re-check if any targets appeared
+      const needsUpdate = state.injections.some(inj => {
+        try {
+          const existing = document.querySelector(`[data-sidekick-injection="${inj.id}"]`);
+          if (existing) return false;
+          const target = document.querySelector(inj.selector);
+          return !!target;
+        } catch {
+          return false;
+        }
+      });
+      if (needsUpdate) createContainers();
+    });
+    if (document.body) {
+      observer.observe(document.body, { childList: true, subtree: true });
+    }
+
+    return () => {
+      observer.disconnect();
+      document.querySelectorAll('[data-sidekick-injection]').forEach(el => el.remove());
+      setInjectionContainers([]);
+    };
+  }, [state.injections, isReady]);
+
+  // --- DOM Event Delegation ---
+  useEffect(() => {
+    if (!isReady || typeof document === 'undefined' || state.domEventListeners.length === 0) return;
+
+    const cleanups: Array<() => void> = [];
+
+    for (const listener of state.domEventListeners) {
+      const handler = (event: Event) => {
+        const target = event.target as Element | null;
+        if (!target) return;
+        let matched: Element | null;
+        try {
+          matched = target.matches(listener.selector) ? target : target.closest(listener.selector);
+        } catch {
+          return; // Invalid selector
+        }
+        if (matched) {
+          try {
+            listener.handler(event, matched);
+          } catch (error) {
+            console.error(`[Sidekick] DOM event handler error for "${listener.selector}" ${listener.eventType}:`, error);
+          }
+        }
+      };
+      document.addEventListener(listener.eventType, handler);
+      cleanups.push(() => document.removeEventListener(listener.eventType, handler));
+    }
+
+    return () => {
+      cleanups.forEach(cleanup => cleanup());
+    };
+  }, [state.domEventListeners, isReady]);
+
+  // --- Route Modification (history patch) ---
+  useEffect(() => {
+    if (!isReady || typeof window === 'undefined' || state.routeModifiers.length === 0) return;
+
+    const originalPushState = history.pushState.bind(history);
+    const originalReplaceState = history.replaceState.bind(history);
+
+    function interceptNavigation(
+      original: typeof history.pushState,
+      data: unknown,
+      unused: string,
+      url?: string | URL | null
+    ) {
+      let finalUrl = url;
+      if (url) {
+        const urlStr = url.toString();
+        for (const modifier of stateRef.current.routeModifiers) {
+          const pattern = modifier.pathPattern;
+          const matches = typeof pattern === 'string'
+            ? urlStr.includes(pattern)
+            : pattern.test(urlStr);
+
+          if (matches) {
+            try {
+              const result = modifier.handler({ path: urlStr, params: {} });
+              if (typeof result === 'string') {
+                finalUrl = result;
+              }
+            } catch (error) {
+              console.error(`[Sidekick] Route modifier error:`, error);
+            }
+          }
+        }
+      }
+      original(data, unused, finalUrl);
+    }
+
+    history.pushState = function(data: unknown, unused: string, url?: string | URL | null) {
+      interceptNavigation(originalPushState, data, unused, url);
+    };
+
+    history.replaceState = function(data: unknown, unused: string, url?: string | URL | null) {
+      interceptNavigation(originalReplaceState, data, unused, url);
+    };
+
+    const handlePopState = () => {
+      const currentPath = window.location.pathname;
+      for (const modifier of stateRef.current.routeModifiers) {
+        const pattern = modifier.pathPattern;
+        const matches = typeof pattern === 'string'
+          ? currentPath.includes(pattern)
+          : pattern.test(currentPath);
+
+        if (matches) {
+          try {
+            modifier.handler({ path: currentPath, params: {} });
+          } catch (error) {
+            console.error(`[Sidekick] Route modifier error on popstate:`, error);
+          }
+        }
+      }
+    };
+
+    window.addEventListener('popstate', handlePopState);
+
+    return () => {
+      history.pushState = originalPushState;
+      history.replaceState = originalReplaceState;
+      window.removeEventListener('popstate', handlePopState);
+    };
+  }, [state.routeModifiers, isReady]);
+
+  const isOverrideEnabled = useCallback(
+    (id: string) => {
+      // For API-based overrides, check the loaded state
+      const override = overrides.find(o => o.id === id);
+      if (override) return override.enabled;
+      // Fallback to localStorage
+      return getFlag(id);
+    },
+    [overrides]
+  );
+
+  const toggleOverride = useCallback(
+    (id: string) => {
+      const currentEnabled = getFlag(id);
+      saveFlag(id, !currentEnabled);
+      // Trigger re-initialization
+      window.location.reload();
+    },
+    []
+  );
+
+  const getColumns = useCallback(
+    (tableId: string): AddedColumn[] => {
+      return state.columns.get(tableId) ?? [];
+    },
+    [state.columns]
+  );
+
+  const getColumnRenames = useCallback(
+    (tableId: string): ColumnRename[] => {
+      return state.columnRenames.get(tableId) ?? [];
+    },
+    [state.columnRenames]
+  );
+
+  const getHiddenColumns = useCallback(
+    (tableId: string) => {
+      return state.hiddenColumns.get(tableId) ?? [];
+    },
+    [state.hiddenColumns]
+  );
+
+  const getColumnOrder = useCallback(
+    (tableId: string) => {
+      return state.columnOrders.get(tableId);
+    },
+    [state.columnOrders]
+  );
+
+  const getMenuItems = useCallback(
+    (menuId: string) => {
+      return state.menuItems.get(menuId) ?? [];
+    },
+    [state.menuItems]
+  );
+
+  const getTabs = useCallback(
+    (tabGroupId: string) => {
+      return state.tabs.get(tabGroupId) ?? [];
+    },
+    [state.tabs]
+  );
+
+  const getActions = useCallback(
+    (actionBarId: string) => {
+      return state.actions.get(actionBarId) ?? [];
+    },
+    [state.actions]
+  );
+
+  const getValidations = useCallback(
+    (formId: string) => {
+      return state.validations.get(formId) ?? [];
+    },
+    [state.validations]
+  );
+
+  const applyPropsModifiers = useCallback(
+    (componentId: string, props: Record<string, unknown>) => {
+      const modifiers = state.propsModifiers.get(componentId) ?? [];
+      return modifiers.reduce((acc, { modifier }) => modifier(acc), props);
+    },
+    [state.propsModifiers]
+  );
+
+  const getComputedValue = useCallback(
+    <T,>(fieldName: string, data: Record<string, unknown>): T | undefined => {
+      const field = state.computedFields.get(fieldName);
+      if (!field) return undefined;
+      return field.compute(data) as T;
+    },
+    [state.computedFields]
+  );
+
+  const applyFilters = useCallback(
+    <T,>(filterName: string, items: T[]): T[] => {
+      const filter = state.filters.get(filterName);
+      if (!filter) return items;
+      return filter.filter(items as unknown[]) as T[];
+    },
+    [state.filters]
+  );
+
+  const applyTransform = useCallback(
+    <T,>(dataKey: string, data: T): T => {
+      const transform = state.transforms.get(dataKey);
+      if (!transform) return data;
+      return transform.transform(data) as T;
+    },
+    [state.transforms]
+  );
+
+  const getSortOptions = useCallback(
+    (tableId: string) => {
+      return state.sortOptions.get(tableId) ?? [];
+    },
+    [state.sortOptions]
+  );
+
+  const getGroupByOptions = useCallback(
+    (tableId: string) => {
+      return state.groupByOptions.get(tableId) ?? [];
+    },
+    [state.groupByOptions]
+  );
+
+  const getKeyboardShortcuts = useCallback(
+    () => {
+      return state.keyboardShortcuts;
+    },
+    [state.keyboardShortcuts]
+  );
+
+  const emitEvent = useCallback(
+    (eventName: string, payload: Record<string, unknown>) => {
+      const handlers = state.eventHandlers.get(eventName) ?? [];
+      for (const handler of handlers) {
+        try {
+          handler.handler(payload);
+        } catch (error) {
+          console.error(`[Sidekick] Event handler error for ${eventName}:`, error);
+        }
+      }
+    },
+    [state.eventHandlers]
+  );
+
+  const getWrapper = useCallback(
+    (componentName: string): ((Component: ComponentType) => ComponentType) | undefined => {
+      const wrappers = state.wrappers.get(componentName);
+      if (!wrappers || wrappers.length === 0) return undefined;
+
+      // Compose all wrappers into a single wrapper function
+      return (Component: ComponentType) => {
+        return wrappers.reduce(
+          (wrapped, { wrapper }) => wrapper(wrapped),
+          Component
+        );
+      };
+    },
+    [state.wrappers]
+  );
+
+  const getReplacement = useCallback(
+    (componentName: string): ComponentType | undefined => {
+      return state.replacements.get(componentName);
+    },
+    [state.replacements]
+  );
+
+  const contextValue: SidekickContextValue = useMemo(
+    () => ({
+      state,
+      overrides,
+      isOverrideEnabled,
+      toggleOverride,
+      // UI
+      getColumns,
+      getColumnRenames,
+      getHiddenColumns,
+      getColumnOrder,
+      getMenuItems,
+      getTabs,
+      getActions,
+      getValidations,
+      getWrapper,
+      getReplacement,
+      applyPropsModifiers,
+      // Data
+      getComputedValue,
+      applyFilters,
+      applyTransform,
+      getSortOptions,
+      getGroupByOptions,
+      // Behavior
+      getKeyboardShortcuts,
+      emitEvent,
+    }),
+    [
+      state,
+      overrides,
+      isOverrideEnabled,
+      toggleOverride,
+      getColumns,
+      getColumnRenames,
+      getHiddenColumns,
+      getColumnOrder,
+      getMenuItems,
+      getTabs,
+      getActions,
+      getValidations,
+      getWrapper,
+      getReplacement,
+      applyPropsModifiers,
+      getComputedValue,
+      applyFilters,
+      applyTransform,
+      getSortOptions,
+      getGroupByOptions,
+      getKeyboardShortcuts,
+      emitEvent,
+    ]
+  );
+
+  // Cache for wrapped component types — persisted across renders via ref
+  // so React sees stable component identities and doesn't remount
+  const wrapCacheRef = useRef(new Map<unknown, ComponentType>());
+
+  // Transform the children element tree to apply wrappers/replacements
+  // to components whose JSX callsite is in a server component (and therefore
+  // bypasses the custom JSX runtime interception).
+  const transformedChildren = useMemo(() => {
+    if (!isReady) return null;
+    if (state.wrappers.size === 0 && state.replacements.size === 0) return children;
+    return transformElementTree(children, state.wrappers, state.replacements, wrapCacheRef.current);
+  }, [children, isReady, state.wrappers, state.replacements]);
+
+  // Don't render children until overrides are loaded and JSX runtime is configured
+  return (
+    <SidekickContext.Provider value={contextValue}>
+      {isReady ? transformedChildren : null}
+      {injectionContainers.map(({ injection, container }) =>
+        createPortal(
+          React.createElement(injection.component, {}),
+          container,
+          `sidekick-injection-${injection.id}`
+        )
+      )}
+    </SidekickContext.Provider>
+  );
+}