SurfDoc Format Specification

1. Design Principles

1. Backward-compatible. Every standard Markdown document is a valid SurfDoc. SurfDoc adds typed block directives; it never breaks existing files.
2. Three-layer architecture. Every document has a content layer (prose), a data layer (structured, typed, queryable), and a presentation layer (layout, styling). Each layer is accessible independently.
3. Graceful degradation. A SurfDoc opened in a plain text editor, GitHub, or any markdown renderer is fully readable. Blocks degrade to fenced content with visible labels. No information is lost.
4. AI-native. An AI agent can read, write, and modify a SurfDoc without special tooling. The format is text-based, the syntax is simple, and the block types are semantic.
5. File-based and portable. A SurfDoc is a .surf file. It lives on disk, in git, in any filesystem. It is not a database row, not a cloud-only format, not proprietary.
6. Schema-validated. Block types have defined attributes. A renderer or linter can validate that a ::data block has a format, a ::turn block has a participant, etc.
7. Renderable at multiple fidelities. Plain text → styled markdown → rich interactive → print/PDF. Same source, four fidelity levels.

2. File Format

A .surf file signals to tooling that it should be rendered with SurfDoc block support. Renaming .surf to .md produces a fully readable markdown file (graceful degradation).

3. Front Matter

SurfDoc uses YAML front matter delimited by ---. Front matter is optional but recommended.

---
title: "Document Title"
type: doc
version: 1
created: 2026-02-10
updated: 2026-02-10
author: "Brady Davis"
status: draft
scope: workspace
tags: [architecture, surfdoc]
---

Required Fields by Document Type

4. Block Syntax

SurfDoc blocks use the :: directive syntax. Container blocks open with ::blocktype[attrs] and close with ::. Leaf directives fit on a single line.

Container Block (multi-line)

::blocktype[attr1=value attr2="quoted value"]
Content inside the block.
Multiple lines allowed.
::

Leaf Directive (single-line)

::blocktype[attr1=value]{Inline content}

Nesting

Blocks can nest. Inner blocks use additional colons. Maximum nesting depth: 4 levels.

::columns[count=2]

:::column
Left column content.
:::

:::column
Right column content.
:::

::

Attribute Syntax

5. Core Blocks

The foundation blocks for structured content: callouts, decisions, summaries, figures, quotes, and code.

::callout[type=warning]
This deployment will cause 5 minutes of downtime.
::

> **Warning:** This deployment will cause 5 minutes of downtime.

::decision[status=accepted date=2026-02-10]
**GTK4 native** — 5MB binary, native look and feel.
::

> **Decision (accepted, 2026-02-10):** GTK4 native — 5MB binary, native look and feel.

::summary
This document covers the GTK vs Electron decision for desktop.
We chose GTK4 for binary size and native feel.
::

*This document covers the GTK vs Electron decision for desktop. We chose GTK4 for binary size and native feel.*

::figure[src=brand/diagrams/ecosystem.png caption="Product Ecosystem" alt="Diagram showing product relationships"]
::

![Diagram showing product relationships](brand/diagrams/ecosystem.png)
*Product Ecosystem*

::quote[by="Peter Thiel" cite="Zero to One"]
Every moment in business happens only once.
::

> Every moment in business happens only once.
>
> — Peter Thiel, *Zero to One*

::code[lang=rust file=src/sync/mod.rs]
pub fn run_sync(opts: &SyncOpts) -> Result<SyncReport> {
    let repo_root = find_repo_root()?;
    let config = config::load_config(&repo_root)?;
}
::

pub fn run_sync(opts: &SyncOpts) -> Result<SyncReport> {
    let repo_root = find_repo_root()?;
    let config = config::load_config(&repo_root)?;
}

```rust
pub fn run_sync(opts: &SyncOpts) -> Result<SyncReport> {
    let repo_root = find_repo_root()?;
    let config = config::load_config(&repo_root)?;
}
```

6. Data Blocks

Blocks that embed structured, queryable data inside documents.

::data[id=competitors format=table sortable]
| Company | Funding | Users  | Threat |
|---------|---------|--------|--------|
| Linear  | $52M    | 10K+   | High   |
| Jira    | Public  | 250K+  | Medium |
::

| Company | Funding | Users  | Threat |
|---------|---------|--------|--------|
| Linear  | $52M    | 10K+   | High   |
| Jira    | Public  | 250K+  | Medium |

::metric[label="MRR" value="$2,400" trend=up]

**MRR:** $2,400

::timeline
- 2026-01: Beta launch
- 2026-02: First paying customers
- 2026-03: Angel round
::

- 2026-01: Beta launch
- 2026-02: First paying customers
- 2026-03: Angel round

::chart[type=bar title="Revenue by Quarter"]
| Quarter | Revenue |
|---------|---------|
| Q1 2026 | $3,000  |
| Q2 2026 | $8,000  |
::

*[Chart: Revenue by Quarter]*

| Quarter | Revenue |
|---------|---------|
| Q1 2026 | $3,000  |
| Q2 2026 | $8,000  |

7. Conversation Blocks

Blocks that structure multi-party discussions and decision alternatives.

::turn[participant=brady time=2026-02-10T05:00Z]
Should we go native per platform?
::

### Brady — 2026-02-10 05:00

Should we go native per platform?

::alternatives
| Option   | Pros            | Cons          | Verdict     |
|----------|-----------------|---------------|-------------|
| GTK4     | 5MB, native     | Linux-first   | **Selected**|
| Electron | Cross-platform  | 150MB, heavy  | Rejected    |
::

| Option   | Pros            | Cons          | Verdict     |
|----------|-----------------|---------------|-------------|
| GTK4     | 5MB, native     | Linux-first   | **Selected**|
| Electron | Cross-platform  | 150MB, heavy  | Rejected    |

8. Task Blocks

Actionable task lists and progress indicators embedded in documents.

::tasks[source=inline]
- [x] Build parser crate @brady #done
- [ ] Add chart rendering @brady #in-progress
- [ ] Publish to crates.io @brady
::

- [x] Build parser crate @brady #done
- [ ] Add chart rendering @brady #in-progress
- [ ] Publish to crates.io @brady

::progress[value=65 label="Sprint 3 completion" max=100]

**Sprint 3 completion:** 65%

9. Reference Blocks

Cross-references, embeds, and citations that link documents together.

::related
- [Architecture Plan](plans/architecture.md) — produces
- [GTK Decision](conversations/gtk-decision.md) — references
::

- [Architecture Plan](plans/architecture.md) — produces
- [GTK Decision](conversations/gtk-decision.md) — references

::embed[src=.context/docs/architecture.md section="## Stack" mode=preview]

See: [architecture.md — Stack](.context/docs/architecture.md)

::footnote[id=1]
Gartner, "Magic Quadrant for PM Tools," 2025. Tier 1 source.
::

[^1]: Gartner, "Magic Quadrant for PM Tools," 2025. Tier 1 source.

10. Layout Blocks

Blocks that control content arrangement: columns, tabs, collapsibles, and dividers.

::columns

:::column
Left column content.
:::

:::column
Right column content.
:::

::

Left column content.

Right column content.

::tabs

## Linux
Install via PPA: `sudo apt install surf-browser`

## macOS
Install via Homebrew: `brew install surf-browser`

::

## Linux
Install via PPA: `sudo apt install surf-browser`

## macOS
Install via Homebrew: `brew install surf-browser`

::details[title="Implementation details" open=false]
The sync engine uses SHA-256 content hashing.
::

<details>
<summary>Implementation details</summary>
The sync engine uses SHA-256 content hashing.
</details>

::divider[label="Phase 2"]

---

11. Landing Page Blocks

Web generation blocks for building complete websites from .surf files. These blocks are used inside ::page containers.

::site[domain=example.com]
  name: My App
  theme: dark
  accent: #6366f1
::

**Site Configuration:** example.com, theme: dark

::page[route=/ layout=hero]
# Welcome to My App
Build faster with less.
::cta[label="Get Started" href=/signup primary]
::

# Welcome to My App
Build faster with less.
[Get Started](/signup)

::cta[label="Get Started" href=/signup primary icon=arrow-right]

[Get Started](/signup)

::hero-image[src=assets/screenshot.png alt="App screenshot"]

![App screenshot](assets/screenshot.png)

::testimonial[author="Jane Dev" role="Engineer" company="Acme"]
Replaced 3 tools for me.
::

> Replaced 3 tools for me.
> — Jane Dev, Engineer at Acme

::faq
### Is my data encrypted?
Yes — AES-256 at rest, TLS in transit.

### Can I self-host?
Yes. Docker image available.
::

### Is my data encrypted?
Yes — AES-256 at rest, TLS in transit.

### Can I self-host?
Yes. Docker image available.

::pricing-table
| | Free | Pro | Team |
|---|---|---|---|
| Price | $0 | $4.99/mo | $8.99/seat/mo |
| Notes | Unlimited | Unlimited | Unlimited |
::

| | Free | Pro | Team |
|---|---|---|---|
| Price | $0 | $4.99/mo | $8.99/seat/mo |

::logo-cloud[title="Trusted by"]
- assets/logos/acme.svg
- assets/logos/initech.svg
::

**Trusted by**: acme.svg, initech.svg

::subscribe[action=https://api.example.com/newsletter placeholder="you@email.com"]
Get notified when we launch.
::

Get notified when we launch. Subscribe: https://api.example.com/newsletter

::countdown[date=2026-03-15 label="Launch day"]

**Launch day:** 2026-03-15

::footer
  brand: "My App"
  copyright: "My Company — {year}"
  columns:
    - Links: [Pricing=/pricing, Privacy=/privacy]
::

---
My App | [Pricing](/pricing) | [Privacy](/privacy) | My Company — 2026

::style
  accent: #2563EB
  heading-font: montserrat
  body-font: inter
::

*Ignored entirely — content renders without styling overrides.*

::css
.custom-thing { border: 2px dashed red; }
::

*Ignored entirely.*

::form[submit=/api/contact]
Name: text
Email: email
Message: textarea
::

**Contact form:** /api/contact
- Name (text)
- Email (email)
- Message (textarea)

::gallery[columns=3]
- assets/img1.jpg
- assets/img2.jpg
- assets/img3.jpg
::

![](assets/img1.jpg)
![](assets/img2.jpg)
![](assets/img3.jpg)

12. Navigation Block

::nav[logo="assets/logo.svg"]
- [Home](/)
- [Features](/features)
- [Pricing](/pricing)
::

- [Home](/)
- [Features](/features)
- [Pricing](/pricing)

13. Inline Extensions

Inline extensions use single-colon syntax within text for evidence tags, status badges, person references, and knowledge references.

14. Rendering Model

SurfDoc defines four rendering fidelities. The same source file produces progressively richer output.

Rendering Rules

1. Unknown blocks are preserved. A renderer that does not understand a block type renders it as a fenced section with the block name as a label.
2. Attributes are informational. A renderer that does not understand an attribute ignores it.
3. Content is king. The content layer MUST always be accessible regardless of rendering fidelity.
4. Progressive enhancement. Each fidelity level adds to the previous one.

15. Graceful Degradation

Every block type defines its degradation behavior. A SurfDoc without a renderer MUST be at least as useful as the equivalent plain markdown document.

16. AI Interaction Model

SurfDoc is designed for AI agents to read, write, and modify without special tooling. The syntax is text-based, and block types are semantic.

::ai-context[model=opus tokens=2400 loaded=true]
Context window state when this section was written.
::

*[AI context: opus, 2400 tokens]*

::ai-generated[model=opus date=2026-02-10 reviewed=false]
This section was generated by AI and has not been human-reviewed.
::

*[AI-generated, opus, 2026-02-10, not reviewed]* This section was generated by AI.

17. Document Types

The front matter type field maps to ARDS artifact types. Types are advisory — any block can appear in any document type.

18. Relationship to ARDS

SurfDoc is the document format layer of the ARDS ecosystem. Every ARDS artifact is a SurfDoc. But SurfDoc is not limited to ARDS — it works independently as a general-purpose document format.

ARDS v1-3: File structure + discovery order + artifact types
     |
ARDS v4: Knowledge-context unification + scope model
     |
SurfDoc: Document format that makes artifacts rich, interactive, and AI-native

You do not need ARDS to use SurfDoc. You do not need SurfDoc to use ARDS. They are better together.

19. Export Targets

20. Tooling

surf CLI

surf render <file>                   # Render to terminal
surf render <file> --html             # Render to HTML
surf validate <file>                  # Validate syntax and front matter
surf convert <file>                   # Auto-annotate markdown with blocks
surf new doc "Architecture"           # Create new SurfDoc

Parser Library (surf-parse)

Reference parser in Rust. 378+ tests, 35 block types implemented. Also available as npm package, Python package, and WASM module.

let doc = surf_parse::parse(content);
let html = doc.doc.to_html();            // Rendered HTML
let blocks = doc.doc.blocks();           // Structured block tree

21. Web Generation

SurfDoc files can generate complete websites. A .surf file with ::site and ::page blocks contains everything needed to produce a multi-route static site.

surf build site.surf --out dist/       # Static HTML+CSS+JS
surf serve site.surf                    # Local dev server with hot reload
surf pack site.surf --out site.html    # Single portable HTML file

Layout Types

22. Self-Contained Bundling

SurfDoc supports bundling all assets into a single .surfpack file (ZIP archive) or a single .html file with all content inlined.

document.surfpack
+-- index.surf          # The main document
+-- manifest.json       # Asset inventory with checksums
+-- assets/
    +-- images/
    +-- fonts/

surf pack --html produces one HTML file containing all content, CSS, base64-encoded assets, and the embedded runtime. The original .surf source is recoverable via surf unpack.

23. Computed Data Layer

Data blocks can reference other blocks and compute derived values using =function(#block-id, 'column') syntax.

Computed values are not Turing-complete — no loops, no conditionals. They degrade to their last-evaluated static value.

24. Security Model

SurfDoc is designed to be received from untrusted sources. The security model assumes every document is adversarial.

Core Principles

1. Inert by default. Nothing executes on open, load, render, or view.
2. No ambient authority. No cookies, no session tokens, no implicit credentials.
3. Typed block tree, not arbitrary DOM. Unknown types render as plain text.
4. Fixed visual semantics. A ::callout[type=warning] always looks like a warning.
5. Explicit permission model. Execution, network, and filesystem require per-document consent.
6. Deterministic rendering. Same input always produces the same visual output.

Permission Categories

25. Context-Budget Loading

SurfDoc defines a loading priority protocol for AI agents operating under token constraints. Any block can declare a priority attribute (0-4).

26. Surf Browser

SurfDoc defines a browser architecture for native rendering with a dual-engine design.

Surf Browser
+-- SurfEngine (Rust + GPU)     <- .surf files
|   +-- surf-parse              <- Parser
|   +-- surf-layout             <- Block tree to positioned rectangles
|   +-- surf-render             <- GPU rendering (wgpu/skia)
|
+-- WebView (platform WebKit)   <- .html sites
|   +-- Full web compatibility
|
+-- AI Layer
    +-- Block-tree query API
    +-- Summarization
    +-- Knowledge graph

No DOM. SurfEngine uses a typed, immutable block tree. No XSS. No script injection vector. Deterministic rendering. Same .surf always produces the same visual output.

27. Executable Code

Documents contain code, and code should be runnable. The runnable attribute on ::code blocks activates execution, turning a .surf file into a Jupyter-class notebook that degrades to a readable text file.

::kernel[lang=python env=analysis]
  runtime: python3.12
  packages: [numpy, pandas, matplotlib]
  sandbox: strict
::

*[Kernel: python3.12, packages: numpy, pandas, matplotlib]*

::output[for=analysis timestamp="2026-02-10T12:00:00Z" exit=0]
Mean quarterly revenue: $12,000
Growth: 633%
::

```
Mean quarterly revenue: $12,000
Growth: 633%
```

28. Accessibility

SurfDoc is accessible by construction, not by remediation. If a .surf file is valid, it is accessible. Every block type defines a narration strategy, reading modes, and semantic navigation.

Block Narration Contract

Every block type MUST define a narration strategy. Adding a new block type without defining its narration is a compilation error in the reference implementation.

Reading Modes

Semantic Navigation