Roadmap

Milestones and exit criteria for 0.1 → 1.0. Update statuses in the Task board when PRs land; align the current chunk of work in chat per How we work.

| --- | --- | | ROADMAP.md | Milestones 0.2 → 1.0 — themes, scope, exit criteria (this file). | | TASKS.md | Concrete tasks with stable ids (task-001, …) and status symbols. | | CHANGELOG.md | Shipped history (Unreleased while in progress). |

Pick a task from Tasks → align scope in chat → implement → update Changelog and mark the task [x]. See How we work.

---

Progress snapshot (May 2026)

Milestone	Theme	Status
0.2	API surface alignment	Done on main — task-007/008 landed; cut v0.2.0 in a follow-up release step.
0.3	Testing & emulator hardening	Done on main — RTL re-exports, waitForEvent, presets, schema snapshots.
0.4	Performance & re-render budget	Done on main — bench harness, slice identity tests, /guide/performance budgets.
0.5	Replica & schema upgrade	Not started
0.6	Examples & templates	Partially — playground demos + Guide exist; per-page playground routes + create-grist-widget CLI not done.
0.7	Pre-1.0 freeze	Not started
0.8	Optionals	Backlog — rigour/DX not blocking 1.0 (task-013 emulator parity audit).
1.0	Stable surface	Target

Package version today: 0.1.0 in packages/core/package.json. Unreleased 0.2.0 work is tracked in CHANGELOG under Unreleased — 0.2.0.

---

Versioning model

• 0.x — fast iteration, breaking changes acceptable, no migration code.
• 1.0 — frozen public surface. Anything in /api/ becomes a contract.
• 1.x — additive features, deprecations announced one minor in advance, removals only in majors.

Release mechanics: bump packages/core/package.json, tag v*, pnpm --filter grist-widget-sdk publish after merge (see workflow step 8).

---

0.2 — API surface alignment

Theme: make the implementation match the documented target surface.

Scope:

• All four slice hooks (useGristStatus, useGristSelection, useGristWrites, useGristTheme) shipped from the primary entry, with documented re-render contracts.
• useGristStatus() carries currentTableId and friends.
• mapBack(allowMultiple) skips + surfaces a warning via getGristSdkAlertDescriptors (mapBackSkipped on useGrist()).
• safeParse options accept either true or GristSafeParseOptions everywhere.
• Action builders complete (records / columns / tables / document) per /api/helpers.
• presets.blank() / presets.todoList() / presets.contacts() stable.

Out of scope: documentation reorganisation (largely done in 0.1 / current docs iteration).

Exit criteria:

• pnpm --filter grist-widget-sdk build && test green.
• Every public symbol enumerated in packages/core/tests/sdk/public-api.test.ts matches /api/.
• apps/playground consumes only the documented surface (no deep imports into package internals).

Linked tasks: Task board — milestone 0.2.

---

0.3 — Testing & emulator hardening

Theme: make renderWithGrist a credible alternative to manual Grist testing.

Scope:

• renderWithGrist re-exports the testing-library surface (screen, fireEvent, waitFor, act, cleanup).
• waitForEvent, actionsOf, eventsOf documented and covered by unit tests.
• A minimum of three preset documents (blank, todoList, contacts) used by the playground + tests.
• Snapshot tests for the schema replica produced by useGristSchema().

Out of scope (moved to 0.8): exhaustive emulator ↔ plugin API parity audit (task-013).

Exit criteria:

• A new widget can be authored end-to-end (read + write + options) with zero mocks beyond renderWithGrist.

---

0.4 — Performance & re-render budget

Theme: measurable performance guarantees.

Scope:

• A pnpm --filter grist-widget-sdk bench task that runs reproducible React render benchmarks.
• Documented "render budget" per slice hook in /guide/performance.
• Stability of returned function identities (table, getTable, applyActions, mapBack, etc.) verified by tests.
• Memoization of getTable(id) extended to all per-id factories.

Exit criteria:

• A 1000-row records subscription does not re-trigger downstream memoized components when the selection changes within the same list.

---

0.5 — Replica & schema upgrade

Theme: make the replica format complete enough to power tests, LLMs, and type generation without further changes.

Scope:

• GristReplicaColumn.references?: string added for ref/refList columns.
• GristReplicaColumnWidgetOptions type with well-known fields.
• useGristSchema() always includes selection (with mode: "empty" when absent).
• A .replica.json fixture spec documented; .grist.json deprecated.
• A pnpm --filter grist-widget-sdk replica:dump CLI that prints a replica from any deployed widget.

Exit criteria:

• Round-trip: getDocumentJson(replica) → parseDocument(json) → emulator → widget works in tests with full data fidelity.

---

0.6 — Examples & templates

Theme: every concept in the Guide has a runnable example.

Scope:

• templates/grist-widget-template-vite updated to the new API.
• apps/playground reorganised into one example per page, each one demonstrating exactly one Guide page.
• Cross-linked: every /guide/ page ends with "see live example: …".
• A create-grist-widget CLI (or one-liner npm create …) that scaffolds the template.

Exit criteria:

• A new user can read the Guide top-to-bottom and find a working example for every code snippet.

---

0.7 — Pre-1.0 freeze

Theme: lock the public surface, fix anything that would otherwise be a 1.x breaking change.

Scope:

• Close every entry in /design/open-questions.
• Audit every export from packages/core/src/sdk/index.ts against the public API test + /api/. Remove or rename anything inconsistent.
• Bundle-size budget: < 30 KB gzipped for the primary entry.
• Peer-dep range: react@^18 || ^19 || ^20.
• Final pass at error messages — every thrown Error includes the failing call site and (where useful) a doc link.

Exit criteria:

• A two-week soak with no surface changes.
• MIGRATION.md written if any 0.x → 1.0 transition needs guidance.

---

0.8 — Optionals

Theme: polish and rigour that helps maintainers and power users but does not block shipping 1.0.

Scope:

• Emulator parity audit: every grist.* method the SDK calls is implemented or throws a clear error (task-013).

Exit criteria:

• None required for 1.0 — tasks here ship when useful.

---

1.0 — Stable surface

Cut from the last 0.7 patch, no surface changes. Announcements:

• Update the README and landing page to drop the "alpha" warning.
• Tag v1.0.0, publish to npm with latest.
• Freeze the docs site (the /design/open-questions page should be empty or repurposed for 1.x discussions).
• Open /design/v2/ for any future major-version proposals.

---

1.x — Additive era

• Deprecations announced one minor in advance via console.warn + /design/open-questions.
• Removals only in 2.0.
• New features land behind named exports — no flag-based opt-ins.

The roadmap from here is open and lives in the same Task board.

---

Cross-cutting

These don't fit cleanly in one milestone but ship continuously:

• Documentation — every PR that touches behavior updates the relevant /guide/, /api/, /design/ pages.
• Changelog — every PR adds a CHANGELOG.md entry under "Unreleased".
• CI — every PR runs build, test, tsc --noEmit, lint (when task-091 lands) before merge.
• Browser support — modern evergreen browsers + the Grist desktop / web hosts. No polyfills.