refactor(three-sixty-viewer): migrate the iDevice to TypeScript

[erseco]

Internal PR — base and head both live in ateeducacion/exelearning
(main ← refactor/three-sixty-viewer-typescript). Nothing here targets
exelearning/exelearning.

Summary

Full TypeScript refactor of the 360° Viewer iDevice
(public/files/perm/idevices/base/three-sixty-viewer/):

• All maintained JavaScript (≈3 100 lines across two mirrored classic scripts)
  moves into a typed, modular src/ tree (shared/, viewer/, edition/,
  export/, test/), compiled by the centralized TypeScript-iDevice build
  convention selectively reused from upstream PR
  exelearning/exelearning#2147
  (ADR-0006).
• The generated edition/three-sixty-viewer.js and
  export/three-sixty-viewer.js bundles (+ source maps) are not committed
  — they are gitignored and rebuilt by bun run bundle:idevices /
  build:all, and shipped to E2E CI runners via the build artifact.
• The duplicated state normalization/geometry that edition and export each
  carried is replaced by one shared implementation; the persisted format
  is unchanged and the v1 → v2 migration remains fully supported.

Architecture

src/
├── shared/    document model, hydration (v1/v2/future), normalization,
│              hotspot actions (discriminated union + explicit
│              UnsupportedHotspotAction), geometry, ids, urls, html
├── viewer/    browser layer shared by editor preview AND learner runtime:
│              panorama renderer (owns every WebGL resource), flat-image
│              renderer (letterbox-aware), hotspot overlay, scene controller,
│              nav/fullscreen/drag-capture controls, render-loop + disposer
│              lifecycle, asset:// resolution
├── edition/   window.$exeDevice — device bridge over an explicit Editor
│              instance: typed state store, pure form builders (all legacy
│              control ids preserved), scene list/editor, hotspot list +
│              per-action editors, placement controller, preview, asset picker
├── export/    window.$threesixtyviewer — per-node instances in a
│              WeakMap-backed registry; accessible content modal; safe link
│              opening; WebGL/three.js/no-image fallbacks
└── test/      structural THREE mock + manual frame scheduler, fixtures
               (v1 / v2 / future-version / invalid), bundle-contract specs

Both window globals are assigned explicitly by the entry points (the
workarea re-evaluates the edition script per edit session); nothing relies on
the bundler's globalName. Every runtime instance and every editor owns a
LIFO disposer bag — animation frames, WebGL resources (textures, geometry,
material, renderer), OrbitControls, observers, listeners and modal handlers
are all released on destroy(), and re-rendering a node disposes its
predecessor first. Multiple viewers on one page share no state.
prefers-reduced-motion disables autorotation in both the runtime and the
preview.

Build integration

Selectively applied from upstream PR exelearning#2147 (commits 085d7f9 + f29923e),
infrastructure only:

• scripts/build-idevices.ts + spec — convention-based builder
  (src/edition|export/index.ts → classic IIFE edition|export/<name>.js,
  per-iDevice strict tsconfig.json typecheck, --only/--watch/--typecheck,
  optional build.config.json manifest).
• Slide moves onto the central builder via build.config.json
  (scripts/build-slide-editor.ts removed); package.json gains
  typecheck:idevices / bundle:idevices / bundle:idevices:watch, wired
  into build:all before resource packaging so public/bundles/idevices.zip
  always contains fresh bundles (.map files are excluded from resource ZIPs).
• vitest.config.mts discovers TypeScript-iDevice specs and coverage by
  convention (public/files/perm/idevices/base/*/src/**), not by naming a
  single iDevice.
• Docs: ADR-0006 + doc/development/idevices-typescript.md (adapted to this
  repo's state); ADR-0001…0005 / SDD-0001 IDs stay reserved for the
  upstream Interactive Video PR so the two histories can merge without
  renumbering.
• Deliberately not cherry-picked: all Interactive Video sources, tests,
  schema/importer/workarea/SCORM changes, bun.lock churn and IV-specific
  ADRs/SDD.
• .github/workflows/e2e.yml ships the two generated bundles in the
  build-public artifact — a fresh CI checkout serves them without 404s.

Schema compatibility

• Persisted format unchanged: version: 2, ideviceId, startSceneId,
  scenes[] (id, title, src, alt, description, equirectangular/flat
  projection, initial yaw/pitch/fov, hotspots with yaw/pitch and x/y percent,
  labels, icons), behaviour (autorotate, zoom, fullscreen, nav controls,
  render quality, labels + position, brightness/contrast/saturation). All
  ranges, defaults and enum fallbacks match the legacy normalization.
• v1 single-image documents still migrate to a one-scene v2 tour with the
  exact legacy detection; nothing is lost (verified by fixtures and by an E2E
  test driving the real bundle's init → save).
• version > 2 is never rewritten: hydrateDocument() returns
  unsupported-version with the original payload intact; the editor shows an
  explanation and save() passes the payload through byte-for-byte; the
  runtime renders an accessible notice.
• Unknown hotspot actions are preserved, not converted to text: they
  become an explicit UnsupportedHotspotAction in memory and serialize back
  to their original wire form (lossless round-trip, covered by tests).

Hotspot authoring improvements

• Explicit placement mode: "Place hotspot by clicking" toggles
  aria-pressed, shows a hint, announces via an aria-live region, cancels
  with Escape, and ends after one placement. Equirectangular clicks are
  unprojected to yaw/pitch; flat clicks map to percentages of the contained
  image rectangle and clicks on letterbox bars are ignored instead of
  snapping to an edge. Numeric fields remain for precise adjustment;
  list-based creation is untouched.
• Inline validation next to the affected field (goToScene target must
  exist and differ from the current scene; links accept only safe schemes;
  image/video need a source) with text + icon, never colour alone.
• Scene deletion is reference-aware: a confirmation names how many
  goToScene hotspots point at the scene; accepting clears their targets
  deterministically and flags them for review — no silent dangling
  references.
• One selected hotspot row at a time, reflected in the list and the preview
  handles; dragging handles updates the row; save announces Saved. in the
  status region. Unsafe link URLs block saving (save() → false).

Accessibility

Keyboard-operable authoring controls with visible focus; labelled icon
buttons; aria-live status region; Escape closes the runtime modal and
cancels placement; modal focus trap + focus restoration to the trigger;
hotspots in exported content are real buttons operable via Enter/Space;
accessible fallbacks when WebGL/three.js/the image are unavailable;
reduced-motion support; no colour-only meaning.

Tests

• 284 colocated Vitest specs under the iDevice's src/ (shared schema/
  migration/normalization/geometry/actions, viewer, export runtime, editor,
  placement, bundle contracts) + 8 builder specs (bun test scripts/build-idevices.spec.ts). The old eval-based *.test.js pairs are
  replaced without losing behavioural coverage.
• Bundle-contract specs evaluate the real generated IIFEs: classic-script
  shape, both window globals and APIs, safe evaluation without THREE,
  re-evaluation contract, and a v1-open → v2-save round-trip.
• Playwright: the spec grows from 8 to 14 scenarios — configuration
  persistence, flat projection, link hotspots, second scene + start scene
  persistence, goToScene editing, placement mode (aria-pressed/Escape/click
  placement/letterbox ignore), reference-aware scene deletion, bundle
  contracts, v1 → v2 through the real bundle. Repeated reopen-after-reload
  boilerplate got a shared helper.
• Coverage (v8, statements/lines): shared/ 99.6 %/100 %, viewer/
  95.4 %/95.9 %, export/ 96.1 %/97.5 %, edition/ 92.8 %/96.1 %. The two
  bundle entry points are excluded by convention (exercised as compiled IIFEs
  by the bundle-contract specs — v8 cannot instrument them through imports).

Verification

All executed on this branch:

• make fix — clean (2 pre-existing warnings untouched).
• bun test scripts/build-idevices.spec.ts — 8/8.
• bun run typecheck:idevices and bun run bundle:idevices — green; slide +
  three-sixty-viewer build through the one convention.
• bun x vitest run public/files/perm/idevices/base/three-sixty-viewer/src —
  284/284.
• make test-frontend (full Vitest suite) — 13 823 tests, 0 failures.
• make test-integration — 721/721.
• make test-unit — frontend green; backend has pre-existing environmental
  failures unrelated to this PR (verified identical on the unmodified
  main base commit): src/routes/api/v1/assets.spec.ts (SQLite migration
  002 fails in the dev container), src/cli/commands/elp-convert.spec.ts
  ("/root must not be writable" — the container runs as root) and one
  order-dependent src/routes/api/convert.spec.ts case that passes in
  isolation.
• bun x playwright test --project=chromium …/three-sixty-viewer.spec.ts —
  14/14. The COMPLETE chromium E2E suite could not finish in the
  development container (three attempts each crashed the container under
  load — resource exhaustion unrelated to this change); it relies on the CI
  run of this PR, which now also receives the generated bundles as build
  artifacts.
• Clean-build check: deleting both generated bundles and running
  bun scripts/build-idevices.ts --only three-sixty-viewer --typecheck
  regenerates them; git status stays clean (bundles and maps ignored) and
  public/bundles/idevices.zip contains the bundle but no .map files.

Known limitations

• Hotspot drag on equirectangular scenes and WebGL rendering are covered by
  unit tests against a structural THREE mock plus manual E2E; no automated
  pixel-level WebGL assertions (deliberate — they are unreliable in CI).
• The editor still rebuilds the whole form on projection toggle (legacy
  behaviour, kept intentionally to swap the renderer + per-mode fields).
• Backend suite failures listed above are environmental and pre-date this
  branch.

Follow-ups

• When upstream PR [proposal] Refactor interactive-video iDevice exelearning/exelearning#2147 lands, the reserved ADR-0001…0005 / SDD-0001 IDs and
  the interactive-video build entries merge in without conflicts with this
  branch's ADR-0006/SDD-0002 usage.
• Hotspot icon choices beyond the current circle and per-hotspot colour
  themes would slot into shared/types.ts + hotspot-renderer.ts without a
  schema bump.
• doc/development/idevices-typescript.md §Testing suggests adding new
  iDevice spec globs; with the convention-based Vitest config this is now
  automatic and the guide could drop that step.

Docs: adds SDD-0002 (360° Viewer TypeScript architecture), reuses ADR-0006
and the TypeScript-iDevices guide from upstream.

---

Generated by Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 87.25383% with 233 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
...ase/three-sixty-viewer/src/edition/hotspot-list.ts	69.69%	28 Missing and 32 partials ⚠️
...ces/base/three-sixty-viewer/src/edition/preview.ts	82.41%	10 Missing and 22 partials ⚠️
...ices/base/three-sixty-viewer/src/edition/editor.ts	81.94%	9 Missing and 17 partials ⚠️
...three-sixty-viewer/src/viewer/panorama-renderer.ts	84.29%	7 Missing and 12 partials ⚠️
...evices/base/three-sixty-viewer/src/export/modal.ts	89.89%	1 Missing and 9 partials ⚠️
...ces/base/three-sixty-viewer/src/export/instance.ts	88.15%	1 Missing and 8 partials ⚠️
...ase/three-sixty-viewer/src/edition/scene-editor.ts	86.20%	0 Missing and 8 partials ⚠️
...ase/three-sixty-viewer/src/edition/three-loader.ts	84.00%	4 Missing and 4 partials ⚠️
...ices/base/three-sixty-viewer/src/export/runtime.ts	78.37%	2 Missing and 6 partials ⚠️
...es/base/three-sixty-viewer/src/viewer/lifecycle.ts	85.41%	5 Missing and 2 partials ⚠️
... and 17 more

📢 Thoughts on this report? Let us know!

[codecov]

Bundle Report

Bundle size has no change ✅