# UnifiedSpread dev-31.0.0 UnifiedScriptEngineFoundation

## Purpose

This milestone adds the first browser-safe scripting layer for UnifiedSpread.
The goal is not to execute VBA directly.  Instead, UnifiedSpread provides a
JavaScript-syntax based script engine that can operate on workbook, worksheet,
range and cell APIs.  XLSM/VBA compatibility is handled by preserving macro
parts where possible and converting supported workbook logic into UnifiedSpread
Script modules.

## Added runtime modules

- `scripts/scripting/unified_spread_script_engine.js`
- `scripts/scripting/script_runtime_api.js`
- `scripts/scripting/script_sandbox.js`
- `scripts/scripting/script_module_registry.js`
- `scripts/compatibility/vba/vba_lexer.js`
- `scripts/compatibility/vba/vba_to_unified_script_transpiler.js`
- `scripts/compatibility/vba/vba_compatibility_report.js`

## Script API scope

Supported script access is intentionally limited to:

- workbook metadata
- active sheet and named sheet access
- range and cell value/formula/style operations
- simple UI message/input abstraction
- event binding metadata

Direct browser APIs, DOM access, network access, local storage, host callbacks,
COM, Shell and Win32 API calls are not available to scripts.

## VBA conversion policy

The first transpiler stage covers common worksheet automation patterns:

- `Sub` / `Function`
- `Dim`
- `If` / `Else` / `End If`
- simple `For ... To ... Next`
- `Range("A1").Value = ...`
- `Range("A1").Formula = ...`
- `Cells(r, c).Value = ...`
- `Cells(r, c).Formula = ...`
- `MsgBox ...`

Unsupported lines are preserved as `// TODO VBA conversion:` comments in the
converted script.  Browser-hostile lines such as `Declare`, `Shell`,
`CreateObject`, `GetObject`, `FileSystemObject` and direct file-system
statements are reported as unsupported and are never executed.

## Persistence

Script metadata is stored in `workbook.config.scripting` and, for native `.uspdx`
packages, also in `shared/scripts.json`.  XLSX/XLSM round-trip continues to use
UnifiedSpread hidden metadata bridge for native scripting metadata.

## Commands

- `spread.script.report`
- `spread.script.module.sample`
- `spread.script.run.first`
- `spread.script.run.sample`
- `spread.vba.transpile.sample`
- `spread.vba.compat.report`