> For the complete documentation index, see [llms.txt](https://basedapp.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://basedapp.gitbook.io/docs/integrations/mini-apps-platform/13-changelog.md).
# Changelog
This is the partner-facing changelog for `based_mini_app_sdk` and the `based.*` JS surface. It mirrors the npm-published `@based/sdk-types` versions.
The changelog is **append-only** for resolved entries. Anything still in flight lives in `12-open-questions.md`.
## v1.0.0 — Unreleased (Phase 5 / GA)
Initial GA. The full surface listed in [`03-host-contract.md`](/docs/integrations/mini-apps-platform/03-host-contract.md) ships under SDK 1.0.0. From this version on:
* `targetSdkVersion: "1.0"` is supported by host versions that advertise `sdkVersion ≥ "1.0.0"`.
* API additions are minor-version bumps (1.1, 1.2, …); breaking changes are major-version bumps following the deprecation policy in [`14-breaking-change-policy.md`](/docs/integrations/mini-apps-platform/14-breaking-change-policy.md).
## v0.x — Pre-GA
The 0.x series is reserved for the Phase 4 partner pilot. Bundles built against `targetSdkVersion: "0.x"` are accepted by the bridge in **strict compat mode**, with no shims — partners are expected to track latest 0.x during the pilot.
| Version | Date | Notes |
| ------- | ---------------- | ----------------------------------------------------------------------------------------------- |
| 0.1.0 | 2026-Q4 (target) | First partner pilot; full host contract minus `nav.openMiniApp` and `signing.signEvmTypedData`. |
| 0.0.x | 2026-04 → | Internal pre-pilot series. Phase 2/3 work. |
## Significant changes — 2026-04 batch (current 0.0.x snapshot)
This catches the docs up with everything that's landed in the host + SDK + JS-runtime since the last formal review. None of these are breaking under `targetSdkVersion: '0.x'`; partners on 1.0 will pick them up at major release time.
### Runtime / engine
* **QuickJS now runs in a dedicated Dart isolate** (architecture spec A1, implemented). `MiniAppRuntime` is a host-side proxy; the engine, the three `sendMessage` channels (`based-bridge` / `based-console` / `based-rerender`), and microtask pumping all live in `js_worker.dart`. JS no longer blocks the UI isolate. See [`05-js-runtime.md`](/docs/integrations/mini-apps-platform/05-js-runtime.md).
* **CPU watchdog hard-kills the worker** on `TimeoutException` via `Isolate.kill(priority: Isolate.immediate)`, freeing the host instead of pinning it forever. Pending Completers unwind so awaiters don't hang.
* **Rerender coalescing** in the worker: at most one in-flight `App()` evaluation; bursts collapse to a "dirty" flag and one trailing rerun.
* **Host-side fire-event serialization** via a Future tail so vdom updates land in dispatch order even with rapid taps.
* **Worker error / exit listeners** route uncaught isolate errors through a single `_terminate(reason)` chokepoint.
### UI catalog additions
The renderer's case dispatch now covers a substantial post-v1 catalog. Every type below is shipped, doc'd in [`07-ui-nodes-and-renderer.md`](/docs/integrations/mini-apps-platform/07-ui-nodes-and-renderer.md), and exposed via the SDK type declarations:
* **Animation:** `Motion` (initial/animate/exit/transition with `repeat: 'reverse' | 'loop'`), `AnimatePresence`.
* **Effects:** `Gradient` (linear + radial), `Blur`, `DropShadow`, `AspectRatio`, `PositionedAbsolute`, `SafeArea`, `IgnorePointer`, `Marquee`.
* **Media:** `Video`, `WebView`.
* **Chrome:** `BottomNavBar`.
* **Sensor-driven:** **`CardTilt`** — gyro-driven 2.5D parallax tilt for a single card image. Reads `sensors_plus` natively in the renderer, applies a perspective `Matrix4` + radial-gradient glare overlay that tracks the tilt. Auto-orbits when no sensor is available and clamps to zero when reduce-motion is on. **No permission required** — sensor access is out-of-band of the bridge.
### `BasedGyro` namespace (new)
```ts
based.gyro.read(): Promise<{
accelerometer: { x, y, z } | null;
gyroscope: { x, y, z } | null;
timestampMs: number;
}>
```
Pull-based one-shot read. The first call kicks off the host's sensor stream; subsequent calls return cached samples updated at the platform's native rate. Mini-apps wanting continuous updates poll on `setInterval` (30 Hz is plenty). New permission **`gyro.read`**.
The native `` UiNode does **not** use this namespace and does **not** require the permission — it lives entirely in the renderer.
### `Text` props
Two new props on every `Text` UiNode:
* `maxLines: number` — hard cap on line count.
* `overflow: 'clip' | 'ellipsis' | 'fade' | 'visible'` — tail handling when content exceeds `maxLines` or the bounded row width.
Use `maxLines: 1` + `overflow: 'ellipsis'` inside `ui.Expanded(...)` for narrow-row labels.
### Hex colour parser fix (renderer)
The `Gradient` / `DropShadow` parser previously treated 8-char hex as ARGB while every other color prop in the renderer treated it as RRGGBBAA (CSS convention, alpha last). All effects widgets now use the RRGGBBAA convention consistently. If a partner sees pink-spec'd gradients render green, they're on a stale host build.
### JSX runtime
The partner CLI's esbuild config and `tsconfig.json` template ship with `jsxFactory: 'h'` wired by default. The mini-app project template provides `src/jsx-runtime.ts` plus `src/jsx-ui.ts` so partners can write `{kids}` instead of `ui.Column(kids, { spacing: 0 })` without adding a build step. JS-side authoring style is partner choice; both factory-call and JSX produce identical UiNode JSON.
### Public points leaderboard endpoint (partner backend, parity-only)
`GET /api/public/leaderboard/points?period=weekly|all&limit=10` — public mirror of the web's `getPointsLeaderboard` server actions. Returns `{ id, username, displayName, avatarUrl, points }`. Privacy-aware via `publicIdentity`. Used by the gacha mini-app's leaderboard tab. Not part of the SDK surface — listed here so partners aren't surprised by the new route.
### Card detail surface (partner-side polish, no SDK change)
The pack-detail public route now selects `psaCertNumber` alongside the existing `condition` / `cardNumber` / `language` / `year` fields. Partners that build a card-detail sheet against `LiveCard` should expect those fields to be populated; types in the project template were updated. Renderer-side the gacha mini-app's sheet now offers a **2D / 3D toggle** (3D = ``).
## Significant changes — 2026-05 batch
This batch is heavy on the surface-area side: notifications, Live Activities, a generic launch route, and several UX polish items. Backwards-compatible under `targetSdkVersion: '0.x'`.
### `BasedNotifications` namespace (new)
```ts
based.notifications.show({
title: "Pull complete",
body: "You pulled a holographic Charizard!",
deepLink: "basedapp://miniapp//pulls/123",
data: { pullId: "123" },
});
```
Local system banner. Title is auto-prefixed `[]` ; icon comes from the manifest registry. Both enforced server-side — partners can't override. Deep link gated against `permissions.deepLinks`.
New permission **`notifications.local`**. Spec'd in [`03-host-contract.md`](/docs/integrations/mini-apps-platform/03-host-contract.md#basednotifications--local-system-notifications) and [`15-notifications.md`](/docs/integrations/mini-apps-platform/15-notifications.md).
### `BasedLiveActivity` namespace (new)
```ts
const { activityId } = await based.liveActivity.start({
template: "progress",
title: "Deposit pending",
state: { stages: ["Pending","Confirming","Completed"], currentStage: 0, progress: 0 },
});
await based.liveActivity.update(activityId, { /* updated state */ });
await based.liveActivity.end(activityId);
```
iOS Live Activities (lock-screen + Dynamic Island) and Android Live Updates (progress notifications). Three templates compiled into the host: `progress`, `status`, `countdown`. Partners pick a template + supply state; they cannot ship layout code.
Background updates flow via the partner backend hitting the gateway — the host registers the iOS push-to-LA token and the Android FCM token with the gateway on the user's behalf, so partners never see tokens.
New permission **`liveActivity`**.
### Partner notification API (server-to-server)
`POST /api/partners/notifications/push` and three Live Activity endpoints (`POST` / `PATCH` / `DELETE /api/partners/live-activities/{id}`) on `app.based.one`. Authenticated by an `mp_<32-hex>` partner API key minted via the admin UI.
* Recipients by email or wallet (≤1000 each).
* Title auto-prefixed `[]`.
* Tenant-scoped — Based partners can't push to Hyena users.
* Sliding-window rate limit (60/min, 10k/day defaults; tunable per partner).
* Idempotency-Key dedupe within 24h.
* Audit log (`MiniAppPushLog`) on every send.
Full reference in [`17-partner-api.md`](/docs/integrations/mini-apps-platform/17-partner-api.md).
### Generic mini-app launch route (replaces hardcoded routes)
Hardcoded `/dev/mini-apps/` GoRoutes are gone. One generic route now handles every launch:
```
/mini-apps/launch?manifest=
```
`MiniAppScreen.fromUrl` fetches the manifest, derives the bundle URL by joining `manifest.entry` against the manifest URL, then boots the runtime. Whitelisted launches go through the home- screen carousel; arbitrary launches via the "Open by URL" sheet under the carousel header.
### Home-screen mini-apps carousel + "Open by URL"
New section above the More grid on the home screen. Tappable cards for whitelisted partners (Pull.Fun, AI Assistant initially); an "Open by URL" header action opens a paste-and-launch sheet for partner devs. The whitelist lives in `mini_app_registry.dart`; Phase 5's signed-registry rollout swaps the const list for a fetched + signed payload without changing the consumer shape.
### Auto-hiding drag-to-dismiss grabber
Every mini-app gets a 40×4pt iOS-style grabber painted in the status-bar inset gutter. Visible 2.5s after mount, fades out, re-fades back on touch. Three dismiss paths: tap the grabber, swipe down on the top band, or call `based.nav.close()` from inside the bundle. Replaces the floating ✕ button from earlier prototypes (which occluded partner toolbars).
### Android Google OAuth fix
`AndroidManifest.xml` now declares `com.linusu.flutter_web_auth_2.CallbackActivity` scoped to `basedapp://miniapp/*` so Chrome Custom Tabs can route OAuth redirects back into the app. Without it, Pull.Fun's Google sign- in tab opened, the user signed in, and the redirect landed nowhere. iOS unaffected (ASWebAuthenticationSession intercepts redirects natively).
### Bottom-nav padding (platform-aware)
`BasedBottomNavBar` now clamps the iOS home-indicator inset to 12pt (the indicator is decorative; no need for a 34pt gutter) but honours the full Android system-nav inset (gesture handle / 3-button bar is interactive UI we have to clear). Fixes the "labels render under the system buttons" bug on Android.
### `Image.color` SVG tint
The renderer's `Image` widget now accepts a `color` prop. Monochrome SVGs (e.g. Lucide icons) are tinted via `BlendMode.srcIn`. Used by the AI Assistant's hamburger menu / compose icon in the chat toolbar.
### iOS WidgetExtension target (host build)
The host's iOS project now ships a `MiniAppLiveActivityExtension` target (`ios/MiniAppLiveActivity/`) containing the three templates' SwiftUI views, shared `ActivityAttributes`, and a `MethodChannel` handler. Partners don't touch this code; setup is documented in `ios/MiniAppLiveActivity/README.md` for host engineers adding the target via Xcode.
## How partners track changes
* This file is the canonical source. The Docusaurus site (`docs/mini-apps-site/`) renders this as `Changelog`.
* Each minor release links to a migration page describing additive API surface and any new permissions.
* Major releases come with a per-major migration guide and a 2-quarter deprecation window for the methods being removed.