Draft format 0.1

Make a book that beckons.

The `.beckon` format is a portable, inspectable package for semantic books and safe interactive details. Anyone can author one; the trusted Beckon reader supplies the React runtime.

The model

Creators shape the book, composition, data, and behavior. Beckon handles the secure rendering engine.

A `.beckon` is not a bespoke edition we make for you. It is a format you can generate yourself—from a publishing project, an export tool, or eventually Beckon Studio.

Books do not ship React or JavaScript. They select versioned capabilities such as beckon:stat-card@1 and provide validated data plus readable fallback prose. The reader maps that declaration to its trusted React implementation.

Package anatomy

A `.beckon` file is a constrained ZIP container with a required media-type marker, manifest, typed chapter JSON, and local assets.

mimetype
manifest.json
content/
  chapter-01.json
assets/
  cover.webp

Required protections

  • No absolute or parent paths, symlinks, encryption, nested archives, duplicate paths, scripts, remote embeds, or author CSS.
  • 100 MB compressed, 400 MB expanded, 2,000 files, and a 100:1 maximum entry compression ratio.
  • Every content and asset file is declared with byte length, media type, and SHA-256 checksum.
  • Published revisions are immutable. Any changed byte creates a new revision.

Minimal manifest

{
  "beckon": "0.1",
  "publicationId": "your-book-id",
  "revision": "2026-07-21.first-edition",
  "title": "Your Book Title",
  "contributors": [{ "name": "Author Name", "role": "author" }],
  "language": "en",
  "direction": "ltr",
  "cover": "assets/cover.webp",
  "readingOrder": [
    { "id": "chapter-01", "href": "content/chapter-01.json", "title": "Chapter One" }
  ],
  "resources": [],
  "capabilities": ["beckon:stat-card@1", "beckon:message-thread@1", "beckon:composition@1.0"],
  "styleProfile": "beckon:utilities@1.0",
  "rights": {
    "basis": "copyright-owner",
    "territories": ["worldwide"]
  }
}

Semantic content

EPUB 3, Markdown, and HTML are import formats. Runtime chapters use a typed JSON tree so the same book remains stable across browsers, themes, devices, and future readers.

Core blocks are paragraphs, headings, block quotes, thematic breaks, accessible tables, images, and components. Stable kebab-case block IDs anchor progress and future annotations. Raw author HTML is never passed to React through dangerouslySetInnerHTML.

Italics, bold, and inline code

Text remains plain UTF-8 plus validated zero-based UTF-16 code-unit ranges. Marks may overlap, but every range must begin before it ends and remain within the text. Readers render emphasis as semantic italics, strong as semantic bold, and code as inline code.

{
  "type": "paragraph",
  "id": "warning-note",
  "text": "Do not open the door.",
  "marks": [
    { "type": "emphasis", "start": 0, "end": 21 },
    { "type": "strong", "start": 7, "end": 20 }
  ]
}

Tables

Tables require a caption, one to twelve uniquely identified columns, and one to five hundred rows. Every row has exactly one rich-text cell per column. A single column may be marked as the row-header column; alignment is semantic and narrow screens receive a keyboard-accessible horizontal scroll region.

{
  "type": "table",
  "id": "training-results",
  "caption": "Dumpling diagnostic results",
  "columns": [
    { "id": "trait", "header": "Trait", "rowHeader": true },
    { "id": "before", "header": "Before", "align": "right" },
    { "id": "after", "header": "After", "align": "right" }
  ],
  "rows": [{
    "id": "health",
    "cells": [{ "text": "Health" }, { "text": "2" }, { "text": "3", "marks": [{ "type": "strong", "start": 0, "end": 1 }] }]
  }]
}

Pictures, GIFs, and video

Visual storytelling is part of the format. Pictures are package-local JPEG, PNG, WebP, or sanitized static SVG files. Meaningful pictures require useful alternative text; decorative art uses an empty alternative. Every asset is declared and checksum-covered.

GIFs are accepted during import, then normalized. Essential animation becomes controlled MP4/WebM with a static poster; decorative animation becomes a still. Raw animated GIF is not shipped because it cannot reliably honor pause controls or reduced-motion preferences.

Video is package-local MP4 or WebM and requires a poster, WebVTT captions, readable transcript fallback, and concise description. Beckon supplies controls, never autoplays or starts sound, and never requires playback to continue the book. The 0.1 profile recommends 75 MB per video, 10 MB per picture, and 100 MB for the complete package.

Sequential short-form stories

Beckon can package a micro-series, vertical drama, or mixed text-and-video serial. A work declares itself as a serial or hybrid, then lists stable chapters, episodes, and interludes in one canonical order.

Unlike an endless swipe feed, a Beckon serial has a beginning, visible episode count, exact resume position, previous and next episodes, and an ending. A user may opt into continuous play, but creators cannot force autoplay, automatic sound, or algorithmic detours.

Episodes may move from vertical video into prose, pictures, or interactive details and back again without losing narrative position. AI use is disclosed per video as none, assisted, generated, or unknown; rights for music, performance, face, voice, and likeness remain explicit. Social clips can deep-link into an episode for discovery while Beckon preserves “start at episode one” and “continue” as first-class actions.

Creator-made experiences

Capabilities are reusable vocabulary. Creators supply content, semantic structure, themes, and declarative composition while Beckon supplies the trusted renderer.

{
  "type": "component",
  "id": "inn-ledger",
  "component": "beckon:stat-card@1",
  "data": {
    "id": "inn-ledger",
    "title": "The Admiral Benbow",
    "stats": [{ "label": "Owed", "value": "4", "unit": "months" }],
    "fallback": "The captain owes four months of lodging."
  },
  "fallback": [
    { "type": "paragraph", "id": "inn-ledger-fallback", "text": "The captain owes four months of lodging." }
  ]
}

beckon:message-thread@1

Message threads preserve chronological semantic reading order while the trusted reader aligns incoming and outgoing bubbles visually. Each thread declares one to twenty participants and one to five hundred messages. Participant and message IDs are unique; every senderId must resolve to a declared participant.

Each message requires direction, senderId, and text. Timestamps are optional story labels rather than machine dates. Delivery status—sent, delivered, read, or failed—is optional and valid only on outgoing messages.

{
  "type": "component",
  "id": "midnight-messages",
  "component": "beckon:message-thread@1",
  "data": {
    "title": "Unknown number",
    "participants": [
      { "id": "mara", "name": "Mara" },
      { "id": "unknown", "name": "Unknown" }
    ],
    "messages": [
      {
        "id": "message-01",
        "senderId": "unknown",
        "direction": "incoming",
        "text": "You should not have opened the door.",
        "timestamp": "11:42 PM"
      },
      {
        "id": "message-02",
        "senderId": "mara",
        "direction": "outgoing",
        "text": "Who is this?",
        "timestamp": "11:43 PM",
        "status": "delivered"
      }
    ]
  },
  "fallback": [
    {
      "type": "paragraph",
      "id": "midnight-messages-fallback",
      "text": "An unknown sender warned Mara that she should not have opened the door. Mara asked who it was."
    }
  ]
}

Beckon Utilities · beckon:utilities@1.0

Beckon Utilities is a versioned, Tailwind-like vocabulary owned by Beckon. A publisher may compose stacks, rows, grids, headings, rich text, dividers, and stat changes; apply approved layout, spacing, typography, color, border, radius, and responsive utilities; and provide a semantic hexadecimal palette.

Version 1.0 classes never silently change meaning. There is no Tailwind runtime or publisher CSS. Unknown classes fail validation. Arbitrary bracket values, dynamic class construction, positioning, z-index, selectors, URLs, imports, hooks, handlers, forms, raw HTML, scripts, and browser APIs are rejected.

{
  "type": "component",
  "id": "dumpling-diagnostic",
  "component": "beckon:composition@1.0",
  "data": {
    "styleProfile": "beckon:utilities@1.0",
    "label": "Dumpling diagnostic",
    "theme": { "surface": "#21152c", "surfaceAlt": "#2c1d38", "ink": "#f4edf8", "muted": "#c0aacb", "accent": "#e7bd70", "positive": "#79d69f", "negative": "#ff9b9b" },
    "root": {
      "type": "stack",
      "class": "bg-surface border border-accent rounded-lg p-4 gap-3 font-mono",
      "children": [
        { "type": "heading", "level": 3, "text": "SP-4 DIAGNOSTIC · DUMPLING", "class": "text-xs text-accent uppercase tracking-wider" },
        { "type": "stat-change", "label": "Health", "previous": "2", "current": "3", "change": "increase", "class": "text-sm" }
      ]
    }
  },
  "fallback": [{ "type": "paragraph", "id": "dumpling-diagnostic-fallback", "text": "Dumpling's health increased from two to three." }]
}

Compositions are limited to 300 nodes, 12 levels of nesting, 50 children per group, and 32 approved utilities per node. They are rendered inside CSS containment and always include equivalent fallback prose.

  • Every capability and style profile has an exact versioned schema.
  • Every instance contains an equivalent semantic fallback.
  • Unknown capabilities degrade to fallback instead of breaking the chapter.
  • No network, storage, account access, autoplay, DOM access, arbitrary navigation, or executable code.
  • The reader owns focus, keyboard behavior, reduced motion, containment, and screen-reader semantics.

Trusted motion

Beckon Utilities 1.0 includes animate-blink for cursors and indicator lamps, animate-pulse for quiet status emphasis, and animate-glow for restrained luminous text. Publishers choose where to apply them but cannot alter their keyframes, timing, iteration, or easing.

These utilities affect only opacity or text shadow, never layout. The reader automatically removes every animation when the user requests reduced motion. Custom keyframes, transforms, flashing colors, and animation URLs remain prohibited.

Conformance

A valid package passes container safety, exact manifest schemas, resource closure, checksums, content schemas, unique block IDs, component schemas, accessibility checks, and responsive/offline rendering. Format validity does not itself grant publication or sale rights.

Creators may iterate in a mutable preview workspace using the exact production validator and renderer. Browser edits replace structured blocks, retain stable IDs, create an audit change, and advance a guarded workspace generation; they never introduce raw HTML, CSS, or JavaScript. Only an explicitly promoted workspace becomes an immutable revision.

This is intentionally a 0.1 draft. A project creating packages today should pin to 0.1, retain its source, and expect explicit migrations before 1.0—not silent behavior changes.

Create a `.beckon`

  1. Structure the manuscript semantically and assign stable publication, chapter, and block IDs.
  2. Convert chapters to the 0.1 JSON block model and add local, declared assets.
  3. Add optional versioned capability declarations with complete fallback prose.
  4. Build the manifest, calculate exact byte sizes and SHA-256 hashes, and package the required ZIP layout.
  5. Use the remote Beckon MCP to upload and validate an immutable private draft, create an expiring reader preview, and publish only after explicit approval.