Files
wordcraft/docs/control-protocol.md
T
Martin BallandClaude Opus 5.5 b5e0be7879 Port the UI onto the craft framework (#7101)
* canvas-w21: net change of 3 commits

- canvas-w21: written from its sheet
- canvas-w21: repair 1
- canvas-w21: review fixes (review-1)

* chrome-w8: net change of 2 commits

- chrome-w8: repair 1
- chrome-w8: review fixes (review-1)

* mini_toolbar tests: import egui pos2 and Vec2 the tests use directly (production imports only Rect, Ui)

* App compile: open context_menu, font_box and ribbon::common to their callers; Label and Value import from their framework homes; balloons read command_enabled; wordart test runs fired commands through WordApp::run_fired; delete rtl.rs, which has no reader

* Fix imports (palette, picker, icons, color), expose find helpers, drop old keytip phase state per S-L365

* keytip_places: removed with the old keytip phase machine (S-L365); WordApp, WindowUi and the destructurings no longer carry it

* ribbon submodule imports: Value, Target, Remember, egui geometry, Label, TypeRole, DisclosureGlyph and kittest Node come from their own modules, not the ribbon.rs re-exports ribbon-w8 dropped

* context menu: CanvasState keeps the open point so the menu anchors where it was asked

* Palette derives Default: dialog forms hold an empty palette until prepare fills it

* ribbon: Stack/Row/Menu show need ShowContainer in scope

* canvas Read Mode: reading metrics come from a probe component measured under the theme (S-L355)

* Dialog and mini toolbar call sites follow the framework: Mode into style previews, owned colour key, non-exhaustive DialogResult, struct EditEvent variants, IconButton::command, Props::command on bound toggles

* canvas: the mini toolbar shows inside the page view body, where it maps its anchor through the canvas view

* ribbon: runtime labels as owned Strings, Props in scope for MenuItem::label, RibbonGroup icon 'static

* Tests read the canvas zoom through CanvasState::zoom and pass the context to qat_enabled

* More Colors settle hook returns Settle (S-L280) so it registers as a DialogHooks settle

* ribbon: wordart/shapes galleries take the menu body cx; TextRun built with its builders; symbol tile paints centred by the run's alignment; paint_style gets the content painter cx

* math pictures: MathSource takes an aspect and sizes its layout box from the thumbnail request, with thumb_aspect for the tile or button (S-L393)

* CatalogRef: Debug says whether a catalog is held, since the framework's Catalog has no Debug

* mini toolbar tests: read accessibility labels and popups through kittest's NodeT::accesskit_node

* tests.rs: readers move to the framework and canvas accessors that exist (ScriptedFiles held/queue/answer_to, Host::builder, page_rects()/canvas_rect(), drain_inbox, DefaultAppError, pixel-sized auto_scale_limit_over, ClipItem::Image, DropTarget::Elsewhere, dialogs::close_all)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* Reading probe returns an Outcome output; context menu rows label via MenuItem::new; colour preview matches cover non_exhaustive Preview; mini toolbar toggle icon is static

* fu2-app: app batch 2 rulings on batch 1 sets (S-L412, S-L365, S-L410, S-L411, S-L414, S-L419, S-L372, S-L368, S-L364)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* Ribbon menu rows take owned labels: framework Label is String or 'static str, not a borrowed &str

* QAT command menu request drops the removed opener field

* Colour child answer: DialogResult is non_exhaustive, so any other result is ignored

* Thickness menu face: Button has no icon_only, so it shows icon and label

* Tests: By filter helper with an explicit lifetime; accessibility label compared as Option<String>

* lead: last compile fixes (menu label lifetime; perf test reads the page view's resident pictures, S-L352)

* lead: binary compile fixes (egui DroppedFile trait, Lang accessor, print test binding)

* lead: dropped file bytes as Arc

* lead: examples reach the framework through craft:: (S-L230)

* lead: examples reach the framework through craft::ui::shell::embed (S-L230)

* lead: ui_shot example runs its main under the test build cl uses (harness = false)

* rr-app-ribbon: the ribbon slots are sized by their content (SlotSize::Content)

The default top slot is one options bar high with a one-line layout: the ribbon's groups landed beside the tabs and all
collapsed. Needs the framework's SlotSize::Content (branch red/ribbon-place).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* app tests: one harness that installs the craft runtime before the first frame

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* lead: WordApp::new registers the app icon set (ribbon-w13 icons::register had no caller)

* red app-t2 g4: tests step with the app's command input; print preview is a group; neutral SmartArt error

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* red app-t2 g6: tests step with the app's frame input; integrated frame for the title-bar test; undo list caps rows; table press hold released; test clipboard answers files

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* red app-t2 g3: dialog collections cap their rows, tests give dialogs their context and focus, glyph scan skips test data

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* red app-t2 g5: tests step frames through frame_input; split-button arrows named; collections capped; stale premises rewritten

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* red app-t2 g8: closing guard outlives window swaps, root focus/close, web save undo, collections natural height, test premises

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* red app-t2 g2 (lead commit)

* red app-t2 g1 (lead commit)

* red app-t2 g7 (lead commit)

* lead: backstage test row query borrows the name as long as the harness

* red app-t4 g2: key tests step through the app's frame hook; draw paths read format state without running a command

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* red app-t4 g8: custom dictionary caps its rows; chrome/language-pack tests press as a person does; sources test steps through the frame hook; audit and pane tests follow the framework's layout

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* red app-t4 g3: dialog test premises and Custom Properties labels, colors route, macro names, bookmark delete

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* red app-t4 g6: md_source focus waits for a non-measuring pass; window rig reports inner rects; smoke sends a close request; switch windows label; i18n tests

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* red app-t4 g5: table borders above selection areas, ruler markers follow drags, proofing list click-activates, test premises (focus, Enter=OK, extra buttons stay open)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* red app-t4 g7: failed web save keeps clean state, symbol dialog fields, table margin hold release, object release keeps Alt placement, test premises (toggle off, Escape chord, CJK glyphs, palette swatches, frame gesture)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* red app-t4 g4: frame hook in keytips tests, held list previews, crop keys and handles, read-mode context menu, keyboard overrides notes

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* red app-t4 g1: frames run the app's input hook and close path; page focus survives measuring runs; stale prompt dropped; recipients/styles collections capped

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* look-backstage: File pages as production: menu rows at the reading start, Discord above About, page titles over sections, Info property labels, Print preview fills the page

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* look-dialogs-b: TOC levels label, Options/Modify row and sample card metrics; watermark layouts in a row; About listed layout and version line

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* look-ribbon-1b: Styles gallery tiles are 2:1 and named under the sample; Paragraph shows whole at 1440 pt

The style gallery asks the framework gallery for 2:1 pictures (the sample crop, STYLE_TILE_W, at the
medium thumbnail height) with the style's name under each, instead of square tiles that shrank the
sample. A test pins the Home tab showing the Paragraph group whole in a 1440 pt window (framework:
red/ribbon-look's ribbon place, short font and size boxes, flat close ribbon buttons).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* look-backstage: the File side menu is as tall as the window (Sizing::FillHeight), About and the community link at its foot

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* look-chrome: title in a native frame; status bar view icons, fonts warning icon, plain zoom rail

The title bar shows the document title under the OS's title bar too
(TitleBar::title_when_native), as the old bar always did. The status bar's
view buttons are icon-only toggles in the old order (Read Mode, Print Layout,
Web Layout) with the current view pressed; the missing-fonts item has its
warning icon; the zoom slider has no fill up to the thumb. Tests
the_title_shows_in_a_native_frame and
status_bar_view_buttons_are_icons_with_the_view_pressed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* look-backstage: File page controls at stacked-row spacing, as production's

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* look-backstage: one contract import in pages.rs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* look-dialogs-a: Zoom opens on the view's percent (fraction x100), radios in a row, slider with its field inline, fit buttons in the body; Word Count as a plain label/count table over Close and Cancel; Font dialog as the old framed boxes: label table, kerning size and Points and above on the check box's line, Effects two to a line, preview at its own size; tests

* backstage test: import NodeT for accesskit_node

* red app-t5 g6: window rig reports the real child, ruler drags free of the framework snap

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* red app-t5 g4: smoke drops texture deltas, md_source tests step the hook frame, font list rows are tree items, Escape closes bar then menu, symbol pick confirms twice

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* red app-t5 g5: rotate objects about their centre, CJK stand-in in ribbon fit test, caret blink restart, Switch Windows node pair

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* red app-t5 g7: nav lists take natural height; menu/keytip tests step the frames the runtime needs

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* red app-t5 g8: Size dialog tests step through the app frame hook, Styles pane test scrolls its capped list, pack tests end the agent's injection

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* red app-t5 g3: dialog tests read the page's preview, the input hook, framework About key; Alert on refused custom property; Text Pane focus via framework stop

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* red app-t5 g1: harness hands app input before the pass; confirm via passes; pane/close/clipboard test premises

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* red app-t5 g2: keys tests follow the framework's IME ordering, interrupt and reset; undo folds an open SmartArt run; join survives a later pass

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* look-rest-2: File side menu rows in the side menu place at the side menu's width (production's 200 pt rail of 38 pt rows); Print settings column wraps its notes at the column width

* look-rest-2: side menu imports formatted; test pins the rail's width and row height

* panes test: MouseWheel carries its source

* red app-t6 g8: ribbon end order, cjk stand-in any family, capped findings list

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* red app-t6 g6: smoke finds the platform's answer button, info/side-menu tests use the framework's mechanisms, pack-bar click settles

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* red app-t6 g3: menus open from their opener, view buttons given, caret test animation time, switch windows rows

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* red app-t6 g2: icons dialog owns its scroll, effects grid fills, search opens in place, macros press runs once

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* red app-t6 g5: symbol pick OK, md pane Undo/Redo enabled by the field, live rotation pixel preview, text-box turn tolerance

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* red app-t6 g7: mini_toolbar and table_resize tests settle on the framework's layer and marker timing

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* red app-t6 g4: Alt+Q row follows the engine's build-time binding

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* red app-t6 g1: CJK stand-in in the shared harness, late-paste test clipboard, web-layout gutter, search dropped in Focus, split-button and held-Return tests

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* look-rest-3: Print settings column as production's: one Pages heading over both page lists, the page count muted, a rule above the export formats; Word Count rows a control's height apart

* look-ribbon-3: Design's style-set tiles and Home's style samples at the large thumbnail size (Gallery::thumb), as large as the old ribbon's; the samples show unscaled

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Ribbon: the Zotero tab is called Citations; Zotero is its provider

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* Citations: a Provider menu with Zotero as its one provider

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* citations tests: hold the layout the tabs borrow; import NodeT

* red app-t7 g6: settle the Install button before the person's click; wait for the caret glide; coverage check skips symbols kept from the English source

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* red app-t7 g5: smart-art category list natural height, print panel FillHeight, ribbon fit test checks on-screen controls

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* red app-t7 g2: Alt+Q test back on the Focus dialog, Tab hand-off owned by the framework, macros name read from the box, effects as pair rows, caret test waits for focus

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* red app-t7 g4: Size dialog fields take edit events, font list opens from the field, test keys release

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* red app-t7 g3: keymap test assigns through the keymap's Steal policy; smoke finds the prompt button by its resolved name

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* red app-t7 g1: Escape reaches select.collapse and the window's untaken Cancel (File page, Focus, Full Screen); web width settles after a drag; prompt helper asks the shown window; chord tests step the framework's frames

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* look-ribbon-4: the tab row's Comments and Editing are outlined and Share a filled accent button, as the old strip drew them (StripEnd::variant)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* look-rest-4: Font dialog's Effects columns as wide as their check boxes (production's table, Italic just past Superscript); File page section headings in the heading role (production's 15 pt) and page titles, Options' too, a step above them

* look-5: Home's Font and Paragraph button rows close up as the old ribbon's; Layout's Paragraph group as two label/field grids of small fields, indents to two decimals, a section gap before Spacing

* red stub g2: caret glide compares the view, which the page view reports on every pass

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* red stub g2: crop overlay takes the box as given so a drag survives to its commit

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* red stub g1: Alt+Q to Search Commands off macOS, ui.print state, scripts open no dialogs, equation state read without a command, size and New Label tests on the framework fields

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* red stub g2: collections in scrolling bodies cap their rows or take their natural height, as production shows them

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* red stub g2: Escape on the page dismisses an open text menu first

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* red stub g1: format.enclose gives a script an error without a shape, as the engine always has

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* red stub g2: the caret marks are shown over the view, so their strokes are not clipped to an empty rect

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* red stub g2: header/footer presses keep their release; the caret follow settles after a page jump; a wheel zoom keeps its exact zoom

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* red stub g2: tests find the framework's controls by their real roles and names; the ribbon group check covers the ribbon's groups

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* red stub g2: the canvas keeps the whole layout's page rects; the side-by-side test reads every page as production did

* red stub g2: the perf wheel helper sends point travel over the touchpad factor the framework now applies, as production's host did

* red stub g2: the alignment test steps once more for the fired command to run, as the port's command board does

* red stub g2: the Zoom dialog's programmatic OK answers with the percent it shows

* red stub g1: tests install no gallery story command sets (they took Mod+F from Find); the Navigation pane keeps its focus request until a pass takes it; Field Code opens before the first frame; report rows of the input-dialog test expect the report's data

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* red stub g2: a WordArt style pick hands the keyboard to the page

* red stub g1: the language pack bar's slot takes the bar's height, so a failure's line no longer clips Install out of reach

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* red stub g2: a tab click and a dismissed status-bar language menu give the page the keyboard back after the pass; the test reads the framework's open menus

* red stub g2: the caret follow waits for the page's settled rect and places an unplaced page's caret from the whole layout

* red stub g2: the canvas reports the area the pages show in; the wheel-zoom test points at its centre, as production's canvas rect was

* look-6: a script's launcher command (format.fontDialog, Zoom, Page Setup) opens its dialog as production did; commands lacking input still open none

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* look-6: the File page body stands on the window background (production's #f9f9f9), not the white panel

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* red stub g2: the app's Host carries the embedded catalogs, so framework words translate; catalog labels and command hints are translated; the canvas's zoom chords are dropped for Word's

* red stub g2: the caret glide test catches the caret the frame after it sets off, as on main (the set-off frame draws it where it was)

* red stub g2: Manage Styles and Customize Ribbon lists scroll their own rows (row caps as main's boxes); the Arabic Go To check compares the targets with the framework dialog's button column

* red stub g1: Alt chords fire from the page (PlainKeysWait; Alt+F7/Alt+F8 left to Word's commands), Macros reopened keeps its hooks, the recipient grid holds its rows through the click that ends an edit, ui.clickText maps page points by the page's scale; chrome tests read the title bar outside the File page and open the desktop chooser as its pump does

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* red stub g2: watermark, citation style, TOC level, Zotero, caption, cross-reference and icon category labels are translated; the audit reads a wrapped marked label's second line as marked, and allows a hover hint's shortcut and separators, listed or cut-short names and trimmed licence texts

* red stub g1: the Print page decides what an opening holds back in the opening frame's first pass, as appeared() now holds through all of that frame's passes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* red stub g1: tests give a key and its text (or one IME batch) one frame, as kittest's event runs a frame per event; Paste Formatting's key reads its chord when the modifiers are already up; ⌘Q is the runtime's close (S-L332); Search's Escape meets the draft rule first

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* red stub g1: wrap the command board's import at the repository width

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* red stub g1: the PDF bytes test expects the equation's x the math face can draw (plain x on a host with no math font, as in the pre-port baseline)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* red stub g1: the smoke test turns AccessKit on for its own context, so the Save Changes prompt's buttons are in the tree it searches

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* look-7b: Custom Watermark's text field asks for 38 characters (Param::field_chars), about the old dialog's 280 pt; the field length gave about 195 pt

* look-7a: File pages: titles at production's 26 pt (WordCraft's display size), the page's 40 pt margin clearing the move band, the rail's footer in the side menu place (white ink), Protect Document a section apart on Info, the Print settings a frameless 380 pt column with chevrons for the sheets; tests

* red stub g2: Shift+Delete cuts the selection and does nothing without one (EditorInput::Delete.shift); the page reports its marked text (EditorState::marked); one-frame input back in the refused-delete and disabled Alt chord tests; a Delete after a commit waits out the framework's composition-key guard; a user binding reaches the keymap a harness frame later; window.move/size keep their defaults

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* red stub g2: Ctrl+wheel zoom test keeps the place under the pointer at each notch: a reflow centres the rows, so the page under the pointer is taken when the notch comes, and a pointer over the centre gutter moves onto a page first

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* merge app-ui: resolve production main into the port's UI

- ribbon/home.rs (4e8c9d55, #3172): the Paste face is named "Paste"; its tooltip adds
  edit.paste's chord as the platform writes it (commands::resolve + tooltip::with_chord).
  tests.rs: the_paste_button_is_named_without_a_mac_key rewritten on the port harness.
- dialogs/paragraph.rs (32b4ab57): the framework ParagraphDialog's Special box does the work;
  intersect leaves By blank when the paragraphs' kinds differ, so a kind picked then starts at
  the half inch. dialogs/tests.rs: the three Special-box tests rewritten on the dialog host.
- dialogs/dialogs_review.rs (bce64c0e): the port's Compare form already names its fields.
- canvas.rs, canvas/tests.rs (07c0a893): keep the port's composition painter and state;
  production's egui composition painter, its fields and its tests are dropped (framework items).

* merge app-shell: resolve production main into the port

- engine lib.rs: export set_bookmark_error/set_reference_error beside system_locale
  (the port dropped the KeyMap re-export; it stays dropped).
- app.rs: logic() sets the PAGEREF/REF error texts in the interface language.
- file_dialogs.rs: Save As starts in the open file's folder, made absolute
  (#4143), through PickRequest::directory; tests carried to ScriptedFiles.
- window_geometry.rs: 600 pt minimum width (#5886) and its test.
- chrome/status_bar.rs: Page item bound to edit.goto so its tooltip shows the
  platform's Go To key (#3172); language tooltip names the language in full.
- chrome/tests.rs: narrow-window title bar and status bar tests rewritten
  against the app harness.
- a11y.rs: test expects zero-based AccessKit levels (#3173); the mapping
  fix is the framework's.
- chrome.rs, theme.rs, app/fonts.rs, windows.rs, windows/tests.rs,
  keytips/tests.rs: production's replaced egui code and cut tests dropped.

* land sync: canvas.rs declares its tests module again (dropped in canvas-w9, so canvas/tests.rs, markup.rs and overlays.rs never compiled)

* land sync: the app takes craft gpu-startup (the sync moved craft::gpu::configure behind it)

* red stub g1: canvas tests compile against the ported canvas (imports, kurbo/Env/commands paths, equation_frame sizes, page_grid)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* red stub g1: canvas tests step through the app's input hook; caret reports the editor from an off-screen page

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* red stub g1: candidate window at the composition cursor; page keeps its keyboard across a document switch; IME, tip and Hide White Space tests on the ported mechanisms

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* red stub g1: a pass whose input edits the document runs again so its frame paints the edit; read-only balloons open no edit; balloon tests type in the card's field

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* red stub g1: a right click selects what it clicked before its menu opens; the page under a point is the nearest shown band; the status bar's page in view measures from the view's top edge

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* red stub g1: Hide White Space gets the page bodies; a refused balloon draft stays when the balloon is left; context menu, crop and ruler tests on the ported mechanisms

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* red stub g1: comment drafts stay with their document across a window switch; Hide White Space test probes the overlap inside the text areas

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* red stub g2: rotated effect-extent fixtures use Word's exchanged-frame measure (craft-libs #2227)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* red stub g1: the title bar's search and Discord and the status bar's zoom slider and Focus give way in a narrow window (#5886 fit, measured per step); the IME composition draws in the text's face, size and baseline through Draw::face_run; narrow-window tests read the bar row and the painted texts; production's three composition tests

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* land sync: a refused input-method edit asks the framework for the interrupt (ToolPass::ime_interrupt), so the commit keeps its InputMethod cause

* port build loop: craft-i18n and craft-fonts come from the environment (CRAFT_I18N_DIR, CRAFT_FONTS_DIR), not machine paths in the manifest

* Resolve the craft framework from https://github.com/storytold/craft-libs next at 362eb2820996b475e6f21967c561219dbde24343

Every framework path dependency and patch is now a git dependency at that revision.
Cargo.lock is regenerated against it separately.

* Cargo.lock: resolve against craft-libs next at 362eb2820996b475e6f21967c561219dbde24343

* port: cargo fmt

* fonts: drop the face_names re-export the ported UI fallback no longer uses

* Restore the [patch.crates-io] block: the egui and winit forks and the vendored crates the framework builds with

* Workspace clippy: dead code and unused imports the port left, test-only helpers under cfg(test), the examples report a failed install

* Tests: headings read in tree order, not egui id-map order; the picker Install is aimed after downloading goes off, which adds a licence line to each row and moves it

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Ribbon: own icons under wordcraft.* names so the catalog no longer shadows them; 32/17-pt ribbon icons and corner launcher

* Ribbon: filled menu arrows right after the label, as the old ribbon

* Ribbon: 22-point small-row pitch (20-point rows a tight gap apart), RibbonLook

* Ribbon: Draw colour/thickness and Layout align/group/rotate show icons alone; Window collapses to the more icon, as the old ribbon

* Styles gallery: sample letters on the ribbon with no white paper box, as the old ribbon

* Title bar: tool-size QAT icons, the filled undo-list arrow and the small AutoSave switch, as the old title bar

* Ribbon: tabs in the text colour over a 3-point underline

* Ribbon: body on the old lighter band with its rules

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FypgCZhHKRuRB5wZUiw6BE

* Ribbon: framed Styles gallery; Style Sets drop their buttons while all show

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FypgCZhHKRuRB5wZUiw6BE

* wasm: gate native-only craft features (dialogs, update, automation client, default app) off wasm32

craft-dialogs (rfd folder picker, file paths) and craft-update (ureq/ring, getrandom 0.2) are
documented native-only, as are craft::automation's client/security/args/dialogs and
craft::platform::default_app. ui-egui takes `dialogs` and `update` through a
non-wasm32 `craft` dependency; wordcraft-mcp's `Remote` bridge moves to backend/remote.rs,
native only. The code that used them is gated the way production main gated its
native-only paths, with a plain fallback on the web. Also drops dead-code/unused-import
warnings on wasm32 and keeps chrono's parser available there.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* MCP: pin the shared server refusing a request without the JSON-RPC version (craft-libs #2444)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Resolve the craft framework from https://github.com/storytold/craft-libs next at a5f6cd7f6ccd560438e3bbeb1209aa117ba957dc

Every framework path dependency and patch is now a git dependency at that revision.
Cargo.lock is regenerated against it separately.

* Cargo.lock: resolve against craft-libs next at a5f6cd7f6ccd560438e3bbeb1209aa117ba957dc

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* port: the default-chords rows stay mutable only where the off-macOS rows extend them (macOS clippy)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* port: the web build embeds its Japanese interface face when the craft-fonts checkout has one, CRAFT_FONTS_REQUIRED binds the native build

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* port: wordcraft-web builds against the ported UI: the host takes the framework language, the legacy prefs parser is imported, no native-window hook on the page

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* ui-egui: use the framework constructors for non_exhaustive types

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* port test: the files clipboard keeps any absolute path from a uri-list, so the copied-files trials run on Windows

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Resolve the craft framework from https://github.com/storytold/craft-libs next at 1e48c0807e18c5f5ae25b6227fde52281942f288

Every framework path dependency and patch is now a git dependency at that revision.
Cargo.lock is regenerated against it separately.

* Cargo.lock: resolve against craft-libs next at 1e48c0807e18c5f5ae25b6227fde52281942f288

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* port test: on macOS the smoke close goes to the platform quit, so Don't Save shows as no second prompt

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Resolve the craft framework from https://github.com/storytold/craft-libs next at 1e48c0807e18c5f5ae25b6227fde52281942f288

Every framework path dependency and patch is now a git dependency at that revision.
Cargo.lock is regenerated against it separately.

* Cargo.lock: resolve against craft-libs next at 1e48c0807e18c5f5ae25b6227fde52281942f288

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Resolve the craft framework from https://github.com/storytold/craft-libs next at 27c1c0ebb1d16adf97d09952bb781e69f9962e46

Every framework path dependency and patch is now a git dependency at that revision.
Cargo.lock is regenerated against it separately.

* Cargo.lock: resolve against craft-libs next at 27c1c0ebb1d16adf97d09952bb781e69f9962e46

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Resolve the craft framework from https://github.com/storytold/craft-libs next at 243d68e12d05e89122db6d154924bf1992e10d38

Every framework path dependency and patch is now a git dependency at that revision.
Cargo.lock is regenerated against it separately.

* Cargo.lock: resolve against craft-libs next at 243d68e12d05e89122db6d154924bf1992e10d38

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-20 14:02:07 +00:00

263 lines
23 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Control protocol
> **Last updated:** 2026-11-18 · The control channel authenticates once per connection with a token (`auth`), replacing the per-request key. Earlier: Correct the force-close request envelope and document the optional command search parameter; command behavior unchanged. #6146: scroll speed preferences (`ui.scrollSpeed`, `ui.touchpadScrollSpeed`); #6159: refuse ui.screenshot on secondary document windows and support root window selection with view.switchWindows.
Start the app with a control port: `wordcraft --control 7981` (or `WORDCRAFT_CONTROL_PORT=7981`).
A missing or invalid port after `--control` (not 1–65535) prints an error and exits with status 2.
It listens on `127.0.0.1` only. Authenticate once per connection with the window's token (see
[Token](#token)), then send one JSON object per line; each gets one reply line:
```json
{"id": 1, "method": "auth", "params": {"token": "…"}}
{"id": 1, "ok": true, "result": {"authenticated": true}}
{"id": 2, "method": "engine.execute", "params": {"command": "text.insert", "params": {"text": "Hello"}}}
{"id": 2, "ok": true, "result": {"anchor": {...}, "focus": {...}}}
```
Errors come back as `{"id": …, "ok": false, "error": "message"}`. A failed command leaves the
document unchanged. Before authentication, a line that isn't a valid `auth` gets
`authentication required` and the server closes the connection (so an HTTP request sent to the
port can't run a command). After it, a line that isn't valid JSON gets a `bad JSON` error and the
connection stays open.
## Token
Any local program (and possibly a web page) can reach a loopback port, so every connection must
authenticate with the window's token. Unless a token is supplied (below), once the port is bound
the app writes a random token (256 bits, as hex) to
`<settings>/control-key.<instance>` and removes the file when the window closes; a new start
writes a new token. `WORDCRAFT_PROFILE_DIR` overrides the whole profile folder for isolated runs,
including recovery copies. See [local recovery](recovery.md). `<settings>` is the folder that holds the preferences: on Linux
`$XDG_CONFIG_HOME/wordcraft` (by default `~/.config/wordcraft`), on macOS
`~/Library/Application Support/WordCraft`, on Windows `%APPDATA%\WordCraft`. `<instance>` is the
Flatpak instance id inside Flatpak, and `local-<port>` otherwise. On Unix the file has mode 0600.
```sh
cat ~/.config/wordcraft/control-key.local-7981 # Linux, outside Flatpak, port 7981
```
To choose the token, pass `--control-token <hex>` or `--control-token-file <path>` (or set
`WORDCRAFT_CONTROL_TOKEN` or `WORDCRAFT_CONTROL_TOKEN_FILE`; the port is `--control <port>` or
`WORDCRAFT_CONTROL_PORT`). The two are alternatives, and a token file you name is not removed on
exit.
- Send `{"method": "auth", "params": {"token": "…"}}` as the first line of every connection
(reply `{"ok": true, "result": {"authenticated": true}}`); later requests carry no token. A
challenge handshake (`auth.challenge`, then `auth` with a proof) proves the token without
sending it.
- Any other first line, or a wrong token, gets `authentication required` and the app closes the
connection. A second `auth` gets `already authenticated`; the connection keeps serving.
- A line over 1 MiB gets an error reply, and the app closes the connection.
- A connection that has not authenticated within 10 s of being accepted is closed, whatever it
sends. After that the connection may stay idle.
- At most 16 connections are served at once; the next one gets `connection limit reached`.
`wordcraft-cli mcp --connect` takes the token from `WORDCRAFT_CONTROL_TOKEN`, or else from the
token file for the port it connects to, and reads it again on every new connection (the app may
have restarted). It sends the token only to the app's own address, `127.0.0.1` (`localhost`
connects there too, never to `::1`): another loopback address such as `::1` or `127.0.0.2` is not
where the app listens, so whoever listens there gets no token (#3699). For
any other host it sends nothing and says why: to drive an app on
another machine, forward its port to `127.0.0.1` (for example `ssh -L 7981:127.0.0.1:7981 host`)
and set `WORDCRAFT_CONTROL_TOKEN` to that app's token.
## Delivery and startup failures
If the accept thread cannot start, startup reports that the control server is off and removes
its newly written token file; it does not report a listening server.
A client that encounters a write error or a lost reply must treat delivery as unknown once it
has attempted to send. The MCP bridge does not replay mutations in this case, or image exports
with a string `path`; see [delivery failures](mcp.md#delivery-failures).
A request that times out while still queued is cancelled and cannot run later. If execution
has already started, the timeout reports an unknown outcome rather than promising cancellation.
## View › Window
The app's native windows (one per document, or several on one document) take part in View ›
Window (#322): `view.arrangeAll` tiles them over the monitor, `view.sideBySide {value?, window?}`
places this window and another one in the left and right halves and turns on Synchronous
Scrolling, `view.syncScroll {value?}` turns that on or off, and `view.switchWindows {id?, window?}`
lists documents and switches documents or windows. For Side by Side, `window` is an id from
`ui.inspect` → `windows.others` and is optional when only one other window is open. For Switch
Windows, `window` is an open window's key. A secondary-window screenshot refusal can include
the root window key in the suggested `view.switchWindows` command. The
commands are disabled where there is one window (web, CLI, MCP without the app). Wayland doesn't
let apps move windows, so there Arrange All and Side by Side only resize.
## Methods
| Method | Params | Result |
|---|---|---|
| `engine.execute` | `command`, `params`, `doc?` | the command's result (any id from `engine.commands`, including UI commands `ui.tab`, `ui.dialog` (`{"name": dialog, "part"?: table style part}`; `part` opens New / Modify Table Style (`newTableStyle` / `modifyTableStyle`) on that part: `wholeTable`, `headerRow`, `firstColumn`, `bandedRows`, `nwCell`… as `table.modifyStyle` names them), `ui.backstage`, `ui.zotero.*` (see `docs/zotero.md`), `ui.language` (`{"value": "auto"\|"en"\|"zh-hans"\|"zh-hant"\|"ja"\|"pt-br"\|"es"\|"uk"\|"sr"\|"sr-latn"\|"et"\|"tr"\|"ru"\|"pl"\|"de"\|"it"\|"cs"\|"hu"\|"fr"}`), `ui.theme` (`{"value": "system"\|"light"\|"dark"}`; `system` follows the OS appearance, light when it reports none), `ui.interfaceSize` (`{"value": "auto"}` or `{"percent": 50–300}`, clamped; no value reads it; `auto` keeps the system display scale, capped so a window of at least 900x460 points fits the screen (#4030), a percentage is absolute, so 100 is one screen pixel per point (#822); the result's `percent` is the size drawn at and `auto` whether it follows the system; document zoom stays `view.zoom`), `ui.animations` (`{"value": "system"\|"on"\|"off"}`; no value reads it; `system` follows the system's animation setting, which the desktop app reads on Windows, macOS, Linux and the BSDs and the web app from `prefers-reduced-motion`, and means on where the system doesn't say; the result's `enabled` is what the setting comes to and `system` what the system reports, `null` when it doesn't say), `ui.fileBrowser` (desktop: `{"purpose": "document"\|"picture"\|"recipients"\|"save"\|"export"}` opens WordCraft's own file browser, for when the system file dialog doesn't show up, #576; `export` offers File › Export's formats as its types, #3535), `ui.saveAsTemplate` (File › Save As › Save as Word Template: the Save dialog for a `.dotx`, starting in the user templates folder; the result's `dir` is that folder, `null` on the web, #2852), `ui.caretAnimation` (`{"value": true\|false}`; no value reads it; off, the caret jumps and blinks on and off instead of gliding and fading), `ui.startScreen` (`{"value": true\|false}`; no value reads it; on, the default, the desktop and web apps start on File › Home when launched with nothing to open, #766), `ui.alignmentGuides` (`{"value": true\|false}`; no value reads it; on, the default, moving a picture or shape snaps it to the page, the margins and other objects, with guide lines while dragging; Alt moves freely), `ui.quickAccessToolbar` (`{"value": true\|false}`; no value toggles it; false takes the Quick Access Toolbar out of the title bar, as its menu's Hide Quick Access Toolbar does, and true brings it back, #1945), `ui.displayServer` (`{"value": "auto"\|"wayland"\|"x11"}`; no value reads it; File › Options › Advanced › Linux display server, which the desktop app reads on Linux and the BSDs at its next launch; `WORDCRAFT_WAYLAND` overrides it, #2184), `ui.scrollSpeed` (`{"value": "slow"\|"normal"\|"fast"}`; no value reads it; mouse-wheel scroll speed, #6146), `ui.touchpadScrollSpeed` (`{"value": "slow"\|"normal"\|"fast"}`; no value reads it; scales touchpad scrolling on Wayland: slow 2×, normal 4×, fast 8×; on macOS: 0.5×, 1×, 2×; File › Options › Advanced › Scrolling › Touchpad scroll speed, #6146), `ui.statusCount` (`{"value": "words"\|"characters"\|"charactersNoSpaces"}`; no value reads it; what the status bar's count shows — words (the default), characters with spaces, or characters without spaces — kept between runs, #2797), `ui.recentRemove` (`{"path": entry}` takes that document off the recent list — `path` must be an entry on the list; on the desktop the new list is saved right away: the result's `saved` is true then, false with `saveError` when the write failed (the removal still holds for this run) and null where the host keeps no preferences (the web app, or preferences switched off), #2716), `ui.recentClear` (`{}` clears the whole list; the result reports `removed`, the new `recent` and `saved` as above), `ui.focusRibbon` (`{"value": true\|false}`; no value toggles it; in Focus, true drops the ribbon down over the page, as the bar's ⋯ does, and false puts it away, as a click on the page does; outside Focus it stays put away, #1678), `ui.contextMenu` (opens the page's context menu below the caret, as Shift+F10 does), `ui.paneDock` (`{"pane": "navigation"\|"clipboard"\|"styles"\|"styleInspector"\|"accessibility"\|"altText"\|"formatShape"\|"restrictEditing"\|"comments"\|"smartArtText", "dock"?: "left"\|"right"\|"float", "before"?: pane\|null}`; no `dock` reads it; docks or floats a task pane as its menu does, kept between runs; Styles is `view.stylesPaneDock`, #1756; `before` puts the pane directly before that pane in the order, outside it on their edge, as a drop over a docked pane's outer third does, and `null` after every pane; the order is kept between runs)…) |
| `engine.commands` | `search?` | every command: id, label, location, shortcut, params, enabled |
| `document.inspect` | `text?`, `doc?` | blocks (text, style, runs, lists, tables), parts, sections, selection, pages |
| `ui.inspect` | — | UI state, view, dialog, window size, page rects on screen, caret, comment balloons (`balloons`: id + screen rect; `balloon`: the selected one), perf; `windows`: the other windows as the drawn window sees them (`available`, `others`, `sideBySide`, `syncScroll`); `document`: the active document's id; `documents`: the open documents (`id`, `title`, `path`, `dirty`, `active`) |
| `ui.click` | `x`, `y`, `button?`, `count?`, `shift?`, `cmd?`, `alt?` | real pointer input at window coordinates |
| `ui.clickText` | `page` (0-based), `x`, `y` (points from the page's top-left), `count?` | click inside a page |
| `ui.move` / `ui.drag` | `x`,`y` / `x`,`y`,`toX`,`toY`,`steps?` | pointer move / drag |
| `ui.press` / `ui.release` | `x`,`y`, modifiers | primary button down / up there (with `ui.move` between: a drag you can screenshot halfway) |
| `ui.wheel` | `x`, `y`, `dy`, `dx?`, `unit?` (`point`/`line`/`page`), `phase?` (`start`/`move`/`end`), modifiers | mouse-wheel or trackpad scroll at window coordinates (`dy` < 0 scrolls down) |
| `ui.key` | `key` (`B`, `Enter`, `Left`…), `shift?`, `alt?`, `cmd?` | key press through egui (shortcuts apply) |
| `ui.text` | `text` | typed text through egui |
| `ui.screenshot` | `path?` | PNG of the window in the root viewport: written to `path`, or without one returned as base64 `png` in the reply. Capturing a secondary document window is not supported by the viewport renderer; select the root window with `view.switchWindows {"window": root}` first |
| `ui.render` | `path?`, `page?` (1-based), `scale?`, `doc?` | PNG of a page, rendered by the engine: written to `path`, or without one returned as base64 `png` in the reply (never a fixed name in the shared temporary folder) |
| `ui.parity` | — | feature-catalog parity |
| `ui.resize` | `width`, `height` | asks for that window content size in points; sizes that aren't positive and finite are refused, the rest are clamped to the app's minimum (600 × 480, #5886) and to the largest surface the GPU can draw (at most 16384; that limit wins over the minimum), and the reply's `width` and `height` are the size asked for |
| `ui.focus` / `app.quit` | | window control |
Any other method name is treated as a command id: `{"method": "format.bold"}` works.
**Task pane docking.** `ui.paneDock` and `view.stylesPaneDock` use **physical** `left` / `right`
(the window's left and right edges), matching Dock Left / Dock Right in the pane menu. That stays
true in a right-to-left interface language: `{"dock":"left"}` always puts the pane on the physical
left and the command reports `"left"`. A pane that has never been docked keeps its default
start-/end-edge role when mirrored: start-default panes (e.g. Navigation) open on the physical
right in Arabic, end-default panes (e.g. Comments) on the physical left. Saved docks and explicit
requests are never flipped.
Language packs (see [MCP](mcp.md#language-packs)) are commands like any other: `proof.packs`,
`proof.installPack {"locale": "nl"}` and `proof.removePack {"locale": "nl"}`. Through the control
channel they act on the running app's packs, and install only while its downloading setting is on;
they never turn it on, and neither does a `ui.click` or `ui.key` on the app's Install, Add a
language… or Refresh buttons. An install or a refresh runs in the background
(`"started": true`); `proof.packs` reports its progress, then the result.
`ui.dialog {"name": "languageData"}` opens About › Language data.
### Open documents
Several documents can be open at once. Each has an id, a whole number that stays the same while
the document is open and is never reused by the running app. On the desktop each open document
has a native window of its own; the web app shows them one at a time in its one window. One
document is the active one: on the desktop, the document of the window focused last (the active
window); in the browser, the one the window shows. Commands work on it unless told otherwise.
- `file.new` opens another document in a new window, focused, and makes it active. `file.open`
does the same with a file; it replaces a blank document nobody has used yet in that document's
window, and a file that is already open becomes active again and its window comes to the front
(`"alreadyOpen": true`). Its result carries the document's `id`.
- `view.switchWindows` lists the open documents (`{"documents": [{"id", "title", "path",
"dirty", "active"}]}`); with `{"id": n}` it makes that document active and brings its window to
the front. With `{"window": key}` it selects that window directly and brings it to the front.
- `file.closeDocument {"id"?, "force"?}` closes a document; its window closes with it unless it
is the last window.
- `engine.execute`, `document.inspect` and `ui.render` take `doc`, the id of the document to work
on, next to their other params. The command runs on that document and the active window stays
active. A dialog or page the command opens (Save As, Print) opens in that document's window,
which comes to the front:
```json
{"id": 2, "method": "engine.execute", "params": {"command": "text.insert", "params": {"text": "Hello"}, "doc": 3}}
```
`doc` left out, or `null`, is the active document. An id that names no open document, or a value
that isn't a whole number from 0 up, is an error and nothing runs. Window commands (`ui.*`) work
on the active window only: with the id of another document they are an error.
### The active window
Input and window methods go to the active window, the one focused last: `ui.click`, `ui.key`,
`ui.text`, `ui.wheel` and the other input methods (coordinates are that window's),
`ui.screenshot` (a PNG of that window), `ui.inspect` (its size), `ui.resize` and `ui.focus`. To
work in another window, make its document active first with `view.switchWindows {"id": n}`.
`ui.screenshot` is the exception when multiple document windows are open: the desktop renderer
captures only the window in the root viewport (the first window opened, until that window closes and
another is adopted in its place). While the active window is a secondary document window in a separate
native viewport, `ui.screenshot` returns an error directing the caller to select the root window
instead of hanging for 8 seconds and timing out. Select the root window with
`view.switchWindows {"window": root}` and request the capture again. The error gives the root
window key when it is available.
The `CharProps` and `ParaProps` that `format.set`, `para.set` and `styles.modify` take are listed
in [MCP server](mcp.md#character-and-paragraph-properties).
Positions are `{"story": "body" | {"part": n}, "path": [block, row, cell, block, …], "off": byteOffset}`.
### Keyboard and text input
`ui.key` and `ui.text` go to this window's focused widget even when another app is in front
(#2420). A focused Find field receives the text; a document receives it only while its canvas
owns keyboard focus. Shortcuts, dialogs and document protection still apply. These methods do
not activate the native window. `ui.focus` separately requests native activation.
The `{"queued": true}` reply acknowledges the input queue, not a completed edit. Input is applied
on subsequent UI frames. Inspect the resulting document or widget state before continuing with
an operation that depends on it; do not replay an edit simply because its effect is not immediate.
### Closing the document
`engine.execute` never shows the Save / Don't Save / Cancel prompt, so a command that would
discard unsaved work is **refused with an error** (the app keeps running and the edits stay);
save first (`file.save`), or pass `{"force": true}` to discard the changes and go ahead.
`file.close` closes the shown document, so it is refused while that document has unsaved
changes; the bare form `{"method": "file.close", "params": {"force": true}}` (a method name that is a
command id) is guarded the same way, and only a boolean `true` counts as `force`. A document
without unsaved changes closes at once (#1268). Closing closes the document and its window, and
the window focused before it becomes the active one. The last window stays open with no page,
and `file.new` or `file.open` goes on from there (#1712); closing it doesn't quit the app. With
`doc` naming a document in the background, `file.close` closes that document and its window under
the same rule (unsaved changes need `{"force": true}`), and the active window stays active.
When another window shows the same document, `file.close` closes only the window it is sent to:
the document and its unsaved work stay open, so nothing is lost and the command is **not**
refused (#3274).
`file.new`, `file.open`, `file.recover` (with `restore`) and the mailings merges open their
result as **another document beside** the open ones and leave the unsaved one alone, so they
lose nothing and are never refused.
`file.closeDocument` closes the document its `id` names (the active one when the `id` is
absent), so it is refused while that document has unsaved work: changes that aren't written to
a file, a save the browser's picker hasn't finished, or a comment still being typed. Pass
`{"force": true}` to discard that work and close the document; only a boolean `true` counts as
`force`. The refusal and the Save Changes prompt ask about the same work, so they cannot
disagree (#3274).
`app.quit` closes every open document, so it is refused while any of them has unsaved changes:
the app keeps running and the work stays. Save first, or pass `{"force": true}` to discard the
changes and quit. Only a boolean `true` counts as `force`.
### Native printing
`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.
`ui.printSubmit` / `ui.print` also accept the upstream PDF page settings (`range`, `pages`,
`parity`, `copies`, `collate`). Native printing renders the selected pages once and passes
copies/collation to the spooler; the browser and `file.printPdf` keep copies in the PDF.
Omitting native `copies` uses the configured `ui.printSettings` value. `collate` defaults to
File › Print's setting; invalid ranges submit no job. `paper` (`none`, or a Layout › Size name
such as `Letter`, `Legal`, `A4`) is Scale to paper size (#2108): every page is scaled onto that
paper and centred, and native jobs ask the spooler for that `media`; the document's page size is
unchanged. `file.printPdf` takes it too; an unknown paper submits no job.
`engine.commands {"search":"print"}` lists the engine print commands and the app-owned
`ui.printSettings`, `ui.printSubmit`, and legacy `ui.print` alias, with current enablement
and their parameter documentation. Search is case-insensitive across IDs, labels, locations
and parameter descriptions. Listing commands never discovers printers, submits a job or opens
a dialog. Settings inspection is always available; submission becomes enabled when the native
printer is ready, or when the browser host provides its print flow.
### Physical print sheet layout
`ui.printSubmit`, `ui.print` and `file.printPdf` accept `pagesPerSheet`: the integer
1 (default), 2, 4, 6, 9 or 16, or `"booklet"` / `"bookletReverse"` for left/right binding.
These settings change only the print PDF, leaving document Page Setup unchanged.
Selection/range/parity are applied first. N-up fills cells in row order; booklet mode
pads the selected pages to a multiple of four and pairs outer/inner pages. Copies
repeat complete sheet plans, preserving blank slots at copy boundaries. Native copies
remain a spooler setting. Two-up and booklet sheets are landscape. Use duplex on the
short edge for folded booklets; this does not configure a printer's duplex capability.
The preview shows physical sheet sides, before copies, using the same sheet plan.
Explicit `paper` chooses the physical sheet; otherwise the first selected page supplies
its size. Independent Page Setup multiple-page modes (#2414) are not required.