# WEB Document Format (`.webd`)

| | |
| --- | --- |
| **Version** | `0.1.0` |
| **Extension** | `.webd` |
| **Container** | ZIP archive |
| **MIME type (proposed)** | `application/webd+zip` |
| **Audience** | Tools, generators, and LLMs that **create** valid `.webd` packages |

A `.webd` file is a self-contained, fixed-layout document package: HTML + CSS + embedded assets, with no JavaScript and no external resource dependencies. This document defines what to put in the package so that it is valid.

---

## 1. Create a package (recipe)

1. Build a directory with the layout in [§2](#2-package-layout).
2. Choose a document pattern ([§3](#3-document-patterns)):
   - **Single-page:** all content in `index.html`; omit `/pages/`.
   - **Multi-page:** one HTML file per page under `/pages/` (zero-padded names recommended); `index.html` is only a shell or local redirect.
3. Add root `styles.css` and package-local assets as needed ([§2.1](#21-embedded-assets-recommended-layout)). Prefer a single optional `assets/` folder.
4. Write `metadata.json` with every required field ([§6](#6-metadatajson)). Set `"format": "webd"` and `"version": "0.1.0"`.
5. Optionally add `manifest.json` (TOC), `/annotations/annotations.json`, or filled form values in the HTML.
6. Ensure all HTML, CSS, and JSON follow the content rules in this document.
7. ZIP the directory **contents** (not the parent folder). Entry names must be safe relative paths ([§2](#2-package-layout)). Name the file `*.webd`.
8. Optionally encrypt the ZIP with AES-256 ([§10](#10-optional-passcode-encryption)).

---

## 2. Package layout

### ZIP rules

- The file is a standard ZIP archive renamed/extended as `.webd`.
- Entry paths are relative to the package root, using `/` separators.
- **Not allowed** in entry names: empty names, `..` segments, absolute paths (`/…`, `C:…`).

### Tree

```text
document.webd  (ZIP)
|
+-- index.html                 required
+-- styles.css                 required
+-- metadata.json              required
+-- manifest.json              optional (TOC / labels)
+-- pages/                     optional (one .html per published page)
|     0001.html
|     0002.html
+-- assets/                    optional (recommended for all embedded media)
|     images/
|     fonts/
|     video/
|     audio/
|     …
+-- annotations/               optional
      annotations.json
```

| Path | Required | Role |
| --- | --- | --- |
| `index.html` | Yes | Full document, or thin shell / local redirect for multi-page |
| `styles.css` | Yes | Shared package stylesheet |
| `metadata.json` | Yes | Document metadata |
| `manifest.json` | No | Table of contents / navigation labels only |
| `pages/*.html` | No | Fixed published pages (long documents) |
| `assets/` | No | **Recommended** home for images, fonts, video, audio, and other embedded files ([§2.1](#21-embedded-assets-recommended-layout)) |
| `annotations/annotations.json` | No | Highlights, comments, drawings, bookmarks |

### 2.1 Embedded assets (recommended layout)

All package-local resources (images, fonts, video, audio, icons, downloadable attachments, and similar binary or static files) **should** live under a single optional root folder named `assets/`.

| Rule | Detail |
| --- | --- |
| **Not required** | There is **no** mandatory folder name for assets. Packages without `assets/`, or with other package-relative locations, remain valid. |
| **Recommended** | Put every embedded resource under `assets/` so tools, validators, and humans can find media in one place. |
| **Subfolders** | Optional organization inside `assets/` is encouraged when helpful, e.g. `assets/images/`, `assets/fonts/`, `assets/video/`, `assets/audio/`, `assets/attachments/`. Flat layouts (`assets/logo.png`) are also fine. |
| **References** | HTML `src` / `href` and CSS `url()` must stay **package-relative** (e.g. from `pages/0001.html`: `../assets/images/photo.png`). |
| **Legacy / alternate layouts** | Root-level folders such as `images/`, `fonts/`, or `attachments/` are still allowed for compatibility with existing packages. Prefer `assets/` for new packages. |

**Examples (all valid):**

```text
# Recommended
assets/logo.png
assets/fonts/roboto.woff2
assets/video/overview.mp4
assets/audio/narration.m4a

# Also valid (not preferred for new packages)
images/logo.png
fonts/roboto.woff2
media/clip.webm
```

### Reserved paths (do not use in 0.1.0)

`/signatures`, `/encrypted`, `/scripts`, `/versions`

### Page order

- If `pages/` exists, **alphabetical filename order** is the only page sequence.
- Prefer zero-padded names: `0001.html`, `0002.html`, …
- Do **not** store `page_count`, `page_order`, or equivalent in JSON.

---

## 3. Document patterns

### Single-page

Put the full document in `index.html`. Omit `pages/`.

### Multi-page

- One fixed published page per file under `pages/`.
- `index.html` must **not** duplicate page content. Use a shell or a **local** redirect only:

```html
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <meta http-equiv="refresh" content="0; url=pages/0001.html">
</head>
<body>Redirecting…</body>
</html>
```

- `meta http-equiv="refresh"` targets must be package-relative (never `http:` / `https:`).
- From files under `pages/`, link the shared stylesheet as `../styles.css`.
- Encode fixed page size in CSS and/or `metadata.json` (`page_width_px` / `page_height_px` / `page_size`).

### Links inside the package

```html
<a href="pages/0012.html#section-2">Go to Section 2</a>
```

Target = package path `pages/0012.html` plus optional fragment. Cross-page links must use package-relative paths (or allowed navigational schemes in [§4](#4-html)).

---

## 4. HTML

Applies to `index.html`, every `pages/*.html`, and any other `.html` entry.

### Allowed

- HTML5 structure and content
- Forms: `input`, `textarea`, `select` / `option` / `optgroup`, labels, fieldsets
- Tables, lists, headings, semantic markup
- Images, video, and audio with **package-relative** `src` (prefer paths under `assets/` — [§2.1](#21-embedded-assets-recommended-layout))
- Package-local stylesheets (`<link rel="stylesheet" href="…">`)
- Inline styles (CSS inside them still follows [§5](#5-css))
- In-page anchors (`id`)
- Package-relative cross-page links
- Navigational `<a href>` schemes: package-relative paths, `webd:`, `https:`, `http:`, `mailto:`, `tel:`, `sms:`

### Not allowed

- JavaScript: `<script>`, `javascript:` URLs, event handlers (`onclick`, `onload`, …)
- `<iframe>`, `<object>`, `<embed>`, `<base>`, `<template>`, `<noscript>`
- External **resources** (`src`, fonts, images, stylesheets loaded by URL)
- Schemes `file:`, `ftp:`, `blob:`, and active `data:` (e.g. `data:text/html`) anywhere
- `formaction` attributes
- Form `action` pointing at external URLs (filled data is stored in the package HTML, not submitted remotely)
- External `meta http-equiv="refresh"` targets
- Video/audio sourced outside the package

### Resources vs navigation

| Kind | Where | Rule |
| --- | --- | --- |
| **Resource** | `src`, CSS `url()`, `@import`, fonts, images, video, audio | Package-relative paths only (prefer under `assets/`) |
| **Navigation** | `<a href>` | Relative, `webd:`, `https:`, `http:`, `mailto:`, `tel:`, `sms:` |

### Example page (`pages/0001.html`)

```html
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <link rel="stylesheet" href="../styles.css">
</head>
<body class="webd-page">
  <section id="employee-form">
    <h1>Employee Form</h1>
    <label>Name:</label>
    <input type="text" name="employee_name" value="">
    <label>Department:</label>
    <input type="text" name="department" value="">
  </section>
</body>
</html>
```

### Filled form state (when saving user input into the package)

| Control | Store filled state as |
| --- | --- |
| Text-like `input` | `value` attribute |
| `textarea` | Element text content |
| `checkbox` / `radio` | Presence/absence of `checked` |
| `select` | `selected` on the chosen `option` |

Update only the affected page file. Do not write viewer chrome, blob URLs, or runtime paths into the HTML.

### Special `webd:` action links

| URI | Meaning in the document |
| --- | --- |
| `webd://accept-terms` | Accept terms when `metadata.has_terms` is true |
| `webd://close-document` | Request to close the document |

```html
<a href="webd://accept-terms">I accept the terms</a>
```

---

## 5. CSS

Applies to root `styles.css`, any other `.css` files, and every inline `<style>` block.

### Allowed

- Package-local CSS only
- Shared `styles.css` used by `index.html` and `pages/*`
- From `pages/`: `url` / `@font-face` paths relative to that file (shared sheet at `../styles.css`; fonts preferably `../assets/fonts/…`)
- Fixed page layout (e.g. width / min-height matching metadata)

### Not allowed

- Remote `@import` (`http:`, `https:`, `//`, or non-package targets)
- External or non-package `url()` (`http:`, `https:`, `//`, `file:`, `ftp:`, `javascript:`, active `data:`)
- Legacy active CSS: `behavior`, `-moz-binding`, `expression()`

Package-relative `url(...)` and `#fragment` references are fine. Static image `data:` URLs are only acceptable if they are not active document types (not `data:text/html`).

### Example (`styles.css`)

```css
@font-face {
  font-family: "Roboto";
  src: url("assets/fonts/roboto.woff2") format("woff2");
}

.webd-page {
  width: 210mm;
  min-height: 297mm;
  font-family: "Roboto", sans-serif;
}
```

---

## 6. `metadata.json`

Must be valid JSON. Required fields:

```json
{
  "format": "webd",
  "version": "0.1.0",
  "title": "Document Title",
  "author": "Author Name",
  "created_on": "2026-04-05",
  "modified_on": "2026-04-05",
  "created_with": "Your Tool Name",
  "has_forms": false
}
```

| Field | Type | Rules |
| --- | --- | --- |
| `format` | string | Must be `"webd"` |
| `version` | string | Format version; use `"0.1.0"` for this specification |
| `title` | string | Document title |
| `author` | string | Author |
| `created_on` | string | `YYYY-MM-DD` |
| `modified_on` | string | `YYYY-MM-DD` |
| `created_with` | string | Creating product/tool id |
| `has_forms` | boolean | `true` if the package contains fillable form controls |

### Optional fields

```json
{
  "description": "Document description",
  "company": "Company Name",
  "document_id": "DOC-001",
  "category": "report",
  "tags": ["invoice", "finance", "2026"],
  "data_classification": "Internal",
  "page_size": "A4",
  "page_width_px": 794,
  "page_height_px": 1123,
  "orientation": "portrait",
  "language": "en",
  "has_annotations": false,
  "has_comments": false,
  "supports_read_aloud": true,
  "searchable": true,
  "passcode_removable": false,
  "passcode_modifiable": false,
  "has_terms": false
}
```

| Field | Notes |
| --- | --- |
| `page_width_px` / `page_height_px` | CSS pixels at 96 DPI. Common: A4 = 794×1123, Letter = 816×1056 |
| `page_size` / `orientation` | Published layout labels (e.g. `A4`, `portrait`) |
| `category` | Free-form string (`invoice`, `contract`, `form`, `report`, …) |
| `tags` | Array of strings |
| `data_classification` | Free-form sensitivity label (e.g. `Public`, `Internal`, `Confidential`) |
| `has_annotations` / `has_comments` | Reflect presence of annotation / comment data |
| `supports_read_aloud` / `searchable` | Hints about text content |
| `passcode_removable` / `passcode_modifiable` | Policy if the ZIP is encrypted; default `false` |
| `has_terms` | Terms gate present; pair with `webd://accept-terms` in content |

Do not include `page_count` or `page_order`.

---

## 7. `manifest.json` (optional)

Navigation metadata only. Does **not** define page order.

```json
{
  "toc": [
    {
      "title": "Chapter 1",
      "path": "pages/0005.html#chapter-1",
      "children": [
        {
          "title": "Section 1.1",
          "path": "pages/0006.html#section-1-1"
        }
      ]
    }
  ]
}
```

- `path` values: package-relative page path, optional `#fragment`.
- Omit the file entirely if there is no TOC.

---

## 8. Annotations (optional)

If present, use exactly:

```text
annotations/annotations.json
```

Annotations live only in that file — never rewrite page HTML to bake them in.

### Types (`type` field)

| `type` | Purpose |
| --- | --- |
| `highlight` | Text highlight |
| `underline` | Text underline |
| `strike` | Strikethrough / optional blackout (`style.redacted`) |
| `comment` | Text-anchored or coordinate pin + thread |
| `draw` | Line or shape drawing |
| `bookmark` | Bookmark |

### Root shape

```json
{
  "version": "1.0",
  "items": [ /* annotation objects */ ]
}
```

### Common item fields

| Field | Rules |
| --- | --- |
| `id` | Unique string in the file (prefixes like `ann-`, `com-`, `bm-` recommended) |
| `type` | One of the types above |
| `author` | String |
| `created_on` | ISO 8601 with milliseconds, e.g. `2026-04-05T10:30:00.000Z` |
| `page_path` | Package-relative HTML path, e.g. `pages/0003.html` |

### Text anchor (`anchor`)

Used by `highlight`, `underline`, `strike`, and text-anchored `comment`:

| Field | Rules |
| --- | --- |
| `selector` | Single CSS selector (no comma lists); max 500 chars; characters limited to letters, digits, whitespace, and `# . > + ~ : = " ' [ ] * \| ( ) ^ $ -` |
| `text_quote` | Exact selected text (fallback) |
| `start_offset` / `end_offset` | Non-negative offsets into the element’s plain text (text nodes in order) |

Meaning: resolve `selector` on that page, then apply character offsets; if that fails, match `text_quote` in the element text.

### Style (`style`)

| Field | Rules |
| --- | --- |
| `color` | Hex only: `#RGB`, `#RGBA`, `#RRGGBB`, `#RRGGBBAA` — not named colors or `rgb()` |
| `underline_style` | `solid` \| `dashed` \| `wavy` \| `dotted` \| `double` |
| `redacted` | Boolean (strike blackout) |
| `x`, `y`, `width`, `height`, `thickness` | Finite numbers (px at 100% zoom) |
| `shape` | `rect` \| `ellipse` |
| `points` | Space-separated `x,y` pairs; only `0-9 . , -` and spaces; max 200 chars |

### Bookmark fields

| Field | Rules |
| --- | --- |
| `bookmark_title` | String |
| `bookmark_color` | Same hex rules as `style.color` |
| `bookmark_page_index` | 0-based page index |

### Comment threads

`comments`: array of `{ id, author, created_on, text, replies }` (`replies` same shape).

### Minimal examples

```json
{
  "version": "1.0",
  "items": [
    {
      "id": "ann-001",
      "type": "highlight",
      "author": "User A",
      "created_on": "2026-04-05T10:30:00.000Z",
      "page_path": "pages/0003.html",
      "anchor": {
        "selector": "p:nth-of-type(3)",
        "text_quote": "sample selected text",
        "start_offset": 12,
        "end_offset": 32
      },
      "style": { "color": "#ffe066" }
    },
    {
      "id": "ann-002",
      "type": "draw",
      "author": "User A",
      "created_on": "2026-06-08T09:50:00.000Z",
      "page_path": "pages/0003.html",
      "style": {
        "color": "#2459e6",
        "x": 50,
        "y": 80,
        "width": 200,
        "height": 100,
        "thickness": 2,
        "shape": "rect"
      }
    },
    {
      "id": "bm-001",
      "type": "bookmark",
      "author": "User A",
      "created_on": "2026-06-08T09:42:36.633Z",
      "page_path": "pages/0003.html",
      "bookmark_title": "Page 3 Bookmark",
      "bookmark_color": "#ff6b6b",
      "bookmark_page_index": 2
    }
  ]
}
```

Omit `/annotations` entirely if there are no annotations.

---

## 9. Authoring recommendations

Not separate required files — improve quality of the package:

- Prefer real text and semantic HTML (headings, paragraphs, lists, tables, labels).
- Do not put essential text only inside images.
- Associate form controls with `<label>`.
- Use a stable reading order on each page.
- **Place all embedded resources under `assets/`** (optional folder; not required for validity). Use subfolders by type when useful (`assets/images/`, `assets/fonts/`, `assets/video/`, `assets/audio/`). See [§2.1](#21-embedded-assets-recommended-layout).
- Prefer stable, URL-safe asset filenames (avoid spaces when practical); package-relative paths with spaces remain allowed.
- No separate search-index file is defined in 0.1.0; searchable text is the HTML itself.
- Embedded video/audio is allowed when package-local; neither is required in 0.1.0.

---

## 10. Optional passcode encryption

To protect the package:

1. Encrypt the ZIP with **AES-256** (WinZip AES-256).
2. Encrypt **every** entry.
3. Optionally set `passcode_removable` / `passcode_modifiable` in `metadata.json`.

Consumer UX (prompts, retries) is out of scope for this format document.

---

## 11. Versioning

| `metadata.version` | Meaning |
| --- | --- |
| `0.1.0` | This specification: package layout, HTML/CSS rules, metadata/manifest/annotations, optional AES-256 ZIP encryption, `webd:` action URIs |

Set `version` to the format version the package conforms to.