iComic authoring and encoding

This note describes the production workflow for provisional iComic draft 0.4.1. It is a working profile, not a claim that one codec or preset is best for every project. It also does not make the Gremmoire Reader or its tooling an open-source project.

What is working now

Reader Publisher’s iComic template produces an actual .icomic archive whose canonical root is comic.json. The export carries:

• included page records in binder order, or one long continuous canvas;
• exact frame geometry, stacking, page ratio and bounded looping animations;
• optional Office / Eye / Shadow reader atmosphere for continuous documents;
• page summaries and explicit accessible panel order;
• staged images and video with placement, fit, opacity, blend, effect, and reveal timing;
• bounded step poses for moving artwork, with static fallback destinations;
• illustrated-page captions with their frames, reveal steps and relative reading order;
• ambient or step-triggered local audio cues;
• accessible descriptions for image/video content;
• optional cover and first-page opening artwork with a separate opening reveal;
• Reader-wide context and extended appendix entries;
• required/optional capabilities; and
• exact packaged byte sizes for every exported media variant.

The export runs through the Reader’s own 0.4.1 manifest validator before download. It remains a local, unpublished delivery package. Saving a Publisher draft and exporting .icomic are separate actions.

Publisher can also open a local .icomic through the actual Reader archive loader. It reconstructs pages and media placements from declared local fallbacks. A multi-variant import deliberately stages only each asset’s fallback and warns the author, because a delivery archive does not replace layered masters.

Choose One continuous document in Page appearance for a long-scroll work. Set its height as a multiple of its width. Keep one published canvas; its imported aspect ratio and independent frame coordinates remain intact. Office / Eye / Shadow changes the surrounding reader as it scrolls. It is a native preset, and its movement respects reader settings.

Use the page’s Captions controls for dialogue over artwork. These retain imported text panels independently of the editorial Markdown document. For soft-edged foreground material, select the bounded Feather effect; Focus shows the complete original artwork.

Design goal

The intended production system covers the complete path: inspect masters, make content-aware delivery recommendations, build the manifest, validate the work, package it reproducibly, and report what happened. Uploading occurs only after an explicit publish action; export itself never posts a work.

Encoding remains outside an ordinary Reader request or edge-worker response. It is long-running production work and should stay separate from playback.

Masters and deliverables

Keep source images, layered projects, editing timelines, WavPack or PCM audio masters, H.266/VVC or mezzanine video, and private production notes outside the .icomic archive.

The package contains only the local delivery assets the work needs:

WavPack and H.266/VVC can be authoring inputs, not current browser-delivery promises. Reader Publisher blocks WavPack from iComic export until it has a deterministic delivery conversion instead of preserving an unplayable cue.

Content-aware decisions

A newer codec is not automatically the correct codec. Recommendations should consider the source, target devices, and desired result, with author override:

• dimensions, bit depth, alpha, color profile, grain, line density, gradients, texture, and flat-color repetition for images;
• sample rate, channels, loudness, silence, transients, ambience, speech, and music for audio;
• frame size/rate, duration, alpha, motion, grain, cuts, and text for video; and
• browser/OS coverage, offline use, startup cost, quality, and package size.

Useful preset families include line-art, painted-page, lossless-art, voice, ambience, music, short-motion, high-motion, and web-balanced. Every preset should record its version and resolved settings.

0.4.1 asset contract

The optional assets catalog contains up to 10,000 logical assets and up to four ordered variants per asset. Each asset declares a unique ID, media kind, local fallback, ordered variants, and optional delivery profile. Every variant declares a local source and MIME type, plus optional codec and exact byte size.

The contract requires:

• kind is image, audio, or video;
• fallback appears in the variant list;
• delivery.selection, when supplied, is first-supported;
• MIME, codec, extension, role, and actual media agree;
• declared bytes, when present, exactly matches the archive entry;
• no source belongs to two logical assets or conflicting roles; and
• a holder with asset retains src equal to the declared fallback.

Reader Publisher beta creates one publisher-source variant per distinct asset. Byte-identical staged media of the same type and role shares one exported asset, while placements retain separate identities and presentation. This is a valid minimal ladder. A future encoder should emit more variants only when they add real compatibility or efficiency.

Authoring model

Treat every page as four connected records:

1. Readable core — summary, panel descriptions or text, and captions.
2. Visual composition — frame, fit, stacking, opacity, blend, and bounded effect.
3. Interaction — discrete reveal step, transition, and duration.
4. Media cues — page-entry or explicit step audio/video behavior.

The manifest’s readingOrder is independent of z. Arrange it as the page is meant to be understood, then control visual stacking separately. Meaning cannot depend on animation, compositing, sound, hover, or one codec.

Context entries are work-wide in the 0.4.1 iComic contract. Publisher may let an author create one while focused on a page, but export consolidates it into the Reader-wide appendix. Exact linked terms remain optional.

Deterministic production pipeline

1. Ingest — fingerprint masters without modifying them.
2. Inspect — collect technical metadata and content signals.
3. Plan — resolve target matrix, variants, fallback, dimensions, and quality.
4. Encode — use pinned tools and record complete settings.
5. Compare — generate review material; never promote an output only because it is smaller.
6. Select — record automated choices and author overrides.
7. Author — write IDs, summaries, reading order, capabilities, context, cues, and fallbacks.
8. Validate — verify accessibility, signatures, roles, sizes, limits, and capabilities.
9. Package — store comic.json first, share repeated media, store compressed media in first-use order, and DEFLATE small supporting text within ZIP limits.
10. Report — record hashes, sizes, settings, warnings, inventory, and validation.
11. Publish — upload only after separate deliberate confirmation.

The pipeline should fail before packaging or upload when an asset is missing, a signature/type/role conflicts, a declared byte size differs, a fallback bridge is invalid, an accessibility requirement is unmet, a required capability is unknown, or a safety limit is exceeded.

Report and reproducibility

A retained build report should include:

• tool, encoder, and preset versions;
• input fingerprints without embedding private masters;
• complete resolved encoding settings;
• output hash, MIME, codec, dimensions/duration, and byte size;
• rejected candidates and reasons;
• author overrides;
• capability and accessible-fallback review;
• manifest/archive validation and package hash; and
• upload result only when publishing was explicitly requested.

Given the same masters, configuration, and tools, the packager should make equivalent choices and produce a byte-stable archive wherever encoders permit.

Preflight checklist

• Confirm every included binder item is meant to become a page.
• Write a concise page summary and meaningful image/video descriptions.
• Check panel reading order separately from visual layer order.
• Test entry and step cues with autoplay denied and sound muted.
• Preview reduced motion, high contrast, largest text, panel mode, and page mode.
• Verify all files are local and all declared byte sizes are exact.
• Keep the editable Publisher draft, original .icomic, and masters together.
• Run the current Reader validator before making the file available.
• Use the separate explicit publish step only after reviewing the export.

Remaining production work

• content-aware multi-variant encoding and comparison UI;
• reproducible encoder reports and asset hashes;
• transcript/caption authoring tied directly to audio cues;
• lossless multi-variant re-import instead of fallback reconstruction;
• migration tooling for future schemas;
• representative device/browser performance profiles; and
• a separately reviewed upload destination and release workflow.

Source availability and bespoke work

The iComic specification and observable behavior may be discussed publicly. The Gremmoire Reader and its authoring/tooling source remain closed because they are designed around ValentineDesigns’ publishing process.

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

Layered movement study

Start with separate raster layers: a quiet background, the character, and foreground material with real alpha. Place a narrative image description on the character and a summary on the page; mark redundant background/foreground images decorative. Move near material farther than the distant background, keep the face and dialogue readable, and check every static destination.

Use Publisher’s Move between reading steps controls to set duration, easing, and ordered poses. Positions use percentage points of the page; scale is shown as a percentage in the editor. Add at most 32 poses per layer and 8 moving layers per page. First pose matches reveal. Changes to the reveal shift all poses. An opening-artwork offset must shift all pose steps without overflow.

Verify Next during movement, a caption-only step, Back, Replay, Pause, hidden app/resume, Focus/exit, Motion off, Reduce motion and Page mode. Essential meaning must remain in still artwork and text. Preview deliberately snaps; use Reader to assess playback. Build the local Gremmy fixture with scripts/build-gremmy-study.py; it uses fixed ZIP metadata and verifies exact asset bytes in the generated manifest. Runtime package validation remains the Reader loader’s responsibility.