Animation Packs

Visual Pack Documentation

Visual Packs (also called Animation Packs) are self-contained interactive modules that embed inside Papyrus articles. They run in sandboxed iframes and communicate with the host article via the postMessage API.

About Papyrus

Papyrus is an interactive research articles platform built by SynaptixLabs. It transforms static academic and technical content into living, explorable experiences — complete with embedded AI assistants, dynamic visualizations, and community engagement tools.

Rich Articles — MDX-powered content with interactive components, code blocks, and embedded media.

AI-Powered — Ask questions about any article and get context-aware answers from an integrated AI assistant.

Community-Driven — Reactions, comments, bookmarks, and feature request voting keep readers engaged.

What Are Visual Packs?

Self-Contained

Each pack is a ZIP containing HTML, CSS, JS, and assets. No external dependencies required.

Sandboxed

Runs in an iframe with security isolation. Cannot access the host page or user data.

Cue-Driven

Responds to article scroll events and user interactions via a simple message protocol.

ZIP Structure

A Visual Pack is uploaded as a ZIP file with the following structure:

directory
my-animation-pack/
├── manifest.json       # Pack metadata & cue definitions
├── index.html          # Entry point (loaded in iframe)
├── snapshot.svg         # Static fallback for print mode
├── styles.css           # Optional styles
├── script.js            # Optional separate JS
└── assets/              # Optional images, fonts, etc.
    └── texture.png
Important: The manifest.json and index.html files are required. The snapshot is optional but strongly recommended for print mode support.

manifest.json Schema

The manifest describes your pack and declares which cues it responds to:

json
{
  "name": "particle-sim",
  "version": "1.0.0",
  "title": "Particle Simulation",
  "description": "Interactive particle physics demo",
  "entry": "index.html",
  "snapshot": "snapshot.svg",
  "dimensions": {
    "width": 800,
    "height": 400
  },
  "cues": ["start", "pause", "reset"],
  "author": "SynaptixLabs"
}
FieldTypeRequiredDescription
namestringYesUnique pack identifier (kebab-case)
versionstringYesSemantic version (e.g. 1.0.0)
titlestringNoHuman-readable display name
descriptionstringNoBrief description of the pack
entrystringYesEntry HTML file (usually index.html)
snapshotstringNoStatic SVG/PNG for print mode
dimensionsobjectNoPreferred width and height in pixels
cuesstring[]NoList of cue names this pack handles
authorstringNoAuthor name or organization

postMessage API

Visual Packs communicate with the Papyrus article viewer using the browser's postMessage API. The host sends messages to the iframe, and the pack can reply:

Messages from Host → Pack

typePayloadWhen
cue{ name: string }Triggered by <Cue> MDX component on scroll/visibility
print—Article entered print mode (?print=true)
theme{ mode: "light" | "dark" }User toggled theme

Messages from Pack → Host

typePurpose
readySignals the host that the pack finished loading and is interactive
resizeRequests a height change: { height: number }

Example Implementation

javascript
// Listen for cues from the host article
window.addEventListener('message', (event) => {
  const { type, name } = event.data

  if (type === 'cue') {
    switch (name) {
      case 'start':
        startAnimation()
        break
      case 'pause':
        pauseAnimation()
        break
      case 'reset':
        resetState()
        break
    }
  }

  if (type === 'print') {
    // Render a static snapshot for print mode
    renderSnapshot()
  }
})

// Signal the host that the pack is ready
window.parent.postMessage({ type: 'ready' }, '*')

Embedding in Articles

Once uploaded via the admin dashboard, Visual Packs are embedded in articles using MDX components:

mdx
<!-- Embed the visual pack -->
<Visual id="particle-sim" height={400} />

<!-- Trigger the "start" cue when visible -->
<Cue target="particle-sim" when="visible" name="start" />

<!-- Trigger "highlight" cue on button click -->
<Cue target="particle-sim" when="click" name="highlight" />

<Visual> Props

  • id — Pack name (matches manifest)
  • height — Iframe height in pixels
  • version — Optional version pin

<Cue> Props

  • target — Visual Pack id to send to
  • when — Trigger: visible, click, scroll
  • name — Cue name sent to the pack

Creating a Pack

  1. 1
    Create your files

    Build your animation with HTML/CSS/JS. Keep it self-contained — all assets must be bundled in the ZIP.

  2. 2
    Add manifest.json

    Define your pack name, version, entry point, and the cues it responds to.

  3. 3
    Add a snapshot

    Create an SVG or PNG that represents the static view for print mode. Place it alongside your manifest.

  4. 4
    ZIP and upload

    Compress all files into a ZIP. Upload via the Visual Packs section in the admin dashboard.

  5. 5
    Embed in your article

    Use <Visual id="your-pack" /> in your MDX content to embed it.

Example Pack

Starter Animation Pack

A minimal example with manifest.json, index.html, snapshot.svg, and a README. Use it as a template for your own packs.

Download Example

Notes

  • •Visual Packs are created and developed outside the Papyrus platform using your own tools and editor. Papyrus only hosts and embeds them.
  • •Packs run inside sandboxed iframes. They have no access to cookies, localStorage, or the parent page DOM.
  • •For best performance, keep your pack size under 5 MB. Optimize images and minify JavaScript when possible.
  • •The pack versioning system lets you update packs without breaking existing articles that pin a specific version.
  • •Need help? Contact us at support@synaptixlabs.ai