microsim-utils

name	microsim-utils
description	Utility tools for MicroSim management including quality validation, screenshot capture, icon management, index page generation, and iframe height synchronization. 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

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	Synchronize iframe heights from CANVAS_HEIGHT in JS files to sim and chapter index.md files
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

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

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:

python /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:

python /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:

python /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.

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 python 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 python 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 python 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.

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 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)