Pranav
f6a0556b9e
* Objects: one selection for charts, pictures, shapes and slicers, with eight resize handles
The sheet tracked the selected object as a bare id in `selected_chart`, so
only charts and text boxes drew a selection frame, only the bottom-right
corner resized, and the kind of the selected object had to be guessed from
the id. The selection is now `SheetApp::selected_object: Option<ObjRef>`,
with `selected_chart()` kept for the Chart Design tab and the Format Chart
pane.
- Model: `ObjKind` (chart, image, shape, slicer) and `ObjRef { kind, id }`;
`Sheet` helpers find, move and remove an object by `ObjRef` and walk every
object's anchor in a fixed order. `next_object_id` saturates instead of
overflowing on an id at `u32::MAX` read from a file.
- Commands: `object.delete`, `object.move` and `object.setAnchorMode` accept
the four kinds through one parameter check, refuse an unknown kind or id
instead of succeeding silently, and clamp hostile offsets. `object.delete`
replies with the deleted object. Arrange and the Selection Pane include
slicers, which stack above the other objects.
- Sheet: the selected object of any kind draws a frame with eight handles
over every object. Each handle resizes only its own edges, which never
cross; the body moves the object, and the first drag frame already applies
the pointer's movement. The pointer shows the handle's resize cursor or a
move cursor, with the diagonals swapped on a right-to-left sheet, where the
frame moves with its object.
- Keys: Escape drops the object selection; Delete and Backspace keep
deleting the selected object (#213). A selection whose object disappears
(undo, redo, delete, sheet switch) is cleared.
- Double-click: `open_object` routes by kind (a text box edits in place, a
chart opens Format Chart).
- Control protocol: `ui.inspect` reports `selectedObject {kind, id}` and
keeps `selectedChart`; `ui.object.select` selects any object and replies
with its rect. The snapshot example takes `--object <id>`.
Tests: engine tests for every kind by kind and id, the Selection Pane and
hostile parameters; UI tests for selecting each kind (a slicer over a chart
takes the click), all eight handles on four kinds, cursors, Delete,
Backspace and Escape, undo and redo, double-click routing, and resizing on a
right-to-left sheet. Existing tests use the new selection API.
* Objects: every kind follows edits; chart series follow cut-moves and sheet deletes
Structural edits and sorts kept three hand-indexed lists (charts, images,
shapes) in step in two places, and slicers were left out of both, so a
slicer stayed put when rows were inserted above it. Chart series were
rewritten for inserted and deleted lines and for sheet renames, but not for
cut-moves or sheet deletes, which left them pointing at the old cells.
- Inserting and deleting rows and columns and sorting walk
`Sheet::object_anchors` and `object_anchors_mut`, one fixed order over
every kind, so slicers now follow their cells by their anchor mode like
the other objects, and a new kind cannot be forgotten in one of the
passes.
- `rewrite_cell_links` is the one place that rewrites the references
floating objects hold (chart series values, categories and names,
and the source block a chart was made from).
`rewrite_all_formulas` calls it, which covers inserting and deleting
lines and cells and cut-moves on one sheet or across sheets; renaming and
deleting a sheet call it too, so a series into a deleted sheet becomes
#REF!, as a formula does.
- Copying a sheet gives its charts, pictures, shapes and slicers fresh ids,
keeping ids unique across the workbook, which object selection and the
`{kind, id}` commands rely on.
Tests: every kind through row and column inserts and deletes, an absolute
shape, a sort and undo; a slicer through inserted rows; chart series
through a cut-move, a sheet rename, a sheet delete and undo; ids after a
sheet copy.
* Objects: bubble sizes follow edits like the other series references
`rewrite_cell_links` rewrote a chart series' values, categories and name
but not its bubble sizes, so inserting or deleting lines, a cut-move or a
sheet rename left a bubble chart's sizes pointing at the old cells. They
are now rewritten with the rest.
Test: bubble sizes through an inserted row, a cut-move and a sheet rename.
* Objects: a resize handle under the headers leaves the press to them
A selected object's handles reach a few points outside it, and a press
was matched against them before any check of where it landed, so a press
on the column or row header beside an object at the sheet's edge resized
the object instead of selecting the column or row. The cursor already
ignored handles outside the cells.
`chartview::selected_handle` finds the selected object's handle under a
point only over the cell area, as `hit` does, and not while objects are
hidden; the press and the cursor both use it.
Test: presses within a handle's reach over the column header and the row
header neither move nor resize the object.
* Objects: each drag of an object is its own undo step
A drag merges its frames into one undo step by dropping a new step whose
label matches the one before it. Its first frame did the same, so a second
drag of an object (a move after a move, or a resize after a move) merged
into the first drag's "Move Object" step, and one undo took back both.
`Drag::Object` records whether the drag has made its step; only the later
frames of the same drag merge into it.
Test: a move and then a resize of a picture take two undos to reverse,
the first restoring the moved picture.
* Objects: the parity and gap docs no longer list chart resizing as missing
gaps.md (§4), target-app-parity.md (the Essentials tier's work, the
Mainstream chart row, the interaction discount and the Essentials chart
task) and chart-parity.md (the element table and the work list) still
described charts as impossible to resize (#190). Charts move and resize
from eight handles like every floating object, so those statements now
say so; the 2026-10-10 revision rows and the 10-10 re-check stay as
history. Scores and the 40-60 h chart estimate are unchanged (resizing
was 1-2 h, within the rounding).
* Objects: one chart evidence paragraph in gaps.md; trendlines are not missing
gaps.md §4 carried two evidence paragraphs, an older one saying PRs #158
and #161 were open and a newer one saying all 2-D kinds survive XLSX round
trip, both repeating the resize, smooth-line, Switch Row/Column and
trendline statements. It is one paragraph with the current status again.
The Mainstream chart row in target-app-parity.md listed trendlines as
missing; they are read, written and drawn (`Series::trendlines`, the XLSX
chart reader and writer, `chart.addElement`), as chart-parity.md records.
The row now says so and keeps "no axis options". No score change.
* Objects: only the selected object's handles resize; a press elsewhere on an object moves it
A primary drag looked for a handle under the press on whatever object it
grabbed, so pressing near the edge or corner of an object that was not
selected started a resize, while the pointer over that spot showed the
Move cursor (handles are only shown, and only offered by the cursor, on
the selected object). The press now takes its handle from
`chartview::selected_handle`, the same lookup the cursor uses; a press on
any other object selects and moves it.
Test: dragging an unselected shape by its bottom-right corner shows the
Move cursor, then selects and moves the shape without resizing it.
* Docs: ui.object.select says what it replies when it clears the selection
* Objects: a test pins that both anchor accessors visit the same objects in the same order
Sorting and row or column edits read every anchor through
`object_anchors`, compute the new ones and write them back through
`object_anchors_mut` in step. Nothing checked that the two accessors
visit the same objects in the same order; a kind of floating object
reaching only one of them would have paired objects with other objects'
anchors silently.
Test: two objects of every kind are inserted in a mixed order, each
anchor is marked with its position through the mutable accessor, the
marks are read back through the shared one in the same sequence, the
count matches the per-kind collections, and the mark is found on the
object `object_anchor` names by kind and id. The test's constructor
matches on `ObjKind` exhaustively, so a new kind does not compile until
the test covers it.
* Objects: sorting keeps the size of a "move and size" picture whose lines swap places
A picture anchored to move and size with cells and spanning two rows
(or columns) was re-fitted between its top-left and bottom-right lines
after a sort. When the sort put the bottom line above the top one, the
fitted extent was negative and the picture collapsed to a zero height
or width. It now keeps its old size on that axis and travels with its
top-left line, like a "move only" picture.
Tests: for a sort by rows and one by columns, "move and size" and
"move only" pictures inside one line travel with it (the first
re-fitted to the same line, the second at its own size), an absolute
picture stays while the cells move under it, a two-line picture whose
lines swap keeps its size, and undo restores every anchor.
* Objects: a copied sheet's objects get free ids even when a file used the largest id
`Workbook::next_object_id` returned one more than the largest id in use,
saturating at `u32::MAX`. A workbook read from a file can carry an object
with that id; every later insert (a chart, picture, shape, table or
slicer) then got `u32::MAX` again, and so did each object of a copied
sheet, whose ids also came from a saturating counter. Lookups and
selection take the first object with an id, and `object.delete` removes
every one.
`Workbook::free_object_ids(count)` now returns distinct unused ids: those
above the largest in use while they last, then the lowest free ones from
1. `next_object_id` takes the first of them, and the sheet copy takes one
per copied object (and refuses if the id space were ever exhausted). The
model test that recorded the saturation now checks the free ids instead,
and a new one covers a file that used the largest ids: the free ids come
from below, 100,000 of them distinct and in order.
Test: object_ids_stay_unique_when_a_file_used_the_largest_id gives a
shape id u32::MAX, inserts two shapes and copies the sheet; every shape id
is distinct across both sheets. It fails without the fix (both new shapes
get 4294967295).
* Objects: main's chart data table compiles with the object selection and the model's object test
Two leftovers of the merge of origin/main (25881a8e), neither a textual
conflict: `Chart` gained a `data_table` field, which the `push_object`
helper of the model's object test did not set (it is `None`, as in
`insert.chart`); and chart_data_table.rs set the `selected_chart` field
this branch replaced by `selected_object`. The test selects its chart as
a floating object, as the branch's other tests do.
* Objects: object.move and chart.set keep a size a file made larger than 10,000
`object.move` clamped `width` and `height` to 10,000 points, the most it
gives a new size, while the XLSX reader accepts anchors far past that.
A resize of a picture a file made 12,000 wide passed 11,990 through the
clamp and jumped to 10,000; `chart.set`, whose Format Chart pane sends
the unchanged dimension back with the edited one, clamped the same way.
Each dimension is now capped at 10,000 or the object's current size,
whichever is larger (`size_cap`): such an object keeps its size when it
is moved, shrinks by what a resize asks and never grows further, and a
hostile size is still capped. The params doc of `object.move` and the
control protocol notes say so.
Tests: an_oversized_imported_object_keeps_its_size_when_moved_and_shrinks_only_by_a_resize
makes a picture 12,000 by 300, writes and reads it back as a file, then
moves it without a size (12,000 stays), asks 12,010 (stays 12,000),
11,990 (11,990, no jump) and 50,000 by 50,000 (11,990 by 10,000).
chart_set_keeps_a_chart_size_a_file_made_larger_than_the_limit does the
same through `chart.set`. Both fail without the fix (width 10,000).
* Objects: dragging an object's body sends its position only, not its size
`drag_object` sent `width` and `height` with every step of a body drag,
so moving a picture a file made 12,000 wide shrank it to the 10,000 that
`object.move` gives a new size. Only a handle drag sends a size now; a
body move leaves the engine's size alone.
Tests (real input): dragging_the_body_of_an_oversized_imported_object_keeps_its_size
reopens the workbook with a 12,000 by 60 picture, drags its body by
30 by 25 and checks the size is untouched, the picture moved with the
pointer and the journaled `object.move` carries no width or height; it
fails without the fix (the journaled command carries both, and without
the engine's cap the picture is 10,000 wide).
a_handle_drag_on_an_oversized_imported_object_resizes_by_the_drag_only
moves the left handle 10 px right: the picture is 10 points narrower in
the window and keeps a width near 12,000, with no jump to the limit.
* Objects: the Format Chart Size fields show a chart's real size and send only the edited dimension
The Width and Height fields ranged 40 to 4,000 and sent both values on
every edit. egui clamps an existing value into a field's range, so a
chart a file made 12,000 wide showed "Width 4000", and typing a new
height sent that 4,000 as the width: the chart shrank although only its
height changed, and the cap `chart.set` keeps for an existing size
cannot help once the pane itself sends 4,000. Each field's range now
reaches the larger of 4,000 and the chart's current size, so the field
shows the real size, and a commit sends only the dimension that differs
from the chart's (`chart.set` reads `width` and `height` independently).
Test (real input): the_size_fields_keep_an_oversized_imported_chart_width_when_the_height_changes
reopens a workbook with a 12,000-wide chart, opens Format Chart Area's
Size section, checks the Width field shows 12000 and types 201 as the
height: the width stays 12,000, the height is 201 and the journaled
chart.set carries no width. Without the fix the field shows
"Width 4000".
13 KiB
GridCraft control protocol
Start the desktop app with a control port:
gridcraft --control 7979 # or GRIDCRAFT_CONTROL_PORT=7979
Authentication
The control port is reachable by every program on the machine, and by a web page that POSTs
text/plain to 127.0.0.1:7979, so every connection must prove it knows the app's token
(#777). There is no way to turn this off.
- The app makes a token at start (256 random bits from the operating system, kept in memory) and
writes it to a file only you can read:
$XDG_RUNTIME_DIR/gridcraft/control-<port>.token(else~/.cache/gridcraft/…; Windows:%USERPROFILE%\.gridcraft\…; the folder is mode 0700 and the file 0600 on Unix). The path is printed on stderr. The token itself is never printed or logged. - Or choose the token yourself:
GRIDCRAFT_CONTROL_TOKEN=…(preferred) or--control-token …(visible in the process list), at least 16 characters. The app then writes no file. - The first line of a connection must be
{"id":0,"method":"auth","params":{"token":"…"}}; the reply is{"id":0,"ok":true,"result":{"authenticated":true}}. Any other first line (a wrong or missing token, another method, text that isn't JSON such as an HTTP request, no line within 10 s, or one longer than 4 KiB) gets{"ok":false,"error":"authentication required"}and the connection is closed. At most 16 connections may be waiting to send their token at once; past that a new connection is closed before anything is read. After that, a line that isn't JSON also closes the connection. gridcraft-cli send/mcp --connectandgridcraft_mcp::Remotedo this themselves: they useGRIDCRAFT_CONTROL_TOKENif set, else the token file of that port (so they work for the same user on the same machine without setup). Your own client reads the file or the variable.
Requests
Then send newline-delimited JSON to 127.0.0.1:7979 (after the auth line). Every request line gets one reply line:
{"id": 1, "method": "engine.execute", "params": {"command": "cell.set", "params": {"cell": "B2", "input": "=SUM(A1:A9)"}}}
{"id": 1, "ok": true, "result": {"cell": "B2", "value": "45"}}
Errors come back as {"id": …, "ok": false, "error": "…"}. Asynchronous work that
finishes later than the reply (a ui.screenshot capture) adds its own request token to
the reply so the client can match it; a capture that completes after its 8 s deadline returns
the timeout error and writes no file.
A line that is not a JSON object with a string method (an HTTP request, text that isn't JSON,
bytes that aren't UTF-8, a line over 64 MiB) gets one error reply and the server closes the
connection; nothing sent after it runs. Blank lines are skipped.
Methods
| Method | Params | What it does |
|---|---|---|
engine.execute |
{command, params, window?, doc?} |
Runs any engine command (see engine.commands or gridcraft-cli commands) in the active window, or in the window named by window (a window id) or doc (a workbook id: its most recent window). The active window stays in front afterwards unless the command itself switches windows. edit.goTo, edit.goToSpecial, selection.set and selection.move scroll the active cell into view, as Go To does in the window |
window.list |
The open windows: [{window, doc, index, title, dirty, active, hidden}]. title is the workbook name, or "Book1:1", "Book1:2"… when a workbook has several windows; index is the workbook's position among the open workbooks |
|
engine.commands |
{search?} |
Every command: id, label, ribbon path, shortcut, params doc, enabled; search keeps those whose id, label or ribbon path contains it (case-insensitive) |
engine.journal |
Commands run so far (replayable). Passwords (password, …Password params) are left out, so a replayed Protect Sheet has no password. Capped at 10,000 entries and 64 MB (serialized); past either cap the oldest entries go |
|
document.inspect |
Workbook summary: sheets, used ranges, tables, charts, names, selection, undo labels | |
sheet.read |
{range?, sheet?, formulas?, formatted?} |
Values (or formulas / displayed text) of a range |
cell.get |
{cell?} |
One cell: value, formula, displayed text, style, merge, comment, link |
ui.inspect |
UI state: ribbon tab, editor, open dialog, Backstage page, message, selected object, grid rect, scroll, perf, windows (as window.list) and activeWindow |
|
ui.object.select |
{id?, kind?} |
Selects a floating object on the active sheet and replies {selected, rect}, the rect in window points; with no id it clears the selection and replies null |
ui.click / ui.drag / ui.move |
{x, y, toX?, toY?, button?, count?, shift?, cmd?, alt?} |
Real pointer input in window points; refused with an error if it would leave more than 10,000 synthetic events or 8 MiB of synthetic input queued (pointer, key, text and move events share this budget) |
ui.cell.click / ui.cell.drag |
{cell} / {from, to} |
Pointer input at a cell's centre (works in point mode while editing); same shared queue limits |
ui.key / ui.text |
{key, shift?, cmd?, alt?, ctrl?} / {text} |
Keyboard input (typing in the grid starts editing); same shared queue limits, and one ui.text string may be at most 1 MiB |
ui.edit.begin / ui.edit.text / ui.edit.commit / ui.edit.cancel |
{text?} / {move?: down|right|up|left|none} |
Drive the cell editor |
ui.ribbon |
{tab} |
Switch ribbon tab |
ui.dialog / ui.dialog.set / ui.dialog.confirm / ui.dialog.cancel |
{name} / {field, value} |
Open, fill in and confirm dialogs; confirm runs the dialog's command with the same parameters as its OK button |
ui.backstage (via engine.execute) |
{page?: home|new|open|info|saveAs|print|export|options|account|close} |
Open the File tab's Backstage view on a page, or close it (ui.inspect reports the open page as backstage) |
ui.screenshot |
{path?} |
PNG of the window (base64 when no path). Animations are settled first: the picture shows the final state. On the native app it works while hidden or occluded when the platform still reports the current content size (the request asks for a hidden paint); a minimized window has no capturable size, so its request stays queued until the window is restored and otherwise reports the 8 s timeout. In a hidden browser tab the web runner does not implement that paint request, so the capture waits until the tab is shown again or reports the 8 s timeout. Up to 4 outstanding requests; retained images are limited to 128 MiB each and 256 MiB in total (each request reserves the largest image the ±1-pixel rounding rule can retain), one capture's transient encoding working set to 256 MiB, a base64 reply to 64 MiB, and retained images plus one capture's encoding working set to 512 MiB; a request that would exceed a budget is refused without evicting earlier ones. See Screenshot budgets. A resize/DPI/zoom/visibility/occlusion change during capture is retried within the bounded retry budget or reported instead of saving stale pixels; the identity intentionally includes zoom and occlusion even though the expected physical size may be unchanged, so a capture never crosses layout generations. Every reply — success, refusal or timeout — carries the request token as request |
ui.set |
{dark?, formulaBar?, ribbonCollapsed?, animations?} |
UI preferences (formulaBar runs view.formulaBar) |
ui.resize / ui.focus |
{width, height} |
Window control |
app.open / app.save / app.quit |
{path, password?} / {path?} |
Files and lifetime. password opens a password-protected workbook; without it, such a workbook returns an error (never a dialog) |
Screenshot budgets
ui.screenshot keeps up to four requests outstanding. Each admitted request reserves the largest
image the ±1-pixel rounding rule can retain: 128 MiB per image and 256 MiB in total across
requests, and a request that would exceed a budget is refused without evicting earlier ones.
Encoding is bounded separately: one capture's transient working set may be 256 MiB (the larger of
the retained image plus its RGBA copy, or, for a base64 reply, the image plus the PNG stream plus
the encoded text), the base64 reply itself may be 64 MiB, and retained images plus one capture's
encoding working set may be 512 MiB. Base64 text counts toward the encoding working set, so a
large pathless capture can be refused there or by its base64 length even when its retained image
fits. path writes the PNG to a file instead of returning base64 text and so avoids those two
base64 costs, but it does not bypass the per-image, aggregate, encoding-working-set or peak
limits.
Any other method name that is a command id (e.g. home.bold) runs that command. Its params may
include window or doc to run it in that window, as with engine.execute; the window commands
(window.*, view.newWindow, view.hideWindow, view.unhideWindow, view.switchWindows) read
them as their own parameters.
ui.inspect reports the selected floating object as selectedObject: {kind, id} (or null),
where kind is chart, image, shape or slicer; the same names go in the kind parameter
of object.delete, object.move, object.setAnchorMode and the arrange.* commands.
object.move and chart.set cap width and height at 10,000 points, or at the object's
current size when a file made it larger: such an object keeps its size when it is moved and
shrinks by what a resize asks, but does not grow further.
selectedChart remains for existing clients: the id when the selection is a chart, otherwise
null. With an object selected, ui.key {key: "Delete"} (or Backspace) deletes the object
instead of clearing cells, and Escape clears the selection.
Windows
Every open workbook has one or more windows; View › New Window (view.newWindow) adds another
on the same workbook, and saving from any of them saves that workbook. Each window has its own
selection, active sheet and scroll position; switching windows never marks the workbook as
changed. window.activate {window}, view.switchWindows {window} and view.unhideWindow {window} bring a window forward; window.close {window?, force?} closes one (the workbook
closes with its last window, asking about unsaved changes unless force); file.close closes
the active window, or with {document: true} the workbook and all its windows.
Use engine.execute with {command: "view.theme", params: {mode: "system"}}
to choose the display theme; mode accepts "system", "light", or "dark".
System follows live OS appearance changes and falls back to Light when the platform supplies no preference.
The saved choice remains System; new users still start in Light. The legacy
view.darkMode command and ui.set {dark} select a fixed Light or Dark theme.
{command: "view.animations", params: {on: false}} turns motion in the UI off (the selection
outline then jumps to a new selection instead of gliding there); without on it toggles. It is
the View ▸ Animations checkbox, saved with the other UI preferences and on by default.
{command: "app.language.set", params: {language: "ja"}} switches the interface language
(code is accepted as an alias for language); app.language.english and
app.language.japanese are shortcuts. engine.commands lists every code it takes (en, es,
zh, ja, ko, ru, pt, de, cs, fr, sr), as does the error for an unknown one. Only
interface chrome is translated, never command ids or document text. The choice is saved in ui.json; with nothing saved the desktop app follows the
system language.
{command: "file.open", params: {path: "Secret.xlsx", password: "…"}} opens a password-protected
workbook (Agile or Standard encryption). Without password it returns an error containing
"is password-protected. Enter its password to open it." and never opens a dialog; a wrong
password returns "The password is incorrect." The password is left out of the journal and never
quoted in an error. The opened workbook has no save path, so Save asks where to save it, without
the password, and never replaces the encrypted original.
For a headless equivalent (no window), use gridcraft-cli mcp or gridcraft-cli run;
see mcp.md and cli.md.
Native printing
Desktop engine.commands {"search":"print"} (and connected MCP list_commands)
lists ui.printSettings and ui.printSubmit with their parameter and result fields.
engine.execute can call ui.printSettings with {} to inspect the printer list, selected
printer, copies, duplex, grayscale, discovery/submission status and backend receipt/error.
{"refresh":true} starts background discovery; poll the same command until discovering is
false. Set printer to a discovered name, integer copies from 1 to 999, duplex to
printerDefault, off, longEdge or shortEdge, and boolean grayscale. Invalid updates are
rejected without changing earlier settings. ui.printSubmit explicitly submits the current
print-ready PDF without opening a dialog; inspect ui.printSettings until busy becomes false
and check status/detail. The browser keeps its own print hook. PDF export remains separate.
GridCraft accepts the existing file.print sheet/pagination params on ui.printSubmit; the engine file.print command returns the PDF without spooling.