iComic format — provisional draft 0.4.0

This specification is provisional. It is the current beta contract shared by Reader and Reader Publisher, not yet a stable interchange or archival standard. Fields, limits, profiles, and migration rules may change before a stable release.

iComic is a page-first interactive-comic format, not a video with comic controls. Each page owns layered panels, an explicit accessible reading order, and discrete reveal steps. Local images, video, audio, transitions, and optional compositing can respond to those steps. The essential page must remain understandable when those enhancements are unavailable.

Working identity and compatibility

{
  "format": "valentine.interactive-comic",
  "schemaVersion": "0.4.0"
}

The development container is .icomic: an ordinary ZIP archive with a custom extension. The provisional app file-handler MIME is application/vnd.gremmoire.icomic+zip; generic application/zip remains accepted during beta development.

The current Reader:

• fully recognizes schema 0.4.0;
• continues to read legacy drafts 0.3.1, 0.3, and 0.2;
• continues to normalize the legacy format ID valentine.interactive-story;
• rejects unknown format and schema identifiers instead of guessing; and
• distinguishes required capabilities from optional enhancements.

Draft 0.4.0 adds fail-closed capability negotiation, explicit page reading order and summaries, optional cover metadata, verifiable media byte declarations, and a bounded compositing vocabulary. Legacy drafts remain readable but do not retroactively gain guarantees for fields they never declared.

Minimum 0.4.0 manifest

{
  "format": "valentine.interactive-comic",
  "schemaVersion": "0.4.0",
  "id": "my-comic",
  "title": "My Comic",
  "capabilities": {
    "required": ["reading-order"],
    "optional": ["panel-reveals"]
  },
  "pages": [
    {
      "id": "page-1",
      "label": "Page 1",
      "summary": "The protagonist enters a dark station.",
      "readingOrder": ["page-1-art"],
      "panels": [
        {
          "id": "page-1-art",
          "type": "image",
          "src": "assets/pages/page-001.webp",
          "alt": "A lone figure enters an unlit railway station."
        }
      ]
    }
  ]
}

The assets catalog is optional, so one local source per panel is valid. In 0.4.0 every image, GIF, and video panel needs meaningful alt; every text panel needs nonempty text. Media-bearing content needs a local src, including content that also references a logical asset.

Recommended archive layout

my-comic.icomic
|-- comic.json
|-- assets/
|   |-- panels/
|   |   |-- page-001.avif
|   |   `-- page-001.webp
|   |-- audio/
|   |   |-- rain.opus
|   |   `-- rain.m4a
|   `-- video/
|       |-- motion-av1.webm
|       `-- motion-h264.mp4
`-- README.txt

For schema 0.4.0, comic.json is the only accepted manifest name and must be at the archive root. The aliases story.json, manifest.json, and reader.json remain readable only for legacy schema packages.

Archive rules:

• Include exactly one recognized root manifest.
• Keep asset paths relative, /-separated, and case-sensitive. A leading ./ is normalized away.
• Absolute paths, parent traversal, backslashes, controls, null bytes, ambiguous names, and duplicate paths are rejected.
• Encrypted entries, symlinks, nested active documents, and nested-container semantics are unsupported.
• Store and DEFLATE are the only accepted ZIP methods.
• A media path must match a selected sibling or archive entry. Protocol-based, missing, and otherwise unsafe paths are never fetched.
• Script, HTML, arbitrary CSS, SVG, plugin, and network execution are forbidden.

Capability negotiation

capabilities has two arrays, each capped at 32 unique lowercase kebab-case names:

{
  "capabilities": {
    "required": ["reading-order"],
    "optional": ["audio-cues", "visual-compositing"]
  }
}

A Reader rejects a package when it does not understand a required capability. It may open a package with an unknown optional capability, but warns and uses the readable fallback. Capability names describe behavior; they do not grant permissions.

The older experimental booleans remain descriptive compatibility hints. They are not a substitute for required/optional capability negotiation.

Media-profile principle

The formats named here are first-class options, not universal winners. Results depend on the source, encoder, quality target, browser and operating system, and the author’s experience and preference.

WavPack and H.266/VVC may be useful authoring/master inputs. They are not 0.4.0 browser-delivery promises. Publisher rejects WavPack in an iComic delivery package instead of silently exporting an unplayable cue. Animated AVIF and GIF imports remain deferred until bounded playback and fallback policies exist.

Logical assets and ordered variants

One manifest may declare at most 10,000 logical assets. Each may contain one to four ordered local variants:

{
  "assets": [
    {
      "id": "page-1-art",
      "kind": "image",
      "fallback": "assets/pages/page-001.webp",
      "delivery": {
        "profile": "painted-page",
        "selection": "first-supported"
      },
      "variants": [
        {
          "src": "assets/pages/page-001.avif",
          "type": "image/avif",
          "bytes": 481203
        },
        {
          "src": "assets/pages/page-001.webp",
          "type": "image/webp",
          "bytes": 639441
        }
      ]
    }
  ]
}

Do not duplicate a source within one asset, bind one path to multiple logical assets, or assign one path conflicting roles. A declared type cannot disguise an extension or file signature.

An image background, cover, image/video panel, or audio cue can reference an asset. Its src must still exactly equal that asset’s fallback. The Reader tries variants in author order when the browser appears to support them and may retry a later local alternative after decoding failure.

Top-level fields

presentation.fit accepts contain, width, or height; presentation.startMode accepts panel or page; pageGap is clamped 0–100.

Page contract and accessible order

If readingOrder is supplied, it must name every panel exactly once: unknown, duplicate, and omitted IDs reject. When absent, manifest panel order is the fallback. z controls visual stacking and never changes reading order.

Background values accept only a narrow sanitized color/gradient grammar. Image backgrounds may use src, asset, fit, and bounded depth. URL/data/blob functions and network-capable CSS are discarded.

Panel contract

Frame x/y are clamped -300–300 and width/height 1–300, permitting bounded off-canvas placement and overscan. Supported transitions are none, fade, rise, slide-left, slide-right, ink, and focus. Decorative animations are none, drift, pulse, float, pan, and breathe; they must never carry information lost under reduced motion.

Cue contract

Recognized cue types are audio, tone, background, vibrate, and caption. Audio cues may use a local audio asset. Current triggers are:

• enter for page-entry behavior;
• reveal for a panel-local cue; and
• step:N for a page cue at a discrete step from 0–10,000.

The Reader cancels delayed cues when a new reveal or page supersedes them. Browser autoplay and codec rules override playback hints. Channel replacement, crossfade, loop lifetime, mastering metadata, and transcript linkage remain provisional.

Cover and extended appendix

cover is optional and uses the same local image asset bridge as a panel. In 0.4.0, a supplied cover needs both a source and meaningful alt text.

Each top-level context entry needs a stable id, label, title, and concise body. An optional term links exact matching text to a hover/focus preview and click/tap appendix entry. Optional details supplies the expanded explanation. Entries without a term remain available from Comic margins. The limit is 100 author-context entries per work.

Packaging performance

The Reader opens comic.json first, resolves only media for the current page, and may warm a bounded part of the next page while idle.

• Use Store for already-compressed AVIF, WebP, PNG, JPEG, FLAC, Opus, AAC/M4A, MP3, MP4, and WebM media.
• Use DEFLATE for comic.json and small text files.
• Test PCM WAV rather than assuming it behaves like compressed media.
• Keep authoring masters, private notes, and layered source projects outside the delivery archive.

Reader Publisher 0.4.0 exports text entries with DEFLATE and media entries with Store. Its current beta export uses one declared delivery source per staged layer; the format supports up to four. Importing a multi-variant package stages its declared fallback and warns the author to retain the original and masters.

Safety and resource limits

Current rejection ceilings include:

• 500 MB selected custom-container file;
• 10,000 pages and 10,000 logical assets;
• four variants per logical asset;
• 100 author-context entries and 32 capabilities per class;
• 2,048 characters per media source path;
• 80 MB per expanded entry and 1.5 GB total expanded archive;
• 100:1 maximum compression ratio and 50,000 archive entries;
• 2 MB root manifest;
• 256 panels per page and 20,000 panels plus cues per work;
• 128 playable cues, 16 sound cues, and four video panels per page; and
• 16,384 pixels per raster axis, 20 megapixels per raster item, and 24 megapixels per rendered page.

These are rejection limits, not performance promises. A valid package can still exceed the practical memory or decoding capacity of a particular phone.

Reader conformance principles

A conforming beta Reader should:

1. Reject unknown schemas and unsupported required capabilities.
2. Warn and fall back when an optional capability is unavailable.
3. Preserve explicit reading order independently of visual stacking.
4. Expose essential content without sound, haptics, animation, sensors, depth, or one optional codec.
5. Respect reduced motion and mute immediately.
6. Provide keyboard and button navigation independent of gestures.
7. Expose authored alt text, context, captions, and page summaries.
8. Never execute package-provided scripts, HTML, CSS, plugins, or network calls.
9. Verify declared local media sizes before exposing archive assets.
10. Tear down media, timers, decoders, and temporary URLs when leaving a work.

Reader Publisher 0.4.0 behavior

The iComic template compiles a real Reader-openable .icomic, rather than a generic prose package carrying an iComic label. Publisher maps included page records, summaries, scoped media layers, reveal steps, transitions, compositing, video playback, audio entry/step cues, context, cover art, and opening artwork into the manifest and archive.

Pages with no visual media receive a readable text fallback. Staged opening artwork receives its own first reveal on page one; that page’s authored panel and step-cue numbers shift forward so the opener is not immediately covered. Export runs the same validator used by Reader. Publisher draft JSON remains the editable working record; .icomic is the delivery copy and does not publish itself.

Local .icomic import uses the actual Reader loader and validator. It rebuilds pages and editable placements from safe local fallbacks. This is an editing bridge, not lossless source recovery: retain the original package and masters.

Packaging checklist

• Use schema 0.4.0 and root comic.json.
• Declare only capabilities the work actually needs.
• Use unique page, panel, cue, context, and asset IDs.
• Give every media panel meaningful alt text and every text panel readable text.
• Declare complete readingOrder arrays for authored pages.
• Use relative /-separated paths with exact filename case.
• Keep each fallback in its variant list and each holder src equal to it.
• Record exact variant bytes when packaging can verify them.
• Test MIME, codec, signature, dimensions, duration, and every fallback.
• Provide visible captions/transcripts for meaningful audio.
• Test sound off, reduced motion, full-page reveal, keyboard navigation, largest text, high contrast, and relevant browsers/devices.
• Store compressed media and DEFLATE JSON/text.
• Exclude masters, private notes, scripts, remote URLs, credentials, and encrypted entries.
• Retain the deterministic build report and Publisher draft with the master.

See Authoring and encoding for the production workflow.

Remaining open questions

• Registration and long-term ownership of the MIME type and format identity.
• Stable migration tooling once the schema leaves beta.
• Content hashes, deduplication, signing, and provenance without DRM.
• Streaming/chunked indexes for very large works.
• Branching, localization, and right-to-left production contracts.
• Typed gradients and richer effects without arbitrary CSS.
• Audio buses, mastering, captions, transcripts, and deterministic loop lifetime.
• Creator-intended crop, orientation, parallax, and responsive art direction.

Source availability and bespoke Readers

The iComic specification and observable behavior may be discussed publicly. The Gremmoire Reader and its authoring/tooling source remain closed.

For a bespoke Reader or authoring workflow adapted to another site, contact [email protected]. A recipient of a bespoke source copy may host, adapt, modify, and use that delivered copy. This does not make the Gremmoire Reader or general toolchain open source.