Office Scripts

Witan can run Excel Office Script TypeScript through witan xlsx exec. Use this when you want to reuse scripts written for Excel on the web, or when an agent should work in the same scripting language and object model that Excel exposes.

Office Scripts are a scripting surface over the same Witan workbook engine used by the xlsx.* API, Calc, and Render. Workbook edits still run in the same sandboxed exec session and return structured JSON.

Running A Script

Office Scripts are normally authored as TypeScript in Excel. Witan follows that convention: exec accepts .ts scripts, compiles TypeScript before execution, and then runs the script in the headless workbook sandbox.

Start the script with an @office-script pragma and define function main(workbook: ExcelScript.Workbook). Witan passes an ExcelScript-like workbook object to main:

witan xlsx exec report.xlsx --save --script ./format-summary.ts

// @office-script
function main(workbook: ExcelScript.Workbook) {
  const sheet = workbook.getWorksheet("Summary")
  const range = sheet.getRange("B2:B20")

  range.setNumberFormat("$#,##0")
  workbook.getApplication().calculate(ExcelScript.CalculationType.full)

  return range.getTexts()
}

If --input-json is provided, Witan passes the parsed input as the second main argument:

// @office-script
function main(
  workbook: ExcelScript.Workbook,
  input: { discountRate: number }
) {
  const sheet = workbook.getWorksheet("Inputs")
  sheet.getRange("B5").setValue(input.discountRate)
  workbook.getApplication().calculate(ExcelScript.CalculationType.full)
  return workbook.getWorksheet("Summary").getRange("F25").getText()
}

Why Use It

Use Office Script-style code when:

• You already have scripts from Excel on the web that you want to adapt.
• You want to use Excel's workbook/worksheet/range object model instead of Witan's xlsx.* function calls.
• You want the same agent logic to target both an Excel add-in environment and Witan's headless Excel-compatible runtime.
• You want Office Script chart, table, range-formatting, conditional-formatting, data-validation, comment, or pivot-table methods that map naturally to existing Excel examples.

Use CLI Scripting and the xlsx API when you want the Witan-native API surface, including compact reads, dependency tracing, sweepInputs, lint, render previews, and structured feature models.

Rendering From Office Scripts

Office Scripts in Excel do not have a screenshot API for Witan's verifier workflow, but Witan's exec runtime still exposes the render preview helper around the Office Script entry point. Call xlsx.previewStyles(wb, range) when an Office Script wants to render a range after editing it:

// @office-script
async function main(workbook: ExcelScript.Workbook) {
  const sheet = workbook.getWorksheet("Summary")
  sheet.getRange("B2:B20").setNumberFormat("$#,##0")
  workbook.getApplication().calculate(ExcelScript.CalculationType.full)

  await xlsx.previewStyles(wb, "Summary!A1:F20")
  return sheet.getRange("B2:B20").getTexts()
}

previewStyles is a Witan bridge, not an ExcelScript workbook method. The Office Script object model stays Excel-compatible, while the enclosing Witan runtime can still request a render preview for verification.

Other Witan-only analysis APIs are not part of the Office Script workbook object model. That includes lint diagnostics, dependency tracing, sweepInputs, formula-evaluation helpers, describeSheet, tableLookup, compact TSV reads, and structured xlsx.* feature models. Use Witan-native CLI Scripting when those features are the main goal.

Implemented Surface

The Office Script runtime covers common ExcelScript workflows across:

Unsupported Office Script members throw explicit NotImplementedError-style errors rather than silently doing nothing. That makes compatibility gaps visible while adapting scripts.

Compatibility Gaps

Witan implements the Office Script surface that maps to headless workbook editing, calculation, rendering, and verification. It does not try to emulate Excel UI state, user selection, external services, or every Office Script object family.

Notable unsupported areas include:

The error message names the missing member, for example NotImplementedError: ExcelScript: Workbook.getBindings is not implemented by xlsx-serve.

Calculation And Results

Office Script application.calculate, worksheet.calculate, and range.calculate use the same calculation engine as witan xlsx calc. Formula-affecting writes update cached values through the workbook engine, and explicit calculation calls are available when an Office Script expects them.

The return value from main is serialized as JSON and becomes the result field of the exec response. Use print(...) for progress output during the script.

Sandbox

Office Script-style code runs in the same exec sandbox as Witan-native scripts:

• No filesystem access.
• No network access.
• No imports.
• The script can only manipulate the open workbook through the supplied workbook object and the preloaded runtime.

See CLI Scripting for the shared exec workflow and xlsx API for the Witan-native scripting API.