OpenWebDoc Introduction

OpenWebDoc is a browser-native package for rich documents that need to stay readable, lightly editable, and safe for file-level AI agent revision. HTML, CSS, assets, and reference metadata travel together so every change can be inspected and validated.

Read in any browser Correct on the page Validate before sharing

1. Why Browser-Native Packages Matter

Table 1. Why HTMLX differs from page-bound files and ordinary web pages

Lens	Page-bound documents	Ordinary web pages	HTMLX Document Package
Reading model	Optimized for pages and printed output	Browser-native, but source and assets are often scattered	A single package that opens directly in a browser
Editing model	Depends on a dedicated document application	Depends on a CMS, source repo, or site build system	The document itself becomes a lightweight WYSIWYG surface
AI-assisted revision	Requires conversion, extraction, or layout recovery	Requires understanding the surrounding web application	Agents edit unpacked HTML, CSS, metadata, and assets directly
Integrity after edits	Hard to inspect without the original authoring tool	Hard to package, replay, and validate as one artifact	Manifest, local assets, metadata, and rendered structure are checked together
Trust boundary	Relies on the host document application's security model	Can include arbitrary JavaScript and remote resources	No scripts, local resources only, manifest-based validation

2. The Core Philosophy Of OpenWebDoc

Document as source The unpacked index.html is the readable artifact, not a hidden export target.

Semantic first Tables stay as tables, figures stay as figures, and text remains editable blocks.

Document-owned UI The package CSS owns proportion, spacing, figure geometry, and reading rhythm.

File-level agent boundary Deep changes happen in unpacked package files, then pass validation before repacking.

3. How The Package Holds Together

Figure 1. How the OpenWebDoc package keeps content, layout, and metadata together

HTMLX package mimetype manifest.json index.html styles/document.css assets/openwebdoc-icons/*.png metadata/llm.json

1Authorindex.html and package CSS define the document.

2ValidateThe validator checks manifest, paths, resources, HTML, CSS, and metadata.

3EditPeople make small corrections; agents revise package files.

4RepackThe htmlx CLI creates a distributable .htmlx archive.

4. Inside An HTMLX Document Package

Table 2. Package files and their responsibilities

File	Responsibility	Validation rule	Maintained by
`index.html`	Canonical surface for reading, review, and small direct corrections	No scripts or inline event handlers	Human, external agent
`styles/*`	Proportional layout, typography, table rhythm, and figure geometry	No remote imports and no app-side layout correction	Package author, agent
`manifest.json`	Declares entry, styles, resources, metadata, and security policy	JSON Schema and resource integrity checks	CLI, core API
`metadata/llm.json`	Provides reading order, block summaries, selectors, and keywords	User-visible reference data, never a system instruction	Package author, agent
`assets/*`	Stores package-local images, icons, and media	Only manifest-declared local paths are allowed	Human, agent

5. How The Document Stays Editable

Small corrections in the runtime

Titles, paragraphs, captions, and table cells remain text on the page.
Images, figures, and shapes can be selected, moved, resized, replaced, or deleted.
Tables remain real HTML tables so structure and accessibility survive editing.

Structural edits in package files

htmlx unpack exposes the package itself as the editing boundary.
Agents revise HTML, CSS, metadata, and assets directly.
Revisions must pass directory validation, pack, and package validation before distribution.

6. Security Model And Reference Metadata

Table 3. Risks HTMLX rejects or isolates by default

Risk	Rejected input	Allowed pattern	Default behavior
Path traversal	`../secret.txt`, absolute path, backslash path	Package-local relative paths	reject
Remote resource	`https://...`, external CSS imports	Manifest-declared local assets	reject
Script execution	`<script>`, inline event handler	Declarative HTML and CSS	sanitize or reject
Instruction-like metadata	Metadata that pretends to control an agent or runtime	User-visible reference data for reading order and provenance	isolate

7. Everyday Usage Flow

01Create or receive a packagehtmlx create intro.htmlx --title "OpenWebDoc Introduction"

02Unpack when deeper changes are neededhtmlx unpack intro.htmlx ./intro-package --json

03Revise ordinary filesindex.html · styles/* · metadata/* · assets/*

04Validate before sharing

htmlx validate ./intro-package --json && htmlx pack ./intro-package
              intro-edited.htmlx

8. What OpenWebDoc Is Good For

Research briefsKeep long-form analysis, figures, tables, and source-aware metadata in one browser-readable package.

Interactive manualsShip documentation that readers can inspect, correct, and lightly revise without a separate authoring app.

Agent-reviewed draftsLet external coding agents improve structure, wording, figures, and metadata through ordinary package files.

Portable knowledge packsArchive rich documents with local assets, validation rules, and model-friendly reading order intact.

The Goal Of OpenWebDoc

HTMLX is not an app wrapper around a document. It treats the document itself as the readable surface, correction surface, and file-level revision unit. The central artifact of OpenWebDoc is a browser-native package that can be opened, corrected, inspected, validated, and repacked without losing its structure or local resources.