@alliance-droid/status-feedback-system 4.2.4 → 4.3.0

package/README.md

@@ -1,365 +1,367 @@
-# @alliance-droid/status-feedback-system
-
-Drop-in system status pages and user feedback components for SvelteKit apps.
-
-This package provides UI components plus an optional SvelteKit server proxy for talking to a [status-feedback-admin](https://alliance.ghe.com/alliance/status-feedback-admin) backend. The admin app handles data storage, API key management, and the admin dashboard.
-
-## Architecture
-
-```
-┌─────────────────────────┐       ┌──────────────────────────┐
-│   Your SvelteKit App    │       │  status-feedback-admin   │
-│                         │       │                          │
-│  ┌───────────────────┐  │  API  │  ┌────────────────────┐  │
-│  │ StatusPage        │──┼───────┼──│ /api/status        │  │
-│  │ FeedbackButton    │  │       │  │ /api/feedback      │  │
-│  │ DevFeedback       │  │       │  │ /api/incidents     │  │
-│  │ Feedback board    │  │       │  │ /api/board         │  │
-│  │  (composable)     │  │       │  │                    │  │
-│  └───────────────────┘  │       │  └────────────────────┘  │
-│                         │       │           │              │
-│  npm package            │       │  MSSQL + Azure Blob      │
-└─────────────────────────┘       └──────────────────────────┘
-```
-
-## Setup
-
-### 1. Deploy the admin backend
-
-The admin app ([status-feedback-admin](https://alliance.ghe.com/alliance/status-feedback-admin)) provides the API, database, and admin dashboard. Deploy it first.
-
-Required env vars on the admin app:
-```bash
-MSSQL_CONNECTION_STRING=Server=...;Initial Catalog=StatusFeedback;...
-SESSION_SECRET=your-secret
-
-# Optional — stores screenshots in Azure Blob Storage instead of base64 in DB
-AZURE_FEEDBACK_BLOB_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...
-AZURE_FEEDBACK_BLOB_CONTAINER=screenshots
-```
-
-### 2. Create a project and keep the API key server-side
-
-Log into the admin dashboard, create a project, and copy its API key (prefixed `sf_`). Store it in a private server-side environment variable, not a `PUBLIC_` / browser-delivered variable.
-
-### 3. Install the client package
-
-```bash
-npm install @alliance-droid/status-feedback-system
-```
-
-**Peer dependencies:** `svelte ^5.48.0`, `@alliance-droid/svelte-component-library >=1.3.2`
-
-> `@alliance-droid/svelte-component-library` must be `>=1.3.2` — earlier versions are incompatible with Svelte `5.56+` and throw `target.exclude.has is not a function` when board components render.
-
-### 4. Add the recommended SvelteKit proxy
-
-Use one catch-all route in the consuming app. The package owns the admin API path mapping, request validation, key injection, and `key` query stripping; the app owns auth and app-specific policy.
-
-```ts
-// src/routes/svc/feedback/[...path]/+server.ts
-import { env } from '$env/dynamic/private';
-import { createSvelteKitFeedbackProxy } from '@alliance-droid/status-feedback-system/sveltekit/server';
-
-export const { GET, POST, PATCH } = createSvelteKitFeedbackProxy({
-  apiUrl: env.SF_API_URL,
-  apiKey: env.SF_API_KEY,
-  resolveUser: async (event) => {
-    const user = event.locals.user;
-    return user ? { email: user.email, roles: user.roles } : null;
-  },
-  requireUser: true,
-  canSubmitInAppFeedback: ({ user }) =>
-    user.roles.includes('QA') || user.roles.includes('ProductOwner'),
-});
-```
-
-Then point components at the same-origin route and omit `apiKey`:
-
-```svelte
-<DevFeedback apiUrl="/svc/feedback/dev" enabled={canSubmitFeedback} userEmail={user.email} />
-```
-
-Direct admin calls with `apiKey="sf_..."` remain supported for existing integrations, but the proxy is the hardened default.
-
-## Components
-
-### StatusPage
-
-Full status page with systems, incidents, and uptime history bars. Supports **self-fetching** (provide `apiUrl`; add `apiKey` only for direct admin calls) or **pass-through** (provide data directly).
-
-```svelte
-<script>
-  import { StatusPage } from '@alliance-droid/status-feedback-system';
-</script>
-
-<!-- Self-fetching through the same-origin proxy -->
-<StatusPage
-  projectName="My App"
-  apiUrl="/svc/feedback"
-/>
-
-<!-- Pass-through mode -->
-<StatusPage
-  projectName="My App"
-  systems={data.systems}
-  incidents={data.incidents}
-  statusHistory={data.statusHistory}
-  showUptime={true}
-/>
-```
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `projectName` | `string` | required | Display name in the header |
-| `apiUrl` | `string` | — | Proxy URL or direct admin backend URL (self-fetching mode) |
-| `apiKey` | `string` | — | Project API key; omit when using the same-origin proxy |
-| `systems` | `System[]` | — | Pass-through: system data |
-| `incidents` | `Incident[]` | — | Pass-through: incident data |
-| `statusHistory` | `Record<string, StatusHistoryEntry[]>` | — | Pass-through: uptime data |
-| `showUptime` | `boolean` | `true` | Show 90-day uptime bars |
-
-### StatusBanner
-
-Compact inline status indicator — good for footers or nav bars.
-
-```svelte
-<StatusBanner
-  apiUrl="/svc/feedback"
-  statusUrl="/status"
-/>
-```
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `systems` | `System[]` | — | Pass-through mode |
-| `apiUrl` | `string` | — | Proxy URL or direct admin backend URL |
-| `apiKey` | `string` | — | Project API key; omit when using the same-origin proxy |
-| `statusUrl` | `string` | — | Links to full status page (renders as `<a>`) |
-
-### FeedbackButton
-
-Floating action button with an embedded feedback form. Fixed position, bottom corner.
-
-```svelte
-<FeedbackButton
-  apiUrl="/svc/feedback"
-  position="bottom-right"
-  categories={['Bug', 'Feature Request', 'General']}
-  userEmail={currentUser?.email}
-/>
-```
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `apiUrl` | `string` | required | Proxy URL or direct admin backend URL |
-| `apiKey` | `string` | — | Project API key; omit when using the same-origin proxy |
-| `categories` | `string[]` | `['Bug', 'Feature Request', 'General']` | Category options |
-| `userEmail` | `string` | — | Pre-fill email field |
-| `position` | `'bottom-right' \| 'bottom-left'` | `'bottom-right'` | Button position |
-
-### FeedbackForm
-
-Standalone feedback form — embed it wherever you need it.
-
-```svelte
-<FeedbackForm
-  apiUrl="/svc/feedback"
-  categories={['Bug', 'Feature Request']}
-  userEmail={currentUser?.email}
-  onSuccess={() => toast('Thanks!')}
-  onError={(msg) => toast(msg, 'error')}
-/>
-```
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `apiUrl` | `string` | required | Proxy URL or direct admin backend URL |
-| `apiKey` | `string` | — | Project API key; omit when using the same-origin proxy |
-| `categories` | `string[]` | `['Bug', 'Feature Request', 'General']` | Category options |
-| `userEmail` | `string` | — | Pre-fill email field |
-| `onSuccess` | `() => void` | — | Called after successful submission |
-| `onError` | `(error: string) => void` | — | Called on submission error |
-
-### Feedback board (composable)
-
-> 📖 **Full integration guide:** [docs/custom-feedback-integration.md](docs/custom-feedback-integration.md) — composing the parts into your own shell, status management via `getAuthToken`, list restyling, and the not-configured fallback.
-
-The board is composed from parts around **one shared state** (`createFeedbackBoard`), so it drops into your own layout/shell — app rails, breadcrumb, a right-hand detail panel, whatever you have.
-
-```svelte
-<script lang="ts">
-  import {
-    createFeedbackBoard,
-    createAuthTokenGetter,
-    FeedbackSidebar,
-    FeedbackList,
-    FeedbackDetail,
-    FeedbackSubmitForm,
-    type BoardItem,
-  } from '@alliance-droid/status-feedback-system';
-
-  let { data } = $props();
-  const board = createFeedbackBoard({
-    apiUrl: '/svc/feedback',
-    userEmail: data.user?.email,
-    getAuthToken: createAuthTokenGetter(), // optional — enables status management
-    categoryConfig: {
-      Bug: { icon: 'fa-solid fa-bug', label: 'Bugs' },
-      'Feature Request': { icon: 'fa-solid fa-lightbulb', label: 'Ideas' },
-    },
-  });
-
-  let selected = $state<BoardItem | null>(null);
-</script>
-
-<YourSidebar><FeedbackSidebar {board} /></YourSidebar>
-<YourMain><FeedbackList {board} onSelect={(i) => (selected = i)} /></YourMain>
-<YourRail>
-  {#if selected}<FeedbackDetail {board} item={selected} />{/if}
-</YourRail>
-<!-- Render <FeedbackSubmitForm {board} /> wherever you want submission. -->
-```
-
-`createFeedbackBoard(options)` returns a reactive `FeedbackBoardState` (items, categories, filters, voting, `loadTransitions`/`setStatus`, …) shared by every sub-component.
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `apiUrl` | `string` | required | Proxy URL or direct admin backend URL |
-| `apiKey` | `string` | — | Project API key; omit when using the same-origin proxy |
-| `userEmail` | `string` | — | Authenticated user (required to submit feedback/replies) |
-| `categoryConfig` | `Record<string, { label?, icon?, description? }>` | `{}` | Relabel / add icons to sidebar categories |
-| `getAuthToken` | `() => string \| Promise<string \| null>` | — | Bearer token so privileged users can set status (see below) |
-| `pageSize` | `number` | `50` | Items per page |
-
-Exported parts: `createFeedbackBoard`, `FeedbackSidebar`, `FeedbackList`, `FeedbackItem`, `FeedbackDetail`, `FeedbackSubmitForm`.
-
-Categories are fixed by the system (**Bug**, **Feature Request**) — `categoryConfig` only relabels or adds icons.
-
-#### Setting status (ProductOwner)
-
-When you pass `getAuthToken`, a signed-in **ProductOwner** with access to the project can change an item's status from the board (via the status badge → menu) — e.g. Open → Considering → Accepted, or a decline with a reason — without a trip to the admin dashboard. Board status management is **ProductOwner-only**; an Admin role alone does not grant it (Admins still manage status from the dashboard).
-
-Privileged viewers also see each item's **real internal status** on the badge (e.g. "QA / UAT", "Technical review") rather than the coarse public bucket ("In progress") that everyone else sees.
-
-- `getAuthToken` must return the user's **Alliance OIDC access token** whose audience covers **`status-feedback-admin`** (an *id token*, whose `aud` is your app's client id, is rejected). It's called on demand; return `null` for anonymous / non-privileged users and the control simply won't appear — the badge stays a plain read-only badge.
-- **Use the built-in `createAuthTokenGetter()`** for this — it fetches a same-origin token endpoint (`/auth/access-token` by default), caches until just before expiry, single-flights, and returns `null` on any failure. With `@alliance-droid/svelte-auth-core`, set `enableAccessTokenEndpoint: true` and request the `status-feedback-admin` scope so that endpoint exists. Create one instance at module level: `export const getAuthToken = createAuthTokenGetter();`
-- The token travels as `Authorization: Bearer …` to the admin backend, which **verifies it against the IdP** and derives the user's roles. Authorization (ProductOwner role + per-project access + which transitions are allowed, including reason prompts on declines/reopens) is enforced **server-side** — the client never decides permissions. The backend returns a `canManage` flag (HTTP 200, not 403) so ordinary signed-in users get no console noise.
-- The available transitions are returned by the backend per item, so the menu always reflects exactly what that user may do.
-
-> Security note: use the SvelteKit proxy to keep the project `apiKey` out of browser-delivered code. Direct admin calls with an embedded key are still supported for existing integrations, but same-origin proxy mode is the recommended default.
-
-### DevFeedback
-
-Feedback overlay for authorized users. Activated via **Ctrl+right-click** (Cmd+right-click on macOS) anywhere on the page.
-
-Auto-captures: screenshots (via html2canvas), console errors, viewport size, current route, clicked element selector, and deployment context (Vercel env vars).
-
-**Gating:** the widget shows only when `enabled` is `true` **and** `userEmail` is non-empty. `enabled` is the single gate — wire it to your own rule, typically a role/permission check. There is no environment auto-detection. See [docs/role-based-access.md](docs/role-based-access.md) for the recommended role-based setup and the pitfalls.
-
-```svelte
-<script>
-  import { DevFeedback } from '@alliance-droid/status-feedback-system';
-</script>
-
-<!-- In your root +layout.svelte -->
-<DevFeedback
-  apiUrl="/svc/feedback/dev"
-  boardUrl="/feedback"
-  userEmail={user?.email ?? ''}
-  enabled={userCanGiveFeedback}
-/>
-```
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `apiUrl` | `string` | required | Proxy URL or direct admin backend URL. Use `/svc/feedback/dev` with the package proxy for stricter widget policy. |
-| `apiKey` | `string` | — | Project API key; omit when using the same-origin proxy |
-| `enabled` | `boolean` | required | The only gate — wire to your role/permission check |
-| `userEmail` | `string` | required | Signed-in user's email. Empty string ⇒ renders nothing (anonymous feedback unsupported) |
-| `boardUrl` | `string` | — | URL for "View Open Issues" link. Hidden if omitted. |
-| `maxConsoleErrors` | `number` | `20` | Max console errors to capture |
-| `showOnboarding` | `boolean` | `true` | Show "Ctrl+right-click" toast on first visit |
-| `renderTokenEndpoint` | `string` | `/svc/internal/issue-render-token` | App endpoint that mints render tokens for screenshot capture |
-
-**Screenshot storage:** If the admin backend has `AZURE_FEEDBACK_BLOB_CONNECTION_STRING` configured, screenshots are uploaded to Azure Blob Storage. Otherwise they're stored as base64 in the database.
-
-## API Client
-
-All components use a shared API client. You can also use it directly:
-
-```typescript
-import { createStatusClient } from '@alliance-droid/status-feedback-system';
-
-const client = createStatusClient({
-  apiUrl: '/svc/feedback',
-  fetch: event.fetch, // Optional: pass SvelteKit's fetch for SSR
-});
-
-const { systems, overallStatus } = await client.getStatus();
-const { incidents } = await client.getIncidents({ limit: 5, includeResolved: true });
-const { history } = await client.getUptime({ days: 90 });
-const feedback = await client.submitFeedback({ message: 'Great product!' });
-const { items, total, categories } = await client.getBoard({ sort: 'votes', status: 'open' });
-```
-
-## Shared Components
-
-Lower-level building blocks used by StatusPage — exported for custom layouts:
-
-```typescript
-import {
-  StatusIndicator,  // Status dot + label (operational/degraded/outage/maintenance)
-  UptimeBar,        // 90-day uptime bar chart
-  IncidentTimeline, // Chronological incident updates
-  SystemCard,       // Single system status card with uptime bar
-} from '@alliance-droid/status-feedback-system';
-```
-
-## All Exports
-
-```typescript
-// Components
-import {
-  StatusPage, StatusBanner, FeedbackForm, FeedbackButton, DevFeedback,
-  StatusIndicator, UptimeBar, IncidentTimeline, SystemCard, PasteImageInput,
-} from '@alliance-droid/status-feedback-system';
-
-// Feedback board (composable)
-import {
-  createFeedbackBoard,
-  createAuthTokenGetter,
-  FeedbackSidebar, FeedbackList, FeedbackItem, FeedbackDetail, FeedbackSubmitForm,
-} from '@alliance-droid/status-feedback-system';
-import type {
-  FeedbackBoardState, FeedbackBoardOptions, CategoryConfig,
-  AuthTokenGetter, AuthTokenGetterOptions,
-} from '@alliance-droid/status-feedback-system';
-
-// API Client
-import { createStatusClient } from '@alliance-droid/status-feedback-system';
-import type {
-  StatusClient, StatusClientConfig,
-  StatusData, IncidentData, UptimeData, BoardData, BoardItem, BoardCategory,
-} from '@alliance-droid/status-feedback-system';
-
-// SvelteKit server proxy
-import {
-  createSvelteKitFeedbackProxy,
-  isFeedbackProxyConfigured,
-} from '@alliance-droid/status-feedback-system/sveltekit/server';
-
-// Utilities
-import { deriveOverallStatus } from '@alliance-droid/status-feedback-system';
-
-// Types
-import type {
-  Project, System, Incident, IncidentUpdate, Feedback, FeedbackResponse,
-  FeedbackVisibility, StatusHistoryEntry, ApiResponse,
-  SystemStatus, IncidentStatus, IncidentSeverity, FeedbackStatus,
-} from '@alliance-droid/status-feedback-system';
-```
-
-## License
-
-Copyright © 2026 Alliance Technical Group. All rights reserved.
+# @alliance-droid/status-feedback-system
+
+Drop-in system status pages and user feedback components for SvelteKit apps.
+
+This package provides UI components plus an optional SvelteKit server proxy for talking to a [status-feedback-admin](https://alliance.ghe.com/alliance/status-feedback-admin) backend. The admin app handles data storage, API key management, and the admin dashboard.
+
+## Architecture
+
+```
+┌─────────────────────────┐       ┌──────────────────────────┐
+│   Your SvelteKit App    │       │  status-feedback-admin   │
+│                         │       │                          │
+│  ┌───────────────────┐  │  API  │  ┌────────────────────┐  │
+│  │ StatusPage        │──┼───────┼──│ /api/status        │  │
+│  │ FeedbackButton    │  │       │  │ /api/feedback      │  │
+│  │ DevFeedback       │  │       │  │ /api/incidents     │  │
+│  │ Feedback board    │  │       │  │ /api/board         │  │
+│  │  (composable)     │  │       │  │                    │  │
+│  └───────────────────┘  │       │  └────────────────────┘  │
+│                         │       │           │              │
+│  npm package            │       │  MSSQL + Azure Blob      │
+└─────────────────────────┘       └──────────────────────────┘
+```
+
+## Setup
+
+### 1. Deploy the admin backend
+
+The admin app ([status-feedback-admin](https://alliance.ghe.com/alliance/status-feedback-admin)) provides the API, database, and admin dashboard. Deploy it first.
+
+Required env vars on the admin app:
+```bash
+MSSQL_CONNECTION_STRING=Server=...;Initial Catalog=StatusFeedback;...
+SESSION_SECRET=your-secret
+
+# Optional — stores screenshots in Azure Blob Storage instead of base64 in DB
+AZURE_FEEDBACK_BLOB_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...
+AZURE_FEEDBACK_BLOB_CONTAINER=screenshots
+```
+
+### 2. Create a project and keep the API key server-side
+
+Log into the admin dashboard, create a project, and copy its API key (prefixed `sf_`). Store it in a private server-side environment variable, not a `PUBLIC_` / browser-delivered variable.
+
+### 3. Install the client package
+
+```bash
+npm install @alliance-droid/status-feedback-system
+```
+
+**Peer dependencies:** `svelte ^5.48.0`, `@alliance-droid/svelte-component-library >=1.3.2`
+
+> `@alliance-droid/svelte-component-library` must be `>=1.3.2` — earlier versions are incompatible with Svelte `5.56+` and throw `target.exclude.has is not a function` when board components render.
+
+### 4. Add the recommended SvelteKit proxy
+
+Use one catch-all route in the consuming app. The package owns the admin API path mapping, request validation, key injection, and `key` query stripping; the app owns auth and app-specific policy.
+
+```ts
+// src/routes/svc/feedback/[...path]/+server.ts
+import { env } from '$env/dynamic/private';
+import { createSvelteKitFeedbackProxy } from '@alliance-droid/status-feedback-system/sveltekit/server';
+
+export const { GET, POST, PATCH } = createSvelteKitFeedbackProxy({
+  apiUrl: env.SF_API_URL,
+  apiKey: env.SF_API_KEY,
+  resolveUser: async (event) => {
+    const user = event.locals.user;
+    return user ? { email: user.email, roles: user.roles } : null;
+  },
+  requireUser: true,
+  canSubmitInAppFeedback: ({ user }) =>
+    user.roles.includes('QA') || user.roles.includes('ProductOwner'),
+});
+```
+
+Then point components at the same-origin route and omit `apiKey`:
+
+```svelte
+<DevFeedback apiUrl="/svc/feedback/dev" enabled={canSubmitFeedback} userEmail={user.email} />
+```
+
+Direct admin calls with `apiKey="sf_..."` remain supported for existing integrations, but the proxy is the hardened default.
+
+## Components
+
+### StatusPage
+
+Full status page with systems, incidents, and uptime history bars. Supports **self-fetching** (provide `apiUrl`; add `apiKey` only for direct admin calls) or **pass-through** (provide data directly).
+
+```svelte
+<script>
+  import { StatusPage } from '@alliance-droid/status-feedback-system';
+</script>
+
+<!-- Self-fetching through the same-origin proxy -->
+<StatusPage
+  projectName="My App"
+  apiUrl="/svc/feedback"
+/>
+
+<!-- Pass-through mode -->
+<StatusPage
+  projectName="My App"
+  systems={data.systems}
+  incidents={data.incidents}
+  statusHistory={data.statusHistory}
+  showUptime={true}
+/>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `projectName` | `string` | required | Display name in the header |
+| `apiUrl` | `string` | — | Proxy URL or direct admin backend URL (self-fetching mode) |
+| `apiKey` | `string` | — | Project API key; omit when using the same-origin proxy |
+| `systems` | `System[]` | — | Pass-through: system data |
+| `incidents` | `Incident[]` | — | Pass-through: incident data |
+| `statusHistory` | `Record<string, StatusHistoryEntry[]>` | — | Pass-through: uptime data |
+| `showUptime` | `boolean` | `true` | Show 90-day uptime bars |
+
+### StatusBanner
+
+Compact inline status indicator — good for footers or nav bars.
+
+```svelte
+<StatusBanner
+  apiUrl="/svc/feedback"
+  statusUrl="/status"
+/>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `systems` | `System[]` | — | Pass-through mode |
+| `apiUrl` | `string` | — | Proxy URL or direct admin backend URL |
+| `apiKey` | `string` | — | Project API key; omit when using the same-origin proxy |
+| `statusUrl` | `string` | — | Links to full status page (renders as `<a>`) |
+
+### FeedbackButton
+
+Floating action button with an embedded feedback form. Fixed position, bottom corner.
+
+```svelte
+<FeedbackButton
+  apiUrl="/svc/feedback"
+  position="bottom-right"
+  categories={['Bug', 'Feature Request', 'General']}
+  userEmail={currentUser?.email}
+/>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `apiUrl` | `string` | required | Proxy URL or direct admin backend URL |
+| `apiKey` | `string` | — | Project API key; omit when using the same-origin proxy |
+| `categories` | `string[]` | `['Bug', 'Feature Request', 'General']` | Category options |
+| `userEmail` | `string` | — | Pre-fill email field |
+| `position` | `'bottom-right' \| 'bottom-left'` | `'bottom-right'` | Button position |
+
+### FeedbackForm
+
+Standalone feedback form — embed it wherever you need it.
+
+```svelte
+<FeedbackForm
+  apiUrl="/svc/feedback"
+  categories={['Bug', 'Feature Request']}
+  userEmail={currentUser?.email}
+  onSuccess={() => toast('Thanks!')}
+  onError={(msg) => toast(msg, 'error')}
+/>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `apiUrl` | `string` | required | Proxy URL or direct admin backend URL |
+| `apiKey` | `string` | — | Project API key; omit when using the same-origin proxy |
+| `categories` | `string[]` | `['Bug', 'Feature Request', 'General']` | Category options |
+| `userEmail` | `string` | — | Pre-fill email field |
+| `onSuccess` | `() => void` | — | Called after successful submission |
+| `onError` | `(error: string) => void` | — | Called on submission error |
+
+### Feedback board (composable)
+
+> 📖 **Full integration guide:** [docs/custom-feedback-integration.md](docs/custom-feedback-integration.md) — composing the parts into your own shell, status management via `getAuthToken`, list restyling, and the not-configured fallback.
+
+The board is composed from parts around **one shared state** (`createFeedbackBoard`), so it drops into your own layout/shell — app rails, breadcrumb, a right-hand detail panel, whatever you have.
+
+```svelte
+<script lang="ts">
+  import {
+    createFeedbackBoard,
+    createAuthTokenGetter,
+    FeedbackSidebar,
+    FeedbackList,
+    FeedbackDetail,
+    FeedbackSubmitForm,
+    type BoardItem,
+  } from '@alliance-droid/status-feedback-system';
+
+  let { data } = $props();
+  const board = createFeedbackBoard({
+    apiUrl: '/svc/feedback',
+    userEmail: data.user?.email,
+    getAuthToken: createAuthTokenGetter(), // optional — enables status management
+    categoryConfig: {
+      Bug: { icon: 'fa-solid fa-bug', label: 'Bugs' },
+      'Feature Request': { icon: 'fa-solid fa-lightbulb', label: 'Ideas' },
+    },
+  });
+
+  let selected = $state<BoardItem | null>(null);
+</script>
+
+<YourSidebar><FeedbackSidebar {board} /></YourSidebar>
+<YourMain><FeedbackList {board} onSelect={(i) => (selected = i)} /></YourMain>
+<YourRail>
+  {#if selected}<FeedbackDetail {board} item={selected} />{/if}
+</YourRail>
+<!-- Render <FeedbackSubmitForm {board} /> wherever you want submission. -->
+```
+
+`createFeedbackBoard(options)` returns a reactive `FeedbackBoardState` (items, categories, filters, voting, `loadTransitions`/`setStatus`, …) shared by every sub-component.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiUrl` | `string` | required | Proxy URL or direct admin backend URL |
+| `apiKey` | `string` | — | Project API key; omit when using the same-origin proxy |
+| `userEmail` | `string` | — | Authenticated user (required to submit feedback/replies) |
+| `categoryConfig` | `Record<string, { label?, icon?, description? }>` | `{}` | Relabel / add icons to sidebar categories |
+| `getAuthToken` | `() => string \| Promise<string \| null>` | — | Bearer token so privileged users can set status (see below) |
+| `pageSize` | `number` | `50` | Items per page |
+
+Exported parts: `createFeedbackBoard`, `FeedbackSidebar`, `FeedbackList`, `FeedbackItem`, `FeedbackDetail`, `FeedbackSubmitForm`.
+
+Categories are fixed by the system (**Bug**, **Feature Request**) — `categoryConfig` only relabels or adds icons.
+
+#### Setting status (ProductOwners and Admins)
+
+When you pass `getAuthToken`, **Admins** and **ProductOwners with project access** can accept, reopen, or decline feedback (Won't do, Duplicate, Can't reproduce), where the current status permits the decision. Reopens and declines require a reason. **Only acceptance starts automation**; engineering, QA approval, release, and completion transitions remain in the admin app.
+
+Editable items have **purple status controls and row accents**, accompanied by a text cue. The sidebar's **Needs my input** filter shows Open, Considering, and Waiting on reply, filtered on the server across all pages. Everyone continues to see each item's granular status.
+
+Deploy the matching admin-server capabilities update first. The packaged proxy forwards the optional board bearer token; custom proxies must also forward `Authorization` on board reads and preserve `status=needs_input`. Custom lists can use the backend's per-item `canChangeStatus` and `needsInput` fields with `board.canManageStatus`.
+
+- `getAuthToken` must return the user's **Alliance OIDC access token** whose audience covers **`status-feedback-admin`** (an *id token*, whose `aud` is your app's client id, is rejected). It's called on demand; return `null` for anonymous / non-privileged users and the control simply won't appear — the badge stays a plain read-only badge.
+- **Use the built-in `createAuthTokenGetter()`** for this — it fetches a same-origin token endpoint (`/auth/access-token` by default), caches until just before expiry, single-flights, and returns `null` on any failure. With `@alliance-droid/svelte-auth-core`, set `enableAccessTokenEndpoint: true` and request the `status-feedback-admin` scope so that endpoint exists. Create one instance at module level: `export const getAuthToken = createAuthTokenGetter();`
+- The token travels as `Authorization: Bearer …` to the admin backend, which **verifies it against the IdP** and derives the user's roles. Authorization (Admin or ProductOwner role + per-project access + the restricted board transitions, including reason prompts on declines/reopens) is enforced **server-side** — the client never decides permissions. The backend returns a `canManage` flag (HTTP 200, not 403) so ordinary signed-in users get no console noise.
+- The available transitions are returned by the backend per item, so the menu always reflects exactly what that user may do.
+
+> Security note: use the SvelteKit proxy to keep the project `apiKey` out of browser-delivered code. Direct admin calls with an embedded key are still supported for existing integrations, but same-origin proxy mode is the recommended default.
+
+### DevFeedback
+
+Feedback overlay for authorized users. Activated via **Ctrl+right-click** (Cmd+right-click on macOS) anywhere on the page.
+
+Auto-captures: screenshots (via html2canvas), console errors, viewport size, current route, clicked element selector, and deployment context (Vercel env vars).
+
+**Gating:** the widget shows only when `enabled` is `true` **and** `userEmail` is non-empty. `enabled` is the single gate — wire it to your own rule, typically a role/permission check. There is no environment auto-detection. See [docs/role-based-access.md](docs/role-based-access.md) for the recommended role-based setup and the pitfalls.
+
+```svelte
+<script>
+  import { DevFeedback } from '@alliance-droid/status-feedback-system';
+</script>
+
+<!-- In your root +layout.svelte -->
+<DevFeedback
+  apiUrl="/svc/feedback/dev"
+  boardUrl="/feedback"
+  userEmail={user?.email ?? ''}
+  enabled={userCanGiveFeedback}
+/>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `apiUrl` | `string` | required | Proxy URL or direct admin backend URL. Use `/svc/feedback/dev` with the package proxy for stricter widget policy. |
+| `apiKey` | `string` | — | Project API key; omit when using the same-origin proxy |
+| `enabled` | `boolean` | required | The only gate — wire to your role/permission check |
+| `userEmail` | `string` | required | Signed-in user's email. Empty string ⇒ renders nothing (anonymous feedback unsupported) |
+| `boardUrl` | `string` | — | URL for "View Open Issues" link. Hidden if omitted. |
+| `maxConsoleErrors` | `number` | `20` | Max console errors to capture |
+| `showOnboarding` | `boolean` | `true` | Show "Ctrl+right-click" toast on first visit |
+| `renderTokenEndpoint` | `string` | `/svc/internal/issue-render-token` | App endpoint that mints render tokens for screenshot capture |
+
+**Screenshot storage:** If the admin backend has `AZURE_FEEDBACK_BLOB_CONNECTION_STRING` configured, screenshots are uploaded to Azure Blob Storage. Otherwise they're stored as base64 in the database.
+
+## API Client
+
+All components use a shared API client. You can also use it directly:
+
+```typescript
+import { createStatusClient } from '@alliance-droid/status-feedback-system';
+
+const client = createStatusClient({
+  apiUrl: '/svc/feedback',
+  fetch: event.fetch, // Optional: pass SvelteKit's fetch for SSR
+});
+
+const { systems, overallStatus } = await client.getStatus();
+const { incidents } = await client.getIncidents({ limit: 5, includeResolved: true });
+const { history } = await client.getUptime({ days: 90 });
+const feedback = await client.submitFeedback({ message: 'Great product!' });
+const { items, total, categories } = await client.getBoard({ sort: 'votes', status: 'open' });
+```
+
+## Shared Components
+
+Lower-level building blocks used by StatusPage — exported for custom layouts:
+
+```typescript
+import {
+  StatusIndicator,  // Status dot + label (operational/degraded/outage/maintenance)
+  UptimeBar,        // 90-day uptime bar chart
+  IncidentTimeline, // Chronological incident updates
+  SystemCard,       // Single system status card with uptime bar
+} from '@alliance-droid/status-feedback-system';
+```
+
+## All Exports
+
+```typescript
+// Components
+import {
+  StatusPage, StatusBanner, FeedbackForm, FeedbackButton, DevFeedback,
+  StatusIndicator, UptimeBar, IncidentTimeline, SystemCard, PasteImageInput,
+} from '@alliance-droid/status-feedback-system';
+
+// Feedback board (composable)
+import {
+  createFeedbackBoard,
+  createAuthTokenGetter,
+  FeedbackSidebar, FeedbackList, FeedbackItem, FeedbackDetail, FeedbackSubmitForm,
+} from '@alliance-droid/status-feedback-system';
+import type {
+  FeedbackBoardState, FeedbackBoardOptions, CategoryConfig,
+  AuthTokenGetter, AuthTokenGetterOptions,
+} from '@alliance-droid/status-feedback-system';
+
+// API Client
+import { createStatusClient } from '@alliance-droid/status-feedback-system';
+import type {
+  StatusClient, StatusClientConfig,
+  StatusData, IncidentData, UptimeData, BoardData, BoardItem, BoardCategory,
+} from '@alliance-droid/status-feedback-system';
+
+// SvelteKit server proxy
+import {
+  createSvelteKitFeedbackProxy,
+  isFeedbackProxyConfigured,
+} from '@alliance-droid/status-feedback-system/sveltekit/server';
+
+// Utilities
+import { deriveOverallStatus } from '@alliance-droid/status-feedback-system';
+
+// Types
+import type {
+  Project, System, Incident, IncidentUpdate, Feedback, FeedbackResponse,
+  FeedbackVisibility, StatusHistoryEntry, ApiResponse,
+  SystemStatus, IncidentStatus, IncidentSeverity, FeedbackStatus,
+} from '@alliance-droid/status-feedback-system';
+```
+
+## License
+
+Copyright © 2026 Alliance Technical Group. All rights reserved.