OIM Architecture: Overview

This document explains how the OIM ecosystem works at a high level, detailing the layer separation philosophy and how web players process information securely and efficiently.

1. The 3-Layer Separation Model

Both OIM (Object Interactive Media - for images) and OVM (Object Video Media - for video) rely on a fundamental paradigm of strict separation between the baked pixels, a symbolic separator, and the declarative interactive slots that stay live:

Layer −1 · Baked

The pixels of the PNG (or the video frames for OVM). It holds whatever the author chooses to fix in the image in the editor ("Fix in image"), of any layer type: backgrounds, photography, shapes, and also filters and masks if the author bakes them. It may contain baked typography if the author fixed text in the image. Any ordinary image viewer shows it. The signature seals it through an immutable SHA-256 hash (image_hash).

Layer 0 · Separator

Symbolic only: it stores nothing. It is the line between what became pixels and what stays live.

Layer +1 · Dynamic

The slots stored in the zTXt chunk OIM_Data: text in every language, buttons, zones, animations, states, and the filters and masks the author left live. The player composes them on top of the baked image. This layer is embedded directly inside the container itself, allowing:

• A single image to contain multiple instant translations.
• Full accessibility for screen readers and SEO crawlers (real DOM nodes in Shadow DOM).
• Dynamic theming via Container Query Width (cqw) units and semantic Dynamic Colors tokens.

Filters and masks are not a layer of their own: each one is either baked (−1) or dynamic (+1), and the author decides per layer. A project option can bake every visible layer for a complete thumbnail, at the cost of the text appearing twice (in the pixels and drawn by the player).

2. Web Players (Web Components)

At the heart of the visualization are our web players, built as framework-agnostic Custom Elements (<oim-player> and <ovm-player>).

Rendering Lifecycle

1. Extraction: The player loads the file, reads the baked image (Layer −1), and extracts the Dynamic Layer (+1) metadata in milliseconds.
2. Validation: It strictly verifies that the metadata conforms to our schemas, preventing corruption or malicious injections.
3. Mounting: The native image or video is rendered underneath, while the text and interactive triggers are rendered as raw HTML overlaid on top.

Performance

For OVM (Video), the architecture lets the browser handle native video buffering, while the web player only manages the temporal interpolation of the Dynamic Layer, ensuring a smooth 60 FPS experience without overloading the main thread.

3. Security Model

Security is critical in interactive media systems. We have implemented multiple guardrails to ensure OIM/OVM files are safe to consume in any environment:

1. Shadow DOM Isolation: The player's styles and markup are encapsulated. Your site's CSS will not break the player, and the player's styles will not leak out.
2. XSS Hardening: All dynamic textual content injected onto the screen is strictly escaped as plain text (textContent). Raw HTML from the Dynamic Layer is never evaluated.
3. Zod Validation: Every metadata payload is validated against a strict schema before execution, rejecting unrecognized properties, excessively long strings, or malformed structures.