classroomio/prd/course-widget-embed [DONE]/README.md

# Course Widget Embed PRD (Org Widgets)

## Status

- Done (shipped)

## Purpose
Ship an organization-scoped widget system so admins can embed selected courses on external websites from `/org/[slug]/widgets`, with a visual editor and lightweight runtime.

## Confirmed Decisions (2026-02-17)
1. Editor route is in dashboard org context: `/org/[slug]/widgets` (user-facing equivalent: `/org/id/widgets`).
2. Embed runtime must be plain Svelte (no SvelteKit in the embed runtime path) for minimal JS payload.
3. Widget rendering supports multiple layouts:
- cards
- table
- primary single course
- carousel
- tag-filtered list (tags as top badges)
4. Widget authoring UI opens an editor with left panel sections:
- `Select Courses`
- `Widgets`
- `Design`
5. Published widgets deploy to Cloudflare-backed static hosting/edge delivery (R2 + Workers).
6. Dashboard editing reuses the existing `@cio/embeds` renderer in dev mode for real preview parity.
7. Dashboard preview does not call a preview endpoint; it uses already-fetched dashboard state and passes payload into an iframe.
8. Public embed fetches a dedicated published widget payload from server endpoints.

## Current State Alignment (2026-04-13)
1. The existing third-party embed runtime already lives in `apps/embeds` and is published as `@cio/embeds`; this feature should extend that app rather than introduce a new `@cio/widgets` package.
2. The existing embed publish path already lives in `apps/embeds/scripts/upload-embeds.ts` and `.github/workflows/deploy-embeds.yml`; the course widget should plug into that release flow.
3. The closest current public course route is `/organization/courses/public`, but it is not suitable as the widget first-render path because it does multiple DB round-trips and has no dedicated public cache strategy.
4. Public widget rendering therefore needs a dedicated published payload fast path:
- compute canonical payload on publish
- persist it with the published widget version
- serve it from a compact public endpoint with CDN/browser cache headers
5. If first-render latency later becomes the top priority, a single published JS endpoint with payload embedded is a valid follow-on optimization, but v1 should start with cached published JSON payload + static `@cio/embeds` assets.

## Implementation Status (2026-04-13)

### Completed
1. Shared widget validation and canonical payload contracts were added in `packages/utils/src/validation/widget/widget.ts`.
2. Widget persistence was added in the DB layer for `widget`, `widget_course`, and `widget_version`.
3. Widget query helpers were added in `packages/db/src/queries/widget/widget.ts`.
4. Organization widget API routes are implemented for list, create, detail, update, archive, publish, and rollback.
5. Public payload delivery is implemented at `GET /widgets/:publicKey/payload`.
6. Widget payload computation, public key generation, embed code generation, and CSS sanitization were added in `apps/api/src/services/widget-payload.ts`.
7. Dashboard widgets UI is implemented at `/org/[slug]/widgets` and `/org/[slug]/widgets/[widgetId]`.
8. The dashboard includes a widget list page, editor page, local live preview, save/discard flow, publish and rollback actions, embed code copy flow, and an org sidebar navigation entry.
9. A course widget runtime was added to `apps/embeds/src/widgets/course-widget/*`.
10. Embed publishing/build plumbing was extended so `question-type-picker` and `course-widget` build and upload independently.
11. The course widget bundle was reduced back into the intended budget range after splitting embed builds per target:
- loader: `6.41 kB` (`2.20 kB` gzip)
- runtime chunk: `80.03 kB` (`22.35 kB` gzip)
12. Shadow DOM isolation was implemented for the public embed runtime:
- Widget CSS extracted to `widget.css` and injected into shadow root
- Custom element `<cio-course-widget>` with `attachShadow({ mode: 'open' })`
- Host page CSS cannot break widget visuals
13. Dashboard preview now uses an iframe + postMessage pipeline:
- Preview route at `/widget-preview` renders the widget component
- `widget-iframe-preview.svelte` handles the parent-side protocol
- `preview-protocol.ts` defines typed message contract (`READY/RENDER/ERROR/RESIZE`)
- Strict origin validation and exponential backoff retry (3 attempts)
14. Data freshness controls were added to the widget editor:
- "Last synced" timestamp display
- Manual "Refresh" button to reload widget data from server
- `onSynced` callback from iframe when render completes
15. Rate limiting was added to the public widget payload endpoint:
- 100 req/min per IP address
- 1000 req/min per widget key
- Uses existing `createRateLimiter` middleware with Redis-backed limiter
16. Widget validation and payload tests were added (47 tests passing):
- Zod schema tests for create/update/config/public-key
- Plan gating tests (free vs paid theme/colors/CSS/branding)
- Base58 encoding and key generation tests
- Embed code generation tests

### Verified
1. `pnpm --filter @cio/utils build`
2. `pnpm --filter @cio/api build`
3. `pnpm --filter @cio/dashboard build`
4. `pnpm --filter @cio/embeds build`
5. `node --import tsx apps/embeds/scripts/upload-embeds.ts --help`

### Remaining / Not Yet Implemented
1. Bundle-size enforcement in CI is not implemented yet; the runtime is small enough now, but there is no automated budget gate.
2. Analytics ingestion is still deferred.
3. Accessibility work is partial:
- focus-visible states and basic labels exist in the runtime
- there is no dedicated axe-core or accessibility verification pass yet
4. Translation coverage is only updated in `en.json`; other locales were not expanded.
5. Manual end-to-end publish smoke testing on a real embedded host page is still pending.
6. Plan-gating UX polish (disabled state tooltips) not yet done.
7. Cloudflare delivery policy automation not yet configured.
8. Feature flag for controlled rollout not yet implemented.

### Important Note
The code path is implemented, but the database portion still depends on the corresponding SQL migration being applied anywhere this feature is expected to run against a real database. Updating `schema.ts` alone is not enough for runtime availability.

## Problem Statement
Organizations currently show courses mainly on their own landing pages. There is no first-class way to publish reusable, brandable, copy-paste course widgets for external websites.

This creates gaps:
- No reusable embed snippet per organization.
- No dashboard-managed widget lifecycle (draft, publish, version rollback).
- No lightweight runtime optimized for third-party pages.
- No structured design controls for layout/theme/branding.

## Product Goals
1. Let org admins create and publish embeddable course widgets.
2. Keep embed runtime lightweight and isolated from host-site CSS/JS conflicts.
3. Reuse existing course and tag data models for content selection/filtering.
4. Provide clear plan-gated design controls (free vs paid capabilities).
5. Support versioned publishing with safe rollbacks.

## Non-Goals (v1)
- Full website/page builder replacement.
- Server-rendered widget runtime.
- Cross-org shared widget templates marketplace.
- Arbitrary third-party JS execution inside widgets.

## Data Sources Checked
- `apps/dashboard/src/lib/features/ui/navigation/org-navigation.ts`
- `apps/dashboard/src/routes/org/[slug]/courses/+page.server.ts`
- `apps/dashboard/src/routes/org/[slug]/tags/+page.server.ts`
- `apps/dashboard/src/lib/features/org/api/org.svelte.ts`
- `apps/dashboard/src/lib/features/org/components/landing-page/landing-page.svelte`
- `apps/dashboard/src/lib/features/course/components/card.svelte`
- `apps/api/src/routes/organization/organization.ts`
- `apps/api/src/services/organization.ts`
- `packages/db/src/schema.ts`
- `packages/db/src/queries/course/course.ts`
- `packages/db/src/queries/tag/tag.ts`
- `packages/utils/src/plans/constants.ts`
- `packages/course-app/README.md`

## User Roles

### Admin (`ROLE.ADMIN`)
- Create/edit/delete/archive widgets.
- Select courses and widget layout.
- Configure design controls and plan-gated options.
- Publish widget versions and rollback.
- Copy embed snippet.

### Tutor (`ROLE.TUTOR`)
- Create/edit widget drafts and use live preview.
- No publish, rollback, or destructive lifecycle actions in v1.

### Student/Public
- No dashboard access.
- Consume published embed on external sites.

## Functional Requirements

### 1. Widget Lifecycle
- Create widget with:
  - `name`
  - `layoutType`
  - selection mode (`manual` course selection or `published courses`)
  - initial design config
- Status model:
  - `DRAFT`
  - `PUBLISHED`
  - `ARCHIVED`
- Save model:
  - manual save only (`Save` button)
  - no autosave in v1
- Publish creates immutable version snapshot.
- Rollback can point latest published to a previous version.

### 2. Widget Editor UX (`/org/[slug]/widgets/:widgetId`)
- Left panel tabs:
  - `Select Courses`
  - `Widgets`
  - `Design`
- Main panel:
  - live preview using the same `@cio/embeds` renderer contract as public embed
  - desktop/mobile preview toggle
  - embed code tab
- Live preview behavior:
  - every design/content change updates a local draft state
  - dashboard uses already-fetched state (courses/tags/widget draft) to build preview payload
  - preview payload is passed down through iframe (`postMessage`) to preview runtime
  - iframe mounts the same widget component contract used by public embed
  - changes are preview-only until user clicks `Save`

### 3. Select Courses
- Source modes:
  - manual selected courses
  - all published org courses
- Filters:
  - tag include/exclude using existing org tags
  - search by course title
- Ordering:
  - manual order
  - newest
  - title A-Z

### 4. Widget Layout Types
- `cards`
- `table`
- `primary_course`
- `carousel`
- `tag_filter`

Each layout supports required shared props:
- `showCourseImage`
- `showCourseTypeBadge`
- `showLessonsCount`
- `showPrice`
- `showDescriptionExcerpt`
- `ctaLabel`

### 5. Design Controls
Design panel is grouped as:

#### Content
- limit courses toggle + max count
- load more label
- hide load more toggle
- show border toggle
- border width
- shadow size + style + color
- border radius scale
- show metadata toggles (lessons/type/price)
- shorten long description toggle
- show highlighted/featured style toggle

#### Colors
- primary color
- background color
- text color
- badge/rating color
- border color
- highlight color

#### Typography
- font family selector
- font size scale

#### Filters
- add/remove tag filter rows
- top badge style for tag filter layout

#### Branding
- `Show Classroomio Powered By` toggle

#### Advanced
- custom CSS textarea (sanitized + size-limited)

### 6. Plan Gating
- Free (`PLAN.BASIC`):
  - **1 preset theme only** (default Classroomio theme)
  - branding forced on
  - custom CSS disabled
- Paid (`PLAN.EARLY_ADOPTER`, `PLAN.ENTERPRISE`):
  - **All preset themes available** (3-5 curated themes)
  - full color controls (custom colors)
  - branding toggle available
  - custom CSS enabled

### 7. Public Embed Contract
- Copy-paste embed pattern:
  - `<div data-cio-widget="course-widget" data-widget-key="wgt_xxx"></div>`
  - `<script async type="module" src="https://<public-embed-host>/embeds/course-widget/course-widget.js"></script>`
- Bootstrap script loads the existing `@cio/embeds` course-widget entry.
- Runtime fetches the compact published widget payload via public key and mounts the widget.
- Host page should not require framework dependencies.
- Payload shape must match dashboard preview payload contract.

### 8. Runtime Constraints (Lightweight Requirement)
- Plain Svelte runtime delivered from the existing `apps/embeds` app output.
- No SvelteKit runtime in embed bundle.
- Use style isolation: **Shadow DOM custom element** (`<widget-root>`) with `:host` selector support.
- Performance budgets:
  - loader <= 3KB gzip
  - base runtime <= 35KB gzip (excluding fetched data)
  - first render <= 1.2s on mid-tier 4G for <= 6 courses
- Accessibility:
  - All interactive elements keyboard accessible
  - ARIA labels on course cards (`aria-label="Course: ${title}"`)
  - Alt text on course images
  - Focus visible indicators

### 9. Security and Safety
- Public widget key must be non-guessable (format: `wgt_<base58>`).
- Custom CSS sanitized with `css-tree` parser (whitelist approach):
  - Max size: 5KB
  - Reject: `@import`, `javascript:`, expression(), behavior:, binding:, `-moz-binding`
  - Reject properties: `position: fixed` (can overlay host page maliciously)
  - Allowed: standard visual styles (color, spacing, typography, flex/grid layout)
- Public endpoint returns only publish-approved fields (no internal org data).
- Rate limit public widget payload endpoint: 100 req/min per IP, 1000 req/min per widget key.
- iframe origin validation: strict `targetOrigin` matching dashboard domain.

### 10. Analytics (Schema Reserved for Phase 2)
**Deferred to Phase 2**, but schema defined for forward compatibility:

```typescript
// Table: widget_analytics_event
{
  id: string;
  widget_id: string;
  widget_version_id: string;
  event_type: 'impression' | 'cta_click' | 'filter_interaction';
  course_id?: string;       // for cta_click events
  filter_tag_id?: string;   // for filter_interaction events
  session_id: string;       // anonymous session fingerprint
  timestamp: Date;
  user_agent_hash: string;  // privacy-preserving hash
  country_code?: string;    // from CF-IPCountry header
}
```

- Ingestion: Batch insert every 30 seconds or 1000 events
- Retention: 90 days raw, aggregated forever
- v1: No events endpoint; schema created but not populated

### 11. Shared Payload Contract (Hard Requirement)
- One canonical payload schema defines widget data:
  - selected courses
  - resolved ordering/filters
  - normalized design tokens and defaults
  - plan-gated fields
- Dashboard preview builds payload client-side from already-fetched state and passes it to iframe.
- Public embed fetches a published payload snapshot from a dedicated widget endpoint; it must not recompute from generic live course queries on every request.
- The embed renderer accepts only this payload schema + minimal runtime options.
- No separate dashboard-only renderer data shape is allowed.

### 11. Cloudflare Publish Pipeline (Phase E)

#### Artifact Generation
1. **Build Trigger**: API call `POST /organization/widgets/:widgetId/publish`
2. **Build Process**:
   ```
   a. API receives publish request
   b. Compute final payload with resolved courses + design config
   c. Persist payload snapshot to `widget_version`
   d. Build or reuse the current `@cio/embeds` course-widget runtime release
   e. Upload immutable static assets to R2 under `embeds/course-widget/`
   f. Purge/bootstrap refresh via existing embeds deployment flow
   g. API saves the published payload snapshot and runtime release metadata to `widget_version`
   ```

#### Artifact Manifest Format
```json
{
  "version": "v1",
  "widgetId": "wgt_xxx",
  "orgId": "org_yyy",
  "createdAt": "2026-02-19T12:00:00Z",
  "runtime": {
    "entryUrl": "https://assets.cdn.clsrio.com/embeds/course-widget/course-widget.js",
    "release": "2026-02-19-1"
  },
  "payload": {
    "schemaVersion": "v1",
    "cacheKey": "widget:payload:wgt_xxx:v3"
  },
  "designHash": "sha256:abc..."
}
```

#### Cleanup Policy
- Keep last 10 versions per widget
- Delete older artifacts after 30 days (R2 lifecycle rule)
- Soft-delete in DB (set `deleted_at`), hard-delete after 90 days

#### Delivery Architecture
```
User's Website                    Cloudflare
|                                 |
|-- script src="course-widget.js"->|-- Serve static `@cio/embeds` asset
|<-- course-widget.js ------------|
|                                 |
|-- runtime fetches payload ----->|-- Validate widget key
|                                 |-- Check CDN/cache
|                                 |-- Cache miss: read published payload snapshot
|<-- payload JSON ----------------|
|                                 |
|-- runtime mounts widget ------->|-- Static assets already cached/immutable
```

---

## Proposed Architecture

### Package and App Boundaries
1. `apps/embeds`
- plain Svelte runtime entrypoints for third-party sites
- layout implementations for course widget
- shared mount/bootstrap logic
- build output: browser-ready ESM bundle + hashed chunks

2. `apps/dashboard`
- widget editor UI and preview
- imports or mirrors the same renderer contract used by `@cio/embeds` in dev/prod preview

3. `apps/api`
- org-protected widget CRUD/publish routes
- public widget payload route
- shared `computeWidgetPayload(...)` service used during publish and for controlled cache rebuilds

4. Cloudflare publish target
- stores versioned embed assets
- serves bootstrap/chunks with immutable cache headers
- serves compact public payload with shorter CDN/browser cache headers

### Render Data Flow
1. Dashboard editor loads widget draft and related data into state (courses/tags/config).
2. Left panel changes update local draft JSON in state.
3. Dashboard builds preview payload from state and sends it to preview iframe via `postMessage`.
4. Preview iframe mounts the same renderer contract used by `@cio/embeds`.
5. Publish stores a payload snapshot; public runtime requests the published payload for the current version and mounts the same renderer.

### Data Model (Proposed)
1. `widget`
- `id`, `organization_id`, `name`, `status`, `layout_type`
- `selection_mode`, `public_key`, `latest_published_version_id`
- `created_by`, `updated_by`, timestamps

2. `widget_course`
- `widget_id`, `course_id`, `order`

3. `widget_version`
- `id`, `widget_id`, `version`
- `config_snapshot` (jsonb)
- `payload_snapshot` (jsonb: canonical public payload)
- `runtime_manifest` (jsonb: embed entry URL + release metadata)
- `published_at`, `published_by`

## API Contract Additions (Target)
### Organization-Scoped (auth + org membership)
1. `GET /organization/widgets`
2. `POST /organization/widgets`
3. `GET /organization/widgets/:widgetId`
4. `PUT /organization/widgets/:widgetId`
5. `DELETE /organization/widgets/:widgetId`
6. `POST /organization/widgets/:widgetId/publish`
7. `POST /organization/widgets/:widgetId/rollback`

### Public
1. `GET /widgets/:publicKey/payload`
2. `POST /widgets/:publicKey/events` (optional in v1, can be deferred)

## UX Flow
1. Admin opens `/org/[slug]/widgets`.
2. Clicks `Create Widget`.
3. Editor opens with left tabs (`Select Courses`, `Widgets`, `Design`).
4. Admin previews and adjusts design.
5. Admin publishes, receives embed snippet.
6. External website adds script tag; widget renders courses.

### Plan Gating UX Pattern
- **Free users**: Show paid features as disabled with upgrade tooltip
  - Theme selector shows 1 option with "Upgrade to unlock more themes" on hover
  - Custom color picker disabled with "Upgrade to customize colors" tooltip
  - Custom CSS textarea shows lock icon with upgrade CTA
  - "Powered by Classroomio" toggle is locked ON with tooltip
- **Paid users**: Full access to all controls, branding toggle available

## Open Questions (Resolved)
1. ✅ **Free plan color tweaks** – **1 preset theme only** (default). Paid users get all preset themes (3-5) plus custom color picker.
2. ✅ **Events endpoint** – Deferred to Phase 2; schema reserved but not implemented in v1.
3. ✅ **Locale detection** – Deferred to Phase 2; widgets use single-language labels from org default locale in v1.
4. ✅ **CSS isolation** – **Shadow DOM custom element** preferred for strongest isolation. Fallback to scoped classes only if Shadow DOM causes critical theming issues during Phase C testing.

## Additional Architecture Decisions

### Widget Key Format
- Format: `wgt_<base58(16-bytes-random)>`
- Example: `wgt_3J98t1WpEZ73CNmYv`
- Includes implicit typo detection via base58 checksum behavior
- Length: 23 characters (prefix + 16 chars)

### Rollback Mechanics
- Rollback is **pointer-swap**, not append-only
- `latest_published_version_id` points to any previous version
- No new version created on rollback
- Analytics remain tied to version ID (history preserved)
- UI shows version history (read-only) with "Restore to this version" action

### Caching Strategy
- Public payload endpoint: `Cache-Control: public, max-age=60, stale-while-revalidate=300`
- Widget JS/chunk artifacts: `Cache-Control: public, max-age=31536000, immutable`
- Bootstrap script: short TTL + revalidation so new chunk references propagate quickly after publish

## Expanded TODOs (Priority)

### TODO-2: Iframe Protocol Spec (Detailed)

#### Message Types
```typescript
// Parent → Iframe
type ParentMessage = 
  | { type: 'WIDGET_PREVIEW_RENDER'; payload: WidgetPayload; requestId: string }
  | { type: 'WIDGET_PREVIEW_PING' }; // health check

// Iframe → Parent
type IframeMessage =
  | { type: 'WIDGET_PREVIEW_READY'; iframeId: string; timestamp: number }
  | { type: 'WIDGET_PREVIEW_RENDERED'; requestId: string; timestamp: number }
  | { type: 'WIDGET_PREVIEW_ERROR'; requestId: string; error: string; timestamp: number }
  | { type: 'WIDGET_PREVIEW_RESIZE'; height: number; width?: number }
  | { type: 'WIDGET_PREVIEW_CTA_CLICK'; courseId: string }; // for preview interactivity
```

#### Payload Envelope
```typescript
interface WidgetPayload {
  version: 'v1';
  widgetId: string;
  layoutType: 'cards' | 'table' | 'primary_course' | 'carousel' | 'tag_filter';
  courses: Course[];
  design: DesignConfig;
  planGatedFields: PlanGatedFields;
  timestamp: number; // epoch ms for cache-busting
}
```

#### Security Rules
1. **Origin Validation**:
   - Production: `targetOrigin` must match `VITE_DASHBOARD_URL` (e.g., `https://app.classroomio.com`)
   - Development: allow `http://localhost:*` with port wildcard
   - Never use `*` in production
   
2. **Message Validation**:
   - Reject messages without `type` field
   - Reject unknown message types
   - Validate payload schema with Zod before processing

3. **iframe Sandboxing**:
   - Use `sandbox="allow-scripts"` attribute
   - No `allow-same-origin` (prevents cookie access)

#### Reliability Rules
1. **Handshake Flow**:
   ```
   Parent: mount iframe → wait for READY (timeout: 5s)
   Iframe: mount complete → send READY
   Parent: receive READY → send RENDER with payload
   Iframe: render complete → send RENDERED or ERROR
   ```

2. **Retry Logic**:
   - READY timeout: 3 retry attempts, exponential backoff (1s, 2s, 4s)
   - RENDERED timeout: 2 retry attempts, show error state in parent

3. **Error Handling**:
   - Render errors: Show fallback UI in parent ("Preview unavailable")
   - Log error details to console with `[WidgetPreview]` prefix
   - Surface user-friendly error in editor UI

#### Sequence Diagram
```
Parent (Dashboard)          Iframe (Widget Runtime)
       |                              |
       |--- mount iframe ------------>|
       |                              |
       |<-- WIDGET_PREVIEW_READY -----|
       |    (iframe ready)            |
       |                              |
       |--- WIDGET_PREVIEW_RENDER --->|
       |    (payload + config)        |
       |                              |
       |<-- WIDGET_PREVIEW_RESIZE ----|
       |    (dynamic height)          |
       |                              |
       |<-- WIDGET_PREVIEW_RENDERED --|
       |    OR WIDGET_PREVIEW_ERROR   |
```

#### Documentation Output
- Spec file: `prd/course-widget-embed [DONE]/iframe-protocol.md` (this section)
- Implementation: `apps/embeds/src/widgets/course-widget/preview/iframe-bridge.ts` + `apps/dashboard/src/lib/features/widget/preview/iframe-parent.ts`

### TODO-3: Preview Data Freshness (Implementation Details)

#### Freshness States
| State | Indicator | User Action | Behavior |
|-------|-----------|-------------|----------|
| `fresh` | Green dot + "Live" | None | Data synced with server within last 5 minutes |
| `stale` | Yellow dot + "Refresh suggested" | Manual refresh button | Data older than 5 minutes or tab was backgrounded |
| `refreshing` | Spinner + "Syncing..." | Disabled | Fetch in progress |
| `error` | Red dot + "Sync failed" | Retry button | Last fetch failed, using cached data |

#### Implementation Rules
1. **Initial Load**: `+page.server.ts` provides hydrated data with `serverTimestamp`
2. **Stale Detection**:
   - Check `Date.now() - lastSyncTime > 5 * 60 * 1000` on mount
   - Listen to `visibilitychange` event: when tab becomes visible, check staleness
3. **Background Sync**:
   - Use `navigator.sendBeacon` or `fetch` with `keepalive` for refresh
   - Debounce refresh calls (minimum 30s between requests)
4. **Warning UX**:
   - Non-blocking toast when stale data detected
   - Course/tag removed warning appears in preview area (not blocking)
5. **Consistency**:
   - Draft state is never auto-refreshed; only source data (courses/tags list)
   - User must explicitly refresh to see new courses/tags

#### State Machine
```
         initial load
[empty] ----------> [fresh]
                       |
            5min timeout | visibility change
                       v
                   [stale] <------.
                       |          |
            manual or |          | error
            auto refresh          |
                       v          |
                  [refreshing] ----'
                       |
            success |  | failure
                 |     |
                 v     v
              [fresh] [error]
                 ^       |
                 '-------'
                  retry
```

---

### TODO-4: CSS Sanitizer Implementation

#### Library Choice
- **Primary**: `css-tree` for parsing + whitelist validation
- **Backup**: `reworkcss` if `css-tree` bundle size exceeds 15KB

#### Validation Rules
```typescript
const CSS_SANITIZER_CONFIG = {
  maxSizeBytes: 5120, // 5KB
  
  // Allowed at-rules
  allowedAtRules: ['media', 'supports', 'keyframes', '-webkit-keyframes'],
  
  // Blocked at-rules (security)
  blockedAtRules: ['import', 'charset', 'namespace', 'font-face', 'page', 'document'],
  
  // Allowed properties (whitelist approach)
  allowedProperties: [
    // Layout
    'display', 'position', 'top', 'right', 'bottom', 'left',
    'flex', 'flex-direction', 'flex-wrap', 'flex-grow', 'flex-shrink', 'flex-basis',
    'justify-content', 'align-items', 'align-content', 'gap', 'row-gap', 'column-gap',
    'grid', 'grid-template', 'grid-column', 'grid-row', 'grid-area',
    // Box model
    'width', 'height', 'min-width', 'min-height', 'max-width', 'max-height',
    'margin', 'margin-top', 'margin-right', 'margin-bottom', 'margin-left',
    'padding', 'padding-top', 'padding-right', 'padding-bottom', 'padding-left',
    'border', 'border-radius', 'box-sizing', 'overflow', 'overflow-x', 'overflow-y',
    // Visual
    'color', 'background', 'background-color', 'background-image', 'background-size',
    'background-position', 'background-repeat', 'opacity', 'box-shadow',
    'border-color', 'border-width', 'border-style', 'border-top', 'border-right',
    // Typography
    'font-family', 'font-size', 'font-weight', 'font-style', 'line-height',
    'text-align', 'text-decoration', 'text-transform', 'letter-spacing', 'word-spacing',
    'white-space', 'word-break', 'overflow-wrap',
    // Effects
    'transform', 'transition', 'animation', 'filter', 'backdrop-filter'
  ],
  
  // Blocked values (regex patterns)
  blockedValuePatterns: [
    /javascript:/i,
    /expression\s*\(/i,
    /behavior\s*:/i,
    /binding\s*:/i,
    /-moz-binding/i,
    /url\s*\(\s*["']?\s*data:/i, // data URIs (potential XSS)
  ],
  
  // Special property validations
  propertyValidators: {
    'position': (value: string) => value !== 'fixed', // No fixed positioning
    'background-image': (value: string) => !value.includes('url') || value.startsWith('url(https://')
  }
};
```

#### Error Handling
- Invalid CSS is stripped silently (not rejected entirely)
- User sees warning: "Some CSS rules were removed for security"
- Log sanitized rules to console in dev mode only

---

### TODO-5: Accessibility Requirements (v1)

#### Keyboard Navigation
- Tab order: logical flow through course cards
- Enter/Space: activate CTA buttons
- Escape: close any open modals/filter dropdowns

#### Screen Reader Support
- Course cards: `role="article"` with `aria-labelledby` pointing to title
- CTA buttons: descriptive `aria-label` (e.g., "View Introduction to Python course")
- Filter badges: `aria-pressed` state for active filters
- Live regions: announce filter results changes (`aria-live="polite"`)

#### Visual Requirements
- Focus indicators: 2px solid outline with 2px offset (using `:focus-visible`)
- Color contrast: minimum 4.5:1 for text (validated in design tokens)
- Reduced motion: respect `prefers-reduced-motion` for carousel animations

---

### TODO-6: Bundle Size Enforcement

#### CI Configuration
```yaml
# apps/embeds/bundle-size.json
{
  "limits": {
    "course-widget.js": "3kb",
    "course-widget-runtime.js": "35kb"
  },
  "failOnViolation": true
}
```

#### Build Script
```bash
#!/bin/bash
# apps/embeds/scripts/check-bundle-size.sh

max_size_loader=$((3 * 1024))     # 3KB
max_size_runtime=$((35 * 1024))   # 35KB

loader_size=$(gzip -c dist/course-widget.js | wc -c)
runtime_size=$(gzip -c dist/course-widget-runtime.js | wc -c)

if [ $loader_size -gt $max_size_loader ]; then
  echo "❌ Loader exceeds budget: ${loader_size}B > ${max_size_loader}B"
  exit 1
fi

if [ $runtime_size -gt $max_size_runtime ]; then
  echo "❌ Runtime exceeds budget: ${runtime_size}B > ${max_size_runtime}B"
  exit 1
fi

echo "✅ Bundle sizes within budget"
```

## Success Criteria
1. Admin can publish a widget and embed it externally in under 5 minutes.
2. Embed snippet works across static HTML, React, and WordPress hosts.
3. Runtime stays within performance budget and has no host CSS collisions.
4. Support tickets for “embed broken by host CSS” remain near zero.
5. Dashboard live preview matches public embed rendering for the same payload and version.
6. **Accessibility**: Widgets are keyboard-navigable (Tab order, Enter/Space to activate CTAs) and screen-reader friendly (ARIA labels on course cards, alt text on images).
7. **Security**: Zero XSS vectors through custom CSS or malformed payloads in penetration testing.