Htmldrop

htmldrop — Share HTML as Hosted Links

Publish any HTML file and get a shareable URL instantly via the htmldrop CLI. Three modes:

• Simple share (Surge.sh hosting) — get a public or password-protected link to a static page.
• Collaborative feedback + converge — publish with an embedded annotation widget so reviewers can highlight text and comment with no account, then pull the feedback, add evidence-backed comments programmatically, and synthesize an improved version with AI.
• Edit mode (local, pre-publish) — serve the file on 127.0.0.1 and iterate on it live with the user: they annotate and comment on one surface; you edit the file (it hot-reloads), reply, or ask them a question. No hosting, nothing published. This is the loop to firm a doc up before sharing it — or between rounds of external feedback. See references/edit-mode.md.

Design applies to every mode: before generating or serving any HTML, match the design system of the project the artifact is about, so it looks like the real product rather than a generic page. See references/design-and-visuals.md — read it whenever you author or edit HTML here.

MUST DO BEFORE WRITING ANY HTML (all modes)

This fires automatically, whether the user runs simple share, feedback, or edit mode — and whether or not they ever type a htmldrop playbook/htmldrop design command. It is the default behavior of this skill, not an opt-in. Do both, in order, before you write or edit a single line of HTML:

1. Match the look first (theme + styling). Detect and adopt the design system of the project the artifact is about (not necessarily your current working dir), in this priority:

   1. a look/system the user named → use exactly that;
   2. the target project's design system → Tailwind/theme config, :root CSS variables/design tokens, an in-use component library, or brand assets (logo, palette, fonts) on an existing styled page;
   3. nothing to match → a clean, deliberate neutral default (small palette, system font stack, generous spacing, clear hierarchy). When you deliver, state which source you used in one line ("styled with the project's Tailwind theme" / "no theme found — neutral default"). Never ship a generic template when a real design system was discoverable.

2. Pick the right shape (the MUST-router). Match the content against these triggers and reach for the right structure before writing. One artifact often combines several:

   • relationships / flows / architecture / sequences → a real Mermaid diagram, never hand-built <div> boxes. Re-render on light/dark flip (Mermaid never restyles an already-drawn SVG).
   • comparing options / tools / approaches / tradeoffs → aligned option cards; make the cost as visible as the benefit (don't hide the downside).
   • teaching a concept / how something works → the explainer shape: (a) lead with the one idea that explains everything; (b) a "feel-the-difference" micro-demo with the smallest honest code (a 450ms setTimeout is network lag; a toggle is a mode switch); (c) a looping before/after; (d) a cheat-sheet table last, including the honest trade-off.
   • proposing a change / roadmap / approach → goal → current → proposed → risks → open questions. Mock the UI, don't describe it.
   • dense structured data / many attributes → a real <table>, aligned columns, no horizontal overflow, highlight the decision-relevant column.
   • a decision/answer needed from the viewer → an in-artifact form with native controls and one explicit send answer per question that delivers the choice to the agent via the feedback channel (not a local-only "queued" state that never arrives).
   • sequential narrative to step through → slides: one idea each, large type, keyboard nav.

The full contract lives in references/design-and-visuals.md — ready-to-paste pinned CDN snippets (with integrity hashes), a layout-safety CSS block, a theme-aware Mermaid re-render snippet, and the per-shape guidance. Read it before authoring; it is the single source of truth for both the guardrail above and the optional commands below.

Optional standalone commands (same content, on demand). If you (or a non-skill agent, or a curious user) want the guidance without this skill loaded, the CLI exposes it directly — these are a convenience, not a replacement for the guardrail:

• htmldrop design [--json] — prints the design contract (priority rule, pinned snippets, layout-safety CSS, theme-aware Mermaid).
• htmldrop playbook [id] [--json] — lists the shapes, or prints one (diagram, comparison, input, plan, table, slides, explainer).

Prerequisites

• Node.js >= 18
• npm install -g @yeefeiooi/htmldrop@latest (the binary is still htmldrop)
• For simple share: run htmldrop init once (sets up Surge account + subdomain)
• For feedback/converge: run htmldrop auth setup once (generates an author API key in ~/.htmldrop/config.json)
• For edit mode: nothing — it's fully local (no init, no Surge, no auth key). Lowest-friction entry point.

Critical Rules

1. Check prerequisites first — the relevant setup must be done before any push
2. Never store credentials — Surge auth lives in ~/.netrc; the feedback author key lives in ~/.htmldrop/config.json
3. For password-protected files — report the URL and password to the user, and remind them htmldrop stores the password nowhere (it's unrecoverable), so they should save it in a password manager now
4. Use absolute paths when calling htmldrop push

Mode 1: Simple Share (Guided Flow)

This is the most common case — "just give me a link." Follow this sequence.

Step 1: Verify Environment

which htmldrop
test -f ~/.htmldrop/config.json && echo "initialized" || echo "not initialized"

If not set up, direct the user to run htmldrop init interactively. The first deploy triggers Surge's interactive email/password login. After that, the token is saved in ~/.netrc and future deploys are automatic.

Step 2: Ask Privacy Preference

Present two options:

1. Public — Anyone with the link can view it
2. Password-protected — Content is AES-256 encrypted; viewers need a password to unlock

Step 3: Handle Based on Choice

If public — ask one follow-up: "Block search engines and AI crawlers from indexing?"

• Yes → htmldrop push --noindex /path/to/file.html
• No → htmldrop push /path/to/file.html

If password-protected — ask for a password, offer to generate one, or pipe one from the user's password manager. htmldrop never stores the password (held in memory only to encrypt at push time, then discarded), so tell the user to save it in their password manager the moment it's created — a forgotten one can't be recovered (re-push with a new one). Three ways to supply it:

# 1. Let htmldrop generate a memorable one (two words + a number), printed once:
htmldrop push --password --generate-password /path/to/file.html

# 2. Pipe from a password manager so it never touches shell history:
htmldrop push --password "$(op read op://vault/item/password)" /path/to/file.html   # 1Password
htmldrop push --password "$(bw get password <id>)" /path/to/file.html               # Bitwarden
htmldrop push --password "$(pass show <name>)" /path/to/file.html                   # pass

# 3. A known value:
htmldrop push --password <pass> /path/to/file.html

A bare --password (no value) reads from $HTMLDROP_PASSWORD or a hidden prompt.

Step 4: Report Results

Public:

Published: https://subdomain.surge.sh/filename.html

Password-protected:

Published with password protection!
  URL: https://subdomain.surge.sh/filename.html
  Password: coral-sunset-42
htmldrop never stores this password — it can't be recovered.
Save it in your password manager now, then share both with your recipients.

Skip the Flow When Intent is Clear

If the user explicitly states preference in their request, skip the question:

• "Share report.html publicly" → push directly
• "Share spec.html with password hello123" → push with provided password
• "Publish this privately" → go to password flow

Simple-Share Commands

Mode 2: Collaborative Feedback & Converge

Use this when the user wants people to review and comment on an HTML doc, spec, or report — or when they want to pull, answer, or synthesize that feedback. Publishing with --feedback embeds an annotation widget in the page.

The Single-URL Model

htmldrop push <file> --feedback prints one shareable Feedback URL like:

https://htmldrop-feedback.htmldrop.workers.dev/doc/<uuid>

That single /doc/<uuid> link serves everyone:

• Reviewers open it, highlight any text (or drag a box over an area via the ▢ toggle) and leave comments — no account, no login. They comment anonymously (an optional name field is available).
• The author uses the same link to see the page with all comments rendered inline.

There is no separate "viewer link" vs "author link." Share the one URL and you are done.

The link is stable. Re-pushing the same file with --feedback reuses its docId, so the URL never changes and existing comments stay attached. This is why the agent loop below works: you can keep updating the document at the same link as feedback comes in. Use --new-doc only when you deliberately want a fresh, empty doc.

Prerequisites for this mode

• htmldrop auth setup run once (creates the author API key). Add --force to regenerate it.
• converge additionally needs an LLM API key (Anthropic, OpenAI, or Gemini) in the environment — ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, or LLM_API_KEY. The provider is auto-detected from the key; override with --provider/--model. No SDK install needed.

Feedback & Converge Commands

Roles: anyone with the link is a reviewer (read + comment, via feedback read / feedback add --doc-id / fetch — no key). The owner (author-key holder who published) additionally runs converge and feedback clear. So a teammate's Claude/Codex session can fully review a shared doc, but only the owner synthesizes/converges it.