microsim-utils

MicroSim Utilities

Overview

This meta-skill provides utility functions for managing and maintaining MicroSims in intelligent textbook projects. It consolidates five utility skills into a single entry point with on-demand loading of specific utility guides.

When to Use This Skill

Use this skill when users request:

• Validating MicroSim quality and standards
• Capturing screenshots for preview images
• Adding or managing icons for MicroSims
• Generating index pages for MicroSim directories
• Quality scoring and standardization checks
• Synchronizing iframe heights from JS source files
• Setting up runtime iframe auto-resize via postMessage
• Scaffolding MicroSim directories (main.html, index.md, metadata.json) from TODO JSON specs
• Testing whether interactive controls are fully visible inside the iframe (Playwright)
• Reviewing a MicroSim's visual layout for rendering defects (Claude Vision)
• Auditing diagram/MicroSim coverage across chapters (status, difficulty, Bloom's levels)

Step 1: Identify Utility Type

Match the user's request to the appropriate utility guide:

Routing Table

Trigger Keywords	Guide File	Purpose
standardize, quality, validate, score, check, audit	references/standardization.md	Quality validation and scoring
screenshot, capture, preview, image, thumbnail	references/screen-capture.md	Automated screenshot generation
icons, add icons, favicon, logo	references/add-icons.md	Icon management for MicroSims
index page, microsim list, grid, directory, catalog, update the microsim listings, update the list of microsims, create a grid view, generate a listing	references/index-generator.md	Generate index page with grid cards
TODO, todo json, extract specs, diagram specs, unimplemented, create microsim todo, todo files, extract diagrams, unimplemented microsims	scripts/create-microsim-todo-json-files.py	Extract unimplemented diagram specs into TODO JSON files
scaffold microsims, scaffold from todo, scaffold sims, create microsim stubs, generate microsim scaffolding, stub out microsims, create scaffold files, generate scaffold from json, microsim stubs from todo	scripts/scaffold-microsims-from-todo.py	Generate main.html, index.md, and metadata.json stub files for each TODO JSON spec that does not yet have an implementation
fix iframe heights, sync iframe heights, correct iframe heights, iframe height, canvas height, sync heights, update iframe heights	scripts/sync-iframe-heights.py	Set every sim iframe to CANVAS_HEIGHT + 2, resolving CANVAS_HEIGHT from the .js comment / metadata.json / main.html / computed vars, across the sim's own index.md and all embeds
canvas height strategy, where is the height stored, height convention, how do iframe heights work, store height for mermaid/vis-network, metadata canvasHeight, no js height	references/canvas-height-strategy.md	The build-time height convention: resolution order, per-library storage, metadata.json fallback, and downstream hand-off
iframe auto height, iframe auto resize, iframe postMessage, runtime iframe resize, microsim auto resize, auto-size iframe, iframe self-resize	references/iframe-auto-height.md	Runtime postMessage protocol so embedded MicroSims report their own height to the parent page
test iframe, controls clipped, controls cut off, are controls visible, test iframe heights, verify controls fit, check if sims fit, iframe visibility	references/iframe-tester.md (runs scripts/test-iframe-heights.py)	Playwright check that every interactive control is fully visible inside the iframe at its declared height
review layout, layout review, looks off, looks wrong, clipped labels, overlapping controls, residual stroke, draw order, visual QA, review the sim	references/layout-reviewer.md	Claude Vision review of a sim's rendered layout — walks a checklist, diagnoses defects, patches source
diagram report, diagram reports, visualization coverage, audit diagrams, audit microsims, diagram status, microsim status report	references/diagram-reports.md (runs scripts/diagram-report.py)	Generate status reports of all diagrams/MicroSims across chapters (type, status, Bloom's levels, UI complexity, difficulty)

Decision Tree

Need to check MicroSim quality/standards?
  → YES: standardization.md

Need to capture screenshots for previews?
  → YES: screen-capture.md

Need to add or manage icons?
  → YES: add-icons.md

Need to generate/update the MicroSim index page?
  → YES: index-generator.md

Need to extract unimplemented diagram specs into TODO files?
  → YES: Run scripts/create-microsim-todo-json-files.py

Need to scaffold sim directories (main.html, index.md, metadata.json) from those TODO JSON files?
  → YES: Run scripts/scaffold-microsims-from-todo.py

Need to fix, sync, or correct iframe heights?
  → YES: Run scripts/sync-iframe-heights.py

Need iframes to auto-resize at runtime via postMessage?
  → YES: references/iframe-auto-height.md

Need to verify interactive controls are fully visible inside the iframe?
  → YES: references/iframe-tester.md (runs scripts/test-iframe-heights.py)

Need to review whether a sim's rendered layout looks right (not just fits)?
  → YES: references/layout-reviewer.md

Need a status report of all diagrams/MicroSims across chapters?
  → YES: references/diagram-reports.md (runs scripts/diagram-report.py)

Iframe-height utilities at a glance

Three utilities touch iframe height — they are complementary, not redundant:

Utility	Question it answers	Tool
scripts/sync-iframe-heights.py	"Do all iframes use the sim's CANVAS_HEIGHT + 2?" (build-time)	Python
references/canvas-height-strategy.md	"Where is CANVAS_HEIGHT stored for each library type, and how does it flow?" (convention)	Doc
references/iframe-tester.md	"Do the controls actually fit at that height?" (geometric)	Playwright
references/layout-reviewer.md	"Does the rendering inside the canvas look right?" (visual)	Claude Vision

Step 2: Load the Matched Guide or Run the Script

For reference-based utilities, read the corresponding guide file from references/ and follow its workflow.

For Python script utilities, run the script directly:

TODO JSON extractor:

python3 /path/to/skills/microsim-utils/scripts/create-microsim-todo-json-files.py --project-dir /path/to/project

Report the summary output to the user (chapters scanned, total specs found, already implemented, TODO files written, output directory).

Scaffold from TODO JSON:

python3 /path/to/skills/microsim-utils/scripts/scaffold-microsims-from-todo.py --project-dir /path/to/project

Report the summary output to the user (TODO specs processed, scaffolded, skipped). Use --force only if the user explicitly asks to regenerate stubs; the script never overwrites an existing main.html regardless of --force.

Iframe height sync:

python3 /path/to/skills/microsim-utils/scripts/sync-iframe-heights.py --project-dir /path/to/project --verbose

Report the summary output to the user (sims synced, CANVAS_HEIGHT comments inserted, iframe heights updated).

Step 3: Execute Utility

Each guide contains:

1. Purpose and use cases
2. Prerequisites
3. Step-by-step workflow
4. Output format
5. Best practices

Available Utilities

standardization.md

Purpose: Validate MicroSim quality against standards

Checks:

• Required file presence (main.html, index.md)
• Code structure and patterns
• Accessibility features
• Documentation completeness
• Responsive design implementation

Output: Quality score (0-100) with recommendations

screen-capture.md

Purpose: Capture high-quality screenshots for social media previews

Script: ~/.local/bin/bk-capture-screenshot <microsim-directory-path>

Features:

• Uses Chrome headless mode with localhost server
• Handles JavaScript-heavy visualizations (p5.js, vis-network, Chart.js)
• Waits 3 seconds for proper rendering
• Creates consistent 1200x800 image sizes

Output: PNG screenshot named {microsim-name}.png in MicroSim directory

add-icons.md

Purpose: Add favicon and icons to MicroSim directories

Creates:

• favicon.ico
• apple-touch-icon.png
• Other platform-specific icons

index-generator.md

Purpose: Generate comprehensive MicroSim index page

Creates:

• Grid-based card layout
• Screenshots for each MicroSim
• Alphabetically sorted entries
• MkDocs Material card format
• Updates mkdocs.yml navigation

create-microsim-todo-json-files.py

Purpose: Extract unimplemented MicroSim diagram specifications from chapter content and create TODO JSON files

Script: scripts/create-microsim-todo-json-files.py --project-dir /path/to/project

How it works:

• Scans all docs/chapters/*/index.md files for #### Diagram: headers
• Extracts sim-id, library, Bloom level, learning objective, and full specification from <details> blocks
• Skips any sim-id that already has a directory with main.html under docs/sims/
• Writes one JSON file per unimplemented diagram to docs/sims/TODO/

Output: Individual JSON files in docs/sims/TODO/{sim-id}.json with fields:

• sim_id, diagram_name, chapter_number, chapter_title
• library, bloom_level, bloom_verb, learning_objective
• completion_status: "specified", extracted_date, specification

Important: Always pass --project-dir pointing to the project root (the directory containing mkdocs.yml). If omitted, the script walks up from its own location to find mkdocs.yml, which may find the wrong project.

scaffold-microsims-from-todo.py

Purpose: Generate scaffold (stub) files for each MicroSim that has a TODO JSON spec but no implementation yet. This is the natural next step after create-microsim-todo-json-files.py.

Script: scripts/scaffold-microsims-from-todo.py --project-dir /path/to/project

How it works:

• Reads each docs/sims/TODO/<sim-id>.json
• For any sim-id that does NOT already have docs/sims/<sim-id>/main.html, creates the directory with three stub files:
  • main.html — placeholder canvas with the spec embedded as a comment
  • index.md — frontmatter, learning objective, iframe embed, full spec
  • metadata.json — mapped from the TODO JSON
• Skips any sim-id whose main.html already exists (so real implementations are never clobbered)

Flags:

• --project-dir — Project root containing mkdocs.yml (required or auto-detected)
• --force — Overwrite existing index.md and metadata.json stubs. Never overwrites an existing main.html, even with --force, because that file may contain a real implementation.

Output: Summary showing TODO specs processed, scaffolded, and skipped (already implemented).

Important: Always pass --project-dir pointing to the project root. The script auto-detects by walking up from cwd to find mkdocs.yml if omitted.

sync-iframe-heights.py

Purpose: Set every iframe that shows a sim to CANVAS_HEIGHT + 2, using each sim's resolved CANVAS_HEIGHT as the single source of truth. See references/canvas-height-strategy.md for the full convention (resolution order, per-library storage, downstream hand-off).

Script: scripts/sync-iframe-heights.py --project-dir /path/to/project

How it works:

• Resolves each sim's CANVAS_HEIGHT from the first source that has it:
  1. // CANVAS_HEIGHT: <int> in the first ~15 lines of <id>.js (primary)
  2. "canvasHeight": <int> in metadata.json (the consistent place for sims with no .js — Mermaid, vis-network, Chart.js, Leaflet, vis-timeline, Plotly, custom HTML)
  3. <!-- CANVAS_HEIGHT: <int> --> in main.html (back-compat)
  4. computed drawHeight + controlHeight (+ graphHeight) from <id>.js, then inserts the // CANVAS_HEIGHT comment on line 2
• Sets iframe height = CANVAS_HEIGHT + 2 (2px for iframe border) in:
  • The sim's own docs/sims/<id>/index.md
  • Every page under docs/ that embeds the sim, matched by the sims/<id>/main.html path. Layout-agnostic: handles the standard docs/chapters/<chapter>/index.md and the nested docs/bands/<band>/chapters/<chapter>/index.md used only by the health-education textbook, plus teacher guides. Poster embeds and the learning-graph viewer are never touched.
• Reports all changes with colored output

Flags:

• --project-dir — Project root containing mkdocs.yml (required or auto-detected)
• --sim <sim-id> — Sync a single sim instead of all
• --dry-run — Preview changes without writing files
• --write-metadata — Backfill each sim's metadata.json canvasHeight field (off by default; use once to migrate no-.js sims into the structured store)
• --verbose — Show the resolved height and source for every sim

Output: Summary showing sims resolved (by source), iframe heights updated (own-index vs embeds), and any metadata backfilled.

Important: Always pass --project-dir pointing to the project root. The script auto-detects by walking up from cwd to find mkdocs.yml if omitted.

iframe-auto-height.md

Purpose: Runtime alternative to sync-iframe-heights.py. Documents the two-part postMessage protocol that lets an embedded MicroSim report its own measured content height to the parent page, which then resizes the iframe automatically.

When to use: Sims with responsive or content-dependent heights that are hard to predict at build time (e.g., diagram-overlay sims whose height depends on the longest callout text). Coexists with sync-iframe-heights.py without conflict.

What's in the guide:

• The 'microsim-resize' message contract (type, height fields)
• Drop-in parent-side listener block for docs/js/extra.js
• Child-side reporter snippets for diagram-overlay, p5.js, and Mermaid sims
• Why to match by event.source === iframe.contentWindow (not by URL)
• Caveats: one-shot vs. live, target origin, sandbox attributes, fullscreen mode
• Reference implementation paths in the digital-citizenship project

Setup is one-time per project: add the listener block once to docs/js/extra.js, then any MicroSim that posts the microsim-resize message participates automatically.

iframe-tester.md

Purpose: Verify that every interactive control (button, slider, dropdown, checkbox) is fully visible inside the iframe at its declared height — a geometric check using a real headless browser.

Script: scripts/test-iframe-heights.py (Playwright)

How it works:

• Finds all MicroSim directories under docs/sims/
• Reads each index.md to get the declared iframe height
• Loads main.html in a viewport constrained to that height
• Checks every interactive element's bounding box against the iframe boundary
• Reports PASS/FAIL with a suggested height for failures

Prerequisites: pip install playwright && playwright install chromium

When to use: controls appear clipped at the bottom of a sim, or auditing iframe sizing across all sims after a batch generation. Complements sync-iframe-heights.py (which propagates the height) — run the tester to confirm the propagated height actually works.

A legacy Node.js version was retired during consolidation; the Python script is the only supported implementation.

layout-reviewer.md

Purpose: Review a sim's rendered layout with Claude Vision — catches defects geometric checks miss: clipped row labels, overlapping controls, text rendered with residual strokes, panel overflow, low-contrast labels, draw-order bugs, and library-specific rendering issues.

Tool: Claude Vision (reads the screenshot PNG directly) + bk-capture-screenshot

How it works:

• Reads the iframe height from index.md, captures a screenshot at that height
• Walks references/visual-checklist.md item by item (PASS / FAIL / N/A)
• For each FAIL, consults references/common-fixes.md and applies the smallest patch
• Re-captures and re-walks; stops after 3 review-patch cycles

Reference files: references/visual-checklist.md (every item to inspect), references/common-fixes.md (symptom → root cause → edit).

When to use: right after generating a new sim (proactive QA), or when the iframe height is correct but something inside the canvas looks wrong. For "controls clipped at the edge" only, run iframe-tester.md first.

Examples

Example 1: Quality Check

User: "Check if my bouncing-ball MicroSim meets standards" Routing: Keywords "check", "standards" → references/standardization.md Action: Read standardization.md and follow its workflow

Example 2: Capture Screenshot

User: "Create a preview image for the timeline MicroSim" Routing: Keywords "preview", "image" → references/screen-capture.md Action: Run ~/.local/bin/bk-capture-screenshot /path/to/docs/sims/timeline

Example 3: Update Index

User: "Update the MicroSim index page with all new sims" Routing: Keywords "index", "update" → references/index-generator.md Action: Read index-generator.md and follow its workflow

Example 4: Create TODO JSON Files

User: "Create MicroSim TODO JSON files" Routing: Keywords "TODO", "create microsim todo" → scripts/create-microsim-todo-json-files.py Action: Run python3 scripts/create-microsim-todo-json-files.py --project-dir /path/to/project and report results (chapters scanned, specs found, already implemented, TODO files written)

Example 5: Scaffold MicroSims from TODO JSON

User: "scaffold the microsims" or "create the stub files for the TODO sims" or "generate scaffold files from the JSON specs" Routing: Keywords "scaffold microsims", "stub out microsims", "scaffold from todo" → scripts/scaffold-microsims-from-todo.py Action: Run python3 scripts/scaffold-microsims-from-todo.py --project-dir /path/to/project and report results (TODO specs processed, scaffolded, skipped). Typically follows immediately after create-microsim-todo-json-files.py.

Example 6: Fix Iframe Heights

User: "fix the iframe heights" or "sync the iframe heights" or "correct the iframe heights" Routing: Keywords "fix iframe heights", "sync iframe heights", "correct iframe heights" → scripts/sync-iframe-heights.py Action: Run python3 scripts/sync-iframe-heights.py --project-dir /path/to/project --verbose and report results (sims synced, comments inserted, iframe heights updated)

Example 7: Set Up Iframe Auto-Resize

User: "make the iframes auto-size" or "set up iframe auto height" or "I want microsims to report their own height" Routing: Keywords "iframe auto height", "auto-size iframe", "iframe postMessage" → references/iframe-auto-height.md Action: Read iframe-auto-height.md and follow the two-part setup: paste the parent-side listener block at the top of docs/js/extra.js, then ensure the relevant MicroSims post { type: 'microsim-resize', height } after layout settles. Confirm both sides are in place and report which sims now participate.

Example 8: Test Iframe Control Visibility

User: "check if my sims fit" or "are the controls visible" or "test iframe heights" Routing: Keywords "check if sims fit", "controls visible", "test iframe heights" → references/iframe-tester.md Action: Read iframe-tester.md, ensure Playwright is installed, then run python3 scripts/test-iframe-heights.py --sims-dir docs/sims and present the PASS/FAIL table. Offer to fix failing heights.

Example 9: Review a Sim's Visual Layout

User: "this sim looks off" or "review the layout" or "the labels look clipped" Routing: Keywords "looks off", "review layout", "clipped labels" → references/layout-reviewer.md Action: Read layout-reviewer.md, capture a screenshot at the sim's iframe height, read the PNG with Claude Vision, walk visual-checklist.md, and patch defects per common-fixes.md (max 3 cycles).

Common Workflows

After Creating New MicroSim

1. Run standardization.md to validate quality
2. Run ~/.local/bin/bk-capture-screenshot <microsim-path> to create preview image
3. Run references/layout-reviewer.md (Claude Vision) to catch rendering defects
4. Run references/iframe-tester.md (Playwright) to confirm controls fit at the iframe height
5. Run index-generator.md to add to index page

Bulk Quality Audit

Use standardization.md to audit all MicroSims in a project and generate a quality report.

Integration Notes

These utilities work with the standard MicroSim directory structure:

docs/sims/<microsim-name>/
├── main.html       # Main visualization
├── index.md        # Documentation
├── *.js            # JavaScript code
├── style.css       # Styles (optional)
└── <name>.png      # Preview screenshot (created by screen-capture)