v2.0.0 — @studiolxd/scorm: framework-agnostic core + multi-framework adapters

.github/workflows/angular-smoke.yml

@@ -0,0 +1,55 @@
+name: angular-smoke
+
+# Validates that @studiolxd/scorm/angular compiles in a real Angular AOT/production
+# build — the acceptance criterion for the decorator-free, plain-ESM adapter
+# (docs/PLAN-agnostic-core.md §5/§11). Targets the documented floor, Angular 17.
+
+on:
+  push:
+    branches: [main, feat/agnostic-core]
+    paths:
+      - 'packages/scorm/**'
+      - 'tests/angular-smoke/**'
+      - '.github/workflows/angular-smoke.yml'
+  pull_request:
+    paths:
+      - 'packages/scorm/**'
+      - 'tests/angular-smoke/**'
+      - '.github/workflows/angular-smoke.yml'
+
+jobs:
+  aot-build:
+    name: Angular 17 AOT build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install monorepo deps
+        # Remove the lockfile before installing to sidestep npm's cross-platform
+        # optional-dependency bug (npm/cli#4828): a lockfile generated on macOS makes
+        # npm skip the Linux rollup native binary tsup/rollup need on the runner.
+        # A fresh install resolves the correct platform binaries.
+        run: |
+          rm -f package-lock.json
+          npm install --no-audit --no-fund
+
+      - name: Build @studiolxd/scorm
+        run: npm run build --workspace=packages/scorm
+
+      - name: Pack the built library into the fixture
+        run: npm pack --workspace=packages/scorm --pack-destination tests/angular-smoke
+
+      - name: Install the Angular fixture (Angular 17 + the packed tarball)
+        working-directory: tests/angular-smoke
+        run: |
+          npm install
+          npm install ./studiolxd-scorm-*.tgz
+
+      - name: Angular production (AOT) build
+        working-directory: tests/angular-smoke
+        run: npx ng build --configuration production

AGENTS.md

@@ -0,0 +1,58 @@
+# AGENTS.md — working in this repository
+
+Guidance for AI coding agents (Claude Code, Cursor, Copilot, etc.) operating in this
+monorepo. For how to *use* the published library, see `packages/scorm/llms.txt`.
+
+## What this is
+
+`@studiolxd/scorm` — a headless SCORM 1.2 / 2004 runtime. npm workspaces monorepo:
+
+- `packages/scorm/` — the published library (`@studiolxd/scorm`).
+  - `src/` core is **framework-agnostic** (no framework imports outside `src/react`,
+    `src/vue`, `src/angular`, `src/svelte`, `src/wc`).
+  - Entry points map to subpaths: `.` (core+vanilla), `./react`, `./vue`,
+    `./angular`, `./svelte`, `./wc`. Built with `tsup` (ESM + CJS + IIFE).
+- `example/` — the single demo app (React + Vite). Not published.
+- `docs/` — planning + design docs.
+
+## Commands (run from repo root)
+
+- `npm run build` — build the library.
+- `npm run test` — run the library test suite (vitest).
+- `npm run dev:example` — run the demo at http://localhost:5173.
+- Per-package: `npm run typecheck --workspace=packages/scorm`.
+
+Always run `typecheck` + `test:run` + `build` in `packages/scorm` before committing.
+
+## Conventions
+
+- **TypeScript strict.** Every public symbol has JSDoc, ideally with an `@example`.
+- **`Result<T, ScormError>`** is the universal return type — never throw across the
+  public API (except `noLmsBehavior: 'throw'`). Check `.ok` before `.value`.
+- **Framework isolation.** Code in `src/` (outside the adapter folders) must not
+  import any framework. Adapters are thin bridges over `createScormSession` and the
+  vanilla `autoTerminate`/`autoCommit` helpers — put shared logic in the core, not
+  in an adapter.
+- **SSR-safe.** Guard any `window`/`document`/`HTMLElement` access with
+  `typeof … === 'undefined'`.
+- **Tests** live in `packages/scorm/tests/`, mirroring `src/`. Use mock mode
+  (`noLmsBehavior: 'mock'`) — no real LMS needed.
+
+## Adding a framework adapter
+
+1. Create `src/<framework>/index.ts` — bridge `session.on('change')` to the
+   framework's reactivity; reuse `autoTerminate`/`autoCommit`.
+2. Add the entry to `tsup.config.ts` and an `exports` subpath in `package.json`.
+3. Add the framework as an **optional** peerDependency (+ devDependency for builds).
+4. Add a test under `tests/adapters/`.
+
+## Release workflow
+
+See `docs/PLAN-agnostic-core.md` §7 and the version-bump steps: update CHANGELOG →
+`npm version` → commit → (publish is manual and gated on npm auth).
+
+## Do not
+
+- Do not introduce a framework dependency into the core.
+- Do not bundle framework deps (they are externalized/optional peers).
+- Do not read `.value` without checking `.ok`.

README.de.md

@@ -1,47 +1,66 @@
 🌐 [English](README.md) · [Español](README.es.md) · [Français](README.fr.md) · [Português](README.pt.md) · [Deutsch](README.de.md) · [Polski](README.pl.md)
 
-# @studiolxd/react-scorm
+# @studiolxd/scorm
 
-Monorepo, das die headless-Bibliothek `@studiolxd/react-scorm` für die SCORM-Laufzeitumgebung und eine interaktive Demo-App enthält, die alle Funktionen der Bibliothek zeigt.
+Monorepo für `@studiolxd/scorm` — eine Headless-Laufzeitumgebung für SCORM 1.2 / 2004 mit einem **frameworkunabhängigen Kern** und Adaptern für **React, Vue, Angular, Svelte, Web Components** sowie reines Vanilla-JS — inklusive einer interaktiven Demo-App.
+
+> Vormals `@studiolxd/react-scorm`. Die React-API befindet sich jetzt im Unterpfad `@studiolxd/scorm/react`.
 
 ## Pakete
 
-| Paket | Beschreibung |
-|-------|--------------|
-| [`@studiolxd/react-scorm`](./packages/react-scorm/) | Headless React + TypeScript Laufzeitbibliothek für SCORM 1.2 / 2004 | [README](./packages/react-scorm/README.md) |
-| [`example`](./example/) | Interaktive Demo-App — zeigt alle Funktionen der Bibliothek | [README](./example/README.md) |
+| Paket | Beschreibung | Doku |
+|---------|-------------|------|
+| [`@studiolxd/scorm`](./packages/scorm/) | Headless-Laufzeitumgebung für SCORM 1.2 / 2004 — unabhängiger Kern + Framework-Adapter | [README](./packages/scorm/README.md) |
+| [`example`](./example/) | Interaktive Demo-App — präsentiert jede Funktion der Bibliothek | [README](./example/README.md) |
 
 ## Erste Schritte
 
 ```bash
-npm install          # alle Workspaces vom Root aus installieren
-npm run dev:lib      # Bibliothek im Watch-Modus bauen
-npm run dev:example  # Entwicklungsserver der Demo starten (http://localhost:5173)
+npm install          # install all workspaces from the root
+npm run dev:lib      # build the library in watch mode
+npm run dev:example  # start the example dev server (http://localhost:5173)
 ```
 
-Weitere Skripte, die vom Root aus verfügbar sind:
+Weitere Skripte, die vom Stammverzeichnis aus verfügbar sind:
 
 - `npm run build` — baut die Bibliothek
-- `npm run test` — führt die Test-Suite der Bibliothek aus
+- `npm run test` — führt die Testsuite der Bibliothek aus
+
+## Einstiegspunkte
+
+Die Bibliothek ist ein einzelnes Paket mit Unterpfad-Exporten — importiere nur das, was du verwendest:
+
+| Import | Für |
+|--------|-----|
+| `@studiolxd/scorm` | Frameworkunabhängiger Kern + Vanilla (`createScormSession`) |
+| `@studiolxd/scorm/react` | React (`ScormProvider`, `useScorm`, …) |
+| `@studiolxd/scorm/vue` | Vue 3.3+ (`useScorm`) |
+| `@studiolxd/scorm/angular` | Angular 17+ (`provideScorm`, `SCORM`) |
+| `@studiolxd/scorm/svelte` | Svelte 4+ (`createScormStore`) |
+| `@studiolxd/scorm/wc` | `<scorm-session>` Web Component |
+| `window.Scorm` (CDN `<script>`) | Reines HTML, kein Bundler |
 
 ## Projektstruktur
 
 ```
 react-scorm/
-├── package.json          # npm-workspaces-Root (privat)
+├── package.json          # npm workspaces root (private)
 ├── packages/
-│   └── react-scorm/      # @studiolxd/react-scorm — auf npm veröffentlicht
-│       └── README.md     # vollständige Bibliotheksdokumentation
-└── example/              # interaktive Demo (nicht veröffentlicht)
-    └── README.md         # Demo-Dokumentation
+│   └── scorm/            # @studiolxd/scorm — published to npm
+│       └── README.md     # full library documentation
+├── example/              # interactive demo (not published)
+│   └── README.md         # demo documentation
+├── skills/               # AI agent skills (Claude Code, Cursor, …)
+├── tests/angular-smoke/  # Angular AOT smoke test fixture
+└── docs/                 # design & planning docs
 ```
 
 ## Veröffentlichung
 
-Nur `packages/react-scorm` wird auf npm veröffentlicht. Der `example`-Workspace und der Root sind privat. Zur Veröffentlichung:
+Nur `packages/scorm` wird auf npm veröffentlicht. Der `example`-Workspace und das Stammverzeichnis sind privat. So wird veröffentlicht:
 
 ```bash
-cd packages/react-scorm
+cd packages/scorm
 npm publish
 ```
 

README.es.md

@@ -1,47 +1,66 @@
 🌐 [English](README.md) · [Español](README.es.md) · [Français](README.fr.md) · [Português](README.pt.md) · [Deutsch](README.de.md) · [Polski](README.pl.md)
 
-# @studiolxd/react-scorm
+# @studiolxd/scorm
 
-Monorepo que contiene la librería headless `@studiolxd/react-scorm` para el runtime de SCORM y una aplicación de demostración interactiva que muestra todas las funcionalidades.
+Monorepo de `@studiolxd/scorm` — un runtime SCORM 1.2 / 2004 headless con un **núcleo agnóstico al framework** y adaptadores para **React, Vue, Angular, Svelte, Web Components** y JavaScript vanilla — además de una aplicación de demostración interactiva.
+
+> Antes `@studiolxd/react-scorm`. La API de React vive ahora en el subpath `@studiolxd/scorm/react`.
 
 ## Paquetes
 
-| Paquete | Descripción |
-|---------|-------------|------|
-| [`@studiolxd/react-scorm`](./packages/react-scorm/) | Librería headless React + TypeScript para el runtime de SCORM 1.2 / 2004 | [README](./packages/react-scorm/README.md) |
-| [`example`](./example/) | Aplicación de demostración interactiva — muestra todas las funcionalidades de la librería | [README](./example/README.md) |
+| Paquete | Descripción | Documentación |
+|---------|-------------|---------------|
+| [`@studiolxd/scorm`](./packages/scorm/) | Runtime SCORM 1.2 / 2004 headless — núcleo agnóstico + adaptadores de framework | [README](./packages/scorm/README.md) |
+| [`example`](./example/) | Aplicación de demostración interactiva — muestra todas las funciones de la librería | [README](./example/README.md) |
 
 ## Primeros pasos
 
 ```bash
-npm install          # instala todos los workspaces desde la raíz
-npm run dev:lib      # compila la librería en modo watch
-npm run dev:example  # inicia el servidor de desarrollo del ejemplo (http://localhost:5173)
+npm install          # install all workspaces from the root
+npm run dev:lib      # build the library in watch mode
+npm run dev:example  # start the example dev server (http://localhost:5173)
 ```
 
 Scripts adicionales disponibles desde la raíz:
 
 - `npm run build` — compila la librería
 - `npm run test` — ejecuta la suite de tests de la librería
 
+## Puntos de entrada
+
+La librería es un único paquete con exports por subpath — importa solo lo que uses:
+
+| Import | Para |
+|--------|------|
+| `@studiolxd/scorm` | Núcleo agnóstico al framework + vanilla (`createScormSession`) |
+| `@studiolxd/scorm/react` | React (`ScormProvider`, `useScorm`, …) |
+| `@studiolxd/scorm/vue` | Vue 3.3+ (`useScorm`) |
+| `@studiolxd/scorm/angular` | Angular 17+ (`provideScorm`, `SCORM`) |
+| `@studiolxd/scorm/svelte` | Svelte 4+ (`createScormStore`) |
+| `@studiolxd/scorm/wc` | Web Component `<scorm-session>` |
+| `window.Scorm` (CDN `<script>`) | HTML plano, sin bundler |
+
 ## Estructura del proyecto
 
 ```
 react-scorm/
-├── package.json          # raíz de npm workspaces (privado)
+├── package.json          # npm workspaces root (private)
 ├── packages/
-│   └── react-scorm/      # @studiolxd/react-scorm — publicado en npm
-│       └── README.md     # documentación completa de la librería
-└── example/              # demostración interactiva (no publicada)
-    └── README.md         # documentación de la demostración
+│   └── scorm/            # @studiolxd/scorm — published to npm
+│       └── README.md     # full library documentation
+├── example/              # interactive demo (not published)
+│   └── README.md         # demo documentation
+├── skills/               # AI agent skills (Claude Code, Cursor, …)
+├── tests/angular-smoke/  # Angular AOT smoke test fixture
+└── docs/                 # design & planning docs
 ```
 
 ## Publicación
 
-Solo `packages/react-scorm` se publica en npm. El workspace `example` y la raíz son privados. Para publicar:
+Solo se publica `packages/scorm` en npm. El workspace `example` y la raíz son privados. Para publicar:
 
 ```bash
-cd packages/react-scorm
+cd packages/scorm
 npm publish
 ```
 

README.fr.md

@@ -1,47 +1,66 @@
 🌐 [English](README.md) · [Español](README.es.md) · [Français](README.fr.md) · [Português](README.pt.md) · [Deutsch](README.de.md) · [Polski](README.pl.md)
 
-# @studiolxd/react-scorm
+# @studiolxd/scorm
 
-Monorepo contenant la bibliothèque headless `@studiolxd/react-scorm` pour le runtime SCORM et une application de démonstration interactive présentant toutes les fonctionnalités.
+Monorepo pour `@studiolxd/scorm` — un runtime SCORM 1.2 / 2004 headless doté d'un **cœur agnostique vis-à-vis du framework** et d'adaptateurs pour **React, Vue, Angular, Svelte, Web Components** ainsi que du JavaScript vanilla — accompagné d'une application de démonstration interactive.
 
-## Paquets
+> Anciennement `@studiolxd/react-scorm`. L'API React se trouve désormais sous le sous-chemin `@studiolxd/scorm/react`.
 
-| Paquet | Description |
-|--------|-------------|
-| [`@studiolxd/react-scorm`](./packages/react-scorm/) | Bibliothèque headless React + TypeScript pour le runtime SCORM 1.2 / 2004 | [README](./packages/react-scorm/README.md) |
-| [`example`](./example/) | Application de démonstration interactive — présente toutes les fonctionnalités de la bibliothèque | [README](./example/README.md) |
+## Packages
+
+| Package | Description | Documentation |
+|---------|-------------|------|
+| [`@studiolxd/scorm`](./packages/scorm/) | Runtime SCORM 1.2 / 2004 headless — cœur agnostique + adaptateurs de framework | [README](./packages/scorm/README.md) |
+| [`example`](./example/) | Application de démonstration interactive — illustre chaque fonctionnalité de la bibliothèque | [README](./example/README.md) |
 
 ## Démarrage
 
 ```bash
-npm install          # installe tous les workspaces depuis la racine
-npm run dev:lib      # compile la bibliothèque en mode watch
-npm run dev:example  # démarre le serveur de développement de l'exemple (http://localhost:5173)
+npm install          # install all workspaces from the root
+npm run dev:lib      # build the library in watch mode
+npm run dev:example  # start the example dev server (http://localhost:5173)
 ```
 
 Scripts supplémentaires disponibles depuis la racine :
 
 - `npm run build` — compile la bibliothèque
 - `npm run test` — exécute la suite de tests de la bibliothèque
 
+## Points d'entrée
+
+La bibliothèque est un package unique avec des exports par sous-chemin — n'importez que ce que vous utilisez :
+
+| Import | Pour |
+|--------|-----|
+| `@studiolxd/scorm` | Cœur agnostique vis-à-vis du framework + vanilla (`createScormSession`) |
+| `@studiolxd/scorm/react` | React (`ScormProvider`, `useScorm`, …) |
+| `@studiolxd/scorm/vue` | Vue 3.3+ (`useScorm`) |
+| `@studiolxd/scorm/angular` | Angular 17+ (`provideScorm`, `SCORM`) |
+| `@studiolxd/scorm/svelte` | Svelte 4+ (`createScormStore`) |
+| `@studiolxd/scorm/wc` | Web Component `<scorm-session>` |
+| `window.Scorm` (CDN `<script>`) | HTML simple, sans bundler |
+
 ## Structure du projet
 
 ```
 react-scorm/
-├── package.json          # racine npm workspaces (privé)
+├── package.json          # npm workspaces root (private)
 ├── packages/
-│   └── react-scorm/      # @studiolxd/react-scorm — publié sur npm
-│       └── README.md     # documentation complète de la bibliothèque
-└── example/              # démonstration interactive (non publiée)
-    └── README.md         # documentation de la démonstration
+│   └── scorm/            # @studiolxd/scorm — published to npm
+│       └── README.md     # full library documentation
+├── example/              # interactive demo (not published)
+│   └── README.md         # demo documentation
+├── skills/               # AI agent skills (Claude Code, Cursor, …)
+├── tests/angular-smoke/  # Angular AOT smoke test fixture
+└── docs/                 # design & planning docs
 ```
 
 ## Publication
 
-Seul `packages/react-scorm` est publié sur npm. Le workspace `example` et la racine sont privés. Pour publier :
+Seul `packages/scorm` est publié sur npm. Le workspace `example` et la racine sont privés. Pour publier :
 
 ```bash
-cd packages/react-scorm
+cd packages/scorm
 npm publish
 ```