portal-mojo 0.1.0

package/docs/charts.md

@@ -0,0 +1,303 @@
+# charts — dependency-free SVG
+
+```ts
+import {
+    SeriesChart, MetricsChart, MiniChart, MetricsMiniWidget,
+    KPITile, KPIStrip, CircularProgress, PieChart,
+    showSeriesStats, showSeriesData, exportChartPng,
+    computeSeriesStats, computeTrend, deltaBadge,   // pure math
+} from 'portal-mojo/charts';
+```
+
+No chart library — web-mojo's SVG charts ported whole; they match the
+design tokens in both themes. Demos: Develop → Components → Display.
+
+## The metrics wire (all metrics-driven components speak it)
+
+`GET /api/metrics/fetch` params:
+
+| param | meaning |
+|---|---|
+| `slugs` | comma list, **REQUIRED** (the server 400s without; singular `slug` exists but never send it — prod once rejected it) |
+| `granularity` | `minutes/hours/days/weeks/months` (server default `hours`) |
+| `account` | `'public'` (server default) / `'global'` / `'group-<id>'` / `'user-<id>'` — components default to `'global'` (web-mojo parity) |
+| `dt_start` / `dt_end` | window bounds, **epoch SECONDS** (rule 6) |
+| `category` | optional category passthrough via `apiParams` |
+| `child_kind`, `breakdown` | typed `MetricsChart` fan-out props (`childKind`, `breakdown`) |
+
+Response is a slug-keyed map `{data: {slug: number[]}, labels: string[]}` —
+normalized ONLY by `mojoMetrics` in the client into `{labels, datasets}`.
+Malformed feeds degrade to the empty state WITH a console.warn — never a
+crash.
+
+**Two windowing params ride together, deliberately:** the real backend uses
+`dt_*` and ignores `range`; components send both for quick ranges and only
+`dt_*` for custom ranges. The mock now gives `dt_start`/`dt_end` precedence,
+accepts either bound alone, and mirrors the backend's inclusive buckets.
+Reverse ranges return an empty series; malformed non-epoch bounds reject.
+Month/year buckets advance by calendar boundaries, not 30/365-day arithmetic.
+The mock caps a pathological request at 400 buckets to keep the showcase
+responsive. It also salts values by `account` so entity-scope demos visibly
+change; that salt is a mock-only presentation affordance, not a server promise.
+
+**Trap (fixed here, do not regress):** `dr_start/dr_end` is the model-LIST
+daterange triple — `/api/metrics/fetch` ignores it silently. web-mojo sent
+`dr_*` to metrics for years; its custom ranges never reached the backend.
+
+## SeriesChart (presentational)
+
+```tsx
+<SeriesChart
+    labels={['Mon', 'Tue']}
+    datasets={[{ label: 'API Calls', data: [420, 380] }]}
+    chartType="line"        // 'line' | 'bar' | 'area'
+    stacked="auto"          // bars stack by default
+    height={240}
+    showLegend showGrid showXLabels showYLabels
+    valueFormatter={(n) => ...}
+/>
+```
+
+Legend entries toggle series; hover shows the crosshair index tooltip;
+ticks are "nice"-rounded; container width is measured (no viewBox
+smearing).
+
+## MetricsChart (the django-mojo metrics widget)
+
+```tsx
+<MetricsChart
+    title="Platform activity"
+    slugs={['api_calls', 'user_activity_day', 'api_errors']}
+    seriesLabels={{ api_calls: 'API Calls' }}   // wire carries raw slugs
+    account="global"
+    defaultRange="24h"                          // 1H / 24H / 7D / 30D
+    defaultGranularity="hours"                  // gated per range (MIN HR DAY WK MO)
+    defaultType="line"
+    height={280}
+    valueFormatter={(n) => ...}                 // tooltips, ticks, dialogs
+    childKind="store" breakdown={false}         // typed fan-out; overwrites apiParams
+    loadSeries={exactLoader}                    // optional; default is mojoMetrics
+    seriesCacheKey="caller-42:exact-history"   // required stable namespace for custom loaders
+    preserveSeriesLabels                       // keep full-slug/child identity verbatim
+    allowedGranularities={['minutes','hours','days']} // optional backend subset; unsupported controls omitted
+    refreshSignal={refreshVersion}              // changed by a parent refresh owner; exactly one fetch
+    // toggles, all default true:
+    showGranularity showDateRange showTypeSwitch showRefresh showStats showDataTable
+/>
+```
+
+- **Stats (ⓘ)** — per-series Latest/Min/Max/Avg/Median/Sum dialog.
+  **View data (table)** — the series as a table + Download CSV. Both are
+  native `<dialog>`s via the modal manager; both render the DISPLAY names
+  (`seriesLabels`-mapped).
+- **Custom range** — the calendar button in the range segment opens a
+  DateRangePicker (presets rail) dialog with an explicit Apply. An applied
+  range shows as a chip beside the title, sends `dt_start/dt_end` (local
+  day bounds 00:00:00–23:59:59 → epoch seconds), and re-points granularity
+  at a bucket that fits the span (`granularitiesForSpanMs`).
+- Quick ranges anchor their window at pick time; **Refresh re-anchors at
+  now** (web-mojo kept the stale window — deliberate fix). A quick-window
+  refresh changes the query key and does not also call `refetch`, preventing
+  the former duplicate request. `refreshSignal` follows the same one-request
+  path for a parent-owned refresh control. Range switches
+  re-point granularity at the nearest sensible bucket.
+- `allowedGranularities` additively narrows the control vocabulary for a
+  backend such as CloudWatch. Values outside the supported subset are not
+  rendered; normal metrics callers retain all five granularities.
+- `loadSeries(params)` receives typed `slugs`, `account`, `granularity`,
+  `dt_start`, `dt_end`, and optional fan-out fields. The loader namespace is
+  part of the TanStack key, preventing a custom exact-identity loader from
+  reusing a cached default response with the same wire params.
+- The default loader remaps live tail-only response keys back to configured
+  full slugs when that mapping is unique. Duplicate tails remain an explicit
+  error and require an exact loader that can split/reassemble requests.
+- CSV data export neutralizes formula-looking **string** cells before RFC
+  quoting. Negative numeric metrics remain numeric.
+- Deliberately NOT carried: `compactHeader` (MetricsMiniWidget IS the
+  compact card), `.export()` (removed in web-mojo too — use
+  `exportChartPng`), `withDelta` endpoint switching (KPIStrip covers the
+  KPI use-case).
+
+## MiniChart (sparkline primitive)
+
+```tsx
+<MiniChart data={[4, 9, 6]} labels={['Mon','Tue','Wed']} chartType="line"
+    height={48} color="var(--accent)" fill smoothing={0.3}
+    showTooltip showCrosshair showXAxis={false}
+    minValue={} maxValue={} softMin={} softMax={} />
+```
+
+Single series, line or bar. Hard crops (`minValue/maxValue`) win over bar
+soft bounds (`softMin/softMax` — normalize-to targets that expand if data
+exceeds). Bars always include zero; the x-axis sits at zero when data
+crosses it. All-zero bar data renders the dashed "alive, just zero"
+baseline instead of blank. Draw-in animation is pathLength-normalized CSS
+(no measuring); `prefers-reduced-motion` kills it. Colors accept `var()`
+tokens — the default fill is the stroke at 0.12 opacity, so one token
+drives both.
+
+## MetricsMiniWidget (compact card + entity search)
+
+```tsx
+<MetricsMiniWidget
+    title="Logins" icon="bi bi-box-arrow-in-right"
+    slugs={['user_activity_day']}          // FIRST slug drives the card
+    granularity="hours" defaultRange="24h" chartType="line"
+    subtitle={(ctx) => <><b>{ctx.total}</b> in 24h · {ctx.nowLabel}: {ctx.nowValue}</>}
+    showTrending trendRange={6}
+    tone="accent"                          // token-tinted card variant
+    showSettings showDateRange settingsKey="dash-activity"
+    search={{                              // the C2 addition
+        model: GroupModel,                 // or endpoint: '/api/group'
+        toAccount: (id) => `group-${id}`,  // picked row → account param
+        placeholder: 'All groups (global)',
+    }}
+    onScopeChange={(account, row) => ...}
+/>
+```
+
+- **Entity search**: a CollectionSelect bound to any model list — shared
+  cache keys, NEVER a parallel fetch path. Picking a record re-fetches
+  with `account=toAccount(id, row)`; clearing returns to the base
+  `account` prop.
+- **subtitle** is a ReactNode or `(ctx) => ReactNode`; `ctx` is the typed
+  twin of web-mojo's Mustache tokens: `{total, nowValue, lastValue,
+  prevValue, trendingPercent, nowLabel, totalLabel, granularity}`
+  (`nowValue` is ALWAYS the latest bucket; `lastValue` is the
+  offset-shifted trend-window sum — source distinction preserved).
+- **Trending** is the source's windowed math (`computeTrend`):
+  `trendRange` (k = floor(range/2) buckets per window), `trendOffset`
+  (skip trailing partial buckets), `prevTrendOffset` (compare N earlier).
+  Up renders green / down red (source parity — no tone flip here; KPITile
+  has `tone`).
+- **Settings** (gear, off by default): granularity / chart type / date
+  range dialog; persisted under localStorage `metrics-chart-<settingsKey>`
+  (source key format). A granularity change with a custom window in play
+  auto-adjusts the window (hours→24h … years→5y, source table); it never
+  sets dates for the first time.
+- `defaultRange={null}` omits window params entirely (backend default
+  window — the source MiniChart's behavior when no range was given).
+- Card is single-series by design (source parity); extra slugs still feed
+  the stats/view-data dialogs. A response without the first slug warns
+  once and shows the empty state.
+
+## KPITile + KPIStrip
+
+```tsx
+<KPIStrip
+    tiles={[
+        { slug: 'api_calls', label: 'API Calls', tone: 'good' },
+        { slug: 'api_errors', label: 'API errors', tone: 'bad', severity: 'warn' },
+        { key: 'open', label: 'Open Tickets', value: openCount, sparklineSlug: 'api_calls' },
+    ]}
+    granularity="days" range="7d" account="global"
+    onTileClick={({ slug, key }) => ...}
+/>
+```
+
+ONE batched `/api/metrics/fetch` covers values, deltas and sparklines:
+value = latest bucket, delta = latest − previous, `deltaPct` omitted when
+the previous bucket was 0 — the same convention
+`/api/metrics/series?with_delta=true` uses, so a server-delta variant is a
+drop-in later. A spec with `value` set is a caller-value tile (the
+source's REST-count tiles — pages already have `size:0` count queries);
+`sparklineSlug` lets it borrow a metric trail + delta. Missing slugs warn
+once and render '—'.
+
+`KPITile` alone is pure presentation: `label`, `value`, `delta`,
+`deltaPct`, `tone` ('bad' = rising is bad), `severity`
+(critical/high/warn/info/good left stripe; high shares the warn token —
+no orange in the palette), `sparkline`, `onClick`, `loading`. Badge rules
+(source verbatim, via `deltaBadge`): finite pct → `+12%` (one decimal
+under 10), else absolute delta → `+4`, else no badge; ±0 renders flat.
+**Never Infinity%.**
+
+## CircularProgress
+
+```tsx
+<CircularProgress value={64} size="md" />                       // xs sm md lg xl | px
+<CircularProgress value={64} gap={90} rotation={135} />         // gauge
+<CircularProgress value={7} max={10} valueFormat="fraction" />  // 7/10
+<CircularProgress segments={[{ value: 38, color: 'var(--accent)' }, ...]} max={100} />
+<CircularProgress gradientColors={['var(--accent)', 'var(--ok)']} />
+```
+
+Ring progress with size presets (stroke auto-scales), variants mapped to
+tokens (`success/danger/warning/info` → ok/bad/warn/info), partial-arc
+gauges, rounded caps, center value (`percentage | fraction | value` or a
+`valueFormatter(value, min, max)`), `label`, `icon`, and multi-segment
+mode with `segmentGap` degrees. Value changes glide via the CSS
+dash-offset transition (the imperative `animateTo/pulse` API from the
+source is just… setting the prop). Dropped from source: the Bootstrap
+popover tooltip (pass `title` or wrap it) and the hardcoded 'dark'/'light'
+theme presets (tokens make them meaningless).
+
+## PieChart
+
+```tsx
+<PieChart data={[{ label: 'Chrome', value: 61, color: 'var(--info)' }]} />  // shape 1
+<PieChart data={{ labels: ['a'], datasets: [{ data: [1] }] }} />            // shape 2 (Chart.js)
+<PieChart data={{ US: 42, DE: 21 }} />                                      // shape 3 (map)
+<PieChart endpoint="/api/some/summary" params={{ days: 7 }} />              // fetched
+<PieChart data={d} cutout={0.62}
+    centerLabel={(ctx) => ctx.total.toLocaleString()} centerSubLabel="users" />
+```
+
+Native SVG pie/doughnut. All three web-mojo input shapes; unknown shapes
+warn + empty state. Colors: per-item `color` → `colors[i]` (default
+CHART_PALETTE) → `colorGenerator(i)` (default golden angle — distinct hues
+forever). `legendPosition` right/bottom/none; `showLabels` puts labels at
+the slice edges; tooltip clamps inside the svg area; `onSliceClick` gets
+`{label, value, pct, index}`. Data changes tween label-keyed (existing
+slices slide, new ones grow from a 0-arc; rAF, cancelled on unmount).
+Center labels are strings (SVG `<text>` — not a ReactNode slot). The
+single-full-circle case renders a circle element (SVG arcs can't draw
+360°). `endpoint` fetches through `mojoCall` (the one boundary) with the
+source's `data.data ?? data` nesting heuristic; fetch errors warn + empty.
+Pure helpers (`parsePieInput`, `buildPieGeometry`, `goldenAngleColor`,
+`interpolateSegments`, `arcPath`) are exported from `pie-math`.
+
+## Stats + view-data dialogs (shared)
+
+```ts
+showSeriesStats({ title, labels, datasets, granularity, formatter });
+showSeriesData({ title, labels, datasets, granularity, formatter });  // + Download CSV
+```
+
+Awaitable native-`<dialog>`s (modal manager). Stats: per-series
+Latest/Min/Max/Avg/Median/Sum with the "Hourly · N points" header. Data:
+one row per label, one column per series; CSV downloads as
+`<title-slug>-<date>.csv` (RFC-safe quoting via `buildCsv`). Empty data
+renders "No data to display." — never a blank dialog.
+
+## exportChartPng
+
+```ts
+exportChartPng(refOrElement, { filename: 'chart.png', background: null, scale: 2 });
+```
+
+Framework-free SVG→PNG: finds the `<svg>` in the target (element or ref),
+clones it, **inlines computed styles** (token-driven fills/strokes/fonts
+would otherwise vanish — theme classes don't serialize), rasterizes at
+`scale` (default 2) over the nearest ancestor's real background (dark
+exports stay dark; pass a color or `null` for transparent), and downloads.
+⚠️ Tainted-canvas caveat (from the source, still true): an SVG referencing
+cross-origin resources (external `<image href>`, remote fonts) taints the
+canvas and `toDataURL` throws a SecurityError. These charts reference
+none; inline such resources before exporting anything that does.
+
+## Pure math (headless-tested)
+
+`computeSeriesStats`, `defaultStatFormat`, `computeTrend`, `deltaBadge`,
+`buildCsv`/`csvEscape`/`csvFilename`, `quickRangeWindow`,
+`granularitiesForSpanMs`, `ymdRangeToEpochSeconds`, `toNumber` — all in
+`charts/stats.ts`, no DOM/React, shared by every surface above (web-mojo
+carried two diverging copies of the stats math; here there is one).
+
+## WorldMap
+
+`portal-mojo/charts` also exports `WorldMap` — the dependency-free geo map
+(markers, routes, drill-down, the country centroid table) plus its projection
+math. It has its own page: **[worldmap.md](worldmap.md)**. Note that
+`charts/pie-math` exports `arcPath` and the map's arc helper is therefore
+`geoArcPath`.

package/docs/client.md

@@ -0,0 +1,206 @@
+# client — the typed django-mojo protocol layer
+
+```ts
+import {
+    mojoList, mojoGet, mojoSave, mojoDelete, mojoDownload, mojoMetrics,
+    mojoCall, mojoQueryDefaults, usingMockTransport, apiOrigin,
+    MojoError, AuthRequiredError,
+} from 'portal-mojo/client';
+```
+
+## Transport
+
+- `VITE_MOJO_API` unset → the in-memory mock answers every call
+  (`npm run dev`). Set to a django-mojo origin → real backend
+  (`npm run dev:live`, configured in `apps/portal/.env.live`).
+- Every request carries `X-Mojo-UID` (device id) and, once `initAuth()` ran
+  and a session exists, `Authorization: Bearer <jwt>`.
+- CORS note (dev, cross-origin): every request shows an `OPTIONS` preflight
+  twin in devtools. Not a duplicate fetch.
+
+## Envelope — the ONE unwrap boundary
+
+django-mojo wraps everything: `{status, data, …}`. `status: false` (or a
+non-2xx with an envelope body) becomes a **thrown `MojoError(message,
+status, errorCode, data)`** carrying the server's real message, numeric HTTP
+status, semantic `error_code`, and structured safe failure evidence. Nothing outside `client.ts`
+parses envelopes; `mojoCall(path, {method, params, body})` is the typed
+escape hatch for protocol modules and returns the unwrapped `Envelope`.
+
+Live non-2xx responses and mock `status:false` envelopes preserve the same
+shape. Modern envelopes use numeric top-level `code` plus a string semantic
+`error_code`; numeric legacy `error_code` remains a status fallback. Failed
+envelopes always reject. Structured `data` can contain deliberately safe
+recovery evidence, but callers must still avoid logging it indiscriminately.
+
+## Functions
+
+| Fn | Wire | Returns |
+|---|---|---|
+| `mojoList<T>(endpoint, params)` | `GET endpoint?start&size&sort&search&<lookups>` | `{rows: T[], count, start, size}` |
+| `mojoGet<T>(endpoint, id)` | `GET endpoint/<id>` | `T` |
+| `mojoSave<T>(endpoint, id\|null, changes)` | `POST endpoint[/<id>]` | `T` (server-authoritative row). REJECTS on failure |
+| `mojoDelete(endpoint, id)` | `DELETE endpoint/<id>` | `void` — server answers `{status:"deleted"}` (string; deliberate) |
+| `mojoDownload(endpoint, params, 'csv'\|'json')` | `GET endpoint?download_format&filename&<filters>` (start/size stripped) | triggers a browser download of the WHOLE filtered set |
+| `mojoMetrics(params)` | `GET /api/metrics/fetch?slugs&range&granularity` | `{labels, datasets:[{label: slug, data}]}` — normalized from the wire's `{data:{slug: number[]}, labels}` |
+
+Wire facts (measured against live django-mojo): list sort is `'-field'`
+desc; filters are Django lookups (`field`, `field__in=a,b`,
+`field__icontains`, `field__gte`, `field__isnull=true`); the daterange
+triple is `dr_field/dr_start/dr_end`; datetimes serialize as epoch seconds;
+unknown params are silently ignored by the server.
+
+The executable mock coerces comparisons narrowly: both operands must be
+fully numeric for numeric comparison; temporal comparison only recognizes
+canonical `YYYY[-MM[-DD]]` or full ISO datetime shapes; everything else is
+text. This keeps numeric IDs (`10 > 2`) and `User.dob` DateFields correct
+without turning arbitrary date-looking labels into timestamps. The showcase
+Filters demo exercises both `dob__gte=YYYY-MM-DD` and epoch-backed `dr_*`.
+
+Mock-only contract controls are exported in development: call
+`armMockReauth(method, path)` to make one authenticated method+path match
+answer 440. Ordinary requests and real transports are unaffected.
+
+## Mock admin contracts
+
+The mock carries measured GroupView/admin transports, not UI-shaped
+shortcuts:
+
+- group API keys use `/api/group/apikey`; ordinary/default rows omit the raw
+  token, create returns it, and only explicit `graph=token` reads it later;
+- webhook subscriptions validate HTTPS URLs, reject URL credentials, and
+  keep metadata detail-only; `/api/group/webhook_secret` is the deliberate
+  read/rotate secret endpoint;
+- member invites stamp the requested group and member edits preserve the
+  backend permission-dict behavior; group incident rows filter through
+  `/api/incident/event?group_id=`;
+- `/api/auth/config` resolves defaults → deployment → root → child, replaces
+  lists, preserves nested dict keys, ignores unknown/inactive UUIDs, and
+  returns only the public whitelist;
+- settings keep plaintext for secret rows in a private mock slot, while every
+  wire response carries `value:''` + `display_value:'******'`. Payload order
+  deliberately mirrors live `set_value`: serialize `is_secret` before
+  `value`. Non-null group scopes enforce `(key, group)` uniqueness; repeated
+  global `(key, null)` rows remain possible because PostgreSQL NULL uniqueness
+  does. REST delete is denied;
+- metrics permissions are top-level `/api/metrics/permissions` responses, not
+  model envelopes. Single permission reads may be strings, multiple are
+  lists, and cleared values read as null. Clearing/deleting retains the
+  account row in the list, matching the separate Redis account index.
+
+Stable mock permission identities (password `mojo`) make gates reproducible:
+`ian@mojoverify.com` is only an odd-group admin;
+`security.viewer@nativemojo.com` has global security/geofence view;
+`security.manager@nativemojo.com` has security/geofence/settings/metrics
+management; `groups.manager@nativemojo.com` has global groups/users
+management. `/api/geo/check?__mock_country=CN` is the deterministic public
+deny case; the default US case allows.
+
+The record-feed mock follows the shared Django feed shape rather than a
+component-specific adapter. `/api/incident/ticket/note` and
+`/api/incident/incident/history` return the newest 100 rows, support parent
+and group filtering, and explicitly use `graph=default`. Posts reject unknown
+parents, inherit the parent's group, stamp the authenticated user, embed that
+user in the response, and keep `media` null.
+
+Bouncer operator data is available to the stable global security identities:
+signals and devices provide seeded list/detail graphs, while bot signatures
+exercise create, update, uniqueness validation, and enable/disable; DELETE
+matches the live endpoint's denial. The security
+viewer is read-only; the security manager can mutate supported resources.
+Signal detail deliberately omits `token_nonce`: it is neither needed by the
+admin portal nor safe to type, store, or cache as operator-facing data. Block
+and monitor decisions are also seeded into the incident-event feed. The
+read-only `/api/incident/incident` mock follows the real reporter contract:
+Bouncer device investigations filter the security category and search the
+incident details for the device MUID, without invented model linkage.
+
+The mock-only component showcase signs in as
+`showcase.operator@nativemojo.com`, an explicit broad demo identity. The
+narrow `security.viewer`, `security.manager`, `groups.manager`, and Ian
+fixtures remain unchanged for permission-boundary verification.
+
+Communications mock parity includes `/api/aws/email/{domain,mailbox,sent,template,send}`
+and `/api/account/public_message`. Credential plaintext is reduced to masks
+and discarded, managed onboarding writes through the registered DNS adapter,
+audit persists domain status, send may return a 2xx `failed` row, and mailbox
+and domain deletes reproduce local audit cascades. Stable email/support
+operator identities are listed in [admin-messaging.md](admin-messaging.md).
+
+DNSMan's mock contract is central-state-backed and capability-first. Stable
+identities `dns.viewer@nativemojo.com`, `dns.manager@nativemojo.com`, the
+group-1-only member `dns.tenant@nativemojo.com`, and the house-only superuser
+`dns.platform@nativemojo.com` (password `mojo`) exercise the exact global
+view/manage, tenant, and platform split. Credential
+assignment searches only `/api/dnsman/credential/group-choice`; an exact
+selection hydrates with `?id=…`, and inactive or over-depth groups never
+appear. First-link verification failure creates no row. Failed rotation marks
+the existing row unverified while retaining its old masks. Successful raw
+keys are used only by the imperative call and are never stored in mock state
+or returned. Registrar confirmation tokens, legal-contact PII, WHOIS PII, and
+certificate material likewise stay outside model/query state.
+
+## Imperative file uploads
+
+`startFileUpload(file, options?)` implements django-mojo's three stages:
+initiate the File, transfer bytes to the returned capability, then reconcile
+and mark the File completed. It returns a `FileUploadTask` immediately; its
+`result` always resolves to a fixed `completed`, `failed`, or `uncertain`
+outcome.
+
+```ts
+const task = startFileUpload(file, { fileManagerId: 12, groupId: 4, use: 'attachments' });
+const unsubscribe = task.subscribe(({ phase, loadedBytes, totalBytes }) => {
+    console.log(phase, loadedBytes, totalBytes);
+});
+const outcome = await task.result;
+unsubscribe();
+```
+
+Progress is the count reported by the actual byte transport. Multipart POST
+progress therefore includes wire overhead. Provider fields are appended
+before `file`, and the browser owns the multipart boundary. The #1485 response
+keeps `upload_url`, `method`, `fields`, and `headers` flat beside the safe File
+lifecycle fields. PUT and POST are supported only. The server-echoed MIME type
+governs the byte request.
+Root-relative direct-upload paths missing the deployment's `/api` prefix are
+repaired before transfer. API Bearer and DUID headers are never forwarded;
+an unsafe backend-provided Bearer transfer header produces only a fixed safe
+outcome.
+
+Snapshots and outcomes never contain capability URLs, provider fields or
+headers, API bearer/DUID values, raw response bodies, or File URLs. A completed
+outcome exposes only an `UploadedFileRef`: authoritative id, name, MIME, size,
+category, manager id, and group id.
+
+Every task generates one private strict `idempotency_key`. `cancel()` aborts
+current work. Even an initiation abort is `uncertain` with a
+nullable File id: the server may have committed before the response became
+observable. `recover()` cannot act without an id and returns the same outcome;
+calling `retry()` replays the same key so a committed-but-lost initiation
+returns the same File. Cancellation after a known initiation, dropped provider responses,
+and ambiguous completion responses are likewise `uncertain`, since remote
+bytes or a completed File may already exist. `recover()` reconciles and
+attempts completion without replaying bytes. `retry()` reconciles first and
+replays the retained private capability only while the File is still
+uploading. If reconciliation proves failed/expired, that same Retry rotates to
+a fresh key and attempt; completed replays need no target. Both are single-flight and generation guarded. A successful
+completion POST is never authoritative by itself; a following File GET must
+confirm `completed` before the task returns success. Completed scalar
+`file_manager_id` and `group_id` must match an explicitly selected destination.
+
+## `mojoQueryDefaults()`
+
+Spread into the app's `QueryClient` defaults. Provides: no retry on 4xx
+`MojoError`s (deterministic failures), `networkMode: 'always'` under the
+mock ('online' live), and `refetchOnWindowFocus: false` (freshness comes
+from explicit refresh + opt-in autoRefresh — focus storms read as phantom
+fetches).
+
+## Errors
+
+- `MojoError{message, status, errorCode, data}` — server-reported failure;
+  `message` is the server's text, `status` is numeric, `errorCode` preserves
+  the semantic wire code, and `data` preserves safe structured evidence.
+- `AuthRequiredError` — thrown by the pre-request gate when a request needs
+  a session that doesn't exist (synthetic 401; no network was touched).

package/docs/collection-multiselect.md

@@ -0,0 +1,117 @@
+# CollectionMultiSelect — server-backed multi-pick dropdown
+
+```tsx
+import { CollectionMultiSelect } from 'portal-mojo/ui';
+```
+
+A checkbox list over live model data — server search, `SELECT (n)` /
+`DESELECT (n)` with live counts, shift-click range selection — presented by
+default as a **dropdown**: a summary trigger + `<Popover>` menu sharing
+`MultiSelectDropdown`'s shell. The menu stays open while ticking; **Done**,
+Escape or an outside click closes it. `variant="panel"` keeps the
+always-visible box (web-mojo's shape) for settings-page contexts. The value
+is a **controlled id array** in both directions. Ported from web-mojo
+`CollectionMultiSelect.js`; sibling of `CollectionSelect` in the server-data
+selects family (epic #1275).
+
+```tsx
+const [ids, setIds] = useState<Array<string | number>>([]);
+
+<CollectionMultiSelect<GroupRow>
+    model={GroupModel}            // or endpoint="/api/group"
+    value={ids}
+    onChange={setIds}
+    label="Groups"
+    required
+/>
+```
+
+## Props
+
+| Prop | Behavior |
+|---|---|
+| `model` / `endpoint` | One is required. `model` is a `defineModel` def (supplies endpoint + row type); `endpoint` is the bare path. |
+| `value` / `onChange` | Controlled id array. Every toggle commits — `onChange` fires with the full next array. Ids keep their caller-side types; all comparisons are normalized (`String()`), so string vs number ids work by construction. |
+| `variant` | `'dropdown'` (default): summary trigger + Popover menu — the form-embedded presentation. `'panel'`: the always-visible box. Internals (search, counts, ranges, states) are identical. |
+| `placeholder` | Trigger text while nothing is selected (dropdown). Default `'Select...'`. |
+| `showSelectedLabels` / `maxLabelsToShow` | Trigger summary: up to `maxLabelsToShow` (default 3) comma-joined labels **when every pick's label is known** (labels accumulate from rows the control has seen — across searches), else `"N selected"`. Hydrated initial ids the control has never seen summarize as `"N selected"` — no per-id fetches, no warn. |
+| `placement` | Menu placement against the trigger. Default `'bottom-start'`. |
+| `labelField` / `valueField` | Row fields for label and id, **dot notation** reaches nested fields (`'user.email'`). Defaults `'name'` / `'id'`. A missing field warns once and falls back (label → the id; missing id → row dropped) — never renders nothing silently. |
+| `size` | VISIBLE rows before the list scrolls (max-height = `size × 42px`). Default 8. **Not the fetch size** — the wire page size defaults to 50; override it via `defaultParams: { size: 100 }`. |
+| `maxHeight` | Explicit px override for the list height. |
+| `enableSearch` | Search input above the list. **Defaults ON in the dropdown variant, OFF in the panel.** 400ms debounce (source parity — deliberately not ModelTable's 300) into the `search` wire param; trimmed; empty term drops the param. |
+| `defaultParams` | Extra wire params — a dict, or a **callback re-evaluated per render** (each fetch uses the freshest result; a changed result is a new query key → refetch). Merge order: `{size: 50} → defaultParams → group → search` (later wins). |
+| `requiresActiveGroup` | Folds the active group id in as `group`. With NO active group the fetch is **held** (empty state shows) — never an unscoped list where a scoped one was demanded. Needs a `<GroupProvider>` above; missing one warns. |
+| `ignoreIds` | Ids hidden client-side — the "already added" pattern. Compared normalized. This is the documented exception to the no-client-filtering rule; it exists so a picker can subtract rows already chosen elsewhere without a server round-trip. |
+| `renderItem` | `(row) => ReactNode` — replaces the label span; the checkbox stays component-owned. This replaces web-mojo's mustache `itemTemplate` (trusted-HTML slots end here). |
+| `isRowDisabled` | `(row) => boolean` — per-row disabled: unclickable, skipped by SELECT and by shift-click ranges. |
+| `showSelectAll` | The SELECT/DESELECT header row. Default true. |
+| `label` / `required` / `help` / `error` | Field wrapper (house `.field-label` / `.field-help` / `.field-error`; `error` replaces `help`). |
+| `disabled` | Whole control: trigger, search, buttons, every row. |
+| `id` | id for the trigger button (a `<label for>` can point at it). |
+
+## Selection semantics (the contract)
+
+- **Selection is an id set, never row references** — it survives searches,
+  refetches and paging of the visible list. Picking under one search term
+  and then searching another keeps the first picks in `value`.
+- **SELECT (n)**: n = visible rows that are enabled and not yet selected.
+  Clicking it ADDS those ids to the value (**union** — deliberate fix over
+  the source, which replaced the value and dropped off-screen selections).
+  Disabled rows are skipped. Disabled at n = 0.
+- **DESELECT (n)**: n = `value.length` — the WHOLE selection, including ids
+  not on screen under the current search. Clicking it clears the entire
+  value (source parity: it is the "empty the value" affordance). Disabled
+  at 0.
+- **Shift-click range**: anchor = the last clicked row's index; the clicked
+  row's NEW state applies across the span; disabled rows skipped; the
+  anchor moves to the clicked row afterwards. The anchor resets whenever
+  the row set changes (new data / `ignoreIds` change) — stale indices into
+  a replaced list are meaningless (the source kept them and could walk off
+  the array).
+- Counts render only when > 0 (`SELECT`, not `SELECT (0)`) — source parity.
+
+## Wire contract
+
+One GET to the list endpoint through `useModelList`, so the cache key is the
+shared `[endpoint, params]` — this picker, `ModelTable` and model hooks read
+one cache and one invalidation root (`[endpoint]`). There is no parallel
+fetch path; `model.invalidate(qc)` refreshes open pickers too.
+
+Params sent: `size: 50` (default page size) merged with `defaultParams`,
+plus `group` (when `requiresActiveGroup`) and `search` (when searching).
+Sorting is the server's default unless `defaultParams` carries `sort`.
+
+## Invariants
+
+1. Controlled value, one pipeline: the checkboxes can never display a state
+   `value` doesn't hold (the visual checkbox is `pointer-events: none`; all
+   interaction — including `shiftKey` — lands on the row element).
+2. Every id comparison goes through one `String()` normalization. Never
+   compare raw ids anywhere in or around this component.
+3. Rows the server returns are shown as-is except the `ignoreIds` subtraction
+   — every other narrowing (kind, group, search…) must be a wire param.
+4. Loading shows skeleton rows (house silhouette) whenever the current key's
+   rows aren't on screen yet — cold load AND search/param changes. Empty is
+   `"No items available"`; fetch errors show the server's message + Retry.
+
+## Pitfalls
+
+- `size` is visible rows, not the fetch size. A list of 300 candidates with
+  the default wire size shows only the first 50 — raise it via
+  `defaultParams: { size: 300 }` (or make the user search; search is server-side).
+- The legacy `excludeIds` option is **not ported**: despite its "server-side
+  filtering" comment it was a second client-side filter identical to
+  `ignoreIds` (web-mojo filtered both in `buildItems`). Use `ignoreIds`.
+- DESELECT clears ids that are hidden by `ignoreIds` or the current search
+  too — it empties the value, not the visible page.
+- An inline `defaultParams` object/callback re-evaluates per render; that is
+  fine (TanStack hashes keys structurally — equal content, same key). Only a
+  changed RESULT refetches.
+- `requiresActiveGroup` holds the fetch until a group is active; pair the
+  control with `RequiresGroup` or group-scoped screens so users aren't shown
+  a permanently empty picker in global context.
+- The dropdown's trigger/footer classes (`.multiselect-trigger`,
+  `.multiselect-footer`, `.multiselect-done`) live in
+  `multiselect-dropdown.css` — consuming apps must import it alongside
+  `collection-multiselect.css` (the reference `theme.css` imports both).