https://github.com/code-dot-org/ai-literacy-oceans
https://github.com/code-dot-org/ai-literacy-oceans
Last synced: about 1 month ago
JSON representation
- Host: GitHub
- URL: https://github.com/code-dot-org/ai-literacy-oceans
- Owner: code-dot-org
- Created: 2026-06-02T21:08:13.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-02T23:14:02.000Z (about 2 months ago)
- Last Synced: 2026-06-02T23:15:46.146Z (about 2 months ago)
- Language: TypeScript
- Size: 104 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# ai-literacy-oceans
A self-contained, embeddable web app that sequences the five interactive modes of the [AI for Oceans](https://studio.code.org/s/oceans) lab for the EU AI Literacy Framework.
## Embedding
```html
```
The canvas is always 16:9. The progress bar sits above it — the iframe is taller than 16:9 by the bar's height (~32px).
The iframe container should be at least **1024px wide** so the 16:9 canvas reaches 576px height,
which is OceansLab's designed canvas height. Below 1024px the word-selection scene clips.
### Contract
- **Self-contained**: no `postMessage`, no URL parameters, no completion signal. The host page owns all surrounding UI.
- **Locale auto-detection**: `navigator.language` is mapped to the nearest of the 24 official EU languages; English is the fallback. No in-app picker.
- **No network calls for translations**: EU strings are baked into the bundle.
- **TTS is best-effort**: only `en` and `it` have voice data; other EU locales fall back to browser voices or stay silent.
## Sequence
The app runs five lab modes in curriculum order, advancing on the lab's Continue callback:
```
fishvtrash → creaturesvtrashdemo → creaturesvtrash → short → long → play-again
```
After the final mode a "Play Again" button restarts from `fishvtrash`.
## Development
```bash
# Install (requires read:packages token for @code-dot-org scope)
npm ci
# Dev server
npm run dev
# Build
npm run build
# Preview the subpath build
npm run preview
```
### GitHub Packages auth
The `@code-dot-org/oceans-lab` package lives on GitHub Packages under the `code-dot-org` org. In CI the deploy workflow uses `GITHUB_TOKEN` (automatic, no secret needed). Locally you need a token with `read:packages`:
```bash
echo "//npm.pkg.github.com/:_authToken=YOUR_TOKEN" >> ~/.npmrc
```
## Testing
```bash
# Run e2e tests locally (starts dev server automatically)
npm run test:ui
# CI mode (used in the deploy workflow)
npm run test:ui:ci
```
## Translations
EU locale strings live in `i18n/.json`. They were generated from the `@code-dot-org/oceans-lab` English catalog (`@code-dot-org/oceans-lab/i18n`) and committed once. To regenerate after an English catalog update:
1. `npm show @code-dot-org/oceans-lab` — check the version.
2. Import the catalog: `import catalog from '@code-dot-org/oceans-lab/i18n'`.
3. Regenerate each locale JSON preserving `{var}` placeholders and ICU plural syntax.
4. Commit under `i18n/.json`.