Studio readiness

Framework readiness for LessonKit Studio (and AI/dev workflows)

This checklist is how we decide the LessonKit framework is ready to act as the shared runtime for:

• Developers authoring directly in React

• AI code generators producing LessonKit code (Claude/Cursor-style workflows)

• LessonKit Studio (a non-coder layer built on top, post–framework 1.0.0)

Framework 1.0.0 has shipped — the Studio development gate is met. Studio implementation may begin per ROADMAP.

Readiness principles

• Stable contracts: API surfaces are documented, versioned, and testable.

• Deterministic outputs: builds/exports don’t rely on hidden randomness; regeneration yields minimal diffs.

• Dual export parity: React/Vite and LXPack/LMS artifacts match behavior and theme.

• Machine-readable surfaces: generators can discover supported primitives and constraints without scraping source.

• Reusable building blocks: components and themes are designed to be shared across projects (portable defaults, predictable override rules).

0.4.x — Theme system + tokens

• Token schema v1 exists in @lessonkit/themes (required tokens + allowed extensions)

• CSS variables contract is documented (namespacing, required variables, override precedence)

• @lessonkit/react exposes a stable ThemeProvider (or equivalent) with default theme

• Example demonstrates theme override and dark/light switching

• Enumerable theming: “what can be themed” is documented and discoverable for generators

• React/Vite example (examples/react-vite) consumes --lk-* tokens via ThemeProvider

0.5.x — Identity + semantics (IDs, telemetry, xAPI)

• Identity model v1 is documented (IDENTITY.md):

  • courseId required on Course / LessonkitProvider

  • lessonId required on Lesson (no runtime useId fallback)

  • checkId required on Quiz / KnowledgeCheck; optional blockId on Scenario / Reflection

• ID generation guidance is deterministic (slugifyId, deriveId, validateId in @lessonkit/core)

• Telemetry event catalog is versioned (telemetry-catalog.v1.json, TELEMETRY.md)

• Telemetry → xAPI mapping is canonical (telemetryEventToXAPIStatement in @lessonkit/xapi)

• “Regenerate code” guidance exists in IDENTITY.md

0.6.x — Export surfaces + @lessonkit/lxpack adapter

• Theme parity: same tokens produce the same visual output in React/Vite and LXPack-packaged artifacts (via @lessonkit/lxpack runtime cssVariables bridge)

• @lessonkit/lxpack exists and is covered by tests

• Adapter produces a valid LXPack project/interchange with stable ID mapping

• Adapter prefers programmatic LXPack APIs where possible (structured results/errors)

• Golden end-to-end example exists:

  • LessonKit course → LXPack build → SCORM ZIP importable into an LMS

  • Standalone web artifact runnable locally

• CI runs a packaging smoke test on the golden example

• Output layout is stable and documented (so generators/CI can rely on it)

0.7.x — CLI workflow (developer + AI friendly)

• lessonkit init/dev/build are real and documented

• lessonkit package supports dual export targets:

  • react-vite

  • lxpack|scorm12|scorm2004|xapi|cmi5 (via adapter)

• CLI errors are structured and actionable (good messages, stable exit codes)

• The CLI is safe for automation (CI-friendly, no interactive prompts by default)

0.8.x — Runtime block catalog (machine-readable)

• Block catalog v1 exists (framework-owned)

• Catalog includes per-block:

  • allowed props/schema

  • a11y behavior contract

  • theming surface contract

  • telemetry semantics

• Catalog is exported in machine-readable form (JSON) and documented

• @lessonkit/react is capable of rendering every framework catalog block in an example (v1 + v2 block catalog)

0.9.x — Conformance harness (parity proof)

• Playwright e2e covers:

  • keyboard navigation/focus flows

  • telemetry / progress persistence on Vite surface

  • telemetry batching + xAPI queue behavior (telemetry-harness Playwright project)

  • packaging artifact smoke (standalone + SCORM 1.2 launch with LMS API mock)

• Conformance matrix exists and is enforced in CI:

  • @lxpack/conformance + golden package matrix scripts

  • React/Vite, standalone, and SCORM 1.2 parity spec on examples/lxpack-golden

• Contributor docs for Playwright e2e and packaging smoke (export parity guide, e2e README, contributing E2E section)

0.8.0+ — Plugin architecture

• Plugin contract v1 in @lessonkit/core (LessonkitPlugin, createPluginRegistry, defineTelemetryPlugin)

• @lessonkit/react registers plugins on LessonkitProvider (config.plugins)

• Extension points: lifecycle (setup/dispose), onTelemetry, wrapTrackingSink, scoreAssessment, interactionBlocks metadata

• Plugins reference and plugin cookbook

• Example plugin: examples/_shared/plugins/consoleAnalyticsPlugin.ts

1.1.0 — Assessment contract + Tier B P0 blocks (framework)

• AssessmentHandle / assessment_* telemetry on P0 blocks (TrueFalse, FillInTheBlanks, DragAndDrop, DragTheWords, MarkTheWords, AssessmentSequence)

• Block catalog v2 (block-catalog.v2.json) with interaction types

• Example examples/assessments-p0 and MIGRATION-1.0-to-1.1.md

• lessonkit init template pins ^1.1.0

1.0.0 — Studio gate checklist (framework)

• Public APIs for @lessonkit/react, @lessonkit/core, @lessonkit/xapi, @lessonkit/themes, @lessonkit/accessibility are stable and documented

• Storybook + docs site are live and up to date

• Accessibility conformance documented (WCAG 2.1 AA target)

• Dual export parity is proven (conformance harness is green)

• Packaging is documented end-to-end (React/Vite and LXPack/LMS targets)

• Generator-friendly API checklist is met:

  • predictable defaults

  • stable prop shapes

  • canonical reference example that is easy to scaffold and modify

Studio 0.1.0 — Schema and shared renderer

• @lessonkit/studio-schema in monorepo (packages/studio-schema) with schemaVersion: 1, parse / validate / normalize / migrate / load

• studio-project.v1.json and studio-block-catalog.v1.json exported; catalog matches buildStudioBlockCatalog() in tests

• @lessonkit/studio-renderer maps Studio blocks to @lessonkit/react (Course, Lesson, Quiz, Scenario) plus presentational primitives

• Initial block types: text, heading, image, button, input, container, quiz, scenario (checklist / video: schema + stub renderer)

• Example studio-minimal loads src/project.json via shared renderer

• Studio project format v1 documented

• npm publish path: studio-v* tag → Studio Release (see RELEASING.md)

Studio 0.2.0 — Visual editor MVP

• @lessonkit/studio-builder: Zustand editor store, commands, undo/redo (bounded stack), validation on commit, debounced autosave subscription

• @lessonkit/studio-ui: StudioEditor with page list, block palette, dnd-kit canvas (root + nested containers), property inspector, live preview

• apps/studio-web: runnable Vite app; localStorage autosave; import/export JSON

• Checklist / video blocks: minimal real preview renderers (not stubs)

• Monorepo CI: build:packages includes studio-builder → studio-ui; build:apps includes lessonkit-studio-web

• Studio editor guide documented

• npm publish: studio-v0.2.0 (schema, builder, renderer, ui)

Not included in 0.2.0: codegen (studio-codegen), GitHub sync, AI workflows, lessonkit-studio CLI, Tauri desktop, schema v2.

Studio 0.3.0 — Code generation and export

• @lessonkit/studio-codegen: studioProjectToDescriptor, renderer + explicit JSX React/Vite export, Node helpers (writeReactViteProject, writeLxpackProjectFromStudio, packageStudioProject)

• @lessonkit/studio-ui: ExportPanel (mode, theme, xAPI IRI, zip download hook, CLI snippet); canvas lazy block previews + root-list virtualization (30+ blocks)

• apps/studio-web: Export panel wired with JSZip download; version label from package

• Integration test: codegen → vite build → lessonkit package --target scorm12

• Example studio-export and Studio export guide

• Monorepo: build:packages includes studio-codegen; Studio Release publishes five packages

• npm publish: studio-v0.3.0 (five Studio packages; framework pinned at 1.0.2 on npm tag)

Not included in 0.3.0: GitHub sync (studio-github), AI workflows, lessonkit-studio CLI, Tauri desktop, schema v2, hosted lessonkit.app.