HTML Interpretation

Elonn supports HTML as a source language for content and interaction.

HTML describes document structure, content, relationships, resources, and behavior. It does not describe a two-dimensional page. Elonn interprets HTML into canonical data; a Runtime then presents that data according to the capabilities of its environment.

This document defines how HTML enters the Elonn object model and how assumptions specific to conventional browser layout are separated from the document itself.

Interpretation, not rendering

Elonn does not define an alternate HTML renderer. It defines an HTML-to-canonical-data interpretation.

A conventional browser approximately performs:

HTML -> DOM -> style -> layout -> paint -> viewport

Elonn preserves HTML structure and semantics and lets presentation diverge after interpretation:

World owns canonical representation. The Runtime owns presentation.

web.elonn.com is the web Runtime — it renders a World Dataset in a browser. It is not the HTML interpreter, and it does not parse source HTML into Elonn semantics. A web page that becomes Elonn content is interpreted before any Runtime sees it, the same as content from any other Service.

Interpretation does not introduce a presentation requirement into the canonical representation merely because conventional browsers rely on that requirement.

HTML is a format, not a system

A Provider adapts an external system to a Service. HTML is not an external system. It is a format that may be returned across a Service or Provider boundary — by a web-search backend, by a document import, by a system that happens to serve HTML.

Elonn does not define an "HTML Provider" and does not define an HTML Service. Either one produces a separate HTML interpretation for every source that returns HTML.

The Service that consumes an external representation is responsible for interpreting that representation into canonical data.

Format interpreters are reusable platform components — libraries that implement this specification. They are not Services and not Providers. An interpreter returns canonical structures; the consuming Service assembles them into a Service Dataset.

This preserves the existing boundaries:

Services return Datasets.
World does not parse HTML.
Providers do not define canonical HTML semantics.
Runtimes do not parse arbitrary source HTML into Elonn semantics.

Format dispatch

A Service that retrieves an external resource determines the resource's format and dispatches to the interpreter for that format:

Format detection is the consuming Service's responsibility. An interpreter is given a representation it has already been told is HTML.

Find is the first consumer. Find retrieves a resource, detects text/html, runs the HTML interpreter, and returns the resulting canonical structures in its Service Dataset. Other formats follow the same architecture behind the same dispatch.

The interpreter is a pure function

HTML interpretation is a pure function from an HTML representation to canonical data.

It performs no network retrieval. Referenced resources are recorded as references; they are not fetched or resolved during interpretation.
It does not depend on wall-clock time, locale, or environment.
The same HTML input produces the same canonical structures every time.

Determinism keeps a single specification in control of the result regardless of which component holds the implementation.

Dynamic behavior — script execution, translation of CSS layout into spatial layout — is not part of this function and is out of scope for the initial specification (see Scope). Those are the parts that would make interpretation non-deterministic.

Scope

The initial scope is static HTML documents and declarative external resources.

In scope:

the document, its head metadata, and its perceivable content;
structural and text-level content;
anchors and their targets;
images, audio, video, and embedded resources declared in markup;
the initial element set listed at the end of this document.

Out of scope for the initial specification:

general JavaScript execution;
translation of CSS layout into spatial or runtime-independent presentation;
canvas, WebGL, and other imperative drawing surfaces;
reconstruction of single-page applications;
forms, tables, and SVG (specified after the boundaries below are stable).

This scope is sufficient to prove the architecture.

Source preservation

Elonn preserves the source HTML as a Resource.

Resource
media_type: text/html
source: URI
content: the HTML bytes, when retained

The canonical Object references that Resource. A retrievable reference is sufficient — when the authoritative source remains retrievable, Elonn does not duplicate the bytes. Retention follows the persistence rules resource.md already defines.

Interpretation does not require destructive transformation of the source. The source document and its canonical representation serve different purposes: the source preserves the document; the canonical data exposes the document's content, structure, resources, relationships, and actions to Elonn.

Document

An HTML document remains a document.

The html element establishes the HTML document.
The head element contains document metadata and resources not ordinarily represented as perceivable content.
The body element establishes the root of the document's perceivable content.

Elonn preserves this distinction. body does not canonically mean a rectangular page or viewport; it establishes the content root.

Semantic regions

A page structured with landmark elements — header, nav, aside, footer — groups its content into semantic regions instead of one flat, document-order tree. The recognized regions are:

header
navigation
main content
sidebar
secondary sidebar
footer

A header, nav, aside, or footer is extracted into its region wherever it occurs in the body — including inside a main element, which carries no special selection of its own and is otherwise transparent. It is not extracted, and stays ordinary content of its container, when it occurs inside article or section: an article's own byline header or a section's own related-content aside describes that piece of content, not the page. A nav nested inside an already-extracted header or footer stays that region's content rather than establishing a separate navigation region, by the same rule. Two aside landmarks are the sidebar and secondary sidebar, in document order; a third and further aside joins the secondary sidebar. Content claimed by no region belongs to the main content region — a page with no landmark elements at all is a single main content region holding everything the interpreter finds.

Only regions that contain content are exposed. A page with no footer element has no footer region.

A region is an addressable part of the document Object, not a promoted Object. This is the same rule div and span already follow: identifying a part of the content does not by itself create independent identity (see Object promotion, object.md).

The document's <title> is not a region. It is the Object's own name (Head promotion, below) and remains visible regardless of which region is displayed — it is not something a member navigates into or away from.

Head promotion

Information in head may contribute to canonical representation. Its presence in head does not mean a Runtime presents it.

The recognized promotions are:

<title> -> the Object's content title
<link rel="canonical"> -> a source canonical URI, recorded as provenance
<link rel="..."> (recognized) -> a Relationship, when the relation is recognized
<meta name="description"> -> a description
OpenGraph / schema.org -> interpreted when the vocabulary is recognized
<meta> (unrecognized) -> retained in the source HTML only; no canonical structure

<link rel="canonical"> is the publisher's statement about the source resource. It is provenance and identity evidence. It does not assign an Elonn Object identifier — Elonn assigns its own.

An unrecognized metadata vocabulary produces no canonical structure. It remains available in the preserved source Resource.

Structural elements

section and article establish thematic groupings of content. Elonn preserves the grouping. A Runtime represents it using mechanisms appropriate to the Runtime — a document section, a native content grouping, a spatial grouping. The grouping is canonical; its arrangement is presentation.

div establishes a generic grouping of descendants. Elonn assigns it no additional intrinsic meaning. div does not canonically mean rectangle, panel, window, plane, screen, or surface.

span establishes a generic scope within phrasing content. It may mark content for a relationship, an action, or metadata without causing that content to become an independent object.

div and span are never promoted to Objects.

Text-level content

Headings (h1–h6) and paragraphs (p) contribute structured content to the canonical representation that contains them. They do not independently cause Object promotion.

A promotable ancestor is not required. A document may be:

<body>
<h1>Hello</h1>
<p>World.</p>
</body>

Here the document itself is the Object, and its canonical content contains the heading and paragraph. No intermediate element is promoted to make this valid.

Anchors and navigation

The a element establishes an anchor. When href is present, it establishes a relationship to the resource identified by that URI.

<a href="https://example.com/place">Place</a>

Elonn preserves the anchor's content and its target. The anchor does not by itself create another Object.

Interpretation turns the anchor into a canonical reference, not a URL string a Runtime later reads. The anchor's href becomes the references Relationship and the navigate Action described under Produced structures; the raw URI is reference data on those structures, and the operation for following the link is the navigate Action's operation_invocation (see action.md, relationship.md, resource.md). A Runtime follows the link by dispatching that operation — never by opening the URI itself.

Activation of an anchor is an action. For a navigational href, the default action is navigation of the content context that contains the anchor.

When the anchor is inside an Object opened on Carry, activation navigates within that Object:

Object
+-- current content A
+-- <a href="B">
|
| activate
v
Object
+-- current content B

Activation does not open another Object on Carry merely because the target is another URI. This is the Object navigation model in layout.md: navigation history belongs to the Object, context.objects[id].history records prior states, and world.back steps them. The Runtime determines how activation is performed — click, tap, gaze, gesture, pointer, keyboard, or another supported input. The semantic action is navigation.

Activation is focus (layout.md, Focus and alt focus). Alt-focusing an anchor opens its destination in a new Object instead, leaving the Object the anchor was activated in unchanged.

Region navigation

Opening a document — the initial open of a Finding, or following a link to a document not yet interpreted — presents that document's region list first, not a region's content directly. This holds for every document; interpretation does not decide that one region matters more than another on the member's behalf.

Object
+-- <document>
+-- region list: header, navigation, main content, footer
|
| focus "footer"
v
Object
+-- <document>
+-- footer content

Focusing a region displays that region's content within the current Object. Focusing a link found within a region's content is an ordinary anchor activation (Anchors and navigation, above) — it opens within the current Object, landing on the destination document's own region list.

Alt-focusing a region, or a link within one, opens the same target — the current document, for a region; the link's destination, for a link — in a new Object, landing on that Object's region list. Alt focus does not open a region's content directly in the new Object; a freshly focused document always starts at its region list, regardless of what was alt-focused to get there.

Displaying a region the current Object already holds — including returning to one via back — is a World operation with no Service call: the region's content already exists in the composed document Object, so World changes only its own navigation state for the container (context.objects[id].region, layout.md), the same history a document swap pushes onto. Opening a document not yet interpreted — following a link — calls a Service, because its canonical content does not yet exist in the Dataset. Both are focus, and both go through World; the difference is only whether a Service is involved.

Media and embedded resources

img, audio, video, and iframe declare resources. Each is a Resource and may additionally be promoted to an Object.

Elonn preserves, as available: source URI, title, intrinsic or specified dimensions, aspect ratio when determinable, permissions, and provider requirements.

An iframe establishes a nested browsing context containing an embedded resource. Elonn does not represent it as a rectangle within a rectangle. When the embedded resource has distinct identity, it may be represented as an Object.

Whether an iframe's src is a recognized provider embed, and what Object it is promoted to, is decided by the oEmbed provider table (oembed.md) — the same table find.open checks against a bare pasted URL, so the same video reached either way resolves to the same Object. oembed.md is the authority on provider recognition and the execution boundary (what a provider may and may not determine); this section states the resulting shape.

may be represented as:

Object
type: video
title: Rebuilding a Carburetor
content:
source: https://www.youtube.com/embed/p9iOYApFgu8
provider: YouTube
aspect: 16:9

The Object represents the video as a thing within the member's world. Elonn does not thereby claim ownership of the video or its media bytes.

External presentation

Some resources require presentation supplied by their originating provider.

An Object may have canonical identity, properties, relationships, actions, and placement while relying on an external provider for part of its presentation or behavior:

video Object
+-- identity Elonn
+-- placement Elonn
+-- relationships Elonn
+-- sharing Elonn
+-- discussion Elonn
+-- provenance Elonn
+-- audiovisual playback YouTube

Provider presentation is a capability of the resource. It does not define the identity of the Object.

Object promotion

Not every element becomes an Object.

Elements establish structure and semantics from which Objects, Resources, Relationships, Actions, and Collections are identified. The tag alone does not determine Object identity.

div -> grouping (never an Object)
span -> content scope (never an Object)
header, nav, aside, footer, main -> semantic region (never an Object)
h1-h6, p -> structured content (never independently an Object)
a -> relationship + action
img -> Resource, potentially Object
iframe -> embedded Resource, potentially Object
video -> Resource, potentially Object
article -> structured content, potentially Object

Promotion depends on whether the represented thing has independent identity or utility within Elonn — not on the tag. A document with no promotable descendant is itself the Object.

CSS

CSS is presentation information.

Elonn may consume CSS. CSS does not create a canonical Object, Relationship, Action, Collection, Resource, or Placement.

Some declarations carry presentation meaning that remains useful across Runtimes; others are meaningful only to two-dimensional presentation. The mapping of CSS into runtime-independent presentation semantics requires separate definition and is not defined here.

Script

JavaScript can alter document structure, content, state, and behavior. Elonn does not assume that an HTML document is fully described by its initial source markup.

Within the initial scope, script is not executed.

If script execution is supported later:

JavaScript execution does not directly create canonical structures.
JavaScript does not obtain an Elonn capability by calling DOM methods such as document.createElement().
JavaScript may modify the interpreted document state. Canonical structures are then derived from the resulting state under the same interpretation rules in this document. A script-created video element is eligible for the same Object promotion as a video element present in source markup, because promotion is a property of the interpreted document state, not of the original bytes.

The relationship among execution, security boundaries, and Runtime behavior requires separate definition and is not defined here.

Placement invariant

HTML interpretation never creates a Placement.

Placement types are exactly carry and field, governed by the World Dataset contract (layout.md, placement.md). Webpage coordinates, CSS position, document order, and visual arrangement have no bearing on Placement.

Interpreted content is returned unplaced. World and the Runtime place it according to the layout rules — as Findings in the Results pane, opened onto Carry when focused, or placed on Field only by an explicit Field placement from the owning Service.

Compatibility

Elonn permits conventional web rendering when content cannot usefully be represented otherwise.

Compatibility rendering is a Runtime capability, not a canonical representation. It is itself Runtime-dependent and may be unavailable — a Runtime with no browser surface cannot fall back to one. When it is unavailable, the Object still exists with its canonical identity, metadata, and actions, and the Runtime presents what it can, including an action to open the source externally.

The existence of a compatibility path does not make conventional browser presentation the canonical representation.

A resource may move along a representation spectrum:

canonical native representation
|
v
provider-specific representation
|
v
conventional web rendering

Output

An interpreter returns canonical structures. The consuming Service assembles them into a Service Dataset, which World composes into the World Dataset like any other Service result.

Interpreted content carries no Placement. It is composed as Findings unless an explicit operation or a focused Finding opens an Object (layout.md).

Produced structures

Interpreting one HTML document produces:

one document Object. Its content carries the document title, the source URI, a canonical_url when the source declared one (provenance only), a description, the recognized head facts, and regions — an ordered list of the page's semantic regions (Semantic regions, above), each {key, content} where content is that region's own ordered structured-content tree. Each tree node is a heading (level, text), a paragraph (text, and links when it contains anchors), a section (role, nested content), or media (kind, and a reference to the promoted Resource or Object). A page with no landmark elements produces exactly one region, main. The document Object is the one opened on Carry when a Finding for the source is focused, presenting its region list first (Region navigation);

a text/html source Resource the document references;

a promoted media Object for each media element with independent identity — a recognized provider embed becomes a video Object (content: title, source, provider, provider_id, aspect, playback: "external"); a native video/audio element with a real source becomes a video/audio Object (playback: "native"). An img, and an unrecognized iframe, stay Resources;

for each resolvable anchor, a references Relationship (source: the document; target_url) and a navigate Action. The navigate Action carries the operation_invocation that re-opens the target — so a Runtime follows an in-document link by dispatching that invocation with the document as origin_object, and it navigates in place (layout.md, Object navigation). A Runtime never composes that invocation itself.

The type names above (document, video, audio) are Object types produced by interpretation; they are not part of the Canonical Data Model's fixed vocabulary, which defines structure, not types (object.md).

Initial element set

Interpretation behavior is defined first for:

html head body title meta link
section article div span
header nav main aside footer
h1 h2 h3 h4 h5 h6 p
a
img video audio iframe

These establish the boundaries among document, structure, grouping, content, resource, relationship, action, Object, and presentation. Forms, tables, canvas, SVG, WebGL, CSS layout, and JavaScript execution are specified only after these boundaries are stable.

Invariant

Elonn does not assume that HTML must be presented as a rectangular webpage.

HTML describes content and relationships. Interpretation makes those available to World as canonical data. The Runtime determines how they inhabit the member's environment.

A browser makes HTML inhabit a viewport. Elonn makes HTML capable of inhabiting the world.

Html