Canonical instruction file for all AI coding agents working on this repository.

eXeLearning is an open-source (AGPL-3.0) educational content authoring tool. Educators create interactive learning materials and export them as SCORM 1.2/2004, HTML5, EPUB3, or IMS Content Packages. The new backend runs on Bun + Elysia + Kysely with Yjs for real-time collaboration. The frontend is vanilla JavaScript. Desktop builds use Electron.

Current state: Early development. Prioritize clean, well-organized code.

Before any change is submitted (PR, commit push, or handoff), all of the following must hold:

1. make fix passes — lint and formatting are clean.
2. Unit tests pass — make test-unit is green (backend bun test + frontend vitest).
3. Integration tests pass — make test-integration is green.
4. E2E tests pass — make test-e2e is green (Playwright). Run make test-e2e-static too if the change affects the static build, embedding, or export flow.
5. Patch coverage ≥ 90% — every new or modified line must be covered by a test. Check with make test-coverage and inspect the diff, not just the global percentage. If a line is genuinely untestable, justify it in the PR description.
6. New code ships with tests in the same PR. A new .ts file under src/ needs a colocated *.spec.ts; a new .js file under public/app/ needs a colocated *.test.js. User-visible flows need an E2E spec under test/e2e/playwright/specs/.
7. No skipped or disabled tests without an issue link and explanation.

These apply to every skill below. If you cannot meet them, stop and ask the user — do not submit partial work.

• No workarounds. Always build full, long-term-sustainable implementations for >1000 users. Never create compatibility shims or half-baked solutions.
• Do not remove existing features or UI options unless explicitly asked. Stub/annotate unfinished work instead of deleting it.
• Single source of truth. When two code paths need the same data, extract a shared function. Duplicated logic is a bug waiting to happen. Example: PR #1564.
• Extract testable pure functions. When fixing a bug in inline arithmetic or logic, extract it into a named function with edge-case handling. Example: PR #1546.
• Respect platform differences. File operations must work on Windows (EBUSY file locks), macOS, and Linux. Kill processes before deleting their files. Use path.join() always.

Critical: Frontend tests (public/) use Vitest. Backend tests (src/) use Bun test. Never swap them. Frontend tests fail with "window is not defined" under Bun.

make deps                       # Install dependencies (preferred over bun install)
cp .env.dist .env               # Create env file (auto-created by make check-env)
make up-local                   # Local dev server (web only)
make up-local APP_ENV=prod      # Local dev server (prod mode)
make run-app                    # Electron desktop app
make bundle                     # Build all assets (TS + CSS + JS)
make up                         # Docker dev environment

# Backend (single file)
bun test src/services/my-service.spec.ts

# Frontend (single file)
npx vitest run public/app/workarea/project/projectManager.test.js

# Frontend (specific test name)
npx vitest run public/app/path/file.test.js -t "test name"

# E2E (single file)
bun x playwright test --project=chromium test/e2e/playwright/specs/my-test.spec.ts

Patch coverage ≥ 90% is required on every PR, measured against the lines you added or modified — not the global project average. A PR that only raises global coverage but leaves new lines uncovered does not pass.

• Backend (src/): global target 90%, patch coverage ≥ 90% (hard gate).
• Frontend (public/app/): global target 80%, patch coverage ≥ 90% on changed lines.
• Every new .ts file under src/ must ship with a colocated *.spec.ts in the same PR.
• Every new .js file under public/app/ must ship with a colocated *.test.js in the same PR.
• User-visible behavior changes (workarea, preview, export, embedding, collaboration) must include or update a Playwright spec under test/e2e/playwright/specs/.
• Before submitting: run make fix && make test-unit && make test-integration && make test-e2e and inspect make test-coverage for the diff. All four must be green. E2E may be slow — budget time for it rather than skipping.
• Do not mark tests as .skip / .todo to land a PR. If a test cannot run in CI, open an issue and link it in the PR description.

Avoid mock.module() in Bun tests — it can cause test pollution. The project uses a DI pattern instead:

// Source file: export configure/resetDependencies
export function configure(newDeps: Partial<Deps>): void { deps = { ...defaultDeps, ...newDeps }; }
export function resetDependencies(): void { deps = defaultDeps; }

// Spec file: inject mocks via DI
beforeEach(() => configure({ queries: { findById: mockFindById } }));
afterEach(() => resetDependencies());

See backend-service and backend-route skills for full details.

Always run make fix after any code changes. This runs Biome for both TypeScript and JavaScript.

Config: biome.json — 120 char line width, 4-space indent, single quotes, trailing commas, semicolons always.

Note: Biome formatter is disabled for public/app/** (legacy code). Linting still applies.

The Yjs Y.Doc in the browser is the canonical document state.

CLIENT (Browser)                        SERVER (Bun/Elysia)
─────────────────                       ────────────────────
YjsDocumentManager (Y.Doc)              SessionManager: lightweight metadata
├── navigation (Y.Array)                WebSocket: stateless relay
├── metadata (Y.Map)                    Database: projects + yjs snapshots
├── assets (Y.Map)                      Filesystem: FILES_DIR/assets/{uuid}/
└── themeFiles (Y.Map)

• ELP extraction and export generation happen client-side by default
• Server stores assets permanently, persists Yjs snapshots, relays WebSocket
• Server-side exports are used by CLI commands and the external API
• REST API v1 (/api/v1/*) is designed for external integrations — internal frontend uses Yjs + WebSocket instead

Every opened project gets a UUID session ID. Server maintains lightweight in-memory Map<sessionId, ProjectSession>.

Client-side storage:

FILES_DIR resolution: ELYSIA_FILES_DIR (tests) → FILES_DIR (.env) → ./data/ (fallback).

FILES_DIR/
├── assets/{projectUuid}/           # Permanent project assets
├── tmp/{year}/{month}/{day}/{id}/  # Temporary files
├── dist/{year}/{month}/{day}/{id}/ # Ready-to-download exports
├── chunks/                         # Upload chunks
├── themes/site/                    # Custom themes
└── exelearning.db                  # SQLite DB (if pdo_sqlite)

Key rules:

• Directories created lazily (on-demand), never eagerly
• Assets use project UUID, not numeric ID
• Always use isPathSafe() for user-supplied paths
• Use path.join() for cross-platform paths

• i18n: _() for GUI strings, c_() for content strings, | trans in Nunjucks templates. Avoid hardcoded English. See i18n skill.
• Styles: Prefer SCSS classes in assets/styles/ over inline styles. See doc/development/styles.md.
• No framework: Vanilla JavaScript in public/app/.

• Routes: Elysia plugins with { prefix: '/api/...' }, registered in src/index.ts via .use()
• Queries: Kysely functions always take db parameter (dependency injection)
• Migrations: Sequential numbering in src/db/migrations/, must work across SQLite/PostgreSQL/MariaDB
• ZIP: JSZip for extraction, Archiver for creation. Check zipEntry.dir before reading.

Service Worker (public/preview-sw.js) intercepts /viewer/* requests. Html5Exporter.generateForPreview() generates files in memory, sends to SW via postMessage, iframe loads from SW cache.

ZIP archives containing content.xml (modern) or contentv3.xml (legacy). Legacy .elp files from pre-v3.0 must be supported — handled client-side by ElpxImporter.importLegacyFormat().

Two paths exist. The primary path is entirely browser-side; the server never parses ELP files in the normal flow.

1. Primary (browser, direct import): User selects .elp/.elpx → browser imports in memory via Yjs (importElpDirectly → importFromElpxViaYjs) → UI refreshes from Y.Doc → saved to server on explicit save/autosave.
2. Fallback (chunked upload): Browser uploads in 15 MB chunks to POST /api/project/upload-chunk → server concatenates into temp file (no parsing) → browser reloads workarea with ?import=... and imports client-side → browser calls DELETE /api/project/cleanup-import to remove temp file.

Key rule: the server is a temp store in the fallback path. The browser is always responsible for importing into Yjs.

The UI tries browser-side first, falling back to server-side.

1. Primary (browser): UI triggers export → SharedExporters generates ZIP in memory → browser downloads (web) or Electron saves to disk.
2. Fallback (server): Browser POSTs to /api/export/:sessionId/:exportType/download → server builds Y.Doc from DB/structure, runs exporters, writes ZIP to dist/ → streams back for download. Used by CLI commands and the external API.

Static editor embeds in LMS plugins (WordPress, Moodle, Drupal, Omeka-S) via iframe + postMessage. Key files: RuntimeConfig.js, Capabilities.js, EmbeddingBridge.js, app.js, previewPanel.js, main.scss. See doc/development/embedding.md.

Configure via .env file (use .env.dist as template).

Use built-in debug flags before adding ad-hoc logs.

ELPX export timing:

window.eXeLearning.config.debugElpxExport = true;
// After export: window.__lastElpxExportSummary, window.__lastElpxExportTimeline

Save memory profiling:

window.eXeLearning.config.debugSaveMemory = true;
// After save: window.__lastSaveMemorySummary, window.__lastSaveMemoryTimeline

Full details: doc/development/profiling.md

Credentials: user@exelearning.net / 1234

Fixtures: test/fixtures/ and test/fixtures/xml/

Helpers (test/e2e/playwright/helpers/workarea-helpers.ts): waitForAppReady, openElpFile, saveProject, openPreviewPanel, getPreviewFrame, addIdevice, editIdevice, saveIdevice, deleteIdevice, expandIdeviceCategory

Key selectors:

// Login
'input[type="email"]', 'input[type="password"]', 'button[type="submit"]'
// Workarea
'#head-bottom-preview', '#head-top-save-button'
// Preview
'#preview-iframe' (frameLocator), 'article', 'nav a[href*="html/"]'

Guidelines:

• Prefer deterministic waits (waitForFunction, waitFor) over waitForTimeout() for async operations
• Each test should create its own project for isolation
• Use helpers from workarea-helpers.ts to avoid duplication
• Review existing specs in test/e2e/playwright/specs/ for patterns
• See e2e-test skill for full details

Domain-specific guidance lives in .agents/skills/*/SKILL.md.