microsim-utils

name: microsim-utils description: Utility tools for MicroSim management including quality validation, screenshot capture, icon management, index page generation, iframe height synchronization, iframe control-visibility testing, and visual layout review. Routes to the appropriate utility based on the task needed.

MicroSim Utilities

Overview

This meta-skill provides utility functions for managing and maintaining MicroSims in intelligent textbook projects. It consolidates four 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)

Step 1: Identify Utility Type

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

Routing Table

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

Iframe-height utilities at a glance

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

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: Synchronize iframe heights across MicroSim index.md files and chapter files using the CANVAS_HEIGHT comment in each sim's JavaScript file as the single source of truth.

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

How it works:

• Reads // CANVAS_HEIGHT: <int> from the first 15 lines of each sim's .js file
• If the comment is missing, computes CANVAS_HEIGHT from drawHeight + controlHeight (+ graphHeight if present) and inserts the comment on line 2 of the JS file
• Sets iframe height = CANVAS_HEIGHT + 2 (2px for iframe border) in:
  • The sim's own docs/sims/<sim-id>/index.md
  • Any chapter file (docs/chapters/*/index.md) that embeds the sim
• 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
• --verbose — Show status for all sims, not just changes

Output: Summary showing sims synced, CANVAS_HEIGHT comments inserted, and iframe heights updated.

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)