single-html-forge

name	single-html-forge
description	Generate a single self-contained HTML file — a horizontal slide deck, a vertical-scroll explainer document, or a fixed-canvas summary image — with zero external runtime dependencies, then verify it mechanically. Use when the user asks for HTMLスライド, 単一HTMLスライド, single-file HTML presentation, ブラウザーで開く説明資料, HTML 説明資料, HTMLサマリ画像, or self-contained HTML, or wants to hand someone a deck or explainer that opens anywhere without PowerPoint. Also use to embed images into such a file or to re-check an existing one. Does not output PPTX.
argument-hint	作りたい内容と、deck / doc / poster のどれか
user-invocable	true
license	CC BY-NC-SA 4.0
metadata	{"author":"yamapan (https://github.com/aktsmm)"}

Single HTML Forge

One HTML file. No CDN, no build step, no external fetch at runtime. Opens the same on any machine and survives being emailed.

When to Use

• "HTMLスライドを作って" / "単一HTMLで資料にして" / "ブラウザーで開ける説明資料にして" / "サマリ画像を1枚"
• Handing a deck or explainer to someone who should not need PowerPoint
• Embedding images into a self-contained HTML artifact
• Re-verifying or editing an artifact this skill produced

Not for: PPTX output (this skill does not produce it), editable diagram source files, or anything needing a live server.

Archetype Routing

Ask which one unless the request already says. Load only that archetype's reference.

Archetype	Shape	Use for	Reference
deck	16:9 slides, keyboard nav, presenter overlay	talks, walkthroughs	archetype-deck.md
doc	vertical scroll, sidebar nav, numbered citations	explainers, comparisons, handouts	archetype-doc.md
poster	one fixed canvas, exported as PNG	summary images, social cards	archetype-poster.md

deck also has an outline layout: a slide list on the left, the stage on the right, collapsed with O when projecting. Start from deck-outline-skeleton.html when the deck will be read or reviewed rather than presented.

Intake

1. Archetype (above).
2. Topic, audience, what they should be able to do or decide afterwards, and roughly how much content.
3. Colour direction — propose two or three, or derive one from the topic. See design-tokens.md.
4. Images? If any is a screenshot or of unknown provenance, ask the sanitization question in Hard Constraints before embedding.
5. Which export, if any: PDF, PNG, or per-slide PNG. Produce only what was asked for.

Hard Constraints

These gate the output. They are here, not in a reference, because a reference may never be read.

• No artifact-specific JavaScript or CSS. Script is the bundled runtime only; styling is the fixed template plus typed custom properties. Any other <script> or <style> fails verification.
• Images ride in a data: URI on an <img>, or in allowlisted inline SVG. Nothing else may carry a resource — not CSS url(), not srcset, not <object>, <embed>, <iframe>, <video>, <link>, and never srcdoc.
• No web fonts. System font stack only. Glyphs will differ across machines; say so rather than claiming pixel fidelity.
• Do not generate brand logos or trademarks.
• Never write a customer name, tenant name, subscription id, or internal hostname into the output.
• Before embedding a screenshot or an image of unknown provenance, ask: "is this sanitized for publication?" On "no" or "not sure", stop and mask it first (mask_image.py). A text scan cannot see a name rendered inside an image, so this judgement stays with the user. Re-ask if the image changes.
• Prefer the active workspace's instructions for colour and formatting when they exist; otherwise use this skill's defaults.
• Never call an artifact finished on Tier 1 alone. Without the browser pass, report it as UNVERIFIED.

Build Flow

1. Storyboard first and stop there. Open with one sentence for the whole artifact — where it starts, what it passes through, where it lands — then one row per slide or section: the id it will keep, the assertion it makes, and the block that carries it. Wait for the user's answer before opening a skeleton.

   id	assertion	block
   s2	鍵は保管するのをやめる	shf-cards × 2

   Assertions, not topic names (anti-slop.md). One wrong line is free to fix here and costs a rebuild plus a re-verify once twelve slides exist. Skip only for a poster, or when the user arrives with the structure already settled. If the user hands the rest back, fill it provisionally and mark which rows they never saw.

2. Copy the skeleton for the chosen archetype from assets/skeletons/.

3. Replace the content, using the storyboard ids as data-slide-id and section id. Keep them stable — they are the handles for later edits.

4. Adjust colours by editing <style id="shf-theme"> only; that block is the whole design system, so carrying it into the next artifact is how a series stays consistent. Never touch <style id="shf-css"> or <script id="shf-runtime">; both are hash-pinned.

5. For each image: embed_assets.py, then paste the dataUri into an <img> with alt and data-asset-ref, and add the asset entry to <script id="shf-model">.

6. Verify, then export only the requested format.

Changing anything under assets/runtime/ or assets/css/ means re-running build_skeletons.py, which regenerates the skeletons and re-pins the registry.

Verification Gate

python scripts/verify_html.py <artifact.html> --tier2

• Tier 1 is standard library only and always runs: canonical grammar, element and attribute allowlist, pinned-region hashes, theme tokens, model and asset closure, data URI decode, image metadata, link schemes, size budget.
• Tier 2 needs Playwright: blocks all network egress, walks every slide, waits for images to finish decoding, then checks for zero-size images, missing viewBox, overflow, and console errors.

Exit codes: 0 PASS, 1 FAIL, 2 UNVERIFIED. Anything but 0 means do not ship it.

Fast path is the default: one viewport, only the requested export. Do the exhaustive pass at publish time. Even the fast path never skips single-file-ness, image decode, overflow at the target viewport, deck navigation, or the sanitization question.

Scripts

Script	Needs	Purpose
verify_html.py	stdlib (Tier 2: Playwright)	the gate
build_skeletons.py	stdlib	rebuild skeletons and re-pin hashes
embed_assets.py	stdlib (resize: Pillow)	fetch, strip metadata, encode
mask_image.py	Pillow	mask rectangles before embedding
export_html.py	Playwright	PDF / PNG
test_verify.py	stdlib	proves the gate actually fails

Missing Pillow or Playwright stops the affected step with installation guidance. It never silently degrades.

References

• artifact-grammar.md — the normative rules the verifier enforces
• design-tokens.md — colour recipe and the token grammar
• japanese-typography.md — CJK line breaking and spacing
• asset-embedding.md — image routes, budget, provenance
• component-patterns.md — the markup blocks available
• anti-slop.md — what makes output look generated
• verification.md — what to check by eye

Requirements

A harness with file read/write and Python 3.x. Everything in this folder is self-contained; copy it anywhere and it still works.

Done Criteria

• Archetype confirmed with the user
• Storyboard agreed, or the skip recorded (poster / structure already settled)
• Claims that could not be backed are named for the user, or the artifact makes none
• verify_html.py --tier2 exits 0; a Tier 1-only run is reported as UNVERIFIED
• Every image has alt, a model entry, and a sanitization answer if it is a screenshot
• Only the requested exports exist
• Output carries no customer, tenant, or subscription identifiers