@a3s-lab/office 0.8.0 → 0.9.0

package/COLLABORATION_ROADMAP.md

@@ -111,8 +111,8 @@ Redis/NATS fan-out plus a distributed writer/lock policy.
 Status: browser collaboration foundation, participant roster, remote
 selection/caret projection, participant navigation, durable review-only
 comment and suggestion modes, immutable suggestion-decision audit, and native
-text/options/bounded structural paragraph/comment mutations implemented; rich
-native mutation parity remains pending.
+text/options/bounded structural paragraph/comment/suggestion mutations
+implemented; rich native mutation parity remains pending.
 
 - TipTap is bound to `document.content` through
   `@tiptap/extension-collaboration`; StarterKit undo/redo is disabled and the
@@ -167,12 +167,15 @@ native mutation parity remains pending.
   without the additive roots remain readable, and a final decision clears
   local history that could otherwise resurrect the decided mark.
 - Rust, CLI, MCP, and A3S Code expose `document-comment-create`,
-  `document-comment-reply`, `document-comment-set-resolved`, and
-  `document-comment-delete`. Projection schema v2 returns attributable threads,
-  replies, anchor text, paragraph/text identities, browser-compatible UTF-16
-  offsets, resolution, and detached state. Native and browser fixtures cover
-  restart, reordered delivery, stale anchor guards, idempotent retries,
-  ownership failures, and cross-language convergence.
+  `document-comment-reply`, `document-comment-set-resolved`,
+  `document-comment-delete`, `document-suggestion-create`, and
+  `document-suggestion-decide`. Projection schema v3 returns attributable
+  comment threads, replies, anchor text, live suggestion identities and exact
+  placements, immutable final decisions, paragraph/text identities,
+  browser-compatible UTF-16 offsets, resolution, and detached state. Native and
+  browser fixtures cover restart, reordered delivery, stale guards, idempotent
+  retries, ownership/mode failures, atomic replacement decisions, and
+  cross-language convergence.
 - The A3S Boot backend permits `edit` content/review updates, semantically
   validated Document `comment` review-only updates, and semantically validated
   Document `suggest` proposal updates. Signed actor identity and display name
@@ -183,10 +186,6 @@ native mutation parity remains pending.
 
 Remaining:
 
-- Add closed typed native projection and mutation variants for creating
-  Document suggestions and deciding them through CLI/MCP/A3S Code. The current
-  typed native mutation set can synchronize the resulting Yjs state but does
-  not originate these two workflows.
 - Prove concurrent full-table, list-restructure, section, comment, and revision
   workflows, plus DOCX import/export after merged edits.
 - Expand native convergence from bounded paragraph edits to complete table,
@@ -248,9 +247,9 @@ comments, and delete-vs-edit cases converge and survive PPTX round trips.
 
 ### Phase 4: Spreadsheet
 
-Status: browser collaboration foundation and native conflict-local cell
-mutations implemented; structural operations, native recalculation parity, and
-XLSX concurrency coverage are pending.
+Status: browser collaboration foundation plus native conflict-local single-cell
+and atomic batch-cell mutations implemented; structural operations, native
+recalculation parity, and XLSX concurrency coverage are pending.
 
 - Stable sheet/named-range order arrays, ID-keyed records, and append-only
   creation claims avoid a serialized workbook or dense worksheet root.
@@ -283,11 +282,16 @@ XLSX concurrency coverage are pending.
   and an empty sheet's first write stays sparse. Native restart, real CLI/MCP
   subprocesses, and browser Yjs duplicate/reordered delivery cover the same
   update contract.
+- `spreadsheet-batch-cells` translates one paste, fill, or other bounded user
+  gesture into 1 to 4,096 distinct coordinates in one sheet and one Yjs
+  transaction. Set/create changes retain recursive optimistic guards; delete
+  changes require an exact complete observed cell. Every change is preflighted
+  against one shared sheet snapshot, so one conflict rejects the entire batch
+  without partial fields, presence markers, dense dimensions, or durable log
+  growth. Single-cell mutations use this same kernel.
 
 Remaining:
 
-- Translate one user gesture into one transaction; batch paste/fill/sort/filter
-  without emitting a document-sized replacement.
 - Add stable structural operations and reference transforms for row/column
   insertion/deletion, merged ranges, tables, sort, and named references.
 - Treat calculated values as derived once browser and native recalculation are
@@ -388,11 +392,11 @@ destructive actions remain attributable, reviewable, and non-retryable.
 
 Status: native Yrs replica store, resumable CLI/MCP event streams, `a3s code`
 projection, a host-injected live CLI transport session, authenticated browser
-suggestion-update authorization, and typed Markdown, Document content/comment,
-Spreadsheet cell, Presentation scene-element, PDF annotation/form-value, and
-PDF redaction/page-operation review mutation surfaces are implemented; typed
-native Document suggestion/decision mutations, the remaining format mutations,
-and native presence projection are pending.
+suggestion-update authorization, and typed Markdown, Document
+content/comment/suggestion, Spreadsheet cell, Presentation scene-element, PDF
+annotation/form-value, and PDF redaction/page-operation review mutation surfaces
+are implemented; the remaining format mutations and native presence projection
+are pending.
 
 - Yrs `0.27.3` now uses 53-bit Yjs-compatible client IDs and exchanges standard
   Yjs v1 updates, state vectors, and y-sync `SyncStep1`/`Update` messages with
@@ -444,25 +448,28 @@ and native presence projection are pending.
 - Host-authenticated Document `suggest` transport updates are semantically
   checked in Yrs before commit: only attributed insertion/deletion/replacement
   proposals owned by the authenticated actor may be added or withdrawn, while
-  canonical state and every non-suggestion root remain protected. This is a
-  transport authorization path, not a `NativeOfficeCollaborationMutation`;
-  `collab mutate`, `office_collaboration_mutate`, and projection v2 do not yet
-  expose native typed suggestion creation or final-decision operations.
+  canonical state and every non-suggestion root remain protected.
+  `document-suggestion-create` exposes the same closed proposal contract to an
+  actor-scoped native `suggest` replica; `document-suggestion-decide` lets an
+  `edit` replica match and accept or reject one or more complete projected
+  identities atomically, then appends immutable browser-compatible decisions.
 - Rust `project`, `collab read`, and `office_collaboration_read` interpret the
   Office-owned browser schema inside Office rather than in a product host.
   Markdown returns its exact canonical source. Document returns bounded
   traversal-order paragraph records, stable `paragraphId`/`textId` pairs,
-  structural ancestry, option fields, subordinate plain text, and projection-v2
-  comment/reply/anchor/detached records together with the exact state vector.
+  structural ancestry, option fields, subordinate plain text, and projection-v3
+  comment/reply/anchor/detached records, live suggestions with exact placements,
+  and immutable final decisions together with the exact state vector.
   `document-replace-paragraph` uses those stable
   identities plus complete expected text to reject a stale same-paragraph
   browser/agent edit before writing, while unrelated changes can proceed
   without replacing the full document.
 - Spreadsheet cell mutations create or recursively patch one zero-based
   coordinate after matching the caller's observed cell, or delete it only after
-  an exact complete-cell match. They preserve the browser's field-addressed
-  representation, dense/sparse projection mode, and atomic fail-closed
-  semantics without replacing a worksheet or workbook.
+  an exact complete-cell match. `spreadsheet-batch-cells` applies 1 to 4,096
+  distinct changes from one sheet snapshot in one transaction. They preserve
+  the browser's field-addressed representation, dense/sparse projection mode,
+  and atomic fail-closed semantics without replacing a worksheet or workbook.
 - Presentation scene-element mutations create, update, move, or tombstone one
   stable object inside a slide, master, or layout. Canonical creation claims
   prevent conflicting same-ID reuse, optimistic top-level field guards merge
@@ -509,9 +516,8 @@ Remaining:
 
 - Extend typed format-model mutations to Spreadsheet and remaining Presentation
   structural/rich-text operations plus PDF signatures; deepen Document
-  mutations to additional nested structures and add typed suggestion creation,
-  suggestion projection, and tracked final-decision operations for native
-  clients.
+  mutations to additional nested structures and complete table/list/section
+  revision workflows.
 - Project editor-visible presence and selection state while keeping Awareness
   ephemeral and outside native replica persistence.
 

package/README.md

@@ -144,11 +144,11 @@ The images below are committed visual-regression baselines from the real
 - **Automation outside the browser** — The native Rust CLI, standard MCP
   server, and Office Skill share bounded mutation contracts. Coding agents can
   also keep a durable Yrs replica, exchange standard Yjs v1 updates and state
-  vectors, perform authorized typed Markdown, Document, Spreadsheet cell,
+  vectors, perform authorized typed Markdown, Document, Spreadsheet cell/batch,
   Presentation scene-element and z-order, and PDF annotation, form-value, and
-  review changes, including attributable Document selection comments and
-  replies, retain browser/native actor attribution, and checkpoint without
-  replacing a whole Office file.
+  review changes, including attributable Document selection comments, replies,
+  text suggestions, and atomic final decisions, retain browser/native actor
+  attribution, and checkpoint without replacing a whole Office file.
 
 ## Real-time collaboration
 
@@ -1075,6 +1075,33 @@ cargo run -p a3s-office-cli -- collab mutate .a3s/report-review.replica \
   --operation-id comment-45 \
   --mutation '{"type":"document-comment-create","commentId":"comment-1","paragraphId":"00000001","expectedTextId":"00000002","startUtf16":6,"endUtf16":12,"expectedText":"review","author":"Ada Reviewer","createdAt":"2026-08-17T00:00:00.000Z","text":"Clarify this review point."}' --json
 
+# Propose an atomic replacement from an actor-scoped suggest replica. Read
+# projection v3 immediately before writing and copy its exact paragraph/text
+# identity, UTF-16 selection, and selected text.
+cargo run -p a3s-office-cli -- collab join .a3s/report-suggest.replica \
+  --artifact-id report --kind document --actor-id agent-7 \
+  --actor-kind agent --mode suggest --operation-id suggestion-join-1 \
+  --input browser.update --json
+cargo run -p a3s-office-cli -- collab read .a3s/report-suggest.replica --json
+cargo run -p a3s-office-cli -- collab mutate .a3s/report-suggest.replica \
+  --artifact-id report --kind document --actor-id agent-7 --mode suggest \
+  --operation-id suggestion-create-1 \
+  --mutation '{"type":"document-suggestion-create","paragraphId":"00000001","expectedTextId":"00000002","startUtf16":6,"endUtf16":8,"expectedText":"😀","replacement":"reviewed","insertionId":"agent-7-insertion-1","deletionId":"agent-7-deletion-1","author":"A3S Agent","createdAt":"2026-08-17T11:00:00.000Z"}' --json
+cargo run -p a3s-office-cli -- collab diff .a3s/report-suggest.replica \
+  --output agent-suggestion.update --json
+
+# An edit replica accepts or rejects one or more complete projected suggestion
+# identities atomically and appends immutable actor-attributed decisions.
+cargo run -p a3s-office-cli -- collab join .a3s/report-editor.replica \
+  --artifact-id report --kind document --actor-id editor-1 \
+  --actor-kind human --mode edit --operation-id editor-join-1 \
+  --input agent-suggestion.update --json
+cargo run -p a3s-office-cli -- collab read .a3s/report-editor.replica --json
+cargo run -p a3s-office-cli -- collab mutate .a3s/report-editor.replica \
+  --artifact-id report --kind document --actor-id editor-1 --mode edit \
+  --operation-id suggestion-accept-1 \
+  --mutation '{"type":"document-suggestion-decide","suggestions":[{"id":"agent-7-deletion-1","kind":"deletion","expectedActorId":"agent-7","expectedAuthor":"A3S Agent","expectedCreatedAt":"2026-08-17T11:00:00.000Z","expectedText":"😀"},{"id":"agent-7-insertion-1","kind":"insertion","expectedActorId":"agent-7","expectedAuthor":"A3S Agent","expectedCreatedAt":"2026-08-17T11:00:00.000Z","expectedText":"reviewed"}],"decision":"accept","decidedBy":"Grace Editor","decidedAt":"2026-08-17T11:01:00.000Z"}' --json
+
 # Recursively patch one Spreadsheet cell after matching the observed value.
 # Zero-based row/column coordinates follow the browser collaboration model.
 cargo run -p a3s-office-cli -- collab mutate .a3s/plan.replica \
@@ -1082,6 +1109,13 @@ cargo run -p a3s-office-cli -- collab mutate .a3s/plan.replica \
   --operation-id edit-45 \
   --mutation '{"type":"spreadsheet-set-cell","sheetId":"sheet-data","row":1,"column":0,"expectedCell":{"v":10,"m":"10"},"nextCell":{"v":12,"m":"12","f":"=6*2"}}' --json
 
+# Apply one bounded Spreadsheet gesture atomically. Coordinates must be unique;
+# nextCell:null is an exact guarded delete.
+cargo run -p a3s-office-cli -- collab mutate .a3s/plan.replica \
+  --artifact-id plan --kind spreadsheet --actor-id agent-7 --mode edit \
+  --operation-id paste-46 \
+  --mutation '{"type":"spreadsheet-batch-cells","sheetId":"sheet-data","changes":[{"row":1,"column":0,"expectedCell":{"v":12,"m":"12","f":"=6*2"},"nextCell":{"v":14,"m":"14","f":"=7*2"}},{"row":1,"column":1,"expectedCell":null,"nextCell":{"v":20,"m":"20"}},{"row":2,"column":0,"expectedCell":{"v":"obsolete","m":"obsolete"},"nextCell":null}]}' --json
+
 # Update one Presentation scene element after matching the complete observed
 # record. Create/delete use presentation-create/delete-element.
 cargo run -p a3s-office-cli -- collab mutate .a3s/deck.replica \
@@ -1148,8 +1182,9 @@ suppression, without opening its own network provider. Native Rust `project`,
 Markdown source or an Office-owned bounded Document projection with stable
 paragraph/text identities, structural ancestry, option fields, subordinate
 plain text, durable comments, replies, resolution and detached state, exact
-paragraph-local UTF-16 anchors, and the current state vector. Projection schema
-version 2 is the contract for these review fields. Product hosts therefore do
+paragraph-local UTF-16 anchors, live suggestions with exact placements,
+immutable final decisions, and the current state vector. Projection schema
+version 3 is the contract for these review fields. Product hosts therefore do
 not need to interpret Office's private Yjs schema. Typed Markdown
 replace/splice operations use browser UTF-16 offsets. Document mutations edit
 ProseMirror `Y.XmlText` in place, rotate the affected Word `textId`, replace one
@@ -1169,7 +1204,11 @@ write only changed leaves, so unrelated concurrent value, formula, style,
 hyperlink, note, and metadata edits merge. Use `expectedCell: null` only when
 creating an observed blank coordinate. Spreadsheet deletion requires the exact
 complete current cell, dense projections keep their dimensions, and sparse or
-empty sheets remain sparse. Presentation creation writes one complete element
+empty sheets remain sparse. `spreadsheet-batch-cells` applies 1 to 4,096
+distinct coordinates in one sheet after checking every guard against the same
+snapshot, then writes fields, presence markers, and dense dimensions in one
+Yjs transaction. One conflict rejects the complete gesture without a durable
+event. Presentation creation writes one complete element
 plus a canonical immutable claim inside a slide, master, or layout and can
 place it after a stable active element. Presentation update compares complete
 expected/current/next elements and writes only changed top-level fields, so
@@ -1206,6 +1245,18 @@ the thread as a detached review record. Browser and native comment changes
 share immutable claims and remain isolated from another participant's undo
 history.
 
+Document suggestion mutations use `document-suggestion-create` in an
+actor-scoped `suggest` replica and `document-suggestion-decide` in an `edit`
+replica. Creation matches a stable plain paragraph, its current text identity,
+an exact UTF-16 range, and selected text before writing an insertion, deletion,
+or atomic replacement proposal. Decisions match every projected suggestion
+identity and text in the batch, then accept or reject all of them in one
+transaction and append immutable browser-compatible audit records. Actor IDs
+come from replica manifests; authors and decision names must match the
+authenticated display names. Stable-ID retries are idempotent, while stale
+identities, overlapping proposals, incomplete replacement IDs, forged
+attribution, or conflicting final decisions fail without a durable update.
+
 Read the [native engine design](docs/latest/en/native-office-engine.md), the
 complete [CLI reference](docs/latest/en/cli-reference.md), or the published
 [CLI and Skill guide](https://a3s-lab.github.io/Office/docs/automation/).
@@ -1269,6 +1320,8 @@ without hard-coded return URLs.
 
 - [Live Playground](https://a3s-lab.github.io/Office/)
 - [Documentation center](https://a3s-lab.github.io/Office/docs/)
+- [A3S Office 0.9.0 documentation](https://a3s-lab.github.io/Office/docs/0.9.0/)
+- [A3S Office 0.8.1 documentation](https://a3s-lab.github.io/Office/docs/0.8.1/)
 - [A3S Office 0.8.0 documentation](https://a3s-lab.github.io/Office/docs/0.8.0/)
 - [A3S Office 0.7.3 documentation](https://a3s-lab.github.io/Office/docs/0.7.3/)
 - [A3S Office 0.7.2 documentation](https://a3s-lab.github.io/Office/docs/0.7.2/)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a3s-lab/office",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Open-source collaborative browser editors for documents, Markdown, spreadsheets, presentations, and PDFs.",
   "keywords": [
     "office",