grist-widget-sdk 0.3.27 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # grist-widget-sdk
 
+## 0.5.0
+
+### Minor Changes
+
+- d3d9232: **`defineGristWidget()`: one declaration types, mounts and tests a widget.**
+  
+  ```ts
+  export const widget = defineGristWidget({
+    title: "Tasks",
+    requiredAccess: "full",
+    columns: [{ name: "Title", type: "Text" }, { name: "Done", type: "Bool" }],
+  })
+  const w = widget.useGrist()          // mappedRecord typed from the declaration: no generics, no `as const`
+  await w.updateRecord({ Done: true }) // the selected row, encoded for each declared type
+  ```
+  
+  - `defineGristWidget(definition)` keeps the column names and types literal (a `const` type parameter), so `widget.useGrist()` types `mappedRecord`, `mappedRecords`, `mapBack` and the writes from the declaration. `GristWidgetRow<typeof widget>` names the record type.
+  - `useGrist()` gains `updateRecord(patch)` / `updateRecord(rowId, patch)` and `addRecord(patch)`: `mapBack` + encoding + `table.update` / `table.create` in one call, under the declared names.
+  - `mountGristWidget(entry, { dev })` takes the widget's entry module (`import * as entry from "./app/App"`) and reads its exports: `default`, `widget` (or `GRIST_OPTIONS` and `WIDGET_METADATA`), and optionally `Alerts`, `LocalDevPage`, `ReleasePage`. A widget's customisations then live in its own file instead of `src/main.tsx`. The declaration's title and description set the page's title and meta tags. `mountGristWidget({ App, options, dev })` still works.
+  - `renderWithGrist(<App />, { widget, rows })` runs the widget as `mountGristWidget()` does inside Grist, against a table with a column per declared column, every one mapped, seeded with typed rows: no document or mapping setup in a test. `smokeTestWidget(entry)` takes the entry module as `mountGristWidget()` does (or `{ App, widget }`), so one smoke test fits a widget declared either way.
+  
+  Nothing changes for an existing widget: `GRIST_OPTIONS`, `useGrist<TRow, TMapped>()`, `mapBack` and `table.update` work as before.
+
+### Patch Changes
+
+- 734d307: **`pnpm dev` opens the widget in real Grist, in the browser, with no Docker.** The template ships its demo page (`public/demo/`, a document for its widget and the page that opens it in grist-static), and on the dev server `http://localhost:5173/demo/index.html` runs that Grist on the dev server's own widget: edits reload in place, writes land in the document. The SDK's local-dev page links to it (or says how to get it, `pnpm demo --save`, when the widget has no demo page yet). The scaffold puts the widget's title in the page.
+  
+  Existing widgets can do nothing: those with a demo page (`pnpm demo --save`) already get it on `pnpm dev` at `/demo/index.html`; the others get it once they run `pnpm demo --save` (Docker, once).
+- dfb2e66: **Writes are the mirror of typed reads.** `mapBack` now encodes each value for the type its column declares: a ChoiceList's `string[]`, a RefList's row ids or an Attachments list become `["L", ...]`, a `Date` becomes seconds, a `Reference` its row id. Before, writing back what `mappedRecord` gave stored a ChoiceList or RefList cell as an error (`["E", "KeyError"]`, checked in Grist 1.7.22), because Grist's plugin API writes values as given. `encodeGristCell(type, value)` is exported for writes that don't go through `mapBack`; a value already encoded passes through.
+  
+  The emulator now stores a bare list written to a list column as Grist does, an error cell reported in `cellIssues`, so `pnpm test` shows the mistake instead of hiding it.
+  
+  Overlapping writes count as one run: `actionStatus` stays `"running"` until the last one ends, then is `"error"` if any failed (the first write to end used to set it back to `"idle"`). A failed write nobody awaits no longer logs an unhandled rejection; the alert reports it, and the promise still rejects for whoever awaits it.
+  
+  What to change, if a widget relies on it: a widget that already encoded lists itself (`["L", ...]`, `encodeGristValue`, the attachment helpers) needs nothing. A test that wrote a bare array to a RefList through the emulator now gets an error cell: encode it, or go through `mapBack`.
+- ca3f010: `GristMappedRow` now types every declared column as its value or `null`, `Text` and `Bool` included (`Title: string | null`, not `string`). It promised a non-null value for those types while `mappedRecord` holds `null` for a cell that doesn't match its declared type, so a widget trusting the type could crash on a formula error. A widget that reads a `Text` or `Bool` column from a `GristMappedRow` may need a fallback (`row.Title ?? ""`) to compile.
+  
+  The package README, shown on npm, describes the 0.4.0 surface; it still listed `grist-widget-sdk/advanced`, the slice hooks and the emulator's iframe transport and devtools, all removed in 0.4.0.
+
+## 0.4.0
+
+### Minor Changes
+
+- a257767: The emulator is a test harness only. Removed: `grist-widget-sdk/emulator/transports` (the iframe transport, `createIframeTransport`) and `grist-widget-sdk/emulator/devtools` (the inspector), which only the retired playground used; `createGristEmulator`'s `transport` option takes `{ kind: "inline", target? }` only. `renderWithGrist`, `smokeTestWidget` and `createGristEmulator` are unchanged. To see a widget run, use a real Grist: `pnpm demo`, or its demo page (`pnpm demo --save`).
+- 74395a7: **0.4.0: a synchronous runtime and a small public surface (breaking).**
+  
+  The connection to Grist is one synchronous `connect()` and one store read through `useSyncExternalStore`, instead of the handshake state machine (detection polling, a 30 s heartbeat, generations). `useGrist()` keeps its shape for what widgets use and re-renders less (a cursor move: 3 renders to 1). The root entry exports 29 runtime names instead of about 195; `grist-widget-sdk/advanced` is gone.
+  
+  Fixed on the way: `fetchSelectedTable()` returned rows while typed as columns (a widget passing it to `tableDataToRows()` got nothing; it now returns columns); `mode` stuck on `"new-row"` when the selection went away; records reused and mutated by the host no longer go unnoticed. The emulator now matches Grist on `setOptions` (replaces), the add-row (`onNewRecord` only), unmapped columns (`mappedRecord` is `null`) and access (it grants what the widget asks for unless a test sets `widgetInteraction.access_level`).
+  
+  What to replace, if a widget uses it (the six reference widgets need nothing):
+  
+  | Removed | Use instead |
+  | --- | --- |
+  | `useGristSelection()`, `useGristStatus()`, `useGristWrites()`, `useGristTheme()` | `useGrist()` |
+  | `grist-widget-sdk/advanced` (`useGristReady`, `useGristHandshake`, `useGristCapabilities`, `useGristRowsFromTable`, …), `GristHandshakeProvider` | `useGrist()` (`status`, `columnMappingStatus`), or `fetchTableRows` in an effect |
+  | `w.capabilities` | `w.status`, `w.columnMappingStatus.ok`, `w.isReady` |
+  | `w.getWidgetOptions()`, `w.getWidgetOption(key)` | `w.widgetOptions` |
+  | `w.setWidgetOption(key, value)` | `w.patchWidgetOptions({ [key]: value })` |
+  | `w.clearWidgetOptions()` | `w.setWidgetOptions({})` |
+  | `w.fetchRow(table, id)` | `w.fetchTableRows(table)` |
+  | `w.fetchSelectedRecord(id)` | `w.record`, or `w.fetchSelectedTable()` |
+  | `w.buildReplicaDocumentFromDocApi(...)`, `buildReplicaDocumentFromDocApi` | `useGristSchema()` |
+  | `w.getDocName()`, `w.configure()`, `w.refreshMappings()`, `w.refreshCurrentTable()`, `w.currentTableLoading` | — (`currentTableId` and `mappings` follow Grist) |
+  | `w.isNewRecord`, `w.recordsMappings`, `w.newRecordMappings` | `w.mode === "new-row"`, `w.mappings` |
+  | `w.widgetInteraction`, `w.readError`, `w.mapBackSkipped` | the alerts `mountGristWidget()` shows |
+  | `w.getAccessToken()`, `w.fetchAttachmentBase64()`, `getGristAccessToken`, `fetchWithGristAuth` | `w.fetchWithAuth()`, `w.fetchAttachmentBlob()` |
+  | `<GristBoundary gate widget bootingFallback …>` | `<GristBoundary>`: it gates on declared columns itself |
+  | alert and boundary helpers (`getGristSdkAlertDescriptors`, `deriveBoundaryView`, `format…AlertMessage`, …), `validateColumnMappings` | `mountGristWidget()` shows them; `w.columnMappingStatus` |
+  | replica builders and normalizers, value codecs beyond `decodeGristValue` / `encodeGristValue` / `isGristCellError`, `gristBulk*` / table / document action builders | write the user-action tuple; `useGristSchema()` |
+  | `GristReadyOptions.availabilityMaxAttempts`, `availabilityIntervalMs`, `logWhenNotEmbedded` | — (no polling) |
+- 673a02d: **Typed reads, with read-only access; no zod in a widget's bundle.**
+  
+  Each mapped cell is now checked against the type its column declares in `GRIST_OPTIONS.columns`: no schema to fetch, no full access. `mappedRecord` (and the new `mappedRecords`, every row of the section) holds the value each type promises (`Text` → string, `Numeric` → number, `Date` → `Date`, `Ref` → row id, `RefList` / `Attachments` → ids, `ChoiceList` → strings); a cell that doesn't match (text Grist couldn't parse, a formula error, a column whose type changed) is `null`, and listed in the new `cellIssues` (`{ rowId, column, message, value }`), which `mountGristWidget()` shows as a `cell-issues` alert. `GristMappedRow<typeof GRIST_OPTIONS>` types the mapped records from the declaration (declare it `as const satisfies UseGristOptions`). `UseGristOptions.schema` takes any Standard Schema (zod 4, valibot, arktype) for extra rules; the SDK depends on none. `checkGristCell(type, value)` checks a value read another way.
+  
+  Removed: `safeParseGristTableData`, `safeParseRowsToDisplayRows` and `fetchTableRows`'s `safeParse` option (the zod-based safe-parse), which put zod in every widget. A widget's template build goes from 129 KB to 94 KB of JavaScript, gzipped; CI now fails above 100 KB.
+  
+  What to change, if a widget relies on it (the six reference widgets need nothing): a `Ref` column's value in `mappedRecord` is now its row id (it was a `Reference` object), and a cell that doesn't match its declared type is `null` (it was the raw value); safe-parse users read `mappedRecords` / `cellIssues`, or call `checkGristCell` per cell.
+
+### Patch Changes
+
+- f4a467a: Routine dependency updates via Dependabot (PR #241). See the PR diff for the exact version bumps.
+- f5e04b4: `fetchWithGristAuth()` (and `w.fetchWithAuth()`) now refuses an absolute URL on another origin than the document's Grist instance, instead of sending the document's access token there. The token travels as the `auth` query parameter, so a URL taken from a cell or another input could hand it to any host. Relative paths and absolute URLs on the Grist instance work as before; for other hosts, use plain `fetch()`.
+
 ## 0.3.27
 
 ### Patch Changes

package/README.md

@@ -1,249 +1,120 @@
 # grist-widget-sdk
 
-React hooks and TypeScript utilities for building Grist widgets.
+React hooks for [Grist](https://www.getgrist.com) custom widgets: one
+`useGrist()` for the connection, the selected record and the section's
+records, column mapping, typed reads, writes, widget options and the
+document's REST API, plus an emulator to test a widget without Grist.
 
-## Why not use `grist` directly?
+Documentation: <https://gristwidgets.com/docs>. To start a widget, use the
+scaffold, which wires all of this up:
 
-Grist’s [`grist-plugin-api.js`](https://docs.getgrist.com/grist-plugin-api.js) exposes a global `grist` object. For React widgets, **`grist-widget-sdk`** replaces hand-rolled glue:
+```bash
+npm create grist-widget my-widget
+```
+
+## Why not `grist` directly?
 
 | Raw `grist` | SDK |
 | --- | --- |
-| `grist.ready` + `onRecord` callbacks | `<GristWidgetProvider>` + `useGrist()` with `mode` |
-| Wire-format dates/refs | Decoded values by default |
-| `mapColumnNames` / tuples for writes | `mappedRecord`, `mapBack`, `table.update` |
-| No test harness | `renderWithGrist` + emulator presets |
+| `grist.ready` and `onRecord` callbacks | `useGrist()`: `status`, `record`, `records`, `mode` |
+| Wire-format dates, refs and errors | Each mapped cell as its declared type (`mappedRecord`), mismatches in `cellIssues` |
+| `mapColumnNames`, tuples for writes | `mappedRecord`, `mapBack`, `table.update` |
+| No test harness | `renderWithGrist` with emulator presets |
 
 Full comparison: [Raw plugin API vs SDK](https://gristwidgets.com/docs/sdk/guide/raw-plugin-api-vs-sdk).
 
-## What This Package Provides
-
-- Main API via `grist-widget-sdk` (hooks, types, helpers)
-- `grist-widget-sdk/advanced` — lower-level hooks (`useGristReady`, `useGristHandshake`, …)
-- `grist-widget-sdk/emulator` subpath for emulator utilities
-- ESM + CJS + type declaration builds (`.d.ts`)
-
-## Installation
+## Install
 
 ```bash
 pnpm add grist-widget-sdk
 ```
 
-Required peer dependencies:
-
-- `react >= 18`
-- `react-dom >= 18`
-
-## Grist Runtime Script (Required)
-
-This package expects a global `grist` object at runtime.
-
-Load the official Grist plugin API script in your app shell/layout:
+Peer dependencies: `react` and `react-dom` 18 or later. The page must load
+Grist's plugin API, which defines the `grist` global:
 
 ```html
 <script src="https://docs.getgrist.com/grist-plugin-api.js"></script>
 ```
 
-## Quick Start Next.js (`app/layout.tsx`)
+## A widget
 
 ```tsx
-import Script from "next/script"
-import { GristBoundary, GristWidgetProvider } from "grist-widget-sdk"
-
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return (
-    <html lang="en">
-      <body>
-        <Script src="https://docs.getgrist.com/grist-plugin-api.js" />
-        <GristWidgetProvider options={{ requiredAccess: "read table" }}>
-          <GristBoundary>
-            {children}
-          </GristBoundary>
-        </GristWidgetProvider>
-      </body>
-    </html>
-  )
+// src/app/App.tsx
+import { defineGristWidget } from "grist-widget-sdk"
+
+export const widget = defineGristWidget({
+  title: "Tasks",
+  requiredAccess: "full",
+  columns: [{ name: "Title", type: "Text" }, { name: "Done", type: "Bool" }],
+})
+
+export default function App() {
+  const w = widget.useGrist() // w.mappedRecord: { id; Title: string | null; Done: boolean | null } | null
+  if (w.mode !== "row" || !w.mappedRecord) return <p>Select a task.</p>
+  return <button onClick={() => w.updateRecord({ Done: true })}>{w.mappedRecord.Title}</button>
 }
 ```
 
-Then render widget content from your page, for example `app/page.tsx`:
-
 ```tsx
-import { useGrist } from "grist-widget-sdk"
-
-export default function Page() {
-  const w = useGrist()
-
-  if (w.status === "booting") return <p>Loading...</p>
-  if (w.mode === "empty") return <p>Select a row.</p>
-  if (w.mode === "new-row") return <p>New row flow</p>
+// src/main.tsx
+import { mountGristWidget } from "grist-widget-sdk/app"
+import * as entry from "./app/App"
 
-  return <p>Record id: {String(w.record?.id ?? "")}</p>
-}
+mountGristWidget(entry, { dev: import.meta.env.DEV })
 ```
 
-## Quick Start Vite (`src/main.tsx`)
-
-In `index.html`, load the script:
-
-```html
-<script src="https://docs.getgrist.com/grist-plugin-api.js"></script>
-```
-
-Then mount your widget root:
+The declaration types everything with no generics: the mapped records, and
+the writes (`updateRecord`, `addRecord`), which encode each value for its
+declared type. `mountGristWidget()` reads `App.tsx`'s exports: the widget,
+its declaration (for the access, the columns and the page title), and any
+page it replaces. Inside Grist it renders the widget in `GristWidgetProvider`
+and `GristBoundary` (the connecting, access and column-mapping screens), with
+the SDK's alerts, in Grist's light or dark theme.
+
+## Entry points
+
+- **`grist-widget-sdk`**: `defineGristWidget`, `useGrist`, `useGristContext`, `useGristOptional`,
+  `GristWidgetProvider`, `GristBoundary`, `useGristSchema`,
+  `useWidgetMetadata`, `checkGristCell`, `encodeGristCell`, the value codec, the attachment
+  helpers, the user-action builders for `applyActions`, and Grist's types.
+  [API reference](https://gristwidgets.com/docs/sdk/api).
+- **`grist-widget-sdk/app`**: `mountGristWidget`, `GristWidgetApp`,
+  `useTheme`, and the deploy-channel helpers the scaffold's pages use.
+  [Reference](https://gristwidgets.com/docs/sdk/api/app).
+- **`grist-widget-sdk/emulator`**: `createGristEmulator`, document
+  `presets`, `parseDocument`. [Reference](https://gristwidgets.com/docs/emulator/api).
+- **`grist-widget-sdk/emulator/testing`**: `renderWithGrist`,
+  `smokeTestWidget`, `installJsdomStubs`, the matchers (`actionsOf`,
+  `eventsOf`, `waitForEvent`), `presets`, and the usual
+  `@testing-library/react` helpers. [Testing](https://gristwidgets.com/docs/emulator/testing).
+- **`grist-widget-sdk/tsconfig/app.json`**, **`/tsconfig/node.json`**: the
+  compiler settings a scaffolded widget extends.
+
+ESM and CJS builds, with type declarations.
+
+## Testing a widget
 
 ```tsx
-import { StrictMode } from "react"
-import { createRoot } from "react-dom/client"
-import { GristBoundary, GristWidgetProvider, useGrist } from "grist-widget-sdk"
-
-function WidgetContent() {
-  const w = useGrist()
-
-  if (w.status === "booting") return <p>Loading...</p>
-  if (w.mode === "empty") return <p>Select a row.</p>
-  if (w.mode === "new-row") return <p>New row flow</p>
-
-  return <p>Record id: {String(w.record?.id ?? "")}</p>
-}
-
-function App() {
-  return (
-    <GristWidgetProvider options={{ requiredAccess: "read table" }}>
-      <GristBoundary>
-        <WidgetContent />
-      </GristBoundary>
-    </GristWidgetProvider>
-  )
-}
-
-createRoot(document.getElementById("root")!).render(
-  <StrictMode>
-    <App />
-  </StrictMode>
-)
+import { fireEvent, renderWithGrist, screen, waitFor } from "grist-widget-sdk/emulator/testing"
+import App, { widget } from "./App"
+
+it("marks the task done", async () => {
+  const { emulator } = renderWithGrist(<App />, { widget, rows: [{ Title: "Ship", Done: false }] })
+  fireEvent.click(await screen.findByRole("button", { name: "Ship" }))
+  await waitFor(() => expect(emulator.state.tables.get("Table1")!.rows[0]).toMatchObject({ Done: true }))
+})
 ```
 
-## Exports
-
-Main entrypoint:
-
-- `grist-widget-sdk` — production surface:
-  - Components: `GristWidgetProvider`, `GristBoundary`, `useGristContext`, `useGristOptional`
-  - Primary hook: `useGrist` (includes `capabilities` — `canRender`, `canWriteRecords`, …)
-  - Slice hooks: `useGristStatus`, `useGristSelection`, `useGristWrites`, `useGristTheme`
-  - Schema hook: `useGristSchema`
-  - Helpers: action builders, value codec, safe parsing, replica builders,
-    REST auth, attachments, column-mapping validation, alerts.
-
-Subpath exports:
-
-- `grist-widget-sdk/advanced` — low-level / mid-level hooks for power users
-  (`useGristReady`, `useGristAvailability`, `useGristRecord`, `useGristRecords`,
-  `useGristActions`, `useGristTableOps`, `useGristMappedRecord`,
-  `useGristRowsFromTable`, `useGristAccessToken`, `useGristSection`,
-  `useGristWidgetOptions`, `useGristTable`).
-- `grist-widget-sdk/emulator` — `createGristEmulator`, `parseDocument`,
-  `safeParseDocument`, `presets`, emulator types.
-
-## Replica document (`GristReplicaDocument`)
+The emulator runs in the test process and stands in for `window.grist`. It
+is a test harness, not a preview: to see a widget run, use a real Grist
+(`pnpm demo` in a scaffolded widget, or its demo page).
 
-One JSON shape is used for **`useGristSchema()`**, **`getDocumentJson` / `buildDocumentJson`**, playground **`*.grist.json`** fixtures, and **`createGristEmulator({ document })`**. Valid fixtures are checked with **`parseDocument`** (Zod).
+## Developing this package
 
-### Top-level fields
-
-| Field | Required | Notes |
-| --- | --- | --- |
-| `generatedAt` | yes | ISO 8601 string |
-| `tables` | yes | `Record<tableId, GristReplicaTable>` — keys align with `docApi.listTables()` / `fetchTable(tableId)` |
-| `source` | no | Provenance (e.g. pass `useGristSchema({ source })` or `buildReplicaDocumentFromDocApi(docApi, { source })`); hosts may log it |
-| `docName`, `mode`, `selection`, `widgetOptions`, `widgetInteraction`, `configuration`, `accessToken` | no | Same semantics as in types |
-
-Optional **`mode`**: `"schema-only"` \| `"schema+samples"` \| `"schema+data"` (hint only). At boundaries, use **`normalizeReplicaTableInput`** / **`normalizeReplicaDocumentInput`** so missing **`rows`** behaves like **`[]`**.
-
-### Tables and rows
-
-- **`GristReplicaTable`**: optional `label`, `columns`, `rows`, `rowCount`, `dataOmitted`, etc.
-- Row bodies are **`GristReplicaRow`** (`{ id: number, … }`), **not** columnar `fetchTable` wire format. Use **`buildReplicaDocumentFromDocApi`** or **`decodeColumnarToReplicaRows`** to build rows from `docApi.fetchTable`.
-
-### Building and serializing
-
-- Prefer **`buildReplicaDocumentFromDocApi(docApi, { includeRows: false \| "samples" \| "full", sampleRowLimit, source, includeSystemTableData })`**, or **`w.buildReplicaDocumentFromDocApi(...)`** from **`useGrist()`**.
-- **`getDocumentJson` / `buildDocumentJson`** accept **`includeRows`**: `"none"` \| `"samples"` \| `"full"` (plus optional **`sampleRowLimit`**, **`space`**).
-
-### Emulator
-
-Only a full **`GristReplicaDocument`** is accepted: **`createGristEmulator({ document })`** and **`parseDocument`**. There is no legacy coercion or alternate “emulator input” type; assemble the object (or load JSON), then **`parseDocument`** if you need validation.
-
-The canonical design document for this shape is [Replica document](https://gristwidgets.com/docs/sdk/design/replica-document).
-- `grist-widget-sdk/emulator/transports` — low-level `iframe` and `inline` transports if you need to wire your own host.
-- `grist-widget-sdk/emulator/devtools` — `<EmulatorInspector />` React component (table editor + event timeline + options).
-- `grist-widget-sdk/emulator/testing` — `renderWithGrist(...)`, vitest
-  matchers (`actionsOf`, `eventsOf`, `waitForEvent`), document `presets`,
-  and the most-used `@testing-library/react` primitives (`screen`,
-  `fireEvent`, `waitFor`, `act`, `cleanup`, `within`, `render`) so a typical
-  test file only needs one import line.
-
-## Emulator (SOTA)
-
-The emulator is the single source of truth for three use-cases:
-
-1. **Demoing widgets** — production-fidelity by loading the *real*
-   `grist-plugin-api.js` inside an iframe and speaking `grain-rpc` over
-   `postMessage`:
-
-   ```tsx
-   import { createGristEmulator, presets } from "grist-widget-sdk/emulator"
-   import { EmulatorInspector } from "grist-widget-sdk/emulator/devtools"
-
-   const iframe = document.querySelector("iframe")!
-   const emulator = createGristEmulator({
-     document: presets.todoList(),
-     transport: { kind: "iframe", iframe },
-   })
-   ```
-
-2. **Robust SDK testing** — `renderWithGrist` synthesises `window.grist`
-   in-process, so every `useGrist` test goes through the *exact* same code
-   path without ceremony:
-
-   ```ts
-   import { renderWithGrist } from "grist-widget-sdk/emulator/testing"
-
-   const { emulator, getByText } = renderWithGrist(<MyWidget />, {
-     emulator: { document: presets.contacts() },
-   })
-   emulator.mutate.addRow("Contacts", { firstName: "Grace", lastName: "Hopper" })
-   ```
-
-3. **Live IDE preview** — same `inline` transport, mounted next to the
-   widget to give a Storybook-grade dev loop.
-
-## Local Development
-
-From the workspace root:
+From the monorepo root:
 
 ```bash
 pnpm --filter grist-widget-sdk build
-pnpm --filter grist-widget-sdk dev
 pnpm --filter grist-widget-sdk test
-```
-
-## Pre-Commit / Pre-Publish Checks
-
-```bash
-pnpm --filter grist-widget-sdk build
 pnpm --filter grist-widget-sdk exec tsc --noEmit
-pnpm --filter grist-widget-sdk exec vitest run
-pnpm dlx @arethetypeswrong/cli -P packages/core
 ```
-
-If no tests exist yet:
-
-```bash
-pnpm --filter grist-widget-sdk exec vitest run --passWithNoTests
-```
-
-## Notes
-
-- This package targets pure TypeScript/React usage (no Next.js dependency required).
-- ATTW may report a `node10` warning for the `grist-widget-sdk/emulator` subpath. This is expected for modern `exports`-based packages and is non-blocking for Node 16+ and modern bundlers.