grist-widget-sdk 0.2.0 → 0.2.2-rc.0

package/CHANGELOG.md

@@ -1,730 +1,23 @@
-# Changelog
+# grist-widget-sdk
 
-All notable changes to `grist-widget-sdk` are recorded here. In-flight work is
-tracked on [`/TASKS.md`](./TASKS.md) and [`/ROADMAP.md`](./ROADMAP.md); landed
-changes accumulate under **Unreleased** until a version is cut.
+## 0.2.1
 
-This project follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
-and [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+### Patch Changes
 
-## Unreleased — 0.2.0 (API surface alignment)
+- 3c0315f: Relicense to MIT and ship the `LICENSE` in the published tarball. No runtime or
+  API changes — `dist` is identical to 0.2.0; this release corrects the package
+  license metadata (0.2.0 shipped as ISC) and lands the release tooling (OIDC
+  Trusted Publishing + external-install smoke test).
 
-### Changed
+This file is generated by [Changesets](https://github.com/changesets/changesets)
+and is the canonical changelog for the published `grist-widget-sdk` npm
+package, starting at `0.2.1`. Every entry corresponds to a version actually
+published to npm.
 
-- **Unified, release-driven widget deploys.** The seven copy-pasted
-  `deploy-<widget>.yml` workflows are replaced by one
-  `.github/workflows/deploy-widgets.yml` + `scripts/deploy/publish.mjs`
-  (node builtins only). Two channels: push to `main` publishes **immutable**
-  `/<repo>/<widget>/v<version>/` + a mutable `/<widget>/latest/` alias, and
-  regenerates a root `manifest.json` (Grist widget-repository format, usable via
-  `GRIST_WIDGET_LIST_URL`); a widget is (re)built only when its `package.json`
-  `version` has no `v<version>/` dir yet, so bumping the version *is* the release
-  and a `packages/core`-only push no longer moves shipped widget URLs. Concurrent
-  runs are serialized and the publisher rebases-and-retries its push; one failing
-  widget build no longer blocks the others. Widgets carry a `grist` metadata
-  block (`name`, `widgetId`, `accessLevel`, …) consumed by the manifest;
-  `v0-minimal-demo` is intentionally unlisted. The former single mutable
-  `/<widget>/` URL is kept but deprecated in favor of pinned `v<version>/` /
-  `latest/`.
+For the fuller project history — widgets, docs, tooling, process — see the
+monorepo root [`/CHANGELOG.md`](https://github.com/ArthurBlanchon/grist-widget-sdk/blob/main/CHANGELOG.md).
 
-### Added
+## 0.2.0
 
-- **Dev deploy channel + in-Grist self-reload.** Pushing a `dev/<widget>` branch
-  publishes to `/<repo>/<widget>/dev/` with a `version.json` and a **dev-only**
-  self-reload snippet that polls for new builds and hot-swaps the widget inside
-  an open Grist document (cache-busting `__dev=<sha>` navigation that preserves
-  the host's query params). Prod builds are unchanged. Enables a push → CI →
-  review-in-real-Grist loop without a tunnel.
-
-### Fixed
-
-- **Gantt widget dates** — Grist Date cells (UTC midnight) are normalized to local
-  calendar days before timeline layout, so bars align with table dates in all timezones.
-- **Gantt weekly timeline positioning** — event bars and the Today marker now walk
-  the same week columns as the header (weeks that straddle two months are no longer
-  skipped in offset math), fixing ~3-month placement drift on the weekly scale.
-- **Gantt weekly headers** — columns show ISO week numbers (Monday-based, e.g. W26)
-  with the week start date below.
-- **Upload CORS error message** — includes the widget `location.origin` and notes that
-  changing deploy URL (e.g. ngrok → GitHub Pages) requires updating server CORS.
-
-### Added
-
-- **`uploadGristAttachment` / `w.uploadAttachment`** — canonical widget upload
-  (`POST /attachments`, `X-Requested-With`, `?auth=`) returning `{ ids, firstId }`.
-- **`parseGristAttachmentUploadResponseIds`**, **`gristAttachmentCellValues`**,
-  **`mergeGristAttachmentCellValue`** — full id list parsing and Attachments cell
-  encode/merge helpers aligned with Grist’s `["L", …]` wire format.
-
-### Fixed
-
-- **`fetchWithAuth` CORS on attachment upload** — non-GET REST calls from custom
-  widgets now attach the access token as `?auth=` (same as downloads) instead of
-  `Authorization: Bearer`, which many Grist hosts block in CORS preflight.
-- **`parseGristAttachmentUploadResponse` / `gristAttachmentCellValue`** — helpers
-  for `POST /attachments` (response is a JSON array of ids, e.g. `[42]`) and
-  writing a single id into an Attachments column as `["L", id]`.
-- **`mapBack` erased unrelated columns on partial updates** —
-  `grist-plugin-api.js`'s `mapColumnNamesBack` applies transformations for
-  *all* mapped columns, injecting `undefined` for fields absent from the
-  patch. Those `undefined` values JSON-serialise to `null` over RPC,
-  causing Grist to erase the corresponding cells. `mapBack` now strips
-  all `undefined` entries from the result so only fields explicitly
-  included in the patch are sent in the update.
-- **Access-insufficient alerts for all SDK hooks** — `useGristSchema`,
-  `useGristRowsFromTable`, and `useGristAttachmentsRest` now surface
-  access-insufficient errors through the provider's `readError` so the SDK alert
-  system displays a smooth "Access level" alert instead of failing silently.
-  `useGristSchema` and `useGristRowsFromTable` delegate to the provider's guarded
-  read methods when inside a `GristWidgetProvider`; `useGristAttachmentsRest` uses
-  its own `guardedRpc` wrapper whose `readError` is merged into `UseGristResult`.
-- **Heartbeat false-positive on semantic errors** — `applyActions` failures (e.g.
-  "No such column") no longer briefly flash the connection-degraded indicator.
-  RPC failures are no longer coalesced into the heartbeat; the regular probe
-  detects real transport issues on its own schedule.
-- **`fetchTable` / `fetchTableRows` / `fetchRow` / `listColumns` / `buildReplicaDocumentFromDocApi`
-  access guard** — these methods now check the granted access level before making
-  an RPC call. When the widget only has `"read table"` access, the SDK throws
-  immediately with a descriptive message and sets `readError`, preventing a
-  looping RPC failure cycle. The `access-insufficient` SDK alert is emitted
-  automatically so the `<GristSdkAlerts>` / `useGristSdkAlertDescriptors` shell
-  shows actionable instructions.
-- **`@access` annotations** — corrected `fetchTable`, `fetchTableRows`, `fetchRow`,
-  `listColumns`, and `buildReplicaDocumentFromDocApi` from `@access "read table"`
-  to `@access "full"` in `UseGristResult` JSDoc.
-
-### Added
-
-- **`gristAddVisibleColumnAction(tableId, colId, colInfo)`** — new action builder
-  that emits `["AddVisibleColumn", ...]`. Unlike `gristAddColumnAction`, it also
-  adds the column to the current view section so it is immediately visible.
-- **`w.listColumns(tableId, options?)`** — new lightweight API to retrieve
-  column metadata (id, label, type, formula, description) for a given table
-  without fetching all row data. Noise columns (`id`, `manualSort`,
-  `gristHelper_*`, logging formulas) are filtered out by default.
-- **`w.listTables(options?)` — system-table filtering** — `listTables()` now
-  accepts `{ includeSystem?: boolean }` and filters system/hidden tables
-  (`_grist*`, `GristHidden_*`) by default.
-- **`useGristWidgetOptionsFromContext<T>()`** — typed widget options hook
-  designed for use inside `<GristWidgetProvider>`. Provides `options`,
-  `loading`, `setOptions`, `patchOptions`, and `reset` with debounced writes
-  and a `namespace` option. Unlike `useGristWidgetOptions()` (advanced), this
-  hook does not call `grist.ready()` and is fully compatible with the provider.
-- **`UseGristResult` JSDoc** — documents that all function-typed fields are
-  referentially stable (`useCallback`-wrapped) and safe in `useEffect` deps,
-  while the container object itself is not.
-- **`UseGristResult` access-level annotations** — every field now carries an
-  `@access` JSDoc tag (`"none"`, `"read table"`, or `"full"`) so editors and
-  documentation show the minimum `requiredAccess` at a glance. Fields are
-  grouped by access tier in the type definition and in the API reference.
-- **`suppressAlerts` on `UseGristOptions`** — widgets that intentionally
-  operate without a link source can now declare
-  `suppressAlerts: ["section-not-linked"]` in their `GRIST_OPTIONS`. The alert
-  system (`useGristSdkAlertDescriptors`) reads it automatically from the widget
-  slice — no extra wiring needed. A lower-level `suppressKinds` option on
-  `GetGristSdkAlertDescriptorsOptions` is also available as an override.
-- **`source-not-wired` SDK alert** — when a widget declares
-  `allowSelectBy: true` but no other section is linked to read from it, a
-  distinct `source-not-wired` alert is emitted instead of `section-not-linked`.
-  This clearly distinguishes "widget expects an incoming link" from "widget is
-  a selector but nothing listens yet".
-- **`access-insufficient` SDK alert** — when a write or REST call fails because
-  of insufficient access (`"Access not granted"`, etc.), the alert system now
-  emits a dedicated `access-insufficient` alert with actionable copy instead
-  of the generic `action-error`. Hosts render it as an error-severity callout.
-- **API reference grouped by access tier** — the `useGrist` API reference page
-  organizes fields under `"none"`, `"read table"`, and `"full"` headings so
-  developers can quickly see which features require which access level.
-- **create-email-draft widget: diffusion lists** — users can configure a
-  "diffusion list" table via the widget's _Open configuration_ panel (select
-  table, display-name column, and emails column). Typing `/` in the Bcc field
-  opens a picker to insert all emails from a diffusion list at once. Config
-  panel now uses `listColumns()` for lightweight column discovery.
-
-### Changed
-
-- **Monorepo tooling** — upgrade to pnpm 11 (`packageManager` pin), root
-  `engines` (Node 22+, pnpm 11+), and `pnpm-workspace.yaml` settings
-  (`engineStrict`, `minimumReleaseAge` 7 days, `allowBuilds`). README
-  documents `corepack enable`.
-
-### Added
-
-- **`<GristBoundary>` shell UX** — blocking states (booting, unavailable, error, preparing)
-  use centered layout via `GristBoundaryScreen` with neutral typography, visible card borders,
-  and shell background (`#f8f8f8` fallback). Access-denied copy is short and points to Custom
-  widget settings. Widget HTML templates include inline background styles to reduce the initial
-  white flash before the bundle loads. Helpers `formatBoundaryUserMessage`, `GRIST_BOUNDARY_PREPARING_COPY`.
-
-- **Host access level enforcement** — `interaction.access_level` from `grist.onOptions` is
-  applied to the handshake `authz` axis (`AUTHZ_REPORT`). When Grist grants less than
-  `requiredAccess` (e.g. widget requests `read table` but the document is set to no access),
-  `useGrist().status` becomes `error` and `<GristBoundary>` shows the error fallback instead
-  of widget content. After **Try reconnecting** / `reload()`, the cached `onOptions`
-  level is re-checked when the handshake goes online so insufficient access stays blocked
-  even when Grist does not send a fresh `onOptions` event.
-
-- **`section-not-linked` SDK alert** — `getGristSdkAlertDescriptors` emits a warning when
-  Grist reports `widgetInteraction.linking.asTarget === null` (including when a stale row
-  is still shown). `onOptions` settings are normalized (`accessLevel` → `access_level`,
-  `linking` parsed) before they reach `w.widgetInteraction`.
-  (section not driven by a linked table/selector). Helpers `isWidgetSectionNotLinked`,
-  `formatSectionNotLinkedAlertMessage`; type `GristWidgetLinkingInfo`. Older hosts without
-  `linking` on `onOptions` are unchanged (no false positive).
-
-- **`grist-widget-sdk/advanced` build export** — `advanced` entry in `tsup` and `package.json` `exports` so documented advanced hooks resolve from npm.
-- **`useGrist().capabilities`** — projects handshake `GristCapabilities` (`canRender`, `canWriteRecords`, `missingMappings`, …) on the primary hook; type `GristCapabilities` exported from the main entry.
-- **Guide: [Raw plugin API vs SDK](/guide/raw-plugin-api-vs-sdk)** — comparison table and migration snippets vs calling `grist` directly.
-- **Docs home** — eight VitePress feature cards (four « One … » product links + four guide links); original hero tagline.
-- **Vite template DX** — ESLint `no-restricted-globals` for `grist`, `grist-types.example.ts`, `GristBoundary gate="canRender"` when `columns` are set (no bundled tests — see `/guide/testing`).
-
-- **Handshake-aware boundary + alert helpers** — `task-070`.
-  `deriveBoundaryView`, `deriveBoundaryBootLabel`, extended
-  `getGristSdkAlertDescriptors` (mapping-pending, mapping-unreported,
-  link-stale, current-table-error; `title` / `severity` on descriptors),
-  `useGristSdkAlertDescriptors`, and `<GristBoundary gate="canRender">` with
-  phase-aware boot labels when the manager is mounted.
-- **`useGristHandshake()` / `useGristCapabilities()` hooks** — `task-062`.
-  Exported from `grist-widget-sdk/advanced`. Returns the full
-  `GristWidgetSnapshot` (lifecycle / link / authz / config / sync), derived
-  `status`, error message, and pre-computed `GristCapabilities` (`canRead`,
-  `canRender`, `canWriteRecords`, `canWriteSchema`, `canFetchTable`,
-  `hasFreshSelection`, …). Includes `reload()` and `restart()` controls.
-  Independent of the existing `useGrist*` hooks — no breaking change to the
-  current API surface.
-- **`<GristHandshakeProvider>` + `useGristHandshakeContext()` /
-  `useGristHandshakeContextOptional()`** — `task-064`. Opt-in React provider
-  that mounts a single `GristHandshakeManager` per app tree and broadcasts
-  its snapshot to all descendants. Coexists with the legacy
-  `<GristWidgetProvider>` without interference (ready calls are deduped at
-  the singleton level).
-- **Public snapshot types** — `GristWidgetSnapshot`, `GristCapabilities`,
-  `GristLifecycle*`, `GristLink*`, `GristAuthz`, `GristConfig`, `GristSync`,
-  `GristMapping*`, `GristStreamFreshness`, `GristCurrentTableState`,
-  `GristGeneration`, `GristTerminationReason` re-exported from `/advanced`.
-
-### Fixed
-
-- **`mapBack` injected spurious `id` field** — `grist-plugin-api.js`'s
-  `mapColumnNamesBack` unconditionally copies `from.id → to.id` (a side-effect
-  of sharing code with forward mapping). When the input patch has no `id` key,
-  the result contained `id: undefined`, causing Grist to reject writes with
-  "Invalid column 'id'". The SDK now strips the injected `id` key.
-
-- **Playground theme-demo stuck on `"light"`** — `useGristTheme` listens on
-  `grist.on("message")` only (production `grist-plugin-api.js`). Emulator transports
-  post the same `msg.theme` object shape (`appearance`, `name`, `colors`); removed
-  emulator-only `themeInitialChange` / `themeChange`. Playground shell theme (**d**) is
-  mirrored via `emulator.theme.set`.
-
-- **`useGrist()` cursor updates in production Grist** — merged widget state is
-  rebuilt from live slice contexts (`useGristFromProvider`) instead of a
-  memoized `GristContext` snapshot that could keep `w.record.id` on the first
-  row after `onRecord` fired again. `recordEvent` also listens for host
-  `message` events with a new numeric `rowId` and refetches via
-  `fetchSelectedRecord` (same path as `grist-plugin-api.js` `onRecord`).
-- **Playground iframe: row stuck on first selection** — iframe transport now
-  sends `dataChange: true` on `cursor-change` (same contract as inline
-  `pushRecord`), so `grist-plugin-api.js` refetches the record when the
-  inspector changes the cursor. Cursor-only messages left `w.record.id`
-  frozen on the initial row.
-- **Selected row missing after handshake** — `useGristSelection` now binds
-  `grist.onRecord` / `onRecords` on mount instead of waiting for `docApi`
-  (`lifecycle.phase === "online"`). The host can push the initial cursor
-  record during `grist.ready` before `docApi` exists; late binding left
-  `w.record` / `w.mode` stuck at `null` / `"empty"`. A follow-up mount effect
-  that cleared stream state whenever `docApi` was falsy ran after the
-  `recordEvent` replay and wiped the first row; clearing now happens only after
-  a real disconnect, and cached payloads are re-applied when `docApi` turns
-  ready. The handshake manager also wires stream subscriptions when
-  negotiation starts. Regression tests in
-  `tests/sdk/selection-initial-record.test.tsx`.
-- **Selection stuck on the first row** — `useGristSelection` now shallow-copies
-  `onRecord` / `onRecords` payloads. Grist can reuse one record object and
-  mutate fields in place; React skipped re-renders when the reference was
-  unchanged, so `w.record` looked frozen (e.g. always `{ "id": 1 }`).
-
-### Changed
-
-- **Widget Pages deploy concurrency** — GitHub Actions deploy workflows use
-  `queue: max` on the shared `pages-gh-pages` group so multiple widget deploys
-  triggered by one push (e.g. `packages/core` changes) queue instead of canceling
-  each other while waiting.
-
-- **SDK alerts use classic `severity` only** — `info` / `warning` / `error` on
-  each descriptor; host shells style from `severity` (template `GristSdkAlerts`
-  maps warning → amber, info → muted, error → destructive).
-- **Full SOTA handshake — no legacy connectivity path** — all SDK hooks now
-  route through `GristHandshakeManager` only. Removed
-  `useGristCoreFromLegacy`, the inline `mergeGristStatus()` ladder in the
-  compose path, and the parallel mapping bootstrap in
-  `useGristSelection` (mappings + `columnMappingStatus` now project from
-  `snapshot.config.mappings` via `deriveColumnMappingStatus` /
-  `extractResolvedMappings`). Standalone `useGrist()` / mid-level hooks
-  without `<GristWidgetProvider>` share a ref-counted page-level embedded
-  manager (`acquireEmbeddedHandshakeManager`). `useGristReady` and
-  `useGristAvailability` are thin wrappers over `useGristCore` (FSM-backed).
-  `useGristCurrentTable` feeds `CURRENT_TABLE_*` actions into the reducer and
-  reads `currentTableId` / loading / errors from `snapshot.sync.currentTable`.
-  Mid-level `useGristTableOps` / `useGristRowsFromTable` participate in
-  heartbeat coalescence via `useRpcHeartbeatCoalesce`. Deleted
-  `tests/unit/handshake-legacy-equivalence.test.ts` (obsolete).
-- **Heartbeat auto-coalescence across the slice hooks** — `task-066`.
-  Every successful Grist RPC issued through the SDK's slice hooks
-  (`useGristWrites().applyActions` / `.table.*` / `.getTable(…)`,
-  `useGrist().fetchTable` / `.fetchTableRows` / `.fetchRow` /
-  `.listTables` / `.getDocName` / `.fetchSelectedTable` /
-  `.fetchSelectedRecord` / `.buildReplicaDocumentFromDocApi`,
-  `useGrist().getAttachmentUrl` / `.fetchAttachmentBase64` /
-  `.fetchAttachmentBlob` / `.getAccessToken` / `.fetchWithAuth`,
-  `useGrist().getWidgetOptions` / `.getWidgetOption` / `.setWidgetOption` /
-  `.setWidgetOptions` / `.patchWidgetOptions` / `.clearWidgetOptions`,
-  `useGrist().setCursorPosition` / `.setLinkedRowSelection`,
-  `useGristSectionApi().configure` / `.refreshMappings`,
-  `useGrist().refreshCurrentTable`, and `useGristActions().apply` and
-  derivatives) is now reported to the handshake manager via a single
-  internal `useRpcHeartbeatCoalesce()` helper. The heartbeat treats each
-  success as a free `HEARTBEAT_OK` and skips the next scheduled probe;
-  failures shorten the next probe to ≤ 1 s for fast re-confirmation.
-  Chatty widgets cost zero extra round-trips; quiet widgets keep their
-  baseline 30 s health check. Outside `<GristWidgetProvider>` /
-  `<GristHandshakeProvider>` the helper is a zero-cost passthrough.
-  - The legacy `<GristWidgetProvider>` was restructured into a two-layer
-    component so the internal manager context is mounted *before* the
-    slice composer runs (`GristWidgetContextTree` under the manager). Without this,
-    `useRpcHeartbeatCoalesce()` resolved to `null` inside the slice hooks and
-    coalescence silently no-op'd — `tests/sdk/handshake-rpc-coalesce.test.tsx`
-    pins the contract.
-  - Defensive `typeof grist === "undefined"` guards added to
-    `useGristCurrentTable` and `useGristSelection` so late passive
-    effects firing after a test's `emulator.dispose()` no longer surface
-    `ReferenceError: grist is not defined`. Pre-existing flake, surfaced
-    by the new test layout, now 0/10 in the stability loop.
-- **`<GristWidgetProvider>` now mounts the handshake manager internally** —
-  `task-065`. The legacy provider creates a single `GristHandshakeManager` per
-  instance and exposes it through a private context. `useGristCore` reads from
-  that manager (via `useSyncExternalStore`) and projects the FSM snapshot into
-  the same `{ status, isAvailable, isReady, error, docApi, reload }` shape the
-  slice composer expects, so every existing slice hook
-  (`useGristSelection`, `useGristReads`, `useGristWrites`, …) transparently
-  benefits from the FSM-driven timing without any API change. Outside the
-  provider, `useGristCore` falls back to the pre-FSM
-  `useGristAvailability` + `useGristReady` chain so standalone escape hatches
-  keep working byte-for-byte.
-  - The manager's negotiate effect routes through the existing
-    `ensureGristReady()` singleton (so any stray `useGristReady()` user
-    coalesces with the manager's ready call), and the provider passes
-    `onBeforeReload: resetGristReadySingleton()` so a user-triggered
-    `reload()` actually re-issues `grist.ready` instead of replaying the
-    cached promise.
-  - Heartbeat is on by default for the provider (same defaults as
-    `<GristHandshakeProvider>`); pass nothing to keep it, or thread
-    `options.heartbeat = false` through the manager if a widget needs to opt out.
-  - Migration is transparent — no widget code change required. Two pre-existing
-    flaky integration tests (`tests/sdk/sdk-react.test.tsx` and
-    `tests/sdk/column-mapping-pending.test.tsx`) were tightened from a
-    "snapshot once" assertion to a single `waitFor` block on the fully-settled
-    state, because `pendingColumnMappingStatus.ok` is `true` (no `missing`
-    columns reported yet) and the legacy assertion was racing against the
-    transient pending-but-ok window.
-
-### Internal
-
-- **Handshake state machine (foundation)** — `task-060`. New
-  `packages/core/src/sdk/internal/handshake/` module models the widget ↔ Grist
-  relationship as five orthogonal axes (`LIFECYCLE`, `LINK`, `AUTHZ`, `CONFIG`,
-  `SYNC`) feeding a pure reducer + status projection + capability derivation.
-- **Handshake effects layer** — `task-061`. `internal/handshake/effects/`
-  wires the pure machine to a real (or stubbed) runtime:
-  - `detect.ts` — exponential-backoff polling for `window.grist`, adaptive
-    budget driven by `navigator.connection.effectiveType` (30 s on 4g, 60 s
-    on 3g, 120 s on 2g/slow-2g).
-  - `negotiate.ts` — issues `grist.ready` with a 30 s timeout and an external
-    `AbortSignal`; bridges promise/sync ready impls.
-  - `subscriptions.ts` — pluggable binder; default wires SDK singletons,
-    `noopSubscriptionsBinder` available for tests.
-  - `mappings.ts` — declare + `sectionApi.mappings()` fetch + stream-payload
-    ingestion + 5 s `MAPPING_TIMEOUT` fallback to `unreported`.
-  - `manager.ts` — `GristHandshakeManager` owns the snapshot, runs effects in
-    response to lifecycle transitions, bumps generation on `reload()`,
-    cancels through a per-generation `AbortController`. Implements the
-    `subscribe` / `getSnapshot` interface React's `useSyncExternalStore`
-    requires. Exposes `recordRpcSuccess()` / `recordRpcFailure()` for
-    external coalescing with the heartbeat.
-- **Heartbeat effect** — `task-063`. `internal/handshake/effects/heartbeat.ts`:
-  - Interval probe (default 30 s) calls `grist.docApi.getDocName()` (or any
-    custom `probe`); per-probe timeout default 10 s.
-  - `recordRpcSuccess()` coalesces with natural RPC traffic and pushes the
-    next probe out by a full interval — we don't burn requests.
-  - `recordRpcFailure()` immediately degrades the link signal and shortens
-    the next probe to ≤ 1 s for fast re-confirmation.
-  - Pauses on `visibilitychange:hidden` and resumes (with an immediate probe)
-    on `visible`. Listens to `online` events for instant network-recovery
-    re-probe.
-  - Reducer transitions: `connected → stale` after `staleAfterMissed`
-    misses, `→ lost` after `lostAfterMissed`. `lost` escalates to global
-    `"error"` status via `deriveStatus`.
-- **Environment abstraction** — `internal/handshake/environment.ts` exposes a
-  `GristEnvironment` interface (`now`, `setTimeout`, `probeGrist`,
-  `effectiveTypeHint`, …) so effects are unit-testable with a virtual clock
-  via `createTestEnvironment`. Production code uses `createBrowserEnvironment`.
-- **Mapping resolver** — `MappingResolver` merges column mappings from
-  `section_api` / `stream_record` / `stream_records` / `stream_new_record`
-  with a fixed priority order, making the final resolution a pure function of
-  the set of received payloads. Payloads stamped with a stale generation are
-  dropped silently.
-
-### Tests
-
-- **Handshake reducer + resolver** — 50 new unit tests covering: 24-permutation
-  resolver determinism, generation-stamped action drop, reducer idempotence
-  for duplicate stream payloads, link transitions `connected → stale → lost`,
-  mapping invalidation/recovery, current-table local-error containment, and
-  capability gates (`canRender` / `canWriteRecords` / `canWriteSchema` /
-  `hasFreshSelection`).
-- **Manager lifecycle** — 14 unit tests with virtual time: detect budget
-  exhaustion, NOT_EMBEDDED detection, negotiate success/failure/timeout,
-  `reload()` generation bump + lifecycle reset, stale-generation drop,
-  capability transitions through online + mapping completion, no error
-  escalation on incomplete mappings, and `subscribe` / `getSnapshot`
-  contract for `useSyncExternalStore`.
-- **`useGristHandshake()` integration** — 3 emulator-driven tests in
-  `tests/sdk/handshake-react.test.tsx` covering ready transition, mapping
-  state propagation, and stream-subscription wiring against `renderWithGrist`.
-- **Heartbeat unit tests** — 11 tests in `tests/unit/handshake-heartbeat.test.ts`:
-  interval start (no t=0 probe), probe success / reject / timeout dispatches,
-  repeated firing, RPC coalesce, visibility pause + resume, `online` event,
-  `cancel()` cleanup.
-- **Heartbeat ↔ manager integration** — 5 tests in
-  `tests/unit/handshake-manager.test.ts`: link degradation `connected → stale
-  → lost`, `recordRpcSuccess()` reset, heartbeat shutdown on `stop()`,
-  `heartbeat: false` disablement.
-- **`<GristHandshakeProvider>` integration** — 4 tests in
-  `tests/sdk/handshake-provider.test.tsx`: shared snapshot across consumers,
-  optional vs throwing context hooks.
-- **Property-based / chaos tests** — `task-067`. 12 tests in
-  `tests/unit/handshake-properties.test.ts` using `fast-check`:
-  resolver determinism (200 random runs per property), generation gate,
-  reducer idempotence, `terminated` absorption, fuzz sequences of up to 30
-  random actions (200 runs) confirming no throws, monotone generation,
-  and `link.state` stays in its closed domain. Capability gates are
-  asserted to form a conjunctive chain
-  `canWriteSchema ⇒ canWriteRecords ⇒ canRender ⇒ canRead` over 300
-  randomized snapshots.
-
-### Dev dependencies
-
-- Added `fast-check ^4.8.0` (used only by `tests/unit/handshake-properties.test.ts`).
-
-### Docs
-
-- **Handshake module documentation** — `task-068`. New API reference page
-  at `/api/handshake` covering the public hooks
-  (`useGristHandshake` / `useGristCapabilities` / `<GristHandshakeProvider>` /
-  `useGristHandshakeContext` / `useGristHandshakeContextOptional`), the full
-  snapshot shape (`GristWidgetSnapshot`, `GristLifecycle`, `GristLink`,
-  `GristAuthz`, `GristConfig`, `GristSync`), derived `GristCapabilities`,
-  heartbeat coalescence semantics, and `reload()` vs `restart()`. New
-  conceptual guide page at `/guide/handshake` covering when to use the
-  new hooks, the five-axis state machine, the capability chain, the
-  heartbeat, the mapping states, and generation discipline.
-- Updated `/api/index.md`, `/api/provider-boundary.md`, `/guide/concepts.md`,
-  and `/guide/error-handling.md` to cross-link the new module and to
-  describe the FSM-backed implementation of `<GristWidgetProvider>`.
-- VitePress navigation: handshake guide listed under "Advanced topics",
-  handshake API ref listed in the unified Reference sidebar.
-
-### Process
-
-- **Lightweight workflow.** Dropped the seven-step `/ITERATION.md` cycle;
-  planning lives in chat. Roadmap + task board + `apps/docs/work.md` replace
-  the formal spec file.
-
-### Changed
-
-- **Slice hook return stability** — slice hooks memoize their result objects so
-  React context consumers and `React.memo` children keep stable callable references
-  (`table`, `mapBack`, `reload`, …) across unrelated slice updates.
-
-### Tests
-
-- **Slice identity** — `slice-identity.test.tsx` asserts zero extra renders for
-  memoized children when selection, writes, theme, or status slices change in isolation;
-  1000-row `records` list stays stable on cursor-only changes.
-
-- **Render budget bench** — `pnpm --filter grist-widget-sdk bench` runs
-  `tests/bench/render-budget.test.tsx` and writes `packages/core/bench/results.json`
-  (full-record / slice / write / schema-fetch render deltas on `presets.todoList()`).
-
-- **`useGristSchema` snapshots** — `use-grist-schema.snapshot.test.tsx` guards
-  `blank` / `todoList` / `contacts` × `schema-only` / `schema+samples` /
-  `schema+data` replica output from the emulator.
-
-### Docs
-
-- **Render budgets** — `/guide/performance` documents measured re-renders per
-  operation from the bench harness and slice-isolation expectations.
-
-### Fixed
-
-- **`waitForEvent`** no longer resolves immediately from bus history; waits for
-  the next matching event. Kind overload (`ready`, `record`, `records`, `options`,
-  `theme`, `cursor`) and clearer timeout errors.
-- **Column mapping on load** — `columnMappingStatus.pending` stays true until Grist
-  reports mappings (`onRecord` / `onRecords` or `sectionApi.mappings()`). Widgets
-  no longer show a false "Column mapping is incomplete" alert during the brief
-  window after `status === "ready"`. `getGristSdkAlertDescriptors` ignores
-  pending mapping status.
-
-### Changed
-
-- **`columns` vs `safeParse` on reads** — `/guide/reading-data` documents the
-  contract: `columns` alone yields plain decoded rows; `safeParse` adds per-cell
-  issue tracking. Covered by unit tests in `grist-table-data.test.ts`.
-- **Retired `/design/api-surface.md`** — export list lives in
-  `public-api.test.ts` + `/api/index`; conventions in `/design/principles`.
-  `tests/docs/structure.test.ts` fails CI if the page returns.
-- **Cleared shipped items** from `/design/open-questions` → *Pending API
-  tightenings* (0.3+ work stays on the task board).
-
-### Tests
-
-- `packages/core/tests/unit/grist-table-data.test.ts` — `columns` vs `safeParse`
-  materialization shapes.
-- `packages/core/tests/docs/structure.test.ts` — docs project in Vitest;
-  `api-surface.md` must not exist.
-
-**Learnings:** The duplicate api-surface page was pure drift risk once
-`public-api.test.ts` existed; documenting `columns` without `safeParse` stops
-readers from wrapping every fetch in safe-parse cell types.
-
-### Documentation & DX
-
-- **Developer pathway is now template-first.** `/guide/getting-started`
-  opens with a two-minute `degit` TL;DR, then keeps manual install +
-  hello-world below the fold.
-- **Cheat sheet, cookbook, troubleshooting, templates, and demos.**
-  Four new guide pages under `/guide/` (cookbook = 10 end-to-end
-  recipes, cheatsheet, troubleshooting, templates) plus a
-  top-level demo catalogue at `/demos`.
-- **Three live demo widgets.** `form-edit`, `task-board`, and
-  `attachment-gallery` under `apps/playground/src/widgets/`,
-  reachable at `https://demo.grist-widgets.com/widget.html?id=<id>`
-  (raw, pasteable into a Grist Custom Widget URL) and
-  `https://demo.grist-widgets.com/?url=widget.html?id=<id>` (preview
-  in the playground shell, embedded in `/demos`).
-- **Agent guide consolidation.** `/files/*` is reduced to 9 pages
-  (`AGENT.md`, `architecture.md`, `testing-patterns.md`,
-  `replica-document.md` deleted). Architecture / replica content
-  lives canonically under `/design/`. `/files/start-here.md` becomes
-  the single dense entry: operating contract, eight-step workflow
-  summary, commands, path map, decision tree, anti-patterns,
-  hand-off checklist. Every remaining `/files/*` page carries an
-  Audience / Companion / Verified-in preamble.
-- **`llms.txt` + `llms-full.txt`** at `apps/docs/public/`. The first
-  is the standard llmstxt.org index for AI tool discovery; the
-  second concatenates every page in the slim `/files/*` set in
-  alphabetical order with `# <path>` delimiters so a single fetch
-  primes a model with the entire agent operating manual.
-- **"Choose your path" tiles** on the docs home page: four entry
-  points keyed on intent (writing a widget / AI agent / evaluator /
-  see-it-work).
-- **Code-block contract.** Every fenced `tsx` / `ts` block in
-  `/guide/getting-started`, `/guide/cookbook`,
-  `/guide/cheatsheet`, and the landing page (`/`) whose first
-  line is `// @example` is type-checked against the SDK at test
-  time. Catches API drift between docs and code automatically.
-  The contract caught five real bugs on first run
-  (gristAddTableAction arg shape, safeParseGristTableData result
-  field name, useGristSchema option name, missing presets.simple,
-  renderWithGrist option shape) — all fixed.
-- **Landing page reworked for one-look DX + agent triage.** Three
-  hero CTAs (Get started / Reference / Demos), an inline `npx
-  degit` TL;DR scaffold block, a complete fifteen-line widget
-  shown as a `// @example` `tsx` block (type-checked alongside the
-  rest of the docs), and a "Choose your path" markdown table that
-  routes by intent — writing a widget, AI coding agent (links to
-  `/files/start-here`), evaluating the SDK, or seeing it work.
-  Feature cards rewritten to name the concrete APIs each one
-  represents and link to the most relevant `/api/` page.
-- **Reference consolidation.** `Design` is no longer a top-level
-  nav entry; `Reference` collapses Design + API rationale under
-  one umbrella in nav and sidebar. URLs unchanged — `/api/*` and
-  `/design/*` still resolve where they did, and both share the
-  same sidebar grouping. `apps/docs/design/api-surface.md` is
-  retired: its conventions (naming / slot / empty-null / promise)
-  move to `/design/principles.md` as a `## Conventions` section,
-  and its "breaking changes to do" list moves to
-  `/design/open-questions.md` as `## Pending API tightenings`.
-- **Landing-page polish.** Body region order is now What it looks
-  like → Start with Vite → Choose your path → Highlights: code
-  first, scaffold second, routing third, marketing last. The
-  `npx degit` block lives under a new `## Start with Vite` heading
-  that explicitly flags more templates (Next.js, plain HTML) are
-  planned, linking to `/guide/templates` as the running roster.
-  YAML feature cards (which rendered above the wayfinder and
-  carried deep links) are replaced by a `## Highlights` markdown
-  section below the Choose-your-path table — six capability blurbs
-  with no outbound links so the table is the only navigation
-  surface on the home page.
-- **`/demos` promoted to a top-level URL.** The catalogue page
-  was previously at `/guide/demos`, miscategorising the showcase
-  as a learning step. Now lives at `/demos` with its own top-nav
-  entry, no sidebar (matches the catalogue shape). All cross-
-  links — landing page CTAs, getting-started "Next steps",
-  `llms.txt` index, demos.md internal Cookbook links — migrated
-  in the same commit so the build stays green at every HEAD.
-- **Hero image.** The home page hero now has a real screenshot
-  next to the headline: the `form-edit` demo widget rendered
-  beside the playground's emulator panel. ~39 KB PNG at
-  `apps/docs/public/hero.png`, served via VitePress's
-  `hero.image` frontmatter slot. Real product surface, zero
-  illustration work, zero external network dep on first paint.
-
-- Consolidated the docs `/work/` folder (roadmap + task board + guidelines +
-  release process) into a single iteration workflow described in
-  [`apps/docs/work.md`](/work).
-  The source of truth for in-flight scope is now `/ITERATION.md`; this
-  `CHANGELOG.md` is the source of truth for history.
-- Root `pnpm test` now runs the SDK suite **plus** the docs build
-  **plus** the playground's widget bundle. Dead links and unbound
-  widget metadata trip CI without a separate workflow change.
-- New `packages/core/tests/docs/` vitest project (node env). Four
-  files: `code-blocks.test.ts` (type-checks `// @example` blocks
-  in the three guide pages **and** the landing page),
-  `structure.test.ts` (slim /files/* set, preamble blocks, cookbook
-  recipe count, cookbook → demo cross-links, demos catalogue
-  shape, **landing-page hero / TL;DR / @example / table shape,
-  `/design/api-surface.md` retired, `/design/principles.md`
-  Conventions block, `/design/open-questions.md` Pending API
-  tightenings, body order (code-before-scaffold), uniform feature-
-  card `linkText: "Learn more →"`, hero `image.src: /hero.png`
-  with the file on disk, `/demos` top-level move**),
-  `links.test.ts` (resolves every relative link across
-  `apps/docs/**` and the three root files), `llms-txt.test.ts`
-  (asserts both `llms.txt` and `llms-full.txt`).
-
-### Learnings
-
-- The single highest-leverage change was the `// @example`
-  type-check: it caught five real API mismatches between docs and
-  code on the first run. Future iterations should keep adding the
-  sentinel to new code blocks rather than relying on review.
-- Splitting the docs site into two audiences (`/guide/` for
-  developers, `/files/` for agents) with strict no-duplication
-  rules and a slim, deterministic agent set produced a much cleaner
-  navigation than the previous mixed structure. The `/files/`
-  preamble (Audience / Companion / Verified-in) is the gate that
-  keeps the agent surface honest.
-- Embedding demos via the existing playground shell (preview URL =
-  emulated table next to the widget) is a much better
-  reading-experience than a bare widget — the reader sees both the
-  data and the widget's reaction to it. Worth keeping that pattern
-  for any future demo iteration.
-- Including agent-facing top-level files (`ITERATION.md`,
-  `CHANGELOG.md`) into VitePress pages via the `@include`
-  directive is convenient but couples two link-resolution
-  contexts: the source file (read from repo root, GitHub, IDE)
-  and the included page (read from the docs site). Relative
-  links in the source silently break in one of the two. Rule of
-  thumb: any link that lives inside the included range must use
-  an absolute URL — prefer the GitHub permalink so the source
-  file still works outside the docs build.
-- Nav consolidation under `Reference` (instead of separate `API` /
-  `Design` entries) without moving files is a strict improvement:
-  unifies the mental model for readers and AI agents, keeps every
-  external URL stable. Prefer sidebar-level grouping over directory
-  reshuffles whenever the cost is borne by future external links.
-- The opposite intuition holds when a page is genuinely
-  miscategorised: `/demos` belonged at the top level, not under
-  `/guide/`. The move broke a handful of cross-links (cookbook,
-  getting-started Next steps, `llms.txt`, demos.md's own
-  `./cookbook` references) but every break was caught at build
-  time by the dead-link detector + the existing `links.test.ts`,
-  with no manual auditing required. Lesson: trust the safety
-  net, ship the structural fix, watch the build fail loudly, fix
-  the breaks. Cheaper than living with the miscategorisation.
-- Two-pillar landing-page surface — a code block ("what does this
-  look like") plus an image ("what does a real widget look like")
-  — answers more pre-commitment questions than either alone. The
-  image being a real product screenshot (the form-edit demo +
-  emulator side by side) rather than an illustration carries
-  more weight: the reader trusts the surface they're shown is
-  the one they'll be building. Worth preserving as the SDK
-  matures — swap the asset, keep the slot.
-- When build-green-at-HEAD is a hard constraint and two changes
-  are coupled (the `/demos` URL was simultaneously consumed by
-  the landing page and produced by the moved file), the
-  three-commit plan from the spec collapsed to a two-commit
-  reality. Cleaner to acknowledge this in the commit message
-  and bundle than to leave a broken HEAD or carry a fake "the
-  page exists at the new location but no one links to it" interim
-  state.
-
-### Added
-
-- `useGristStatus()` now exposes `currentTableId`, `currentTableLoading`,
-  `refreshCurrentTable`, `tableError`, and the raw `docApi` handle. The hook
-  is a single subscription point for "status + selected table" UIs.
-- `mapBack(patch)` reports skipped logical names via `w.mapBackSkipped`
-  (and on `useGristSelection().mapBackSkipped`). A new alert descriptor
-  `kind: "map-back-skip"` surfaces them through
-  `getGristSdkAlertDescriptors(...)`.
-- `formatMapBackSkipMessage(skipped, hint?)` for hosts that build alert copy
-  themselves.
-- `presets` (`blank`, `todoList`, `contacts`) are now re-exported from
-  `grist-widget-sdk/emulator/testing`.
-- `grist-widget-sdk/emulator/testing` re-exports the most-used
-  `@testing-library/react` primitives (`screen`, `fireEvent`, `waitFor`,
-  `act`, `cleanup`, `within`, `render`).
-- `emulator.theme.set("light" | "dark")` convenience for tests that drive
-  theme transitions.
-
-### Changed
-
-- **Breaking:** Slice hooks (`useGristStatus`, `useGristSelection`,
-  `useGristWrites`, `useGristTheme`) now require a parent
-  `<GristWidgetProvider>` and throw outside of one. Use `useGrist()` for the
-  standalone single-leaf case.
-- The inline emulator transport emits `themeInitialChange` /
-  `themeChange` instead of a single `theme` event, matching production
-  `grist-plugin-api.js`. Late listeners get replayed.
-
-### Tests
-
-- Public-API snapshot pins every documented symbol across the four entry
-  points (`/`, `/advanced`, `/emulator`, `/emulator/testing`).
-- Slice-hook integration tests for status / selection / writes / theme using
-  the emulator (`renderWithGrist`).
-- Action-builder shape tests for every supported user action.
-- `mapBack` + `allowMultiple` end-to-end test exercising the alert path.
-
-### Process
-
-- Consolidated the docs `/work/` folder (roadmap + task board + guidelines +
-  release process) into a single iteration workflow described in
-  [`apps/docs/work.md`](/work).
-  The source of truth for in-flight scope is now `/ITERATION.md`; this
-  `CHANGELOG.md` is the source of truth for history.
-
-## 0.1.0
-
-### Added
-
-- Slice hooks: `useGristSelection`, `useGristWrites`, `useGristStatus`, `useGristTheme`
-- `patchWidgetOptions`, `configure`, `refreshMappings` on `useGrist()`
-- `fetchAttachmentBlob`, schema table action builders, brief REST token cache
-- Theme subscription via `grist.on("themeInitialChange" | "themeChange")`
-
-### Changed
-
-- **Breaking:** Removed deprecated `updateRecord` / `addRecord` / `bulk*` helpers from `useGrist()`
-- **Breaking:** Removed `buildDocument()` — use `buildReplicaDocumentFromDocApi()` only
-- `useGristSchema()` defaults to `requiredAccess: "read table"`
-- `GristBoundary` unavailable grace period increased to 5s
-- Refactored `useGrist` into composable internal hooks + context slices
-
-### Fixed
-
-- `currentTableId` now refreshes when the selected row changes
-- `validateColumnMappings` no longer double-counts missing `allowMultiple` columns
+Published manually (pre-Changesets); see the root changelog's **0.1.0** →
+**Unreleased — 0.2.0** history for everything that shipped in this version.