webtweak 0.1.0

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "webtweak",
+  "version": "0.1.0",
+  "description": "Local visual editor for hand-coded HTML/CSS — captures edits as patches, Claude reconciles them into source",
+  "bin": {
+    "webtweak": "webtweak.js"
+  },
+  "files": [
+    "webtweak.js",
+    "overlay/",
+    "reconcile/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "visual-editor",
+    "css",
+    "html",
+    "wysiwyg",
+    "local"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stueydubs/webtweak.git"
+  },
+  "homepage": "https://github.com/stueydubs/webtweak"
+}

package/reconcile/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: webtweak-reconcile
+description: Reconcile visual edits captured by the webtweak tool into a site's real source. Reads a <page>.webtweak.json edits file, locates each patched element by its fingerprint, writes clean CSS in the site's house conventions (single-element scope by default), translates nudge intent into clean margin/padding, and marks batches reconciled. Use when the user has finished a webtweak session, says "reconcile my webtweak edits", "apply the webtweak changes", mentions a *.webtweak.json file, or wants webtweak edits folded into source and optionally pushed.
+---
+
+# webtweak reconcile
+
+The second half of the webtweak loop. The webtweak tool captures visual edits as *intent* and never touches source; this skill turns that intent into clean source. Reconcile is judgment work - when a match or a scope decision is genuinely ambiguous, ask rather than guess. That is the whole reason this half is a skill and not code.
+
+## Input
+
+A `<page>.webtweak.json` file sitting next to the edited page:
+
+```
+{ target, batches: [ { sessionId, savedAt, viewport, status, patches: [ { fingerprint, changes: { ...cssProps, nudge? } } ] } ] }
+```
+
+Only `status: "pending"` batches are reconciled. `reconciled` batches are history - never re-apply them.
+
+- `fingerprint`: `{ tag, id, classes, text, ownText, selector, siblingIndex, openTag }`. `ownText` is the element's own direct text (excluding descendants') - prefer it for matching leaf/text elements; `text` includes descendant text - use it to disambiguate containers. `openTag` is the opening tag with any injected inline `style` stripped, so it matches clean source. `selector` is a positional `nth-of-type` path - a weak tiebreaker only. `siblingIndex` is the element's 0-based position among siblings sharing its tag+classes - use it to name *which* one when several are otherwise identical.
+- `changes`: CSS property→value (kebab-case). A position nudge lives *inside* `changes` as `changes.nudge = { dx, dy }` (a 4px-snapped pixel offset), not a separate patch field.
+- `viewport`: the authoring window width in px (an integer).
+- **Captured values can be computed, not authored.** Several controls read `getComputedStyle`, so the value may be resolved rather than what the author wrote - do **not** treat these as ground truth; cross-check against source before writing (see step 5): `line-height`/`letter-spacing` may arrive as absolute px instead of a unitless ratio or em; `margin`/`padding` as resolved 4-value px that has lost `auto` (centering) or `%`; `width`/`height` as fixed px over an authored `%`/`auto`/`max-width`; colours may be alpha-stripped (a transparent element reads as opaque `#000000`).
+
+## Workflow
+
+1. **Find the work.** Locate the edits file (a given path, or `*.webtweak.json` beside the page). Run `scripts/wtreconcile.py pending <file>` for a summary of pending batches (add `--full`, or read the file directly, for complete fingerprints). If none, say so and stop.
+2. **Read the house style.** Open the stylesheet(s) governing the page. Note indentation, selector conventions, units, custom properties, and spelling - match them.
+3. **Locate each element.** Resolve the fingerprint the way a human would, in priority order: `id` (before accepting, confirm the located element's `tag` matches `fingerprint.tag` - guards a stale id moved to a different element) → `classes` + `ownText`/`text` (+ `tag`) → `openTag`. Use `selector` only as a last-resort tiebreaker or confirmation, never as a primary locator - it is a positional `nth-of-type` path captured on the injected DOM, so it is the least trustworthy signal and can be stale. If two candidates still match equally well (identical siblings), use `siblingIndex` to name which one; if it is still genuinely ambiguous, STOP and ask - never guess.
+4. **Decide scope** (per patch). Default: change only the element that was edited. If it is targeted by a shared class AND the change looks systemic (every sibling changed alike, or it is the sole instance of that class), ask "just this one, or all `.class`?". If single-element scope needs a selector hook the source lacks, prefer the captured `selector`; only add a class to the HTML after asking.
+5. **Translate the changes.**
+   - Plain CSS props → write as-is into the governing rule (or a targeted rule for single-element scope). One gotcha: a multi-word `font-family` may arrive unquoted (e.g. `font-family: Helvetica Neue`) - quote the family name on write (`"Helvetica Neue"`) so the CSS is valid.
+   - **Suspect computed-not-authored values** (per the Input caveat) - check each against the source declaration before writing, don't bake the resolved value:
+     - `line-height` as px (e.g. `33.6px`): if source authored a unitless ratio or em, keep that form - recompute the ratio from the new px ÷ the element's font-size, or ask for the ratio. Same for em `letter-spacing`.
+     - `margin`/`padding` as 4-value px where source had `auto` (centering) or `%`: preserve the `auto`/`%`; only change the side(s) the user actually moved, not the whole shorthand.
+     - `width`/`height` as fixed px where source was `%`/`auto`/`max-width`-governed: confirm "fixed px or keep it fluid?" rather than baking px and breaking responsiveness.
+     - `background-color`/`color` **absent** where you'd expect one: the overlay shows a transparent colour as `#000000` in the swatch and treats clicking that shown value as a no-op revert, so no patch is emitted even if the user meant to set solid black. If a black background/colour is clearly intended (e.g. visible in a screenshot) but no patch is present, ask before writing one.
+     - `width`/`height` on a non-replaced `inline` element: the overlay disables these inputs and the resize grips for inline elements, so this patch can no longer be emitted. If you see one in an older edits file, skip it and note it ("dropped width on inline `<code>` - needs `display:inline-block` first").
+   - `nudge {dx, dy}` → clean spacing. The offset is a `translate(dx, dy)`, so **positive dx = moved right, positive dy = moved down**. Map to margins with the matching sign: `dy>0` (down) → add to `margin-top`; `dy<0` (up) → reduce `margin-top` (go negative if needed); `dx>0` (right) → add to `margin-left`; `dx<0` (left) → reduce `margin-left`. Worked example: `nudge {dx: 0, dy: -8}` means dragged up 8px → take 8px off `margin-top` (e.g. `margin: 20px 0` → `margin: 12px 0`). Never bake in `transform` or `position: absolute`. If the nudge is large or flow cannot express it, flag it as a v2 reorder and skip it.
+6. **Check responsiveness.** The batch `viewport` is the width the edits were authored at. If a width/size change made at a wide viewport would obviously break mobile, warn and offer to scope it to a media query.
+7. **Write** the CSS into the stylesheet already governing the element, in house conventions. Show a concise diff summary.
+8. **Mark done.** `scripts/wtreconcile.py mark <file> <sessionId>` flips that batch to `reconciled` (timestamped); it stays in the file as history, never delete it. On success it prints `marked N batch(es) reconciled` (N≥1) and exits 0; on a wrong/unknown sessionId it prints `... nothing marked` to stderr and exits non-zero. Treat a non-zero exit (or the absence of a `marked N` success line) as: nothing was flipped, so the edits are still pending and would re-apply next run - resolve that before telling the user it's done.
+9. **Stop at source.** Reconcile's job ends at writing source and marking the batch. Never push, commit, or deploy unless the user explicitly asks for it in this session - summarise what changed and let them decide.
+
+## Helper script
+
+`scripts/wtreconcile.py` (Python stdlib only):
+
+- `pending <file>` - one-line summary per pending patch; add `--full` for the complete patch JSON (fingerprints + changes)
+- `mark <file> [sessionId]` - flip the matching pending batch to `reconciled` with a timestamp. Omitting the sessionId marks the single pending batch, but **fails** (marks nothing) if more than one is pending, so reconciling one session can't silently retire another. Prints `marked N` + exits 0 on success; exits non-zero and marks nothing on a no-match or an ambiguous bare `mark`.
+- `status <file>` - counts (pending vs reconciled) + newest pending save time, for a quick "is this file fully reconciled?" check

package/reconcile/scripts/wtreconcile.py

@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+"""Helpers for the webtweak-reconcile skill.
+
+Deterministic bookkeeping over a <page>.webtweak.json edits file so Claude
+doesn't hand-edit JSON: list pending batches, mark batches reconciled, and
+report status. Python stdlib only.
+"""
+
+import argparse
+import json
+import os
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import NoReturn
+
+
+def _die(msg: str) -> NoReturn:
+    sys.stderr.write(f"wtreconcile: {msg}\n")
+    raise SystemExit(1)
+
+
+def _load(path: str) -> dict:
+    try:
+        doc = json.loads(Path(path).read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        _die(f"{path} not found")
+    except json.JSONDecodeError as e:
+        _die(f"{path} is not valid JSON (corrupt edits file): {e}")
+    except OSError as e:
+        _die(f"cannot read {path}: {e}")
+    # Guard the shape the way the server's apply_batch does, so a valid-JSON-but-wrong
+    # structure dies cleanly instead of as a raw AttributeError mid-iteration.
+    if not isinstance(doc, dict):
+        _die(f"{path} is not a JSON object (corrupt edits file)")
+    batches = doc.get("batches")
+    if batches is not None and (not isinstance(batches, list)
+                                or any(not isinstance(b, dict) for b in batches)):
+        _die(f"{path} has a malformed batches array (corrupt edits file)")
+    return doc
+
+
+def _save(path: str, doc: dict) -> None:
+    # Atomic + flushed: temp file in the same dir, fsync, then replace - so an
+    # interrupted mark never truncates the edits file (it has no .bak fallback here).
+    p = Path(path)
+    tmp = p.parent / (p.name + ".tmp")
+    try:
+        with open(tmp, "w", encoding="utf-8") as f:
+            f.write(json.dumps(doc, indent=2) + "\n")
+            f.flush()
+            os.fsync(f.fileno())
+        tmp.replace(p)
+    except BaseException:
+        tmp.unlink(missing_ok=True)
+        raise
+
+
+def _changes_summary(changes: dict) -> str:
+    parts = []
+    for k, v in changes.items():
+        if k == "nudge" and isinstance(v, dict):
+            parts.append(f"nudge({v.get('dx')},{v.get('dy')})")  # surface drag magnitude
+        else:
+            parts.append(k)
+    return ", ".join(parts)
+
+
+def _describe(fp: dict) -> str:
+    s = fp.get("tag", "?")
+    if fp.get("id"):
+        s += "#" + fp["id"]
+    elif fp.get("classes"):
+        s += "." + fp["classes"][0]
+    text = (fp.get("ownText") or fp.get("text") or "").strip()
+    if text:
+        s += f' "{text[:40]}"'
+    return s
+
+
+def pending(args) -> None:
+    doc = _load(args.file)
+    pend = [(i, b) for i, b in enumerate(doc.get("batches", []))
+            if b.get("status") == "pending"]
+
+    if args.full:  # full patch JSON (fingerprints + changes) for deep work
+        out = [
+            {"index": i, "sessionId": b.get("sessionId"), "savedAt": b.get("savedAt"),
+             "viewport": b.get("viewport"), "patchCount": len(b.get("patches", [])),
+             "patches": b.get("patches", [])}
+            for i, b in pend
+        ]
+        json.dump(out, sys.stdout, indent=2)
+        print()
+        return
+
+    if not pend:
+        print("no pending batches")
+        return
+    for i, b in pend:  # cheap orientation summary (read the file itself for full fingerprints)
+        patches = b.get("patches", [])
+        print(f"[{i}] session={b.get('sessionId')} saved={b.get('savedAt')} "
+              f"viewport={b.get('viewport')} patches={len(patches)}")
+        for p in patches:
+            print(f"    - {_describe(p.get('fingerprint', {}))}  [{_changes_summary(p.get('changes') or {})}]")
+
+
+def mark(args) -> None:
+    doc = _load(args.file)
+    now = datetime.now().isoformat(timespec="seconds")
+    candidates = [
+        b for b in doc.get("batches", [])
+        if b.get("status") == "pending"
+        and (args.session is None or b.get("sessionId") == args.session)
+    ]
+
+    if not candidates:
+        if args.session is not None:
+            _die(f"no pending batch with sessionId '{args.session}' - nothing marked")
+        _die("no pending batches to mark")
+
+    # Refuse to bulk-retire multiple sessions on a bare `mark`: each pending batch is a
+    # separate session that may not have been reconciled yet, and marking it loses it.
+    if args.session is None and len(candidates) > 1:
+        ids = ", ".join(str(b.get("sessionId") or "?") for b in candidates)
+        _die(f"{len(candidates)} pending batches ({ids}); pass a sessionId to mark one "
+             f"at a time - reconcile each before marking it")
+
+    for b in candidates:
+        b["status"] = "reconciled"
+        b["reconciledAt"] = now
+
+    _save(args.file, doc)
+    print(f"marked {len(candidates)} batch(es) reconciled")
+
+
+def status(args) -> None:
+    doc = _load(args.file)
+    batches = doc.get("batches", [])
+    pend = [b for b in batches if b.get("status") == "pending"]
+    recon = [b for b in batches if b.get("status") == "reconciled"]
+    last_pending = max((b.get("savedAt") or "" for b in pend), default="")
+    print(f"target:       {doc.get('target')}")
+    print(f"pending:      {len(pend)}")
+    print(f"reconciled:   {len(recon)}")
+    print(f"last pending: {last_pending or '-'}")
+    print("fully reconciled" if not pend else f"{len(pend)} batch(es) awaiting reconcile")
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="webtweak-reconcile helpers")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p = sub.add_parser("pending", help="list pending batches (summary; --full for patch JSON)")
+    p.add_argument("file")
+    p.add_argument("--full", action="store_true", help="dump full patch JSON, not a summary")
+    p.set_defaults(fn=pending)
+
+    m = sub.add_parser("mark", help="mark pending batch(es) reconciled")
+    m.add_argument("file")
+    m.add_argument("session", nargs="?", default=None,
+                   help="sessionId to mark (all pending if omitted)")
+    m.set_defaults(fn=mark)
+
+    s = sub.add_parser("status", help="report pending vs reconciled counts")
+    s.add_argument("file")
+    s.set_defaults(fn=status)
+
+    args = ap.parse_args()
+    args.fn(args)
+
+
+if __name__ == "__main__":
+    main()

package/webtweak.js

@@ -0,0 +1,380 @@
+#!/usr/bin/env node
+// webtweak - a local visual editor for hand-coded HTML/CSS pages.
+//
+// Opens a local source .html file in the browser with an editing overlay,
+// captures visual changes as machine-readable patches, and writes them to a
+// running-history edits file (<name>.webtweak.json) next to the page. Claude
+// then reconciles those patches into the real source. See CONTEXT.md / ADR-0001.
+//
+// Node.js stdlib only. No dependencies.
+'use strict';
+
+const http  = require('node:http');
+const fs    = require('node:fs');
+const path  = require('node:path');
+const os    = require('node:os');
+const { execFile } = require('node:child_process');
+
+const TOOL_DIR   = path.dirname(path.resolve(__filename));
+const OVERLAY_DIR = path.join(TOOL_DIR, 'overlay');
+const RESERVED   = '/__webtweak__/';
+const MAX_BODY   = 8 * 1024 * 1024; // 8 MB cap on a save payload
+
+const OVERLAY_ASSETS = {
+  'overlay.js':       'application/javascript; charset=utf-8',
+  'overlay.css':      'text/css; charset=utf-8',
+  'interact.min.js':  'application/javascript; charset=utf-8',
+};
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.htm':  'text/html; charset=utf-8',
+  '.css':  'text/css; charset=utf-8',
+  '.js':   'application/javascript; charset=utf-8',
+  '.mjs':  'application/javascript; charset=utf-8',
+  '.json': 'application/json',
+  '.png':  'image/png',
+  '.jpg':  'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif':  'image/gif',
+  '.svg':  'image/svg+xml',
+  '.ico':  'image/x-icon',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.woff': 'font/woff',
+  '.woff2':'font/woff2',
+  '.ttf':  'font/ttf',
+  '.otf':  'font/otf',
+  '.eot':  'application/vnd.ms-fontobject',
+  '.txt':  'text/plain; charset=utf-8',
+  '.xml':  'text/xml; charset=utf-8',
+  '.mp4':  'video/mp4',
+  '.webm': 'video/webm',
+};
+
+// --- pure functions (no I/O) -----------------------------------------------
+
+function overlayMarkup(targetName) {
+  // Use ': ' separator to match Python's json.dumps format (tests rely on this).
+  const cfg = '{"target": ' + JSON.stringify(targetName) + '}';
+  return (
+    '\n<!-- webtweak overlay (injected, not part of source) -->\n' +
+    `<script>window.__WEBTWEAK__ = ${cfg};</script>\n` +
+    `<link rel="stylesheet" href="${RESERVED}overlay.css">\n` +
+    `<script src="${RESERVED}interact.min.js"></script>\n` +
+    `<script src="${RESERVED}overlay.js" defer></script>\n`
+  );
+}
+
+function injectOverlay(html, targetName) {
+  const markup = overlayMarkup(targetName);
+  const idx = html.toLowerCase().lastIndexOf('</body>');
+  if (idx === -1) return html + markup;
+  return html.slice(0, idx) + markup + html.slice(idx);
+}
+
+function applyBatch(doc, payload, now) {
+  if (doc && typeof doc === 'object' && Array.isArray(doc.batches)) {
+    doc = Object.assign({}, doc);
+  } else {
+    doc = { target: payload.target || null, batches: [] };
+  }
+  if (!doc.target && payload.target) doc.target = payload.target;
+
+  const patches = Array.isArray(payload.patches) ? payload.patches : [];
+  const session = payload.sessionId || 'unknown';
+  const batches = doc.batches.slice();
+
+  if (!patches.length) {
+    // Empty save: user reverted every edit this session - drop their pending batch.
+    doc.batches = batches.filter(b =>
+      !(b && typeof b === 'object' && b.sessionId === session && b.status === 'pending')
+    );
+    return doc;
+  }
+
+  const batch = {
+    sessionId: session,
+    savedAt:   now,
+    viewport:  payload.viewport || null,
+    status:    'pending',
+    patches,
+  };
+
+  const idx = batches.findIndex(b =>
+    b && typeof b === 'object' && b.sessionId === session && b.status === 'pending'
+  );
+  if (idx >= 0) batches[idx] = batch;
+  else batches.push(batch);
+  doc.batches = batches;
+  return doc;
+}
+
+function writeJsonAtomic(filePath, doc) {
+  const tmp = filePath + '.tmp';
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(doc, null, 2) + '\n', 'utf8');
+    fs.renameSync(tmp, filePath);
+  } catch (e) {
+    try { fs.unlinkSync(tmp); } catch (_) {}
+    throw e;
+  }
+}
+
+// --- HTTP helpers ----------------------------------------------------------
+
+function send(res, code, body, ctype) {
+  const buf = Buffer.isBuffer(body) ? body : Buffer.from(body, 'utf8');
+  res.writeHead(code, {
+    'Content-Type':   ctype,
+    'Content-Length': buf.length,
+    'Cache-Control':  'no-store',
+  });
+  res.end(buf);
+}
+
+function sendError(res, code, msg) {
+  send(res, code, `${code} ${msg}\n`, 'text/plain; charset=utf-8');
+}
+
+function log(msg) {
+  process.stderr.write(`  webtweak: ${msg}\n`);
+}
+
+// --- request handlers ------------------------------------------------------
+
+function serveOverlayAsset(name, res) {
+  const asset = path.resolve(OVERLAY_DIR, name);
+  // Path-traversal guard: must stay inside OVERLAY_DIR
+  if (asset !== OVERLAY_DIR &&
+      !asset.startsWith(OVERLAY_DIR + path.sep)) {
+    return sendError(res, 404, 'Unknown webtweak asset');
+  }
+  const ctype = OVERLAY_ASSETS[name];
+  if (!ctype) return sendError(res, 404, 'Unknown webtweak asset');
+  let buf;
+  try { buf = fs.readFileSync(asset); }
+  catch (_) { return sendError(res, 404, 'Unknown webtweak asset'); }
+  send(res, 200, buf, ctype);
+}
+
+function serveEdits(editsPath, res) {
+  let body = '{"batches": []}';
+  try {
+    const raw = fs.readFileSync(editsPath, 'utf8');
+    JSON.parse(raw); // validate; fall back to empty on corrupt
+    body = raw;
+  } catch (_) {}
+  send(res, 200, body, 'application/json');
+}
+
+function serveHtml(filePath, targetName, res) {
+  let html;
+  try { html = fs.readFileSync(filePath, 'utf8'); }
+  catch (e) { return sendError(res, 500, 'Read error'); }
+  send(res, 200, injectOverlay(html, targetName), 'text/html; charset=utf-8');
+}
+
+function serveStatic(filePath, res) {
+  let buf;
+  try { buf = fs.readFileSync(filePath); }
+  catch (_) { return sendError(res, 404, 'Not found'); }
+  const ctype = MIME[path.extname(filePath).toLowerCase()] || 'application/octet-stream';
+  send(res, 200, buf, ctype);
+}
+
+function handleSave(body, targetName, serveRoot, res) {
+  let payload;
+  try { payload = JSON.parse(body || '{}'); }
+  catch (_) { return sendError(res, 400, 'Bad JSON'); }
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload))
+    return sendError(res, 400, 'Bad JSON: expected an object');
+
+  const stem      = path.basename(targetName, path.extname(targetName));
+  const editsPath = path.join(serveRoot, stem + '.webtweak.json');
+
+  let doc = null;
+  if (fs.existsSync(editsPath)) {
+    let raw;
+    try { raw = fs.readFileSync(editsPath, 'utf8'); }
+    catch (e) {
+      // Transient read error - propagate; don't touch the file
+      return send(res, 500, JSON.stringify({ ok: false, error: e.message }), 'application/json');
+    }
+    try { doc = JSON.parse(raw); }
+    catch (_) {
+      // Corrupt JSON - back up and start fresh
+      const stamp  = Date.now();
+      const backup = editsPath + '.' + stamp + '.bak';
+      try { fs.renameSync(editsPath, backup); } catch (_) {}
+      log(`edits file corrupt; backed up to ${path.basename(backup)}`);
+    }
+  }
+
+  if (!payload.target) payload = Object.assign({ target: targetName }, payload);
+  const now = new Date().toISOString().slice(0, 19);
+  doc = applyBatch(doc, payload, now);
+  try { writeJsonAtomic(editsPath, doc); }
+  catch (e) {
+    return send(res, 500, JSON.stringify({ ok: false, error: e.message }), 'application/json');
+  }
+
+  const n = (payload.patches || []).length;
+  log(`saved ${n} patch(es) -> ${path.basename(editsPath)}`);
+  send(res, 200, JSON.stringify({ ok: true, file: path.basename(editsPath), patches: n }), 'application/json');
+}
+
+function createHandler(targetPath, serveRoot) {
+  const targetName = path.basename(targetPath);
+  const stem       = path.basename(targetName, path.extname(targetName));
+
+  return function (req, res) {
+    const rawPath = (req.url || '/').split('?')[0];
+
+    // --- webtweak API endpoints and overlay assets -------------------------
+    if (rawPath.startsWith(RESERVED)) {
+      const name = rawPath.slice(RESERVED.length);
+
+      if (name === 'edits' && req.method === 'GET') {
+        return serveEdits(path.join(serveRoot, stem + '.webtweak.json'), res);
+      }
+
+      if (name === 'save' && req.method === 'POST') {
+        const lenStr = req.headers['content-length'];
+        const length = parseInt(lenStr, 10);
+        if (!lenStr || isNaN(length) || length < 0) return sendError(res, 400, 'Bad Content-Length');
+        if (length > MAX_BODY) return sendError(res, 413, 'Payload too large');
+
+        const chunks = [];
+        let received = 0;
+        req.on('data', chunk => {
+          received += chunk.length;
+          if (received <= MAX_BODY) chunks.push(chunk);
+        });
+        req.on('end', () => {
+          if (received > MAX_BODY) return sendError(res, 413, 'Payload too large');
+          if (received < length)   return sendError(res, 400, 'Incomplete request body');
+          handleSave(Buffer.concat(chunks).toString('utf8'), targetName, serveRoot, res);
+        });
+        req.on('error', () => sendError(res, 400, 'Incomplete request body'));
+        return;
+      }
+
+      return serveOverlayAsset(name, res);
+    }
+
+    // --- static file serving -----------------------------------------------
+    if (req.method !== 'GET' && req.method !== 'HEAD')
+      return sendError(res, 405, 'Method not allowed');
+
+    let decoded;
+    try { decoded = decodeURIComponent(rawPath); }
+    catch (_) { return sendError(res, 400, 'Bad URL'); }
+
+    // Resolve and contain within serveRoot (path-traversal guard)
+    const local = path.resolve(serveRoot, decoded.replace(/^\/+/, ''));
+    if (local !== serveRoot &&
+        !local.startsWith(serveRoot + path.sep))
+      return sendError(res, 403, 'Forbidden');
+
+    // No directory listings
+    let stat;
+    try { stat = fs.statSync(local); }
+    catch (_) { return sendError(res, 404, 'Not found'); }
+    if (stat.isDirectory()) return sendError(res, 404, 'No listing');
+
+    const ext = path.extname(local).toLowerCase();
+    if (ext === '.html' || ext === '.htm') return serveHtml(local, targetName, res);
+    serveStatic(local, res);
+  };
+}
+
+// --- browser opener --------------------------------------------------------
+
+function openBrowser(url) {
+  const cmds = {
+    darwin: ['open',     [url]],
+    win32:  ['cmd',      ['/c', 'start', '', url]],
+  };
+  const [cmd, args] = cmds[os.platform()] || ['xdg-open', [url]];
+  execFile(cmd, args, { detached: true }, () => {});
+}
+
+// --- server ----------------------------------------------------------------
+
+function serve(targetPath, port, openBrowserFlag) {
+  const serveRoot = path.dirname(targetPath);
+  const handler   = createHandler(targetPath, serveRoot);
+  const server    = http.createServer(handler);
+
+  server.listen(port, '127.0.0.1', () => {
+    const actual = server.address().port;
+    const url    = `http://127.0.0.1:${actual}/${path.basename(targetPath)}`;
+    process.stdout.write(`webtweak editing: ${targetPath}\n`);
+    process.stdout.write(`  serving ${serveRoot}\n`);
+    // Flush before remaining lines so the test harness sees the port immediately.
+    process.stdout.write(`  listening on 127.0.0.1:${actual}\n`, () => {
+      process.stdout.write(`  open    ${url}\n`);
+      process.stdout.write(`  Ctrl-C to stop.\n\n`);
+    });
+    if (openBrowserFlag) openBrowser(url);
+  });
+
+  server.on('error', e => {
+    const hint = e.code === 'EADDRINUSE'
+      ? `cannot bind port ${port}. Try --port 0 for any free port.`
+      : e.message;
+    process.stderr.write(`webtweak: ${hint}\n`);
+    process.exit(1);
+  });
+
+  process.on('SIGINT', () => {
+    process.stdout.write('\nwebtweak stopped.\n');
+    server.close(() => process.exit(0));
+  });
+}
+
+// --- CLI -------------------------------------------------------------------
+
+function main() {
+  const args = process.argv.slice(2);
+  let htmlFile = null, port = 8723, noBrowser = false;
+
+  for (let i = 0; i < args.length; i++) {
+    if ((args[i] === '--port') && args[i + 1]) {
+      port = parseInt(args[++i], 10);
+      if (isNaN(port)) { process.stderr.write('webtweak: --port must be a number\n'); process.exit(1); }
+    } else if (args[i] === '--no-browser') {
+      noBrowser = true;
+    } else if (args[i] === '--help' || args[i] === '-h') {
+      process.stdout.write('Usage: webtweak <page.html> [--port N] [--no-browser]\n');
+      process.exit(0);
+    } else if (!args[i].startsWith('-')) {
+      htmlFile = args[i];
+    } else {
+      process.stderr.write(`webtweak: unknown option ${args[i]}\n`);
+      process.exit(1);
+    }
+  }
+
+  if (!htmlFile) {
+    process.stderr.write('webtweak: path to an .html file is required\n');
+    process.stderr.write('Usage: webtweak <page.html> [--port N] [--no-browser]\n');
+    process.exit(1);
+  }
+
+  const targetPath = path.resolve(htmlFile);
+  if (!fs.existsSync(targetPath)) {
+    process.stderr.write(`webtweak: not a file: ${targetPath}\n`);
+    process.exit(1);
+  }
+  const ext = path.extname(targetPath).toLowerCase();
+  if (ext !== '.html' && ext !== '.htm') {
+    process.stderr.write(`webtweak: expected an .html file, got ${ext || 'no extension'}\n`);
+    process.exit(1);
+  }
+
+  serve(targetPath, port, !noBrowser);
+}
+
+main();