docs: track the design specs and implementation plans in docs/superpowers

Author: azhukaudev

.gitignore

@@ -50,5 +50,3 @@ Thumbs.db
 .claude/worktrees
 .nx/polygraph
 .nx/self-healing
-# Local AI working docs
-docs/superpowers/

docs/superpowers/plans/2026-06-10-ssr-hydration.md

@@ -0,0 +1,156 @@
+# SSR / Hydration Support Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** `injectQuery`/`injectQueries` fetch real data during Angular SSR, transfer it via `TransferState`, and seed hydrated clients with it; every helper is SSR-safe.
+
+**Architecture:** On the server platform the `ConvexClient` is created `disabled: true` (no WebSocket); a `ConvexServerQueryLoader` runs one-shot queries over `ConvexHttpClient` inside `PendingTasks` and writes results to `TransferState`. On the browser, `ConvexHydrationState` seeds helpers from `TransferState` until `ApplicationRef.whenStable()`. See spec: `docs/superpowers/specs/2026-06-10-ssr-hydration-design.md`.
+
+**Tech Stack:** Angular 21 (`TransferState`, `PendingTasks`, `isPlatformServer`), convex `ConvexHttpClient`, `convexToJson`/`jsonToConvex`, Jest + jest-preset-angular.
+
+---
+
+### Task 0: Branch
+
+- [ ] `git checkout -b feat/ssr-hydration` in `convex-angular/`.
+
+### Task 1: State transfer utilities + hydration service
+
+**Files:**
+
+- Create: `packages/convex-angular/src/lib/ssr/state-transfer.ts`
+- Test: `packages/convex-angular/src/lib/ssr/state-transfer.spec.ts`
+- Modify: `packages/convex-angular/src/lib/providers/inject-query.ts` (extract `serializeQueryArgs` later in Task 4; the util lives in state-transfer.ts)
+
+Interfaces (locked):
+
+```ts
+export type TransferredQueryResult = { d: JsonValue } | { u: true };
+export function serializeQueryArgs(args: Record<string, Value>): string; // JSON.stringify(convexToJson(args))
+export function makeQueryStateKey(queryName: string, argsKey: string): StateKey<TransferredQueryResult>; // 'cva:' + queryName + ':' + argsKey
+export function wrapQueryResult(value: Value | undefined): TransferredQueryResult;
+export function unwrapQueryResult(t: TransferredQueryResult): Value | undefined;
+
+@Injectable()
+export class ConvexHydrationState {
+  // inject(TransferState), inject(ApplicationRef)
+  // active until first whenStable() resolution
+  consume(queryName: string, argsKey: string): { value: Value | undefined } | undefined;
+}
+```
+
+- [ ] Write failing specs: key format; wrap/unwrap round-trip for plain object, BigInt (Int64), undefined; `consume` returns `{value}` when TransferState has key; returns undefined when absent; returns undefined after `ApplicationRef.whenStable()` resolved (use TestBed + `await appRef.whenStable()`).
+- [ ] Run `nx test convex-angular --testFile=state-transfer.spec.ts` → FAIL.
+- [ ] Implement `state-transfer.ts`.
+- [ ] Tests pass. Commit `feat(ssr): add query state transfer utilities and hydration service`.
+
+### Task 2: Server query loader + provider wiring
+
+**Files:**
+
+- Create: `packages/convex-angular/src/lib/ssr/server-query-loader.ts`
+- Test: `packages/convex-angular/src/lib/ssr/server-query-loader.spec.ts`
+- Modify: `packages/convex-angular/src/lib/tokens/convex.ts`
+- Modify: `packages/convex-angular/src/index.ts` (export `ConvexSsrOptions`, `ProvideConvexOptions`)
+
+Interfaces (locked):
+
+```ts
+// tokens/convex.ts
+export interface ConvexSsrOptions {
+  fetchOnServer?: boolean;
+  authToken?: () => string | null | undefined | Promise<string | null | undefined>;
+}
+export interface ProvideConvexOptions extends ConvexClientOptions {
+  ssr?: ConvexSsrOptions;
+}
+/** @internal */ export const CONVEX_SSR_CONFIG: InjectionToken<{ url: string; ssr: ConvexSsrOptions }>;
+/** @internal */ export const CONVEX_HTTP_CLIENT: InjectionToken<Pick<ConvexHttpClient, 'query' | 'setAuth'>>; // default factory: new ConvexHttpClient(url)
+
+// server-query-loader.ts
+@Injectable()
+export class ConvexServerQueryLoader {
+  readonly enabled: boolean; // ssr.fetchOnServer !== false
+  fetch<Query extends FunctionReference<'query'>>(
+    query: Query,
+    args: FunctionArgs<Query>,
+    argsKey: string,
+  ): Promise<FunctionReturnType<Query>>;
+}
+```
+
+`provideConvex(url, options)`:
+
+- strips `ssr` from options before constructing `ConvexClient`;
+- on `isPlatformServer(PLATFORM_ID)` adds `disabled: true`;
+- provides `CONVEX_SSR_CONFIG`, `CONVEX_HTTP_CLIENT` (factory), `ConvexServerQueryLoader`, `ConvexHydrationState`.
+
+Loader behavior: dedup map keyed `queryName + ':' + argsKey` caching the promise (including rejections); auth token resolved once per instance and applied via `httpClient.setAuth(token)` when non-null; body runs inside `pendingTasks.run(...)`; on success `transferState.set(makeQueryStateKey(...), wrapQueryResult(result))`; rejection propagates to callers but never unhandled inside the pending task (catch inside, rethrow to callers from the cached promise).
+
+- [ ] Write failing specs (mock `CONVEX_HTTP_CLIENT` via TestBed provider): single fetch writes TransferState; concurrent fetch same key → one HTTP call; different args → two calls; authToken applied once before first query; query rejection → caller sees error, TransferState empty; `enabled === false` when `fetchOnServer: false`.
+- [ ] FAIL run, implement, PASS run.
+- [ ] Spec for provideConvex: on server platform client is `disabled`; `ssr` key not forwarded to client options (assert via `injectConvex().disabled` with `PLATFORM_ID: 'server'`).
+- [ ] Commit `feat(ssr): add server query loader and platform-aware provideConvex`.
+
+### Task 3: SSR-safety guards in non-query helpers
+
+**Files:**
+
+- Modify: `packages/convex-angular/src/lib/providers/inject-connection-state.ts` (disabled → static default `ConnectionState`)
+- Modify: `packages/convex-angular/src/lib/providers/inject-prewarm-query.ts` (disabled → `prewarm()` no-op)
+- Test: extend `inject-connection-state.spec.ts`, `inject-prewarm-query.spec.ts`
+
+Default state object: `{ hasInflightRequests: false, isWebSocketConnected: false, timeOfOldestInflightRequest: null, hasEverConnected: false, connectionCount: 0, connectionRetries: 0, inflightMutations: 0, inflightActions: 0 }`.
+
+- [ ] Failing specs: mock client with `disabled: true` and throwing `connectionState` → signal returns default, no subscribe call; prewarm on disabled client → no `onUpdate`, no timer.
+- [ ] Implement, PASS, commit `fix(ssr): make connection state and prewarm helpers safe on disabled clients`.
+
+### Task 4: injectQuery server fetch + hydration seeding
+
+**Files:**
+
+- Modify: `packages/convex-angular/src/lib/providers/inject-query.ts`
+- Test: extend `packages/convex-angular/src/lib/providers/inject-query.spec.ts` (new describe blocks `SSR` and `hydration`)
+
+Changes:
+
+- Replace local `serializeArgs` with `serializeQueryArgs` from `../ssr/state-transfer`.
+- `const isServer = isPlatformServer(inject(PLATFORM_ID));`
+- `const serverLoader = isServer ? inject(ConvexServerQueryLoader, { optional: true }) : null;`
+- `const hydration = !isServer ? inject(ConvexHydrationState, { optional: true }) : null;`
+- Effect, non-skip path:
+  - **server:** no subscription. If `serverLoader?.enabled`: `serverLoader.fetch(query, args, argsKey).then/catch` under generation guard → success: `data.set`, `error.set(undefined)`, `isLoading.set(false)`, `onSuccess`; failure: `error.set`, `isLoading.set(false)`, `onError`. Else: remain `pending`.
+  - **browser:** warm-cache read only when `!convex.disabled`; if no warm cache, `hydration?.consume(queryName, argsKey)` hit → `data.set(value)`, `error.set(undefined)`, `isLoading.set(false)`; subscription registered as today.
+
+- [ ] Failing specs (server platform via `{ provide: PLATFORM_ID, useValue: 'server' }`, loader mocked or real with mocked `CONVEX_HTTP_CLIENT`): success → status `'success'` + data; error → status `'error'`; `onUpdate` never called; skip works; no loader provided → stays `'pending'`; arg change mid-fetch → stale result dropped (generation guard).
+- [ ] Failing specs (browser + TransferState pre-set): instant `'success'` with transferred data before any `onUpdate`; live update overwrites; warm cache wins over transfer; after `whenStable` no seeding.
+- [ ] Implement, PASS (full file: `nx test convex-angular --testFile=inject-query.spec.ts`), commit `feat(ssr): server-side fetching and hydration seeding for injectQuery`.
+
+### Task 5: injectQueries same treatment
+
+**Files:**
+
+- Modify: `packages/convex-angular/src/lib/providers/inject-queries.ts`
+- Test: extend `inject-queries.spec.ts`
+
+Same branches as Task 4 applied per definition entry (each entry has its own argsKey, fetch, and seed). Guard `localQueryResult` behind `!convex.disabled`.
+
+- [ ] Failing specs: server fetch resolves all entries; one entry error → its `errors` record entry set, others succeed; hydration seeds entries individually.
+- [ ] Implement, PASS, commit `feat(ssr): server-side fetching and hydration seeding for injectQueries`.
+
+### Task 6: Full-suite verification + docs
+
+**Files:**
+
+- Modify: `packages/convex-angular/README.md` (new "Server-side rendering" section)
+- Modify: `packages/convex-angular/src/index.ts` (verify exports annotated `@public`)
+
+- [ ] `nx test convex-angular` → all green (290 existing + new).
+- [ ] `nx build convex-angular` → success.
+- [ ] `nx lint convex-angular` → clean.
+- [ ] README: setup snippet (`provideConvex(url, { ssr: { authToken } })` + `provideClientHydration()`), cookie/`REQUEST`-token example, per-helper SSR behavior table, note paginated queries load after hydration.
+- [ ] Commit `docs(ssr): document server-side rendering support`.
+
+### Task 7: Demo smoke (stretch, time-boxed)
+
+- [ ] Only if Tasks 1–6 complete cleanly: attempt `ng add @angular/ssr` on `apps/frontend`; if the env-var esbuild plugin conflicts, revert and leave documented as follow-up (spec lists it out of scope).