All notable changes to @tv/extension-sdk.

The format follows Keep a Changelog; the SDK uses Semantic Versioning from 1.0 onward.

[1.0.0] — 2026-05-30

First stable release. The surface tagged in Phase 2.1 (see STABILITY.md) is now binding under semver: @stable exports carry a 6-month deprecation guarantee; @experimental exports may still change in any release.

No breaking API changes from 0.2.0 — the move to 1.0 is the commitment to the surface, not a reshaping of it. Existing consumers upgrade by bumping the version; review the @experimental list below and decide which symbols to track changes on.

Added

• Stability tiers documented: every subpath barrel now carries a @stable or @experimental JSDoc tag. See STABILITY.md.
• @tv/extension-sdk/permissions — permission catalog extractor + types (extractCatalog, extractCatalogFromFile, PermissionCatalog, SubjectEntry). Phase 2.4.
• tv-sdk snapshot-permissions CLI command — extracts the catalog from tv-api's PERMISSION_ROLE_MAP source. Phase 2.4.
• permissions.snapshot.json artifact ships with the package (17 subjects, 33 actions as of 2026-05-25).
• @tv/extension-sdk/sandbox — tv-sdk sandbox CLI subcommand family (create / list / connect / extend / delete / reset). Phase 1a.4. @experimental — surface may grow during Phase 1a rollout.

Changed

• Build moved off zod-to-json-schema (Zod 3-only) onto Zod 4's built-in z.toJSONSchema(). Affects manifest.schema.json + tv-events.snapshot.json outputs — same contract, normalized representation. CI's check-events self-consistency passes against the regenerated snapshot.
• tsconfig.json adds "types": ["node"] so node:fs / process / etc. resolve. Closes silent SDK build break that started 2026-05-01.
• z.record() call sites updated to Zod 4's two-arg form (z.record(z.string(), …)).
• manifest.schema.json regenerated under Zod 4's emitter — more strict (more required fields surfaced). Downstream consumers using $schema for editor validation should re-validate their manifests.

Removed

• zod-to-json-schema dependency (no longer used).

Stability tiers in this release

Already @stable (no churn expected within a major):

• @tv/extension-sdk/manifest — schema + validator + scaffolders + checkExposes
• @tv/extension-sdk/context — PlatformContext types
• @tv/extension-sdk/events — catalog, envelope, subjects
• @tv/extension-sdk/api — PlatformApiClient types
• @tv/extension-sdk/react — provider + core hooks
• @tv/extension-sdk/nestjs — @ModuleCapability(), @RequiresLicense() decorators
• @tv/extension-sdk/testing — createMockPlatformContext
• @tv/extension-sdk/permissions — extractor + catalog types
• CLI: validate, check-exposes, init-manifest, init-module, write-version, snapshot-permissions
• JSON artifacts: manifest.schema.json, permissions.snapshot.json

@experimental (may change in any release until graduation; see STABILITY.md):

• @tv/extension-sdk/heartbeat
• @tv/extension-sdk/version-check
• @tv/extension-sdk/sandbox (CLI subcommands)
• Manifest fields: PayloadContract, McpToolDeclaration.permissions
• CLI: check-events, check-api, check-pact, snapshot-events, snapshot-api
• React: useVersionCheck, <UpdatePrompt>
• NestJS: TvHeartbeatModule.register()

[0.2.0] — 2026-04 (historical reference)

Initial SDK consolidation. ModuleManifest schema + PlatformContext + React/NestJS integration. See git history for details.

Migration guide: 0.x → 1.0

When 1.0.0 ships (Phase 2.2), the surface above becomes binding under semver. There are no breaking API changes between current pre-1.0 and the planned 1.0 — only the addition of the stability tiers. Existing internal consumers should not need code changes; they should review the @experimental list above and decide which symbols to track changes on more carefully.