# Stryde Superapp SDK — Changelog

The platform serves this kit live at **`/sdk/stryde-superapp-sdk.zip`** and
re-bundles it on every download from `app/static/sdk/`, so the link is never
stale. Bump the `?v=` query in your `<link>` tags when a new release ships so
clients pick up the latest CSS.

The **design-system identity** (`design_system: "stryde@2"` in your
`manifest.json`, gated by `GATE.UI.DESIGN_SYSTEM`) is stable across the changes
listed below. Class names and the token surface remain backward compatible —
existing apps don't need to be rebuilt, they only need to bump `?v=` to pick
up visual refinements.

---

## stryde@2.2 — 2026-06-02 — "Notification Center + icons + canonical top bar"

This is the consolidated release after the overnight design pass and the
Notification Center rollout. Adopt it by bumping the cache-bust query on both
stylesheets:

```html
<link rel="stylesheet" href="/sdk/stryde.css?v=3" />
<link rel="stylesheet" href="/sdk/stryde-tokens.css?v=3" />
```

### New

- **Notification Center (platform capability, shell chrome).** The bell + glass
  drawer mounts automatically on every superapp surface, and a full-screen
  `/notifications` page is always available. Apps **emit** through
  `POST /v1/notifications` and the shell renders the inbox, detail, structured
  responses, comments, and audit timeline. See README "The Notification
  Center" + wiki §Notifications. New files in the kit:
  - `notifications.js` — shell-chrome bell + drawer (intentionally no-ops
    inside an app iframe to avoid double-bells).
  - `notifications-page.js` — drives the full-screen page.
  - `notifications.css` — self-contained, themed off `.dark` / `[data-theme]`,
    RTL-safe.
- **`app_key` attribution on every notification.** Every emitted notification
  carries the originating app's key so the recipient can see which app
  initiated the request, and admins can filter the notification CRUD by app.
- **Real attachment storage (S3, with local-disk fallback).** The
  `interaction: "file_upload"` and composite file controls now upload through
  `POST /v1/files` (boto3 → S3 when `S3_BUCKET` is configured; otherwise a
  local-disk fallback). Read back via presigned `GET /v1/files/{key}`.
- **Canonical top bar across every surface.** Launcher, `/wiki`, `/admin`,
  `/apps/{key}`, `/notifications` all render the same top bar (logo, app
  switcher, Cmd-K search, language, theme, your avatar, bell). The shell-mf
  host deep-links into iframed apps so Cmd-K results land inside the shell
  wrap. Apps must **not** render a top nav — that contract is enforced by
  `GATE.UI.LAYOUT` and documented in app-standards §6.2.
- **App icon system (Higgsfield-rendered).** Per-app 256px PNGs in both themes
  + hero / empty-state art, served at:
  - `/admin/icons/256/<app_key>.png` — dark theme tile chip
  - `/admin/icons/light/256/<app_key>.png` — light theme tile chip
  - `/admin/icons/heroes/<app_key>.png` — app detail hero
  - `/admin/icons/empty/<app_key>.png` — empty-state art
  Use these in your sidebars/empty states so cross-app visuals are consistent.
- **TypeScript type declarations now ship in the kit** under `types/`:
  `index.d.ts` (the full `SdkContext` API surface — auth, api, telemetry,
  i18n, theme, lookups, bus, nav, errors) and `skin.d.ts` (`applyStrydeSkin`,
  `bindIframeSkin`, `SKIN_ID`, `SKIN_VERSION`, `SKIN_HREF`).
- **CMS module ships as the reference app** — a working example of an SDK
  app: WYSIWYG editor, anchored comments, SVG callout lines, mind-map ↔ CMS
  bidirectional integration, in-doc auto-collapsing sidebar.

### Refined

- **Tokens / skin polish.** Softer ambient glow so light surfaces don't take
  on a purple tint; stopped clobbering app colour tokens (the "transparent
  cards" bug); stopped the global link colour bleeding into card text (the
  "blue cards" bug); entry HTML now `no-cache` so redeploys are picked up
  immediately while hashed assets stay long-cached.
- **Stricter gate.** `GATE.UI.DESIGN_SYSTEM` now requires both stylesheets
  (skin + tokens) AND the side-menu pattern. The plug-and-play starter
  (`/sdk/starter.html`) is the conformance proof.
- **Notification CRUD in admin console.** Notifications + responses + comments
  + preferences are now first-class admin entities (sidebar group), built on
  the generic CRUD machinery, so support can drive them like any other table.

### Fixed

- **Mutation-observer infinite loop** in `notifications.js` that froze pages
  (mountBells → paintBadge → observer → mountBells…). Added a `needsMount()`
  guard; mountBells no longer triggers paintBadge.
- **Iframe double-bell.** `notifications.js` early-returns if
  `window.top !== window.self`, so embedded shell chrome doesn't double-mount.
- **Naive timestamp under "THIS WEEK".** `_iso()` now stamps `tzinfo=UTC`
  when the DB returns a naive datetime (SQLite path) so newly created
  notifications group correctly.

### Migration notes (existing apps)

1. Bump `?v=2` → `?v=3` on both `<link>` tags in your `<head>` to pick up the
   refined CSS.
2. No manifest change needed — `design_system: "stryde@2"` is still correct.
3. If your app emits notifications, you can now pass `app_key` for proper
   attribution (the platform also infers it from your service key).
4. If you want types in your editor, point your `tsconfig.json` `paths` or
   triple-slash references at `types/index.d.ts` from this kit, or
   `npm i -D @stryde/superapp-sdk` once the package publishes (the kit `.d.ts`
   files are the same surface).

---

## stryde@2 — 2026-05-31 — "real downloadable kit"

- Authored the canonical SDK kit and the `/sdk/stryde-superapp-sdk.zip`
  endpoint that re-bundles on every download.
- Rewrote the wiki Downloads + Build sections to point at the live kit.
- Centralized the app palette into `/sdk/stryde-tokens.css` (HSL channels for
  Tailwind apps) — separate from `stryde.css` (hex tokens for the shell/wiki).
- Canonical side-menu component (`.stryde-side*`) — the only allowed app nav.
- Plug-and-play starter (`/sdk/starter.html`) — links **only** the SDK and
  renders the whole catalog; the conformance proof for new apps.
- Bumped `design_system` to `stryde@2`; the gate enforces both stylesheets
  AND the side-menu pattern.

## stryde@1 — initial

- The single-file skin (`stryde.css`) injected by the shell into every app
  iframe as the last stylesheet.
- `applyStrydeSkin` / `bindIframeSkin` runtime helpers (theme-synced).
- Base `SdkContext` surface (auth, api, telemetry, i18n, theme, lookups, bus,
  nav, errors).
- `GATE.UI.DESIGN_SYSTEM` introduced in the validation engine.