refactor(three-d-viewer): migrate iDevice to TypeScript

.agents/skills/idevice/SKILL.md

@@ -23,6 +23,25 @@ Creating or modifying interactive devices (iDevices) in `public/files/perm/idevi
 
 **Reference iDevices** (well-tested, good to study): `checklist`, `rubric`, `geogebra-activity`
 
+## TypeScript iDevices (`src/`)
+
+An iDevice with a `src/` directory is a **TypeScript iDevice**: its
+`edition/<name>.js` and `export/<name>.js` are GENERATED bundles (gitignored)
+— never edit them; edit `src/` and rebuild. Convention and commands:
+
+- `src/edition/index.ts` → `edition/<name>.js` (assigns `window.$exeDevice`);
+  `src/export/index.ts` → `export/<name>.js` (assigns the runtime global).
+- Build/typecheck: `bun run bundle:idevices` / `bun run typecheck:idevices`
+  (central runner `scripts/build-idevices.ts`; `--only <name>`, `--watch`).
+  Run `make bundle` after src/ edits and BEFORE E2E, or the preview serves the
+  stale bundle from `public/bundles/idevices.zip`.
+- Tests are colocated `*.spec.ts` (Vitest — `bun test` ignores `public/**`),
+  plus bundle-contract smoke tests over the compiled IIFEs.
+- Deviations (custom bundle name, externals, minify) go in an optional
+  `build.config.json` — see `doc/development/idevices-typescript.md` and
+  ADR-2147-01. Reference implementations: `three-d-viewer` (full convention),
+  `slide` (manifest).
+
 ## Structure
 
 ```

.github/workflows/e2e.yml

@@ -47,6 +47,9 @@ jobs:
       - name: Build all assets once
         run: bun run build:static
 
+      # The path list must include every GENERATED (gitignored) file the
+      # workarea serves — the test runners get a fresh checkout, so anything
+      # missing here 404s at runtime (e.g. TypeScript-iDevice bundles, ADR-2147-01).
       - name: Upload dynamic bundles (chromium/firefox)
         uses: actions/upload-artifact@v7
         with:
@@ -65,6 +68,8 @@ jobs:
             public/bundles/**
             public/style/workarea/main.css
             public/files/perm/idevices/base/slide/edition/slide-editor.bundle.js
+            public/files/perm/idevices/base/three-d-viewer/edition/three-d-viewer.js
+            public/files/perm/idevices/base/three-d-viewer/export/three-d-viewer.js
 
       - name: Upload static distribution (static project)
         uses: actions/upload-artifact@v7

.gitignore

@@ -106,7 +106,10 @@ symfony.lock
 .phpunit.cache
 .idea/
 
-runtime/
+# Anchored to the repository root: an unanchored `runtime/` also matches source
+# directories named `runtime` at any depth (e.g. a TypeScript iDevice's
+# `src/runtime/`) and silently drops them from commits.
+/runtime/
 symfony_legacy
 nestjs_legacy
 test-results/
@@ -134,8 +137,12 @@ public/app/dist/
 /app/dist/
 /app/node_modules/
 
-# Slide iDevice — pre-built editor bundle (regenerated by package.json postinstall)
+# TypeScript iDevice bundles — generated from each iDevice's src/ by scripts/build-idevices.ts
 /public/files/perm/idevices/base/slide/edition/slide-editor.bundle.js
+/public/files/perm/idevices/base/three-d-viewer/edition/three-d-viewer.js
+/public/files/perm/idevices/base/three-d-viewer/edition/three-d-viewer.js.map
+/public/files/perm/idevices/base/three-d-viewer/export/three-d-viewer.js
+/public/files/perm/idevices/base/three-d-viewer/export/three-d-viewer.js.map
 .omc/
 
 # Live-LMS harness working directories (see test/e2e/moodle/README.md)

AGENTS.md

@@ -37,6 +37,7 @@ These apply to every skill below. If you cannot meet them, stop and ask the user
 | `src/**/*.ts` | Backend | `bun test` | `make fix` |
 | `public/app/**/*.js` | Frontend | `vitest` | `make fix` |
 | `public/files/perm/idevices/**` | iDevice | `vitest` | `make fix` |
+| `public/files/perm/idevices/*/src/**` | iDevice (TypeScript, see [ADR-2147-01](doc/architecture/adr/ADR-2147-01-typescript-idevices-build-convention.md)) | `vitest` (`*.spec.ts`) | `make fix` |
 | `src/shared/export/**` | Exporter | `bun test` | `make fix` |
 | `src/db/migrations/**` | Database | `bun test` | `make fix` |
 | `src/routes/api/v1/**` | API v1 | `bun test` | `make fix` |
@@ -91,6 +92,7 @@ make up                         # Docker dev environment
 | `public/app/**/*.test.js` | Frontend unit tests | `vitest` |
 | `public/libs/**/*.test.js` | Frontend lib tests | `vitest` |
 | `public/files/perm/idevices/**/*.test.js` | iDevice tests | `vitest` |
+| `public/files/perm/idevices/*/src/**/*.spec.ts` | TypeScript iDevice tests | `vitest` |
 | `test/e2e/playwright/specs/*.spec.ts` | E2E tests | `playwright` |
 
 ### 5.2 Running Individual Tests
@@ -352,6 +354,7 @@ Domain-specific guidance lives in `.agents/skills/*/SKILL.md`.
 | REST API v1 | [doc/development/rest-api.md](doc/development/rest-api.md) |
 | Embedding in LMS | [doc/development/embedding.md](doc/development/embedding.md) |
 | Profiling | [doc/development/profiling.md](doc/development/profiling.md) |
+| TypeScript iDevices | [doc/development/idevices-typescript.md](doc/development/idevices-typescript.md) |
 | Styles/Themes | [doc/development/styles.md](doc/development/styles.md) |
 | Conventions | [doc/conventions.md](doc/conventions.md) |
 | Architecture | [doc/architecture.md](doc/architecture.md) |

Makefile

@@ -567,7 +567,10 @@ test-frontend: check-bun check-env bundle ## Run frontend tests (with Vitest + h
 	bun test:frontend
 
 .PHONY: test-unit-ci
-test-unit-ci: check-bun check-tests check-env ## Run unit tests with lcov coverage for CI/Codecov
+# Depends on `bundle` for the same reason test-unit/test-integration/test-frontend
+# do: backend tests assert against generated assets (e.g. the TypeScript iDevice
+# bundles), which are not committed.
+test-unit-ci: check-bun check-tests check-env bundle ## Run unit tests with lcov coverage for CI/Codecov
 	@echo "Running unit tests with lcov coverage..."
 	@mkdir -p coverage/bun
 	$(TEST_ENV) bun test:unit:ci

doc/architecture/adr/ADR-2147-01-typescript-idevices-build-convention.md

@@ -0,0 +1,121 @@
+---
+id: ADR-2147-01
+title: "TypeScript iDevices: src/ sources compiled by one convention-based build"
+status: Proposed
+date: 2026-07-30
+tracking_issue: 2147
+deciders:
+  - "@erseco"
+reviewers:
+  - "@mnunezcedec"
+  - "@cristinavaldera"
+related:
+  prs: [2147]
+  changes:
+    - "2153-three-d-viewer-interactions"
+  adrs: []
+supersedes: []
+superseded_by: []
+ai_assistance:
+  tool: "Claude Code"
+  model: "claude-fable-5"
+---
+
+# ADR-2147-01: TypeScript iDevices: src/ sources compiled by one convention-based build
+
+## Context
+
+iDevices are classic-script objects loaded by the workarea and the exporters.
+Historically each one is hand-written vanilla JavaScript committed directly
+under `edition/` and `export/`. Two iDevices now keep their maintained source
+in TypeScript instead — Slide (`src/` + a bespoke `scripts/build-slide-editor.ts`)
+and Interactive Video (`src/` + a bespoke `scripts/build-interactive-video.ts`).
+Two per-iDevice build scripts with duplicated Bun plumbing were already
+diverging in flags and behaviour, and every future TypeScript iDevice would
+have added another copy plus more package.json entries.
+
+## Problem
+
+How does the repository recognise, build, type-check and test an iDevice whose
+maintained source is TypeScript, without a new build pipeline per iDevice?
+
+## Decision drivers
+
+- One obvious convention for the next TypeScript iDevice (zero new scripts).
+- The shipped output must remain plain classic-script IIFEs; the language and
+  compile step are not a framework.
+- Generated artifacts must never be committed; a clean checkout must
+  regenerate them through the existing pipeline (`build:all` / `make bundle`).
+- Existing iDevices with special needs (Slide) must fit without renaming their
+  shipped bundles.
+
+## Decision
+
+**An iDevice that keeps a `src/` directory is a TypeScript iDevice**, built by
+the centralized `scripts/build-idevices.ts`:
+
+- **Convention:** `src/edition/index.ts` → `edition/<name>.js` and
+  `src/export/index.ts` → `export/<name>.js` — self-contained IIFEs
+  (`target: browser`, linked source maps, unminified), whose entry points
+  explicitly assign their window globals (`$exeDevice`, `$<name>`).
+- **Escape hatch:** an optional `build.config.json` next to `config.xml`
+  replaces the convention for that iDevice (custom entries/naming/globalName/
+  minify/sourcemap, plus `externals` mapping bare imports to page-provided
+  globals so vendored libraries are never inlined). Slide uses it.
+- **Type checking:** each TypeScript iDevice ships its own `tsconfig.json`
+  (strict for new code); the runner executes `tsc -p` for every one it finds.
+- **Tests:** colocated `*.spec.ts` next to each module, run by **Vitest**
+  (`bun test` ignores `public/**`), plus bundle-contract smoke tests that
+  evaluate the compiled IIFEs.
+- **Artifacts:** generated bundles and source maps are gitignored;
+  `build:all` runs `typecheck:idevices` + `bundle:idevices` before
+  `bundle:resources` (export bundles ship inside `idevices.zip`).
+
+Package scripts: `typecheck:idevices`, `bundle:idevices`,
+`bundle:idevices:watch`; the runner accepts `--only <names>` and `--watch`.
+
+## Options considered
+
+### Option 1: One bespoke build script per TypeScript iDevice (status quo)
+
+Pros: each script is trivially readable. Cons: duplicated plumbing, per-iDevice
+package.json entries, drift between scripts (they already differed in
+sourcemaps, watch support and failure reporting).
+
+### Option 2: Convention-based central runner + per-iDevice manifest (chosen)
+
+Pros: the next TypeScript iDevice needs no build changes at all; one place to
+fix bundler behaviour; deviations are declared, not programmed. Cons: one more
+convention to know; the manifest is a small new format (documented in the
+runner header and `doc/development/idevices-typescript.md`).
+
+## Consequences
+
+### Positive
+
+- Adding a TypeScript iDevice = create `src/edition|export/index.ts` (+ a
+  strict `tsconfig.json`); building, type-checking and watching come for free.
+- Slide and Interactive Video share one build path; Slide's output stayed
+  byte-identical apart from the generic externals shim's message strings.
+
+### Negative
+
+- A hidden convention: `src/` now has meaning. Mitigated by this ADR,
+  `doc/development/idevices-typescript.md` and the idevice skill.
+
+### Neutral
+
+- Classic-script iDevices are untouched; nothing forces a migration.
+
+## Validation
+
+- `scripts/build-idevices.spec.ts` covers discovery, the convention, the
+  manifest and its validation against the real repository state.
+- `bun run build:all` exercises typecheck + build for every TypeScript
+  iDevice on every bundle/test target.
+
+## References
+
+- `scripts/build-idevices.ts` (runner; manifest schema in its header).
+- `doc/development/idevices-typescript.md` (developer guide).
+- PR [#2147](https://github.com/exelearning/exelearning/pull/2147).