/add-xapi-events-to-microsim

Add xAPI Events to a MicroSim

Version: 0.2 (2026-09-26). This version folds in the lessons of the first whole-book batch, the 20 sims of eight-hour-entrepreneur.

What this skill does

This skill takes a MicroSim that already works and makes it report what the student did, as xAPI statements, without changing what the sim does. The per-sim code is a thin mapping, usually 20 to 60 lines, onto a shared runtime. It is never a copy of the runtime.

The runtime decides Full vs. Compact from config and builds every statement. It also enforces the producer contract and renders the teaching panel. Your job is to decide which interactions are evidence, of what, and for which concept, and then wire them up.

The canonical runtime and the four reference sims live in the learning-record-store repo. Read them whenever this skill points at one; they are the ground truth.

LRS_REPO=~/Documents/ws/learning-record-store
$LRS_REPO/docs/js/lrs-sim.js           the API a sim calls (its header comment is the contract)
$LRS_REPO/docs/js/lrs-config.js        per-book identity + default policy (example)
$LRS_REPO/docs/sims/bouncing-ball/     p5, slider + Start/Pause            (verified)
$LRS_REPO/docs/sims/sine-wave/         p5, three sliders                   (verified)
$LRS_REPO/docs/sims/scientific-method/ Mermaid, hover + pin, page dwell    (verified)
$LRS_REPO/docs/sims/animal-cell/       image overlay, explore + quiz       (verified)
$LRS_REPO/docs/js/quiz-xapi.js         chapter quiz page, answers only     (verified)
$LRS_REPO/docs/specs/xapi-producer-contract-v1.md   the statement rules

Scripts are in this skill's scripts/ directory (SKILL_DIR below). The Python scripts need only the standard library, except the two that drive a browser. Run those with uv run --with playwright==1.58.0 python ....

Principles, and why they matter

• Instrument the act the sim was designed for. Don't record every act you can detect. The sim's own instructions tell you which act was designed ("Click a node to see details", "Hover over a marker or a label"). Hover is absent on touch devices, so hover-only evidence is biased by device, and device correlates with school funding. Record hover only when it is the designed act, or when click is simply how a touchscreen does the same thing (then they are one act; see animal-cell).
• Not every interaction is evidence. Mouse crossings (<600 ms hover), mis-clicks (<250 ms runs), glances (<1 s page dwell), and events the program fires on itself (autosize, setView, rangechange) are noise. If you emit them, dashboards will believe them.
• Answers are never folded. A checked answer (a quiz item, a checked prediction, a goal reached) is its own answered statement in both modes, emitted as it happens. Only exposure evidence folds into the Compact summary. BKT reads the order of attempts.
• Mode and teaching UI come from config, never from the sim. The book's docs/js/lrs-config.js sets the default for every sim. A sim's metadata.json xapi block overrides it for that one sim. Production sims show nothing.
• Any instrumented sim can become a teaching aid for one visit. A reader who adds ?xapi=teaching to the page that embeds the sim sees its statement log, with no file edited. So a production sim's layout must still work with the panel showing. The runtime grows the iframe to fit the panel, but a layout that fills its frame (100vh, or html/body at 100%) defeats that. Pin such a layout while the panel is present.
• Never edit the runtime or a vendored library. docs/js/lrs-*.js is identical in every book. A vendored file such as shared-libs/diagram.js is shared by many sims. Wrap functions and add listeners beside the originals instead. If the runtime truly lacks something, use lrs.emit(spec), or stop and tell the user.
• The sim must still run without the runtime. Teachers paste p5 sketches into the p5.js editor. Guard every call site with if (window.LRSSim) or a null lrs. scripts/check-no-runtime.py proves it (step 9).

Workflow

Work through these steps in order. Steps 2–4 are the thinking. Show the user the evidence table from step 3 before you write code whenever there is anything debatable, for example two input paths to one act, a canvas hit-test, or no matching concept.

Step 0 — Locate the book and the sim

The book root is the directory containing mkdocs.yml. The sim is docs/sims/<sim-name>/, containing main.html (the iframe payload), index.md (the lesson page that embeds it), and usually metadata.json. For a chapter quiz, the "sim" is the rendered quiz page; go straight to references/adapters/quiz-page.md.

For a batch request ("instrument chapter 5's sims"), handle one sim at a time and keep a running table of results. Finish and verify each sim before starting the next.

A whole book at once (proven on the 20 sims of eight-hour-entrepreneur, 2026-09-26) can use parallel subagents, one per group of sims that share a library or template. Split the work this way:

• The coordinator does the per-book steps, once:
  • install-runtime.py (step 5), before any worker starts.
  • One sim wired and verified by hand, as the in-book reference the workers copy.
  • At the end: sync-status.py --apply (step 7), check-no-runtime.py over the whole book, mkdocs build --strict, and a fresh check-xapi.py run of every sim with its actions file.
• Workers do steps 1–4, 6, the metadata half of step 7, and step 9 for their own sims only. They must not touch mkdocs.yml, extra.css, docs/js/, chapter files, status: or git. check-xapi.py and measure-iframe.py each serve on a random port, so they run safely side by side.
• Relay findings between workers. One worker's discovery often applies to another's sims. For example, the keyPressed panel guard in p5-canvas.md was found by one worker and needed by two others.

Step 1 — Detect the library (from script tags, not the catalog)

python3 $SKILL_DIR/scripts/detect-library.py docs/sims/<sim-name>

The catalog's library field is empty for about 45% of sims, so trust the <script> tags. The report also lists:

• whether the runtime is already loaded (if so, this is a revision, not a first pass),
• vendored shared files you must wrap rather than edit,
• a first-pass inventory of interaction hooks found in the JS.

Open the matching adapter and read it before going further:

Many sims mix shapes, for example p5 DOM controls plus canvas-drawn buttons. Read every adapter that applies. An unverified adapter was drafted from library docs and has not passed a pilot yet. Follow it, but verify its claims against the real sim and tell the user which parts you had to correct. A piloted adapter passed a pilot in an eval run, and its corrections are folded in. It becomes verified once that pilot sim is committed to its book.

Step 2 — Inventory the interactions

Read the sim's JS and HTML completely; the detector's inventory is only a starting point. List every way the student can change or inspect the sim: each control, each clickable thing, each hover target, each mode switch, each check of an answer. Also note the sim's own instruction text, because it names the designed act.

Step 3 — Classify each interaction into an evidence class

Read references/evidence-classes.md. Every interaction becomes exactly one of:

Write the result as a table for the user: interaction → class → fragment key → concept. Name each fragment key for what the thing is (#frequency-slider, #start-pause-control, #q-kafka), never for its position.

Step 4 — Map each object to a concept id

Read references/concept-mapping.md. In short: the concept id is namespaced as {conceptPrefix}-{ConceptID} from the book's docs/learning-graph/learning-graph.csv. Each statement carries one concept. To propose candidates, run:

python3 $SKILL_DIR/scripts/find-concepts.py --book . --sim docs/sims/<sim-name>
python3 $SKILL_DIR/scripts/find-concepts.py --book . "prediction" "data loss"

The script only proposes; you choose. If nothing genuinely matches, leave that object unmapped and tell the user. Don't guess the nearest label. A wrong concept id is worse than none, because it silently credits mastery of the wrong thing. A mapping the book itself states is not a guess. If the chapter or a sibling sim's spec pairs Gateway with Kafka Unavailable Failure, use that pairing and cite it.

While mapping a question, check its answer key against the chapter. A key that contradicts the text makes every student who learned the chapter score success: false. Both chaos-kill eval runs found such a key. Report it; changing it is a content decision for the user.

In code, write LRS.conceptId(353) so the prefix comes from the book's config. Record the map, with full ids, in metadata.json (step 7).

Step 5 — Confirm the runtime is installed in this book

python3 $SKILL_DIR/scripts/install-runtime.py --book . --check

If files are missing, run it without --check. It copies lrs-xapi.js, lrs-lite-sim.js, lrs-sim.js, xapi-json-viewer.js and lrs-xapi.css from the canonical repo. It writes docs/js/lrs-config.js from mkdocs.yml only if that file is absent, because the config is the book's identity and is never overwritten. If the script reports drift (the book's copy differs from canonical), stop and tell the user; don't pass --force on your own. Phase 3 will move this job into book-installer.

Step 6 — Wire the adapter

1. main.html: add the script block from assets/main-html-script-block.html, in that order, before the sim's own script. Add the CSS link. For layouts where the panel should sit below the sim, add <div id="xapi-slot"></div> after <main>.
2. The sim's JS: create one LRSSim instance, then one handle per object from step 3, then call the handles from the sim's existing event handlers. Follow the adapter file for the library. See references/runtime-api.md for every option, with a worked example of each class.
3. Keep the sim's original behaviour byte-for-byte where you can: add listeners, wrap functions, and don't reorder the sim's own logic. For a sim whose main file is a vendored library, put the instrumentation in a separate xapi.js (animal-cell).
4. Clicks and mouse moves inside the xAPI panel must not reach the sim's own handlers, such as "click outside to unpin" or a follow-the-mouse infobox. Check for these.
5. Make the layout tolerate the panel even for a production sim, because ?xapi=teaching can switch it on. Give the panel a place to go (mount). If the sim fills its frame, add teaching-only CSS scoped to body:has(> .xapi-panel) that pins the container to its production pixel height. See the Mermaid adapter's "Layout" section. That CSS costs nothing in production, where no panel exists.

Read references/pitfalls.md before you finish this step; every item on it was learned by shipping the bug.

Step 7 — Set the metadata.json xapi block

"xapi": {
  "concept": "learning-record-store-353",
  "objects": {
    "service-select": "learning-record-store-353",
    "q-kafka": "learning-record-store-334",
    "q-neo4j": "learning-record-store-336"
  }
}

In this example, the page and its generic controls take the sim's concept (353, Chaos Kill Test). Each question takes the concept it tests (334, Kafka Unavailable Failure).

• concept is the page-level concept (runs, page dwell, the Compact summary). objects maps every fragment key to its concept id. check-xapi.py verifies that the emitted statements match this map, so the map and the code can't drift apart silently. The map also gives the MicroSim catalog exact concept ids, which it lacks today.
• Production sims (the normal case) carry no policy keys, so they inherit the book's lrs-config.js default. If the book's default is ever teaching: true, add "teaching": false to keep this sim silent.
• Teaching sims (ones that exist to teach xAPI) add "compact": false, "teaching": true, so they start on Full and show the log.
• Policy keys and their meaning: compact, teaching, idleMs, offscreenMs, blurMs. The precedence, lowest first, is: runtime defaults < book lrs-config.js xapi < page policy option < this block < the URL switch ?xapi= (one visit only).

Then mark the sim in the nav (always, for every sim this skill instruments):

python3 $SKILL_DIR/scripts/sync-status.py --book . --apply

This sets status: instrumented in the index.md frontmatter of every sim whose main.html loads the runtime and whose code calls LRSSim.create. It marks that the capability is present, whether or not teaching is on. The nav shows the signal icon (the Material Design Icons "access-point" broadcast symbol, in teal). That icon is the standard for xAPI instrumentation in every book (Dan, 2026-09-26), so don't substitute another. If a book lacks the icon, --apply installs it by appending assets/status-instrumented.css to docs/css/extra.css and adding the tooltip under mkdocs.yml extra.status. The script never overwrites an approved sign-off.

If the book's AGENTS.md (or CLAUDE.md) lists the allowed status: values, usually scaffold | built | approved, add instrumented to that list, along with the comment above extra.status in mkdocs.yml. Otherwise the next agent that follows those rules may "fix" the new status back to built.

Step 8 — Re-measure the iframe height

uv run --with playwright==1.58.0 python $SKILL_DIR/scripts/measure-iframe.py docs/sims/<sim-name>

A teaching sim gains a panel, so its iframe must grow. The script measures a full log at 375, 700 and 900 px and recommends a height from the 700 px measurement.

Size for the laptop column, not the phone. On the published site the content column is 690–760 px on laptops and tablets. About 90% of the target students use laptops, and phones are often banned in US junior-high and high schools. The ~20% mobile traffic in the logs is mostly browsing the text, not using the sims (Dan, 2026-09-26). A sim that is taller at 375 px may scroll or clip on a phone; that's accepted. Mention it in the report, but don't grow the iframe for it unless the user asks. It measures the state after load. If the sim is taller in another state (quiz mode, an open detail panel), put it there first with --eval "sim.setMode('quiz')". An empty-log screenshot is not a measurement.

The script also lists every iframe in the book that embeds this sim, not just the one in index.md. Chapters embed sims too, and the teaching panel appears wherever the sim is shown, because the mode comes from the sim's own metadata.json. It also reports the sim's CANVAS_HEIGHT source. microsim-utils' sync-iframe-heights.py sets every embedding iframe to CANVAS_HEIGHT + 2. So if you edit iframe heights by hand, its next run silently shrinks them back. Instead:

1. Set the sim's CANVAS_HEIGHT (its // CANVAS_HEIGHT: comment, or canvasHeight in metadata.json, whichever the script reports) to the recommended height − 2.
2. Run python3 ~/Documents/ws/ibook-skills/src/microsim-utils/sync-iframe-heights.py --project-dir . --sim <sim-name> to update every embed.

A production sim should not change height; if it did, the wiring added something visible, so find it.

Step 9 — Verify both modes headless

uv run --with playwright==1.58.0 python $SKILL_DIR/scripts/check-xapi.py docs/sims/<sim-name> \
    --actions docs/sims/<sim-name>/xapi-actions.json      # optional; see below

The script serves docs/ and embeds the sim in an iframe the way the book does. It rewrites metadata.json in flight to Full, then Compact, then production. It then loads the production sim once more with ?xapi=teaching, at its real index.md iframe height. In each mode it drives interactions and asserts the contract:

• only the three verbs,
• IRIs from the book's siteUrl, with no main.html and no localhost,
• grouping present,
• concept ids present and matching the metadata map,
• Compact silent until focus loss, then exactly one summary with statements_represented,
• answers passing through unfolded,
• no teaching UI in production,
• with ?xapi=teaching, the panel appears and fits its iframe,
• a clean console.

Generic driving covers DOM sliders, selects, checkboxes and buttons. For canvas clicks, hovers, chart points or graph nodes, write a small actions file. The format is in scripts/check-xapi.py --help and in each adapter. Keep that file in the scratch space, not in the book, unless the user wants it. Iterate until every check passes. Report any warning you decide to accept, and why.

Some actions cover cases that are easy to miss:

• type sends real keystrokes into a text box, then commits them.
• "leave": false on a hover keeps the pointer in place, so a following click_at is the same visit.
• Action selectors skip the teaching panel's own controls; add "panel": true to target them deliberately.

Drive every evidence class you wired. Full mode must show each one at least once, which is the positive control that makes the other checks mean something.

Then prove the sim still runs with no runtime at all (the p5.js-editor case). The script blocks the five runtime scripts, loads the sim, clicks its buttons, and fails on any uncaught error:

uv run --with playwright==1.58.0 python $SKILL_DIR/scripts/check-no-runtime.py --book . <sim-name> ...

With no sim names it checks every instrumented sim in the book.

Step 10 — Lesson text (teaching sims only)

For a sim that teaches xAPI, add a section to index.md that lists what it emits in each mode. Also add keyQuestions in metadata.json that make the student compare the two streams. Use $LRS_REPO/docs/sims/bouncing-ball/index.md as the model. Production sims get no lesson text about xAPI.

Step 11 — Report

Tell the user, briefly:

• the evidence table (interaction → class → key → concept),
• anything left unmapped and why,
• files changed,
• the check-xapi.py summary, with the iframe height before and after,
• any unverified-adapter claim you had to correct. That feedback is how an adapter becomes verified.

Reference files

Scripts