@serimo/player 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -25,7 +25,7 @@ Build from the root so workspace dependencies such as `@serimo/core` are built b
25
25
  npx playwright install chromium
26
26
  ```
27
27
 
28
- Pack Player with `npm pack --workspace=@serimo/player --ignore-scripts --pack-destination <existing-absolute-directory>` after building, using an existing directory outside the checkout. Install `serimo-player-0.1.0.tgz` alongside Core's archive and React. Player has external peers `@serimo/core@0.1.0` and `react@19.3.1`; the browser host supplies `react-dom@19.3.1`, and Core requires `gsap@3.15.0`. Required UI JavaScript and styles are compiled at build time, so the consumer needs neither a private UI package nor a Tailwind compiler. See the [CLI preview setup](../cli/README.md#preview-a-source-composition) for all three archives and the [migration guide](../cli/README.md#migrate-private-runtime-consumers) for older projects.
28
+ Pack Player with `npm pack --workspace=@serimo/player --ignore-scripts --pack-destination <existing-absolute-directory>` after building, using an existing directory outside the checkout. Install `serimo-player-0.2.0.tgz` alongside the matching Core archive and React. Player has external peers `@serimo/core@0.2.0` and `react@19.3.1`. The browser host supplies `react-dom@19.3.1`, and Core requires `gsap@3.15.0`. The build compiles the required UI JavaScript and styles into the Player archive. [CLI preview setup](../cli/README.md#preview-a-source-composition) · [Migration guide for older projects](../cli/README.md#migrate-private-runtime-consumers)
29
29
 
30
30
  ## Usage
31
31
 
@@ -99,7 +99,7 @@ To embed a composition **without** a browser global, render `CompositionPlayer`
99
99
 
100
100
  ## API Reference
101
101
 
102
- Player exports two React components and their supporting types from the `@serimo/player` entry point. `@serimo/player/styles.css` is a separate precompiled CSS export; the JS entry does not import it automatically. Existing hosts may retain their shared stylesheet setup. Examples below reuse `composition` and `components` from [Usage](#usage).
102
+ Player exports React components and their supporting types from the `@serimo/player` entry point. `@serimo/player/styles.css` is a separate precompiled CSS export; the JS entry does not import it automatically. Existing hosts may retain their shared stylesheet setup. Examples below reuse `composition` and `components` from [Usage](#usage).
103
103
 
104
104
  ### `@serimo/player`
105
105
 
@@ -149,6 +149,41 @@ function RenderScene() {
149
149
 
150
150
  While mounted, exposes `window.__serimoRenderer` with the `PlayerHandle` methods below. Only **one** bridge may own a page; mounting another throws, and unmount removes the global. The bridge follows the active Player instance. It is an internal Renderer contract, **not** a published browser SDK.
151
151
 
152
+ #### `ImageAsset`
153
+
154
+ Renders a prepared image inside a composition adapter and registers its timeline with Core. Acquire the descriptor with the [CLI portable-image workflow](../cli/README.md#freeze-portable-images); raw remote URLs are not accepted as this component's input.
155
+
156
+ ```tsx
157
+ import { ImageAsset, type PlayerComponent } from "@serimo/player"
158
+ import heroArt from "serimo:images/hero-art"
159
+
160
+ const imageComponent: PlayerComponent = ({ clip, registry }) => (
161
+ <ImageAsset
162
+ asset={heroArt}
163
+ clipId={clip.id}
164
+ registry={registry}
165
+ alt='Hero illustration'
166
+ style={{ width: 320, height: 180 }}
167
+ />
168
+ )
169
+ ```
170
+
171
+ The CLI import requires the wildcard TypeScript declaration in its recipe. Other trusted hosts must supply equivalent validated `FrozenImageAsset` descriptors and same-origin prepared resources; Player does not download originals or run the freeze pipeline.
172
+
173
+ | Prop | Type | Description |
174
+ | -------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------- |
175
+ | `asset` | `FrozenImageAsset` | Required prepared static raster, raster sequence or validated SVG tree. |
176
+ | `clipId` | `string` | Required ID of the composition clip. |
177
+ | `registry` | `Pick<ReturnType<typeof createTimelineRegistry>, "register">` | Required registry supplied to the adapter. |
178
+ | `alt` | `string` | Required accessible description; use `""` for decoration. |
179
+ | `className`, `style` | `string`, `CSSProperties` | Optional presentation on the image root. |
180
+
181
+ Exported types are `ImageAssetProps`, `FrozenImageAsset`, `FrozenImageFrame` and `FrozenSvgNode`. Descriptors have `schemaVersion: 1`, intrinsic `width`/`height`, `kind: "static" | "sequence" | "svg"`, total `plays` and a `frames` array. Each raster frame has `src`, byte length and optional rational `timing: { numerator, denominator }` in seconds. SVG descriptors contain an inert `tree` and prepared-data byte estimate. Treat descriptors as immutable preparation results; changing one remounts its resources.
182
+
183
+ Readiness waits for all image resources before registering the clip. Same-origin prepared PNGs are byte/dimension checked and decoded once per shared URL, with reference-counted leases in the document. Decode is sequential; stale work cannot register or revive an unmounted clip, and final release closes bitmaps. Each raster instance owns its canvas; SVG instances own isolated roots, IDs and paused SMIL/CSS effects. Cleanup unregisters the timeline and releases reservations/resources.
184
+
185
+ Animation uses clip-local composition time and the composition FPS, including reverse and random seek. Source raster frame durations remain exact rational values, with exclusive frame ends; finite plays hold the final raster frame and infinite plays repeat. SVG time-based SMIL and supported CSS keyframes are sampled synchronously, without a wall-clock playback loop. Pause therefore holds the same state during preview and capture. The [CLI recipe](../cli/README.md#freeze-portable-images) specifies supported formats, the safe SVG subset and strict input limits. Player enforces descriptor boundaries and a separate 512 MiB per-document managed-data budget for prepared bytes, decoded surfaces, canvas/tree data and CSS effects. This is not a native process RSS cap or a guarantee of identical pixels across environments.
186
+
152
187
  #### `PlayerComponent`
153
188
 
154
189
  Adapter function that maps a validated clip to a locally imported React element with a registered Core timeline.
@@ -1 +1 @@
1
- {"version":3,"file":"composition-player.d.ts","sourceRoot":"","sources":["../src/composition-player.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAuB,MAAM,0BAA0B,CAAA;AAC/E,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAA;AACvE,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,GAAG,EAMT,MAAM,OAAO,CAAA;AAEd,OAAO,EAAE,KAAK,YAAY,EAAuB,MAAM,qBAAqB,CAAA;AAG5E,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,UAAU,CAAA;IAChB,QAAQ,EAAE,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAA;IACnD,eAAe,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,sBAAsB,KAAK,YAAY,CAAA;AAE/E,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,OAAO,CAAA;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;IAC3C,GAAG,CAAC,EAAE,GAAG,CAAC,YAAY,CAAC,CAAA;CACxB;AAED,wBAAgB,iBAAiB,CAAC,EAChC,WAAW,EACX,UAAU,EACV,GAAG,EACJ,EAAE,sBAAsB,+BA4GxB"}
1
+ {"version":3,"file":"composition-player.d.ts","sourceRoot":"","sources":["../src/composition-player.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAuB,MAAM,0BAA0B,CAAA;AAC/E,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAA;AACvE,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,GAAG,EAMT,MAAM,OAAO,CAAA;AAGd,OAAO,EAAE,KAAK,YAAY,EAAuB,MAAM,qBAAqB,CAAA;AAG5E,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,UAAU,CAAA;IAChB,QAAQ,EAAE,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAA;IACnD,eAAe,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,sBAAsB,KAAK,YAAY,CAAA;AAE/E,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,OAAO,CAAA;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;IAC3C,GAAG,CAAC,EAAE,GAAG,CAAC,YAAY,CAAC,CAAA;CACxB;AAED,wBAAgB,iBAAiB,CAAC,EAChC,WAAW,EACX,UAAU,EACV,GAAG,EACJ,EAAE,sBAAsB,+BA4GxB"}
@@ -0,0 +1,2 @@
1
+ export declare const CompositionFps: import("react").Context<number | null>;
2
+ //# sourceMappingURL=composition-timing.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"composition-timing.d.ts","sourceRoot":"","sources":["../src/composition-timing.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,cAAc,wCAAqC,CAAA"}
@@ -0,0 +1,24 @@
1
+ export interface FrozenImageFrame {
2
+ src: string;
3
+ bytes: number;
4
+ timing?: {
5
+ numerator: number;
6
+ denominator: number;
7
+ };
8
+ }
9
+ export interface FrozenSvgNode {
10
+ tag: string;
11
+ attributes: Readonly<Record<string, string>>;
12
+ children: readonly (FrozenSvgNode | string)[];
13
+ }
14
+ export interface FrozenImageAsset {
15
+ schemaVersion: 1;
16
+ kind: 'static' | 'sequence' | 'svg';
17
+ width: number;
18
+ height: number;
19
+ plays: number | 'infinite';
20
+ frames: readonly FrozenImageFrame[];
21
+ tree?: FrozenSvgNode;
22
+ bytes?: number;
23
+ }
24
+ //# sourceMappingURL=image-asset-types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"image-asset-types.d.ts","sourceRoot":"","sources":["../src/image-asset-types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAA;CACpD;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAC5C,QAAQ,EAAE,SAAS,CAAC,aAAa,GAAG,MAAM,CAAC,EAAE,CAAA;CAC9C;AAED,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,CAAC,CAAA;IAChB,IAAI,EAAE,QAAQ,GAAG,UAAU,GAAG,KAAK,CAAA;IACnC,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,GAAG,UAAU,CAAA;IAC1B,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAA;IACnC,IAAI,CAAC,EAAE,aAAa,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf"}
@@ -0,0 +1,13 @@
1
+ import type { createTimelineRegistry } from '@serimo/core/timeline-registry';
2
+ import { type CSSProperties } from 'react';
3
+ import type { FrozenImageAsset } from './image-asset-types.js';
4
+ export interface ImageAssetProps {
5
+ asset: FrozenImageAsset;
6
+ clipId: string;
7
+ registry: Pick<ReturnType<typeof createTimelineRegistry>, 'register'>;
8
+ alt: string;
9
+ className?: string;
10
+ style?: CSSProperties;
11
+ }
12
+ export declare function ImageAsset(props: ImageAssetProps): import("react").JSX.Element;
13
+ //# sourceMappingURL=image-asset.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"image-asset.d.ts","sourceRoot":"","sources":["../src/image-asset.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAA;AAC5E,OAAO,EACL,KAAK,aAAa,EAKnB,MAAM,OAAO,CAAA;AAGd,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAK9D,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,gBAAgB,CAAA;IACvB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,IAAI,CAAC,UAAU,CAAC,OAAO,sBAAsB,CAAC,EAAE,UAAU,CAAC,CAAA;IACrE,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,aAAa,CAAA;CACtB;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,+BAoBhD"}
@@ -0,0 +1,7 @@
1
+ import type { FrozenImageFrame } from './image-asset-types.js';
2
+ export declare function reserveImageData(bytes: number, document?: Document): () => void;
3
+ export declare function acquireImageFrame(frame: FrozenImageFrame, width: number, height: number, document?: Document): {
4
+ ready: Promise<ImageBitmap>;
5
+ release(): void;
6
+ };
7
+ //# sourceMappingURL=image-resources.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"image-resources.d.ts","sourceRoot":"","sources":["../src/image-resources.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAiC9D,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,QAAQ,GAAE,QAA8B,GACvC,MAAM,IAAI,CAgBZ;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,gBAAgB,EACvB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,QAAQ,GAAE,QAA8B,GACvC;IAAE,KAAK,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAAC,OAAO,IAAI,IAAI,CAAA;CAAE,CA0KlD"}
@@ -0,0 +1,3 @@
1
+ import type { FrozenImageFrame } from './image-asset-types.js';
2
+ export declare function createImageSequence(frames: readonly FrozenImageFrame[], plays: number | 'infinite', fps: number): (localFrame: number) => number;
3
+ //# sourceMappingURL=image-sequence.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"image-sequence.d.ts","sourceRoot":"","sources":["../src/image-sequence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAO9D,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,gBAAgB,EAAE,EACnC,KAAK,EAAE,MAAM,GAAG,UAAU,EAC1B,GAAG,EAAE,MAAM,GACV,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAoDhC"}
@@ -0,0 +1,5 @@
1
+ export declare function prepareSvgAnimations(root: SVGSVGElement): {
2
+ seek(seconds: number): void;
3
+ dispose(): void;
4
+ };
5
+ //# sourceMappingURL=image-svg-animation.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"image-svg-animation.d.ts","sourceRoot":"","sources":["../src/image-svg-animation.ts"],"names":[],"mappings":"AAAA,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,aAAa;IAuDpD,IAAI,UAAU,MAAM;IA8BpB,OAAO;EAIV"}
@@ -0,0 +1,10 @@
1
+ import type { FrozenSvgNode } from './image-asset-types.js';
2
+ import type { ImageAssetProps } from './image-asset.js';
3
+ export declare function inspectSvgTree(tree: FrozenSvgNode, bytes: number, width: number, height: number): {
4
+ styles: string[];
5
+ ids: Map<string, FrozenSvgNode>;
6
+ nodes: number;
7
+ masks: number;
8
+ };
9
+ export declare function SvgImageAsset({ asset, clipId, registry, alt, className, style }: ImageAssetProps): import("react").JSX.Element;
10
+ //# sourceMappingURL=image-svg.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"image-svg.d.ts","sourceRoot":"","sources":["../src/image-svg.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAuCvD,wBAAgB,cAAc,CAC5B,IAAI,EAAE,aAAa,EACnB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM;;;;;EA6If;AA+ED,wBAAgB,aAAa,CAAC,EAC5B,KAAK,EACL,MAAM,EACN,QAAQ,EACR,GAAG,EACH,SAAS,EACT,KAAK,EACN,EAAE,eAAe,+BA0HjB"}
package/dist/index.d.ts CHANGED
@@ -2,4 +2,7 @@ export { CompositionPlayer } from './composition-player.js';
2
2
  export type { CompositionPlayerProps, PlayerComponent, PlayerComponentOptions } from './composition-player.js';
3
3
  export type { PlayerHandle } from './player-session.js';
4
4
  export { CompositionPlayerBridge } from './renderer-bridge.js';
5
+ export { ImageAsset } from './image-asset.js';
6
+ export type { ImageAssetProps } from './image-asset.js';
7
+ export type { FrozenImageAsset, FrozenImageFrame, FrozenSvgNode } from './image-asset-types.js';
5
8
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAC3D,YAAY,EACV,sBAAsB,EACtB,eAAe,EACf,sBAAsB,EACvB,MAAM,yBAAyB,CAAA;AAChC,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAA"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAC3D,YAAY,EACV,sBAAsB,EACtB,eAAe,EACf,sBAAsB,EACvB,MAAM,yBAAyB,CAAA;AAChC,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAA;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,YAAY,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AACvD,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACd,MAAM,wBAAwB,CAAA"}