Upgrading

Every @platform/sdk release so far is within the 1.x line and backwards-compatible — each adds API without removing or changing existing behaviour, so upgrading is a version bump, not a migration. This page records what each release adds and will carry a step-by-step migration when the first breaking (major) change lands.

The general process

When a new version ships:

1. Bump @platform/sdk and re-run npm install.
2. Run your typecheck. Because the SDK is strict TypeScript, a removed or renamed API surfaces as a compile error pointing straight at the call site — the fastest possible upgrade signal.
3. Skim the CHANGELOG.md shipped with the package (node_modules/@platform/sdk/CHANGELOG.md) for entries between your old and new versions, looking for Removed and Changed.

Pin intentionally

Pin @platform/sdk to a caret range within a major (^1.0.0) so you get compatible minors and patches automatically, and treat a major bump as a planned migration. See SDK versioning and pinning.

1.3.0 — ergonomic helpers (optional)

1.3.0 is additive: nothing was removed, so upgrading is a bump + npm install. It adds three conveniences you can adopt incrementally, each replacing a hand-rolled pattern:

• conn.activate(el) — one call for a surface or modal body’s bring-up, replacing the observe(el) + ready() (+ a requestAnimationFrame) you wrote by hand. See Embedded surfaces and Modals.
• surfaceHost(platform, opts) — a single-slot host whose render(params) embeds first and re-parameterises after, folding in the embedSurface embed-or-update branch and the ready rejection handler. See Embedded surfaces.
• defineStateChannel(namespace) — a typed, named handle over platform.state / conn.state so a cross-frame namespace and its shape are declared once. See Cross-frame state.

One behaviour change worth knowing: StateWriter.set now suppresses a write whose snapshot is structurally equal to the last one sent. This removes redundant cross-frame traffic and lets a reactive binding push the seed snapshot harmlessly (no “already seeded” guard). A genuinely changed snapshot is always delivered; a suppressed equal write simply does not appear in the ops traffic log.

When a breaking change ships

The wire protocol is backwards-compatible within a major version, so the upgrades that need real work are major bumps. When the first one lands, this page will carry a step-by-step migration — what was removed and what to do instead — keyed to its changelog entry.