socialcalc-ai 1.0.0 → 1.0.2

package/README.md

@@ -1,55 +1,243 @@
-# SocialCalc AI (`socialcalc-ai`)
+# socialcalc-ai
+
+[![npm version](https://img.shields.io/npm/v/socialcalc-ai.svg?color=cb3837&style=flat-square)](https://www.npmjs.com/package/socialcalc-ai)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg?style=flat-square)](https://www.typescriptlang.org/)
+[![Module: ESM](https://img.shields.io/badge/Module-ESM-success.svg?style=flat-square)](https://nodejs.org/api/esm.html)
 
 > **A modernized, modularized, high-performance spreadsheet engine with ES6 module exports, React/Ionic UI components, AI template capabilities, and an extensible plugin system.**
 
+Derived from Dan Bricklin's proven, industrial-strength **SocialCalc** engine, `socialcalc-ai` has been re-architected for modern web, mobile, and AI-driven applications. It replaces legacy global variables with clean ES modules, provides full TypeScript definitions, adds smooth mobile touch physics, and includes a full suite of modern React/Ionic UI controls.
+
+---
+
+## 📑 Table of Contents
+
+- [Features](#-features)
+- [Installation](#-installation)
+- [Quick Start in React / Ionic](#-quick-start-in-react--ionic)
+- [Quick Start in Vanilla JavaScript](#-quick-start-in-vanilla-javascript)
+- [Architecture Overview](#-architecture-overview)
+- [UI Components](#-ui-components)
+  - [CellEditModal](#1-celleditmodal)
+  - [HorizontalScrollBar](#2-horizontalscrollbar)
+  - [RowActionPopover](#3-rowactionpopover)
+  - [EditableCellsModal](#4-editablecellsmodal)
+  - [DemoVideosModal](#5-demovideosmodal)
+- [Plugins & Modules API](#-plugins--modules-api)
+  - [Row & Column Headers](#1-row--column-headers-modulesrow-col-headersjs)
+  - [Grid Lines](#2-grid-lines-modulesgrid-linesjs)
+  - [Smooth Touch Scroll](#3-smooth-touch-scroll-modulestouch-scrolljs)
+  - [Horizontal Scroll](#4-horizontal-scroll-moduleshorizontal-scrolljs)
+  - [Editable Cells & Template Locks](#5-editable-cells--template-locks-moduleseditable-cellsjs)
+  - [Plugin Manager](#6-plugin-manager-modulesplugin-managerjs)
+  - [History & Undo/Redo](#7-history-undo--redo-moduleshistoryjs)
+  - [Exporters & Sheets](#8-exporters--sheets-modulesexportersjs-modulessheetsjs)
+  - [Invoice Utilities](#9-invoice-utilities-modulesinvoicejs)
+- [Event-Driven Architecture](#-event-driven-architecture)
+- [AI & MultiSheet Calc (MSC) Integration](#-ai--multisheet-calc-msc-integration)
+- [TypeScript Support](#-typescript-support)
+- [Browser & Framework Compatibility](#-browser--framework-compatibility)
+- [License & Acknowledgments](#-license--acknowledgments)
+
+---
+
+## ✨ Features
+
+- **⚡ Modern ES6 Architecture**: Pure ES module exports replacing legacy global namespace pollution. Works with Vite, Next.js, Webpack, Rollup, and ES2020+ runtimes.
+- **📱 Touch & Mobile Optimized**: Smooth momentum physics and inertia swipe scrolling without screen jumping or layout stutter.
+- **🎨 Modern React & Ionic UI Suite**:
+  - Full-featured **CellEditModal** (Formulas, rich formatting, custom color palettes, borders, and compressed image inserts).
+  - Smooth **HorizontalScrollBar** with live column indicators and drag navigation.
+  - Interactive **RowActionPopover** for dynamic row insertion and deletion.
+  - **EditableCellsModal** to inspect and manage cell locks.
+  - **DemoVideosModal** with an interactive formula cheat sheet.
+- **🔌 Pluggable Architecture**: Dynamically enable, disable, or configure spreadsheet subsystems (headers, gridlines, momentum scroll, locks).
+- **📐 Universal Calculation Engine**: Industrial-grade formula AST evaluator supporting standard math, statistics, string, logic, and financial functions.
+- **🤖 AI-Ready MultiSheet Calc (MSC)**: Serialize and deserialize full spreadsheet workbooks as structured JSON or MSC strings, ideal for LLM spreadsheet generation pipelines.
+- **🛡 Full TypeScript Definitions**: First-class `index.d.ts` definitions included out of the box.
+
 ---
 
 ## 📦 Installation
 
+Install `socialcalc-ai` via npm:
+
 ```bash
 npm install socialcalc-ai
 ```
 
-Or with yarn / pnpm:
+Or using Yarn / pnpm:
+
 ```bash
+# Using Yarn
 yarn add socialcalc-ai
+
+# Using pnpm
 pnpm add socialcalc-ai
 ```
 
+### Peer Dependencies
+
+If you plan to use the pre-built React / Ionic components (`CellEditModal`, `HorizontalScrollBar`, etc.), ensure the peer dependencies are installed:
+
+```bash
+npm install react react-dom @ionic/react ionicons
+```
+
+*(Note: Peer dependencies are optional if you only consume the core calculation engine in headless Node.js or Vanilla JS environments).*
+
 ---
 
-## 📌 Overview
+## 🚀 Quick Start in React / Ionic
+
+Below is a complete, minimal working example showing how to mount the spreadsheet engine and hook up the interactive React UI suite:
+
+```tsx
+import React, { useEffect, useState } from "react";
+import * as AppGeneral from "socialcalc-ai";
+import {
+  CellEditModal,
+  HorizontalScrollBar,
+  RowActionPopover,
+  EditableCellsModal,
+} from "socialcalc-ai";
+
+// Optional: Ionic base styles if using Ionic framework
+import "@ionic/react/css/core.css";
 
-This package (`socialcalc-ai`) is a **standalone, framework-agnostic core** with first-class React & Ionic bindings. It takes Dan Bricklin's proven, industrial-strength SocialCalc engine and modernizes it for modern web, mobile, and AI applications:
-- **Clean ES6 module structure** replacing legacy globals.
-- **Pluggable Architecture**: Dynamically toggle features like Grid Lines, 123/ABCD Row-Col Headers, Touch Scroll with momentum, and Editable Cell Locking.
-- **Modern Touch & Mobile Support**: Smooth inertia swipe scrolling without jumping.
-- **Modern Ionic / React Components**: High-fidelity modal editors, responsive horizontal scroll controls, context popovers for row operations, and cell mapping inspectors.
-- **Universal Spreadsheet Commands**: Full support for SocialCalc formulas, cell formatting, font styling, borders, multi-sheet workbooks, and CSV/MSC serialization.
+export const SpreadsheetEditor: React.FC = () => {
+  const [cellEditData, setCellEditData] = useState<any>(null);
+  const [showEditModal, setShowEditModal] = useState(false);
+  const [rowPopoverEvent, setRowPopoverEvent] = useState<{ event: any; rowNum: number } | null>(null);
+
+  useEffect(() => {
+    // 1. Initialize SocialCalc DOM container with initial data (or empty string)
+    const initialMSC = ""; 
+    AppGeneral.initializeApp(initialMSC);
 
-> ⚠️ **CRITICAL FOR DEVELOPERS & AGENTS**:  
-> This package is consumed as a shared standalone dependency across multiple downstream apps. Any breaking changes to public APIs, event signatures, or file paths will impact all applications using it. Always preserve backward compatibility.
+    // 2. Activate desired plugins
+    AppGeneral.enableRowColHeaders(); // 1, 2, 3... & A, B, C... headers with resize handles
+    AppGeneral.enableGridLines();      // Modern cell border grid
+    AppGeneral.enableTouchScroll();    // Smooth mobile inertia scroll
+
+    // 3. Listen for Cell Edit Modal requests
+    const handleCellEdit = (e: any) => {
+      setCellEditData(e.detail);
+      setShowEditModal(true);
+    };
+
+    // 4. Listen for Row Header clicks (context actions)
+    const handleRowClick = (e: any) => {
+      setRowPopoverEvent({
+        event: e.detail.originalEvent || e.detail,
+        rowNum: e.detail.rowNum,
+      });
+    };
+
+    window.addEventListener("socialcalc:cell-edit-request", handleCellEdit);
+    window.addEventListener("socialcalc:row-header-click", handleRowClick);
+
+    return () => {
+      window.removeEventListener("socialcalc:cell-edit-request", handleCellEdit);
+      window.removeEventListener("socialcalc:row-header-click", handleRowClick);
+    };
+  }, []);
+
+  return (
+    <div style={{ position: "relative", width: "100%", height: "100vh", overflow: "hidden" }}>
+      {/* SocialCalc DOM Mounting Target Elements */}
+      <div id="container" style={{ width: "100%", height: "calc(100% - 44px)" }}>
+        <div id="workbookControl" style={{ display: "none" }}></div>
+        <div id="tableeditor" style={{ width: "100%", height: "100%" }}></div>
+        <div id="msg"></div>
+      </div>
+
+      {/* Horizontal Viewport Scrollbar */}
+      <HorizontalScrollBar />
+
+      {/* Rich Cell Editor Bottom Sheet */}
+      <CellEditModal
+        isOpen={showEditModal}
+        cellData={cellEditData}
+        onClose={() => setShowEditModal(false)}
+      />
+
+      {/* Row Insert / Delete Popover */}
+      <RowActionPopover
+        isOpen={!!rowPopoverEvent}
+        event={rowPopoverEvent?.event}
+        selectedRow={rowPopoverEvent?.rowNum}
+        onDismiss={() => setRowPopoverEvent(null)}
+      />
+    </div>
+  );
+};
+
+export default SpreadsheetEditor;
+```
 
 ---
 
-## 📁 Package Architecture
+## 🌐 Quick Start in Vanilla JavaScript
+
+`socialcalc-ai` can be used in plain HTML/JavaScript or non-React web apps without any framework overhead:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>SocialCalc AI Standalone</title>
+</head>
+<body>
+  <div id="container">
+    <div id="workbookControl" style="display: none;"></div>
+    <div id="tableeditor"></div>
+    <div id="msg"></div>
+  </div>
+
+  <script type="module">
+    import * as SocialCalcApp from "socialcalc-ai";
+
+    // Initialize spreadsheet
+    SocialCalcApp.initializeApp("");
+
+    // Enable modern features
+    SocialCalcApp.enableGridLines();
+    SocialCalcApp.enableRowColHeaders();
+    SocialCalcApp.enableTouchScroll();
+
+    // Listen for cell change events
+    SocialCalcApp.setupCellChangeListener((coord, value) => {
+      console.log(`Cell ${coord} updated:`, value);
+    });
+  </script>
+</body>
+</html>
+```
+
+---
+
+## 📁 Architecture Overview
 
 ```text
-socialcalc/
-├── index.js                      # Main entry point: re-exports core, all modules & React components
+socialcalc-ai/
+├── index.js                      # Main entry point: aggregates core, modules & UI
+├── index.d.ts                    # Complete TypeScript typings
 ├── package.json                  # Standalone package definition
-├── core/                         # Core calculation engine & table rendering
-│   ├── constants.js              # SocialCalc constant definitions & default styles
+├── core/                         # Core calculation engine & DOM table rendering
+│   ├── constants.js              # Formatting codes, default styles & limits
 │   ├── core.js                   # Spreadsheet sheet model, cell evaluation, formula AST
-│   ├── formula.js                # Built-in math, logical, string, financial formulas
+│   ├── formula.js                # Built-in math, logical, string, financial functions
 │   ├── format-number.js          # Numeric and date formatting routines
 │   ├── spreadsheet-control.js    # Spreadsheet control lifecycle & pane management
 │   ├── table-editor.js           # DOM table editor layout & cursor rendering
 │   └── index.js                  # Assembled core SocialCalc singleton export
-├── modules/                      # Modularized functional features & plugins
+├── modules/                      # Modular functional features & plugins
 │   ├── plugin-manager.js         # Central registry for dynamic SocialCalc plugins
-│   ├── grid-lines.js             # Dynamic cell border grid-lines plugin
-│   ├── row-col-headers.js        # 123 Row & ABCD Col headers with resize handles & row selection
+│   ├── grid-lines.js             # Cell border grid-lines plugin
+│   ├── row-col-headers.js        # 123 / ABCD headers with resize handles & row selection
 │   ├── touch-scroll.js           # Momentum/inertia mobile touch scroll
 │   ├── horizontal-scroll.js      # Viewport tracking & horizontal scrolling subscriptions
 │   ├── editable-cells.js         # Cell lock & template permission plugin
@@ -60,12 +248,13 @@ socialcalc/
 │   ├── init.js                   # Workbook & table editor DOM initialization
 │   ├── prompts.js                # Enhanced input dialogs & modal dispatchers
 │   ├── exporters.js              # HTML, CSV, MSC export helpers
+│   ├── invoice.js                # Coordinate mapping & invoice utilities
 │   ├── device.js                 # Device detection and responsive helpers
 │   ├── logos.js                  # Brand/logo helper utilities
 │   ├── utils.js                  # Coordinate conversions, DOM utilities
 │   └── weight.js                 # Cell weight/scoring utilities
 ├── components/                   # React & Ionic UI Components
-│   ├── CellEditModal/            # Rich bottom sheet editor (Text, Formula, Colors, Borders, Images)
+│   ├── CellEditModal/            # Rich editor sheet (Formulas, Text, Colors, Borders, Images)
 │   ├── HorizontalScrollBar.tsx   # Smooth horizontal navigation bar & track slider
 │   ├── RowActionPopover/         # Context menu for row insertion & deletion
 │   ├── EditableCellsModal/       # Template mapping manager & cell lock editor
@@ -77,192 +266,284 @@ socialcalc/
 
 ---
 
-## 🚀 Quick Start in React / Ionic
+## 🎨 UI Components
 
-### 1. Installation
+### 1. `CellEditModal`
+A modern, responsive bottom-sheet modal that replaces legacy browser `prompt()` dialogs with a rich spreadsheet formatting bar:
+- **Formula & Text Editor**: Live input bar with syntax validation (e.g. `=SUM(A1:B10)`).
+- **Styling**: Bold, Italic, Alignment (Left, Center, Right).
+- **Curated Palette**: 8 font colors (`FONT_COLORS`) and 7 background colors (`BG_COLORS`).
+- **Cell Borders**: Top, Bottom, Left, Right, and All borders with Solid, Dashed, or Dotted styles.
+- **Image Insertion**: Embed images into cells with automatic client-side compression via `imageCompressor.ts`.
+- **Fallback**: Automatically falls back to native inline input if modal mode is disabled.
 
-```bash
-npm install socialcalc-ai
+```tsx
+<CellEditModal
+  isOpen={isOpen}
+  cellData={cellData}
+  onClose={() => setIsOpen(false)}
+/>
 ```
 
-### 2. Initialization in React Component
+### 2. `HorizontalScrollBar`
+A smooth horizontal track controller designed specifically for wide spreadsheets on mobile and desktop:
+- Step-by-step column advancement buttons (◀ / ▶).
+- Responsive drag track with active column indicator (e.g., `Cols: A - J`).
+- Synchronizes bi-directionally with keyboard arrow navigation and touch scrolling.
 
 ```tsx
-import React, { useEffect, useState } from "react";
-import * as AppGeneral from "socialcalc-ai";
-import {
-  CellEditModal,
-  HorizontalScrollBar,
-  RowActionPopover,
-} from "socialcalc-ai";
-
-const MySpreadsheet: React.FC = () => {
-  const [cellEditData, setCellEditData] = useState<any>(null);
-  const [showModal, setShowModal] = useState(false);
-
-  useEffect(() => {
-    // 1. Initialize DOM workbook container
-    const initialMSC = { /* SocialCalc MSC json or save string */ };
-    AppGeneral.initializeApp(JSON.stringify(initialMSC));
+<HorizontalScrollBar />
+```
 
-    // 2. Enable desired plugins
-    AppGeneral.enableRowColHeaders(); // 123 / ABCD headers
-    AppGeneral.enableGridLines();      // Cell grid borders
-    AppGeneral.enableTouchScroll();    // Smooth touch scrolling
+### 3. `RowActionPopover`
+A context popup that appears when clicking any row header index:
+- **Insert Row Above**: Inserts an empty row above the selected index.
+- **Insert Row Below**: Inserts an empty row below the selected index.
+- **Delete Row**: Removes the selected row and cascades formula references.
 
-    // 3. Listen for Cell Edit Modal request events
-    const handleCellEdit = (e: any) => {
-      setCellEditData(e.detail);
-      setShowModal(true);
-    };
-    window.addEventListener("socialcalc:cell-edit-request", handleCellEdit);
+```tsx
+<RowActionPopover
+  isOpen={showPopover}
+  event={clickEvent}
+  selectedRow={rowNumber}
+  onDismiss={() => setShowPopover(false)}
+/>
+```
 
-    return () => {
-      window.removeEventListener("socialcalc:cell-edit-request", handleCellEdit);
-    };
-  }, []);
+### 4. `EditableCellsModal`
+An administrative inspector for template creators:
+- View all locked vs editable cells in the active sheet.
+- Bind application field mappings (e.g., `vendor_name -> B4`) to spreadsheet coordinates.
+- Test template locking permissions.
 
-  return (
-    <div style={{ position: "relative", width: "100%", height: "100vh" }}>
-      {/* SocialCalc mounting targets */}
-      <div id="container">
-        <div id="workbookControl" style={{ display: "none" }}></div>
-        <div id="tableeditor"></div>
-        <div id="msg"></div>
-      </div>
+```tsx
+<EditableCellsModal
+  isOpen={showModal}
+  onClose={() => setShowModal(false)}
+/>
+```
 
-      {/* Horizontal Scroll Bar */}
-      <HorizontalScrollBar />
+### 5. `DemoVideosModal`
+An interactive help and reference modal containing:
+- Built-in formula cheat sheets (`SUM`, `AVERAGE`, `IF`, `VLOOKUP`, `COUNT`, `CONCATENATE`, etc.).
+- Embedded tutorial guides for spreadsheet operators.
 
-      {/* Modern Cell Edit Modal */}
-      <CellEditModal
-        isOpen={showModal}
-        cellData={cellEditData}
-        onClose={() => setShowModal(false)}
-      />
-    </div>
-  );
-};
+```tsx
+<DemoVideosModal
+  isOpen={showHelp}
+  onClose={() => setShowHelp(false)}
+/>
 ```
 
 ---
 
-## 🛠 Features & Plugins Deep Dive
-
-### 1. Row and Column Headers (`modules/row-col-headers.js`)
-Displays standard spreadsheet row numbers (`1, 2, 3...`) and column letters (`A, B, C...`).
-- **Smooth Column Resizing**: Hover or drag right edge of any column header to resize. Live floating tooltip and guideline indicate new column width.
-- **Corner Resize Handle**: Tap/click a column header to display a mobile-friendly corner drag handle (`#sc-col-resize-corner-handle`).
-- **Row Selection**: Clicking a row header selects the full row and fires `socialcalc:row-header-click`.
-- **API**:
-  ```ts
-  AppGeneral.enableRowColHeaders();
-  AppGeneral.disableRowColHeaders();
-  AppGeneral.toggleRowColHeaders(); // returns boolean
-  AppGeneral.isRowColHeadersEnabled(); // returns boolean
-  AppGeneral.executeSheetCommand(cmd); // runs SocialCalc sheet command synchronously
-  ```
+## 🔌 Plugins & Modules API
+
+### 1. Row & Column Headers (`modules/row-col-headers.js`)
+Enables 123 row numbers and ABCD column headers with interactive column resizing:
+```ts
+// Enable row/col headers
+AppGeneral.enableRowColHeaders();
+
+// Disable row/col headers
+AppGeneral.disableRowColHeaders();
+
+// Toggle headers dynamically (returns boolean)
+const isEnabled = AppGeneral.toggleRowColHeaders();
+
+// Execute raw SocialCalc commands
+AppGeneral.executeSheetCommand("set A1 text hello");
+```
 
 ### 2. Grid Lines (`modules/grid-lines.js`)
-Provides clean, modern cell grid lines across all table cells.
-- **API**:
-  ```ts
-  AppGeneral.enableGridLines(customCss?: string);
-  AppGeneral.disableGridLines();
-  AppGeneral.toggleGridLines(); // returns boolean
-  AppGeneral.isGridLinesEnabled(); // returns boolean
-  ```
+Adds subtle, high-contrast borders between cells:
+```ts
+AppGeneral.enableGridLines();
+AppGeneral.disableGridLines();
+AppGeneral.toggleGridLines();
+```
 
 ### 3. Smooth Touch Scroll (`modules/touch-scroll.js`)
-Replaces clunky full-page jumping on mobile swipes with smooth continuous panning and physics-based inertia momentum.
-- **API**:
-  ```ts
-  AppGeneral.enableTouchScroll();
-  AppGeneral.disableTouchScroll();
-  AppGeneral.toggleTouchScroll(); // returns boolean
-  AppGeneral.isTouchScrollEnabled(); // returns boolean
-  AppGeneral.configureTouchScroll({ momentumFriction: 0.94 });
-  ```
-
-### 4. Cell Edit Modal (`components/CellEditModal/`)
-A responsive, high-feature editing sheet replacing legacy browser prompt popups:
-- **Text & Numeric Inputs**: Edit formulas (e.g. `=SUM(B4:C4)`), raw values, or labels.
-- **Formatting Presets**: Currency, Percent, Date, Time, Integer.
-- **Styling**: Bold, Italic, Alignment (Left, Center, Right).
-- **Colors**: 8 curated font colors and 7 cell background colors.
-- **Borders**: All, Top, Bottom, Left, Right with Solid/Dashed/Dotted styles and custom widths.
-- **Image Insertion**: Embed images into cells with automatic client-side compression (`imageCompressor.ts`).
-- **Fallback**: Calling `toggleCellEditModal(false)` automatically falls back to native inline input.
-
-### 5. Horizontal Scroll Bar (`components/HorizontalScrollBar.tsx`)
-A dedicated, smooth horizontal control bar for navigating wide sheets:
-- Step buttons for next/prev columns.
-- Draggable slider track with live position indicator.
-- Automatically syncs with spreadsheet viewport when user scrolls or uses keyboard navigation.
-
-### 6. Row Action Popover (`components/RowActionPopover/`)
-Context popup that triggers when user taps a row header:
-- **Insert Above**: Calls `executeSheetCommand("insertrow A" + rowNum)`.
-- **Insert Below**: Calls `executeSheetCommand("insertrow A" + (rowNum + 1))`.
-- **Delete Row**: Calls `executeSheetCommand("deleterow A" + rowNum)`.
-
-### 7. Editable Cells Mode & Template Mapping (`modules/editable-cells.js`)
-Allows template authors to lock the spreadsheet so end-users can only edit designated cells:
-- **API**:
-  ```ts
-  AppGeneral.enableEditableCellsOnly();
-  AppGeneral.disableEditableCellsOnly();
-  AppGeneral.toggleEditableCellsOnly();
-  AppGeneral.setAppMapping(mappingObj);
-  ```
-
-### 8. Plugin Manager (`modules/plugin-manager.js`)
-Allows developers to register custom plugins with lifecycle hooks:
-- **API**:
-  ```ts
-  AppGeneral.registerPlugin("myPlugin", {
-    metadata: { displayName: "My Plugin", description: "Custom feature" },
-    enable: () => { ... },
-    disable: () => { ... },
-    isEnabled: () => true,
-    toggle: () => { ... },
-  });
-  ```
-
-### 9. Cell Change & Status Listeners (`modules/listeners.js`)
-Safely intercepts cell updates and spreadsheet status cycles:
-- **API**:
-  ```ts
-  const unsubscribe = AppGeneral.setupCellChangeListener((coord: string) => {
-    console.log("Cell modified:", coord);
-  });
-  ```
-- **Forwarding Safety**: Intercepts `SocialCalc.EditorSheetStatusCallback` while preserving all 4 internal parameters (`recalcdata, status, arg, editor`), avoiding undefined context dereference during render routines.
+Adds mobile touch inertia scrolling:
+```ts
+AppGeneral.enableTouchScroll();
+AppGeneral.configureTouchScroll({
+  momentumFriction: 0.94, // adjust friction
+  velocityMultiplier: 1.2
+});
+AppGeneral.disableTouchScroll();
+```
+
+### 4. Horizontal Scroll (`modules/horizontal-scroll.js`)
+Programmatic viewport scrolling:
+```ts
+// Scroll horizontally by a relative number of columns
+AppGeneral.scrollHorizontalBy(3);
+
+// Scroll to a specific target column index (1-based)
+AppGeneral.scrollToColumn(5); // Scrolls to column E
+
+// Subscribe to horizontal scroll events
+const unsubscribe = AppGeneral.subscribeHorizontalScroll((info) => {
+  console.log("Current first col:", info.currentFirstCol);
+});
+```
+
+### 5. Editable Cells & Template Locks (`modules/editable-cells.js`)
+Restricts user editing to designated cells while protecting formula and header cells:
+```ts
+// Enable template protection mode
+AppGeneral.enableEditableCellsOnly();
+
+// Define allowed mapping
+AppGeneral.setAppMapping({
+  sheet1: {
+    customerName: "B3",
+    itemsTotal: "D15"
+  }
+});
+
+// Check if a specific cell coordinate is editable
+const canEdit = AppGeneral.isCellEditable(editor, "B3"); // true
+const isLocked = AppGeneral.isCellEditable(editor, "A1"); // false
+```
+
+### 6. Plugin Manager (`modules/plugin-manager.js`)
+Allows registration of custom lifecycle plugins:
+```ts
+AppGeneral.registerPlugin("myCustomPlugin", {
+  metadata: {
+    displayName: "Audit Logger",
+    description: "Logs cell updates to an external service"
+  },
+  enable: () => console.log("Plugin activated"),
+  disable: () => console.log("Plugin deactivated"),
+  isEnabled: () => true
+});
+```
+
+### 7. History (Undo / Redo) (`modules/history.js`)
+```ts
+AppGeneral.undo();
+AppGeneral.redo();
+```
+
+### 8. Exporters & Sheets (`modules/exporters.js`, `modules/sheets.js`)
+```ts
+// Export sheet as CSV string
+const csvData = AppGeneral.getCSVContent();
+
+// Export sheet as HTML string
+const htmlContent = AppGeneral.getCurrentHTMLContent();
+
+// Get full spreadsheet data (save format / MSC)
+const mscData = AppGeneral.getSpreadsheetContent();
+
+// Multi-sheet operations
+AppGeneral.switchSheet("Sheet2");
+AppGeneral.addNewSheet("Expenses");
+AppGeneral.deleteSheet("Sheet3");
+AppGeneral.renameSheet("Sheet1", "Overview");
+```
+
+### 9. Invoice Utilities (`modules/invoice.js`)
+```ts
+import { getInvoiceCoordinates } from "socialcalc-ai";
+
+const coords = getInvoiceCoordinates();
+// Returns standard coordinates for billTo, from, invoiceDetails, items, totals
+```
 
 ---
 
-## 📡 Events Dispatched by SocialCalc
+## 📡 Event-Driven Architecture
+
+`socialcalc-ai` broadcasts standard DOM CustomEvents on the `window` object. This allows any framework (React, Vue, Svelte, Angular, Vanilla JS) to react to spreadsheet changes:
 
-| Event Name | `detail` Payload | Description |
+| Event Name | `event.detail` Structure | Purpose |
 | :--- | :--- | :--- |
-| `socialcalc:cell-edit-request` | `{ coord, text, okfn, cleanup }` | Dispatched when a cell is clicked/tapped (consumed by `CellEditModal`). |
-| `socialcalc:row-header-click` | `{ rowNum, clientX, clientY }` | Dispatched when a row number is clicked (consumed by `RowActionPopover`). |
-| `socialcalc:cell-change` | `{ coord, value }` | Dispatched when any cell value is successfully modified. |
-| `socialcalc:horizontal-scroll`| `{ currentFirstCol, currentColName, totalCols }` | Dispatched when sheet column scrolls. |
-| `socialcalc:plugin-change` | `{ pluginName, state, allStates }` | Dispatched when any plugin is enabled/disabled. |
+| `socialcalc:cell-edit-request` | `{ coord: string, text: string, okfn: Function, cleanup: Function }` | Fired when a cell is clicked/tapped. Consumed by `CellEditModal`. |
+| `socialcalc:row-header-click` | `{ rowNum: number, originalEvent: MouseEvent }` | Fired when a row number index is clicked. Consumed by `RowActionPopover`. |
+| `socialcalc:cell-change` | `{ coord: string, value: string }` | Fired after a cell's value or formula is committed and recalculated. |
+| `socialcalc:horizontal-scroll`| `{ currentFirstCol: number, currentColName: string, totalCols: number }` | Fired whenever the horizontal viewport column changes. |
+| `socialcalc:plugin-change` | `{ pluginName: string, state: boolean, allStates: Record<string, boolean> }` | Fired whenever a plugin is registered, enabled, or disabled. |
+
+### Event Listener Example:
+
+```ts
+window.addEventListener("socialcalc:cell-change", (e: CustomEvent) => {
+  const { coord, value } = e.detail;
+  console.log(`Cell ${coord} changed to: ${value}`);
+});
+```
 
 ---
 
-## 🧪 Testing & Verification
+## 🤖 AI & MultiSheet Calc (MSC) Integration
 
-Run tests anytime you modify the package:
-```bash
-# Run Vitest test suite
-npm test -- --run
+`socialcalc-ai` is built for automated and LLM-driven spreadsheet workflows:
+
+### Generating Spreadsheets via LLMs
+AI agents can generate spreadsheet structures in SocialCalc MSC format (MultiSheet Calc). An MSC document defines multiple named sheets with cell formulas, formats, and values:
+
+```json
+{
+  "sheets": {
+    "Summary": {
+      "content": "cell:A1:t:Quarterly Revenue\ncell:A3:t:Q1\ncell:B3:v:12500\ncell:A4:t:Q2\ncell:B4:v:14200\ncell:A5:t:Total\ncell:B5:v#:=SUM(B3:B4)"
+    }
+  }
+}
+```
 
-# Run TypeScript compilation & Vite build
-npm run build
+Load this directly into `socialcalc-ai`:
 
-# Verify SocialCalc core modularization in Node
-node test-socialcalc.js
+```ts
+import * as AppGeneral from "socialcalc-ai";
+
+AppGeneral.loadWorkbookData(aiGeneratedMscJson);
 ```
+
+---
+
+## 🛡 TypeScript Support
+
+`socialcalc-ai` ships with full type definitions in `index.d.ts`:
+
+```ts
+import * as AppGeneral from "socialcalc-ai";
+import {
+  CellEditModal,
+  CellEditModalProps,
+  HorizontalScrollBarProps,
+  RowActionPopoverProps
+} from "socialcalc-ai";
+```
+
+---
+
+## 💻 Browser & Framework Compatibility
+
+- **Browsers**: Chrome, Edge, Safari, Firefox (Desktop & Mobile).
+- **Frameworks**: React 18+, Ionic React 7+, Next.js (Client Component), Vite, Plain JavaScript.
+- **Runtimes**: Node.js 18+ (for headless calculation & CSV/MSC transformation).
+
+---
+
+## 📦 Release Notes
+
+### v1.0.2
+- **Cell Edit Modal Fix**: Fixed cell click interceptor and mouse delegates so clicking any cell reliably triggers the `CellEditModal` bottom sheet.
+- **Scroll Distortion Fix**: Resolved table border collapse and column misalignment when scrolling past multi-row (`rowspan`) and multi-column (`colspan`) blocks.
+- **Formula Support**: Enhanced modal editing to support formula values (`=SUM(...)`) seamlessly alongside raw numbers, text, and HTML formatting.
+- **Strict Column Sizing**: Enforced CSS pixel widths and `box-sizing: border-box` containment across `<colgroup>` and sizing rows to preserve layout integrity.
+- **Safety Guards**: Added null guards and try/catch protection across SocialCalc workbook control callbacks.
+
+---
+
+## 📜 License & Acknowledgments
+
+- **Original SocialCalc Engine**: Created by Dan Bricklin (co-creator of VisiCalc) and Socialtext.
+- **Modernized `socialcalc-ai` Package**: Maintained and modernized for ES6 modules, React/Ionic UI components, touch physics, and AI workflows by **Anirudh Sharma** under the **MIT License**.
+
+Feel free to open issues and pull requests to help enhance the modern spreadsheet engine!

package/core/core.js

@@ -5186,6 +5186,7 @@
         if (context.showRCHeaders) {
             newcol = document.createElement("col");
             newcol.width = context.rownamewidth;
+            newcol.style.width = context.rownamewidth + "px";
             result.appendChild(newcol);
         }
 
@@ -5197,12 +5198,16 @@
             ) {
                 newcol = document.createElement("col");
                 t = context.colwidth[colnum];
-                if (t) newcol.width = t;
+                if (t) {
+                    newcol.width = t;
+                    newcol.style.width = t + "px";
+                }
                 result.appendChild(newcol);
             }
             if (colpane < context.colpanes.length - 1) {
                 newcol = document.createElement("col");
                 newcol.width = context.defaultpanedividerwidth;
+                newcol.style.width = context.defaultpanedividerwidth + "px";
                 result.appendChild(newcol);
             }
         }
@@ -5218,6 +5223,8 @@
         if (context.showRCHeaders) {
             newcell = document.createElement("td");
             newcell.style.width = context.rownamewidth + "px";
+            newcell.style.minWidth = context.rownamewidth + "px";
+            newcell.style.maxWidth = context.rownamewidth + "px";
             newcell.height = "1";
             result.appendChild(newcell);
         }
@@ -5230,13 +5237,21 @@
             ) {
                 newcell = document.createElement("td");
                 t = context.colwidth[colnum];
-                if (t) newcell.width = t;
+                if (t) {
+                    newcell.width = t;
+                    newcell.style.width = t + "px";
+                    newcell.style.minWidth = t + "px";
+                    newcell.style.maxWidth = t + "px";
+                }
                 newcell.height = "1";
                 result.appendChild(newcell);
             }
             if (colpane < context.colpanes.length - 1) {
                 newcell = document.createElement("td");
                 newcell.width = context.defaultpanedividerwidth;
+                newcell.style.width = context.defaultpanedividerwidth + "px";
+                newcell.style.minWidth = context.defaultpanedividerwidth + "px";
+                newcell.style.maxWidth = context.defaultpanedividerwidth + "px";
                 newcell.height = "1";
                 result.appendChild(newcell);
             }
@@ -5289,8 +5304,8 @@
                 if (rownum === firstVisibleRow && colnum === firstVisibleCol) {
                     // This is the visible start of the scrolled spanned cell in this pane!
                     isSpanContinuation = true;
-                    spanColSpan = Math.min(spanEndCol, panecollimits ? panecollimits.last : spanEndCol) - firstVisibleCol + 1;
-                    spanRowSpan = Math.min(spanEndRow, panerowlimits ? panerowlimits.last : spanEndRow) - firstVisibleRow + 1;
+                    spanColSpan = Math.max(1, Math.min(spanEndCol, panecollimits ? panecollimits.last : spanEndCol) - firstVisibleCol + 1);
+                    spanRowSpan = Math.max(1, Math.min(spanEndRow, panerowlimits ? panerowlimits.last : spanEndRow) - firstVisibleRow + 1);
                     cell = originCell;
                 } else {
                     // Covered by the visible span in this pane -- skip
@@ -5416,6 +5431,9 @@
             } else stylestr += "text-align:left;";
         }
 
+        var activeColSpan = isSpanContinuation ? spanColSpan : (result.colSpan || cell.colspan || 1);
+        var activeRowSpan = isSpanContinuation ? spanRowSpan : (result.rowSpan || cell.rowspan || 1);
+
         num = cell.bt;
         if (num && (!isSpanContinuation || (originCR && rownum === originCR.row))) {
             stylestr += "border-top:" + sheetobj.borderstyles[num] + ";";
@@ -5428,12 +5446,12 @@
             if (
                 context.CellInPane(
                     rownum,
-                    colnum + (isSpanContinuation ? spanColSpan : (cell.colspan || 1)),
+                    colnum + activeColSpan,
                     rowpane,
                     colpane
                 )
             )
-                t = SocialCalc.crToCoord(colnum + (isSpanContinuation ? spanColSpan : (cell.colspan || 1)), rownum);
+                t = SocialCalc.crToCoord(colnum + activeColSpan, rownum);
             else t = "nomatch";
             if (context.cellskip[t]) t = context.cellskip[t];
             if (!sheetobj.cells[t] || !sheetobj.cells[t].bl)
@@ -5446,13 +5464,13 @@
         } else if (context.showGrid) {
             if (
                 context.CellInPane(
-                    rownum + (isSpanContinuation ? spanRowSpan : (cell.rowspan || 1)),
+                    rownum + activeRowSpan,
                     colnum,
                     rowpane,
                     colpane
                 )
             )
-                t = SocialCalc.crToCoord(colnum, rownum + (isSpanContinuation ? spanRowSpan : (cell.rowspan || 1)));
+                t = SocialCalc.crToCoord(colnum, rownum + activeRowSpan);
             else t = "nomatch";
             if (context.cellskip[t]) t = context.cellskip[t];
             if (!sheetobj.cells[t] || !sheetobj.cells[t].bt)
@@ -5483,6 +5501,8 @@
         }
 
         result.style.cssText = stylestr;
+        result.style.boxSizing = "border-box";
+        result.style.overflow = "hidden";
 
         //!!!!!!!!!
         // NOTE: csss and cssc are not supported yet.

package/core/spreadsheet-control.js

@@ -7014,8 +7014,13 @@ SocialCalc.SpreadsheetCmdTable = {
   // this is for checkmark toggling
   SocialCalc.Callbacks.ToggleCell = function (cellname) {
     var control = SocialCalc.GetCurrentWorkBookControl();
+    if (!control || !control.currentSheetButton || !control.workbook || !control.workbook.sheetArr) {
+      return;
+    }
     var sheetid = control.currentSheetButton.id;
+    if (!control.workbook.sheetArr[sheetid]) return;
     var sheetobj = control.workbook.sheetArr[sheetid].sheet;
+    if (!sheetobj || !sheetobj.cells) return;
     var cell = sheetobj.cells[cellname];
     var sheetname = sheetobj.sheetname;
 

package/core/table-editor.js

@@ -1582,22 +1582,33 @@
             mouseinfo.registeredElements.push({ element: element, editor: editor });
         }
 
+        if (!SocialCalc.ProcessEditorMouseDownHandler) {
+            SocialCalc.ProcessEditorMouseDownHandler = function (e) {
+                return SocialCalc.ProcessEditorMouseDown(e);
+            };
+        }
+        if (!SocialCalc.ProcessEditorDblClickHandler) {
+            SocialCalc.ProcessEditorDblClickHandler = function (e) {
+                return SocialCalc.ProcessEditorDblClick(e);
+            };
+        }
+
         if (element.addEventListener) {
             // DOM Level 2 -- Firefox, et al
             element.addEventListener(
                 "mousedown",
-                SocialCalc.ProcessEditorMouseDown,
+                SocialCalc.ProcessEditorMouseDownHandler,
                 false
             );
             element.addEventListener(
                 "dblclick",
-                SocialCalc.ProcessEditorDblClick,
+                SocialCalc.ProcessEditorDblClickHandler,
                 false
             );
         } else if (element.attachEvent) {
             // IE 5+
-            element.attachEvent("onmousedown", SocialCalc.ProcessEditorMouseDown);
-            element.attachEvent("ondblclick", SocialCalc.ProcessEditorDblClick);
+            element.attachEvent("onmousedown", SocialCalc.ProcessEditorMouseDownHandler);
+            element.attachEvent("ondblclick", SocialCalc.ProcessEditorDblClickHandler);
         } else {
             // don't handle this
             throw "Browser not supported";
@@ -1629,21 +1640,21 @@
                 // DOM Level 2
                 oldelement.removeEventListener(
                     "mousedown",
-                    SocialCalc.ProcessEditorMouseDown,
+                    SocialCalc.ProcessEditorMouseDownHandler || SocialCalc.ProcessEditorMouseDown,
                     false
                 );
                 oldelement.removeEventListener(
                     "dblclick",
-                    SocialCalc.ProcessEditorDblClick,
+                    SocialCalc.ProcessEditorDblClickHandler || SocialCalc.ProcessEditorDblClick,
                     false
                 );
             } else if (oldelement.detachEvent) {
                 // IE
                 oldelement.detachEvent(
                     "onmousedown",
-                    SocialCalc.ProcessEditorMouseDown
+                    SocialCalc.ProcessEditorMouseDownHandler || SocialCalc.ProcessEditorMouseDown
                 );
-                oldelement.detachEvent("ondblclick", SocialCalc.ProcessEditorDblClick);
+                oldelement.detachEvent("ondblclick", SocialCalc.ProcessEditorDblClickHandler || SocialCalc.ProcessEditorDblClick);
             }
             mouseinfo.registeredElements.splice(i, 1);
         }
@@ -3772,18 +3783,6 @@
             return;
         }
 
-        if ((vamount == 1 || vamount == -1) && hamount == 0) {
-            // special case quick scrolls
-            if (vamount == 1) {
-                editor.ScrollTableUpOneRow();
-            } else {
-                editor.ScrollTableDownOneRow();
-            }
-            if (editor.ecell) editor.SetECellHeaders("selected");
-            editor.SchedulePositionCalculations();
-            return;
-        }
-
         // Do a gross move and render
 
         if (vamount != 0 || hamount != 0) {
@@ -3874,215 +3873,13 @@
     };
 
     SocialCalc.ScrollTableUpOneRow = function (editor) {
-        var toprow,
-            rowpane,
-            rownum,
-            colnum,
-            colpane,
-            cell,
-            oldrownum,
-            maxspan,
-            newbottomrow,
-            newrow,
-            oldchild,
-            bottomrownum;
-        var rowneedsrefresh = {};
-
-        var context = editor.context;
-        var sheetobj = context.sheetobj;
-        var tableobj = editor.fullgrid;
-
-        var tbodyobj;
-
-        tbodyobj = tableobj.lastChild;
-
-        toprow = context.showRCHeaders ? 2 : 1;
-        for (rowpane = 0; rowpane < context.rowpanes.length - 1; rowpane++) {
-            toprow +=
-                context.rowpanes[rowpane].last - context.rowpanes[rowpane].first + 2; // skip pane and spacing row
-        }
-
-        tbodyobj.removeChild(tbodyobj.childNodes[toprow]);
-
-        context.rowpanes[rowpane].first++;
-        context.rowpanes[rowpane].last++;
-        editor.FitToEditTable();
-        context.CalculateColWidthData(); // Just in case, since normally done in RenderSheet
-
-        newbottomrow = context.RenderRow(context.rowpanes[rowpane].last, rowpane);
-        tbodyobj.appendChild(newbottomrow);
-
-        // if scrolled off a row with starting rowspans, replace rows for the largest rowspan
-
-        var maxrowspan = 1;
-        oldrownum = context.rowpanes[rowpane].first - 1;
-
-        for (colpane = 0; colpane < context.colpanes.length; colpane++) {
-            for (
-                colnum = context.colpanes[colpane].first;
-                colnum <= context.colpanes[colpane].last;
-                colnum++
-            ) {
-                var coord = SocialCalc.crToCoord(colnum, oldrownum);
-                if (context.cellskip[coord]) continue;
-                cell = sheetobj.cells[coord];
-                if (cell && cell.rowspan > maxrowspan) maxrowspan = cell.rowspan;
-            }
-        }
-
-        if (maxrowspan > 1) {
-            for (rownum = 1; rownum < maxrowspan; rownum++) {
-                if (rownum + oldrownum >= context.rowpanes[rowpane].last) break;
-                newrow = context.RenderRow(rownum + oldrownum, rowpane);
-                oldchild = tbodyobj.childNodes[toprow + rownum - 1];
-                tbodyobj.replaceChild(newrow, oldchild);
-            }
-        }
-
-        // if added a row that includes rowspans from above, update the size of those to include new row
-
-        bottomrownum = context.rowpanes[rowpane].last;
-
-        for (colpane = 0; colpane < context.colpanes.length; colpane++) {
-            for (
-                colnum = context.colpanes[colpane].first;
-                colnum <= context.colpanes[colpane].last;
-                colnum++
-            ) {
-                coord = context.cellskip[SocialCalc.crToCoord(colnum, bottomrownum)];
-                if (!coord) continue; // only look at spanned cells
-                rownum = context.coordToCR[coord].row - 0;
-                if (
-                    rownum == context.rowpanes[rowpane].last ||
-                    rownum < context.rowpanes[rowpane].first
-                )
-                    continue; // this row (colspan) or starts above pane
-                cell = sheetobj.cells[coord];
-                if (cell && cell.rowspan > 1) rowneedsrefresh[rownum] = true; // remember row num to update
-            }
-        }
-
-        for (rownum in rowneedsrefresh) {
-            newrow = context.RenderRow(rownum, rowpane);
-            oldchild =
-                tbodyobj.childNodes[
-                toprow + (rownum - context.rowpanes[rowpane].first)
-                ];
-            tbodyobj.replaceChild(newrow, oldchild);
-        }
-
-        return tableobj;
+        SocialCalc.ScrollRelativeBoth(editor, 1, 0);
+        return editor.fullgrid;
     };
 
     SocialCalc.ScrollTableDownOneRow = function (editor) {
-        var toprow,
-            rowpane,
-            rownum,
-            colnum,
-            colpane,
-            cell,
-            newrownum,
-            maxspan,
-            newbottomrow,
-            newrow,
-            oldchild,
-            bottomrownum,
-            maxrowspan,
-            coord;
-        var rowneedsrefresh = {};
-
-        var context = editor.context;
-        var sheetobj = context.sheetobj;
-        var tableobj = editor.fullgrid;
-
-        var tbodyobj;
-
-        tbodyobj = tableobj.lastChild;
-
-        toprow = context.showRCHeaders ? 2 : 1;
-        for (rowpane = 0; rowpane < context.rowpanes.length - 1; rowpane++) {
-            toprow +=
-                context.rowpanes[rowpane].last - context.rowpanes[rowpane].first + 2; // skip pane and spacing row
-        }
-
-        tbodyobj.removeChild(
-            tbodyobj.childNodes[
-            toprow +
-            (context.rowpanes[rowpane].last - context.rowpanes[rowpane].first)
-            ]
-        );
-
-        context.rowpanes[rowpane].first--;
-        context.rowpanes[rowpane].last--;
-        editor.FitToEditTable();
-        context.CalculateColWidthData(); // Just in case, since normally done in RenderSheet
-
-        newrow = context.RenderRow(context.rowpanes[rowpane].first, rowpane);
-        tbodyobj.insertBefore(newrow, tbodyobj.childNodes[toprow]);
-
-        // if inserted a row with starting rowspans, replace rows for the largest rowspan
-
-        maxrowspan = 1;
-        newrownum = context.rowpanes[rowpane].first;
-
-        for (colpane = 0; colpane < context.colpanes.length; colpane++) {
-            for (
-                colnum = context.colpanes[colpane].first;
-                colnum <= context.colpanes[colpane].last;
-                colnum++
-            ) {
-                coord = SocialCalc.crToCoord(colnum, newrownum);
-                if (context.cellskip[coord]) continue;
-                cell = sheetobj.cells[coord];
-                if (cell && cell.rowspan > maxrowspan) maxrowspan = cell.rowspan;
-            }
-        }
-
-        if (maxrowspan > 1) {
-            for (rownum = 1; rownum < maxrowspan; rownum++) {
-                if (rownum + newrownum > context.rowpanes[rowpane].last) break;
-                newrow = context.RenderRow(rownum + newrownum, rowpane);
-                oldchild = tbodyobj.childNodes[toprow + rownum];
-                tbodyobj.replaceChild(newrow, oldchild);
-            }
-        }
-
-        // if last row now includes rowspans or rowspans from above, update the size of those to remove deleted row
-
-        bottomrownum = context.rowpanes[rowpane].last;
-
-        for (colpane = 0; colpane < context.colpanes.length; colpane++) {
-            for (
-                colnum = context.colpanes[colpane].first;
-                colnum <= context.colpanes[colpane].last;
-                colnum++
-            ) {
-                coord = SocialCalc.crToCoord(colnum, bottomrownum);
-                cell = sheetobj.cells[coord];
-                if (cell && cell.rowspan > 1) {
-                    rowneedsrefresh[bottomrownum] = true; // need to update this row
-                    continue;
-                }
-                coord = context.cellskip[SocialCalc.crToCoord(colnum, bottomrownum)];
-                if (!coord) continue; // only look at spanned cells
-                rownum = context.coordToCR[coord].row - 0;
-                if (rownum == bottomrownum || rownum < context.rowpanes[rowpane].first)
-                    continue; // this row (colspan) or starts above pane
-                cell = sheetobj.cells[coord];
-                if (cell && cell.rowspan > 1) rowneedsrefresh[rownum] = true; // remember row num to update
-            }
-        }
-
-        for (rownum in rowneedsrefresh) {
-            newrow = context.RenderRow(rownum, rowpane);
-            oldchild =
-                tbodyobj.childNodes[
-                toprow + (rownum - context.rowpanes[rowpane].first)
-                ];
-            tbodyobj.replaceChild(newrow, oldchild);
-        }
-
-        return tableobj;
+        SocialCalc.ScrollRelativeBoth(editor, -1, 0);
+        return editor.fullgrid;
     };
 
     // *************************************

package/modules/init.js

@@ -8,9 +8,10 @@ if (typeof window !== "undefined" && window.SocialCalc) {
   SocialCalc = global.SocialCalc;
 } else {
   console.error("SocialCalc not found in global scope");
-  SocialCalc = {}; // Fallback to prevent errors
 }
 
+import { setupMouseListener } from "./listeners.js";
+
 export function initializeApp(data) {
   /* Initializes the spreadsheet */
   // Try multiple candidate IDs so the renderer can namespace its elements
@@ -91,4 +92,5 @@ export function initializeApp(data) {
   }
 
   spreadsheet.DoOnResize();
+  setupMouseListener();
 }

package/modules/listeners.js

@@ -30,6 +30,7 @@ export function enableCellEditModal() {
   if (typeof window !== "undefined" && window.SocialCalc) {
     window.SocialCalc.isCellEditModalEnabled = () => true;
   }
+  setupMouseListener();
 }
 
 /**
@@ -57,6 +58,9 @@ export function toggleCellEditModal(show) {
   if (typeof window !== "undefined" && window.SocialCalc) {
     window.SocialCalc.isCellEditModalEnabled = () => _cellEditModalEnabled;
   }
+  if (_cellEditModalEnabled) {
+    setupMouseListener();
+  }
   return _cellEditModalEnabled;
 }
 
@@ -167,7 +171,15 @@ export function setupMouseListener() {
   if (typeof window !== "undefined" && window.SocialCalc) {
     SocialCalc = window.SocialCalc;
   }
-  if (!SocialCalc || !SocialCalc.EditorMouseInfo) return;
+  if (!SocialCalc || !SocialCalc.EditorMouseInfo) {
+    if (typeof window !== "undefined") {
+      setTimeout(setupMouseListener, 50);
+    }
+    return;
+  }
+
+  if (SocialCalc._customMouseListenerInstalled) return;
+  SocialCalc._customMouseListenerInstalled = true;
 
   const originalDblClick = SocialCalc.ProcessEditorDblClick;
 
@@ -292,7 +304,11 @@ export function setupMouseListener() {
 
     // Toggle Cell Callback
     if (SocialCalc.Callbacks && SocialCalc.Callbacks.ToggleCell) {
-      SocialCalc.Callbacks.ToggleCell(result.coord);
+      try {
+        SocialCalc.Callbacks.ToggleCell(result.coord);
+      } catch (err) {
+        // Ignore toggle cell errors in custom environments
+      }
     }
 
     // Move ECell (Updates Selection)
@@ -367,7 +383,7 @@ export function setupMouseListener() {
   const originalKeyPress = SocialCalc.ProcessKeyPress;
 
   SocialCalc.ProcessKeyDown = function (e) {
-    const isModalOpen = !!document.querySelector(".sc-cell-edit-backdrop");
+    const isModalOpen = !!document.querySelector(".sc-cell-modal-backdrop, .sc-cell-edit-backdrop, .sc-modal-container");
     const activeElement = document.activeElement;
     const isTypingInInput =
       activeElement &&
@@ -386,7 +402,7 @@ export function setupMouseListener() {
   };
 
   SocialCalc.ProcessKeyPress = function (e) {
-    const isModalOpen = !!document.querySelector(".sc-cell-edit-backdrop");
+    const isModalOpen = !!document.querySelector(".sc-cell-modal-backdrop, .sc-cell-edit-backdrop, .sc-modal-container");
     const activeElement = document.activeElement;
     const isTypingInInput =
       activeElement &&
@@ -416,8 +432,8 @@ function triggerCustomModal(editor) {
   if (!editor || !editor.ecell) return;
 
   const coord = editor.ecell.coord;
-  const sheet = editor.context.sheetobj;
-  const cell = sheet.GetAssuredCell(coord);
+  const sheet = editor.context ? editor.context.sheetobj : null;
+  const cell = sheet && sheet.GetAssuredCell ? sheet.GetAssuredCell(coord) : null;
 
   // Hide the native input box and cancel its timer
   if (editor.inputBox) {
@@ -442,25 +458,35 @@ function triggerCustomModal(editor) {
 
   // Determine initial text
   let initialText = "";
-  if (cell.datavalue !== undefined && cell.datavalue !== null) {
-    initialText = String(cell.datavalue);
-  } else if (cell.displaystring !== undefined && cell.displaystring !== null) {
-    initialText = String(cell.displaystring);
+  if (cell) {
+    if (cell.formula) {
+      initialText = "=" + cell.formula;
+    } else if (cell.datavalue !== undefined && cell.datavalue !== null) {
+      initialText = String(cell.datavalue);
+    } else if (cell.displaystring !== undefined && cell.displaystring !== null) {
+      initialText = String(cell.displaystring);
+    }
+  }
+  if (!initialText && SocialCalc && SocialCalc.GetCellContents && sheet) {
+    initialText = SocialCalc.GetCellContents(sheet, coord) || "";
   }
 
   // Callback when user confirms edit in Modal
   const handleOk = (newValue) => {
     let cmd = "";
-    const isNum = !isNaN(Number(newValue)) && newValue.trim() !== "";
-
-    if (isNum) {
-      cmd = `set ${coord} value n ${newValue}`;
+    if (typeof newValue === "string" && newValue.startsWith("=")) {
+      cmd = `set ${coord} formula ${newValue.slice(1)}`;
     } else {
-      const isHtml = /<[a-z][\s\S]*>/i.test(newValue);
-      if (isHtml) {
-        cmd = `set ${coord} text th ${newValue}\nset ${coord} textvalueformat text-html`;
+      const isNum = !isNaN(Number(newValue)) && newValue.trim() !== "";
+      if (isNum) {
+        cmd = `set ${coord} value n ${newValue}`;
       } else {
-        cmd = `set ${coord} text t ${newValue}`;
+        const isHtml = /<[a-z][\s\S]*>/i.test(newValue);
+        if (isHtml) {
+          cmd = `set ${coord} text th ${newValue}\nset ${coord} textvalueformat text-html`;
+        } else {
+          cmd = `set ${coord} text t ${newValue}`;
+        }
       }
     }
 
@@ -529,3 +555,8 @@ export function setupCellChangeListener(callback) {
   };
 }
 
+// Auto-initialize mouse listener if in browser environment
+if (typeof window !== "undefined") {
+  setupMouseListener();
+}
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "socialcalc-ai",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Modernized, modular spreadsheet calculation engine and React/Ionic UI suite with AI formula and template capabilities.",
   "type": "module",
   "main": "index.js",