oim_flutter library

@license Copyright (c) 2026 Xue Studios LLC SPDX-License-Identifier: Apache-2.0

Classes

GeoShapeClipper
GeoShapePainter
InfiniteLayerConfig
Configuration of an infinite moving background or parallax layer.
InfiniteLayerPlan
Render and layout plan for an infinite layer.
InfiniteParallaxTrack
An animated horizontal track that loops child pieces infinitely.
LottieSlot
Renders embedded vector Lottie animations for slots with type: "lottie".
OimExtractionResult
OimFilter
A parsed CSS filter chain: a Gaussian blur sigma and one color matrix (Flutter's 4x5 layout, offsets in the 0-255 scale).
OimImageFillWidget
Widget that displays an image with crop, flip, and shape clipping according to OIM canonical specification (contract 1.15.0 & 1.17.0).
OimPlayer
Interactive native Flutter widget to render OIM files.
OimPublicKey
A public key the SDK trusts. Mirrors PlayerKey in @oim-media/player-oim.
PathDrawing
PolygonDrawing
ShapeDrawing

Enums

OimSecurityStatus
What the SDK can say about a file, from strongest to weakest claim. Same vocabulary as SecurityStatus in @oim-media/player-oim, plus unknownKey: the player asks the server for a key it does not carry, the SDK never phones home, so an unknown key_version is reported, not guessed at.
ReeditPermission

Constants

clockSkew → const Duration
A device clock a few days off must not switch valid works off.
dynamicColorRoles → const List<String>
filterPresetCss → const Map<String, String>
Same table and order as mediaFilterCss in @oim-media/core (media-filters.ts): preset, blur, brightness, contrast, saturation, hue-rotate. Neutral values produce no CSS, so a slot with no adjustments pays for no filter at all.
geoShapes → const Map<String, ShapeDrawing>
Geometry of the 24 catalogue shapes in the editor's viewBox 0 0 100 100. Copied directly from packages/core/src/geoShapes.ts to guarantee exact parity.
imageHashAlg → const String
The seal scheme the backend writes in image_hash_alg: SHA-256 of the IDAT payloads.
maxCanonicalNumber → const int
Largest magnitude a signed number may have (2^53 - 1): every JSON parser reads it exactly.
maxDecompressedMetadataBytes → const int
oimDefaultLanguage → const String
Language used when the caller does not set one, as in the web player (1.26.0).
oimEmbeddedKeys → const List<OimPublicKey>
Same key set as EMBEDDED_KEYS in packages/player-oim/src/render/keys.ts.
pngSignature → const List<int>

Functions

blendModeOf(dynamic name) → BlendMode?
CSS mix-blend-mode names to Flutter blend modes. normal and unknown names return null.
buildShapePath({ShapeDrawing? drawing, String? svgPath, required Size size, Rect viewBox = const Rect.fromLTWH(0, 0, 100, 100)}) → Path
Builds a Path scaled to size from drawing or svgPath.
childrenByGroup(List? slots) → Map<String, List<String>>
Which slots go inside which group. Matches @oim-media/core childrenByGroup.
composeMatrices(List<double> a, List<double> b) → List<double>
Applies a first and then b.
computeInfiniteLayerPlan(InfiniteLayerConfig cfg, double pieceWidthPx, [double? canvasWidthPx, double canvasScale = 1]) → InfiniteLayerPlan
Computes the exact infinite parallax plan for a moving layer.
decodeAndDecompressJSON(String base64Str, {int maxBytes = maxDecompressedMetadataBytes}) → dynamic
Decodes base64 string and decompresses zlib/raw-deflate metadata into parsed JSON.
decodeDataUri(String? uri) → Uint8List?
Decodes an embedded base64 data URL (data:image/...;base64,...), memoised.
decompressAndParseBytes(Uint8List bytes, {int maxBytes = maxDecompressedMetadataBytes}) → dynamic
Decompresses raw/deflate bytes and parses as JSON.
embeddedKey(String kid, [List<OimPublicKey> keys = oimEmbeddedKeys]) → OimPublicKey?
extractOIM(Uint8List pngBytes) → OimExtractionResult
Extracts OIM metadata JSON and IDAT hash from raw PNG bytes.
hasEffectsStack(Map<String, dynamic> style) → bool
Web: a non-empty style.effects replaces the legacy shadow, layer blur and grain fields.
hasNumberOutOfRange(dynamic value) → bool
Whether value carries, at any depth, a number with no canonical form. Beyond 2^53 - 1 parsers disagree on the value they read, so such a file's signature is invalid (BINARY_SPEC 5.1 rule 3).
isGroup(dynamic slot) → bool
Is this slot a group?
isKnownGeoShape(dynamic geoShape) → bool
isRefused(OimSecurityStatus status) → bool
Altered files are refused outright: neither their image nor their layers are shown.
isValidDynamicColorRole(dynamic role) → bool
keyExpiredAt(OimPublicKey key, DateTime now) → bool
Whether this SDK no longer trusts key, judged by the device clock.
layerEffects(Widget child, Map<String, dynamic> style, OimPalette? palette, {required bool isText, double unit = 1}) → Widget
style.effects as a CSS filter chain on the whole layer (web ImageEngine, unified effects stack), applied in file order: blur blurs, and on non-text layers drop-shadow and glow cast the layer's own silhouette (CSS drop-shadow()), not its box. On text layers those two are text shadows (textEffectShadows) and are skipped here.
mediaFilterCss(Map<String, dynamic> style) → String?
The CSS filter chain a slot's style asks for, or null when everything is neutral.
oimLanguages(Map<String, dynamic> metadata) → List<String>
The languages of a file's texts, lower-case and sorted (the web player's languages).
parseBorderRadius(dynamic rawRadius, double containerWidth, double containerHeight) → BorderRadius
Parses CSS border-radius (e.g. "10px", "10px 25px 50px 0px") into BorderRadius.
parseCssColor(dynamic rawColor) → Color?
Parses CSS-style hex colors (#RGB, #RRGGBB, #RRGGBBAA, transparent) into Flutter Color.
parseCssFilter(String? css) → OimFilter?
Parses the chain mediaFilterCss writes. Unknown functions are ignored.
parseInfiniteParallax(Map<String, dynamic> slot, Map<String, dynamic> style, {Map<String, dynamic>? parentSceneLoop}) → InfiniteLayerConfig?
Parses a layer's own infinite parallax. Like the web, a group's sceneLoop moves nothing by itself (it only makes the group clip); parentSceneLoop is accepted and ignored.
parseSvgPath(String d) → Path
Parses an SVG path data string (d) into a Flutter Path.
permissionOf(Map<String, dynamic> metadata) → ReeditPermission
Who may re-edit a file. An unknown value falls back to ReeditPermission.authorOnly, never to public: corrupt or tampered data must not loosen a permission. Mirrors permissionOf and normalizeLegacyKeys in @oim-media/core.
resolveColor(dynamic role, dynamic fallback, OimPalette? palette) → Color?
Resolves a color given a semantic role, fallback raw value, and active palette.
resolveContent(Object? content, String lang) → String
A layer's content in lang. Mirrors resolveContent in @oim-media/player-oim so both players show the same text.
resolveCssUnit(dynamic rawVal, double containerWidth, double containerHeight) → double?
Resolves CSS units (e.g. "62.5cqw", "10.0cqh", "24px", 24) to logical pixels given container dimensions.
resolvePalette(Map<String, dynamic> metadata, {String? requested, bool? prefersDark}) → OimPalette?
Resolves the document's active palette from its metadata.
serializeCanonical(Map<String, dynamic> metadata) → Uint8List
The same rules as serializeCanonical in @oim-media/core (canonical.ts): root exclusion, numeric normalization, key ordering by Unicode code point, compact output, non-ASCII emitted raw, UTF-8.
serializeLegacyCanonical(Map<String, dynamic> metadata) → Uint8List
Files published before creator_user_id was excluded were signed keeping it at the root. Mirrors the legacy fallback in the player: only the three transport keys are dropped, keys are sorted, numbers are left as they came.
shadowOf(Map<String, dynamic> style, {double unit = 1}) → BoxShadow?
The slot's drop shadow. The player uses CSS drop-shadow, whose blur radius is twice the Gaussian sigma, which is what Flutter's blurRadius means too. unit turns design px into canvas px: the web's shadow lives in the scaled stage.
shapeDrawing(dynamic geoShape) → ShapeDrawing?
Returns the ShapeDrawing for geoShape, or null if rectangle or unknown.
signatureIsWithinKeyWindow(OimPublicKey key, String? signedAt) → bool
A file with no signed_at cannot be judged: it predates signed dates.
slotParent(dynamic slot) → String?
A slot's parent group id, as the editor writes it in style.groupId.
slotShownIn(Map raw, String lang) → bool
A layer with languages (other than ["*"]) shows only in those languages.
textEffectShadows(Map<String, dynamic> style, OimPalette? palette, {double unit = 1}) → List<Shadow>
style.effects on a text layer, as the web paints it (ImageEngine, unified effects stack): drop-shadow is one text-shadow and glow two (blur radius*0.4, then radius). blur is in layerEffects; texture is not drawn yet.
verifyMetadataSignature(Map<String, dynamic> metadata, {List<OimPublicKey> keys = oimEmbeddedKeys}) → bool?
Whether the ECDSA signature in metadata is valid over its canonical bytes. Returns null when the key is not one this SDK carries.
verifyOim(OimExtractionResult result, {DateTime? now, List<OimPublicKey> keys = oimEmbeddedKeys}) → OimSecurityStatus
The single place that decides a file's security status. Mirrors securityVerdict in the player: the signature covers image_hash, so once it is valid the seal can be trusted, and what is checked here is that the image shipped in the file is the one that was sealed.

Typedefs

OimPalette = Map<String, Color>
Resolved colors for a palette: map of role -> Color.