@noodlet/sdk

Lesson-side SDK for Noodlet — the sandboxed interactive lesson platform for teachers.

Call createLesson once, render your activity in onStart, and report a score when the student finishes. The lesson never receives student identity; the platform attaches it server-side.

Installation

npm install @noodlet/sdk

Or load the global build from the CDN (no bundler needed):

<script src="https://cdn.noodlet.com/sdk/noodlet-sdk.js"></script>
<!-- window.Noodlet.createLesson(...) is now available -->

Note: When you publish a lesson through Noodlet, window.Noodlet is injected automatically — you don't need the CDN script tag in the published build. Add it only for local development.

Usage

import { createLesson } from '@noodlet/sdk'

createLesson({
  onStart(ctx, info) {
    // Build your lesson UI here.
    const btn = document.createElement('button')
    btn.textContent = 'Finish'
    btn.addEventListener('click', () => {
      ctx.submitResult({ score: 3, maxScore: 3, passed: true })
      ctx.complete({ score: 3, maxScore: 3, passed: true })
    })
    document.body.appendChild(btn)
  },
})

API

createLesson(handlers, options?)

Registers lifecycle handlers and returns a LessonContext.

Handlers

| Handler | Called when | |---|---| | onStart(ctx, info) | The lesson starts. Build your UI here. info.entryPoint is "main". | | onResume(ctx, state) | The host restores previously saved state. | | onPause(ctx) | The host is about to hide the lesson. | | onDestroy(ctx) | The lesson is being torn down. |

Context methods (available on ctx in every handler)

| Method | Description | |---|---| | submitResult({ score, maxScore, passed, response?, duration? }) | Record an attempt. score / maxScore becomes a 0–1 mastery fraction. duration is milliseconds, stored as ISO 8601. | | complete(result?) | Mark the lesson finished. Pass the final result if not already submitted. | | reportProgress({ fraction }) | Report 0–1 progress while the student works. | | saveState(obj) | Persist resumable state. Replayed via onResume if the student returns. | | requestNext() | Ask the host to advance to the next activity. | | reportError(message) | Surface an error to the host. |

Options

| Option | Description | |---|---| | teacher | Force teacher dev-mode guards on (true) or off (false). Default: auto (on when no host connects). |

Dev mode

When a lesson runs outside the Noodlet platform (opened directly in a browser), the SDK activates dev-mode guards:

• Logs every ctx.* call to the console so you can see what the real host would do.
• Warns about network calls, external scripts, and inline event handlers that the sandbox CSP will block.
• Shows a collapsible warning banner in the corner of the page.
• Persists saveState to sessionStorage and replays it on reload.

Sandbox constraints

Published lessons run in a strict CSP sandbox with no network access, no external scripts, and no inline event handlers. Author your lesson to be fully self-contained. See the sandbox rules for details.

Vite / bundler tip

Keep your build unminified — set build.minify: false in Vite. Readable source keeps publish warnings actionable and lets teachers audit exactly what runs for students.