Open Source Launch: DocCenter — A Cure for HTML Document ...

python aiohttp opensource ai-tools frontend tooling claude chatgpt productivity

Tags:
Suggested platforms: dev.to (best DX) · Hashnode (custom domain) · Medium (broad reach) · X long post

I. The Problem: AI-Era Document Sprawl

For the past year, I've been drowning in AI-generated HTML files.

Claude artifacts: ~20/day. ChatGPT canvas: ~10/day. Cursor and CodeBuddy reports: 5-8/day. They scatter across a dozen folders. Double-clicking only lets me view; fixing a typo means re-running the original prompt; finding historical versions is impossible.

I tried several alternatives and none worked:

Solution	Why it didn't work
VSCode	Needs a preview plugin; rich-text editing requires switching to source mode
Notion	Doesn't accept HTML uploads; copy-paste loses styles
Browser bookmarks	Can't edit, can't annotate
Self-hosted static site	Too heavy; every change means build → deploy

So I built DocCenter — a local workbench at localhost:9901 purpose-built for this disease.

Repo: https://github.com/louisecxqiu-glitch/html-doc-center

II. Tech Stack: Why a Single Python File + Vanilla JS

DocCenter's entire backend is one server.py, zero requirements.txt, with aiohttp as the only external dependency. The frontend is vanilla JS with no build step.

This isn't showing off — it's intentional. Three key decisions:

2.1 aiohttp over FastAPI

Dimension	aiohttp	FastAPI
Cold start	0.3s	1.5s (pydantic loading)
Memory	~30MB	~80MB
Mental overhead	One `web.RouteTableDef` and you're done	Need to grok Pydantic models

A workbench is not a product. It's a daily-use tool I run on my own laptop. Fast cold start and low memory beat clean OpenAPI docs by 100×. I have dashboard (9900), heartbeat (4011), cockpit (8088) running simultaneously — I won't accept 80MB per service.

2.2 Vanilla JS over React

Zero build = zero mental overhead. Fixing a bug doesn't mean npm install → npm run build → refresh. It means edit → Cmd+Shift+R.

The only embedded dependency is marked.min.js (Markdown rendering, MIT) sitting flat in web/vendor/. The entire web/ directory has 8 files — that's the whole frontend.

2.3 iframe over SPA Routing

The HTML files being edited are complete pages — they have their own CSS animations, JS interactions, external fonts. Extracting <body> into an SPA loses all that context.

iframe preserves each document's full runtime. DocCenter only injects a small saver-runtime.js before </body>, providing the editing toolbar and auto-save capability. Keeping the source file's runtime uncontaminated has been a hard rule since v1.0.

III. Core Architecture: Three Tiers

┌─────────────────────────────────────────────────────────────┐
│  Browser at localhost:9901                                  │
│                                                             │
│  ┌─────────────────┐   ┌──────────────────────────────────┐ │
│  │  web/app.js     │   │  iframe                          │ │
│  │  (sidebar tree) │   │  ┌────────────────────────────┐  │ │
│  │                 │←─→│  │ user's HTML                │  │ │
│  │                 │   │  │ + injected saver-runtime.js│  │ │
│  └─────────────────┘   │  └────────────────────────────┘  │ │
│         ↕ HTTP JSON    └──────────────────────────────────┘ │
└─────────┼───────────────────────────────────────────────────┘
          ↓
┌─────────────────────────────────────────────────────────────┐
│  server.py (aiohttp, single file)                           │
│  ┌───────────┬──────────────┬──────────────────────────────┐│
│  │ Static    │ Tree/Config  │ HTML Read/Write              ││
│  │ /         │ /api/tree    │ /api/file (inject saver)     ││
│  │ /static/* │ /api/config  │ /api/snapshot                ││
│  │ /changelog│              │ /api/save (overwrite/new/    ││
│  │           │              │            discard)          ││
│  └───────────┴──────────────┴──────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘

3.1 Backend (server.py): Path Safety is the Only Hard Rule

Every I/O handler must go through _resolve_safe(): resolve the input path to absolute, then verify it's under one of the scan_roots. Otherwise return 403.

def _resolve_safe(raw: str, scan_roots: list[str]) -> Optional[Path]:
    """The single gate for path traversal defense."""
    try:
        target = Path(raw).expanduser().resolve()
    except (OSError, RuntimeError):
        return None
    for root in scan_roots:
        root_path = Path(root).expanduser().resolve()
        if target == root_path or root_path in target.parents:
            return target
    return None  # caller returns 403

No new I/O handler may bypass this — it's been a hard rule since v1.0 and remains unbroken at v1.11.11.

scan_roots is configured in ~/.codebuddy/html-doc-center/config.json and editable via the settings panel. Defaults exclude _auto-save / node_modules / .git / dist / build.

3.2 Injection Layer (saver-runtime.js): Three Guardrails for Dirty Detection

This is the hardest part of the project. Dirty detection must trigger only when the user actively edits — not on page JS animations, scroll, or highlight effects.

// Guardrail 1: User interaction window
const USER_INTERACT_WINDOW_MS = 800;
let lastInteract = 0;
['keydown', 'mousedown', 'paste', 'cut', 'drop'].forEach(ev =>
  document.addEventListener(ev, () => { lastInteract = Date.now(); }, true)
);

// Guardrail 2: MutationObserver only watches childList + characterData
const mo = new MutationObserver(mutations => {
  if (Date.now() - lastInteract > USER_INTERACT_WINDOW_MS) return;
  if (mutations.some(m =>
      m.target.tagName === 'SCRIPT' ||
      m.target.tagName === 'STYLE')) return;
  setDirty(true);
});

// Guardrail 3: Delay 1s before observe to skip page init
setTimeout(() => {
  mo.observe(document.body, {
    childList: true,
    characterData: true,
    subtree: true
    // NEVER attributes: true — animations/scroll-highlight cause false positives
  });
}, 1000);

These three guardrails were established after a v1.2.4 false-positive bug. They have not regressed since. Read the comments before modifying this section — it's tempting to "optimize" by enabling attributes: true, which immediately regresses.

3.3 Frontend (app.js): The Single UX Decision Point

When switching files / closing / refreshing while isDirty=true, this dialog appears:

┌─────────────────────────────────────────┐
│  You modified this document             │
│                                         │
│  ✅ Overwrite source                    │
│  🆕 Save as review copy                 │
│  🗑 Discard changes                     │
└─────────────────────────────────────────┘

This is the only decision point in the entire UX. I tried adding a 4th 💾 button ("Save and continue editing") in v1.2.5 and reverted it the same hour — more decision points = more user fatigue. Less is more isn't a slogan; it's a gate every "let's add a button" idea must pass.

IV. 5 Hard-Won Anti-Bug Rules

42 iterations from v1.0 to v1.11.11 stepped on plenty of mines. The v1.11 series alone had 11 consecutive hotfixes that beat me into submission and produced 5 hard rules, all written into ITERATION-SOP.md:

Rule 1: Real Browser Drill — `curl 200` ≠ User-Perspective Working

Cautionary tale (v1.11.10): Three-tab switching feature. curl returned 200, 0 lint errors, I claimed done. User testing: switching to "Favorites" or "Recent" tab showed blank.

Root cause: CSS .active { display: block } couldn't override inline style="display:none" left over in HTML.

Rule: Before commit, you must hard-refresh in browser (Cmd+Shift+R) and click 3+ core interactions from user perspective. Acceptance reports cannot consist only of curl 200. Write "I clicked X in browser and saw Y."

Rule 2: Guard Expressions Need Explicit Verification

Cautionary tale (v1.11.11): if (window.sidebarTabsCtl) was forever false because sidebarTabsCtl is an IIFE-internal const and was never attached to window.

// ❌ Forever false
(function() {
  const sidebarTabsCtl = { activate: ... };
})();
if (window.sidebarTabsCtl) { ... }  // never enters

// ✅ Reference within closure
(function() {
  const sidebarTabsCtl = { activate: ... };
  function onClick() {
    sidebarTabsCtl && sidebarTabsCtl.activate('tree');
  }
})();

Rule: Before writing if (X), confirm X's actual visibility in the current scope.

Rule 3: Grep Inline Style Residue Before Changing CSS .active / display

Rule: CSS specificity: inline > id > class > tag. Before adding new class-based display control, grep old HTML for same-name style="display:none" residue — it will override your CSS. !important is the last resort, not the first.

Rule 4: DOM-Dependent Actions After Toggle Need rAF

Cautionary tale (v1.11.11): Click favorite folder → activate('tree') toggles display → immediately scrollToPath() calculates position → calculates on stale layout → zero visual feedback.

// ❌ Calculates on stale layout
sidebarTabsCtl.activate('tree');
scrollToPath(path);  // getBoundingClientRect returns stale values

// ✅ Wait for next frame
sidebarTabsCtl.activate('tree');
requestAnimationFrame(() => {
  scrollToPath(path);
});

Rule: Code that reads getBoundingClientRect / scroll / highlight after toggling display/class must use requestAnimationFrame to wait for the next frame.

Rule 5: Autonomous Mode ≠ Skipping User Perspective

When the user says "don't interrupt me with decision cards in autonomous mode," they mean don't send approval prompts — not "skip verification." Every 2-3 versions, run at least one "pretend I'm the user" drill. The prettier the CHANGELOG user-story section, the more critical to verify in browser — otherwise it's documentation-driven self-hypnosis.

V. Quick Start & v1.12 Roadmap

Quick Start (3 lines)

git clone https://github.com/louisecxqiu-glitch/html-doc-center.git
cd html-doc-center
pip3 install aiohttp && python3 server.py
# → open http://localhost:9901

macOS auto-start on boot:

cp launchd.plist.example ~/Library/LaunchAgents/com.louis.html-doc-center.plist
launchctl load ~/Library/LaunchAgents/com.louis.html-doc-center.plist

v1.12 Roadmap (in progress)

Full-text search (FTS5 + debounce)
Block-level HTML editing (drag-reorder, batch styling)
Multi-window sync (state broadcast when same file is open in multiple tabs)
Mobile touch reading mode (drawer-style sidebar)

See docs/superpowers/plans/2026-05-14-v1.12-roadmap.md.

VI. Repo & Connect

⭐ GitHub: https://github.com/louisecxqiu-glitch/html-doc-center
🐛 Issues / 💡 Discussions / 🔧 PRs all welcome — see CONTRIBUTING.md

Connect:

🐦 X / Twitter: @louisqiu285052 — English build-in-public
📝 CSDN: blog.csdn.net/qcx23 — Chinese deep-dives
🔶 WeChat (Chinese): 一深思AI — companion long-form articles on AI Agent practice

If DocCenter helps you, a star is the best support for open source. Issues and PRs welcome — let's grow this slowly.

Built with ❤️ by Louis Qiu · MIT Licensed · 2026

推荐订阅源

DEV Community

I. The Problem: AI-Era Document Sprawl

II. Tech Stack: Why a Single Python File + Vanilla JS

2.1 aiohttp over FastAPI

2.2 Vanilla JS over React

2.3 iframe over SPA Routing

III. Core Architecture: Three Tiers

3.1 Backend (server.py): Path Safety is the Only Hard Rule

3.2 Injection Layer (saver-runtime.js): Three Guardrails for Dirty Detection

3.3 Frontend (app.js): The Single UX Decision Point

IV. 5 Hard-Won Anti-Bug Rules

Rule 1: Real Browser Drill — `curl 200` ≠ User-Perspective Working

Rule 2: Guard Expressions Need Explicit Verification

Rule 3: Grep Inline Style Residue Before Changing CSS .active / display

Rule 4: DOM-Dependent Actions After Toggle Need rAF

Rule 5: Autonomous Mode ≠ Skipping User Perspective

V. Quick Start & v1.12 Roadmap

Quick Start (3 lines)

v1.12 Roadmap (in progress)

VI. Repo & Connect

推荐订阅源

DEV Community

I. The Problem: AI-Era Document Sprawl

II. Tech Stack: Why a Single Python File + Vanilla JS

2.1 aiohttp over FastAPI

2.2 Vanilla JS over React

2.3 iframe over SPA Routing

III. Core Architecture: Three Tiers

3.1 Backend (server.py): Path Safety is the Only Hard Rule

3.2 Injection Layer (saver-runtime.js): Three Guardrails for Dirty Detection

3.3 Frontend (app.js): The Single UX Decision Point

IV. 5 Hard-Won Anti-Bug Rules

Rule 1: Real Browser Drill — curl 200 ≠ User-Perspective Working

Rule 2: Guard Expressions Need Explicit Verification

Rule 3: Grep Inline Style Residue Before Changing CSS .active / display

Rule 4: DOM-Dependent Actions After Toggle Need rAF

Rule 5: Autonomous Mode ≠ Skipping User Perspective

V. Quick Start & v1.12 Roadmap

Quick Start (3 lines)

v1.12 Roadmap (in progress)

VI. Repo & Connect

Rule 1: Real Browser Drill — `curl 200` ≠ User-Perspective Working