Gridcraft

GridCraft

Audit basis: this checkout is tag v0.15.0, commit 30b210b4ef03b30616923465efa70766cefba379 ("Release 0.15.0", 2026-11-01; the v0.14.2 ref was fetched for id diffs). The installed /Applications/GridCraft.app matches this tag (CFBundleIdentifier ai.storyteller.gridcraft, binary prints GridCraft 0.15.0). Verify against your installed version — the ArtCraft Launcher auto-updates. Counts and formats below were re-derived from this tag's code and generated docs; every claim carries a repo-relative pointer.

v0.14.2 → v0.15.0 is a compatibility wave with no command-registry change (363 non-test engine ids at both tags in this audit's extract; MCP tools 22 = 22 with only write_range's schema changed; CLI, control dispatch, UI commands and 19 languages unchanged). What landed: .xls files give up their cell formatting, with font family and charset kept on import (#2495, #3052); xlsx writes _xlfn. prefixes for STOCKHISTORY, TRANSLATE and DETECTLANGUAGE (#2793) and keeps the workbook view settings (sheet tabs, scroll bars, tab ratio) across an open + save (#3062); Google Sheets' _xlfn._xlws.DUMMYFUNCTION export wrapper opens as the original formula (#3075); CSV and text open detect each column's date order (#3043); formula edge cases match Excel — YEARFRAC basis 0, MOD large quotients, NUMBERVALUE, PERCENTRANK significance limits (#2657, #2979, #2980); range.setValues takes parse: false to store strings as typed, reports what converted, and "" clears (#3042/#2255); a locked cell's edit is refused before a draft can block Save (#3040); each window keeps its own ribbon tab, so Table Design stays active (#3041); Alt, H, B opens the Borders menu with its item letters (#3077); Esc leaves the in-cell text field before closing the file view (#3050); Intel Macs skip wgpu's indirect-call validation shaders (#3039); a Dock quit brings the asking window to the front (#3083); and the Merge & Center label is part of its split button (#3024). ⚠️ Generated docs/parity-checklist.md reads 276 / 292 (94.5 %) and is byte-identical at v0.14.2 and v0.15.0 — the previous audit's "275/291" did not match its own pinned tag; the generated file wins.

v0.14.0–0.14.2 adds a macro system: Automate ▸ Record Macro (name, shortcut — one letter, alone or after Ctrl+Shift — and description), a Macros dialog with Trust Scripts for file-loaded scripts, a macro step editor with a debug bar and grid overlays, macro.* engine commands (below), macros persisted into .xlsx and a save that refuses a macro that skipped the check, dry-run journaling discipline and undo-group rollback. Also: CSV export values: true writes raw values for automation (#2648), password-protected Excel workbooks open again (hash-size integrity key, #2712), Ctrl+Arrow / Ctrl+Shift+Arrow jump to the data edge during formula pointing, print outputs checkbox cells as boxes and structured references to @-prefixed columns in double brackets, a status-bar statistic copies its value on click, the control channel enforces its 10 s token deadline and caps waiting connections, and a large function-parity wave landed (YEARFRAC basis 0, MOD, NUMBERVALUE, PERCENTRANK, IMSQRT, HYPERLINK, UNICHAR, base conversions, F/T/BINOM/BETA distribution edges).

Overview

GridCraft is an open-source, clean-room reimplementation of Microsoft Excel's workflow in pure Rust (README.md), by the ArtCraft team; source: github.com/storytold/gridcraft. XLSX is the native document format, and the architecture is engine-first: every ribbon button, menu item, dialog OK, keystroke and mouse gesture is a command (crates/engine/src/cmd/), reachable over a JSON control channel, an MCP server and a headless CLI. Maturity is alpha: the core workflow (open XLSX → edit/format → sort/filter → chart/pivot → print to PDF → save XLSX) works end to end, but the project's own estimate is ~75% feature breadth and ~50% "ready for real work" (docs/target-app-parity.md summary; ROADMAP.md). It runs natively on macOS 11+, Windows, Linux and BSD, and in the browser via WebAssembly (apps/gridcraft-web). The UI migrated to egui 0.37 this release.

Capabilities (verified)

Core workbook and editing

• One native window per workbook window (new this release): view.newWindow opens another window on the same workbook — no clone, saving from either window saves it — view.arrangeAll tiles the windows, window.list/window.close are new engine commands, and a cell draft stays in its workbook (crates/engine/src/cmd/extra.rs:167; PRs #2616–#2619). Several workbooks open side by side; view.switchWindows and window.activate {index} switch between them.
• Three built-in samples budget, sales, grades: file.new {sample}, CLI --sample, URL ?sample= (crates/engine/src/sample.rs).
• 363 engine commands (354 at v0.13.0; +9 macro.* — macro.check, macro.debug, macro.delete, macro.get, macro.list, macro.record, macro.rename, macro.run, macro.save; earlier wave added window.close, window.list; unchanged at v0.15.0); 276 of the 292 Excel catalog ids implemented, 94.5% — crates/engine/src/cmd/*.rs, crates/engine/src/catalog.rs, generated docs/parity-checklist.md (identical at v0.14.2 and v0.15.0; the previous audit's 275/291 was stale).
• Formatting: fonts, fills, borders, alignment, merges, Excel's number-format language (crates/numfmt), cell styles and themes, conditional formatting (CellIs, expression, text, top-10, above-average, time period, duplicate/unique, colour scale, data bar, icon set) and data validation (whole, decimal, list, date, time, text length, custom).
• Tables (structured references, header/total rows, banded rows, style gallery, Resize Table, remove duplicates), notes and threaded comments with replies/resolution/timestamps (editing a note or comment keeps its thread now, PR #2515), hyperlinks, pictures floating or inside a cell (PNG/JPEG only), shapes and text boxes (9 kinds), checkboxes, freehand ink with Ink to Shape, sparklines (line/column/win-loss; removed when their row or column is deleted, PR #2551).
• Editing: fill handle (drag; right-drag opens Copy Cells / Fill Series / Fill Formatting Only / Fill Without Formatting / Series…), AutoFill with the Auto Fill Options button, Flash Fill, Paste Special, Format Painter, Find/Replace, Go To (lists every sheet's defined names, takes several comma-separated targets), Watch Window, undo/redo with bounded history.
• AutoSum: a selected row gets its total to the right, as in Excel (PR #2561).
• Options ▸ Formulas: Maximum Iterations and Maximum Change fields (UI for the existing calc settings, PR #2493).
• Background error checking: green corner, warning button, Convert to Number, Circular References submenu.
• AutoSave switch in the title bar, persisted across restarts; it saves only workbooks that already have a file. Closing the window with unsaved work asks first.
• Slicers exist as in-sheet filter widgets over one table column, but are not written to XLSX.
• Format Chart Area: Chart Type offers the stacked and 100% stacked types and marks the current one (PR #2605).
• Opening a saved workbook without recalculating it is supported (PR #2512) — useful for inspection of files whose volatile formulas you do not want to run.

Formulas and calculation

• 513 of Excel's 523 worksheet functions by name, 504 working (96.4%) — unchanged — including dynamic arrays and spilling, LET/LAMBDA (a self-calling LAMBDA stops at 140 calls with #NUM!), MAP/REDUCE/SCAN/BYROW/BYCOL/MAKEARRAY, GROUPBY/PIVOTBY, structured table references, iterative calculation for circular references — docs/function-parity.md, crates/functions/src/, crates/calc/src/eval.rs.
• Evaluate without editing: gridcraft-cli eval '=SUM(A1:A9)' --in book.xlsx or formulas.evaluate. A formula that could not be typed into a cell is an error that says why, not a silent #VALUE!.
• Calculation settings travel with the workbook: automatic / automaticExceptTables / manual, iterative on/off, max iterations and max change (formulas.calculationOptions).
• Formula fixes this release: PERCENTRANK no longer returns #NUM! for very large significance, MINVERSE's rounding cutoff scales to the input matrix, ISOWEEKNUM/WEEKNUM(…,21) fixed for the first days of the calendar, YEARFRAC basis 0 fixed for February-end starts and 31st ends, IMSQRT no stray real part for negative reals, and range parsing fixed when the second end repeats the sheet name (PRs #2417, #2428, #2443, #2463, #2457, #2473); datetime_from_serial returns None past year 9999.
• Carried hardening: accounting negatives read as negative numbers; INDEX(A1:C3,2) on a 2-D reference is #REF!; REGEXREPLACE bounds each replacement; 16-million-cell budget charged before scanning.

Files it reads and writes

• .xlsx is native read/write: cells, shared/array/dynamic formulas, styles, themes (including per-script typefaces; <scheme val="minor"/> is now kept on every body-font font on save), merges, conditional formats, validation, tables, notes and threaded comments, hyperlinks, names, freeze panes, outlines, print settings, pictures (shared media written once), shapes incl. ink, sparklines, PivotTables, sheet/workbook protection and Allow Edit Ranges, calc settings — and each sheet keeps its sheetId across a rewrite (PR #2513). XLSX save is faster (worksheet XML written without per-cell allocations, PR #2749).
• Pass-through on save (kept byte-for-byte when their owner survives): custom document properties, ribbon customisation, custom XML, external workbook links (never followed or refreshed), data connections, sheet query tables, printer settings, form/ActiveX controls, OLE objects, sheet backgrounds with their VML, header/footer pictures, and chart sheets.
• .xlsm / .xltm keep their VBA project byte-for-byte; macros are never executed. .xltx/.xltm save with the template content type.
• Import-only: .xls/.xlt (BIFF8: values, formulas, number formats, merges, sizes, names, calc and sheet-display settings; chart/macro/dialog sheets skipped), .xlsb and .ods (worksheet values and cached formula results only).
• Text/data: CSV and TSV/TXT/TAB with delimiter/encoding detection; writes the displayed text, keeps the separator a file was opened with, refuses output over 512 MiB; file.open {csvAsText:true} keeps every field as text. .json is a debug serde dump. HTML exports one sheet as a table (pictures as data-URI images, charts as inline SVG; refuses more than 100,001 rows).
• .pdf export: own PDF 1.7 writer; file.exportPdf {path?, sheets?: active|all, range?, fitToPage?} returns {pages, bytes, path} or base64; file.print returns the same PDF. http(s) hyperlinks and internal cell destinations become real PDF link annotations; file: links are omitted. The CLI prints huge and tiny numbers in exponent form now.
• Password-encrypted .xlsx open (Agile AES and Standard encryption, [MS-OFFCRYPTO]) via a password param; the Agile dataIntegrity HMAC is verified. RC4/Extensible and encrypted .xls are refused.
• Save is refused for .xls, .xlsb, .ods with an explanatory message. Content wins over the extension.
• Hard caps: 512 MB per decompressed XLSX part and 1 GB per package, 2 GB per file read, 100,001 HTML rows, 512 MiB CSV/TSV output, 16,000,000 cells per array result. Opening an XLSX now warns for each skipped drawing object and chart (PR #2555).

Charts, PivotTables and analysis

• 26 ChartKinds: column/bar/line/pie/doughnut/area/scatter/bubble/radar/histogram/waterfall/funnel/treemap/sunburst/box-whisker/stock/combo and subtypes; chartex parts for histogram/box-whisker/waterfall/funnel/treemap/sunburst, six trendline types, PivotCharts, Recommended Charts, Select Data, Switch Row/Column, Change Type/Colours/Layout.
• Chart objects move and resize; all 2-D kinds survive the XLSX round trip.
• PivotTables: field list, Filters/Rows/Columns/Values areas, report filters, layouts, date grouping, show-values-as, calculated fields, values on rows, grand totals, styles, refresh, change source; round-trip to/from XLSX. Show Details and Enable show details exist (command only).
• Data tools: sort (multi-key), AutoFilter, Advanced Filter, remove duplicates, text-to-columns, Flash Fill, group/ungroup/subtotals, consolidate, scenario manager, Goal Seek, data table; Outline Settings and Show Outline Symbols.
• Solver (Simplex LP with integer/binary branch-and-bound, augmented-Lagrangian nonlinear, Evolutionary; Answer and Limits reports), Forecast Sheet with hindcast, Analysis ToolPak (13 of Excel's 19 tools).
• Printing: native macOS/Windows/Linux printing through the pinned shared craft-print library, Page Setup, Page Break Preview, Page Layout view with rulers, draggable margins and in-place header/footer editing.
• Conditional formatting's New Formatting Rule formula box takes references clicked or dragged on the grid.

Automation surface (the reason to read this skill)

Counts at this tag, with v0.13.0 in brackets: 363 engine commands (354; +9 macro.*; unchanged at v0.15.0); 276/292 catalog ids (275/291 as previously recorded — the generated file says 276/292 at both v0.14.2 and v0.15.0); 22 MCP tools (21 — added list_windows; unchanged at v0.15.0, only write_range gained the parse passthrough); 11 CLI subcommands (11); 31 documented control-channel methods (31) with 34 dispatch arms including aliases; 15 UI-only command ids served by engine.commands (unchanged shape); 70 shortcut bindings on command specs (70); 365 key-tip sequences (365); 19 interface languages (19); 26 chart kinds (26); 513/523 worksheet functions (513/523); 3 MCP resources (3); 14 check round-trip categories (14).

• The control channel now requires a token (new this release): the first line of a connection must authenticate with the app's token, and a connection that does not — or later sends a bad line — is closed (#777; apps/gridcraft/src/control_server.rs:4, gridcraft_mcp::control_auth). The token is --control-token <token> or GRIDCRAFT_CONTROL_TOKEN (≥ a minimum length), else 256 random bits written to a token file only the user can read whose path is printed to stderr (gridcraft-cli reads it) (apps/gridcraft/src/control_server.rs:26-42).

• CLI gridcraft-cli (headless; the app bundle ships no CLI): info, convert, eval, cat, check, run, commands, functions, mcp, send, version — apps/gridcraft-cli/src/main.rs.

• check is the one to remember: it recalculates every formula against the file's Excel-cached values (skipping volatile formulas and fullCalcOnLoad files), then writes and re-reads the workbook through GridCraft's own XLSX writer and compares 14 categories — package, sheets, values, formulas, numFmts, merges, names, tables, condFormats, validations, charts, comments, hyperlinks, pivots — and validates the package. Flags --tolerance 1e-9 and --max-report N; exit 1 on any difference; --json emits schema gridcraft-check/1.

• MCP server over stdio, protocol 2025-06-18 (older clients answered in their own version); headless (--in FILE | --sample NAME) or remote (--connect PORT). 22 tools: execute_command, list_commands, inspect_workbook, read_range, write_range, set_cell, get_cell, evaluate_formula, select, format_range, insert_chart, create_table, sort_range, filter, open_workbook, save_workbook, new_workbook, undo, redo, screenshot, list_functions, list_windows (new — enumerates the open workbook windows).

  Resources: gridcraft://workbook, gridcraft://commands, gridcraft://functions; prompts/list is empty.

• Control channel methods (all behind the token now): read state — engine.execute, engine.commands, engine.journal (10,000 entries / 64 MB, passwords stripped), document.inspect, sheet.read, cell.get, selection.stats, ui.inspect; drive — ui.click|drag|move, ui.cell.click|drag, ui.key|text, ui.edit.begin|text|commit|cancel, ui.ribbon, ui.dialog|set|confirm|cancel, ui.message.dismiss, ui.menu.invoke; window/app — ui.screenshot, ui.set, ui.resize, ui.focus, app.open|save|quit. ui.backstage {page} and ui.ribbonTab are commands; any other method that is a command id runs that command.

• UI-only commands reachable over engine.execute/MCP (engine.commands marks them "ui": true): ui.ribbonTab, view.collapseRibbon, view.expandFormulaBar, view.darkMode, view.theme, view.animations, options.autoComplete, view.interfaceScale, ui.dialog, ui.backstage, ui.printSettings, ui.printSubmit, app.language.set, app.language.english, app.language.japanese.

• Recorded scripts (Automate tab): automate.recordActions, automate.newScript, automate.allScripts, automate.runScript, automate.trustScripts, automate.deleteScript, automate.stopAction. A workbook opened from a file that carries scripts starts untrusted; steps may not call file.*, link.* or window.* or pass a path. Scripts are stored in the workbook as the hidden defined name _sc_scripts, so they round-trip XLSX.

• Engine building blocks: undo groups, the recording buffer, document Trust, and the chunked hidden-name stash _gc_<key>_<n>.

• Web build: same UI crate via eframe web runner; URL flags ?sample=, ?webgl, ?host=parent&author=, and ?chrome= lets an iframe host turn off the title bar and File tab (new, PR #2444); preferences in localStorage; no TCP control channel.

• Programmatic calls never open dialogs: file.open/file.save/data.getData/data.fromTextCsv without a file path return "missing path…: programmatic calls never open dialogs".

• Interface languages: 19 (Language::ALL): en, es, el, zh, ja, ko, ru, pt, de, cs, fr, sr, tr, pl, it, uk, vi, nl, ro. Untranslated strings fall back to English; command ids, document text, formulas and number formats stay English/en-US. app.language.set {language|code} switches at runtime.

Known limitations and not-implemented

• Partial: .xls import covers values, formulas, number formats, merges, sizes, names, print area/titles, calc settings and WINDOW2 sheet-display options; no fonts, fills, borders, charts, pictures, comments, conditional formats, validation, hyperlinks or freeze panes; chart/macro/dialog sheets are skipped, BIFF5 and FILEPASS files refused. .xlsb/.ods import values and cached formula results only. None of the three is ever written.
• Encryption is read-only: Agile and Standard .xlsx open with a password; saves are always unencrypted and have no save path, so Save asks where to go. RC4/Extensible and encrypted .xls are refused.
• Macros never run. VBA is carried byte-for-byte only into .xlsm/.xltm; any other save drops it. GridCraft's recorded scripts are not VBA.
• Excel-repair-free output is unproven: no real corpus and no Excel verification. Unmodelled content is dropped when its owner is rewritten — slicers and slicer caches, timelines, the data model, query tables attached to tables, unmodelled extLst; chart sheets are passed through unchanged but cannot be viewed, edited or created (open now warns for each skipped drawing/chart).
• Slicers/timelines: slicers can be created and clicked in-sheet but are not saved to XLSX; timelines are catalogued but not implemented.
• Charts are shallow: no 3-D types, no axis options (min/max/log/units), no error bars, no per-point formatting; data labels and gridlines are just booleans; ~26 of Excel's ~60 subtypes (~43%), chart sheets are not editable. Move and resize do work; the Format Chart Area dialog now offers the stacked/100% stacked types.
• PivotTables: no calculated items, GETPIVOTDATA, timelines, value/label filters, number grouping or data-model pivots; Show Details and Enable show details exist but have no Options dialog; XLSX round-trip has not been checked in Excel.
• No Power Query or data model: Get & Transform is only From Text/CSV, Get Data and From Table/Range; Refresh All refreshes PivotTables only. No From Web, Stocks, Geography, Relationships or Analyze Data.
• Scale: recalculation is single-threaded; the project reports ~100 MB workbooks failing to open (#175). Whole-range work is capped and refuses with an error instead of hanging.
• Text: no complex shaping (Arabic, Devanagari, Thai) and no bidi; a right-to-left sheet mirrors the grid and HTML export, but text stays LTR inside its box and printing/PDF are not mirrored. PDF export sets characters outside WinAnsi in a predefined, non-embedded Adobe-GB1 CID font (STSong-Light / UniGB-UTF16-H): Chinese is tested; Japanese/Korean coverage depends on that font; Arabic/Devanagari/Thai have no glyphs there.
• Accessibility: AccessKit is enabled but grid cells and the ribbon are not exposed as an accessible tree; Check Accessibility is a basic scan; no high-contrast mode.
• No VBA/Office Scripts/add-in or custom-function API, no collaboration/co-authoring, no mobile build, no in-app AI.
• Functions: 18 of Excel's 523 names are absent (including GETPIVOTDATA, IMAGE, STOCKHISTORY, TRANSLATE, DETECTLANGUAGE, CALL, REGISTER.ID, RTD, COPILOT, PY) and 9 are error stubs (7 CUBE functions, WEBSERVICE, FILTERXML).
• HTML is export-only: opening .html/.htm falls through to the CSV/TSV reader.
• Objects: inserted icons lose their artwork on XLSX save (#551); Office InkML is not imported; pictures must be PNG/JPEG.
• Save semantics: only .xlsx and .json saves clear the dirty flag and become the document's file; .csv/.tsv/.html/.pdf are exports that leave the workbook dirty. file.close {force:true} and the control-channel app.quit discard unsaved changes without asking.
• Groundwork, not a feature: crates/ui-egui/src/code_editor.rs (Python and LaTeX syntax colours) is exported but no dialog uses it yet — there is still no Python-in-cells (PY) or equation editor.
• Stale repo prose (verify against code, not docs): README says "89% of standard ribbon commands" while the generated checklist says 276/292 = 94.5%; docs/target-app-parity.md still reports 274/290 and "313 command ids"; several docs/gaps.md/docs/ui-parity.md rows contradict the code (PDF fonts, shortcuts, localization, solver, CSV raw values); docs/control-protocol.md does not yet describe the token authentication. Prefer code and the generated docs/parity-checklist.md.

How to operate

macOS launch, flags, environment

• open -a GridCraft; open -a GridCraft book.xlsx — Finder double-clicks and open arrive as Apple events, and files dropped on the window open too.
• The binary takes only these flags: /Applications/GridCraft.app/Contents/MacOS/GridCraft [--control PORT [--control-token TOKEN]] [--sample budget|sales|grades] [files…]; --version prints the release (0.14.2).
• Environment: GRIDCRAFT_CONTROL_PORT=<port>, GRIDCRAFT_CONTROL_TOKEN=<token> (the control channel requires it), GRIDCRAFT_NO_PREFS=1 (the mode for agent test runs), GRIDCRAFT_NO_NATIVE_MENU, RUST_LOG.
• Settings and logs live under Library/Application Support/GridCraft/ in the user's home: ui.json, prefs.json, and logs/gridcraft.log, rotated to .1/.2 at each start, 16 MiB cap.

The CLI (installed separately)

The bundle ships no CLI. Install with cargo install --path apps/gridcraft-cli from a source checkout, or the release zip gridcraft-cli-<ver>-macos-universal.zip.

shCopy code
gridcraft-cli info book.xlsx [--json]
gridcraft-cli convert in.xls out.xlsx [--sheet Sales]     # .xlsx/.csv/.tsv/.json/.html/.pdf by extension
gridcraft-cli eval '=XLOOKUP("b",{"a","b"},{1,2})'        # → 2
gridcraft-cli cat book.xlsx --range A1:F20 [--formulas|--csv]
gridcraft-cli run --in book.xlsx --cmd 'cell.set={"cell":"D2","input":"=B2*C2"}' \
    --cmd 'edit.fillDown={"range":"D2:D20"}' --out book.xlsx --print A1:D5
gridcraft-cli check corpus/ --json --tolerance 1e-9       # calc oracle + XLSX round-trip fidelity
gridcraft-cli commands --search chart                     # every command and its params doc
gridcraft-cli functions --category statistical            # function list with signatures
gridcraft-cli send 7979 engine.execute '{"command":"home.bold","params":{"range":"A1:C1"}}'

• run flags: --in FILE | --sample NAME, repeated --cmd, --script FILE, --out FILE, repeated --print RANGE|used, --sheet, --quiet, --csv, --formulas. A --cmd is id, id={json} or id {json}; a script has one step per line; blank lines and #/// comments are skipped. The first failing step stops the run with a non-zero exit.
• convert refuses an unknown output extension; .pdf goes through file.exportPdf and reports bytes/pages.
• check never writes next to its inputs. --json output is schema gridcraft-check/1.

MCP

shCopy code
claude mcp add gridcraft -- gridcraft-cli mcp                     # headless in-process session
claude mcp add gridcraft-app -- gridcraft-cli mcp --connect 7979 # drive the visible app

Results are one text block holding pretty JSON; failures set isError: true. Unknown tools, missing/wrong arguments are JSON-RPC -32602; malformed JSON -32700; unknown methods -32601. The remote backend uses a 30 s socket timeout: after a timeout, re-read the state instead of retrying blind. list_windows enumerates the open workbook windows; address a window where the backend accepts it.

Control channel (drive the running app)

shCopy code
/Applications/GridCraft.app/Contents/MacOS/GridCraft --sample sales --control 7979
# stderr prints the token file path (or use --control-token / GRIDCRAFT_CONTROL_TOKEN), then
# newline-delimited JSON to 127.0.0.1:7979 — the FIRST line must authenticate with the token:
{"id":0,"method":"auth","params":{"token":"<token>"}}
{"id":1,"method":"engine.execute","params":{"command":"cell.set","params":{"cell":"B2","input":"=SUM(A1:A9)"}}}
{"id":2,"method":"ui.screenshot","params":{"path":"shot.png"}}

• Authentication is required this release: a connection that does not authenticate first is closed, as is one that later sends a bad line. gridcraft-cli send reads the token file automatically.
• Run ui.inspect first (ribbon tab, editor, open dialog, Backstage page, message, grid rect, scroll, perf, windows) and act on what it shows; ui.screenshot needs a presented frame.
• Limits: 64 MiB per request line; 10,000 queued synthetic pointer events; the server waits 60 s for the UI, then reports a timeout. A request the client abandoned is dropped unrun; if the app had already started it, the reply says the outcome is unknown — read the cell/state before retrying.
• The port binds localhost only and is token-authenticated; do not expose it.
• ui.dialog.confirm sends exactly what the dialog's OK sends; dialogs without an OK command return "this dialog has no OK command; drive it with its own commands".

Document model and save/export flow

• One native window per workbook window: view.newWindow shares the workbook (no clone; saving from either window saves it), view.arrangeAll tiles, window.list/window.close manage windows, and view.switchWindows/window.activate switch workbooks. Sheet tabs at the bottom. File opens the Backstage with 9 pages: home, new (three samples), open (recents), info, saveAs, print, export, options, account.
• Save (file.save, file.saveAs, ⌘S, ⇧⌘S): the extension picks the format — .xlsx (default), .csv, .tsv, .json, .html, .pdf; a .pdf save exports the sheet and leaves the document dirty. file.saveBytes {format} returns base64 without writing.
• Exports: file.exportPdf, file.exportCsv, file.exportHtml, file.printPreview, and on the desktop ui.printSettings / ui.printSubmit (native jobs via craft-print).
• Opening a .xls/.xlsb/.ods produces a document titled <name> (imported).xlsx with no save path; opening an already-open path switches to it; a password-decrypted workbook also has no save path. Opening a saved workbook without recalculation is supported.

Keyboard essentials (verified)

• 70 shortcut bindings on command specs (F3 → Paste Names, Ctrl+8 → Show Outline Symbols, Ctrl+Shift+U formula bar), plus a wider keymap table for number formats, borders, F-keys and Alt/Option combinations.
• Essentials: ⌘S save, ⇧⌘S Save As, ⌘O open, ⌘N new, ⌘W close, ⌘Z undo, ⌘Y redo; ⌘B/⌘I/⌘U; ⌘1 Format Cells; ⌘D fill down, ⌘R fill right; ⌃E Flash Fill; ⌘T table; ⌘K link; Ctrl+Shift+L filter; F2 edit; F3 Paste Name; Ctrl+Shift+4 currency; Ctrl+Shift+7 outline border; Ctrl+` show formulas; F9 calculate; Ctrl+[ / Ctrl+] precedents/dependents; Ctrl+6 hide/show objects; Ctrl+8 outline symbols; Ctrl+Shift+U formula bar. Shift+Arrow on a whole column/row keeps the view on the rows/columns it showed (PR #2497).
• Key tips: F10 (or left Alt on Windows/Linux/BSD), then sequence letters; 365 sequences cover every ribbon tab.
• The macOS native menu has Tools ▸ Command Palette… (⌘⇧P).

Working with an AI agent

Prefer headless over GUI. For read/write/convert/verify jobs use gridcraft-cli (or MCP) on files: no window, no preferences (set GRIDCRAFT_NO_PREFS=1 if you launch the app), deterministic. Drive the GUI over the control channel only when the task is genuinely about the UI. Never drive blind — ui.inspect/ui.screenshot before and after.

Legitimate agent work:

• Prepare inputs. Build .xlsx from commands (gridcraft-cli run --script steps.jsonl), convert .xls/.xlsb/.ods/CSV/TSV into .xlsx, or generate CSV/TSV/JSON and import. Use file.open {csvAsText:true} when leading zeros must survive. Remember an import opens as an unsaved "(imported).xlsx".
• Interpret/repair files. XLSX is native and documented in code. "Repair" means: open in GridCraft, inspect (info, check), fix with commands or formulas, save as .xlsx. Do not promise recovery of parts GridCraft does not model. Open without recalculation when you only want to inspect values.
• Verify exports honestly. Run gridcraft-cli check on round-tripped files, compare cat/info output against expectations, check PDF page counts and links. A zero exit from check means GridCraft agrees with itself and with the file's cached values; it does not prove Excel will open the file without a repair prompt.
• Scripts. Recorded scripts are a convenience layer over the same command ids. A workbook received from elsewhere carries its scripts as a hidden name; nothing runs until the workbook is trusted, and script steps cannot touch files, links or windows. A leftover undo group blocks undo/redo: clear it with automate.stopAction.
• Work with two views: view.newWindow now shares the workbook — two windows, one document; list_windows (MCP) and window.list enumerate them; view.arrangeAll tiles.

Must NOT attempt:

• Writing .xls/.xlsb/.ods, or saving password protection; expecting macros to run; expecting slicers/timelines to survive a save; assuming HTML import.
• Raw XML surgery on .xlsx files that contain unmodelled parts: GridCraft's own writer is the supported path, and even it drops parts it does not model once it rewrites them. Prefer read-only analysis of such files.
• Treating formulas as locale-independent without checking docs/formula-input.md: Spanish input/display exists, but files, commands and APIs use canonical English names and , separators.
• Promising PDF output for Arabic, Devanagari or Thai (no glyphs in the CID font, no shaping); verify CJK output visually first.
• Calling app.quit or file.close {force:true} while a workbook has unsaved changes: both discard them silently. Save first.
• Connecting to a --control port without the token (the connection is closed), or assuming the channel is unauthenticated — it is not, since this release.

Verification protocol (alpha discipline)

1. Throwaway round-trip before real work: new workbook → the exact edit → save .xlsx → reopen (or gridcraft-cli info/cat) → gridcraft-cli check file.xlsx. Add the source file itself to check when testing formula fidelity.
2. Never trust a silent export. CSV/HTML/PDF are one-shot exports with no diff UI. Re-read or re-import the artifact. Remember PDF export cannot be assumed to render Arabic/Devanagari/Thai.
3. Version and back up. Keep the previous copy of any workbook you edit; autosave covers only workbooks that already have a file. For agent runs, save after each logical step (--out) rather than at the end.
4. Update between projects, not during. The app auto-updates through the ArtCraft Launcher; update, then re-run your round-trip before a new task.
5. After a control/MCP timeout, re-read state (cell.get, sheet.read, document.inspect) before retrying: a queued request is dropped, but one already taken may still finish.
6. Trust deliberately. Do not call automate.trustScripts on a workbook you did not create unless the user asked you to run its scripts.

Sources & evidence

• Repo: https://github.com/storytold/gridcraft — inspected at tag v0.15.0, commit 30b210b4ef03b30616923465efa70766cefba379 ("Release 0.15.0", 2026-11-01); the v0.14.2 ref was fetched for id diffs. The installed /Applications/GridCraft.app matches the tag and prints GridCraft 0.15.0. If your installed version differs, verify against it.
• Date of inspection: 2026-11-02. Repo treated read-only (not built or modified).
• Key files read: README.md, Cargo.toml, docs/{cli,mcp,control-protocol,parity-checklist,function-parity,chart-parity,file-format-parity,gaps}.md, apps/gridcraft-cli/src/{main.rs,check.rs}, apps/gridcraft/src/{main.rs,control_server.rs}, apps/gridcraft-web/src/main.rs, crates/engine/src/{io.rs,lib.rs,sample.rs,catalog.rs,record.rs}, crates/engine/src/cmd/ (incl. extra.rs window commands), crates/xlsx/src/, crates/pdf/src/lib.rs, crates/mcp/src/{tools.rs,server.rs,backend.rs}, crates/ui-egui/src/{control.rs,keymap.rs,ribbon.rs,lib.rs,dialogs.rs,grid.rs,i18n/}, crates/model/src/{features.rs,workbook.rs,sheet.rs}, crates/functions/src/, crates/calc/src/eval.rs, apps/gridcraft/Cargo.toml.
• Counts were re-measured from code, not prose: commands by (cmd|spec)! multiline id extract (diffed against the fetched v0.14.2 ref — zero added, zero removed at v0.15.0; earlier deltas +window.close, +window.list, +9 macro.*); MCP tools by tool( calls (22 = 22; write_range gained the parse passthrough); catalog coverage by the generated docs/parity-checklist.md (276/292, byte-identical at v0.14.2 and v0.15.0 — the previously recorded 275/291 was stale); languages by the i18n/ directory (19).
• Shared libraries: the craft-libs crates (incl. craft-print) are pinned to one revision, 92d392cf…, this release.
• Deeper per-topic reference (repo docs): docs/target-app-parity.md, docs/gaps.md, docs/architecture.md, docs/parity-checklist.md.