iComic format — provisional draft 0.4.1

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.1"
}

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 schemas 0.4.1 and 0.4.0 under the same strict media, cue, accessibility, byte and canonical-root rules;
• 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.1 adds authored layer poses and explicitly decorative image layers. Draft 0.4.0 introduced fail-closed capability negotiation, explicit page reading order and summaries, cover metadata, byte declarations and bounded compositing. Legacy drafts remain readable but do not retroactively gain guarantees for fields they never declared.

Minimum 0.4.1 manifest

{
  "format": "valentine.interactive-comic",
  "schemaVersion": "0.4.1",
  "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 and 0.4.1 every narrative 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 schemas 0.4.0 and 0.4.1, 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.1 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.

Optional presentation.layout: "continuous" requires exactly one long page and normalizes to width fit, Page mode and zero gap. Declare continuous-scroll in optional capabilities for a readable fallback in older readers. Its native scroll position drives navigation and personal-note anchors. Page/reveal, panel-focus and Auto controls give way to document scrolling.

Optional presentation.atmosphere: "opi-shadow" also declares reader-atmosphere and requires continuous layout. This closed preset progressively changes the Office surroundings, moving Eye apparitions, shadow veil and final blackness. Controls retain contrast. Motion off, Reduce motion, Pause and hidden-tab suspension govern its animations. No package-supplied CSS, HTML or script is accepted.

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.1, 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. iComics with up to 256 MiB of referenced encoded media prepare before display; larger books use a bounded, demand-first LRU and may warm 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.
• Put comic.json first and use Store for it. This avoids repeated inflation and keeps repetitive text within the 100:1 ZIP-ratio ceiling. Small supporting text files may use DEFLATE within the same ceiling.
• Share repeated media through one logical asset. Keep each panel’s placement, accessibility text, reveal and playback settings on the panel.
• 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.1 stores the manifest and media, deflates small supporting text, and writes media in first-use order. Export compares actual file bytes before merging duplicate media of the same type and role. Its current beta uses one declared delivery source per distinct asset; 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.1 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.1 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 comic.json; DEFLATE supporting text within the archive-ratio ceiling.
• 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.

Authored foreground movement — 0.4.1

Declare layer-motion in required or optional capabilities when a panel has motion. Use optional when the base artwork and readable text still explain the page in a reader that ignores movement. A reader must not run scripts, CSS strings, external paths, sensor requests or an independent narrative clock.

{
  "id": "near-shadow",
  "type": "image",
  "src": "assets/shadow.webp",
  "alt": "",
  "decorative": true,
  "z": 30,
  "reveal": { "atStep": 0, "transition": "none" },
  "motion": {
    "durationMs": 1400,
    "easing": "ease-in-out",
    "poses": [
      { "atStep": 0, "x": -8, "y": 10, "scale": 1.1, "rotation": 0 },
      { "atStep": 1, "x": 12, "y": -7, "scale": 1.16, "rotation": 3 }
    ]
  }
}

Motion is for image/GIF/video panels, with at most 8 moving layers per page and 4,096 poses per work. Every panel, including decorative layers, still appears exactly once in readingOrder. Decorative images may have empty alt; a narrative illustration and page summary must retain essential scene detail. Do not classify dialogue, actionable cues or meaningful standalone art as merely decorative. The fields require schema 0.4.1; an older schema declaration must not smuggle in new behavior.

The latest pose at or before the reading step is the scene’s destination. Motion-only steps extend page progression. Adjacent forward steps interpolate from the displayed pose; a caption-only step leaves an unfinished movement running. Back, jumps, restoration and Reveal All snap to the exact destination. Page mode shows the final composition. Motion off and Reduce motion show the current step’s pose immediately. None of these operations changes reading order, reveals essential text early or requires sound, tilt or permission.

The Reader’s Tools offer Pause movement and Replay movement separately from Auto-read. Replay uses the preceding authored pose even after a later caption. Hiding the document pauses elapsed movement; returning resumes it. Leaving a page or work cancels its animation. Focus temporarily contains the original full panel and restores its pose on exit. Preset loops act on inner media so their translation/scale cannot replace authored layer transforms; animation.amount now controls their strength, with 0 stationary.

The bounded feather effect masks the outer layer edges, avoiding rectangular cutoffs when transparent foreground art moves or rotates. It uses a local radial alpha mask; no imported CSS or external mask is accepted.

Publisher keeps imported captions as bounded text/frame/reveal records and provides Page captions controls for writing, adding, removing and retiming them. They are emitted even when the page has artwork; editorial Markdown stays separate from these on-page captions.

Publisher exposes poses beside reveal controls and preserves them through local import/export. Its preview shows snapped poses. Changing the reveal step shifts all poses, including the first-page opening-artwork offset on export; overflow is rejected rather than collapsing steps. Publisher also retains exact rectangular frames, rotation/radius, stacking, page ratios, bounded looping animations and continuous presentation. Alternate media variants still reconstruct from their declared fallback; an exported archive does not replace layered masters.

The included Gremmy — After Hours fixture is a non-canon three-page study, with separate hallway, character and near shadow layers. Its local raster artwork, summaries, text and alpha provide a small reproducible test of movement, static reading and safe packaging.