socialcalc-ai 1.0.0 → 1.0.1

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
 
-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.
+Below is a complete, minimal working example showing how to mount the spreadsheet engine and hook up the interactive React UI suite:
 
-> ⚠️ **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.
+```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";
+
+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);
+
+    // 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;
+```
+
+---
+
+## 🌐 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>
+```
 
 ---
 
-## 📁 Package Architecture
+## 📁 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,273 @@ 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
 
-| Event Name | `detail` Payload | Description |
+`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 | `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)"
+    }
+  }
+}
+```
+
+Load this directly into `socialcalc-ai`:
 
-# Run TypeScript compilation & Vite build
-npm run build
+```ts
+import * as AppGeneral from "socialcalc-ai";
+
+AppGeneral.loadWorkbookData(aiGeneratedMscJson);
+```
+
+---
 
-# Verify SocialCalc core modularization in Node
-node test-socialcalc.js
+## 🛡 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).
+
+---
+
+## 📜 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/package.json

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