v1.2.1

Documentation: how to update an installed copy.

Both READMEs gain an Updating section stating plainly that there is no auto-update, and covering every install shape:

• Installer install — npx skills check shows whether the local copy drifted; npx skills update (or npx skills update html-prototype-reader) re-downloads only what changed. The CLI tracks each skill's source repo and content hash, and installs are symlinked, so one update refreshes every agent. Re-running npx skills add clarklee186/html-prototype-reader also pulls the current contents — valid, but redundant.
• Git clone — git pull; if the skill directory is a symlink to the clone, the new version is live immediately.
• Host agent's own manager (WorkBuddy, Claude Code plugins, …) — update from that manager; its copy is independent of the npx installer.
• Manual copy — copy the files again and overwrite; there is no merge step, local edits are overwritten.

Also documented: read the installed version from _meta.json, compare against this releases page, and note that agents load a skill when they use it — so an update takes effect on the next interaction without a restart. Re-check the Installation section after a major update, since requirements (playwright-core, a local Chrome or Edge) can change.

npm test remains 57/57. Version bumped to 1.2.1 in _meta.json and package.json.

v1.2.0

Deep traversal, drive mode and multi-version detection — built from real-world feedback on a 690 KB JS-assembled prototype.

Traversal (the biggest gap)

• Collapsed nav containers are expanded before entry discovery; the page budget is no longer consumed by navigation-only states.
• Screens are now classified into initial / page / navOnly / overlay by comparing main-content structure and text signatures against the navigation signature, each with its own budget (--max-screens, --max-nav-states).
• Entries are recorded as replayable selectors.
• On the reference prototype: 8 screens (7 of them the same page) → 22 screens with 16 real pages.

Source probes (new probe-source.js)

• Navigation probe aggregates many patterns (state compare/assign, data-*, fn('key') calls, registries, key-label pairs) and ranks driver candidates (assigns page state + calls render + name hint), detecting permission gates. Reference prototype: 6 → 210 candidate keys, driver hint go('%KEY%').
• Multi-version layer detection: 28 overwritten functions, 67 versioned identifiers, string patches — with a banner at the top of summary.md warning that the rendered final state is the last assignment.

Drive mode

• --drive "go('%KEY%')" --keys-auto --max-drive N walks the prototype's own API, so deep screens no longer need hand-written shell files.

Interaction probe (opt-in)

• --probe-interactions clicks overlay triggers, detects newly opened overlays (including containers whose content is filled by innerHTML) and records trigger → target links; clicks with no effect are reported as isolated interactions.

Output layering

• digest.md (a few hundred characters per screen), checklist.md (trigger → target plus structural assertions), screens/*.json per screen; prototype.json is lean by default (18 MB → 200 KB on the sample).

Acceptance

• diff --entry, --entry-js, --restored-entry* and --entries-from <prototype.json> (per-screen batch comparison with replay of each screen's own entry).
• schemaVersion bumped to 2 (additive fields: kind, screenKinds, sourceLayers, navigationProbe, overlayStates, triggerLinks, isolatedInteractions).

npm test now runs 57 assertions, including a collapsed-nav + multi-version fixture.

v1.1.0

Reliability, security and engineering hardening — the full fix pass after a code review of both scripts.

Acceptance can no longer silently pass

• Snapshot or page-load failures now set structure / pixel to null (never zeros), open the report with an explicit failure block, and exit with code 2. Previously an unmeasured dimension reported "no differences".
• Structure snapshots retry once before being declared failed.

Resource safety

• Both scripts release the browser in a finally block; the fatal handler uses exitCode instead of process.exit, so a thrown error no longer leaks a headless Chrome process.

Observability

• Every degraded step is collected into warnings[] (per page + top level, mirrored at the top of summary.md / diff-report.md) — 29 silently swallowed errors became traceable.
• Both artifacts carry schemaVersion (1).

Security

• New --no-network: blocks every request that is not file:// or localhost.
• externalHosts reports which third-party hosts a prototype tried to reach.
• The trust boundary (local file access is enabled for canvas/iframe reads, so run on trusted input) is now documented in SKILL.md, both READMEs and docs.

Tall pages

• Pixel comparison is banded (--max-height, default 12000px; 3000px bands) and reports truncation. A 22,200px page dropped from roughly 1 GB of pixel buffers to ~50 MB.

Performance

• The in-page library is injected once per page (window.__hprLib) and re-injected only when a navigation removes it — previously ~16 KB of source was re-parsed on every evaluate, 7 times per screen.
• Each element resolves computed style once instead of 3–5 times.
• Reference prototype: 9 s → 6 s capture, still 8 screens / 0 warnings.

Structure

• scripts/inpage-lib.js extracted so the in-page library can be syntax-checked; shared.js gained TUNING and SCHEMA_VERSION; dead retry loop removed.
• diff.js text and interaction comparisons use multisets, so 10 identical buttons vs 1 is now a reported gap.
• --shot-format png|jpeg + --jpeg-quality (capture) and --overlay-format (diff).

Engineering

• npm test (34 assertions): component matrix (24 widget-state checks), acceptance chain (self-diff 0, mutant detected, missing file → exit 2, tall page truncated), repo consistency (check-meta, check-docs).
• GitHub Actions CI on ubuntu and windows.
• check-meta and check-docs automate the drift hunts that previously needed a human (metadata parity, README EN/ZH parity, image language match, CLI-default coverage, link/docs existence).

v1.0.6

Documentation sync for the v1.0.4 / v1.0.5 capabilities.

Changed

• Both READMEs: How it works now documents the live-property state reading (checked / value / selected / open / indeterminate read as DOM properties, so JS-set states that never touch the markup are still captured) and the offViewport marker for off-canvas elements; Limits documents that the multi-version report is bounded by traversal coverage (unvisited screens report not-seen-in-capture, not dead).
• AGENTS.md gains two hard-won invariants: widget state is read as DOM properties, never attributes (the 17-point coverage gap in v1.0.5 was caused by exactly this), and off-canvas detection compares against document flow bounds, not the viewport.

Version bumped to 1.0.6 in _meta.json and package.json. No code changes.

v1.0.5

Full widget-state coverage in capture.

A dedicated component-coverage fixture (checkboxes, radios, single/multi select, search box, textarea, range/number, details accordion, open and closed dialogs, custom switch/slider roles, contenteditable, datalist, off-canvas drawer) took the matrix from 7/24 to 24/24.

Root cause of the gaps: attribute vs property. JS-set values do not update attributes, so search/textarea/range values, radio states, indeterminate flags and dialog/details open flags were silently missed by attribute-only reading.

Fixed / added

• semOf now reads live properties: value (input/textarea/select), checked + indeterminate (checkbox/radio), selected + options + optionCount + multiple (select), open (dialog/details), value/max (progress/meter).
• aria-state attributes captured: aria-checked, aria-selected, aria-expanded, aria-pressed, aria-valuenow, aria-valuetext, aria-valuemin/max, aria-controls.
• interactiveList now includes dialog, details, option, progress, meter and contenteditable elements, and marks off-canvas elements with offViewport (detected against document flow bounds, so normal below-the-fold content is never flagged).

Version bumped to 1.0.5 in _meta.json and package.json. diff.js unchanged.

v1.0.4

Dead-content report for multi-version AI prototypes.

AI-generated HTML often keeps several versions alive at once: the stylesheet is the union of all versions while the DOM only holds the current one, and screen content waits inside JS template strings. capture.js now measures and reports this so the restoration targets the reachable version only.

Added

• pages[].deadContent in prototype.json plus a summary section: dead CSS classified three ways (matchedNow / dormant = tokens seen on other screens, e.g. active states / notSeenInCapture = never seen during capture, may activate on unvisited screens, theme states or deep entries).
• Duplicate id detection and version-residue class names (-old / -v2 / -backup patterns).
• Hidden branches (roots only; natural-hidden tags like head/script excluded) with subtree size, interactive count and reachability.

Measured on a 783 KB JS-assembled dashboard prototype
1,092 statically-checkable CSS rules: 69 matched at capture time, 20 dormant (active-state selectors), 1,003 never seen during capture; 605 buttons and 285 inputs waiting in template strings; 8 view identifiers.

Version bumped to 1.0.4 in _meta.json and package.json. diff.js unchanged.

v1.0.3

English visual fix for the bilingual README.

Fixed

• The features infographic was shared by both READMEs but carried Chinese copy (the upstream template hardcodes a Chinese heading), so the English README displayed a Chinese image.
• assets/features.webp is now the English render (used by README.md) and assets/features.zh-CN.webp is the Chinese render (used by README.zh-CN.md), matching the README.md / README.zh-CN.md naming convention.

Notes

• Both images are rendered from the readme-generator skill templates with language-appropriate copy; the skill's font-size floor is enforced (heading 68px, card title 48px, body 28px, labels 22px).
• _meta.json and package.json bumped to 1.0.3. No code changes.

v1.0.2

Portfolio-grade bilingual README with generated visuals.

Documentation

• Both READMEs restructured into the portfolio layout: centred header with banner, two badges, then What / Why / You get / How it works / Quick start / Install / CLI / Limits / Proof / License / Author.
• Depth moved out of the entrance into docs/: CLI reference and output schema, each in English and Chinese.
• AGENTS.md updated for the new docs/ and assets/ layout and the README structure rule.

Visuals

• assets/banner.webp — AI-generated art composed with the exact headline text via HTML/CSS; provider watermark cropped by the 16:9 cover fit.
• assets/features.webp — rendered from the readme-generator skill's HTML templates with this project's own story.
• All in-image text meets the design floor (headline 116px, body ≥28px, labels 22px) and stays readable when GitHub scales the image down.

Version

• _meta.json and package.json bumped to 1.0.2. No behaviour change; the two CLI tools are unchanged from 1.0.1.

v1.0.1

Fixes and hardening after a full project review.

Added

• Same-origin iframe recursion in capture.js (depth ≤ 2) — the documented behaviour is now actually implemented; cross-origin frames record src only.
• capture.js freezes animations/transitions before screenshots, so per-screen visual baselines are reproducible across runs.

Changed

• scripts/shared.js introduced as the single source of truth for STYLE_PROPS, DIFF_PROPS, FREEZE_CSS, LAUNCH_ARGS, IFRAME_DEPTH_LIMIT (the capture and diff property lists had drifted apart).
• summary.md now reports interactive entries found/clicked and iframe recursion stats.
• Diff hotspots are labelled by document outline instead of the full-page container.

Fixed

• Hardcoded user paths removed in favour of os.homedir()-derived resolution.
• Dead code removed; pseudo-element and breakpoint edge cases documented.

Hygiene

• Added .gitignore and package.json (engines.node >= 18, npm run capture/diff).