QHTML

QHTML is a folder-native render contract for reducing repeated full HTML scans and targeting exact UI parts by folder address.

It does not treat index.html as source truth. The source is a managed folder lane:

opaque folder rune lane
  + optional original/source digest
  + media slot placement
  + render policy
  + witness receipts
  -> disposable HTML projection

HTML is output cache. The folder is the address system. QHTML exists so UI artifacts can be edited, audited, regenerated, and handed off without trusting an active editor tab or a single generated HTML file.

The core value is practical:

• reduce repeated full HTML scans by checking lane/source digests first
• target exact UI cells, media slots, rollback points, and future patch proposals by folder path
• keep generated HTML disposable while preserving a stable source lane

Install

go install github.com/companyjupiter/qhtml/cmd/qhtml@latest

Local development:

go test ./...
go run ./cmd/qhtml status

Commands

qhtml status
qhtml render-folder --lane-root <lane_root> --out <rendered.html> [--title <title>] [--write]
qhtml resolve-media --lane-root <lane_root> [--slot-root 04] [--out-dir <media_export_dir>] [--max-bytes <bytes>] [--write]
qhtml chunk-media --lane-root <lane_root> [--slot-root 04] [--chunk-bytes <bytes>] [--write]
qhtml adapter-conformance --lane-root <lane_root> [--write]
qhtml refresh --lane-root <lane_root> [--source <original.html>] [--write]
qhtml witness --lane-root <lane_root> --export <rendered.html> [--source <original.html>] [--write]
qhtml visual-witness --export <rendered.html> [--console-report <console.json>] [--screenshot <screenshot.png>] [--viewport desktop|mobile] [--write]
qhtml layout-witness --export <rendered.html> --report <layout-report.json> [--write]
qhtml target --lane-root <lane_root> --path <lane_relative_target> [--kind cell|media|style|event] [--write]
qhtml tombstone --lane-root <lane_root> --path <lane_relative_target> [--reason <why>] [--write]
qhtml rollback --lane-root <lane_root> --path <lane_relative_target> --to-digest <digest> [--source-receipt <receipt>] [--write]
qhtml import-proposal --lane-root <lane_root> --export <rendered.html> [--path <lane_relative_target>] [--source-receipt <receipt>] [--write]
qhtml runner-proof --report <runner_report.json> --runner-id <id> --runner-version <version> --signature <signature> [--write]
qhtml opfs-proof --report <opfs_report.json> --runner-id <id> --runner-version <version> [--write]
qhtml verify-runner-proof --proof <runner_proof_receipt> --public-key <ed25519_public_key> [--write]
qhtml seal --witness <witness_receipt> [--import-proposal <proposal_receipt>] [--visual-witness <visual_receipt>] [--layout-witness <layout_receipt>] [--runner-proof <proof_receipt>] [--runner-verification <verification_receipt>] [--opfs-proof <opfs_receipt>] [--write]

refresh computes a stable digest over the lane folder and optional source file, compares it with the previous state, and reports:

• lane_changed
• source_changed
• needs_render_refresh
• state_path
• receipt_path when --write is used

State is stored under:

.qhtml/managed/<lane-key>/state.json
.qhtml/managed/<lane-key>/receipts/*.qhtml_refresh.json
.qhtml/renders/<render-key>/*.qhtml_render_folder.json
.qhtml/media/<media-key>/*.qhtml_media.json
.qhtml/chunk_media/<chunk-key>/*.qhtml_chunk_media.json
.qhtml/adapter_conformance/<matrix-key>/*.qhtml_adapter_conformance.json
.qhtml/witnesses/<render-key>/*.qhtml_witness.json
.qhtml/visual_witnesses/<visual-key>/*.qhtml_visual_witness.json
.qhtml/layout_witnesses/<layout-key>/*.qhtml_layout_witness.json
.qhtml/targets/<target-key>/targets/*.qhtml_target.json
.qhtml/targets/<target-key>/tombstones/*.qhtml_tombstone.json
.qhtml/targets/<target-key>/rollbacks/*.qhtml_rollback.json
.qhtml/import_proposals/<proposal-key>/*.qhtml_import_proposal.json
.qhtml/runner_proofs/<proof-key>/*.qhtml_runner_proof.json
.qhtml/runner_verifications/<verification-key>/*.qhtml_runner_proof_verification.json
.qhtml/opfs_proofs/<proof-key>/*.qhtml_opfs_proof.json
.qhtml/seals/<seal-key>/*.qhtml_seal.json

The manager ignores its own runtime artifacts while hashing a lane:

• .qhtml/
• .git/
• dist/
• the configured --state-root if it is inside the lane

This prevents the classic self-contamination failure where writing a state file causes every later refresh to report a false change.

Why It Is Separate

QHTML started inside NeuronFS, but it is a product boundary of its own:

• folder-native UI source management
• deterministic change detection
• disposable HTML export philosophy
• future browser/Vorq witness layer
• cross-platform adapter surface

NeuronFS can embed QHTML, but QHTML must be usable without NeuronFS.

Current Level

Implemented:

• Go-native lane/source digest manager
• standalone render-folder HTML projection renderer
• standalone media slot resolver with digest and size-budget receipts
• streaming chunked hashing receipts for large media assets
• adapter conformance matrix receipts for portable, Windows, POSIX, and browser OPFS path assumptions
• HTML fullscan reduction through digest-first refresh
• seed precision targeting surface through stable folder lane addresses
• JSON status and refresh CLI
• receipt writing for refresh events
• deterministic directory hashing
• exclusive refresh lock
• symlink target hashing without following links
• render export witness receipts binding lane/source/export digests
• browser visual artifact witness receipts for nonblank export, zero console errors, and optional screenshot digest
• browser layout witness receipts for viewport nonblank, console, and overflow evidence
• target/tombstone/rollback receipts for lane-relative cell/media/style/event addresses
• import proposal receipts that turn export changes into lane patch proposals without overwriting source folders
• Vorq-compatible seal receipts that bind witness/import/layout/visual receipts for promotion
• signed browser runner proof receipts that bind runner identity, version, report digest, and signature claim
• Ed25519 public-key verification receipts for runner proof signatures
• browser OPFS runner proof receipts for quota, file-handle, path, and write/read/delete evidence
• tests for initial state, no-change state, source change, and lane change

Not complete:

• official browser runner package

Blind Spots Already Simulated

• State directory inside the lane: fixed by excluding .qhtml and --state-root from lane digest.
• File deletion: covered by digest tests.
• Atomic state writes: state and receipt JSON are written via temp file then rename.
• Concurrent refresh: guarded by an exclusive lock file.
• Symlink drift: symlinks are hashed by link target path and are not followed outside the lane.
• Watcher loss: correctness does not depend on a long-running watcher; polling refresh is the source of truth.
• Blank export: visual-witness rejects HTML without visible text.
• Console errors: visual-witness rejects console reports containing error entries.
• Empty screenshot: visual-witness rejects zero-byte screenshot artifacts.
• Layout report drift: layout-witness rejects blank viewports, console errors, overflow, and invalid viewport dimensions.
• Target escape: target rejects lane-relative paths that escape the lane root.
• Destructive targeting: tombstone and rollback write receipts/proposals first and do not mutate the lane without an external promotion gate.
• Import mutation: import-proposal writes a proposal receipt and leaves the lane target digest unchanged.
• Import escape: import-proposal rejects target paths that escape the lane root.
• Seal integrity: seal rejects missing render witness receipts and wrong receipt schemas.
• Runner proof integrity: runner-proof rejects missing runner identity/version, empty reports, and short signatures.
• Runner proof verification: verify-runner-proof rejects bad public keys, wrong proof schemas, and invalid signatures.
• Render projection safety: render-folder escapes lane file content, writes receipts, and rejects exports inside the lane unless they are under dist/.
• Media slot safety: resolve-media rejects slot-root escapes, rejects export copies inside the lane unless under dist/, rejects oversized assets, rejects media symlinks, and ignores non-media files.
• Large media safety: chunk-media uses streaming chunk reads, rejects too-small chunks, rejects slot-root escapes, and records per-chunk digests.
• Adapter safety: adapter-conformance detects nonportable path characters, case-insensitive collisions, Windows reserved segments, and records POSIX/browser OPFS portability assumptions.
• OPFS proof safety: opfs-proof rejects unavailable OPFS, nonpositive quota, missing file handles, failed write/read/delete, failed path roundtrip, non-relative paths, and console errors.

Remaining blind spots:

• The browser runner package is still external; QHTML validates runner reports but does not ship a runner binary.

Potential Assessment

QHTML has high product potential if it stays focused on one claim:

A UI artifact should have a folder-addressable source of truth, not only a generated HTML file.

Strongest markets:

• AI-generated UI source control
• precision UI targeting without full HTML rescans
• design handoff with receipts
• visual QA and browser witness automation
• NeuronFS or agent-runtime UI artifact lanes
• cross-platform local-first site/app builders

Current potential score from qhtml status: 82/100.

That is not a maturity score. It means the core product thesis is strong, while the implementation is still a seed. The next milestones are:

1. Add official browser runner package.

Product Rule

QHTML never promotes generated HTML to source truth.

If a folder or original source changes, qhtml refresh --write must make the change visible before render, witness, or promotion.